"

 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 handlerContext

		rejected originator proceedable handlingException'

	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: / 4.8.1999 / 09:06:26 / stefan"

! !

!GenericException class methodsFor:'instance creation'!

signal:aSignal originator:origin

    "create a new instance and set the fields in preparation for a raise.

     - only to be sent from the signal when raising"

    "{ Pragma: +inlineNew }"

    ^ (self basicNew) signal:aSignal originator:origin.

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

!

signal:aSignal parameter:aParameter errorString:aString suspendedContext:sContext originator:origin

    "create a new instance and set the fields in preparation for a raise.

     - only to be sent from the signal when raising"

    "{ Pragma: +inlineNew }"

    ^ (self basicNew)

	signal:aSignal 

	parameter:aParameter 

	errorString:aString 

	suspendedContext:sContext 

	originator:origin.

! !

!GenericException class methodsFor:'Compatibility-ANSI'!

raiseSignal:errorMessage 

    "raise a signal (proceedable or not, whatever the proceedability is).

     The argument, errorMessage is used as messageText."

    <context: #return>

    ^ (self newException 

        suspendedContext:thisContext sender

        errorString:errorMessage) raiseSignal.

    "Modified: / 07-08-2004 / 19:24:00 / stefan"

!

raiseSignal:errorMessage with:aParameter

    "raise a signal (proceedable or not, whatever the proceedability is).

     The argument, errorMessage is used as messageText."

    <context: #return>

    ^ (self newException 

        suspendedContext:thisContext sender

        errorString:errorMessage;

        parameter:aParameter)

            raiseSignal.

    "Modified: / 07-08-2004 / 19:10:40 / stefan"

!

signalWith:messageText

    self raiseErrorString:messageText

! !

!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.

! !

!GenericException class methodsFor:'Signal constants'!

noHandlerError

    ^ NoHandlerError

    "Created: / 4.8.1999 / 08:33:35 / stefan"

!

proceedError

    ^ ProceedError

    "Created: / 4.8.1999 / 08:34:30 / stefan"

!

recursiveExceptionError

    "return the signal used to handle recursive signals in the handlers"

    ^ RecursiveExceptionError

    "Created: / 4.8.1999 / 09:05:06 / stefan"

!

recursiveExceptionSignal

    "return the signal used to handle recursive signals in the handlers.

     This is for backward compatinility. Use recursiveExceptionError"

    ^ RecursiveExceptionError

    "Modified: / 4.8.1999 / 09:05:59 / stefan"

!

wrongProceedabilityError

    ^ WrongProceedabilityError

    "Created: / 4.8.1999 / 08:34:19 / stefan"

! !

!GenericException class methodsFor:'accessing'!

notifierString:aString

    NotifierString := aString

! !

!GenericException class methodsFor:'compatibility-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"

! !

!GenericException class methodsFor:'compatibility-defaults'!

emergencyHandler

    ^ NoHandlerError emergencyHandler.

!

emergencyHandler:aOneArgBlock

    "set the handler used for unhandled exceptions.

     The default (a nil-handler) leads to a debugger to be shown."

    ^ NoHandlerError emergencyHandler:aOneArgBlock.

    "ST-80 behavior of first showing a notifier:

     (I prefer to get right into the debugger, though)

     Exception

	emergencyHandler:

	    [:ex | self errorNotify:ex description ]

    "

    "ST-X behavior of going right into the debugger:

     Exception

	emergencyHandler:nil

    "

    "automatically aborting current operation, on error:

     (may be useful for end-user apps; make certain, 

      you have abortSignal handlers at appropriate places)

     Exception

	emergencyHandler:

	    [:ex | Object abortSignal raise. ex return. ]

    "

    "finally, traditional language system behavior; dump core ;-)

     Exception

	emergencyHandler:

	    [:ex | Smalltalk exitWithCoreDump. ]

    "

    "Modified: 15.1.1997 / 20:49:06 / cg"

! !

!GenericException class methodsFor:'compatibility-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.

    [s notNil] whileTrue:[

	self == s ifTrue:[^ true].

	s := s parent

    ].

    ^ false

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

!

exception:anExceptionHandler isHandledIn:aContext

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

     contextChain starting with aContext."

    |theContext|

    theContext := aContext findExceptional.

    [theContext notNil] whileTrue:[

        theContext isRaiseContext ifTrue:[ |ex1 con1|

            "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:anExceptionHandler context:theContext originator:nil) notNil]

            ) ifTrue:[

                "found a handler context"

                ^ true

            ].

        ].

        theContext notNil ifTrue:[

            theContext := theContext findSpecialHandle:true raise:true.

        ].

    ].

    ^ false

!

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

    "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.

    ]].

!

handlingExceptionInContext:theContext

    "answer the handling exception from aContext."

    |sel|

    sel := theContext selector.

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

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

	^ theContext receiver

    ].

    ^ nil

!

inheritsFrom:anotherSignal

    "return true, if the receiver is a child of anotherSignal

     (i.e. if handling anotherSignal also handles the receiver)

     This is almost the same as accepts, but returns false, if

     the receiver is identical to anotherSignal."

    self == anotherSignal ifTrue:[^ false].

    ^ anotherSignal accepts:self

    "Created: / 23.7.1999 / 13:59:51 / stefan"

!

isExceptionCreator

    "return true, if the receiver can create exceptions,

     this includes #raise, #raiseRequest as well as the behavior of

     an exception handler, such as the #accepts: and #handles: messages"

    ^ true

!

isExceptionHandler

    "return true, if the receiver responds to the exception handler protocol,

     especially to the #accepts: and #handles: messages"

    ^ true

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

!