Class StandardException

java.lang.Object
java.lang.Throwable
java.lang.Exception
org.apache.derby.iapi.error.StandardException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
InterruptDetectedException, LongColumnException, NoSpaceOnPage
public class StandardException extends Exception
StandardException is the root of all exceptions that are handled in a standard fashion by the database code, mainly in the language code.

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:

  • 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

      private transient Object[] arguments

    • severity

      private int severity

    • textMessage

      private String textMessage

    • sqlState

      private String sqlState

    • report

      private transient int report

    • isForPublicAPI

      private transient boolean isForPublicAPI

    • next

      private transient SQLException next

  • Constructor Details

    • StandardException

      protected StandardException(String messageID)

    • StandardException

      protected StandardException(String messageID, Throwable t, Object[] args)

    • StandardException

      private StandardException(String sqlState, String text)
      This constructor is used when we already have the message text.
      Parameters:
      sqlState - the sql state of the message
      text - the text of the message

  • Method Details

    • getArguments

      public final Object[] 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

      public final String 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

      public final SQLException getNextException()
      Get the next SQLException that should be put into the parent exception when this instance is converted to an SQLException.
      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

      public static String getSQLStateFromIdentifier(String messageID)
      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

      public static int getSeverityFromIdentifier(String messageID)
      Get the severity given a message identifier from org.apache.derby.iapi.reference.SQLState.

    • normalClose

      public static StandardException normalClose()

    • newException

      public static StandardException newException(String messageId, Object... args)

    • newException

      public static StandardException newException(String messageId, Throwable t, Object... args)

    • 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 message
      a1 - - Message arg
      t - - 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 message
      a1 - - First message arg
      a2 - - Second message arg
      t - - 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

      public static StandardException getArgumentFerry(SQLException se)
      Unpack the exception, looking for a StandardException, which carries the Derby messageID and arguments.
      See Also:

    • isVacuousWrapper

      private static boolean isVacuousWrapper(Throwable t)
      Check if the top-level throwable is just a vacuous wrapper that does not carry any useful information except what's returned by the Throwable.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, or false otherwise

    • unexpectedUserException

      public static StandardException unexpectedUserException(Throwable t)

    • plainWrapException

      public static StandardException plainWrapException(Throwable t)
      Similar to unexpectedUserException but makes no assumtion about when the execption is being called. The error is wrapped as simply as possible.

    • closeException

      public static StandardException closeException()
      A special exception to close a session.

    • getMessage

      public String 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 class Throwable

    • getMessageId

      public final String getMessageId()
      Return the message identifier that is used to look up the error message text in the messages.properties file.

    • getErrorProperty

      public String getErrorProperty(String type)
      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

      public String toString()
      Don't print the class name in the toString() method.
      Overrides:
      toString in class Throwable

    • getErrorProperty

      private static String getErrorProperty(String messageId, String type)

    • interrupt

      public static StandardException interrupt(InterruptedException ie)

    • newWarning

      public static SQLWarning newWarning(String messageId, Object... oa)

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