: a single multi-entry
Theater definition must be contained in in an Array to distinguish it
from a list of Theater locations; this results in doubled parentheses
(or curly braces) around the single definition.
Each Theater definition in the Profile is guaranteed to have a unique
combination of Theater location and Conductor name values. In a user
supplied Profile Configuration file, however, a Theater location and
Conductor name combination may occur in more than one Theater
definition. The Count of each duplicate location/name combination is
added to the Count of the initial definition. That is, Theater
definitions read from Configuration files are accumulated into a
consolidated list of unique definitions.
If a Conductor Theater definition with only a location entry is
duplicated, the duplicates are ignored. However, a definition with
the same location but that also contains a Conductor name causes the
location-only definition to be ignored.
A Theaters parameter in a user supplied Profile Configuration file
may occur at the top level of the file or within Conductor
definitions. A Theater definition within a Conductor definition must
not contain a Conductor name since this is implicitly the name of the
containing Conductor definition.
Example Profile Configuration Theater definitions:
# Single Theater location.
Theaters = host
Theaters = host:1234
Theaters = (host)
# Multiple Theater locations.
Theaters = (host_1, host_2, host_3, host_3:1234)
# Single Theater definition.
Theaters = ((host, name, 1))
Theaters = ((host, name))
# Multiple Theater definitions.
Theaters = ((host_1, name), (host_2, name, 2), (host_3, name_3, 3))
Theaters =
(
host_1:1234,
(host_2:1234, name),
(host_3:1234, name_3, 3)
)
Conductor definitions
A Conductor definition is an Aggregate (Group or Object) Parameter
that specifies the command line arguments used to instantiate a
Conductor at a Theater location. The name of the Aggregate is the
Conductor name used in a Theater definition. All Parameter Aggregates
in a Profile Configuration are taken to be Conductor definitions. The
parameters contained in a Conductor definition are all Assignments
with String values (except the Theaters parameter) and are all
optional:
- Pipeline
- The name of the Pipeline to be managed by the Conductor.
If this parameter is not present it will be provided with the value
being the Conductor definition name.
- Configuration
- The source of the Conductor Configuration file to be used by the
Conductor. This may be a filesystem pathname or a URL. N.B.: A
pathname is for the filesystem on the Theater host. A relative
pathname is relative to the working directory of the Stage_Manager
used to run the Conductor. In general, absolute pathnames may be
preferrable to avoid the uncertainty of relative pathnames.
If this parameter is not present the instantiated Conductor will use
its default Configuration source, which is expected to be the
"Conductor.conf" pathname.
- Server
- The name of the Configuration Server that specifies the name of the
Configuration parameters group containing database server access
information to be used by the Conductor.
If this parameter is not present the instantiated Conductor will use
the first entry in the Configuration Server parameter list.
- Catalog
- The name of the Database Catalog on the selected database server
that contains the pipeline Sources and Procedures definitions.
If this parameter is not present the instantiated Conductor will use
the Catalog prefix of the Pipeline (catalog.pipeline) if present;
otherwise it will use the value of the "Catalog" name from the
Configuration Server parameter group, or the default "Catalog"
parameter in the Configuration.
- Theaters
- A Theater definition list. : The definitions in this list
must not contain a Conductor name since this is implicitly the
name of the Conductor definition.
A Profile may contain zero or more Conductor definitions. It is not
necessary that all Conductor definitions be referenced by a Conductor
name in a Theater definition. Any Conductor name in a Theater definition
for which a Conductor definition has not been provided will be satisfied
by a generic Conductor definition as if an emtpy group with the
Conductor name had been provided.
All Conductor definitions will be unique; Conductor definitions with
the same definition parameters must have different names. N.B.:
A Profile Configuration file should contain only one Conductor definition
Group (or Object) having a given name because when the Configuration is
ingested Groups with the same name will have their parameter contents
coalesced into a single Group; duplicate parameters names that are
encountered will result in an exception being thrown.
Example Profile Configuration Conductor definitions:
# A generic Conductor definition.
Group = name
End_Group
# Simple Conductor definitions.
Group = name
Pipeline = pipeline
End_Group
Group = name_1
Pipeline = pipeline
Configuration = config_pathname_1
End_Group
Group = name_2
Pipeline = pipeline_2
Configuration = config_pathname_2
End_Group
# Complete Conductor definition.
Group = name
Pipeline = pipeline
Configuration = /an/absolute/pathname
Server = server_name
Catalog = catalog_name
End_Group
# Conductor definition with Theater definitions.
Group = pipeline
Theaters = ((host_1), (host2, 2), (host_3, 3))
Configuration = http://config.host/pathname/to/file
End_Group
A Profile Configuration may be managed as separate files by taking
advantage of the "@Include" capability of a Configuration. For
example, sets of "standard" Conductor definitions may be maintained
in files separate from various files that contain Theater
definitions and "@Include" one or more of the standard Conductor
definition sets:
# Theater definitions.
Theaters =
(
# Using standard Conductor definitions.
(host_1, standard_1),
(host_2, standard_2),
# Using special processing Conductor definitions.
(host_1, special_1),
(host_2, special_2)
# Custom Conductor definitions.
(host_1, custom_1),
# Local Conductor definition.
(host_2, local, 3)
)
# Standard Conductor definitions.
@Include = /Conductor/definitions/repository/Standard.defs
# Special processing Conductor definitions.
@Include = /Conductor/definitions/repository/Special_Processing.defs
# Custom Conductor definitions.
@Include = Custom_Conductor.defs
# Local Conductor definition.
Group = local
Configuration = /an/absolute/pathname
End_Group
In this example the included files may have many Conductor
definitions, most of which are not used in any particular Theaters
Theater definitions list.
"@Include" may also be used to provide common parts of various
Coductor definitions by putting it inside the appropriate
Conductor definitions.
Profiles are used by the Kapellmeister application.
- Version:
- 1.35
- Author:
- Michael Wendell and Bradford Castalia, UA/HiROC
ID
public static final String ID
- Class identification name with source code version and date.
- See Also:
- Constant Field Values
PROFILE_NAME
public static final String PROFILE_NAME
- The name of a Profile
Configuration.
- See Also:
- Constant Field Values
THEATERS_PARAMETER_NAME
public static final String THEATERS_PARAMETER_NAME
- The Profile Configuration parameter name for a list of Theater
definitions.
- See Also:
- Constant Field Values
THEATER_DEFINITION_SIZE
public static final int THEATER_DEFINITION_SIZE
- The size of a complete Theater definition Vector.
- See Also:
- Constant Field Values
THEATER_LOCATION_INDEX
public static final int THEATER_LOCATION_INDEX
- The index of the Theater location String in a theater definition Vector.
- See Also:
- Constant Field Values
CONDUCTOR_NAME_INDEX
public static final int CONDUCTOR_NAME_INDEX
- The index of the Conductor name String or Conductor_Definition
in a theater definition Vector.
- See Also:
- Constant Field Values
CONDUCTOR_COUNT_INDEX
public static final int CONDUCTOR_COUNT_INDEX
- The index of the Conductor count Integer in a theater definition Vector.
- See Also:
- Constant Field Values
NO_CONDUCTOR_DEFINITION
public static final String NO_CONDUCTOR_DEFINITION
- Theater Conductor name entry when no Conductor_Definition is provided.
PIPELINE_PARAMETER_NAME
public static final String PIPELINE_PARAMETER_NAME
- The name of the Conductor definition parameter that specifies the
pipeline to be processed.
- See Also:
- Constant Field Values
Profile
public Profile(String source)
throws Configuration_Exception,
PVL_Exception
- Construct a Profile from a source Configuration file.
Any parameters remaining after the source has been read will be held in the unprocessed source Configuration.
- Parameters:
source - A Configuration source String. This may be a file
pathname or a URL.
- Throws:
Configuration_Exception - If there was a problem with the source
Configuration syntax.
PVL_Exception
Profile
public Profile(List<List<Object>> theater_definitions,
List<Conductor_Definition> conductor_definitions)
throws IllegalArgumentException
- Construct a Profile from Theater and Conductor definitions.
- Parameters:
theater_definitions - A List of Theater definitions.conductor_definitions - A List of Conductor_Definitions.
- Throws:
IllegalArgumentException - If there was a problem creating the
Profile.- See Also:
Add(List, List)
Profile
public Profile()
- Construct an empty Profile.
Read
public Profile Read(String source)
throws Configuration_Exception
- Read Theater and Conductor definitions from a Configuration source file.
Theater and Conductor definitions found in the Configuration are
added to the definitions currently in this Profile.
- Parameters:
source - A Configuration source String. This may be a file
pathname or a URL.
- Returns:
- This Profile.
- Throws:
Configuration_Exception - If the source can not be found or parsed
as valid PVL or the contents do not conform to valid Profile
syntax.- See Also:
Read(Configuration)
Read
public Profile Read(Configuration configuration)
throws Configuration_Exception
- Read Theater and Conductor definitions from a Configuration.
Theater and Conductor definitions found in the Configuration are
added to the definitions currently in this Profile. Only THEATERS_PARAMETER_NAME Assignment parameters are used as Theater
definitions. All Aggregate parameters are taken to be Conductor
definitions.
N.B.: The Theater and Conductor definitions found in the
Configuration are removed from the Configuration leaving only the
unprocessed source parameters
in the original Configuration.
- Parameters:
configuration - A Configuration. If null nothing is done.
- Returns:
- This Profile.
- Throws:
Configuration_Exception - If the Configuration Theater or
Conductor definition contents do not conform to valid Profile
syntax.
Unprocessed_Source_Parameters
public Configuration Unprocessed_Source_Parameters()
- Get unprocessed Configuration parameters.
- Returns:
- A Configuration containing any parameters remaining after a
Configuration source was
read. This
will be null if there were no unprocessed parameters.
Write
public Profile Write(String pathname)
throws Configuration_Exception,
IOException
- Write the Profile to a
Configuration file.
If the Profile is empty nothing is written.
- Parameters:
pathname - The file pathname String. If null or empty
nothing is done.
- Returns:
- This Profile.
- Throws:
Configuration_Exception - If there was a problem creating a
Configuration for this Profile.
IOException - If there was a problem writing the file.- See Also:
Write(OutputStream)
Write
public Profile Write(OutputStream output_stream)
throws Configuration_Exception,
IOException
- Write the Profile to an OutputStream.
A configuration is created from the current
Profile contents and this is written to the OutputStream.
If the Profile is empty nothing is written.
- Parameters:
output_stream - An OutputStream where the Profile Configuration
is to be written. If null nothing is done.
- Returns:
- This Profile.
- Throws:
Configuration_Exception - If there was a problem creating a
Configuration for this Profile.
IOException - If there was a problem writing the file.
Configuration
public Configuration Configuration()
throws Configuration_Exception
- Get the Profile as a Configuration.
- Returns:
- A Configuration containing the Profile definition parameters.
The
Name of the Configuration will
be the PROFILE_NAME.
- Throws:
Configuration_Exception - If there was a problem creating the
Configuration
toString
public String toString()
- Get a PVL description of the Profile.
The current contents of the Profile are converted to a Configuration from which a PVL description is obtained.
- Overrides:
toString in class Object
- Returns:
- A PVL String description of the Profile. This will be null
if the
Configuration description
could not be generated.
Add
public Profile Add(List<List<Object>> theater_definitions,
List<Conductor_Definition> conductor_definitions)
throws IllegalArgumentException
- Adds Theater and Conductor definitions to the Profile.
- Parameters:
theater_definitions - A List of Theater definitions.conductor_definitions - A List of Conductor_Definitions.
- Throws:
IllegalArgumentException - If the arguments are not one
List of valid Theater definitions and one List of valid
Conductor_Definitions.
Add
public Profile Add(String theater_location,
Message conductor_definition)
throws IllegalArgumentException
- Add a Conductor_Definition associated with a Theater Location.
The Theater definition will have as a Conductor name the
Conductor name
obtained from the Conductor definition, and it will have a Conductor
count of 1.
- Parameters:
theater_location - A Theater location String. If null or
empty nothing is done.conductor_definition - A Conductor definition Message. If null
nothing is done.
- Returns:
- This Profile.
- Throws:
IllegalArgumentException - If the Conductor definition
conflicts with an existing definition.- See Also:
Add_Theater_Definition(String),
Add_Conductor_Definition(Message)
Add_Theater_Definitions
public Profile Add_Theater_Definitions(List<List<Object>> theater_definitions)
throws IllegalArgumentException
- Add a list of Theater definitions to the Profile.
- Parameters:
theater_definitions - A List containing Theater definitions. If
null or empty nothing is done.
- Returns:
- This Profile.
- Throws:
IllegalArgumentException - If any Theater definition in the
theater_definitions is not valid.- See Also:
Add_Theater_Definition(List)
Add_Theater_Definition
public Profile Add_Theater_Definition(List<Object> theater_definition)
throws IllegalArgumentException
- Add a Theater definition to the Profile.
The theater definition is first validated. It is then copied and
added to the Profile.
- Parameters:
theater_definition - A List containing a Theater definition.
If null or empty nothing is done.
- Returns:
- This Profile.
- Throws:
IllegalArgumentException - If the theater_definition is not
valid.
Add_Theater_Definition
public Profile Add_Theater_Definition(String theater_location)
- Add a general Theater definition.
A general Theater definition has a Theater location but no Conductor
name (this will be null) or count (this will be zero).
Adding a general Theater definition for a location that already has
a Theater definition in the Profile will have no effect; a general
definition does not override a specific definition.
- Parameters:
theater_location - A Theater location String. If this is null
or empty nothing will be done.
- Returns:
- This Profile.
Validate_Theater_Definition
public static void Validate_Theater_Definition(List<Object> theater_definition)
throws IllegalArgumentException
- Validate a Theater definition.
A valid Theater definition Vector contains three entries:
- Theater Location
- The Theater location String is in the form:
host[:port]
The host may be a hostname, short or fully qualified, or IP
address. The optional port is the system port number used to
connect to the Stage_Manager.
- Conductor Name
- The Conductor name String is the name of a
Conductor_Definition in the Profile.
This may be null to indicate that the Conductors on the Theater are
to be used as-is ("discovered").
- Conductor Count
- The Conductor count Integer specifies the number of Conductors as
defined by the Conductor_Defintiion having the Conductor name that
are to be run on the Theater.
The Theater location must always be the first entry in the definition.
The Conductor name and count need not be in that order. N.B.:
If the Conductor name and count are not in that order their order in
the Vector will be swapped.
- Parameters:
theater_definition - A List containing a Theater definition.
- Throws:
IllegalArgumentException - If the theater_definition is invalid.
Validate_Theater_Definitions
public static void Validate_Theater_Definitions(List<List<Object>> theater_definitions)
throws IllegalArgumentException
- Validate a Theater definitions list.
- Parameters:
theater_definitions - The List that is to be validated. If null
or empty nothing is validated.
- Throws:
IllegalArgumentException - If a theater_definitions entry
is invalid.- See Also:
Validate_Theater_Definition(List)
Theater_Definition
public Vector<Object> Theater_Definition(int index)
- Get a Theater definition at its Profile index.
- Parameters:
index - A Profile Theater definition index.
- Returns:
- A reference to the Theater definition Vector in this
Profile; the definition is not copied. This will be null if the
index is invalid.
Next_Theater_Index
public int Next_Theater_Index(String theater_location,
int index)
- Get the Profile index of the next Theater definition for a Theater
location starting after a given index.
Starting at the Profile index immediately following the specified
index, the index of the next Theater definition for the specified
location is returned.
- Parameters:
theater_location - A Theater location String.index - The Profile index after which the search for the
next Theater definition for the the location will begin.
If less than zero the search begins with the first definition.
- Returns:
- The Profile index of the next Theater definition that
contains a matching location, or -1 if no match is found or the
theater location is null or the empty String.
- See Also:
Theater_Definition(int)
Theater_Definitions
public Vector<Vector<Object>> Theater_Definitions()
- Get the list of Theater definitions.
- Returns:
- A Vector containing a copy of the Theater definitions list
in this Profile.
Theater_Definition
public Vector<Object> Theater_Definition(String theater_location,
String conductor_name)
- Get the Theater definition for a Theater location and Conductor name.
- Parameters:
theater_location - A Theater location String. If null, null
is returned.conductor_name - A Conductor name. If null, null is
returned.
- Returns:
- A Theater definition Vector. N.B.: This is a reference
to the definition in the Profile; copy first if it is to be
modified. This will be null if the matching Theater definition
could not be found.
Canonical_Theater_Definitions
public Vector<Vector<Object>> Canonical_Theater_Definitions()
- Get the canonical Theater definitions list.
N.B.: The CONDUCTOR_NAME_INDEX entry in the
definition Vector will be the full Conductor_Definition, not just its
name. This will be null if the definition for the Theater does not
specify any Conductors.
- Returns:
- A Vector containing of all the Theater definitions in the
Profile. N.B.: The Conductor_Definitions in the Theater
definition Vectors will be references to the objects in
the Profile, not copies.
Contains_Theater_Definition
public boolean Contains_Theater_Definition(String theater_location)
- Test if any Theater definition for a location is present in this Profile.
- Parameters:
theater_location - A Theater location String. If null or empty
false is returned.
- Returns:
- true if at least one Theater defifinition for the theater_location
is present in this Profile; false otherwise.
Theater_Definition_Index
public static int Theater_Definition_Index(List theater_definitions,
String theater_location,
String conductor_name)
- Get the index of a Theater definition for a Theater location and
Conductor name in a Vector of Theater definitions.
- Parameters:
theater_definitions - A Vector of Theater definitions. If null
or empty -1 is returned. N.B.: This must be a
valid Theater definitions
list.theater_location - A Theater location String. If null or
empty -1 is returned.conductor_name - A Conductor name String. May be null.
- Returns:
- The index of the Theater definition in the theater_definitions.
This will be -1 if a Theater definition with the theater_location
and conductor_name could not be found.
Total_Theater_Definitions
public int Total_Theater_Definitions()
- Get the number of Theater definitions in the Profile.
- Returns:
- The number of Theater definitions in the Profile.
Remove_Theater_Definition
public Vector<Object> Remove_Theater_Definition(String theater_location,
String conductor_name)
- Remove a Theater definition from the Profile for a Theater location
and Conductor name.
- Parameters:
theater_location - A Theater location String. If null or
empty null will be returned.conductor_name - A Conductor name String. May be null.
- Returns:
- The Theater definition Vector that was removed from the Profile.
This will be null if a matching definition could not be found.
Remove_Theater_Definition
public Vector<Object> Remove_Theater_Definition(int index)
- Removes a Theater definition at a
Theater_Definitions() index.
- Parameters:
index - The index of a Theater definition in this Profile.
- Returns:
- The Theater definition Vector that was removed from the Profile.
This will be null if index is not valid.
Clear_Theater_Definitions
public Profile Clear_Theater_Definitions()
- Clear the Theater definitions list.
- Returns:
- This Profile.
Add_Conductor_Definitions
public Profile Add_Conductor_Definitions(List<Conductor_Definition> conductor_definitions)
throws IllegalArgumentException
- Add Conductor_Definitions to the Profile.
- Parameters:
conductor_definitions - A List of Conductor_Definitions.
- Returns:
- This Profile.
- Throws:
IllegalArgumentException - If a definition conflicts with an
existing definition of the same name.- See Also:
Add_Conductor_Definition(Message)
Add_Conductor_Definition
public Profile Add_Conductor_Definition(Message message)
throws IllegalArgumentException
- Adds a Conductor definition from a Message.
- Parameters:
message - A Message containing a Conductor definition to be
added to this Profile.
- Returns:
- This Profile.
- Throws:
IllegalArgumentException - If the Message does not contain a
valid Conductor definition or contains a conflicting definition
with a definition of the same name already in the Profile.
Contains_Conductor_Definition
public boolean Contains_Conductor_Definition(Message message)
- Test if this Profile contains a Conductor_Definition matching a Message.
Each Conductor_Definition contained in this Profile is compared
against the contents of the Message for a matching definition. N.B.:
The name of the Message does not need to match the name of a
Conductor_Definition, only the contents must logically match.
- Parameters:
message - A Message. If null false is returned.
- Returns:
- true if this Profile contains a Conductor_Definition that
logically matches the Message contents; false if no match is
found.
Conductor_Definitions
public Vector<Conductor_Definition> Conductor_Definitions()
- Get the list of Conductor_Definitions.
- Returns:
- A Vector of Conductor_Definitions. This is a copy of the
Conductor definitions list contained in this Profile.
Conductor_Definition_Index
public static int Conductor_Definition_Index(List<Conductor_Definition> conductor_definitions,
String conductor_name)
- Get a Conductor_Definition index from a list of Conductor_Definition
objects using its name.
- Parameters:
conductor_definitions - A List of Conductor_Definition objects.conductor_name - The Conductor_Definition name.
- Returns:
- The index of the definition in the Conductor_Definitions Vector.
Conductor_Definition
public Conductor_Definition Conductor_Definition(String conductor_name)
- Get the Conductor_Definition for a Conductor name.
- Parameters:
conductor_name - A Conductor_Definition name String. If null,
null is returned.
- Returns:
- The Conductor_Definition in the Profile (not a copy) having
the conductor_name. This will be null if a Conductor_Definition
with the conductor_name could not be found.
Total_Conductor_Definitions
public int Total_Conductor_Definitions()
- Get the number of Conductor_Definitions in the Profile.
- Returns:
- The number of Conductor_Definitions in the Profile.
Remove_Conductor_Definition
public Conductor_Definition Remove_Conductor_Definition(String conductor_name)
- Remove a Conductor_Definition by name.
- Parameters:
conductor_name - A Conductor name.
- Returns:
- The Conductor_Definition that was removed. This will be null
if a Conductor_Definition with the specified name could not be
found.
Remove_Conductor_Definition
public void Remove_Conductor_Definition(int index)
- Removes a definition from the Conductor_Definitions Vector based on the index.
Clear_Conductor_Definitions
public Profile Clear_Conductor_Definitions()
- Clears the Conductor_Definitions Vector.
- Returns:
- This Profile.
Copyright (C) \
2003-2009 Bradford Castalia, University of Arizona
PIRL.Conductor.Maestro.Profile