PIRL.Conductor.Maestro

## Class Stage_Manager

- java.lang.Object
- - PIRL.Messenger.Dispatcher
  - - PIRL.Conductor.Maestro.Stage_Manager

All Implemented Interfaces:
  Runnable, EventListener, Message_Delivered_Listener

    public class Stage_Manager
    extends Dispatcher

A Stage_Manager is a Messenger manager for communication between Conductor processes and client processes.

See Also:
  `Theater`, `Messenger`

### Field Summary

Fields
`static String` `ASSISTANT_NAME`
`static String` `COMMAND_PARAMETER_NAME`
`static String` `CONDUCTOR_COMMAND_PARAMETER_NAME` The name of the Configuration parameter that specifies the Conductor command name.
`static String` `COUNT_PARAMETER_NAME`
`static int` `DEFAULT_MAX_START_CONDUCTORS_COUNT` The default maximum number of remote Conductor commands that may be executed by a single request.
`static String` `EXCEPTION_PARAMETER_NAME`
`static String` `EXPLANATION_PARAMETER_NAME`
`static String` `ID` Class identification name with source code version and date.
`static String` `MAX_START_CONDUCTORS_COUNT_PARAMETER_NAME` The name of the Configuration parameter that specifies the maximum number of remote Conductor commands that may be executed by a single request.
`static String` `REPORT_PARAMETER_NAME`
`static String` `STAGE_MANAGER_NAME` The name used by the base Dispatcher class for the Stage_Manager service.
`static String` `START_CONDUCTORS_ACTION`

### Fields inherited from class PIRL.Messenger.Dispatcher

`ACK_ACTION, ACTION_PARAMETER_NAME, ADDRESS_PARAMETER_NAME, CLASS_ID_PARAMETER_NAME, CONFIGURATION_SOURCE_PARAMETER_NAME, DATE_FORMAT, DATE_FORMATTING, DEFAULT_DISPATCHER_NAME, DEFAULT_HELLO_ADDRESS, DEFAULT_HELLO_PORT, DEFAULT_IDENTIFY_TIMEOUT, DEFAULT_PORT, Dispatcher_ID, DONE_ACTION, EXIT_COMMAND_LINE_SYNTAX, EXIT_CONFIG_FILE_PROBLEM, EXIT_IO_ERROR, EXIT_NO_LOG_FILE, EXIT_SECURITY_VIOLATION, EXIT_SUCCESS, EXIT_UNKNOWN_EXCEPTION, HELLO_ADDRESS_PARAMETER_NAME, HELLO_MESSAGE, HELLO_PORT_PARAMETER_NAME, HELLO_RATE_PARAMETER_NAME, IDENTIFY_ACTION, IDENTIFY_TIMEOUT_PARAMETER_NAME, IDENTITY_ACTION, KEY_PARAMETER_NAME, LINK_MESSENGER_ACTION, LOG_PATHNAME_PARAMETER_NAME, Log_Stream, 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_CORRUPTED_PARAMETER_NAME, MESSAGES_RECEIVED_DROPPED_PARAMETER_NAME, MESSAGES_RECEIVED_PARAMETER_NAME, MESSAGES_SENT_CORRUPTED_PARAMETER_NAME, MESSAGES_SENT_DROPPED_PARAMETER_NAME, MESSAGES_SENT_PARAMETER_NAME, MESSAGES_UNFORWARDABLE_PARAMETER_NAME, MESSENGER_STATUS_PARAMETER_NAME, Messengers, MESSENGERS_REPORT_ACTION, MINIMUM_IDENTIFY_TIMEOUT, NACK_ACTION, NAME_PARAMETER_NAME, NL, ORIGINAL_MESSAGE_PARAMETER_NAME, PASSWORD_PARAMETER_NAME, PORT_PARAMETER_NAME, Report_Messenger_Connections, Report_to_Messengers, ROUTE_TO_PARAMETER_NAME, START_MESSENGER_REPORTING_ACTION, START_STOP_MARKER, STATUS_REPORT_ACTION, STDOUT, STOP_MESSENGER_REPORTING_ACTION, The_Configuration, UNAUTHENTICATED_CONNECTIONS_ALLOWED, UNDELIVERABLE_ACTION, UNLINK_MESSENGER_ACTION`

### Constructor Summary

Constructors
Constructor and Description
`Stage_Manager()` Construct a Stage_Manager.
`Stage_Manager(Configuration configuration)` Construct a Stage_Manager using a Configuration.
`Stage_Manager(Configuration configuration, int port)` Construct a Stage_Manager using a Configuration and port number.

### Method Summary

Methods
`protected void` `Configure(Configuration configuration)` Configures the Stage_Manager.
`static void` `main(String[] args)`
`void` `Message_Delivered(Message_Delivered_Event event)` Receives delivery of a message.
`static void` `Usage()`

### Methods inherited from class PIRL.Messenger.Dispatcher

`Authenticate, Authentication, Config_Pathname, Default_Configuration_Source, Default_Dispatcher_Name, Default_Dispatcher_Name, Default_Log_Filename, Dispatcher_Name, Dispatcher_Name, Hello_Address, Hello_Port, Identify_Timeout, Identify_Timeout, Identity, Identity, Listener_Identity, Location, Log_Pathname, Log_Pathname, Log_Stream, Log_Time, Log, Log, Logging, Logging, Lookup_Messenger, Messenger_Identities, Messenger_Link, Messenger_Quit, Messenger_Quit, Messenger_Unlink, NACK, Port, Report_Messenger_Connections, Report_Messenger_Connections, Report_Messengers, Route_To, Route, Run_Exception, run, Send, Send, Shutdown, Start_Messenger_Reporting, Start, Started, Status_Report, Stop_Messenger_Reporting`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, 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

#### STAGE_MANAGER_NAME

    public static final String STAGE_MANAGER_NAME

The name used by the base Dispatcher class for the Stage_Manager service.

See Also:
  `Dispatcher.Dispatcher_Name(String)`, Constant Field Values

#### CONDUCTOR_COMMAND_PARAMETER_NAME

    public static final String CONDUCTOR_COMMAND_PARAMETER_NAME

The name of the Configuration parameter that specifies the Conductor command name.

If this parameter is not present or its value is empty or "disabled" remote Conductor command execution is disabled.

See Also:
  Constant Field Values

#### MAX_START_CONDUCTORS_COUNT_PARAMETER_NAME

    public static final String MAX_START_CONDUCTORS_COUNT_PARAMETER_NAME

The name of the Configuration parameter that specifies the maximum number of remote Conductor commands that may be executed by a single request.

If the Count of remote commands exceeds this value no commands will be executed and an exception response will be sent in reply.

See Also:
  `CONDUCTOR_COMMAND_PARAMETER_NAME`, Constant Field Values

#### DEFAULT_MAX_START_CONDUCTORS_COUNT

    public static final int DEFAULT_MAX_START_CONDUCTORS_COUNT

The default maximum number of remote Conductor commands that may be executed by a single request.

See Also:
  `MAX_START_CONDUCTORS_COUNT_PARAMETER_NAME`, Constant Field Values

#### START_CONDUCTORS_ACTION

    public static final String START_CONDUCTORS_ACTION

See Also:
  Constant Field Values

#### COUNT_PARAMETER_NAME

    public static final String COUNT_PARAMETER_NAME

See Also:
  Constant Field Values

#### EXPLANATION_PARAMETER_NAME

    public static final String EXPLANATION_PARAMETER_NAME

See Also:
  Constant Field Values

#### COMMAND_PARAMETER_NAME

    public static final String COMMAND_PARAMETER_NAME

See Also:
  Constant Field Values

#### REPORT_PARAMETER_NAME

    public static final String REPORT_PARAMETER_NAME

See Also:
  Constant Field Values

#### EXCEPTION_PARAMETER_NAME

    public static final String EXCEPTION_PARAMETER_NAME

See Also:
  Constant Field Values

#### ASSISTANT_NAME

    public static final String ASSISTANT_NAME

See Also:
  Constant Field Values

### Constructor Detail

#### Stage_Manager

    public Stage_Manager(Configuration configuration,
                 int port)

Construct a Stage_Manager using a Configuration and port number.

The base `Dispatcher` class is constructed using the `STAGE_MANAGER_NAME` along with the specified Configuration and port number. The `Dispatcher.Dispatcher_ID` is set to the `ID` of this class.

Parameters:
  `configuration` - A Configuration. If null an attempt will be made to use a default configuration source.
  `port` - The communications port number. If less than or equal to zero a `Dispatcher.DEFAULT_PORT` number will be used.

#### Stage_Manager

    public Stage_Manager(Configuration configuration)

Construct a Stage_Manager using a Configuration.

The base Dispatcher class will provide a default communications port number.

Parameters:
  `configuration` - A Configuration. If null an attempt will be made to use a default configuration source.
See Also:
  `Stage_Manager(Configuration, int)`

#### Stage_Manager

    public Stage_Manager()

Construct a Stage_Manager.

Defaults will be provided for the Configuration source and communications port number.

See Also:
  `Stage_Manager(Configuration, int)`

### Method Detail

#### Configure

    protected void Configure(Configuration configuration)
                      throws Configuration_Exception,
                             SecurityException

Configures the Stage_Manager.

The Configuration class is set to use this class when using a class-relative search for a configuration source when a Configuration is not provided.

The base Dispatcher class is `configured` and then Stage_Manager specific parameters are obtained.

`CONDUCTOR_COMMAND_PARAMETER_NAME`
  The name of the Conductor command used for remote execution requests. For best security this should be an absolute pathname to the executable file used to run a Conductor. If not present, empty or set to "DISABLED" remote commend execution is disabled.
`MAX_START_CONDUCTORS_COUNT_PARAMETER_NAME`
  The maximum number of command executions allowed for each request. This is used to prevent accidental hordes of Conductors from being run. The default value is `DEFAULT_MAX_START_CONDUCTORS_COUNT`; the minimum value is 1.

N.B.: All parameters are sought in the `in the Configuration Group` with the `Stage_Manager name`.

Overrides:
  `Configure` in class `Dispatcher`
Parameters:
  `configuration` - The Configuration to use. If null and defatult configuration source will sought.
Throws:
  `Configuration_Exception` - If there was a problem parsing the configuration source, accessing its contents, or establishing a log file.
  `SecurityException` - If the connection authentication keys could not be generated, no `Dispatcher.PASSWORD_PARAMETER_NAME` was found but `Dispatcher.UNAUTHENTICATED_CONNECTIONS_ALLOWED` is false, or a log file could not be opened due to a security violation.

#### Message_Delivered

    public void Message_Delivered(Message_Delivered_Event event)

Description copied from class: `Dispatcher`
Receives delivery of a message.

This method implements the `Message_Delivered_Listener` interface.

The following `message actions` are recognized:

`Dispatcher.IDENTIFY_ACTION`
  Replies with the `identity Message`.
`Dispatcher.MESSENGERS_REPORT_ACTION`
  Replies with a list of `currently connected messenger identities` that have been selected by the request message.
`Dispatcher.START_MESSENGER_REPORTING_ACTION`
  `Starts connected Messenger reporting` for the requesting Messenger.
`Dispatcher.STOP_MESSENGER_REPORTING_ACTION`
  `Stops connected Messenger reporting` for the requesting Messenger.
`Dispatcher.LINK_MESSENGER_ACTION`
  Direct `Dispatcher.Messenger_Link(Messenger, Message)` Messenger-to-Messenger communication} is established between the requesting Messenger and another Messenger for which an address is provided.
`Dispatcher.UNLINK_MESSENGER_ACTION`
  Direct `Dispatcher.Messenger_Unlink(Messenger, Message)` Messenger-to-Messenger communication} is removed between the requesting Messenger and another Messenger for which an address is provided.
`Dispatcher.DONE_ACTION`
  The Messenger associated with this Message has `quit` and is to be disconnected.
`Dispatcher.UNDELIVERABLE_ACTION`
  A Message that was `sent` could not be delivered. The undeliverable Message is logged.
`Dispatcher.NACK_ACTION`
  A Message that was `sent` was rejected. The rejected Message is logged.

Any other messages are logged as unrecognized and a `NACK` is sent back to the Messenger from which the message was received.

Specified by:
  `Message_Delivered` in interface `Message_Delivered_Listener`
Overrides:
  `Message_Delivered` in class `Dispatcher`
Parameters:
  `event` - The `Message_Delivered_Event` containing the Message that was delivered and a reference to the Messenger that sent it.

#### main

    public static void main(String[] args)

#### Usage

    public static void Usage()