"

 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' }"

"{ NameSpace: Smalltalk }"

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:

    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:

    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:]

    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:

    Raising:

    all of the 3 messages above come in various flavours:

    [see also:]

    [author:]

"

!

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

    "force strict signal checking in Smalltalk development - nobody cares otherwise"

    StrictRaising := Smalltalk isStandAloneApp not.     "set to true to check whether 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 initialize creator:self.

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

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

!

newException

    "{ Pragma: +inlineNew }"

    ^ self basicNew initialize creator:self.

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

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

! !

!GenericException class methodsFor:'Compatibility-ANSI'!

signal

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

     ANSI compatibility."

    ^ self raiseSignal

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

!

signalWith:messageText

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

     The argument is used as messageText.

     ANSI compatibility."

    <resource: #skipInDebuggersWalkBack>

    self raiseErrorString:messageText

! !

!GenericException class methodsFor:'accessing'!

errorString

    "#errorString is deprecated, use description instead"

    <resource:#obsolete>

    ^ self description

!

handlerBlock

    "Compatibility with Signal. Class based exceptions 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:'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.

    ]].

!

handles:anException

    "return true, if the receiver handles the argument, anException.

     (i.e. the receiver is anExceptions signal or a parent of it)"

    |signal|

    signal := anException creator.