PIRL.Conductor.Pipeline_Configuration

## Class Pipeline_Configuration

- java.lang.Object
- - PIRL.Conductor.Pipeline_Configuration.Pipeline_Configuration

    public class Pipeline_Configuration
    extends Object

A Pipeline_Configuration provides an API and command-line tool for reading and writing pipeline configurations stored a database.

A Pipeline_Configuration database table has the following fields:

ID
  A unique auto-incremented integer.
PIPELINE
  A pipeline name.
PARAMETER
  A pipeline configuration parameter. This corresponds to the command-line "pipeline" specification.
VALUE
  The value of the configuration parameter.
VALIDATION_STRING
  A regular expression used to validate the contents of the value.
DESCRIPTION
  A short description of the parameter
LAST_UPDATE
  The time when the record was last modified.

### API

Pipeline_Configuration provides the ability to read and write all the columns except the ID. Typical usage of the API involves constructing a Pipeline_Configuration object with a database connection, catalog, pipeline, and whether strict-mode should be enforced. For example:

            Configuration
                    configuration = new Configuration ();
            Database
                    database = new Database (configuration);
            database.Connect ();
            String
                    catalog = "HiRISE",
                    pipeline = "HiColorNorm";
            boolean
                    strict = true;
            Pipeline_Configuration
                    pipeline_configuration = new Pipeline_Configuration
                            (database.Connection (), catalog, pipeline, strict);

Where:

configuration
  A PIRL.Configuration object that provides Database access information. A Database configuration file may be used for this purpose.
database
  A PIRL.Database object.
catalog
  The name of the database catalog that contains the table. By default this is obtained from the Configuration "Catalog" parameter.
pipeline
  The name of the pipeline to use when reading or writing a database table record.
strict
  When true all read operations will have their VALUE validated against the VALIDATION_STRING

The pipeline_configuration can then be used to read and write table records. For example:

            Conf
                    conf = pipeline_configuration.read ("Make_Unfiltered_Cube");
            System.out.println ("Make_Unfiltered_Cube = " + conf.value);
            System.out.println ("Description: " + conf.description);

The `Pipeline_Configuration.Conf` class is used to contain the field values of a table record.

A Pipeline_Configuration.write updates a table record if a named pipeline parameter is present in a table record. A new record is inserted in the table otherwise. Table record updates will only set field values for which data has supplied. For example:

            pipeline_configuration.write
                    ("Make_Unfiltered_Cube", "TRUE");
            pipeline_configuration.write
                    ("Make_Unfiltered_Cube", "TRUE", "TRUE|FALSE");
            pipeline_configuration.write
                    ("Make_Unfiltered_Cube", "TRUE", Validator.BOOLEAN);
            pipeline_configuration.write
                    ("Make_Unfiltered_Cube", "TRUE", "TRUE|FALSE", "A description.");

Each write will modify the same record (except, perhaps, the first which might insert a new record) that has the "HiColorNorm" value in the PIPELINE field and the "Make_Unfiltered_Cube" value in the PARAMETER field of a record of the default "Pipeline_Configuration" table in the "HiRISE" catalog.

### Application

The command-line usage can be obtained by using the -help option:

Here is an example of using Pipeline_Configuration for querying a pipeline's parameter for a value, getting all parameter information, and writing parameter information for a pipeline.

#### Querying a pipeline parameter value:

    Pipeline_Configuration \
            -configuration ~/HiRISE/Configuration/EDRgen/EDRgen.conf \
            -pipeline HiColorNorm \
            -parameter Make_Unfiltered_Cube

Returns:

    TRUE

#### Getting all information for a parameter:

    Pipeline_Configuration \
            -configuration ~/HiRISE/Configuration/EDRgen/EDRgen.conf \
            -pipeline HiColorNorm \
            -parameter Make_Unfiltered_Cube \
            -info

Returns:

    PIPELINE = HiColorNorm
    PARAMETER = Make_Unfiltered_Cube
    VALUE = TRUE
    VALIDATION_STRING = TRUE|FALSE
    DESCRIPTION = A boolean value to indicate if the HiColorNorm pipeline
                              should create the unfiltered color cube that has not passed
                              through the noise or furrow filtering corrections
    LAST_UPDATE = 2011-05-17 13:51:59.0

#### Writing parameter information for pipeline:

####

The result of this execution will be an exit code of 0 and no output

    Pipeline_Configuration \
            -configuration ~/HiRISE/Configuration/EDRgen/EDRgen.conf \
          -pipeline HiColorNorm \
              -parameter Make_Unfiltered_Cube \
              -write \
          -value FALSE \
              -validation "TRUE|FALSE|true|false"

Note that for write operations the -write option must be specified.

The result will be no output; the application will produce an exit status value of zero if there were no errors.

### Nested Class Summary

Nested Classes
`static class` `Pipeline_Configuration.Conf` The fields of a record in the Pipeline_Configuration database table.
`static class` `Pipeline_Configuration.ExitCode` Application exit status values.
`static class` `Pipeline_Configuration.Validator` A Validatorcontains a list of commonly used validators for typical values.

### Field Summary

Fields
`static String` `DEFAULT_DATABASE_TABLE_NAME` The default table name.
`static String` `ID` Class identification name with source code version and date.

### Constructor Summary

Constructors
Constructor and Description
`Pipeline_Configuration(Database database, String catalog, String table, String pipeline)` Constructs a Pipeline_Configuration with non-strict semantics.
`Pipeline_Configuration(Database database, String catalog, String table, String pipeline, boolean strict)` Constructs a Pipeline_Configuration.

### Method Summary

Methods
`void` `buildConfigurationTable(String catalog, String table)` Build a configuration table given a database catalog and table name.
`void` `close()` Close the database connection.
`static void` `main(String[] args)` Application main.
`Pipeline_Configuration.Conf` `read(String parameter)` Read the most up-to-date row for a parameter.
`void` `write(Pipeline_Configuration.Conf conf)` Write a configuration (Conf) for a parameter into a table record.
`void` `write(String parameter, String value)` Write a simple parameter-value pair into a table record.
`void` `write(String parameter, String value, String validation)` Write a parameter-value pair with validation string into a table record.
`void` `write(String parameter, String value, String validation, String description)` Write a parameter-value pair with validation string and description into a table record.

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

#### DEFAULT_DATABASE_TABLE_NAME

    public static final String DEFAULT_DATABASE_TABLE_NAME

The default table name.

See Also:
  Constant Field Values

### Constructor Detail

#### Pipeline_Configuration

    public Pipeline_Configuration(Database database,
                          String catalog,
                          String table,
                          String pipeline)

Constructs a Pipeline_Configuration with non-strict semantics.

Parameters:
  `database` - The Database object providing access to the database contents.
  `catalog` - The name of catalog in the database where the database tables are located.
  `table` - The name of the table to use for pipeline configuration queries.
  `pipeline` - The name of the pipeline to query for parameters.

#### Pipeline_Configuration

    public Pipeline_Configuration(Database database,
                          String catalog,
                          String table,
                          String pipeline,
                          boolean strict)

Constructs a Pipeline_Configuration.

Parameters:
  `database` - The Database object providing access to the database contents.
  `catalog` - The name of catalog in the database where the database tables are located.
  `table` - The name of the table to use for pipeline configuration queries.
  `pipeline` - The name of the pipeline to query for parameters.
  `strict` - A flag that indicates whether to treat validation failures as global errors.

### Method Detail

#### read

    public Pipeline_Configuration.Conf read(String parameter)

Read the most up-to-date row for a parameter.

Parameters:
  `parameter` - The name of a parameter in the table for which to read the record.
Returns:
  A `Pipeline_Configuration.Conf` containing all the field values of the record.

#### write

    public void write(String parameter,
             String value)

Write a simple parameter-value pair into a table record.

Parameters:
  `parameter` - The parameter name.
  `value` - The value String for the parameter.

#### write

    public void write(String parameter,
             String value,
             String validation)

Write a parameter-value pair with validation string into a table record.

Parameters:
  `parameter` - The parameter name.
  `value` - The value String for the parameter.
  `validation` - The validation String for the value.

#### write

    public void write(String parameter,
             String value,
             String validation,
             String description)

Write a parameter-value pair with validation string and description into a table record.

Parameters:
  `parameter` - The parameter name.
  `value` - The value String for the parameter.
  `validation` - The validation String for the value.
  `description` - The description String for the parameter.

#### write

    public void write(Pipeline_Configuration.Conf conf)

Write a configuration (Conf) for a parameter into a table record. The string-only variants of the `write` methods are preferable; they use this method.

Parameters:
  `conf` - A `Pipeline_Configuration.Conf` object which contains the field values of the record to be inserted into the table

#### close

    public void close()

Close the database connection. Closing the database connection is usually not necessary. Use this method to ensure that the database is closed when needed. WARNING Do not attempt to read or write a database table record after the connection to the database has been closed.

#### buildConfigurationTable

    public void buildConfigurationTable(String catalog,
                               String table)
                                 throws Database_Exception

Build a configuration table given a database catalog and table name. A database table for holding configuration parameters is created in the specified catalog.

Parameters:
  `catalog` - The name of the database catalog to contain the table.
  `table` - The name of the database table for containing configuration parameters.
Throws:
  `Database_Exception` - if the database table could not be created.

#### main

    public static void main(String[] args)

Application main.

Parameters:
  `args` - The program command-line arguments.