PIRL.Conductor.Maestro

## Class Conductor_Definition

- java.lang.Object
- - javax.swing.tree.DefaultMutableTreeNode
  - - PIRL.PVL.Parameter
    - - PIRL.Messenger.Message
      - - PIRL.Conductor.Maestro.Conductor_Definition

All Implemented Interfaces:
  Serializable, Cloneable, MutableTreeNode, TreeNode

    public class Conductor_Definition
    extends Message

A Conductor_Definition contains the information that defines a Conductor instance.

A Conductor_Definition encapsulates the information necessary to instantiate a Conductor object.

#### Definition Name

The `name` of the definition is used to refer to the entire definition.Typically this name is expected to be unique in a set of Conductor_Definition objects such that if refers to a combination of definition parameter values that does not `match` the combination of parameter values in any other Conductor_Definition object of the set.

#### Definition Parameters

A Conductor_Defintion may contain the following parameters:

`PIPELINE_PARAMETER_NAME`
  The pipeline name used by a Conductor instantiation. This parameter is required. If it is not present when the Conductor_Definition is constructed the parameter is provided using the definition name for its value.
`CONFIGURATION_PARAMETER_NAME`
  The source of the Configuration used by a Conductor instantiation. This parameter is required. If it is not present, or the alternative when the Conductor_Definition is constructed the parameter is provided using the value of the `CONFIGURATION_SOURCE_PARAMETER_NAME` or, if this is not present, the `DEFAULT_CONFIGURATION_FILENAME` for its value.
`SERVER_PARAMETER_NAME`
  The name of the database server access parameters group in the configuration file used by the Conductor instantiation. This parameter is optional. If it is not present the Conductor will use the parameter of the same name to choose the default database server group from the Configuration.
`CATALOG_PARAMETER_NAME`
  The name of the catalog in the database server where the pipeline tables are located. This parameter is optional. If it is not present the Conductor will the parameter of the same name from the Configuration.

See Also:
  `Conductor`, Serialized Form

### Field Summary

Fields
`static String` `ACTION_PARAMETER_NAME` The name of the parameter that specifies the `Start_Conductor_Message(boolean, int)` action.
`static String` `CATALOG_PARAMETER_NAME` The name of the parameter that specifies the database catalog containing the pipeline tables.
`static String` `CONFIGURATION_PARAMETER_NAME` The name of the parameter that specifies the Configuration source.
`static String` `CONFIGURATION_SOURCE_PARAMETER_NAME` The name of the parameter that specifies the Configuration source in a Conductor `Conductor.Identity()`.
`static String` `COUNT_PARAMETER_NAME` The name of the parameter used to specify the number of Conductor instances to run in a Stage_Manger `Start_Conductor_Message(boolean, int)`.
`static String` `DEFAULT_CONFIGURATION_FILENAME` The default Configuration source filename.
`static String` `ID` Class identification name with source code version and date.
`static String` `PIPELINE_PARAMETER_NAME` The name of the parameter that specifies the pipeline name.
`static String` `SERVER_PARAMETER_NAME` The name of the parameter that specifies the database server access information parameters group name in the `Configuration source`.
`static String` `START_CONDUCTORS_ACTION` The value of the `ACTION_PARAMETER_NAME` parameter.
`static String` `WAIT_TO_START_PARAMETER_NAME` The name of the parameter that is used to tell a Conductor instantiation to wait to start.

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

`ACK_ACTION, CLASS_ID_PARAMETER_NAME, CONTENT_AMOUNT_PARAMETER_NAME, DONE_ACTION, ERROR_MESSAGE_MARKER, IDENTIFY_ACTION, IDENTITY_ACTION, NACK_ACTION, NAME_PARAMETER_NAME, ROUTE_FROM_PARAMETER_NAME, ROUTE_TO_PARAMETER_NAME, START_MARKER, START_MARKER_DELIMITER, START_MARKER_END`

### Fields inherited from class PIRL.PVL.Parameter

`AGGREGATE, ASSIGNMENT, BEGIN_GROUP, BEGIN_OBJECT, END, END_AGGREGATE, END_GROUP, END_OBJECT, END_PVL, GROUP, HIGHEST_BIT, LOWEST_BIT, MASK, OBJECT, TOKEN, UNKNOWN`

### Fields inherited from class javax.swing.tree.DefaultMutableTreeNode

`allowsChildren, children, EMPTY_ENUMERATION, parent, userObject`

### Constructor Summary

Constructors
Constructor and Description
`Conductor_Definition(Message message)` Creates a Conductor_Definition from a Message.
`Conductor_Definition(Parameter parameter)` Creates a Conductor_Definition from a Parameter.
`Conductor_Definition(String pipeline)` Creates a Conductor_Definition from a pipeline name.

### Method Summary

Methods
`boolean` `Matches(Message message)` Test if a Conductor Definition Message matches this Conductor_Definition.
`Message` `Start_Conductor_Message(boolean wait_to_start, int count)` Generate a Message used by the Stage_Manager to instantiate a Conductor.
`Message` `Start_Conductor_Message(boolean wait_to_start, Integer count)` Generate a Message used by the Stage_Manager to instantiate a Conductor.
`void` `Validate()` Validate this Conductor_Definition.

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

`Action, Action, Add, Add, Clear_Route_From, Clear_Route_To, Content_Amount, Content_String, Content, Destination_Address, Done, From, From, Get, Identify, Identity, Identity, Matching, NACK, Packet_Label, Packet, Pop_From, Pop_To, PVL_Lister, PVL_Parser, PVL, Remove_All, Remove, Reply_To, Route_From_Count, Route_From, Route_From, Route_To_Count, Route_To, Route_To, Route_To, Routing, Set_Token, Set_Token, Set, Set, Set, Set, Set, Set, Set, Set, Source_Address, To, To, toString, Unescape, Valid_Route, Value_of_Matching, Value_of`

### Methods inherited from class PIRL.PVL.Parameter

`Absolute_Pathname, Absolute_Pathname, Add, add, Add, adopt, Basename, Classification_Name, Classification_Name, Classification, Classification, Classification, clone, Comments, Comments, Data, Data, Data, Description, Description, equals, equalsIgnoreCase, Find, Find, Find, Find, Find, Find, Find, Find, Find, Find, Find, Find, First_Warning, First_Warning, graft, Has_List, Has_Value, Insert, insert, Insert, Is_Absolute_Pathname, Is_Aggregate, Is_Aggregate, Is_Assignment, Is_Assignment, Is_Begin_Aggregate, Is_Begin_Aggregate, Is_Begin_Group, Is_Begin_Group, Is_Begin_Object, Is_Begin_Object, Is_Empty, Is_End_Aggregate, Is_End_Aggregate, Is_End_Group, Is_End_Group, Is_End_Object, Is_End_Object, Is_End_PVL, Is_End_PVL, Is_End, Is_End, Is_Group, Is_Group, Is_Object, Is_Object, Is_Parameter_List, Is_Parameter_Value, Is_Parameter, Is_Token, Is_Token, Is_Unknown, Is_Unknown, iterator, iterator, Last_Warning, Last_Warning, List_Size, List, List, listIterator, listIterator, Match_Depth, Match, Name, Name, orphan, Parent_Pathname, Parent, Path_Delimiter, Path_Delimiter, Path_from, Path_Name, Path_to_Name, Remove_All, remove, Remove, remove, Remove, Reset_Warning, set_classification, set_data, setAllowsChildren, setUserObject, Value, Value, Value, Value, Value, Value, Value, Value, Value, Warning, Write, Write, Write, Write, Write, Write, Write, Write`

### Methods inherited from class javax.swing.tree.DefaultMutableTreeNode

`breadthFirstEnumeration, children, depthFirstEnumeration, getAllowsChildren, getChildAfter, getChildAt, getChildBefore, getChildCount, getDepth, getFirstChild, getFirstLeaf, getIndex, getLastChild, getLastLeaf, getLeafCount, getLevel, getNextLeaf, getNextNode, getNextSibling, getParent, getPath, getPathToRoot, getPreviousLeaf, getPreviousNode, getPreviousSibling, getRoot, getSharedAncestor, getSiblingCount, getUserObject, getUserObjectPath, isLeaf, isNodeAncestor, isNodeChild, isNodeDescendant, isNodeRelated, isNodeSibling, isRoot, pathFromAncestorEnumeration, postorderEnumeration, preorderEnumeration, removeAllChildren, removeFromParent, setParent`

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

`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

#### PIPELINE_PARAMETER_NAME

    public static final String PIPELINE_PARAMETER_NAME

The name of the parameter that specifies the pipeline name.

See Also:
  Constant Field Values

#### CONFIGURATION_PARAMETER_NAME

    public static final String CONFIGURATION_PARAMETER_NAME

The name of the parameter that specifies the Configuration source.

See Also:
  `CONFIGURATION_SOURCE_PARAMETER_NAME`, Constant Field Values

#### CONFIGURATION_SOURCE_PARAMETER_NAME

    public static final String CONFIGURATION_SOURCE_PARAMETER_NAME

The name of the parameter that specifies the Configuration source in a Conductor `Conductor.Identity()`.

See Also:
  `CONFIGURATION_PARAMETER_NAME`, Constant Field Values

#### DEFAULT_CONFIGURATION_FILENAME

    public static final String DEFAULT_CONFIGURATION_FILENAME

The default Configuration source filename.

See Also:
  Constant Field Values

#### SERVER_PARAMETER_NAME

    public static final String SERVER_PARAMETER_NAME

The name of the parameter that specifies the database server access information parameters group name in the `Configuration source`.

See Also:
  Constant Field Values

#### CATALOG_PARAMETER_NAME

    public static final String CATALOG_PARAMETER_NAME

The name of the parameter that specifies the database catalog containing the pipeline tables.

See Also:
  Constant Field Values

#### ACTION_PARAMETER_NAME

    public static final String ACTION_PARAMETER_NAME

The name of the parameter that specifies the `Start_Conductor_Message(boolean, int)` action.

See Also:
  Constant Field Values

#### START_CONDUCTORS_ACTION

    public static final String START_CONDUCTORS_ACTION

The value of the `ACTION_PARAMETER_NAME` parameter.

See Also:
  Constant Field Values

#### WAIT_TO_START_PARAMETER_NAME

    public static final String WAIT_TO_START_PARAMETER_NAME

The name of the parameter that is used to tell a Conductor instantiation to wait to start.

The Conductor will remain in the `Conductor.WAITING`.processing state if this parameter is included in the Conductor_Definition; otherwise it will immediately enter the `Conductor.RUNNING` processing state.

See Also:
  Constant Field Values

#### COUNT_PARAMETER_NAME

    public static final String COUNT_PARAMETER_NAME

The name of the parameter used to specify the number of Conductor instances to run in a Stage_Manger `Start_Conductor_Message(boolean, int)`.

N.B.: This parameter is not a Conductor command line option.

See Also:
  Constant Field Values

### Constructor Detail

#### Conductor_Definition

    public Conductor_Definition(Message message)
                         throws PVL_Exception,
                                IllegalArgumentException

Creates a Conductor_Definition from a Message.

The Message parameters and name are copied and then the contents are `validated`.

Parameters:
  `message` - A Message containg Conductor definition parameters.
Throws:
  `PVL_Exception` - If the definition could not be copied into this object and `validated`.
  `IllegalArgumentException` - If the Message content does not produce a `valid` Conductor_Definition.

#### Conductor_Definition

    public Conductor_Definition(Parameter parameter)
                         throws PVL_Exception,
                                IllegalArgumentException

Creates a Conductor_Definition from a Parameter.

If the Parameter is an Assignment it becomes the sole Parameter in this Message. If it is an Aggregate its Parameter list becomes the list of Parameters in this Message and its `name` becomes the name of this Message.

The contents of the new Conductor_Definition are `validated`.

Throws:
  `PVL_Exception` - If the Parameter could not be copied into this object and `validated`.
  `IllegalArgumentException` - If the Parameter content does not produce a `valid` Conductor definition.

#### Conductor_Definition

    public Conductor_Definition(String pipeline)
                         throws IllegalArgumentException

Creates a Conductor_Definition from a pipeline name.

The resulting definition will have its `name` and `PIPELINE_PARAMETER_NAME` parameter value set to the pipeline name. The `CONFIGURATION_PARAMETER_NAME` will be set with the `DEFAULT_CONFIGURATION_FILENAME` value. No other parameters will be present.

Parameters:
  `pipeline` - The name of the Conductor pipeline.
Throws:
  `IllegalArgumentException` - If the pipeline name is null, empty or the special `Parser.CONTAINER_NAME`.

### Method Detail

#### Matches

    public boolean Matches(Message message)

Test if a Conductor Definition Message matches this Conductor_Definition.

The match criteria are:

If the `PIPELINE_PARAMETER_NAME` parameter is present in the message its value must match the value of the same parameter in this Conductor_Definition. If it is not present in the message the message `name` must match the parameter value in this Conductor_Definition. The Conductor_Definition will always contain this parameter; the Message must either contain the parameter with the same value or be named the same.

If the `CONFIGURATION_PARAMETER_NAME` or `CONFIGURATION_SOURCE_PARAMETER_NAME` parameter is present in the message its value must match the value of the same parameter in this Conductor_Definition. If it is not present in the message the parameter value in this Conductor_Definition must be `DEFAULT_CONFIGURATION_FILENAME`. The Conductor_Definition will always contain this parameter; it is optional for the Message.

If the `SERVER_PARAMETER_NAME` parameter is present in the message the same parameter must be present in this Conductor_Definition with the same value. If the parameter is not present in the message it must not be present in this Conductor_Definition. This parameter is optional for both the Conductor_Definition and the Message.

If the `CATALOG_PARAMETER_NAME` parameter is present in the message the same parameter must be present in this Conductor_Definition with the same value. If the parameter is not present in the message it must not be present in this Conductor_Definition. This parameter is optional for both the Conductor_Definition and the Message.

N.B.: The `name` of the Message does not need to match the name of this Conductor_Definition. Also, the Message may contain additional parameters other than those used to determine the match; the match is only against the Conductor_Definition parameters.

Parameters:
  `message` - A Message. If null, false is returned.
Returns:
  true if the Message contains a Conductor definition that logically matches this Conductor_Definition.

#### Start_Conductor_Message

    public Message Start_Conductor_Message(boolean wait_to_start,
                                  int count)
                                    throws IllegalArgumentException,
                                           PVL_Exception

Generate a Message used by the Stage_Manager to instantiate a Conductor.

A `validated` copy of this Conductor_Definition is filtered for use as a Stage_Manager Conductor start request Message.

The Conductor_Definition must contain a `PIPELINE_PARAMETER_NAME` parameter. The new Message will have an `ACTION_PARAMETER_NAME` set to `START_CONDUCTORS_ACTION`.

Parameters:
  `wait_to_start` - If true a `WAIT_TO_START_PARAMETER_NAME` token parameter will be included in the returned Message.
  `count` - If the value of this integer is greater than 1 a `COUNT_PARAMETER_NAME` parameter having the count value will be included in the returned Message.
Returns:
  A Message suitable for use as a Stage_Manager Conductor start request message.
Throws:
  `IllegalArgumentException` - If this Conductor_Description is not `valid`.
  `PVL_Exception` - If this Conductor_Definition could not be copied into a new Message.

#### Start_Conductor_Message

    public Message Start_Conductor_Message(boolean wait_to_start,
                                  Integer count)
                                    throws PVL_Exception,
                                           IllegalArgumentException

Generate a Message used by the Stage_Manager to instantiate a Conductor.

This is a convenience interface to the `Start_Conductor_Message(boolean, int)` method.

Parameters:
  `wait_to_start` - If true a `WAIT_TO_START_PARAMETER_NAME` token parameter will be included in the returned Message.
  `count` - If the value of this Integer is greater than 1 a `COUNT_PARAMETER_NAME` parameter having the count value will be included in the returned Message.
Returns:
  A Message suitable for use as a Stage_Manager Conductor start request message.
Throws:
  `PVL_Exception` - If this Conductor_Definition could not be copied into a new Message.
  `IllegalArgumentException` - If this Conductor_Description does not contain a `PIPELINE_PARAMETER_NAME` parameter.
See Also:
  `Start_Conductor_Message(boolean, int)`

#### Validate

    public void Validate()
                  throws IllegalArgumentException

Validate this Conductor_Definition.

The values of all Conductor definition parameters are obtained and checked for definition rule violations:

Each Conductor_Definition parameter, if present, must have a non-empty value.

If the `PIPELINE_PARAMETER_NAME` parameter is not present the `name` of the definition must not be the `Parser.CONTAINER_NAME` or empty. The default value for this required parameter is the name of the definition so the name must be valid if the parameter is not present.

All of the current parameters are then removed and the Conductor definition parameters are set to appropriate values:

If the `PIPELINE_PARAMETER_NAME` parameter was not present it is set to the definition name; the default value for this required parameter is the name of the definition. If the parameter was present and the name of the defintion is the `Parser.CONTAINER_NAME` or empty the definition name is set to the value of the parameter. This parameter will be the first entry in the Conductor_Definition.

If neither the `CONFIGURATION_PARAMETER_NAME` parameter nor `CONFIGURATION_SOURCE_PARAMETER_NAME` parameter was present the `CONFIGURATION_PARAMETER_NAME` parameter is set to the `DEFAULT_CONFIGURATION_FILENAME`. This parameter will be the third entry in the Conductor_Definition.

If the `SERVER_PARAMETER_NAME` and `CATALOG_PARAMETER_NAME` parameters were present they are restored. They are not entered if they were not originally present.

N.B.: Any other parameters are not relevant to a Conductor_Definition and so are removed.

Throws:
  `IllegalArgumentException` - If the `PIPELINE_PARAMETER_NAME` parameter isn't present and the `name` of the definition is the `Parser.CONTAINER_NAME`.