Class StandardException
- All Implemented Interfaces:
Serializable
- Direct Known Subclasses:
InterruptDetectedException
,LongColumnException
,NoSpaceOnPage
This class is abstract to ensure that an implementation only throws a specific exception (e.g. TransactionException) which is a sub-class
A method in an iterface in a protocol under com.ibm.db2j.protocol.Database must only throw a StandardException (if it needs to throw an exception). This indicates that the method can throw an exception and therefore its caller must ensure that any resources it allocates will be cleaned up in the event of an exception in the StandardException hierarchy.
Implementations of methods that throw StandardException can have throws clause that are more specific than StandardException.
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
Dummy exception to catch incorrect use of StandardException.newException(), at compile-time. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate Object[]
private boolean
private SQLException
private int
static final int
static final int
static final int
private int
private String
private String
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
StandardException
(String messageID) private
StandardException
(String sqlState, String text) This constructor is used when we already have the message text.protected
StandardException
(String messageID, Throwable t, Object[] args) -
Method Summary
Modifier and TypeMethodDescriptionstatic StandardException
A special exception to close a session.static StandardException
Unpack the exception, looking for a StandardException, which carries the Derby messageID and arguments.final Object[]
final int
getErrorProperty
(String type) Get the error code for an error given a type.private static String
getErrorProperty
(String messageId, String type) The message stored in the super class Throwable must be set up object creation.final String
Return the message identifier that is used to look up the error message text in the messages.properties file.final SQLException
Get the nextSQLException
that should be put into the parent exception when this instance is converted to anSQLException
.final int
static int
getSeverityFromIdentifier
(String messageID) Get the severity given a message identifier from org.apache.derby.iapi.reference.SQLState.final String
Return the 5 character SQL State.static String
getSQLStateFromIdentifier
(String messageID) Convert a message identifer from org.apache.derby.iapi.reference.SQLState to a SQLState five character string.static StandardException
final boolean
Is this a lock timeout exception.final boolean
Is this a lock timeout or lock deadlock exception.final boolean
Is this a self-deadlock exception caused by a nested transaction being blocked by its parent's locks.private static boolean
Check if the top-level throwable is just a vacuous wrapper that does not carry any useful information except what's returned by theThrowable.getCause()
method.(package private) final void
Mark this exception as one that is thrown by a public API method.static StandardException
newException
(String messageId, Object... args) static StandardException
newException
(String messageID, Object a1, Object a2, Throwable t) Dummy overload which should never be called.static StandardException
newException
(String messageID, Object a1, Throwable t) Dummy overload which should never be called.static StandardException
newException
(String messageId, Throwable t, Object... args) static StandardException
newPreLocalizedException
(String MessageID, Throwable t, String localizedMessage) Creates a new StandardException using message text that has already been localized.static SQLWarning
newWarning
(String messageId, Object... oa) static StandardException
static StandardException
Similar to unexpectedUserException but makes no assumtion about when the execption is being called.final int
report()
Yes, report me.final void
setReport
(int report) Set my report type.final void
setSeverity
(int severity) toString()
Don't print the class name in the toString() method.static StandardException
Methods inherited from class java.lang.Throwable
addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
-
Field Details
-
REPORT_DEFAULT
public static final int REPORT_DEFAULT- See Also:
-
REPORT_NEVER
public static final int REPORT_NEVER- See Also:
-
REPORT_ALWAYS
public static final int REPORT_ALWAYS- See Also:
-
arguments
-
severity
private int severity -
textMessage
-
sqlState
-
report
private transient int report -
isForPublicAPI
private transient boolean isForPublicAPI -
next
-
-
Constructor Details
-
StandardException
-
StandardException
-
StandardException
This constructor is used when we already have the message text.- Parameters:
sqlState
- the sql state of the messagetext
- the text of the message
-
-
Method Details
-
getArguments
-
report
public final int report()Yes, report me. Errors that need this method to return false are in the minority. -
setReport
public final void setReport(int report) Set my report type. -
setSeverity
public final void setSeverity(int severity) -
getSeverity
public final int getSeverity() -
getErrorCode
public final int getErrorCode() -
getSQLState
Return the 5 character SQL State. If you need teh identifier that was used to create the message, then use getMessageId(). getMessageId() will return the string that corresponds to the field in org.apache.derby.iapi.reference.SQLState. -
getNextException
Get the nextSQLException
that should be put into the parent exception when this instance is converted to anSQLException
.- Returns:
- the next exception
-
markAsPublicAPI
final void markAsPublicAPI()Mark this exception as one that is thrown by a public API method. The purpose is to signal that this should be a top-level exception, so that it doesn't get wrapped inside multiple layers of other SQLExceptions or StandardExceptions as it travels up through the code layers.- See Also:
-
getSQLStateFromIdentifier
Convert a message identifer from org.apache.derby.iapi.reference.SQLState to a SQLState five character string.- Parameters:
messageID
- - the sql state id of the message from Derby- Returns:
- String - the 5 character code of the SQLState ID to returned to the user
-
getSeverityFromIdentifier
Get the severity given a message identifier from org.apache.derby.iapi.reference.SQLState. -
normalClose
-
newException
-
newException
-
newException
public static StandardException newException(String messageID, Object a1, Throwable t) throws StandardException.BadMessageArgumentException Dummy overload which should never be called. Only used to detect incorrect usage, at compile time.- Parameters:
messageID
- - the sql state id of the messagea1
- - Message argt
- - Incorrectly placed exception to be nested- Returns:
- nothing - always throws
- Throws:
StandardException.BadMessageArgumentException
- - always (dummy)
-
newException
public static StandardException newException(String messageID, Object a1, Object a2, Throwable t) throws StandardException.BadMessageArgumentException Dummy overload which should never be called. Only used to detect incorrect usage, at compile time.- Parameters:
messageID
- - the sql state id of the messagea1
- - First message arga2
- - Second message argt
- - Incorrectly placed exception to be nested- Returns:
- nothing - always throws
- Throws:
StandardException.BadMessageArgumentException
- - always (dummy)
-
newPreLocalizedException
public static StandardException newPreLocalizedException(String MessageID, Throwable t, String localizedMessage) Creates a new StandardException using message text that has already been localized.- Parameters:
MessageID
- The SQLState and severity are derived from the ID. However the text message is not.t
- The Throwable that caused this exception, null if this exception was not caused by another Throwable.localizedMessage
- The message associated with this exception. It is the caller's responsibility to ensure that this message is properly localized. See org.apache.derby.iapi.tools.i18n.LocalizedResource
-
getArgumentFerry
Unpack the exception, looking for a StandardException, which carries the Derby messageID and arguments.- See Also:
-
isVacuousWrapper
Check if the top-level throwable is just a vacuous wrapper that does not carry any useful information except what's returned by theThrowable.getCause()
method.- Parameters:
t
- the throwable to check- Returns:
true
if the throwable is a vacuous wrapper and the only useful piece of information is the cause, orfalse
otherwise
-
unexpectedUserException
-
plainWrapException
Similar to unexpectedUserException but makes no assumtion about when the execption is being called. The error is wrapped as simply as possible. -
closeException
A special exception to close a session. -
getMessage
The message stored in the super class Throwable must be set up object creation. At this time we cannot get any information about the object itself (ie. this) in order to determine the natural language message. Ie. we need to class of the objec in order to look up its message, but we can't get the class of the exception before calling the super class message.Thus the message stored by Throwable and obtained by the getMessage() of Throwable (ie. super.getMessage() in this class) is the message identifier. The actual text message is stored in this class at the first request.
- Overrides:
getMessage
in classThrowable
-
getMessageId
Return the message identifier that is used to look up the error message text in the messages.properties file. -
getErrorProperty
Get the error code for an error given a type. The value of the property messageId.type will be returned, e.g. deadlock.sqlstate. -
toString
Don't print the class name in the toString() method. -
getErrorProperty
-
interrupt
-
newWarning
-
isLockTimeout
public final boolean isLockTimeout()Is this a lock timeout exception.- Returns:
- true if this exception is a lock timeout.
-
isSelfDeadlock
public final boolean isSelfDeadlock()Is this a self-deadlock exception caused by a nested transaction being blocked by its parent's locks.- Returns:
- true if this exception is a self-deadlock.
-
isLockTimeoutOrDeadlock
public final boolean isLockTimeoutOrDeadlock()Is this a lock timeout or lock deadlock exception.- Returns:
- true if this exception is a lock timeout or lock deadlock.
-