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.

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