PIRL.Conductor

## Interface Management

All Known Implementing Classes:
  Conductor, Remote_Theater

    public interface Management

Management is the Conductor management interface.

The Conductor Management interface provides the ability to set and get various processing state and control information from a Conductor. It also provides registration control for processing state change event notifications and log stream writer attachment.

See Also:
  `Conductor`

### Method Summary

Methods
`Management` `Add_Log_Writer(Writer writer)` Register a Writer to receive processing log stream output.
`Management` `Add_Processing_Listener(Processing_Listener listener)` Register a processing state change listener.
`Configuration` `Configuration()` Get the Conductor Configuration.
`boolean` `Connected_to_Stage_Manager()` Test if the Conductor is connected to a Stage_Manager.
`Management` `Enable_Log_Writer(Writer writer, boolean enable)` Enable or disable output to a `registered log stream Writer`.
`Message` `Identity()` Get the Conductor `identity`.
`int` `Poll_Interval()` Get the interval at which the Conductor will poll for unprocessed source records.
`Management` `Poll_Interval(int seconds)` Set the interval at which the Conductor will poll for unprocessed source records.
`Vector<Vector<String>>` `Procedures()` Get the procedures table.
`Exception` `Processing_Exception()` Get the exception that caused Conductor processing to halt.
`int` `Processing_State()` Get the current Conductor processing state.
`void` `Quit()` Immediately stop Conductor processing and exit.
`boolean` `Remove_Log_Writer(Writer writer)` Unregister a log Writer.
`boolean` `Remove_Processing_Listener(Processing_Listener listener)` Unregister a processing state change listener.
`Management` `Reset_Sequential_Failures()` Reset the count of sequential source processing failures that the Conductor has accumulated.
`String` `Resolver_Default_Value()` Get the Conductor default Reference_Resolver value.
`Management` `Resolver_Default_Value(String value)` Set the Conductor default Reference_Resolver value.
`int` `Sequential_Failures()` Get the count of sequential source processing failures that the Conductor has accumulated.
`Vector<Vector<String>>` `Sources()` Get the current cache of source records.
`void` `Start()` Start Conductor source record processing.
`Processing_Changes` `State()` Get the current Conductor processing state variables.
`int` `Stop_on_Failure()` Get the number of Conductor sequential source processing failures at which to stop processing.
`Management` `Stop_on_Failure(int failure_count)` Set the number of Conductor sequential source processing failures at which to stop processing.
`void` `Stop()` Request that Conductor stop source record processing.

### Method Detail

#### Identity

    Message Identity()

Get the Conductor `identity`.

Returns:
  A Message containing the Conductor identification parameters.
See Also:
  `Conductor.Identity()`

#### Configuration

    Configuration Configuration()

Get the Conductor Configuration.

The Configuration that is returned is a copy of the current state of the Conductor Configuration, which is dynamically changed during processing. All parameters named "PASSWORD" (case insensitive) will have their values reset to `Processing_Changes.MASKED_PASSWORD`.

Returns:
  A copy of the Conductor Configuration.
See Also:
  `Conductor.Preconfigure(Configuration)`, `Conductor.Postconfigure(Configuration)`

#### Start

    void Start()

Start Conductor source record processing.

If the Conductor is in a negative `processing state` (`waiting` or `halted`) it will enter the `running` state, reconfigure itself from its Configuration source, and source record processing will commence. If the Conductor is in the `run-to-wait` state it will clear this to the running state; for any other positive state (running or `polling`) there will be no change.

See Also:
  `Conductor.Start()`

#### Stop

    void Stop()

Request that Conductor stop source record processing.

If the Conductor is in a positive `processing state` it will enter the `run-to-wait` state, in which it will enter the `waiting` state when the current source record completes processing. If the Conductor is in the `polling` state it will immediately stop polling for new source records. There will be no effect for any negative state.

See Also:
  `Conductor.Stop()`

#### Quit

    void Quit()

Immediately stop Conductor processing and exit.

Any open log file is closed. The database server is disconnected. An `exiting` processing event is sent to all `processing listeners`. The application exits with a `success status`.

N.B.: If source processing is `running` it is aborted.

See Also:
  `Conductor.Quit()`

#### Processing_State

    int Processing_State()

Get the current Conductor processing state.

The possible processing state values are:

`Conductor.RUNNING`
  Source records are being processing.
`Conductor.POLLING`
  No unprocessed source records are currently available for processing; the Conductor is `polling` for source records to process.
`Conductor.RUN_TO_WAIT`
  When processing of the current source record completes Conductor will go into the waiting state.
`Conductor.WAITING`
  The Conductor is waiting to be told to being processing.
`Conductor.HALTED`
  A problem condition caused the Conductor to halt processing. The problem may be the result of the maximum number of `sequential failures` of source record processing having occured, a database access failure, or some other `system error`.

The WAITING and HALTED state codes are negative; all others are positive.

Returns:
  A Conductor processing state code.

#### Sources

    Vector<Vector<String>> Sources()

Get the current cache of source records.

The table is expected to be delivered with the record fields in `Conductor.SOURCES_FIELD_NAMES` order, and with the records sorted by increasing `Conductor.SEQUENCE_FIELD` order.

N.B.: Only the contents of the Conductor source records cache is delivered. The contents of the database sources table may be much, much larger.

Returns:
  A table Vector of record Vectors of field Strings. The first record contains the field names.

#### Procedures

    Vector<Vector<String>> Procedures()

Get the procedures table.

The table is expected to be delivered with the record fields in `Conductor.PROCEDURES_FIELD_NAMES` order, and with the records in processing order.

N.B.: The entire contents of the database procedures table is delivered.

Returns:
  A table Vector of record Vectors of field Strings. The first record contains the field names.

#### State

    Processing_Changes State()

Get the current Conductor processing state variables.

All Processing_Changes values are set except the except the flag variables - `Processing_Changes.Sources_Refreshed(boolean)`, `Processing_Changes.Procedures_Changed(boolean)` and `Processing_Changes.Exiting(boolean)` - which will always be false.

Returns:
  Processing_Changes object.
See Also:
  `Processing_Changes`

#### Add_Processing_Listener

    Management Add_Processing_Listener(Processing_Listener listener)

Register a processing state change listener.

The Conductor sends its `processing event` notifications to all registered listeners.

Parameters:
  `listener` - A Processing_Listener.
Returns:
  This Management object.
See Also:
  `Processing_Listener`

#### Remove_Processing_Listener

    boolean Remove_Processing_Listener(Processing_Listener listener)

Unregister a processing state change listener.

Parameters:
  `listener` - The Processing_Listener to be removed from the Management list of registered listeners.
Returns:
  true If the listener was registered and is now removed; false if it was not registered.
See Also:
  `Add_Processing_Listener(Processing_Listener)`

#### Add_Log_Writer

    Management Add_Log_Writer(Writer writer)

Register a Writer to receive processing log stream output.

The Conductor writes its processing log reports, including the output from all pipeline procedures it runs, to all registered log Writers.

Parameters:
  `writer` - A Writer object.
Returns:
  This Management object.
See Also:
  `Enable_Log_Writer(Writer, boolean)`, `Remove_Log_Writer(Writer)`

#### Remove_Log_Writer

    boolean Remove_Log_Writer(Writer writer)

Unregister a log Writer.

Parameters:
  `writer` - A Writer object.
Returns:
  true If the writer was registered and is now removed; false if it was not registered.
See Also:
  `Add_Log_Writer(Writer)`

#### Enable_Log_Writer

    Management Enable_Log_Writer(Writer writer,
                               boolean enable)

Enable or disable output to a `registered log stream Writer`.

Parameters:
  `writer` - A Writer that has been registered to receive Conductor log stream output. If the writer is not `registered` to receive the Conductor log stream nothing is done.
  `enable` - If false, Conductor log stream output to the Writer is suspended without having to unregister the Writer. If true, a Writer that has had its log stream output suspended will begin receiving it again.
Returns:
  This Management object.

#### Poll_Interval

    Management Poll_Interval(int seconds)

Set the interval at which the Conductor will poll for unprocessed source records.

When the Conductor is in the polling `state` it will periodically check the database sources table for source records that are marked as unprocessed. Unprocessed source records are used to refresh the Conductor cache of source records to be processed. When all source records in the cache have been processed, the Conductor will enter the polling state if the poll interval is positive; it will enter the waiting state if the poll interval is not positive (as if the `stop request` had been issued), or will exit if it is not `connected to a Stage_Manager` at the time.

Parameters:
  `seconds` - The interval, in seconds, at which the Conductor will poll for unprocessed source records. If less than zero, zero will be set, but the value will be reset to the Conductor Configuration `Conductor.POLL_INTERVAL_PARAMETER` value or the `Conductor.DEFAULT_POLL_INTERVAL` value if the Configuration does contain the parameter, the next time the Conductor is `started` after having stopped processing for any reason.
Returns:
  This Management object.
See Also:
  `Conductor.Poll_Interval(int)`

#### Poll_Interval

    int Poll_Interval()

Get the interval at which the Conductor will poll for unprocessed source records.

This value may also be obtained from the `Configuration` `Conductor.POLL_INTERVAL_PARAMETER`.

Returns:
  The interval, in seconds, at which the Conductor will poll for unprocessed source records. If zero, polling has been disabled.
See Also:
  `Poll_Interval(int)`

#### Resolver_Default_Value

    Management Resolver_Default_Value(String value)

Set the Conductor default Reference_Resolver value.

Normally when the Conductor Reference_Resolver is unable to resolve a reference it will throw an `exception` and enter the halted `processing state`, or exit if it is not `connected to a Stage_Manager` at the time. If, however, the `Reference_Resolver default value` is set to a non-null String that value will be used for the unresolved_reference instead of throwing an exception.

Parameters:
  `value` - The default Reference_Resolver String value. If this starts with `Conductor.UNRESOLVED_REFERENCE_THROWS` (case insensitive) null will be used.
Returns:
  This Management object.
See Also:
  `Conductor.Resolver_Default_Value(String)`, `Reference_Resolver`

#### Resolver_Default_Value

    String Resolver_Default_Value()

Get the Conductor default Reference_Resolver value.

This value may also be obtained from the `Configuration` `Conductor.UNRESOLVED_REFERENCE_PARAMETER`. Note, however, that the value will be `Conductor.UNRESOLVED_REFERENCE_THROWS` when the actual value is null.

Returns:
  The default Reference_Resolver String value.
See Also:
  `Resolver_Default_Value(String)`

#### Stop_on_Failure

    Management Stop_on_Failure(int failure_count)

Set the number of Conductor sequential source processing failures at which to stop processing.

The Conductor keeps a `count of sequential source processing failures`. When this count reaches the stop-on-failure limit the Conductor will enter the halted `processing state` or exit if it is not `connected to a Stage_Manager` at the time.

N.B.: Reaching the stop-on-failure limit does not cause the sequential failures count to be `reset`.

Parameters:
  `failure_count` - The number of Conductor sequential source processing failures at which to stop processing. If zero sequential processing failures will never cause processing to stop. If negative the current value will not be changed, but the value will be reset to the Conductor Configuration `Conductor.STOP_ON_FAILURE_PARAMETER` value or the `Conductor.DEFAULT_STOP_ON_FAILURE` value if the Configuration does contain the parameter, the next time the Conductor is `started` after having stopped processing for any reason.
Returns:
  This Management object.
See Also:
  `Sequential_Failures()`, `Conductor.Stop_on_Failure(int)`

#### Stop_on_Failure

    int Stop_on_Failure()

Get the number of Conductor sequential source processing failures at which to stop processing.

This value may also be obtained from the `Configuration` `Conductor.STOP_ON_FAILURE_PARAMETER`

Returns:
  The number of Conductor sequential source processing failures at which to stop processing. If zero sequential processing failures will never cause processing to stop.
See Also:
  `Stop_on_Failure(int)`

#### Sequential_Failures

    int Sequential_Failures()

Get the count of sequential source processing failures that the Conductor has accumulated.

Other source processing success and failure counts may be obtained from the `Configuration`:

`Conductor.SOURCE_SUCCESS_COUNT`
  The total number of source records that have successfully completed all processing since the Conductor first began processing.
`Conductor.SOURCE_FAILURE_COUNT`
  The number of source records that have resulted in a failed procedure condition during processing.
`Conductor.TOTAL_FAILURE_COUNT`
  The total number of source records that failed to be processed for any reason since the Conductor first began processing.

Returns:
  The count of sequential source processing failures that the Conductor has accumulated.
See Also:
  `Stop_on_Failure(int)`, `Reset_Sequential_Failures()`

#### Reset_Sequential_Failures

    Management Reset_Sequential_Failures()

Reset the count of sequential source processing failures that the Conductor has accumulated.

If the Conductor is in the halted `processing state` it is reset to the waiting state.

Returns:
  This Management object.
See Also:
  `Stop_on_Failure(int)`, `Conductor.Reset_Sequential_Failures()`

#### Processing_Exception

    Exception Processing_Exception()

Get the exception that caused Conductor processing to halt.

N.B.: When Conductor processing is `started` the previous processing exception is cleared.

Returns:
  The Exception that caused processing to halt. This will be null if processing did not halt as the result of an exception, or the current processing state is not halted.

#### Connected_to_Stage_Manager

    boolean Connected_to_Stage_Manager()

Test if the Conductor is connected to a Stage_Manager.

Returns:
  true if the Conductor is connected to a Stage_Manager via an open Local_Theater; false otherwise.
See Also:
  `Local_Theater`