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

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(int param1, int param2)	Adds two integer message parameters for the exception message.
FbExceptionBuilder	messageParameter(java.lang.Object parameter)	Adds an object message parameter for the exception message (applying String.valueOf(parameter)).
FbExceptionBuilder	messageParameter(java.lang.Object... params)	Adds object message parameters for the exception message (applying String.valueOf(parameter)).
FbExceptionBuilder	messageParameter(java.lang.Object param1, java.lang.Object param2)	Adds two object message parameters for the exception message (applying String.valueOf(parameter)).
FbExceptionBuilder	messageParameter(java.lang.String parameter)	Adds a string message parameter for the exception message.
FbExceptionBuilder	messageParameter(java.lang.String param1, java.lang.String param2)	Adds two string message parameters 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	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 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)

transientException

public FbExceptionBuilder transientException(int errorCode)

Force the next exception to be a SQLTransientException.

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(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(java.lang.String parameter)

Adds a string message parameter for the exception message.

Parameters:

parameter - Message parameter

Returns:

this FbExceptionBuilder

messageParameter

public FbExceptionBuilder messageParameter(java.lang.String param1,
                                           java.lang.String param2)

Adds two string message parameters for the exception message.

Parameters:

param1 - message parameter

param2 - message parameter

Returns:

this FbExceptionBuilder

Since:

5

messageParameter

public FbExceptionBuilder messageParameter(java.lang.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(java.lang.Object param1,
                                           java.lang.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(java.lang.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(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