"

 COPYRIGHT (c) 1993 by Claus Gittinger

              All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

"{ Package: 'stx:libbasic' }"

Object subclass:#GenericException

	instanceVariableNames:'signal parameter messageText suspendedContext raiseContext

		handlerContext rejected originator proceedable'

	classVariableNames:'StrictRaising'

	poolDictionaries:''

	category:'Kernel-Exceptions'

!

GenericException class instanceVariableNames:'NotifierString'

"

 No other class instance variables are inherited by this class.

"

!

!GenericException class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1993 by Claus Gittinger

              All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

!

documentation

"

    Note:

        The instance based Signal framework is being replaced by

        class based exceptions.

        I.e. what used to be instances of Signal/QuerySignal is beeing

        rewritten into subclasses of Exception/Error/Query and Warning.

        Although the functionality is basically unchanged, the new

        class based exceptions are easier to instanciate (no need for

        creation in a classes initialize method), easier to use (no real

        need for SIgnal-constant accessors) and allow for easier parameter

        passing (not only a single parameter, but allows for individual

        exception subclasses to add additional state).

    GenericException and its subclasses implement the same protocol as Signal.

    So class based exceptions may be implemented as subclasses of GenericException.

    Normally all exceptions are subclasses of Exception. Exceptions, that are

    used for debugging or that are signalling errors in the exception system itself

    are direct subclasses of GenericException.

    Instances of Exception are passed to a Signal handling block as argument.

    The handler block may perform various actions by sending corresponding messages

    to the exception object. The following actions are possible:

        reject          - don't handle this signal;

                          another handler will be searched for,

                          upper in the calling hierarchy

        proceed         - return from the Signal>>raise, with nil as value

        proceedWith:val - same, but return val from Signal>>raise

        return          - return from the Signal>>handle:do:, with nil as value

        returnWith:val  - same, but return val from Signal>>handle:do:

                          (this is also the handlers default,

                           if it falls through; taking the handlerBlocks value

                           as return value)

        restart         - restart the Signal>>handle:do:, after repairing

    Via the Exception object, the handler can also query the state of execution:

    where the Signal was raised, where the handler is, the signal which caused

    the error and the messageText passed when the signal was raised. Also, an optional

    parameter can be passed - the use is signal specific.

    [instance variables:]

        signal           <Signal>     the signal which caused the exception

        parameter        <Object>     a parameter (if any) which was passed when raising

                                      the signal (only if raised with #raiseWith:aParameter)

        messageText      <String>     an messageText

                                      (usually the signals own messageText, but sometimes

                                       changed explicitely in #raiseWith:errorString:)

        suspendedContext <Context>    the context in which the raise occured

        handlerContext   <Context>    the context of the handler (if any)

    In case of an unhandled signal raise, Exceptions EmergenyHandler will be evaluated.

    The default emergeny handler will enter the debugger.

    For applications, which do not want Debuggers to come up, other handlers are

    possible.

    For example, to get the typical C++ behavior, use:

        Exception emergencyHandler:[:ex | Smalltalk exitWithCoreDump]

    Raising:

        two different raising messages are to be used,

        depending on whether the exception is proceedable or not

        For some stupid reason, someone decided that the raise-code checks if

        the raising messages matches to what the signal thinks is its proceedability.

        (i.e. not only do both the sender and the signal itself specify proceedability,

         this is checked by the raise code and a warning is generated if there is a mismatch)

        This used to be even worse (WrongProceedabilityError), but we relaxed this to

        a message sent to stderr.

        That means, that PROCEEDABLE signals must be raised with:

            raiseRequest

        and NON-PROCEEDABLE signals must be raised with:

            raise

        If you dont know/care as a raiser, you can use

            raiseSignal

        which checks for proceedability and sends the appropriate message.

        (sigh)

    all of the 3 messages above come in various flavours:

        raiseXXX                - do not pass any additional parameter;

                                  default messageText

        raiseXXXWith:           - pass additional parameter;

                                  default messageText

        raiseXXXErrorString:    - do not pass any additional parameter;

                                  given errorString

        raiseXXXWith:errorString:

                                - pass any additional parameter;

                                  AND given errorString

    [see also:]

        Signal  SignalSet QuerySignal

        Context Block

        Object DebugView

        (``Exception handling and signals'': programming/exceptions.html)

    [author:]

        Claus Gittinger

"

!

examples

"

    Examples on Exception-raising & handling are found in the doc/coding

    section (CodingExamples).

    The emergencyHandler stuff is very useful, to prevent endUser applications

    from entering the debugger. See the examples in NoHandlerError.

"

! !

!GenericException class methodsFor:'initialization'!

initialize

    NotifierString := 'unknown exception'.

    StrictRaising := false.     "set to true to check weather a signal may be raised proceedable"

    "Modified: / 04-08-1999 / 09:06:26 / stefan"

    "Modified: / 17-11-2010 / 17:53:13 / cg"

! !

!GenericException class methodsFor:'instance creation'!

new

    "{ Pragma: +inlineNew }"

    ^ self basicNew setSignal:self.

    "Modified: / 23.7.1999 / 13:53:12 / stefan"

    "Created: / 24.7.1999 / 13:21:13 / stefan"

!

newException

    "{ Pragma: +inlineNew }"

    ^ self basicNew setSignal:self.

    "Created: / 23.7.1999 / 13:45:49 / stefan"

    "Modified: / 24.7.1999 / 13:21:25 / stefan"

! !

!GenericException class methodsFor:'Compatibility-Dolphin'!

signal:messageText

    "raise a signal proceedable or nonproceedable (whichever is right).

     The argument is used as messageText."

    <context: #return>

    ^ (self newException

                suspendedContext:thisContext sender

                errorString:messageText)

        raiseSignal.

    "Modified: / 10-08-2010 / 09:41:56 / cg"

! !

!GenericException class methodsFor:'Compatibility-Squeak'!

signal

    "raise a signal proceedable or nonproceedable (whichever is right).

     The argument is used as messageText."

    ^ self raiseSignal

    "Created: / 20-11-2006 / 14:00:09 / cg"

! !

!GenericException class methodsFor:'accessing'!

errorString

    "#errorString is deprecated, use description instead"

    <resource:#obsolete>

    ^ self description

!

handlerBlock

    "Compatibility with Signal. Class based exeptions do not have a handler

     block. They redefine the #action method instead"

    ^ nil

    "Created: / 23.7.1999 / 14:43:18 / stefan"

    "Modified: / 24.7.1999 / 20:52:10 / stefan"

!

notifierString:aString

    NotifierString := aString

! !

!GenericException class methodsFor:'backward compatibility'!

abortingEmergencyHandler

    "WARNING: this method belongs to NoHandlerError, and has been moved there"

    <resource: #obsolete>

    ^ NoHandlerError abortingEmergencyHandler

!

dumpingEmergencyHandler

    "WARNING: this method belongs to NoHandlerError, and has been moved there"

    <resource: #obsolete>

    ^ NoHandlerError dumpingEmergencyHandler

!

emergencyHandler

    "WARNING: this method belongs to NoHandlerError, and has been moved there"

    <resource: #obsolete>

    ^ NoHandlerError emergencyHandler.

!

emergencyHandler:aOneArgBlock

    "WARNING: this method belongs to NoHandlerError, and has been moved there"

    <resource: #obsolete>

    ^ NoHandlerError emergencyHandler:aOneArgBlock

!

mailingEmergencyHandler

    "WARNING: this method belongs to NoHandlerError, and has been moved there"

    <resource: #obsolete>

    ^ NoHandlerError mailingEmergencyHandler

!

notifyingEmergencyHandler

    "WARNING: this method belongs to NoHandlerError, and has been moved there"

    <resource: #obsolete>

    ^ NoHandlerError notifyingEmergencyHandler

!

notifyingEmergencyHandlerForUserProcesses

    "WARNING: this method belongs to NoHandlerError, and has been moved there"

    <resource: #obsolete>

    ^ NoHandlerError notifyingEmergencyHandlerForUserProcesses

! !

!GenericException class methodsFor:'child signal creation'!

newSignal

    "create a new signal, using the receiver as a prototype and

     setting the parent of the new signal to the receiver."

    ^ self newSignalMayProceed:self mayProceed

    "Created: / 23.7.1999 / 20:13:23 / stefan"

!

newSignalMayProceed:mayProceedBoolean

    "create a new signal, using the receiver as a prototype and

     setting the parent of the new signal to the receiver."

    |sig|

    self isQuerySignal ifTrue:[

        sig := QuerySignal basicNew.

        mayProceedBoolean ifFalse:[

            'Exception [warning]: nonProceedable queries do not make sense' infoPrintCR.

        ].

    ] ifFalse:[

        sig := Signal basicNew.

    ].

    ^ sig

        mayProceed:mayProceedBoolean;

        notifierString:NotifierString;

        parent:self

    "Created: / 23.7.1999 / 20:12:43 / stefan"

! !

!GenericException class methodsFor:'converting'!

, anExceptionHandler

    "return a SignalSet with myself and anExceptionHandler"

    ^ SignalSet with:self with:anExceptionHandler

! !

!GenericException class methodsFor:'misc ui support'!

iconInBrowserSymbol

    <resource: #programImage>

    ^ #exceptionClassBrowserIcon

! !

!GenericException class methodsFor:'printing'!

description

    "return the notifier string.

     If the notifier string starts with space, prepend

     the parents notifier string.

     Subclasses may redefine this method."

    |parent|

    NotifierString isNil ifTrue:[

        ^ self nameForDescription asString

    ].

    (NotifierString startsWith:Character space) ifTrue:[

        (parent := self parent) notNil ifTrue:[

            ^ parent description, NotifierString

        ].

    ].

    ^ NotifierString

    "

     Object errorSignal description

    "

    "Created: / 23-07-1999 / 14:22:25 / stefan"

    "Modified: / 10-02-2011 / 12:29:07 / cg"

!

nameForDescription

    "if no notifierString is specified, this is used.

     Can be redfined to hide the namespace in subclasses"

    ^ self name

    "Created: / 10-02-2011 / 12:28:51 / cg"

! !

!GenericException class methodsFor:'queries'!

accepts:aSignal

    "return true, if the receiver accepts the argument, aSignal.

     (i.e. the receiver is aSignal or a parent of it). False otherwise."

    |s|

    self == aSignal ifTrue:[^ true].

    aSignal isQuerySignal ifTrue:[^ false].

    s := aSignal parent.

    [s notNil] whileTrue:[

        self == s ifTrue:[^ true].

        s := s parent

    ].

    ^ false

    "Created: / 23.7.1999 / 14:00:47 / stefan"

!

exception:anException isHandledIn:aContext

    "return true, if there is a handler for anException in the

     contextChain starting with aContext."

    ^ (self handlerContextForException:anException in:aContext) notNil

!

exceptionHandlerFor:anException in:aContext

    "answer the exceptionHandler-block for anException from aContext."

    |sel|

    sel := aContext selector.

    (sel == #'handle:from:do:'

     or:[sel == #'handle:do:']) ifTrue:[

        ^ aContext receiver

    ].

    ^ nil

!

handlerContextForException:anException in:aContext

    "return a handlerContext for anException in the

     contextChain starting with aContext. 

     Returns nil ,if there is no handler."

    |theContext ex1 con1|

    theContext := aContext findExceptional.

    [theContext notNil] whileTrue:[

        theContext isRaiseContext ifTrue:[ 

            "skip all the contexts between the raise and the sender of #handle:do"

            ex1 := theContext receiver.              "exception, that has been raised"

            con1 := ex1 handlerContext.              "the context of the #handle:do:"

            con1 notNil ifTrue:[

                "handlerContext may be nil, if this is a default action"

                theContext := con1.

            ].

            ex1 := con1 := nil.

        ] ifFalse:[ |r|

            ((r := theContext receiver) notNil

             and:[(r handlerForSignal:anException context:theContext originator:nil) notNil]

            ) ifTrue:[

                "found a handler context"

                ^ theContext

            ].

        ].

        theContext notNil ifTrue:[

            theContext := theContext findSpecialHandle:true raise:true.

        ].

    ].

    ^ nil

!

handlerForSignal:signal context:theContext originator:originator

    "answer the handler block for the signal from originator.

     The block is retrieved from aContext.

     Answer nil if the signal is not handled"

    (theContext selector ~~ #'handle:from:do:'

     or:[(theContext argAt:2) == originator]) ifTrue:[

        (self == signal or:[self accepts:signal]) ifTrue:[

            ^ (theContext argAt:1) ? [nil]

        ]

    ].

    ^ nil

    "Created: / 25.7.1999 / 19:52:58 / stefan"

!

handlerProtectedBlock:doBlock inContext:context

    "set the handlerProtectedBlock in context"

    |sel|

    sel := context selector.

    sel == #handle:do: ifTrue:[

        context argAt:2 put:doBlock.

    ] ifFalse:[sel == #handle:from:do: ifTrue:[

        context argAt:3 put:doBlock.

    ]].

!