Class FbExceptionBuilder

java.lang.Object
org.firebirdsql.gds.ng.FbExceptionBuilder

@NullMarked public final class FbExceptionBuilder extends Object
Builder for exceptions received from Firebird.

This class is not thread-safe.

Author:
Mark Rotteveel
  • Constructor Details

    • FbExceptionBuilder

      public FbExceptionBuilder()
  • Method Details

    • exception

      public FbExceptionBuilder exception(int errorCode)
      The (next) exception is an exception.

      This method and related methods can be called multiple times. This builder might produce a chained exception, but could also merge exceptions depending on the error code and other rules internal to this builder.

      Parameters:
      errorCode - Firebird error code
      Returns:
      this FbExceptionBuilder
      See Also:
    • forException

      public static FbExceptionBuilder forException(int errorCode)
      Creates an exception builder with the specified error code.

      Equivalent to calling: new FbExceptionBuilder().exception(errorCode);

      Parameters:
      errorCode - Firebird error code
      Returns:
      FbExceptionBuilder initialized with the specified error code
    • toException

      public static SQLException toException(int errorCode)
      Creates a SQLException (or subclass) with the specified error code.

      Equivalent to calling FbExceptionBuilder.forException(errorCode).toSQLException().

      Parameters:
      errorCode - Firebird error code
      Returns:
      exception with message, vendor code and SQLSTATE derived from errorCode
      Since:
      6
    • forTimeoutException

      public static FbExceptionBuilder forTimeoutException(int errorCode)
      Creates an exception builder for timeout exceptions with the specified error code.

      Equivalent to calling: new FbExceptionBuilder().timeoutException(errorCode);

      Parameters:
      errorCode - Firebird error code
      Returns:
      FbExceptionBuilder initialized with the specified error code
      Since:
      6
    • toTimeoutException

      public static SQLException toTimeoutException(int errorCode)
      Creates a SQLException (or subclass) for timeout exceptions with the specified error code.

      Equivalent to calling FbExceptionBuilder.forTimeoutException(errorCode).toSQLException().

      Parameters:
      errorCode - Firebird error code
      Returns:
      exception with message, vendor code and SQLSTATE derived from errorCode
      Since:
      6
    • forNonTransientException

      public static FbExceptionBuilder forNonTransientException(int errorCode)
      Creates an exception builder for non-transient exceptions with the specified error code.

      Equivalent to calling: new FbExceptionBuilder().nonTransientException(errorCode);

      Parameters:
      errorCode - Firebird error code
      Returns:
      FbExceptionBuilder initialized with the specified error code
      Since:
      6
    • toNonTransientException

      public static SQLException toNonTransientException(int errorCode)
      Creates a SQLException (or subclass) for non-transient exceptions with the specified error code.

      Equivalent to calling FbExceptionBuilder.forNonTransientException(errorCode).toSQLException().

      Parameters:
      errorCode - Firebird error code
      Returns:
      exception with message, vendor code and SQLSTATE derived from errorCode
      Since:
      6
    • forNonTransientConnectionException

      public static FbExceptionBuilder forNonTransientConnectionException(int errorCode)
      Creates an exception builder for non-transient connection exceptions with the specified error code.

      Equivalent to calling: new FbExceptionBuilder().nonTransientConnectionException(errorCode);

      Parameters:
      errorCode - Firebird error code
      Returns:
      FbExceptionBuilder initialized with the specified error code
      Since:
      6
    • toNonTransientConnectionException

      public static SQLException toNonTransientConnectionException(int errorCode)
      Creates a SQLException (or subclass) for non-transient connection exceptions with the specified error code.

      Equivalent to calling FbExceptionBuilder.forNonTransientConnectionException(errorCode).toSQLException().

      Parameters:
      errorCode - Firebird error code
      Returns:
      exception with message, vendor code and SQLSTATE derived from errorCode
      Since:
      6
    • forTransientException

      public static FbExceptionBuilder forTransientException(int errorCode)
      Creates an exception builder for transient exceptions with the specified error code.
      Parameters:
      errorCode - Firebird error code
      Returns:
      FbExceptionBuilder initialized with the specified error code
      Since:
      6
    • toTransientException

      public static SQLException toTransientException(int errorCode)
      Creates a SQLException (or subclass) for transient exceptions with the specified error code.

      Equivalent to calling FbExceptionBuilder.forTransientException(errorCode).toSQLException().

      Parameters:
      errorCode - Firebird error code
      Returns:
      exception with message, vendor code and SQLSTATE derived from errorCode
      Since:
      6
    • forWarning

      public static FbExceptionBuilder forWarning(int errorCode)
      Creates an exception builder for a warning with the specified error code.

      Equivalent to calling: new FbExceptionBuilder().warning(errorCode);

      Parameters:
      errorCode - Firebird error code
      Returns:
      FbExceptionBuilder initialized with the specified error code
    • toWarning

      public static SQLWarning toWarning(int errorCode)
      Creates a SQLWarning with the specified error code.

      Equivalent to calling FbExceptionBuilder.forWarning(errorCode).toSQLException(SQLWarning.class).

      Parameters:
      errorCode - Firebird error code
      Returns:
      exception with message, vendor code and SQLSTATE derived from errorCode
      Since:
      6
    • ioWriteError

      public static SQLException ioWriteError(IOException e)
      Creates an I/O write error (ISCConstants.isc_net_write_err).
      Parameters:
      e - exception cause
      Returns:
      SQLException instance
      Since:
      6
    • ioReadError

      public static SQLException ioReadError(IOException e)
      Creates an I/O write error (ISCConstants.isc_net_read_err).
      Parameters:
      e - exception cause
      Returns:
      SQLException instance
      Since:
      6
    • connectionClosed

      public static SQLException connectionClosed()
      Creates a connection closed error (JaybirdErrorCodes.jb_connectionClosed).
      Returns:
      SQLException instance
      Since:
      6
    • warning

      public FbExceptionBuilder warning(int errorCode)
      The (next) exception is a warning.
      Parameters:
      errorCode - Firebird error code
      Returns:
      this FbExceptionBuilder
      See Also:
    • timeoutException

      public FbExceptionBuilder timeoutException(int errorCode)
      Force the next exception to be a SQLTimeoutException.
      Parameters:
      errorCode - Firebird error code
      Returns:
      this FbExceptionBuilder
      See Also:
    • nonTransientException

      public FbExceptionBuilder nonTransientException(int errorCode)
      Force the next exception to be a SQLNonTransientException.
      Parameters:
      errorCode - Firebird error code
      Returns:
      this FbExceptionBuilder
      See Also:
    • nonTransientConnectionException

      public FbExceptionBuilder nonTransientConnectionException(int errorCode)
      Force the next exception to be a SQLNonTransientConnectionException.
      Parameters:
      errorCode - Firebird error code
      Returns:
      this FbExceptionBuilder
      See Also:
    • transientException

      public FbExceptionBuilder transientException(int errorCode)
      Force the next exception to be a SQLTransientException.
      Parameters:
      errorCode - Firebird error code
      Returns:
      this FbExceptionBuilder
      See Also:
    • messageParameter

      public FbExceptionBuilder messageParameter(int parameter)
      Adds an integer message parameter for the exception message.
      Parameters:
      parameter - message parameter
      Returns:
      this FbExceptionBuilder
    • messageParameter

      public FbExceptionBuilder messageParameter(int param1, int param2)
      Adds two integer message parameters for the exception message.
      Parameters:
      param1 - message parameter
      param2 - message parameter
      Returns:
      this FbExceptionBuilder
      Since:
      5
    • messageParameter

      public FbExceptionBuilder messageParameter(@Nullable Object parameter)
      Adds an object message parameter for the exception message (applying String.valueOf(parameter)).
      Parameters:
      parameter - message parameter
      Returns:
      this FbExceptionBuilder
      Since:
      5
    • messageParameter

      public FbExceptionBuilder messageParameter(@Nullable Object param1, @Nullable Object param2)
      Adds two object message parameters for the exception message (applying String.valueOf(parameter)).
      Parameters:
      param1 - message parameter
      param2 - message parameter
      Returns:
      this FbExceptionBuilder
      Since:
      5
    • messageParameter

      public FbExceptionBuilder messageParameter(@Nullable Object... params)
      Adds object message parameters for the exception message (applying String.valueOf(parameter)).
      Parameters:
      params - message parameters
      Returns:
      this FbExceptionBuilder
      Since:
      5
    • sqlState

      public FbExceptionBuilder sqlState(String sqlState)
      Sets the SQL state. Overriding the value derived from the Firebird error code.

      SQL State is usually derived from the errorCode. Use of this method is optional.

      Parameters:
      sqlState - SQL State value
      Returns:
      this FbExceptionBuilder
    • cause

      public FbExceptionBuilder cause(Throwable cause)
      Sets the cause of the current exception.
      Parameters:
      cause - Throwable with the cause
      Returns:
      this FbExceptionBuilder
    • toSQLException

      public SQLException toSQLException()
      Converts the builder to the appropriate SQLException instance (optionally with a chain of additional exceptions).

      When returning exception information from the status vector, it is advisable to use toFlatSQLException() as this applies some heuristics to get more specific error codes and flattens the message into a single exception.

      If isEmpty() returns false, then this will throw an IllegalStateException.

      Returns:
      SQLException object
      See Also:
    • toFlatSQLException

      public SQLException toFlatSQLException()
      Converts the builder to a single SQLException instance with a single exception message.

      This method attempts to assign the most specific error code and SQL state to the returned exception.

      The cause of the returned exception is set to an instance of FBSQLExceptionInfo which contains the separate items obtained from the status vector. These items are chained together using the SQLException chain.

      If isEmpty() returns false, then this will throw an IllegalStateException.

      Returns:
      SQLException object
      See Also:
    • toSQLException

      public <T extends SQLException> T toSQLException(Class<T> type) throws ClassCastException
      Converts the builder to the appropriate SQLException instance (optionally with a chain of additional exceptions) and casts to the specified type T.
      Type Parameters:
      T - Expected exception type
      Parameters:
      type - Class of type T
      Returns:
      SQLException of type T
      Throws:
      ClassCastException - If the first exception created with this builder is not of the specified type
      See Also:
    • toFlatSQLException

      public <T extends SQLException> T toFlatSQLException(Class<T> type) throws ClassCastException
      Converts the builder to the appropriate SQLException instance and casts to the specified type T.
      Type Parameters:
      T - Expected exception type
      Parameters:
      type - Class of type T
      Returns:
      SQLException of type T
      Throws:
      ClassCastException - If the first exception created with this builder is not of the specified type
      See Also:
    • isEmpty

      public boolean isEmpty()
      Returns:
      true if this builder contains exception information, false otherwise
    • toString

      public String toString()
      Overrides:
      toString in class Object