PIRL.Conductor.Maestro

## Class Theater

- java.lang.Object
- - PIRL.Conductor.Maestro.Theater

Direct Known Subclasses:
  Local_Theater, Remote_Theater

    public class Theater
    extends Object

A Theater provides basic Messenger connection and Message sending services with a Stage_Manager plus the Theater protocol facilities.

This class is designed as a base class for the Remote_Theater and Local_Theater classes that implement a network extended Management interface via Messenger communication with a Stage_Manager class - its clients use the Remote_Theater - that conveys Messages via a Messenger to and from a Conductor instance that use the Local_Theater. These subclasses provide a Message based protocol for transmitting all the Management information between a remote client application and local Conductor application. The common Message parameter names used by the protocol are defined here along with Message `action name` to `action code` mapping for efficient Message `delivery` handler switching.

This class can also be used as the primary interface for clients that will be working with the Stage_Manager directly rather than indirectly through the Management interface.

See Also:
  `Remote_Theater`, `Local_Theater`, `Stage_Manager`

### Field Summary

Fields
`static String` `ACTION_PARAMETER_NAME`
`static String` `ADD_LOG_WRITER_ACTION`
`static int` `ADD_LOG_WRITER_CODE`
`static String` `ADD_PROCESSING_LISTENER_ACTION`
`static int` `ADD_PROCESSING_LISTENER_CODE`
`static String` `ADDRESS_PARAMETER_NAME`
`static String` `CLASS_ID_PARAMETER_NAME`
`static String` `CONDUCTOR_CONNECT_ACTION`
`static int` `CONDUCTOR_CONNECT_CODE`
`static String` `CONDUCTOR_DISCONNECT_ACTION`
`static int` `CONDUCTOR_DISCONNECT_CODE`
`static String` `CONDUCTOR_STATE_ACTION`
`static int` `CONDUCTOR_STATE_CODE`
`static String` `CONFIGURATION_ACTION`
`static int` `CONFIGURATION_CODE`
`static String` `CONFIGURATION_PARAMETER_NAME`
`static int` `Default_Port` The default communications port number.
`static int` `DEFAULT_RECEIVE_TIMEOUT` The default maximum amount of time, in seconds, a Theater will wait for a Message to be received.
`static String` `DONE_ACTION`
`static int` `DONE_CODE`
`static String` `ENABLE_LOG_WRITER_ACTION`
`static int` `ENABLE_LOG_WRITER_CODE`
`static String` `EXCEPTION_PARAMETER_NAME`
`static String` `EXPLANATION_PARAMETER_NAME`
`static String` `FORWARDING_MESSENGERS_PARAMETER_NAME`
`static String` `GET_POLL_INTERVAL_ACTION`
`static int` `GET_POLL_INTERVAL_CODE`
`static String` `GET_RESOLVER_DEFAULT_VALUE_ACTION`
`static int` `GET_RESOLVER_DEFAULT_VALUE_CODE`
`static String` `GET_STOP_ON_FAILURE_ACTION`
`static int` `GET_STOP_ON_FAILURE_CODE`
`static String` `ID` Class identification name with source code version and date.
`static String` `IDENTIFY_ACTION`
`static int` `IDENTIFY_CODE`
`static String` `IDENTITY_ACTION`
`static int` `IDENTITY_CODE`
`static String` `KEY_PARAMETER_NAME`
`static String` `LOG_STYLE_PARAMETER_GROUP`
`static String` `LOG_WRITER_ACTION`
`static int` `LOG_WRITER_CODE`
`static String` `LOG_WRITTEN_PARAMETER_NAME`
`static String` `MEMORY_ALLOCATED_PARAMETER_NAME`
`static String` `MEMORY_AVAILABLE_PARAMETER_NAME`
`static String` `MEMORY_FREE_PARAMETER_NAME`
`static String` `MEMORY_STATUS_PARAMETER_NAME`
`static String` `MESSAGE_BYTES_RECEIVED_PARAMETER_NAME`
`static String` `MESSAGE_BYTES_SENT_PARAMETER_NAME`
`static String` `MESSAGES_RECEIVED_DROPPED_PARAMETER_NAME`
`static String` `MESSAGES_RECEIVED_PARAMETER_NAME`
`static String` `MESSAGES_SENT_DROPPED_PARAMETER_NAME`
`static String` `MESSAGES_SENT_PARAMETER_NAME`
`static String` `MESSENGER_STATUS_PARAMETER_NAME`
`static String` `MESSENGERS_REPORT_ACTION`
`static int` `MESSENGERS_REPORT_CODE`
`static int` `MINIMUM_PROTOCOL_CODE`
`static int` `MINIMUM_RECEIVE_TIMEOUT` The minimum amount of time, in seconds, a Theater will wait for a Message to be received.
`static String` `NACK_ACTION`
`static int` `NACK_CODE`
`static String` `NAME_PARAMETER_NAME`
`static String` `NL`
`static String` `ORIGINAL_MESSAGE_PARAMETER_NAME`
`static char` `PORT_DELIMITER_CHAR` The port number delimiter character.
`static String` `PROCEDURE_RECORD_PARAMETER_NAME`
`static String` `PROCEDURES_ACTION`
`static String` `PROCEDURES_CHANGED_PARAMETER_NAME`
`static int` `PROCEDURES_CODE`
`static String` `PROCESSING_CHANGES_ACTION`
`static int` `PROCESSING_CHANGES_CODE`
`static String` `PROCESSING_EXCEPTION_ACTION`
`static int` `PROCESSING_EXCEPTION_CODE`
`static String` `PROCESSING_STATE_ACTION`
`static int` `PROCESSING_STATE_CODE`
`static String` `QUIT_ACTION`
`static int` `QUIT_CODE`
`static String` `REMOVE_LOG_WRITER_ACTION`
`static int` `REMOVE_LOG_WRITER_CODE`
`static String` `REMOVE_PROCESSING_LISTENER_ACTION`
`static int` `REMOVE_PROCESSING_LISTENER_CODE`
`static String` `RESET_SEQUENTIAL_FAILURES_ACTION`
`static int` `RESET_SEQUENTIAL_FAILURES_CODE`
`static String` `ROUTE_TO_PARAMETER_NAME`
`static String` `SEQUENTIAL_FAILURES_ACTION`
`static int` `SEQUENTIAL_FAILURES_CODE`
`static String` `SET_POLL_INTERVAL_ACTION`
`static int` `SET_POLL_INTERVAL_CODE`
`static String` `SET_RESOLVER_DEFAULT_VALUE_ACTION`
`static int` `SET_RESOLVER_DEFAULT_VALUE_CODE`
`static String` `SET_STOP_ON_FAILURE_ACTION`
`static int` `SET_STOP_ON_FAILURE_CODE`
`static String` `SOURCE_RECORD_PARAMETER_NAME`
`static String` `SOURCES_ACTION`
`static int` `SOURCES_CODE`
`static String` `SOURCES_REFRESHED_PARAMETER_NAME`
`static String` `START_ACTION`
`static int` `START_CODE`
`static String` `START_CONDUCTOR_ACTION`
`static int` `START_CONDUCTOR_CODE`
`static String` `START_MESSENGER_REPORTING_ACTION`
`static int` `START_MESSENGER_REPORTING_CODE`
`static String` `STATUS_REPORT_ACTION`
`static int` `STATUS_REPORT_CODE`
`static String` `STOP_ACTION`
`static int` `STOP_CODE`
`static String` `STOP_MESSENGER_REPORTING_ACTION`
`static int` `STOP_MESSENGER_REPORTING_CODE`
`static String` `TABLE_PARAMETER_NAME`
`static String` `THEATER_LOCATION_PARAMETER_NAME`
`static String` `THEATER_NAME`
`static String` `UNDELIVERABLE_ACTION`
`static int` `UNDELIVERABLE_CODE`
`static String` `VALUE_PARAMETER_NAME`

### Constructor Summary

Constructors
Constructor and Description
`Theater()` Construct an unopened Theater.
`Theater(Message identity)` Construct and open a Theater connected to a Stage_Manager on the local host at the default port.
`Theater(String host, int port, Message identity)` Construct and open a Theater.

### Method Summary

Methods
`static int` `Action_Code(String action)` Get a protocol code for an action name.
`boolean` `Close()` Close this Theater.
`static int` `Default_Port()` Get the default communications port number.
`static void` `Default_Port(int port)` Set the default communications port number.
`static int` `Default_Receive_Timeout()` Get the default maximum amount of time, in seconds, a Theater will wait for a Message to be received.
`static void` `Default_Receive_Timeout(int timeout)` Set the default maximum amount of time, in seconds, a Theater will wait for a Message to be received.
`protected Theater` `Employer(Message_Delivered_Listener employer)` Set the `Messenger employer` to receive asynchronous message delivery.
`static String` `Full_Location(String location)` Provide a fully qualified theater location.
`static String` `Host(String location)` Get the Theater host name for a location or name.
`boolean` `Listen_for_Messages()` Begin asynchronously listening for messages.
`String` `Location()` Get the Theater location.
`static String` `Location(String location)` Provide an abbreviated theater location for a given theater location.
`Messenger` `Messenger()` Get the Messenger used for communication.
`static Message` `NACK(String explanation, Exception exception)` Generate a NACK - no acknowledge - Message with optional explanation and exception parameters.
`static String` `Name(String location)` Get the name portion of a Theater location.
`void` `Open(Message identity)` Open this Theater.
`void` `Open(String host, int port, Message identity)` Open this Theater.
`boolean` `Opened()` Test if this Theater is opened.
`static int` `Port(String location)` Get the Theater communications port number for a location.
`static Processing_Changes` `Processing_Changes(Message message)` Assemble a Processing_Changes object using Message parameter values.
`static Message` `Processing_Changes(String action, Processing_Changes changes)` Assemble a Message containing Processing_Changes parameters.
`Message` `Receive_Message()` Receive a Message.
`int` `Receive_Timeout()` Get the maximum amount of time, in seconds, a Theater will wait for a Message to be received.
`Theater` `Receive_Timeout(int timeout)` Set the maximum amount of time, in seconds, a Theater will wait for a Message to be received.
`static Vector<String>` `Record(Value array)` Assemble a data table record from an Array Value.
`void` `Send_Message(Message message)` Send a Message.
`Message` `Stage_Manager_Identity()` Get the identity of the Theater's Stage_Manager.
`static Vector<Vector<String>>` `Table(Value array)` Assemble a data table from an Array Value.
`String` `toString()` Get the description of this Theater.

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

#### THEATER_NAME

    public static final String THEATER_NAME

See Also:
  Constant Field Values

#### ACTION_PARAMETER_NAME

    public static final String ACTION_PARAMETER_NAME

See Also:
  Constant Field Values

#### IDENTIFY_ACTION

    public static final String IDENTIFY_ACTION

See Also:
  Constant Field Values

#### KEY_PARAMETER_NAME

    public static final String KEY_PARAMETER_NAME

See Also:
  Constant Field Values

#### IDENTITY_ACTION

    public static final String IDENTITY_ACTION

See Also:
  Constant Field Values

#### NACK_ACTION

    public static final String NACK_ACTION

See Also:
  Constant Field Values

#### UNDELIVERABLE_ACTION

    public static final String UNDELIVERABLE_ACTION

See Also:
  Constant Field Values

#### ORIGINAL_MESSAGE_PARAMETER_NAME

    public static final String ORIGINAL_MESSAGE_PARAMETER_NAME

See Also:
  Constant Field Values

#### DONE_ACTION

    public static final String DONE_ACTION

See Also:
  Constant Field Values

#### NAME_PARAMETER_NAME

    public static final String NAME_PARAMETER_NAME

See Also:
  Constant Field Values

#### VALUE_PARAMETER_NAME

    public static final String VALUE_PARAMETER_NAME

See Also:
  Constant Field Values

#### CLASS_ID_PARAMETER_NAME

    public static final String CLASS_ID_PARAMETER_NAME

See Also:
  Constant Field Values

#### EXPLANATION_PARAMETER_NAME

    public static final String EXPLANATION_PARAMETER_NAME

See Also:
  Constant Field Values

#### EXCEPTION_PARAMETER_NAME

    public static final String EXCEPTION_PARAMETER_NAME

See Also:
  Constant Field Values

#### THEATER_LOCATION_PARAMETER_NAME

    public static final String THEATER_LOCATION_PARAMETER_NAME

See Also:
  Constant Field Values

#### START_MESSENGER_REPORTING_ACTION

    public static final String START_MESSENGER_REPORTING_ACTION

See Also:
  Constant Field Values

#### STOP_MESSENGER_REPORTING_ACTION

    public static final String STOP_MESSENGER_REPORTING_ACTION

See Also:
  Constant Field Values

#### MESSENGERS_REPORT_ACTION

    public static final String MESSENGERS_REPORT_ACTION

See Also:
  Constant Field Values

#### START_CONDUCTOR_ACTION

    public static final String START_CONDUCTOR_ACTION

See Also:
  Constant Field Values

#### STATUS_REPORT_ACTION

    public static final String STATUS_REPORT_ACTION

See Also:
  Constant Field Values

#### MESSENGER_STATUS_PARAMETER_NAME

    public static final String MESSENGER_STATUS_PARAMETER_NAME

See Also:
  Constant Field Values

#### FORWARDING_MESSENGERS_PARAMETER_NAME

    public static final String FORWARDING_MESSENGERS_PARAMETER_NAME

See Also:
  Constant Field Values

#### MESSAGES_SENT_PARAMETER_NAME

    public static final String MESSAGES_SENT_PARAMETER_NAME

See Also:
  Constant Field Values

#### MESSAGE_BYTES_SENT_PARAMETER_NAME

    public static final String MESSAGE_BYTES_SENT_PARAMETER_NAME

See Also:
  Constant Field Values

#### MESSAGES_SENT_DROPPED_PARAMETER_NAME

    public static final String MESSAGES_SENT_DROPPED_PARAMETER_NAME

See Also:
  Constant Field Values

#### MESSAGES_RECEIVED_PARAMETER_NAME

    public static final String MESSAGES_RECEIVED_PARAMETER_NAME

See Also:
  Constant Field Values

#### MESSAGE_BYTES_RECEIVED_PARAMETER_NAME

    public static final String MESSAGE_BYTES_RECEIVED_PARAMETER_NAME

See Also:
  Constant Field Values

#### MESSAGES_RECEIVED_DROPPED_PARAMETER_NAME

    public static final String MESSAGES_RECEIVED_DROPPED_PARAMETER_NAME

See Also:
  Constant Field Values

#### MEMORY_STATUS_PARAMETER_NAME

    public static final String MEMORY_STATUS_PARAMETER_NAME

See Also:
  Constant Field Values

#### MEMORY_AVAILABLE_PARAMETER_NAME

    public static final String MEMORY_AVAILABLE_PARAMETER_NAME

See Also:
  Constant Field Values

#### MEMORY_ALLOCATED_PARAMETER_NAME

    public static final String MEMORY_ALLOCATED_PARAMETER_NAME

See Also:
  Constant Field Values

#### MEMORY_FREE_PARAMETER_NAME

    public static final String MEMORY_FREE_PARAMETER_NAME

See Also:
  Constant Field Values

#### CONDUCTOR_CONNECT_ACTION

    public static final String CONDUCTOR_CONNECT_ACTION

See Also:
  Constant Field Values

#### CONDUCTOR_DISCONNECT_ACTION

    public static final String CONDUCTOR_DISCONNECT_ACTION

See Also:
  Constant Field Values

#### ADDRESS_PARAMETER_NAME

    public static final String ADDRESS_PARAMETER_NAME

See Also:
  Constant Field Values

#### ROUTE_TO_PARAMETER_NAME

    public static final String ROUTE_TO_PARAMETER_NAME

See Also:
  Constant Field Values

#### START_ACTION

    public static final String START_ACTION

See Also:
  Constant Field Values

#### PROCESSING_STATE_ACTION

    public static final String PROCESSING_STATE_ACTION

See Also:
  Constant Field Values

#### STOP_ACTION

    public static final String STOP_ACTION

See Also:
  Constant Field Values

#### QUIT_ACTION

    public static final String QUIT_ACTION

See Also:
  Constant Field Values

#### CONFIGURATION_ACTION

    public static final String CONFIGURATION_ACTION

See Also:
  Constant Field Values

#### CONFIGURATION_PARAMETER_NAME

    public static final String CONFIGURATION_PARAMETER_NAME

See Also:
  Constant Field Values

#### SOURCES_ACTION

    public static final String SOURCES_ACTION

See Also:
  Constant Field Values

#### PROCEDURES_ACTION

    public static final String PROCEDURES_ACTION

See Also:
  Constant Field Values

#### TABLE_PARAMETER_NAME

    public static final String TABLE_PARAMETER_NAME

See Also:
  Constant Field Values

#### GET_POLL_INTERVAL_ACTION

    public static final String GET_POLL_INTERVAL_ACTION

See Also:
  Constant Field Values

#### SET_POLL_INTERVAL_ACTION

    public static final String SET_POLL_INTERVAL_ACTION

See Also:
  Constant Field Values

#### GET_RESOLVER_DEFAULT_VALUE_ACTION

    public static final String GET_RESOLVER_DEFAULT_VALUE_ACTION

See Also:
  Constant Field Values

#### SET_RESOLVER_DEFAULT_VALUE_ACTION

    public static final String SET_RESOLVER_DEFAULT_VALUE_ACTION

See Also:
  Constant Field Values

#### GET_STOP_ON_FAILURE_ACTION

    public static final String GET_STOP_ON_FAILURE_ACTION

See Also:
  Constant Field Values

#### SET_STOP_ON_FAILURE_ACTION

    public static final String SET_STOP_ON_FAILURE_ACTION

See Also:
  Constant Field Values

#### SEQUENTIAL_FAILURES_ACTION

    public static final String SEQUENTIAL_FAILURES_ACTION

See Also:
  Constant Field Values

#### RESET_SEQUENTIAL_FAILURES_ACTION

    public static final String RESET_SEQUENTIAL_FAILURES_ACTION

See Also:
  Constant Field Values

#### PROCESSING_EXCEPTION_ACTION

    public static final String PROCESSING_EXCEPTION_ACTION

See Also:
  Constant Field Values

#### CONDUCTOR_STATE_ACTION

    public static final String CONDUCTOR_STATE_ACTION

See Also:
  Constant Field Values

#### SOURCE_RECORD_PARAMETER_NAME

    public static final String SOURCE_RECORD_PARAMETER_NAME

See Also:
  Constant Field Values

#### PROCEDURE_RECORD_PARAMETER_NAME

    public static final String PROCEDURE_RECORD_PARAMETER_NAME

See Also:
  Constant Field Values

#### SOURCES_REFRESHED_PARAMETER_NAME

    public static final String SOURCES_REFRESHED_PARAMETER_NAME

See Also:
  Constant Field Values

#### PROCEDURES_CHANGED_PARAMETER_NAME

    public static final String PROCEDURES_CHANGED_PARAMETER_NAME

See Also:
  Constant Field Values

#### ADD_PROCESSING_LISTENER_ACTION

    public static final String ADD_PROCESSING_LISTENER_ACTION

See Also:
  Constant Field Values

#### REMOVE_PROCESSING_LISTENER_ACTION

    public static final String REMOVE_PROCESSING_LISTENER_ACTION

See Also:
  Constant Field Values

#### PROCESSING_CHANGES_ACTION

    public static final String PROCESSING_CHANGES_ACTION

See Also:
  Constant Field Values

#### LOG_WRITER_ACTION

    public static final String LOG_WRITER_ACTION

See Also:
  Constant Field Values

#### LOG_WRITTEN_PARAMETER_NAME

    public static final String LOG_WRITTEN_PARAMETER_NAME

See Also:
  Constant Field Values

#### LOG_STYLE_PARAMETER_GROUP

    public static final String LOG_STYLE_PARAMETER_GROUP

See Also:
  Constant Field Values

#### ADD_LOG_WRITER_ACTION

    public static final String ADD_LOG_WRITER_ACTION

See Also:
  Constant Field Values

#### REMOVE_LOG_WRITER_ACTION

    public static final String REMOVE_LOG_WRITER_ACTION

See Also:
  Constant Field Values

#### ENABLE_LOG_WRITER_ACTION

    public static final String ENABLE_LOG_WRITER_ACTION

See Also:
  Constant Field Values

#### MINIMUM_PROTOCOL_CODE

    public static final int MINIMUM_PROTOCOL_CODE

See Also:
  Constant Field Values

#### IDENTIFY_CODE

    public static final int IDENTIFY_CODE

See Also:
  Constant Field Values

#### CONDUCTOR_CONNECT_CODE

    public static final int CONDUCTOR_CONNECT_CODE

See Also:
  Constant Field Values

#### IDENTITY_CODE

    public static final int IDENTITY_CODE

See Also:
  Constant Field Values

#### START_CODE

    public static final int START_CODE

See Also:
  Constant Field Values

#### PROCESSING_STATE_CODE

    public static final int PROCESSING_STATE_CODE

See Also:
  Constant Field Values

#### STOP_CODE

    public static final int STOP_CODE

See Also:
  Constant Field Values

#### QUIT_CODE

    public static final int QUIT_CODE

See Also:
  Constant Field Values

#### CONFIGURATION_CODE

    public static final int CONFIGURATION_CODE

See Also:
  Constant Field Values

#### SOURCES_CODE

    public static final int SOURCES_CODE

See Also:
  Constant Field Values

#### PROCEDURES_CODE

    public static final int PROCEDURES_CODE

See Also:
  Constant Field Values

#### GET_POLL_INTERVAL_CODE

    public static final int GET_POLL_INTERVAL_CODE

See Also:
  Constant Field Values

#### SET_POLL_INTERVAL_CODE

    public static final int SET_POLL_INTERVAL_CODE

See Also:
  Constant Field Values

#### GET_RESOLVER_DEFAULT_VALUE_CODE

    public static final int GET_RESOLVER_DEFAULT_VALUE_CODE

See Also:
  Constant Field Values

#### SET_RESOLVER_DEFAULT_VALUE_CODE

    public static final int SET_RESOLVER_DEFAULT_VALUE_CODE

See Also:
  Constant Field Values

#### GET_STOP_ON_FAILURE_CODE

    public static final int GET_STOP_ON_FAILURE_CODE

See Also:
  Constant Field Values

#### SET_STOP_ON_FAILURE_CODE

    public static final int SET_STOP_ON_FAILURE_CODE

See Also:
  Constant Field Values

#### SEQUENTIAL_FAILURES_CODE

    public static final int SEQUENTIAL_FAILURES_CODE

See Also:
  Constant Field Values

#### RESET_SEQUENTIAL_FAILURES_CODE

    public static final int RESET_SEQUENTIAL_FAILURES_CODE

See Also:
  Constant Field Values

#### PROCESSING_EXCEPTION_CODE

    public static final int PROCESSING_EXCEPTION_CODE

See Also:
  Constant Field Values

#### CONDUCTOR_STATE_CODE

    public static final int CONDUCTOR_STATE_CODE

See Also:
  Constant Field Values

#### ADD_PROCESSING_LISTENER_CODE

    public static final int ADD_PROCESSING_LISTENER_CODE

See Also:
  Constant Field Values

#### REMOVE_PROCESSING_LISTENER_CODE

    public static final int REMOVE_PROCESSING_LISTENER_CODE

See Also:
  Constant Field Values

#### PROCESSING_CHANGES_CODE

    public static final int PROCESSING_CHANGES_CODE

See Also:
  Constant Field Values

#### LOG_WRITER_CODE

    public static final int LOG_WRITER_CODE

See Also:
  Constant Field Values

#### ADD_LOG_WRITER_CODE

    public static final int ADD_LOG_WRITER_CODE

See Also:
  Constant Field Values

#### REMOVE_LOG_WRITER_CODE

    public static final int REMOVE_LOG_WRITER_CODE

See Also:
  Constant Field Values

#### ENABLE_LOG_WRITER_CODE

    public static final int ENABLE_LOG_WRITER_CODE

See Also:
  Constant Field Values

#### CONDUCTOR_DISCONNECT_CODE

    public static final int CONDUCTOR_DISCONNECT_CODE

See Also:
  Constant Field Values

#### DONE_CODE

    public static final int DONE_CODE

See Also:
  Constant Field Values

#### NACK_CODE

    public static final int NACK_CODE

See Also:
  Constant Field Values

#### UNDELIVERABLE_CODE

    public static final int UNDELIVERABLE_CODE

See Also:
  Constant Field Values

#### START_MESSENGER_REPORTING_CODE

    public static final int START_MESSENGER_REPORTING_CODE

See Also:
  Constant Field Values

#### STOP_MESSENGER_REPORTING_CODE

    public static final int STOP_MESSENGER_REPORTING_CODE

See Also:
  Constant Field Values

#### MESSENGERS_REPORT_CODE

    public static final int MESSENGERS_REPORT_CODE

See Also:
  Constant Field Values

#### START_CONDUCTOR_CODE

    public static final int START_CONDUCTOR_CODE

See Also:
  Constant Field Values

#### STATUS_REPORT_CODE

    public static final int STATUS_REPORT_CODE

See Also:
  Constant Field Values

#### PORT_DELIMITER_CHAR

    public static final char PORT_DELIMITER_CHAR

The port number delimiter character.

The delimiter, if present, occurs between the `hostname` and `port number` portions of a Theater `location` or `name`.

N.B.: The delimiter and trailing port number portion of a Theater location or name may not be present. In this case the port number is the `default port`.

See Also:
  Constant Field Values

#### Default_Port

    public static int Default_Port

The default communications port number.

The value is initialized to the `Dispatcher.DEFAULT_PORT`.

#### DEFAULT_RECEIVE_TIMEOUT

    public static final int DEFAULT_RECEIVE_TIMEOUT

The default maximum amount of time, in seconds, a Theater will wait for a Message to be received.

See Also:
  `Default_Receive_Timeout(int)`, Constant Field Values

#### MINIMUM_RECEIVE_TIMEOUT

    public static final int MINIMUM_RECEIVE_TIMEOUT

The minimum amount of time, in seconds, a Theater will wait for a Message to be received.

See Also:
  `DEFAULT_RECEIVE_TIMEOUT`, Constant Field Values

#### NL

    public static final String NL

### Constructor Detail

#### Theater

    public Theater()

Construct an unopened Theater.

#### Theater

    public Theater(String host,
           int port,
           Message identity)
            throws IOException

Construct and open a Theater.

Parameters:
  `host` - The name or IP address of the host system where the Stage_Manager is expected to be running. If null, "localhost" will be used.
  `port` - The port number on the named host to use for establishing a communication channel to the Stage_Manager. If less than or equal to zero the `Dispatcher.DEFAULT_PORT` will be used.
  `identity` - An `Identity` Message. N.B.: A `KEY_PARAMETER_NAME` parameter may be required. If null an Identity using the `THEATER_NAME` and no key parameter will be used.
Throws:
  `IOException` - If a connection could not be established to the Stage_Manager. This will be a Theater_Protocol_Exception if there was a problem parsing any of the protocol messages.
See Also:
  `Open(String, int, Message)`

#### Theater

    public Theater(Message identity)
            throws IOException

Construct and open a Theater connected to a Stage_Manager on the local host at the default port.

Parameters:
  `identity` - An `Identity` Message. N.B.: A `KEY_PARAMETER_NAME` parameter may be required. If null an Identity using the `THEATER_NAME` and no key parameter will be used.
Throws:
  `IOException` - If a connection could not be established to the Stage_Manager. This will be a Theater_Protocol_Exception if there was a problem parsing any of the protocol messages.
See Also:
  `Open(String, int, Message)`

### Method Detail

#### Messenger

    public Messenger Messenger()

Get the Messenger used for communication.

Returns:
  A Messenger. This will be null if the communication channel has not yet been `opened`.

#### Default_Port

    public static int Default_Port()

Get the default communications port number.

Returns:
  The default communications port number.
See Also:
  `Default_Port(int)`

#### Default_Port

    public static void Default_Port(int port)

Set the default communications port number.

This port number will be used when an attempt is made to `open` the Theater using a port number that is not positive.

Parameters:
  `port` - The default communications port number. If not positive the `Dispatcher.DEFAULT_PORT` is used.

#### Default_Receive_Timeout

    public static int Default_Receive_Timeout()

Get the default maximum amount of time, in seconds, a Theater will wait for a Message to be received.

Returns:
  The time, in seconds, when a timeout will occur while waiting for a Message to be received.
See Also:
  `Receive_Timeout()`

#### Default_Receive_Timeout

    public static void Default_Receive_Timeout(int timeout)

Set the default maximum amount of time, in seconds, a Theater will wait for a Message to be received.

N.B.: This value is only effective when a new Theater is constructed.

Parameters:
  `timeout` - The time, in seconds, when a timeout will occur while waiting for a Message to be received. The value will be limited to be greater than or equal to the `MINIMUM_RECEIVE_TIMEOUT`.
See Also:
  `Receive_Timeout()`

#### Receive_Timeout

    public int Receive_Timeout()

Get the maximum amount of time, in seconds, a Theater will wait for a Message to be received.

The value is initialized when a Theater is constructed to the `default receive timeout`.

Returns:
  The time, in seconds, when a timeout will occur while waiting for a Message to be received.
See Also:
  `Receive_Timeout(int)`

#### Receive_Timeout

    public Theater Receive_Timeout(int timeout)

Set the maximum amount of time, in seconds, a Theater will wait for a Message to be received.

Returns:
  The time, in seconds, when a timeout will occur while waiting for a Message to be received. The value will be limited to be greater than or equal to the `MINIMUM_RECEIVE_TIMEOUT`.
See Also:
  `Receive_Message()`

#### Action_Code

    public static int Action_Code(String action)

Get a protocol code for an action name.

Returns:
  A protocol code number. This will be -1 if the action name does not map to a protocol code.

#### Location

    public String Location()

Get the Theater location.

The Theater location is the Theater's `Messenger` `client hostname` with the `client port number` following a colon (':') delimiter. This is the fully qualified location of a Theater.

Returns:
  The Theater location String. This will be null if no Messenger has yet been `opened`.
See Also:
  `Location(String)`

#### Stage_Manager_Identity

    public Message Stage_Manager_Identity()

Get the identity of the Theater's Stage_Manager.

N.B.: The availability of a Stage_Manager identity does not imply that the Theater is `open`. The most recent Stage_Manager identity that was obtained when the Theater was last `opened` is provided.

Returns:
  A Message containing the identity of the Stage_Mangager for the Theater. This will be null if the Theater has yet to be opened for the first time.

#### toString

    public String toString()

Get the description of this Theater.

The first line of the description is the class `ID`. The second line of the description provides the Theater location, if it is known, and whether or not the Theater is open. If the Theater has a `Messenger` its description is included on the following lines.

Overrides:
  `toString` in class `Object`
Returns:
  The Theater description String.

#### Open

    public void Open(String host,
            int port,
            Message identity)
              throws IOException

Open this Theater.

If this Theater is not `opened` a new Messenger is constructed with a communication connection to the Stage_Manager at the port on the specifed host.

N.B.: The Messenger will that is constructed will be in synchronous message receive mode. The initial Stage_Manager handshake will be done. The handshake is initiated by an `IDENTIFY_ACTION` Message `received` from the Stage_Manager with an `Identity` Message sent in reply. <b.N.B.: Unless the Stage_Manager will accept unauthenticated connections a `KEY_PARAMETER_NAME` parameter with the required authentication value must be provided in which case the parameter of the same name from the Stage_Manager Identify Message will be used to encode the value from the Identity Message before it is sent.

To start asynchronously listening for messages set the `employer` and begin to `listen for messages`.

Parameters:
  `host` - The name or IP address of the host system where the Stage_Manager is expected to be running. If null, "localhost" will be used.
  `port` - The port number on the named host to use for establishing a communication channel to the Stage_Manager. If less than or equal to zero the `Default_Port()` will be used.
  `identity` - An `Identity` Message. N.B.: A `KEY_PARAMETER_NAME` parameter may be required. If null an Identity using the `THEATER_NAME` and no key parameter will be used.
Throws:
  `IOException` - If a connection could not be established to the Stage_Manager. This will be a Theater_Protocol_Exception if there was a problem parsing any of the protocol messages.

#### Open

    public void Open(Message identity)
              throws IOException

Open this Theater.

The `default port` on the "localhost" will be used to open the communication connection.

Parameters:
  `identity` - An `Identity` Message. N.B.: A `KEY_PARAMETER_NAME` parameter may be required. If null an Identity using the `THEATER_NAME` and no key parameter will be used.
Throws:
  `IOException`

#### Opened

    public boolean Opened()

Test if this Theater is opened.

Returns:
  true if a Messenger is active and has a connected communication channel to the Stage_Manager; false otherwise.

#### Employer

    protected Theater Employer(Message_Delivered_Listener employer)

Set the `Messenger employer` to receive asynchronous message delivery.

Parameters:
  `employer` - A Message_Delivered_Listener employer object. If null, nothing is done.
Returns:
  This Theater object.
Throws:
  `IllegalStateException` - If not yet `opened`.
See Also:
  `Message_Delivered_Listener`

#### Listen_for_Messages

    public boolean Listen_for_Messages()

Begin asynchronously listening for messages.

The Messenger is told to `listen for messages`.

Returns:
  true if the Messenger began asynchronously listening for messages; false if the Messenger is not connected to the communication channel.
Throws:
  `IllegalStateException` - If not yet `opened`.

#### Close

    public boolean Close()

Close this Theater.

If this Theater is `open` it's Messenger is given the `Done` message which will close the communication connection.

Returns:
  true if this Theater was open at the time the method was called; false if the Theater was already closed.

#### Send_Message

    public void Send_Message(Message message)
                      throws IOException

Send a Message.

If not `opened` or the Message is null nothing is done.

A Message is sent via the `Messenger`. If an IOException occurs the Stage_Manager is (@link #Close() closed}. However, if the message can not be parsed the Stage_Manager is not closed.

Parameters:
  `message` - A Message. If null nothing is done.
Throws:
  `IOException` - If there was a problem send the message. This will be a Theater_Protocol_Exception if the message could not be parsed.

#### Receive_Message

    public Message Receive_Message()
                            throws IOException

Receive a Message.

If not `opened` nothing is done and null is returned.

A Message is synchronously received from the `Messenger`. If the `receive timeout` expires null is returned. If an IOException occurs the Stage_Manager is (@link #Close() closed}. However, if the message can not be parsed the Stage_Manager is not closed.

Returns:
  A Message. This will be null if this Theater is not open or if the receive timeout occured.
Throws:
  `IOException` - If there was a problem receiving a message. This will be a Theater_Protocol_Exception if the message could not be parsed.

#### Location

    public static String Location(String location)

Provide an abbreviated theater location for a given theater location.

The format of a theater location string is:

hostname[delimiter port]

The hostname portion is the `name` obtained from the `host` part of the given location.

The delimiter is the `PORT_DELIMITER_CHAR`. If it is present in the given location the remaining port portion is compared to the Theater's `default port`. If they are the same the delimiter and port portion are not included in the returned location String.

Parameters:
  `location` - A theater location or name String. If null, or the emtpy String, null is returned.
Returns:
  A possibly modified theater location String.
See Also:
  `Location()`

#### Full_Location

    public static String Full_Location(String location)

Provide a fully qualified theater location.

The format of a theater location string is:

host[delimiter port]

The host may be a hostname, short or fully qualified, or IP address. If the hostname can be `fully qualified` that name is used; otherwise the hostname portion of the location is used as given.

N.B.: A hashmap of host names to fully qualified hostnames is maintained to avoid the, often very time consuming, DNS lookup of canonical hostnames each time this utility is called on a previously examined location.

The optional port is the system port number used to connect to the Stage_Manager. If no port number is present in the given location the `default port` is used. The delimiter is the `PORT_DELIMITER_CHAR`.

Parameters:
  `location` - A theater location or name String. If null, or the emtpy String, null is returned.
Returns:
  A possibly modified theater location String.
See Also:
  `Location(String)`

#### Name

    public static String Name(String location)

Get the name portion of a Theater location.

The name portion of a Theater location is the leading substring up to, but not including, the first period character ('.') in the String plus the trailing substring starting with the last `PORT_DELIMITER_CHAR`, if present. If no period character is found the entire location is returned. Thus the `port number`, if present, is retained but only the `short hostname` (but without doing the system name lookup) is returned.

However, if the name portion of the string is numeric, then the entire name is always returned since this is most likely an IP address.

Parameters:
  `location` - A Theater location String. If null, null is returned.
Returns:
  The Theater name String.

#### Host

    public static String Host(String location)

Get the Theater host name for a location or name.

Parameters:
  `location` - A Theater location or name String.
Returns:
  If the location String contains a `PORT_DELIMITER_CHAR` the substring preceeding the delimiter is returned. Otherwise the entire String is returned. If the location is null, null is returned.
See Also:
  `Location(String)`

#### Port

    public static int Port(String location)

Get the Theater communications port number for a location.

Parameters:
  `location` - A Theater location String. If null -1 is returned.
Returns:
  If the location String contains a port number following a `PORT_DELIMITER_CHAR` that value is returned. Otherwise the `default port` for a Theater is returned.
See Also:
  `Location(String)`

#### NACK

    public static Message NACK(String explanation,
               Exception exception)

Generate a NACK - no acknowledge - Message with optional explanation and exception parameters.

A `NACK action Message` is obtained. If the explanation is non-null and not empty an `EXPLANATION_PARAMETER_NAME` parameter is set in the Message with the explanation. If the exception is non-null an `EXCEPTION_PARAMETER_NAME` parameter is set in the Message with the exception's String description.

Parameters:
  `explanation` - An explanatory String. May be null.
  `exception` - An Exception associated with the NACK. May be null.
Returns:
  A NACK action Message.

#### Processing_Changes

    public static Message Processing_Changes(String action,
                             Processing_Changes changes)

Assemble a Message containing Processing_Changes parameters.

The Message will have an `ACTION_PARAMETER_NAME` with the specified action value.

Each Processing_Changes state variable that has a value indicating a changed Conductor state is entered as a parameter in the assembled Message:

`CONFIGURATION_PARAMETER_NAME`
  A Parameter Group containing the current Conductor Configuration parameters. This will not be present if the changes `Configuration` is null.
`PROCESSING_STATE_ACTION`
  The current Conductor processing state code. This not be present if the changes `processing state` is zero.
`SOURCE_RECORD_PARAMETER_NAME`
  The current Conductor source record as an Array of String Values. This will not be present if the changes `source record` is null.
`PROCEDURE_RECORD_PARAMETER_NAME`
  The current Conductor procedure record as an Array of String Values. This will not be present if the changes `procedure record` is null.
`SOURCES_REFRESHED_PARAMETER_NAME`
  A flag value of "true" indicating that the Conductor has just refreshed its cache of source records. This will not be present if the changes `sources refreshed` value is false.
`PROCEDURES_CHANGED_PARAMETER_NAME`
  A flag value of "true" indicating that the Conductor has just reloaded a modified procedures table. This will not be present if the changes `procedures changed` value is false;
`SEQUENTIAL_FAILURES_ACTION`
  The current number of sequential source record processing failures that the Conductor encountered. This will not be present if the changes `sequential failures` value is less than zero.
`PROCESSING_EXCEPTION_ACTION`
  A description of the last processing error that occured in the Conductor. This will not be present if the changes `error condition` is null.
`QUIT_ACTION`
  A flag value of "true" indicating that the Conductor process is about to exit. This will not be present if the changes `exiting` value is false.

Parameters:
  `action` - A String naming the value of the `ACTION_PARAMETER_NAME` parameter of the Message. If null, `PROCESSING_CHANGES_ACTION` will be used.
  `changes` - A Processing_Changes object. If null, null is returned.
Returns:
  A Message containing Processing_Changes parameters. This will be null if, and only if, the changes argument is null.

#### Processing_Changes

    public static Processing_Changes Processing_Changes(Message message)

Assemble a Processing_Changes object using Message parameter values.

Each possible `Processing_Changes Message` parameter is sought in the provided Message. For parameters that are found their values are used to set the corresponding Conductor processing state variable in a Processing_Changes object that is initialized with all its variables set to the unchanged value.

Parameters:
  `message` - A Message containing Processing_Changes parameters. If null, null is returned.
Returns:
  A Processing_Changes object. This will be null if, and only if, the message argument is null.

#### Table

    public static Vector<Vector<String>> Table(Value array)

Assemble a data table from an Array Value.

Each Array entry is expected to an Array Value that is assembled into a Record Vector.

Parameters:
  `array` - An Array of Array Values.
Returns:
  A Vector of String Vectors. This will be null if any of the Array entries can not be assembled into a Record Vector of Strings.

#### Record

    public static Vector<String> Record(Value array)

Assemble a data table record from an Array Value.

Each Array entry is converted into its String representation and added to the record Vector.

Parameters:
  `array` - A Array Value.
Returns:
  A Vector of Strings. This will be null if any of the Array entries can not be converted to a String (for example, if the entry is an Array).