com.internationalnetwork.util.conf
Class ConfigurationDirective

Object
  extended by com.internationalnetwork.util.conf.ConfigurationDirective
Direct Known Subclasses:
Container, Directive, Remark

public class ConfigurationDirective
extends Object

This is a generic class that is extended by Container, Directive, and Remark (plus any other unanticipated types as needed in the future).

This class provides all the needed methods to access the hierarchial data obtained from the ConfigurationResource.processStream() method, in a variety of different ways.

Example code

Note:  The examples here are not complete programs, but they do show you what is needed to have functional 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:

    // --------------------------------------------------------------------------
    // Read a configuration file (for Apache HTTPd in this example).  Wildcard
    // mode will be pre-enabled.
    //
    // Requires:  import com.internationalnetwork.util.conf.ConfigurationResource;
    //   ...and:  import com.internationalnetwork.util.conf.ContainerRoot;
    //   ...and:  import com.internationalnetwork.util.conf.ConfigurationDirective;
    // --------------------------------------------------------------------------
    ContainerRoot conf; // Root of configuration hierarchy
    try {
      conf = new ConfigurationResource( "httpd.conf" ).processStream();
    } catch ( java.io.IOException      e ) { // Code to handle exception (required)...
    } catch ( java.text.ParseException e ) { // Code to handle exception (required)...
    }

    // --------------------------------------------------------------------------
    // List all containers and directives in the "conf" container object.
    // --------------------------------------------------------------------------
    for ( ConfigurationDirective cd: conf.getChildren() )
      System.out.println( cd.getName() + " " + cd.getValue() );

    // --------------------------------------------------------------------------
    // List only containers in the "conf" container object.
    // --------------------------------------------------------------------------
    for ( ConfigurationDirective cd: conf.getBranches() )
      System.out.println( cd.getName() + " " + cd.getValue() );

    // --------------------------------------------------------------------------
    // List only directives in the "conf" container object.
    // --------------------------------------------------------------------------
    for ( ConfigurationDirective cd: conf.getContainerDirectives() )
      System.out.println( cd.getName() + " " + cd.getValue() );

    // --------------------------------------------------------------------------
    // Process all "VirtualHost" containers in the "conf" container object by
    // passing them off to a new class somewhere else, which is also added to an
    // ArrayList to keep track of them.
    //
    // This is really easy because we don't need to write our own code to compare
    // container names since the getBranches() method does this for us.  In
    // fact, we can specify more than one container name and getBranches() will
    // return all the appropriate containers (intermixed in their natural order
    // as they were encountered in the configuration stream) in the resulting
    // ConfigurationDirective[] array.
    //
    // Requires:  import java.util.ArrayList;
    //   ...and:  import _your_class; // You will need to write your own
    // --------------------------------------------------------------------------
    ArrayList<ConfigurationDirective> list = new ArrayList<ConfigurationDirective>();
    for ( ConfigurationDirective cd: conf.getBranches( "VirtualHost" ) )
      list.add( new _your_class_( cd ) ); // Store your newly instantiated object

Additional information

You need to get familiar with the various methods documented for the ConfigurationDirective class.  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.

This class cannot be instantiated directly.


Field Summary
static String VERSION
          Version number of this Package (read-only).
 
Method Summary
 void add(ConfigurationDirective configurationDirective)
          Adds a ConfigurationDirective object to the heirarchy.  If the supplied object is a Container type, then it is added to the hierarchy as a child Container, otherwise it is linked into the ordered list of Directive objects (with prev()/next() link references updated respectively to ensure accurate internal tracking).
 boolean containsChild(String directiveName)
          Indicates if the specified ConfigurationDirective name exists within this Container.  Traversal up to the root of the configuration hierarchy is NOT performed as part of this operation.
 ConfigurationDirective first()
          Returns a pointer to the first ConfigurationDirective object in the chain of directives within the current container.
 String getAtom(int index)
          Returns the specific atom from the uninherited value associated with this particular configuration directive, without traversing the configuration hierarchy (see the com.internationalnetwork.util.StringParser.atomize method for more information).
 String getAtom(String directiveName, int index)
          Returns the specific atom from the first local or inherited value associated with this particular configuration directive within the current container, split into atoms (see the com.internationalnetwork.util.StringParser.atomize method for more information).
 String[] getAtoms()
          Returns the uninherited value associated with this particular configuration directive, without traversing the configuration hierarchy, split into atoms (see the com.internationalnetwork.util.StringParser.atomize method for more information).
 String[][] getAtoms(String directiveName, int... index)
          Returns the local or inherited values associated with this particular configuration directive within the current container, split into atoms (see the com.internationalnetwork.util.StringParser.atomize method for more information), traversing the configuration hierarchy to the root to resolve its values.
 String[] getAtomsCombined(String directiveName, int... index)
          The same as the getAtoms(directiveName, index...) method, except that instead of returning a two-dimensional array, all arrays are combined sequentially into a single one-dimensional array (they are effectively "flattened") before being returned.
 ConfigurationDirective[] getBranches(String... containerName)
          Returns an array of Container type objects that are direct subordinate branches of the current Container.  Optionally, one or more container names may be specified, which will be applied as filters that restrict the results to exclude anything that doesn't match (when no container names are specified, all branches are returned).
 int getBranchesTotal()
          Returns the total number of direct subordinate Container-type branches this Container has, without re-creating the internal array.
 ConfigurationDirective[] getChildren()
          Returns an array of ConfigurationDirective objects that are direct subordinates of the current Container.
 int getChildrenTotal()
          Returns the total number of direct subordinate children this Container has, without re-creating the internal array.
 ConfigurationDirective[] getContainerDirectives(String directiveName)
          This is a convenience method for non-container type objects, which causes the parent container to be used to locate the specified value.  For full documentation, see the Container.getDirectives method.
 String getDefaultValue()
          Returns the default value as defined by the Rule that enforced syntax for this configuration directive.  NULL will be returned if a Rule was not specified, or if a default value wasn't defined within the respective Rule object's parameters.
 String getFirstValue(String directiveName)
          Returns the first local or inherited value associated with this particular configuration directive within the current container, traversing the configuration hierarchy to the root to resolve its value.  If multiple values exist, the first one that was encountered in the configuration stream is returned (this is useful for accessing directives which can only be defined once in the configuration file).
 long[] getLineNumbers()
          Returns the line numbers within the original configuration stream that this particular directive was defined on.
 String getName()
          Returns the name of this this configuration directive, adjusted to the correct mixture of upper- and lower-case characters, and Container brackets removed (if this is a container type object).
 String getNameLiteral()
          Returns the name of this this configuration directive, adjusted to the correct mixture of upper- and lower-case characters, but without Container brackets removed (if this is a container type object).
 Rule getRule()
          Returns the Rule object that was used for syntax enforcement.
 String getValue()
          Returns the uninherited value associated with this particular configuration directive, without traversing the configuration hierarchy.
 String[] getValue(String directiveName, int... index)
          Returns the local or inherited values associated with this particular configuration directive within the current container, traversing the configuration hierarchy to the root to resolve its values.
 boolean hasRule()
          Indicates if this object has a Rule defined.
 boolean isContainer()
          Indicates if this object is classified as a containter.
 boolean isContainerTerminator()
          Indicates if this object is classified as a containter terminator.  This may only be "true" for container type objects.
 boolean isDirective()
          Indicates if this object is classified as a directive or anything else that is not classified as a container (this convenience method returns the opposite of isContainer(), and so it should be thought of as if its name was "isNotContainer()").
 boolean isRoot()
          Indicates if this object is the root container.
 ConfigurationDirective last()
          Returns a pointer to the last ConfigurationDirective object in the chain of directives within the current container.
 ConfigurationDirective next()
          Returns a pointer to the next ConfigurationDirective object in the chain of directives within the current container.
 ConfigurationDirective parent()
          Returns a pointer to the ConfigurationDirective container object that this ConfigurationDirective object is stored in, or NULL if this is the root container object.
 ConfigurationDirective prev()
          Returns a pointer to the previous ConfigurationDirective object in the chain of directives within the current container.
 ConfigurationDirective previous()
          Returns a pointer to the previous ConfigurationDirective object in the chain of directives within the current container.
 boolean wasMultiLine()
          Indicates if this object's configuration data originally spanned multiple lines of text in the configuration stream.
 
Methods inherited from class Object
clone, 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
Method Detail

add

public final void add(ConfigurationDirective configurationDirective)
Adds a ConfigurationDirective object to the heirarchy.  If the supplied object is a Container type, then it is added to the hierarchy as a child Container, otherwise it is linked into the ordered list of Directive objects (with prev()/next() link references updated respectively to ensure accurate internal tracking).

Parameters:
configurationDirective - Object to add
Throws:
UnsupportedOperationException - if the ConfigurationDirective object was added to another container or hierarchy previously

containsChild

public boolean containsChild(String directiveName)
Indicates if the specified ConfigurationDirective name exists within this Container.  Traversal up to the root of the configuration hierarchy is NOT performed as part of this operation.

Parameters:
directiveName - Name of ConfigurationDirective to check
Returns:
boolean True = Is present, False = Not found (or not a container)

first

public final ConfigurationDirective first()
Returns a pointer to the first ConfigurationDirective object in the chain of directives within the current container.

The object will be any sub-class of ConfigurationDirective, and traversal will match the natural order as per the original configuration stream.

Returns:
ConfigurationDirective first object

getAtom

public final String getAtom(int index)
Returns the specific atom from the uninherited value associated with this particular configuration directive, without traversing the configuration hierarchy (see the com.internationalnetwork.util.StringParser.atomize method for more information).

Parameters:
index - The specific array element to extract from the atomized value
Returns:
String The specific atom as defined in the original configuration stream, or NULL if not found

getAtom

public final String getAtom(String directiveName,
                            int index)
Returns the specific atom from the first local or inherited value associated with this particular configuration directive within the current container, split into atoms (see the com.internationalnetwork.util.StringParser.atomize method for more information).

Parameters:
directiveName - The name of the directive
index - The specific array element to extract from the atomized value
Returns:
String The specified atom as defined in the original configuration stream, or NULL if not found

getAtoms

public final String[] getAtoms()
Returns the uninherited value associated with this particular configuration directive, without traversing the configuration hierarchy, split into atoms (see the com.internationalnetwork.util.StringParser.atomize method for more information).

Returns:
String[] The atomized value as defined in the original configuration stream

getAtoms

public final String[][] getAtoms(String directiveName,
                                 int... index)
Returns the local or inherited values associated with this particular configuration directive within the current container, split into atoms (see the com.internationalnetwork.util.StringParser.atomize method for more information), traversing the configuration hierarchy to the root to resolve its values.

All values associated with this directive are atomized, unless one or more index numbers were specified.

Parameters:
directiveName - The name of the directive
index - Optional; the specific values to atomize as if these were array elements, although they will be stored sequentially in a smaller array (for values that are out of range, NULL will be stored in the respective element in the array; if two or more index values are the same, then there will be undefined elements in the resulting array)
Returns:
String[][] The values as defined in the original configuration stream, split into their respective atoms (or an empty array if no values were found)

getAtomsCombined

public final String[] getAtomsCombined(String directiveName,
                                       int... index)
The same as the getAtoms(directiveName, index...) method, except that instead of returning a two-dimensional array, all arrays are combined sequentially into a single one-dimensional array (they are effectively "flattened") before being returned.

Parameters:
directiveName - The name of the directive
index - Optional; the specific values to atomize as if these were array elements, although they will be stored sequentially in a smaller array (for values that are out of range, NULL will be stored in the respective element in the array; if two or more index values are the same, then there will be undefined elements in the resulting array)
Returns:
String[] The atomized values from multiple directives of the same name, flattened into a one-dimensional array

getBranches

public final ConfigurationDirective[] getBranches(String... containerName)
Returns an array of Container type objects that are direct subordinate branches of the current Container.  Optionally, one or more container names may be specified, which will be applied as filters that restrict the results to exclude anything that doesn't match (when no container names are specified, all branches are returned).

If this is the first call to this method for this particular Container, or if the number of branches changed since the previous call, then additional processing will be required to re-create the internal array of branches.

If you only need to count the total number of branches, you should use the getBranchesTotal() method instead because it won't incur any overhead since it never re-creates the internal array.

Parameters:
containerName - Optional; one or more container names which will be used internally as filters when building the array of child containers
Returns:
ConfigurationDirective[] Array of subordinate containers

getBranchesTotal

public final int getBranchesTotal()
Returns the total number of direct subordinate Container-type branches this Container has, without re-creating the internal array.

Returns:
int Number of branches

getChildren

public final ConfigurationDirective[] getChildren()
Returns an array of ConfigurationDirective objects that are direct subordinates of the current Container.

If this is the first call to this method for this particular Container, or if the number of children changed since the previous call, then additional processing will be required to re-create the internal array of children.

If you only need to count the total number of children, you should use the getChildrenTotal() method instead because it won't incur any overhead since it never re-creates the internal array.

Returns:
ConfigurationDirectives[] Array of subordinate children

getChildrenTotal

public final int getChildrenTotal()
Returns the total number of direct subordinate children this Container has, without re-creating the internal array.

Returns:
int Number of children

getContainerDirectives

public final ConfigurationDirective[] getContainerDirectives(String directiveName)
This is a convenience method for non-container type objects, which causes the parent container to be used to locate the specified value.  For full documentation, see the Container.getDirectives method.

Parameters:
directiveName - Name of ConfigurationDirective to obtain the values for
Returns:
ConfigurationDirective[] The values (or inherited values) as defined in the original configuration stream, or else NULL if not defined

getDefaultValue

public final String getDefaultValue()
Returns the default value as defined by the Rule that enforced syntax for this configuration directive.  NULL will be returned if a Rule was not specified, or if a default value wasn't defined within the respective Rule object's parameters.

The actual value associated with this directive will never be supplied with this method.

Returns:
String The default value (or NULL if Rule or default was not defined)

getFirstValue

public final String getFirstValue(String directiveName)
Returns the first local or inherited value associated with this particular configuration directive within the current container, traversing the configuration hierarchy to the root to resolve its value.  If multiple values exist, the first one that was encountered in the configuration stream is returned (this is useful for accessing directives which can only be defined once in the configuration file).

All values associated with this directive are returned as a single String.

The getAtoms() methods are most likely what you need since they correctly parse pairs of quotation marks and eliminate extra whitespace for you.

Parameters:
directiveName - The name of the directive
Returns:
String The value as defined in the original configuration stream, or NULL if not found

getLineNumbers

public final long[] getLineNumbers()
Returns the line numbers within the original configuration stream that this particular directive was defined on.

The first element in the resulting array is the line number this directive (or container) began on, and the second element is the line number it ended on (-1 indicates that this directive {this only occurs with containers} is not yet closed {which should only occur during configuration stream processing by the ConfigurationResource class}).

Returns:
long[] Beginning and Ending line numbers

getName

public final String getName()
Returns the name of this this configuration directive, adjusted to the correct mixture of upper- and lower-case characters, and Container brackets removed (if this is a container type object).

Returns:
String Name of this configuration directive in its correct case

getNameLiteral

public final String getNameLiteral()
Returns the name of this this configuration directive, adjusted to the correct mixture of upper- and lower-case characters, but without Container brackets removed (if this is a container type object).

Returns:
String Name of this configuration directive in its correct case

getRule

public final Rule getRule()
Returns the Rule object that was used for syntax enforcement.

Returns:
Rule The Rule object (or NULL if a Rule wasn't defined)

getValue

public final String getValue()
Returns the uninherited value associated with this particular configuration directive, without traversing the configuration hierarchy.

The getAtoms() methods are most likely what you need since they correctly parse pairs of quotation marks and eliminate extra whitespace for you.

Returns:
String The value as defined in the original configuration stream

getValue

public final String[] getValue(String directiveName,
                               int... index)
Returns the local or inherited values associated with this particular configuration directive within the current container, traversing the configuration hierarchy to the root to resolve its values.

All values associated with this directive are returned, unless one or more index numbers were specified.

The getAtoms() methods are most likely what you need since they correctly parse pairs of quotation marks and eliminate extra whitespace for you.

Parameters:
directiveName - The name of the directive
index - Required; the specific values to return as if these were array elements, although they will be stored sequentially in a smaller array (for values that are out of range, NULL will be stored in the respective element in the array; if two or more index values are the same, then there will be undefined elements in the resulting array)
Returns:
String[] The values as defined in the original configuration stream

hasRule

public final boolean hasRule()
Indicates if this object has a Rule defined.

Returns:
boolean True = Rule is defined, False = No Rule was defined

isContainer

public final boolean isContainer()
Indicates if this object is classified as a containter.

Returns:
boolean True = Container, False = Not a container

isContainerTerminator

public final boolean isContainerTerminator()
Indicates if this object is classified as a containter terminator.  This may only be "true" for container type objects.

Returns:
boolean True = Terminator, False = Not a terminator

isDirective

public final boolean isDirective()
Indicates if this object is classified as a directive or anything else that is not classified as a container (this convenience method returns the opposite of isContainer(), and so it should be thought of as if its name was "isNotContainer()").

Returns:
boolean True = Not a container, False = Container

isRoot

public final boolean isRoot()
Indicates if this object is the root container.

Returns:
boolean True = Root container, False = Not root or not a container

last

public final ConfigurationDirective last()
Returns a pointer to the last ConfigurationDirective object in the chain of directives within the current container.

The object will be any sub-class of ConfigurationDirective, and traversal will match the natural order as per the original configuration stream.

Returns:
ConfigurationDirective last object

next

public final ConfigurationDirective next()
Returns a pointer to the next ConfigurationDirective object in the chain of directives within the current container.

The object will be any sub-class of ConfigurationDirective, and traversal will match the natural order as per the original configuration stream.

Returns:
ConfigurationDirective next object

parent

public final ConfigurationDirective parent()
Returns a pointer to the ConfigurationDirective container object that this ConfigurationDirective object is stored in, or NULL if this is the root container object.

The object will be a container sub-class of ConfigurationDirective, and traversal will match the natural order as per the original configuration stream.

Returns:
ConfigurationDirective parent object

prev

public final ConfigurationDirective prev()
Returns a pointer to the previous ConfigurationDirective object in the chain of directives within the current container.

The object will be any sub-class of ConfigurationDirective, and traversal will match the natural order as per the original configuration stream.

Returns:
ConfigurationDirective previous object

previous

public final ConfigurationDirective previous()
Returns a pointer to the previous ConfigurationDirective object in the chain of directives within the current container.

The object will be any sub-class of ConfigurationDirective, and traversal will match the natural order as per the original configuration stream.

Returns:
ConfigurationDirective previous object

wasMultiLine

public final boolean wasMultiLine()
Indicates if this object's configuration data originally spanned multiple lines of text in the configuration stream.

Returns:
boolean True = Was multiple lines, False = Was a single line