com.internationalnetwork.util.conf
Class ConfigurationResource

Object
  extended by com.internationalnetwork.util.conf.ConfigurationResource

public class ConfigurationResource
extends Object

Reads a stream of configuration parameters, using the specified rulesets, and returns the root-most ConfigurationDirective object.  A new stream may be opened, or an existing stream may be specified.

Example code

A very simple example, which does not apply any rules to the configuration file stream (because the internal wildcard mode flag is enabled by default when no rules are defined in the constructor), is as follows:

    // --------------------------------------------------------------------------
    // Constructor with no rules.  Wildcard mode will be pre-enabled.
    //
    // Requires:  import com.internationalnetwork.util.conf.ConfigurationResource;
    // --------------------------------------------------------------------------
    ConfigurationResource cR = new ConfigurationResource();

    // --------------------------------------------------------------------------
    // Read a configuration file (for Apache HTTPd in this example).
    //
    // Requires:  import com.internationalnetwork.util.conf.ContainerRoot;
    // --------------------------------------------------------------------------
    ContainerRoot conf; // Root of configuration hierarchy
    try {
      conf = cR.processStream( "httpd.conf" ); // Read and process the .conf file
    } catch ( java.io.IOException      e ) { // Code to handle exception (required)...
    } catch ( java.text.ParseException e ) { // Code to handle exception (required)...
    }

Configuration rules are defined in the form of rules as String arrays, as demonstrated in the following code (when rules are defined in the constructor, wildcard mode is automatically disabled {but can be enabled at prior to processing the stream by using the setWildcardFlag() method}; more rules can also be added with the defineRules() method, which has no effect on the internal wildcard mode flag):

    // --------------------------------------------------------------------------
    // Constructor with rules originating from multi-dimensional String[][]
    // arrays.  Wildcard mode will be pre-disabled.
    //
    // Requires:  import com.internationalnetwork.util.conf.ConfigurationResource;
    // --------------------------------------------------------------------------
    ConfigurationResource cR = new ConfigurationResource(
      new String[]{ "Directive", "text", "regex=.+" },
      new String[]{ "<Container>", "text", "regex=.+" },
      new String[]{ "Minimum", "number", "range=1..100", "default=3", "alias=Default=3" },
      new String[]{ "Maximum", "number", "range=1..100", "default=8", "alias=Default=8" },
      new String[]{ "Host", "ip", "hostname" }
    );

    // --------------------------------------------------------------------------
    // Read a configuration file (for ProFTPd in this example).
    //
    // Requires:  import com.internationalnetwork.util.conf.ContainerRoot;
    // --------------------------------------------------------------------------
    ContainerRoot conf; // Root of configuration hierarchy
    try {
      conf = cR.processStream( "proftpd.conf" ); // Read and process the .conf file
    } catch ( java.io.IOException      e ) { // Code to handle exception (required)...
    } catch ( java.text.ParseException e ) { // Code to handle exception (required)...
    }

Same example as that above, but using Rule objects instead of String[][] arrays.

    // --------------------------------------------------------------------------
    // Constructor with rules originating from Rule objects.  Wildcard mode will
    // be pre-disabled.
    //
    // Requires:  import com.internationalnetwork.util.conf.ConfigurationResource;
    //   ...and:  import com.internationalnetwork.util.conf.Rule;
    // --------------------------------------------------------------------------
    ConfigurationResource cR = new ConfigurationResource(
      new Rule( "Directive", "text", "regex=.+" ),
      new Rule( "<Container>", "text", "regex=.+" ),
      new Rule( "Minimum", "number", "range=1..100", "default=3", "alias=Default=3" ),
      new Rule( "Maximum", "number", "range=1..100", "default=8", "alias=Default=8" ),
      new Rule( "Host", "ip", "hostname" )
    );

    // --------------------------------------------------------------------------
    // Read a configuration file (for ProFTPd in this example).
    //
    // Requires:  import com.internationalnetwork.util.conf.ContainerRoot;
    // --------------------------------------------------------------------------
    ContainerRoot conf; // Root of configuration hierarchy
    try {
      conf = cR.processStream( "proftpd.conf" ); // Read and process the .conf file
    } catch ( java.io.IOException      e ) { // Code to handle exception (required)...
    } catch ( java.text.ParseException e ) { // Code to handle exception (required)...
    }

See the documentation for the Rule class for full information about defining rules, including more complex topics such as defining scope and specifying special requirements.  The examples provided above are very simple, and don't adequately represent the potential complexities that the Rule class allows for.

Reading additional files efficiently

The processStream() method can be used repeatedly to load process different configuration files that must adhere to the same sets of rules.  This reduces wasteful CPU resource and memory usage because it eliminates the need to re-define rules.

The defineRules() method can be used multiple times also, so that you can create entire sets of rules in advance, and use them to instantiate a variety of ConfigurationResource objects that serve different needs (e.g., the one that supports more directives and containers could be used to read your application's main configuration file, while the others that support subsets of all your rules could be used to read user-created configuration files, etc.).  By re-using your ConfigurationResource objects, you avoid re-defining the processing rules.

Accessing the data

You need to get familiar with the various methods documented for the ConfigurationDirective class (examples are also included that demonstrate how to access the data).  There are a few other methods in the Directive, Container, and ContainerRoot classes, which require a thorough understanding of the ConfigurationDirective class.

Through the ConfigurationDirective class you will be able to easily make use of the configuration data in meaningful ways, while taking full advantage of the hierarchial nature of the configuration file format to provide the greatest flexibility to your users.

Reserved directives

The "Include" directive is used internally and can't be overridden (unless the setReservedDirectivesFlag() method is used to change this behaviour).

All directives and containers whose names begin with an underscore are reserved for internal use, such as "<_root>" for the ContainerRoot object (format types have no effect, although some options will).


Field Summary
static String VERSION
          Version number of this Package (read-only).
 
Constructor Summary
ConfigurationResource()
          Creates a new Configuration Resource without an input stream, and no rules.
ConfigurationResource(java.io.File file, Rule... rules)
          Creates a new Configuration Resource with the specified File object.
ConfigurationResource(java.io.File file, String[]... rules)
          Creates a new Configuration Resource with the specified File object.
ConfigurationResource(java.io.InputStream inputStream, Rule... rules)
          Creates a new Configuration Resource with the specified input stream.
ConfigurationResource(java.io.InputStream inputStream, String[]... rules)
          Creates a new Configuration Resource with the specified input stream.
ConfigurationResource(Rule... rules)
          Creates a new Configuration Resource without an input stream.
ConfigurationResource(String[]... rules)
          Creates a new Configuration Resource without an input stream.
ConfigurationResource(String filename, Rule... rules)
          Creates a new Configuration Resource with the specified input stream.
ConfigurationResource(String filename, String[]... rules)
          Creates a new Configuration Resource with the specified filename.
 
Method Summary
 ConfigurationResource clone()
          Creates a duplicate of the current ConfigurationResource object, with empty internal stream stacks.
 ConfigurationResource defineRules(Rule... rules)
          Defines additional rules for directives and containers that may be encountered in the configuration stream.
 ConfigurationResource defineRules(String[]... rules)
          Defines additional rules for directives and containers that may be encountered in the configuration stream.
 boolean isReservedDirectivesFlag()
          Returns the current state of the reserved directives mode flag.
 boolean isWildcardFlag()
          Returns the current state of the wildcard mode flag.
 ContainerRoot processStream()
          Processes the specified resource and returns a "ConfigurationRoot" object containing the entire hierarchy of ConfigurationDirective objects that represent the parameters that were obtained from the configuration stream.
 ContainerRoot processStream(java.io.File file)
          Processes the specified resource and returns a "ConfigurationRoot" object containing the entire hierarchy of ConfigurationDirective objects that represent the parameters that were obtained from the configuration stream.
 ContainerRoot processStream(java.io.InputStream inputStream)
          Processes the specified resource and returns a "ConfigurationRoot" object containing the entire hierarchy of ConfigurationDirective objects that represent the parameters that were obtained from the configuration stream.
 ContainerRoot processStream(String filename)
          Processes the specified resource and returns a "ConfigurationRoot" object containing the entire hierarchy of ConfigurationDirective objects that represent the parameters that were obtained from the configuration stream.
 ConfigurationResource reDefineRule(Rule rule)
          Re-defines an existing rule.
 ConfigurationResource reDefineRule(String[] rule)
          Re-defines an existing rule.
 void setReservedDirectivesFlag(boolean flag)
          Enables or disables reserved directives.  When reserved directives mode is enabled, all internal directive and container names encountered in the configuration stream are handled internally, and any Rules that match an internal directive/container will consequently be ignored.
 void setWildcardFlag(boolean flag)
          Enables or disables wildcard mode.  When wildcard mode is enabled, all unrecognized directive and container names encountered in the configuration stream are accepted without generating formatting syntax errors.
 
Methods inherited from class Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

VERSION

public static final String VERSION
Version number of this Package (read-only).

See Also:
Constant Field Values
Constructor Detail

ConfigurationResource

public ConfigurationResource()
Creates a new Configuration Resource without an input stream, and no rules.


ConfigurationResource

public ConfigurationResource(java.io.File file,
                             Rule... rules)
                      throws java.io.IOException
Creates a new Configuration Resource with the specified File object.

Parameters:
file - The configuration File object to use
rules - Optional Rule objects either as a set of separate Rule objects, or an array of Rule objects, that defines valid directives and containers that may be encountered in the configuration stream (duplicate directive names replace previous directives); if no rules are specified, then any directives and containers will be permitted
Throws:
java.io.IOException - For the usual reasons that FileInputStream can throw this exception

ConfigurationResource

public ConfigurationResource(java.io.File file,
                             String[]... rules)
                      throws java.io.IOException
Creates a new Configuration Resource with the specified File object.

Parameters:
file - The configuration File object to use
rules - Optional String arrays either as a set of separate String arrays, or an array of String arrays, of rules that defines valid directives and containers that may be encountered in the configuration stream (duplicate directive names replace previous directives); if no rules are specified, then any directives and containers will be permitted
Throws:
java.io.IOException - For the usual reasons that FileInputStream can throw this exception

ConfigurationResource

public ConfigurationResource(java.io.InputStream inputStream,
                             Rule... rules)
Creates a new Configuration Resource with the specified input stream.

Parameters:
inputStream - The configuration stream to use
rules - Optional Rule objects either as a set of separate Rule objects, or an array of Rule objects, that defines valid directives and containers that may be encountered in the configuration stream (duplicate directive names replace previous directives); if no rules are specified, then any directives and containers will be permitted

ConfigurationResource

public ConfigurationResource(java.io.InputStream inputStream,
                             String[]... rules)
Creates a new Configuration Resource with the specified input stream.

Parameters:
inputStream - The configuration stream to use
rules - Optional String arrays either as a set of separate String arrays, or an array of String arrays, of rules that defines valid directives and containers that may be encountered in the configuration stream (duplicate directive names replace previous directives); if no rules are specified, then any directives and containers will be permitted

ConfigurationResource

public ConfigurationResource(Rule... rules)
Creates a new Configuration Resource without an input stream.

Parameters:
rules - Optional Rule objects either as a set of separate Rule objects, or an array of Rule objects, that defines valid directives and containers that may be encountered in the configuration stream (duplicate directive names replace previous directives); if no rules are specified, then any directives and containers will be permitted

ConfigurationResource

public ConfigurationResource(String[]... rules)
Creates a new Configuration Resource without an input stream.

Parameters:
rules - Optional String array of rules that defines valid directives and containers that may be encountered in the configuration stream (duplicate directive names replace previous directives); if no rules are specified, then any directives and containers will be permitted

ConfigurationResource

public ConfigurationResource(String filename,
                             Rule... rules)
                      throws java.io.IOException
Creates a new Configuration Resource with the specified input stream.

Parameters:
filename - The configuration file to use
rules - Optional Rule objects either as a set of separate Rule objects, or an array of Rule objects, that defines valid directives and containers that may be encountered in the configuration stream (duplicate directive names replace previous directives); if no rules are specified, then any directives and containers will be permitted
Throws:
java.io.IOException - For the usual reasons that FileInputStream can throw this exception

ConfigurationResource

public ConfigurationResource(String filename,
                             String[]... rules)
                      throws java.io.IOException
Creates a new Configuration Resource with the specified filename.

Parameters:
filename - Name (with optional path) of the configuration file to use
rules - Optional String arrays either as a set of separate String arrays, or an array of String arrays, of rules that defines valid directives and containers that may be encountered in the configuration stream (duplicate directive names replace previous directives); if no rules are specified, then any directives and containers will be permitted
Throws:
java.io.IOException - For the usual reasons that FileInputStream can throw this exception
Method Detail

clone

public ConfigurationResource clone()
Creates a duplicate of the current ConfigurationResource object, with empty internal stream stacks.

The pre-set streams will not be cloned because if two different stream processing operations occur on the same stream simultaneously, the results will not be as expected.

The main reason this object needs to be cloned is to allow thread-safety.

Overrides:
clone in class Object
Returns:
ConfigurationResource cloned

defineRules

public ConfigurationResource defineRules(Rule... rules)
Defines additional rules for directives and containers that may be encountered in the configuration stream.

Rules cannot be re-defined.  If an attempt is made to define a Rule more than once, a java.lang.IllegalArgumentException exception will be thrown (although this should not occur, it is provided here for developers relying on user-supplied rule definition data).

Parameters:
rules - Optional Rule array of rules that defines valid directives and containers that may be encountered in the configuration stream
Returns:
ConfigurationResource as a convenience to the developer when adding multiple sets of rules
Throws:
IllegalArgumentException - if the given Rule was previously defined (rules cannot be re-defined)

defineRules

public ConfigurationResource defineRules(String[]... rules)
Defines additional rules for directives and containers that may be encountered in the configuration stream.

Rules cannot be re-defined.  If an attempt is made to define a Rule more than once, a java.lang.IllegalArgumentException exception will be thrown (although this should not occur, it is provided here for developers relying on user-supplied rule definition data).

Parameters:
rules - Optional String array of rules that defines valid directives and containers that may be encountered in the configuration stream
Returns:
ConfigurationResource as a convenience to the developer when adding multiple sets of rules
Throws:
IllegalArgumentException - if the given Rule was previously defined (rules cannot be re-defined)

isReservedDirectivesFlag

public boolean isReservedDirectivesFlag()
Returns the current state of the reserved directives mode flag.

Returns:
boolean True = enabled, False = disabled

isWildcardFlag

public boolean isWildcardFlag()
Returns the current state of the wildcard mode flag.

Returns:
boolean True = enabled, False = disabled

processStream

public ContainerRoot processStream()
                            throws java.io.IOException,
                                   java.text.ParseException
Processes the specified resource and returns a "ConfigurationRoot" object containing the entire hierarchy of ConfigurationDirective objects that represent the parameters that were obtained from the configuration stream.

All the streams and files that were specified with the constructor and/or any processStream() methods will be drained from the internal Stack before processing begins (this is by design to prevent unpredictable results when re-using any processStream() method).

This method is NOT thread-safe.  Use the clone() method and work with a copy if using this class from multiple threads.

Returns:
ContainerRoot Root container for the configuration hierarchy
Throws:
java.io.IOException - if something goes wrong with the stream
java.text.ParseException - if an incorrectly formatted Directive or Container/Terminator is encountered in any stream

processStream

public ContainerRoot processStream(java.io.File file)
                            throws java.io.IOException,
                                   java.text.ParseException
Processes the specified resource and returns a "ConfigurationRoot" object containing the entire hierarchy of ConfigurationDirective objects that represent the parameters that were obtained from the configuration stream.

All the streams and files that were specified with the constructor and/or any processStream() methods will be drained from the internal Stack before processing begins (this is by design to prevent unpredictable results when re-using any processStream() method).

This method is NOT thread-safe.  Use the clone() method and work with a copy if using this class from multiple threads.

Parameters:
file - The configuration file object (whose name will also be add to the internal stack, as if it was defined by an "Include" directive)
Returns:
ContainerRoot Root container for the configuration hierarchy
Throws:
java.io.IOException - if something goes wrong with any stream
java.text.ParseException - if an incorrectly formatted Directive or Container/Terminator is encountered in the stream

processStream

public ContainerRoot processStream(java.io.InputStream inputStream)
                            throws java.io.IOException,
                                   java.text.ParseException
Processes the specified resource and returns a "ConfigurationRoot" object containing the entire hierarchy of ConfigurationDirective objects that represent the parameters that were obtained from the configuration stream.

All the streams and files that were specified with the constructor and/or any processStream() methods will be drained from the internal Stack before processing begins (this is by design to prevent unpredictable results when re-using any processStream() method).

This method is NOT thread-safe.  Use the clone() method and work with a copy if using this class from multiple threads.

Parameters:
inputStream - The configuration stream to add to the internal stack, almost as if it was defined by an "Include" directive (except that it's a stream instead of the name of a file)
Returns:
ContainerRoot Root container for the configuration hierarchy
Throws:
java.io.IOException - if something goes wrong with any stream
java.text.ParseException - if an incorrectly formatted Directive or Container/Terminator is encountered in the stream

processStream

public ContainerRoot processStream(String filename)
                            throws java.io.IOException,
                                   java.text.ParseException
Processes the specified resource and returns a "ConfigurationRoot" object containing the entire hierarchy of ConfigurationDirective objects that represent the parameters that were obtained from the configuration stream.

All the streams and files that were specified with the constructor and/or any processStream() methods will be drained from the internal Stack before processing begins (this is by design to prevent unpredictable results when re-using any processStream() method).

This method is NOT thread-safe.  Use the clone() method and work with a copy if using this class from multiple threads.

Parameters:
filename - The configuration file to add to the internal stack, as if it was defined by an "Include" directive
Returns:
ContainerRoot Root container for the configuration hierarchy
Throws:
java.io.IOException - if something goes wrong with any stream
java.text.ParseException - if an incorrectly formatted Directive or Container/Terminator is encountered in the stream

reDefineRule

public ConfigurationResource reDefineRule(Rule rule)
Re-defines an existing rule.

If an attempt is made to re-define a Rule that doesn't exist, a java.lang.IllegalArgumentException exception will be thrown (although this should not occur, it is provided here for developers relying on user-supplied rule definition data).

Parameters:
rule - Rule object containing rule data that re-defines an existing directive or container that may be encountered in the configuration stream
Returns:
ConfigurationResource as a convenience to the developer when re-defining multiple rules
Throws:
IllegalArgumentException - if the given Rule was not previously defined

reDefineRule

public ConfigurationResource reDefineRule(String[] rule)
Re-defines an existing rule.

If an attempt is made to re-define a Rule that doesn't exist, a java.lang.IllegalArgumentException exception will be thrown (although this should not occur, it is provided here for developers relying on user-supplied rule definition data).

Parameters:
rule - String array of rule data that re-defines an existing directive or container that may be encountered in the configuration stream
Returns:
ConfigurationResource as a convenience to the developer when re-defining multiple rules
Throws:
IllegalArgumentException - if the given Rule was not previously defined

setReservedDirectivesFlag

public void setReservedDirectivesFlag(boolean flag)
Enables or disables reserved directives.  When reserved directives mode is enabled, all internal directive and container names encountered in the configuration stream are handled internally, and any Rules that match an internal directive/container will consequently be ignored.

List of internal directives:

Internal directives are enabled by default.  If disabled, all internal directives will be handled like any other directive, and generate errors if not defined (and the wildcard mode flag is disabled).

Parameters:
flag - True = enabled, False = disabled

setWildcardFlag

public void setWildcardFlag(boolean flag)
Enables or disables wildcard mode.  When wildcard mode is enabled, all unrecognized directive and container names encountered in the configuration stream are accepted without generating formatting syntax errors.

Syntax checking is still enforced with directive and container names for which rules are defined, regardless of the state of this flag.

Wildcards are disabled by default, unless rules were not specified with the constructor (in which case wildcards will be enabled by default).

Parameters:
flag - True = enabled, False = disabled