PIRL.Database

## Class Database_Exception

- java.lang.Object
- - java.lang.Throwable
  - - java.lang.Exception
    - - PIRL.Database.Database_Exception

All Implemented Interfaces:
  Serializable

    public class Database_Exception
    extends Exception

The excpetion thrown from the PIRL.Database package.

See Also:
  Serialized Form

### Field Summary

Fields
`static String` `DISCONNECTED_STATE` The two character "class" prefix of a five character SQLState value defined by the X/Open and SQL Access Group (Open Group) SQL CAE specification (1992) that indicates a failure to connect to the database.
`static String` `ID` Class identification name with source code version and date.

### Constructor Summary

Constructors
Constructor and Description
`Database_Exception()` Constructs a Database_Exception.
`Database_Exception(String message)` Constructs a Database_Exception with a message.
`Database_Exception(String message, Throwable cause)` Constructs a Database_Exception with a message and a cause.
`Database_Exception(Throwable cause)` Constructs a Database_Exception having a cause.

### Method Summary

Methods
`boolean` `Disconnected()` Tests if this Database_Exception was caused by an SQLException indicating loss of database connection.
`static String` `exception_String(Exception exception)` Generates a message String for an Exception.
`static String` `exception_String(Throwable throwable)` Generates a message String for a Throwable.
`static SQLException` `masked_SQLException(SQLException SQL_exception)` Copy an SQLException with any passwords masked out.
`static String` `masked_String(String string)` Masks out words that should be hidden in a String.

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

`addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString`

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

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

### Field Detail

#### ID

    public static final String ID

Class identification name with source code version and date.

See Also:
  Constant Field Values

#### DISCONNECTED_STATE

    public static final String DISCONNECTED_STATE

The two character "class" prefix of a five character SQLState value defined by the X/Open and SQL Access Group (Open Group) SQL CAE specification (1992) that indicates a failure to connect to the database.

See Also:
  Constant Field Values

### Constructor Detail

#### Database_Exception

    public Database_Exception(String message,
                      Throwable cause)

Constructs a Database_Exception with a message and a cause.

The ID of this class will preceed the message. If a none-null message is specified it will be preceed with a new-line character. If a non-null cause is specified its message will be appended to the specified message after a new-line character.

Appending the cause's message to the specified message is done for backwards compatibility with the exceptions that did not support a chained cause. This can result in applications that expect to chain the cause messages themselves to get unexpected redundant messages.

N.B.: Once a cause is set it can not be changed. Therefore, though it is allowed to set the cause to null, the Database_Exception will not do this to avoid the situation of not being able to replace a null cause with a valid cause. Use the `Throwable.initCause(Throwable)` method to provide a cause after the Configuration_Exception has been constructed without one.

Parameters:
  `message` - The exception's message String (may be null).
  `cause` - The exception's Throwable cause (may be null). If the cause is null, no cause is set in the exception object.

#### Database_Exception

    public Database_Exception(Throwable cause)

Constructs a Database_Exception having a cause.

The exception will have the ID of this class as its message.

Parameters:
  `cause` - The exception's Throwable cause (may be null).

#### Database_Exception

    public Database_Exception(String message)

Constructs a Database_Exception with a message.

Parameters:
  `message` - The exception's message String (may be null).
See Also:
  `Database_Exception(String, Throwable)`

#### Database_Exception

    public Database_Exception()

Constructs a Database_Exception.

The exception will have the ID of this class as its message.

See Also:
  `Database_Exception(String, Throwable)`

### Method Detail

#### Disconnected

    public boolean Disconnected()

Tests if this Database_Exception was caused by an SQLException indicating loss of database connection.

If the cause of the Database_Exception was itself a Database_Exception it's cause is recursivly checked.

Returns:
  true if this exception was caused by an SQLException which has an SQL state class (first two characters) of `DISCONNECTED_STATE`.

#### exception_String

    public static String exception_String(Throwable throwable)

Generates a message String for a Throwable.

The String returned by the `Throwable.getMessage()` method is used. If the throwable is null or its message is null, the empty String is used. This String has words that should be hidden `masked` out.

If the throwable is a SQLException its message is preceed with a "SQL exception -" line and appended with two lines listing the SQL state and error codes of the exception.

Parameters:
  `throwable` - The Throwable from which to generate a message.

#### exception_String

    public static String exception_String(Exception exception)

Generates a message String for an Exception.

Parameters:
  `exception` - The Exception from which to generate a message.
See Also:
  `exception_String(Throwable)`

#### masked_String

    public static String masked_String(String string)

Masks out words that should be hidden in a String.

When the word "password", "Password" or "PASSWORD" is encountered in the string the following word is replaced with "*******". The delimiters used to identify word characters are any of the " \t\n\r&:=" characters.

Parameters:
  `string` - The String to be masked.
Returns:
  The masked String.
See Also:
  `Words.Mask(Vector)`, `Words.Delimiters(String)`

#### masked_SQLException

    public static SQLException masked_SQLException(SQLException SQL_exception)

Copy an SQLException with any passwords masked out.

A new SQLException is constructed containing a copy of the message and state description from the specified SQLException with any passwords `masked out` in the message. The stack track is also copied. If the SQLException has a chained cause, that is copied over.

This method is applied recursively to any SQLException chained to the specified exception, and the resulting new SQLException used to replace the chained exception.

In effect, a deep copy of the specified SQLException is made with the message being masked in the process.

Parameters:
  `SQL_exception` - The SQLException to be masked and copied.
Returns:
  A SQLExcpetion that is a deep copy of the original.