PIRL

PIRL.Conductor.Maestro
Class Theater

java.lang.Object
  extended by 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.

Version:
1.46
Author:
Bradford Castalia - UA/PIRL
See Also:
Remote_Theater, Local_Theater, Stage_Manager

Field Summary
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
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
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. : 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[delimiterport]

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[delimiterport]

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).

PIRL

Copyright (C) \ 2003-2009 Bradford Castalia, University of Arizona