Module org.firebirdsql.jaybird
Package org.firebirdsql.gds.ng

# 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 Summary

  Constructors
  Constructor
  Description
  `FbExceptionBuilder()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `FbExceptionBuilder`
  `cause(Throwable cause)`
  Sets the cause of the current exception.
  `static SQLException`
  `connectionClosed()`
  Creates a connection closed error (`JaybirdErrorCodes.jb_connectionClosed`).
  `FbExceptionBuilder`
  `exception(int errorCode)`
  The (next) exception is an exception.
  `static FbExceptionBuilder`
  `forException(int errorCode)`
  Creates an exception builder with the specified error code.
  `static FbExceptionBuilder`
  `forNonTransientConnectionException(int errorCode)`
  Creates an exception builder for non-transient connection exceptions with the specified error code.
  `static FbExceptionBuilder`
  `forNonTransientException(int errorCode)`
  Creates an exception builder for non-transient exceptions with the specified error code.
  `static FbExceptionBuilder`
  `forTimeoutException(int errorCode)`
  Creates an exception builder for timeout exceptions with the specified error code.
  `static FbExceptionBuilder`
  `forTransientException(int errorCode)`
  Creates an exception builder for transient exceptions with the specified error code.
  `static FbExceptionBuilder`
  `forWarning(int errorCode)`
  Creates an exception builder for a warning with the specified error code.
  `static SQLException`
  `ioReadError(IOException e)`
  Creates an I/O write error (`ISCConstants.isc_net_read_err`).
  `static SQLException`
  `ioWriteError(IOException e)`
  Creates an I/O write error (`ISCConstants.isc_net_write_err`).
  `boolean`
  `isEmpty()`
  `FbExceptionBuilder`
  `messageParameter(int parameter)`
  Adds an integer message parameter for the exception message.
  `FbExceptionBuilder`
  `messageParameter(int param1, int param2)`
  Adds two integer message parameters for the exception message.
  `FbExceptionBuilder`
  `messageParameter(@Nullable Object parameter)`
  Adds an object message parameter for the exception message (applying `String.valueOf(parameter)`).
  `FbExceptionBuilder`
  `messageParameter(@Nullable Object... params)`
  Adds object message parameters for the exception message (applying `String.valueOf(parameter)`).
  `FbExceptionBuilder`
  `messageParameter(@Nullable Object param1, @Nullable Object param2)`
  Adds two object message parameters for the exception message (applying `String.valueOf(parameter)`).
  `FbExceptionBuilder`
  `nonTransientConnectionException(int errorCode)`
  Force the next exception to be a `SQLNonTransientConnectionException`.
  `FbExceptionBuilder`
  `nonTransientException(int errorCode)`
  Force the next exception to be a `SQLNonTransientException`.
  `FbExceptionBuilder`
  `sqlState(String sqlState)`
  Sets the SQL state.
  `FbExceptionBuilder`
  `timeoutException(int errorCode)`
  Force the next exception to be a `SQLTimeoutException`.
  `static SQLException`
  `toException(int errorCode)`
  Creates a `SQLException` (or subclass) with the specified error code.
  `SQLException`
  `toFlatSQLException()`
  Converts the builder to a single SQLException instance with a single exception message.
  `<T extends SQLException>
  T`
  `toFlatSQLException(Class<T> type)`
  Converts the builder to the appropriate SQLException instance and casts to the specified type T.
  `static SQLException`
  `toNonTransientConnectionException(int errorCode)`
  Creates a `SQLException` (or subclass) for non-transient connection exceptions with the specified error code.
  `static SQLException`
  `toNonTransientException(int errorCode)`
  Creates a `SQLException` (or subclass) for non-transient exceptions with the specified error code.
  `SQLException`
  `toSQLException()`
  Converts the builder to the appropriate SQLException instance (optionally with a chain of additional exceptions).
  `<T extends SQLException>
  T`
  `toSQLException(Class<T> type)`
  Converts the builder to the appropriate SQLException instance (optionally with a chain of additional exceptions) and casts to the specified type T.
  `String`
  `toString()`
  `static SQLException`
  `toTimeoutException(int errorCode)`
  Creates a `SQLException` (or subclass) for timeout exceptions with the specified error code.
  `static SQLException`
  `toTransientException(int errorCode)`
  Creates a `SQLException` (or subclass) for transient exceptions with the specified error code.
  `static SQLWarning`
  `toWarning(int errorCode)`
  Creates a `SQLWarning` with the specified error code.
  `FbExceptionBuilder`
  `transientException(int errorCode)`
  Force the next exception to be a `SQLTransientException`.
  `FbExceptionBuilder`
  `warning(int errorCode)`
  The (next) exception is a warning.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## 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:
      - `warning(int)`

  - ### 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:
      - `exception(int)`

  - ### timeoutException

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

  - ### nonTransientException

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

  - ### nonTransientConnectionException

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

  - ### transientException

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

  - ### 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()`

  - ### 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:
      - `FBSQLExceptionInfo`

  - ### 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:
      - `toSQLException()`

  - ### 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:
      - `toFlatSQLException()`

  - ### isEmpty

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

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`