Package org.firebirdsql.gds.ng

## Class FbExceptionBuilder

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

-     public final class FbExceptionBuilder
      extends java.lang.Object

  Builder for exceptions received from Firebird.

  This class is not thread-safe.

  Author:
    Mark Rotteveel

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `FbExceptionBuilder()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `FbExceptionBuilder` | `cause​(java.lang.Throwable cause)` | Sets the cause of the current exception.
    `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` | `forWarning​(int errorCode)` | Creates an exception builder for a warning with the specified error code.
    `boolean` | `isEmpty()` |
    `FbExceptionBuilder` | `messageParameter​(int parameter)` | Adds an integer message parameter for the exception message.
    `FbExceptionBuilder` | `messageParameter​(java.lang.String parameter)` | Adds a string message parameter for the exception message.
    `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​(java.lang.String sqlState)` | Sets the SQL state.
    `FbExceptionBuilder` | `timeoutException​(int errorCode)` | Force the next exception to be a `SQLTimeoutException`.
    `java.sql.SQLException` | `toFlatSQLException()` | Converts the builder to a single SQLException instance with a single exception message.
    `<T extends java.sql.SQLException> T` | `toFlatSQLException​(java.lang.Class<T> type)` | Converts the builder to the appropriate SQLException instance and casts to the specified type T.
    `java.sql.SQLException` | `toSQLException()` | Converts the builder to the appropriate SQLException instance (optionally with a chain of additional exceptions).
    `<T extends java.sql.SQLException> T` | `toSQLException​(java.lang.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.
    `java.lang.String` | `toString()` |
    `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 Detail

    - #### FbExceptionBuilder

          public FbExceptionBuilder()

  - ### Method Detail

    - #### 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` - The 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().error(errorCode);`

      Parameters:
        `errorCode` - The Firebird error code
      Returns:
        FbExceptionBuilder initialized with the specified error code

    - #### 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` - The Firebird error code
      Returns:
        FbExceptionBuilder initialized with the specified error code

    - #### warning

          public FbExceptionBuilder warning​(int errorCode)

      The (next) exception is a warning.
      Parameters:
        `errorCode` - The 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` - The 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` - The 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` - The 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​(java.lang.String parameter)

      Adds a string message parameter for the exception message.
      Parameters:
        `parameter` - Message parameter
      Returns:
        this FbExceptionBuilder

    - #### sqlState

          public FbExceptionBuilder sqlState​(java.lang.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​(java.lang.Throwable cause)

      Sets the cause of the current exception.
      Parameters:
        `cause` - Throwable with the cause
      Returns:
        this FbExceptionBuilder

    - #### toSQLException

          public java.sql.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 java.sql.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 java.sql.SQLException> T toSQLException​(java.lang.Class<T> type)
                                                             throws java.lang.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:
        `java.lang.ClassCastException` - If the first exception created with this builder is not of the specified type
      See Also:
        `toSQLException()`

    - #### toFlatSQLException

          public <T extends java.sql.SQLException> T toFlatSQLException​(java.lang.Class<T> type)
                                                                 throws java.lang.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:
        `java.lang.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 java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`