PIRL.Conductor.Maestro

## Class Theater_Protocol_Exception

- java.lang.Object
- - java.lang.Throwable
  - - java.lang.Exception
    - - java.io.IOException
      - - PIRL.Conductor.Maestro.Theater_Protocol_Exception

All Implemented Interfaces:
  Serializable

    public class Theater_Protocol_Exception
    extends IOException

A Theater_Protocol_Exception is thrown when a Theater method call encounters a problem with the Stage_Manager protocol.

A Theater_Protocol_Exception may have a message, reason and cause. Usually the message is provided by the caller to descrbe the context of the exception and/or provide information that may be useful is solving the problem. A reason code is intended to indicate the category of the problem.

See Also:
  `Theater`, Serialized Form

### Field Summary

Fields
`static String` `ID`
`static int` `INVALID_MESSAGE` The `reason` code indicating that a protocol Message contained invalid content.
`static int` `TIMEOUT` The `reason` code indicating that the operation did not complete within the allowed timeout period.
`static int` `UNAUTHENTICATED` The `reason` code indicating that the identity authentication during the initial handshake with the Stage_Manager was not successful.
`static int` `UNSPECIFIED` The default `reason` code indicating that categorization of the exception was not specified.

### Constructor Summary

Constructors
Constructor and Description
`Theater_Protocol_Exception()` Construct an empty Theater_Protocol_Exception.
`Theater_Protocol_Exception(int reason, Throwable cause)` Construct a Theater_Protocol_Exception with a reason and cause.
`Theater_Protocol_Exception(String message)` Construct a Theater_Protocol_Exception with a message.
`Theater_Protocol_Exception(String message, int reason)` Construct a Theater_Protocol_Exception with a message and reason.
`Theater_Protocol_Exception(String message, int reason, Throwable cause)` Construct a Theater_Protocol_Exception with a message, reason and cause.
`Theater_Protocol_Exception(String message, Throwable cause)` Construct a Theater_Protocol_Exception with a message and cause.
`Theater_Protocol_Exception(Throwable cause)` Construct a Theater_Protocol_Exception with a cause.

### Method Summary

Methods
`int` `Reason()` Get the Reason code for the exception.

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

See Also:
  Constant Field Values

#### UNSPECIFIED

    public static final int UNSPECIFIED

The default `reason` code indicating that categorization of the exception was not specified.

See Also:
  Constant Field Values

#### TIMEOUT

    public static final int TIMEOUT

The `reason` code indicating that the operation did not complete within the allowed timeout period.

See Also:
  Constant Field Values

#### UNAUTHENTICATED

    public static final int UNAUTHENTICATED

The `reason` code indicating that the identity authentication during the initial handshake with the Stage_Manager was not successful.

See Also:
  Constant Field Values

#### INVALID_MESSAGE

    public static final int INVALID_MESSAGE

The `reason` code indicating that a protocol Message contained invalid content.

See Also:
  Constant Field Values

### Constructor Detail

#### Theater_Protocol_Exception

    public Theater_Protocol_Exception(String message,
                              int reason,
                              Throwable cause)

Construct a Theater_Protocol_Exception with a message, reason and cause.

Parameters:
  `message` - A message String providing a context dependent description for the exception. May be null.
  `reason` - An integer indicating the category of the reason for the exception.
  `cause` - A Throwable that caused this Theater_Protocol_Exception to be thrown.May be null.
See Also:
  `Throwable.getMessage()`, `Reason()`, `Throwable.getCause()`

#### Theater_Protocol_Exception

    public Theater_Protocol_Exception(String message,
                              int reason)

Construct a Theater_Protocol_Exception with a message and reason.

A `cause` will not be intialized.

Parameters:
  `message` - A message String providing a context dependent description for the exception. May be null.
  `reason` - An integer indicating the category of the reason for the exception.
See Also:
  `Throwable.getMessage()`, `Reason()`

#### Theater_Protocol_Exception

    public Theater_Protocol_Exception(int reason,
                              Throwable cause)

Construct a Theater_Protocol_Exception with a reason and cause.

The exception `message` will be set to the `ID` of this class.

Parameters:
  `reason` - An integer indicating the category of the reason for the exception.
  `cause` - A Throwable that caused this Theater_Protocol_Exception to be thrown.May be null.
See Also:
  `Reason()`, `Throwable.getCause()`

#### Theater_Protocol_Exception

    public Theater_Protocol_Exception(String message,
                              Throwable cause)

Construct a Theater_Protocol_Exception with a message and cause.

The `reason` for the exception will be `UNSPECIFIED`.

Parameters:
  `message` - A message String providing a context dependent description for the exception. May be null.
  `cause` - A Throwable that caused this Theater_Protocol_Exception to be thrown.May be null.
See Also:
  `Throwable.getMessage()`, `Throwable.getCause()`

#### Theater_Protocol_Exception

    public Theater_Protocol_Exception(String message)

Construct a Theater_Protocol_Exception with a message.

The `reason` for the exception will be `UNSPECIFIED`.

A `cause` will not be intialized.

Parameters:
  `message` - A message String providing a context dependent description for the exception. May be null.
See Also:
  `Throwable.getMessage()`

#### Theater_Protocol_Exception

    public Theater_Protocol_Exception(Throwable cause)

Construct a Theater_Protocol_Exception with a cause.

The exception `message` will be set to the `ID` of this class.

The `reason` for the exception will be `UNSPECIFIED`.

Parameters:
  `cause` - A Throwable that caused this Theater_Protocol_Exception to be thrown.May be null.
See Also:
  `Throwable.getCause()`

#### Theater_Protocol_Exception

    public Theater_Protocol_Exception()

Construct an empty Theater_Protocol_Exception.

### Method Detail

#### Reason

    public int Reason()

Get the Reason code for the exception.

The common reason codes known to Theater_Protocol_Exception are:

`UNSPECIFIED`
  The reason for the exception has not been specified.
`TIMEOUT`
  The communication channel connection operation, or the receipt of an expected Message, did not complete within the allowed timeout period.
`UNAUTHENTICATED`
  The identity authentication during the initial handshake with the Stage_Manager was not successful.
`INVALID_MESSAGE`
  A protocol Message contained invalid content.

N.B.: Other reason codes may be used, and the common reason codes may be used for other than the expected meaning. The descriptions listed above are the uses that are known.

Returns:
  An integer indicating the category of the reason for the exception.