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.

Version:

1.41

Author:

Bradford Castalia - UA/PIRL

Field Summary

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

Local_Theater(Management management)
Construct a Local_Theater for a Conductor Management interface.

Method Summary

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