PIRL.Conductor.Maestro

## Class Local_Theater

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

All Implemented Interfaces:
  EventListener, Processing_Listener, Message_Delivered_Listener

    public class Local_Theater
    extends Theater
    implements Message_Delivered_Listener, Processing_Listener

A Local_Theater is the local Conductor management side of a `Theater`.

A Local_Theater is used by a `Conductor` to provide network distributed clients access to its `Management` interface via a `Stage_Manager` proxy server.

A Local_Theater implements the `Message_Delivered_Listener` interface. Each `Message` delivered via a Stage_Manager `Messenger` is examined for an `action` parameter that determines how the remaining content will be mapped to a Management method of the Conductor bound to the Local_Theater, and any return values used to assemble the appropriate `reply` sent back.

A Local_Theater also implements the `Processing_Listener` interface that receives `Processing_Event` notifications from the Conductor bound to the Local_Theater. The `Processing_Changes` of the event are used to assemble the appropriate Message that is sent to all clients that have registered, via a Message with a `Theater.ADD_PROCESSING_LISTENER_ACTION`, an interest in the Conductor's processing events. In addition, any clients that have requested, via a Message with a `Theater.ADD_LOG_WRITER_ACTION`, to receive the Conductor processing log stream will have the stream sent via Messages.

### Field Summary

Fields
`static String` `ASSISTANT_NAME` The name of the Theater Message protocol processing Thread.
`static String` `DEFAULT_HELLO_ADDRESS` The default private multicast address to use in the Hello datagram.
`static int` `DEFAULT_HELLO_PORT` The default port on which to receive the Hello datagram.
`static String` `HELLO_MESSAGE` The content of the Hello broadcast datagram message.
`static String` `ID` Class identification name with source code version and date.
`protected int` `NACK_Messages` The Theater Message protcol error statistics.
`protected int` `Undeliverable_Messages` The Theater Message protcol error statistics.
`protected int` `Unrecognized_Messages` The Theater Message protcol error statistics.

### Fields inherited from class PIRL.Conductor.Maestro.Theater

`ACTION_PARAMETER_NAME, ADD_LOG_WRITER_ACTION, ADD_LOG_WRITER_CODE, ADD_PROCESSING_LISTENER_ACTION, ADD_PROCESSING_LISTENER_CODE, ADDRESS_PARAMETER_NAME, CLASS_ID_PARAMETER_NAME, CONDUCTOR_CONNECT_ACTION, CONDUCTOR_CONNECT_CODE, CONDUCTOR_DISCONNECT_ACTION, CONDUCTOR_DISCONNECT_CODE, CONDUCTOR_STATE_ACTION, CONDUCTOR_STATE_CODE, CONFIGURATION_ACTION, CONFIGURATION_CODE, CONFIGURATION_PARAMETER_NAME, Default_Port, DEFAULT_RECEIVE_TIMEOUT, DONE_ACTION, DONE_CODE, ENABLE_LOG_WRITER_ACTION, ENABLE_LOG_WRITER_CODE, EXCEPTION_PARAMETER_NAME, EXPLANATION_PARAMETER_NAME, FORWARDING_MESSENGERS_PARAMETER_NAME, GET_POLL_INTERVAL_ACTION, GET_POLL_INTERVAL_CODE, GET_RESOLVER_DEFAULT_VALUE_ACTION, GET_RESOLVER_DEFAULT_VALUE_CODE, GET_STOP_ON_FAILURE_ACTION, GET_STOP_ON_FAILURE_CODE, IDENTIFY_ACTION, IDENTIFY_CODE, IDENTITY_ACTION, IDENTITY_CODE, KEY_PARAMETER_NAME, LOG_STYLE_PARAMETER_GROUP, LOG_WRITER_ACTION, LOG_WRITER_CODE, LOG_WRITTEN_PARAMETER_NAME, MEMORY_ALLOCATED_PARAMETER_NAME, MEMORY_AVAILABLE_PARAMETER_NAME, MEMORY_FREE_PARAMETER_NAME, MEMORY_STATUS_PARAMETER_NAME, MESSAGE_BYTES_RECEIVED_PARAMETER_NAME, MESSAGE_BYTES_SENT_PARAMETER_NAME, MESSAGES_RECEIVED_DROPPED_PARAMETER_NAME, MESSAGES_RECEIVED_PARAMETER_NAME, MESSAGES_SENT_DROPPED_PARAMETER_NAME, MESSAGES_SENT_PARAMETER_NAME, MESSENGER_STATUS_PARAMETER_NAME, MESSENGERS_REPORT_ACTION, MESSENGERS_REPORT_CODE, MINIMUM_PROTOCOL_CODE, MINIMUM_RECEIVE_TIMEOUT, NACK_ACTION, NACK_CODE, NAME_PARAMETER_NAME, NL, ORIGINAL_MESSAGE_PARAMETER_NAME, PORT_DELIMITER_CHAR, PROCEDURE_RECORD_PARAMETER_NAME, PROCEDURES_ACTION, PROCEDURES_CHANGED_PARAMETER_NAME, PROCEDURES_CODE, PROCESSING_CHANGES_ACTION, PROCESSING_CHANGES_CODE, PROCESSING_EXCEPTION_ACTION, PROCESSING_EXCEPTION_CODE, PROCESSING_STATE_ACTION, PROCESSING_STATE_CODE, QUIT_ACTION, QUIT_CODE, REMOVE_LOG_WRITER_ACTION, REMOVE_LOG_WRITER_CODE, REMOVE_PROCESSING_LISTENER_ACTION, REMOVE_PROCESSING_LISTENER_CODE, RESET_SEQUENTIAL_FAILURES_ACTION, RESET_SEQUENTIAL_FAILURES_CODE, ROUTE_TO_PARAMETER_NAME, SEQUENTIAL_FAILURES_ACTION, SEQUENTIAL_FAILURES_CODE, SET_POLL_INTERVAL_ACTION, SET_POLL_INTERVAL_CODE, SET_RESOLVER_DEFAULT_VALUE_ACTION, SET_RESOLVER_DEFAULT_VALUE_CODE, SET_STOP_ON_FAILURE_ACTION, SET_STOP_ON_FAILURE_CODE, SOURCE_RECORD_PARAMETER_NAME, SOURCES_ACTION, SOURCES_CODE, SOURCES_REFRESHED_PARAMETER_NAME, START_ACTION, START_CODE, START_CONDUCTOR_ACTION, START_CONDUCTOR_CODE, START_MESSENGER_REPORTING_ACTION, START_MESSENGER_REPORTING_CODE, STATUS_REPORT_ACTION, STATUS_REPORT_CODE, STOP_ACTION, STOP_CODE, STOP_MESSENGER_REPORTING_ACTION, STOP_MESSENGER_REPORTING_CODE, TABLE_PARAMETER_NAME, THEATER_LOCATION_PARAMETER_NAME, THEATER_NAME, UNDELIVERABLE_ACTION, UNDELIVERABLE_CODE, VALUE_PARAMETER_NAME`

### Constructor Summary

Constructors
Constructor and Description
`Local_Theater(Management management)` Construct a Local_Theater for a Conductor Management interface.

### Method Summary

Methods
`boolean` `Auto_Open()` Test if auto-open has been enabled.
`Local_Theater` `Auto_Open(boolean enable)` Enable or disable auto-open mode.
`Local_Theater` `Auto_Open(boolean enable, int port, String address)` Enable or disable auto-open mode.
`boolean` `Close()` Close this Theater.
`String` `Hello_Listener_Address()` Get the network multicast address that will be used to listen for an `auto-open` "Hello" broadcast.
`IOException` `Hello_Listener_Exception()` Get any exception that occured in an `auto-open` "Hello" broadcast listener Thread.
`int` `Hello_Listener_Port()` Get the port number that will be used to listen for an `auto-open` "Hello" broadcast.
`Local_Theater` `Key(String key)` Set the key to be used when `open`ing a Stage_Manager connection during `auto-open` operations.
`Message` `Listener_Identity()` Get the identity of the Management object.
`boolean` `Listening_for_Hello()` Test if this Local_Theater is listening for a `auto-open` "Hello" broadcast.
`void` `Message_Delivered(Message_Delivered_Event event)` A message is delivered from the Stage_Manager.
`int` `NACK_Messages()` Get the number of NACK (negative acknowledgment) Messages that have been received.
`void` `Open(String key)` Open this Local_Theater.
`void` `Processing_Event_Occurred(Processing_Event event)` The Processing_Listener interface implementation.
`String` `toString()` Get a description of this Local_Theater.
`int` `Undeliverable_Messages()` Get the number of undeliverable Theater protocol Messages that have been encountered.
`int` `Unrecognized_Messages()` Get the number of Messages encountered that contain content not recognized by the Theater protocol.

### Methods inherited from class PIRL.Conductor.Maestro.Theater

`Action_Code, Default_Port, Default_Port, Default_Receive_Timeout, Default_Receive_Timeout, Employer, Full_Location, Host, Listen_for_Messages, Location, Location, Messenger, NACK, Name, Open, Open, Opened, Port, Processing_Changes, Processing_Changes, Receive_Message, Receive_Timeout, Receive_Timeout, Record, Send_Message, Stage_Manager_Identity, Table`

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

#### ASSISTANT_NAME

    public static final String ASSISTANT_NAME

The name of the Theater Message protocol processing Thread.

See Also:
  Constant Field Values

#### DEFAULT_HELLO_PORT

    public static final int DEFAULT_HELLO_PORT

The default port on which to receive the Hello datagram.

See Also:
  Constant Field Values

#### DEFAULT_HELLO_ADDRESS

    public static final String DEFAULT_HELLO_ADDRESS

The default private multicast address to use in the Hello datagram.

See Also:
  Constant Field Values

#### HELLO_MESSAGE

    public static final String HELLO_MESSAGE

The content of the Hello broadcast datagram message.

See Also:
  Constant Field Values

#### Undeliverable_Messages

    protected int Undeliverable_Messages

The Theater Message protcol error statistics.

#### NACK_Messages

    protected int NACK_Messages

The Theater Message protcol error statistics.

#### Unrecognized_Messages

    protected int Unrecognized_Messages

The Theater Message protcol error statistics.

### Constructor Detail

#### Local_Theater

    public Local_Theater(Management management)

Construct a Local_Theater for a Conductor Management interface.

Parameters:
  `management` - The Conductor Management interface to use with the Theater Message protocol.
Throws:
  `IllegalArgumentException` - If the management is null.

### Method Detail

#### Key

    public Local_Theater Key(String key)

Set the key to be used when `open`ing a Stage_Manager connection during `auto-open` operations.

Parameters:
  `key` - The Stage_Manager authentication key.
Returns:
  This Local_Theater.

#### Auto_Open

    public boolean Auto_Open()

Test if auto-open has been enabled.

Returns:
  true if auto-open is enabled; false otherwise.
See Also:
  `Auto_Open(boolean)`

#### Auto_Open

    public Local_Theater Auto_Open(boolean enable)

Enable or disable auto-open mode.

The current `"Hello" listener port` and `"Hello" listener address` will be used.

Parameters:
  `enable` - If true, auto-open is enabled; otherwise it is disabled.
Returns:
  This Local_Theater.
See Also:
  `Auto_Open(boolean, int, String)`

#### Auto_Open

    public Local_Theater Auto_Open(boolean enable,
                          int port,
                          String address)

Enable or disable auto-open mode.

When auto-open has been enabled this Local_Theater will attempt to stay open once it has been told to `open`. Failure to open will result in a Thread being started that will `listen` for a `HELLO_MESSAGE` broadcast on a specified port of a network multicast address. When the message is received listening stops, an attempt is made to open this Local_Theater again, and the Thread dies. In addition, if a `Theater.DONE_ACTION` Message is received after this Local_Theater has been opened another attempt to open will be made.

N.B.: Enabling auto-open after an open has failed or this Local_Theater is done will not cause an open to be tried again.

Parameters:
  `enable` - If true, auto-open is enabled; otherwise it is disabled.
  `port` - The port number to use when listening for a "Hello" broadcast. If less than or equal to zero the `DEFAULT_HELLO_PORT` will be used.
  `address` - The network multicast address to use when listening for a "Hello" broadcast. If null the `DEFAULT_HELLO_ADDRESS` will be used.
Returns:
  This Local_Theater.

#### Hello_Listener_Port

    public int Hello_Listener_Port()

Get the port number that will be used to listen for an `auto-open` "Hello" broadcast.

Returns:
  The port number on which to listen for an auto-open "Hello" broadcast.

#### Hello_Listener_Address

    public String Hello_Listener_Address()

Get the network multicast address that will be used to listen for an `auto-open` "Hello" broadcast.

Returns:
  The network multicast address String on which to listen for an auto-open "Hello" broadcast.

#### Listening_for_Hello

    public boolean Listening_for_Hello()

Test if this Local_Theater is listening for a `auto-open` "Hello" broadcast.

Returns:
  true if a Thread is running that is listening for a "Hello" broadcast; false otherwise.

#### Hello_Listener_Exception

    public IOException Hello_Listener_Exception()

Get any exception that occured in an `auto-open` "Hello" broadcast listener Thread.

The exception may be from either the "Hello" broadcast listener socket or the `open` operation. In the former case no attempt will be made to open this Local_Theater again to prevent an endless loop of auto-open broadcast listener socket errors.

Returns:
  The most recent IOException that occurred in a "Hello" broadcast listener Thread. This will be null if no exception has occured.

#### Undeliverable_Messages

    public int Undeliverable_Messages()

Get the number of undeliverable Theater protocol Messages that have been encountered.

Returns:
  The number of undeliverable Theater protocol Messages that have been encountered.

#### NACK_Messages

    public int NACK_Messages()

Get the number of NACK (negative acknowledgment) Messages that have been received.

Returns:
  The number of NACK Messages that have been received.

#### Unrecognized_Messages

    public int Unrecognized_Messages()

Get the number of Messages encountered that contain content not recognized by the Theater protocol.

Returns:
  The number of unrecognized Messages that have been encountered.

#### toString

    public String toString()

Get a description of this Local_Theater.

The description is a line containing the Local_Theater `ID` followed by the base Theater `description`.

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

#### Open

    public void Open(String key)
              throws IOException

Open this Local_Theater.

If this Local_Theater is not `opened` a `new connection` is attempted to the Stage_Manager port on the localhost using the `identity` of the Management object provided at construction time supplemented by the specified authentication key. N.B.: The effective authenticiation key for use by auto-open operations is reset to the specified key only if the latter is non-null.

Once the connection to the Stage_Manager has been established this Local_Theater object is set as the `employer` of the Messenger used to `deliver Messages` from the Stage_Manager. Then this Messenger is told to begin `listening for messages`.

If the Stage_Manager connection failed to open and `auto-open` has been enabled a Thread is started that will `listen` for a `HELLO_MESSAGE` broadcast on a specified port of a network multicast address indicating that a Stage_Manager is available to attempt the connection again. The exception that resulted from failing to open the connection is always thrown regardless of whether auto-open has been enabled.

N.B.: If this Local_Theater has already been `opened` nothing is done. In addition, if an auto-open `"Hello" listener` Thread is active nothing is done even if this Local_Theater is not currently open; this prevents a open race condition.

Parameters:
  `key` - The Stage_Manager `Theater.KEY_PARAMETER_NAME` parameter value String. N.B.: If this key is null
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 with any protocol Message content, including if the `identity` from the Management interface object bound to this Local_Theater when it was constructed does not contain a valid PVL structure.
See Also:
  `Key(String)`

#### Close

    public boolean Close()

Close this Theater.

If this Theater is not `open` nothing is done and false is returned.

The log writer is `removed` from the Theater Management and it is `cleared`. N.B.: The Writers contained in the log writer are not closed.

This object is `removed` from the Management and its lists of Messenger routes to receive Processing_Event notifications is cleared.

The parent Theater is then closed.

Overrides:
  `Close` in class `Theater`
Returns:
  true if this Theater was open at the time the method was called; false if the Theater was already closed.

#### Listener_Identity

    public Message Listener_Identity()

Get the identity of the Management object.

Specified by:
  `Listener_Identity` in interface `Message_Delivered_Listener`
Returns:
  A Message containing the identity of the Management object provided at construction time.

#### Message_Delivered

    public void Message_Delivered(Message_Delivered_Event event)

A message is delivered from the Stage_Manager.

The event containing the delivered Message, and a reference to the Messenger that delivered it, is put on a LinkedBlockingQueue. The the Local_Theater Assistant Thread is started, if it is not already running. The Assistant will take events from the queue (FIFO) and process them according to the Theater Message protocol that conveys the Conductor Management interface information.

Of particular interest is the handling of Messages with the `Theater.DONE_ACTION`: After `closing` this Local_Theater, if `auto-open` has been enabled an attempt is made to `open` the Local_Theater again using the current `key`.

Specified by:
  `Message_Delivered` in interface `Message_Delivered_Listener`
Parameters:
  `event` - The Message_Delivered_Event containing the Message.
See Also:
  `Management`

#### Processing_Event_Occurred

    public void Processing_Event_Occurred(Processing_Event event)

The Processing_Listener interface implementation.

This method is used by the Conductor Management interface.

Specified by:
  `Processing_Event_Occurred` in interface `Processing_Listener`
Parameters:
  `event` - The Conductor Management Processing_Event that has occurred.
See Also:
  `Processing_Event`