Configuration (PIRL Java Packages)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

PIRL.Configuration
Class Configuration

java.lang.Object
  javax.swing.tree.DefaultMutableTreeNode
      PIRL.PVL.Parameter
          PIRL.Configuration.Configuration

All Implemented Interfaces:: Serializable, Cloneable, MutableTreeNode, TreeNode

public class Configuration
extends Parameter
implements Cloneable
extends Parameter
implements Cloneable

A Configuration maintains a Parameter list used for configuration management.

A Configuration is constructed by parsing source text in Parameter Value Language (PVL) format (as read by a Parameter Parser), or from another Configuration or PVL Parameter. The Default_Source will be used if no source is specified. Except when a Configuration is constructed as a copy of another Configuration (or Parameter Aggregate), the Defaults Parameters are always included; if the special name DEFAULTS is specified, only the Defaults Parameters will be in the Configuration. In all cases, the Parameters in the Configuration will be Coalesced together.

The parameters of a Configuration are refered to by their pathname. The pathname may include a delimiter (usually the '/' character) separated sequence of names where each segment names a parameter group within which subsequent named parameters are nested. A pathname that begins with a delimiter is rooted at the top of the Configuration parameter groupings (i.e. these pathnames have an absolute location in the Configuration). Otherwise the pathname is rooted at the first occurance of a parameter having the first segment name (i.e. these pathnames have a relative location in the Configuration).

There are a set of parameter names that are known to the Configuration package:

Classpath: The Java CLASSPATH. The default is obtained from the "java.class.path" System Property.
Host: An application-specific hostname. The default is "localhost."
User: A username to be supplied to the application. The default is obtained from the "user.name" System Property.
Alias: The name of the group from which a new Configuration was created when an alias (a linked parameter) was used rather than a group name.

In addition, the INCLUDE parameter is recognized when Include mode is enabled as a parameter with a value that references another source of Parameters that is to be included in the Configuration replacing the Include parameter. Include files may be nested. Cyclical Include file (but not URL) chains are caught.

Version:: 1.55
Author:: Bradford Castalia - UA/PIRL
See Also:: Parameter, Serialized Form

Field Summary
`static String`	`ALIAS` The parameter name for a linked parameter used to create a new Configuration: "Alias".
`static boolean`	`Case_Sensitive_Default` The default `Case_Sensitive()` state.
`static String`	`CLASSPATH` The parameter name for the Java CLASSPATH: "Classpath".
`static String`	`CONTINUE_INCLUDE_ON_ERROR_FLAG` `INCLUDE` parameter value flag that, when found at the beginning of the value, causes an error on the include - the source does not exists - to be ignored and the include skipped.
`static String`	`Default_Source` The name of the default configuration source: initially "DEFAULTS".
`static Parameter`	`Defaults` The default parameters conditionally set during `configuration`.
`static String`	`DEFAULTS` The name of the internal default parameters: "DEFAULTS".
`static boolean`	`Defaults_Default` The default automatic `Defaults` state.
`static int`	`Duplicate_Parameter_Action_Default` The default `Duplicate_Parameter_Action()`.
`static String`	`ENVIRONMENT` The name of the Group containing the environment variable parameters: "/Environment".
`static String`	`HOST` The parameter name for the application-specific hostname: "Host".
`static String`	`ID` Class name and version identification.
`static String`	`INCLUDE` The name of a parameter that refers to a file of parameters to be included at that point in the Configuration: "@Include".
`static boolean`	`Include_Default` The default automatic `Include` state.
`static String`	`INCLUDE_END` Parameter name prefix for the end of an `Include` file when tracing is enabled.
`static String`	`INCLUDE_ERROR` Parameter name prefix for an `ignored error` report from an `Include` file when tracing is enabled.
`static String`	`INCLUDE_START` Parameter name prefix for the start of an `Include` file when tracing is enabled.
`static boolean`	`Include_Tracing_Default` The default automatic `Include` tracing flag.
`static String`	`NL`
`static int`	`PREFER_FIRST_PARAMETER` The first duplicate parameter in the list gets preference when coalescing.
`static int`	`PREFER_LAST_PARAMETER` The last duplicate parameter in the list gets preference when coalescing.
`static int`	`THROW_ON_DUPLICATE_PARAMETERS` Duplicate parameters in the list when coalescing causes an exception.
`static String`	`USER` The parameter name for the application-specific username: "User".

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
`Configuration()` Constructs a default Configuration.
`Configuration(Configuration configuration)` Copies a Configuration.
`Configuration(InputStream stream)` Constructs a Configuration using the specified InputStream.
`Configuration(Parameter parameter)` Constructs a Configuration from a Parameter.
`Configuration(String source)` Constructs a Configuration using the specified source.
`Configuration(URL url)` Constructs a Configuration using the specified URL.

Method Summary
`Configuration`	`Add_Environment()` Adds environment variables to the Configuration.
`boolean`	`Case_Sensitive()` Gets the case sensitive mode for finding parameter names.
`boolean`	`Case_Sensitive(boolean enable)` Sets the case sensitive mode for finding parameter names.
`Object`	`clone()` Clones a Configurtion.
`void`	`Coalesce()` Coalesce all Aggregate parameters of the same name together.
`void`	`Configure(InputStream stream)` Loads a Configuration from an InputStream.
`void`	`Configure(String source)` Loads a Configuration from a configuration file.
`void`	`Configure(URL url)` Loads a Configuration from a URL.
`static String`	`Default_Filename()` Deprecated. Replaced by `Default_Source()`
`static void`	`Default_Filename(String filename)` Deprecated. Replaced by `Default_Source(String)`
`static String`	`Default_Source()` Gets the default source name.
`static void`	`Default_Source(String source)` Sets the default source name.
`boolean`	`Defaults(boolean enable)` Enables or disables automatic inclusion of `Defaults` parameters.
`String`	`Description()` Provides a String description of a Configuration formatted as a list of the parameters and their values.
`int`	`Duplicate_Parameter_Action()` Gets the duplicate parameter action during coalescing.
`Configuration`	`Duplicate_Parameter_Action(int action)` Sets the duplicate parameter action during coalescing.
`Parameter`	`Effective_Parameter(String pathname)` Gets the effective Parameter for a pathname.
`String`	`Effective_Pathname(String pathname)` Gets the effective pathname for a specified pathname.
`boolean`	`Enabled(String pathname, boolean default_flag)` Tests if a parameter has a logically true value.
`String`	`Filename()` Deprecated. Replaced by `Source()`
`Configuration`	`Filename(String filename)` Deprecated. Replaced by `Source(String)`
`String`	`Get_Linked_One(String pathname)` Gets one String value for the effective, and possibly linked, parameter at a pathname.
`Vector`	`Get_Linked(String pathname)` Gets the value(s) for the effective parameter at a pathname where the parameter may be linked to another parameter through its value.
`double`	`Get_Number(String pathname, double default_value)` Gets a numerical value.
`String`	`Get_One(Parameter parameter)` Gets one String value from the Get Vector.
`String`	`Get_One(String pathname)` Gets one String value for the effective parameter at a pathname.
`String`	`Get_One(Value value)` Gets one String value from the Get Vector.
`static String`	`Get_One(Vector values)` Gets the first String value from a Vector of values.
`static String`	`Get_One(Vector values, int index)` Gets the indexed String value from a Vector of values.
`String`	`Get_Specific_One(String pathname)` Gets one String value from the specific pathname.
`Vector`	`Get_Specific(String pathname)` Gets the value(s) for a parameter at a specific pathname.
`Vector`	`Get(Parameter parameter)` Gets the value(s) for a Parameter.
`Vector`	`Get(String pathname)` Gets the value(s) for the effective parameter at a pathname.
`Vector`	`Get(String pathname, boolean specific)` Gets the value(s) for a parameter at a pathname.
`Vector`	`Get(String pathname, boolean specific, int skip)` Gets the value(s) for a parameter at the Nth pathname.
`static Vector`	`Get(Value value)` Gets the value(s) for a Parameter Value.
`String`	`Group_Pathname(String group)` Gets the pathname to a parameter group.
`Configuration`	`Group(String group)` Gets the Configuration parameters for a group.
`boolean`	`Include_Tracing(boolean enable)` Enables or disables `Include` file tracing.
`Configuration`	`Include()` Includes parameters from include files.
`boolean`	`Include(boolean enable)` Enables or disables automatic `Include`s.
`static void`	`main(String[] arguments)` Assemble and report on the contents of a configuration.
`Parameter`	`Parameter_at(String pathname)` Gets the parameter or parameter group at a pathname.
`Parameter`	`Parameter(String pathname, boolean specific)` Gets the parameter for a pathname.
`Parameter`	`Parameter(String pathname, boolean specific, int skip)` Gets the Nth parameter for a pathname.
`static String`	`Path_Name_to_Pathname(String pathname)` Gets the Configuration pathname for a Parameter Path_Name.
`static String`	`Pathname_Uncle(String pathname)` Gets the pathname for a parameter at the previous group level.
`static String`	`Pathname(Parameter parameter)` Gets the Configuration pathaname for a parameter.
`static Class`	`Relative_to_Class()` Gets the class relative to which a configuration file may be sought.
`static void`	`Relative_to_Class(Class related_class)` Sets the class relative to which a configuration file may be sought.
`boolean`	`Remove_Group(String pathname)` Removes a group of parameters at a pathname.
`boolean`	`Remove_Specific(String pathname)` Removes the parameter at the specific pathname.
`boolean`	`Remove(String pathname)` Removes the all of the effective parameters for the pathname.
`boolean`	`Remove(String pathname, boolean specific)` Removes the parameter(s) at a pathname.
`boolean`	`Set_All(String name, Object value)` Sets all occurances of a parameter with the specified name to have the specified value.
`void`	`Set_Conditionally(Parameter parameter)` Conditionally sets parameters in the Configuration to correspond with the contents of another parameter.
`void`	`Set_Conditionally(String[][] parameter_table)` Conditionally sets all of the entries of an array of String arrays.
`boolean`	`Set_Conditionally(String pathname, Object value)` Sets the value of a new parameter at a pathname.
`void`	`Set(Parameter parameter)` Sets parameters in the Configuration to correspond with the contents of another parameter.
`void`	`Set(Parameter parameter, boolean replace)` Sets parameters in the Configuration to correspond with the contents of another parameter.
`void`	`Set(String[][] parameter_table)` Sets all of the entries of an array of String arrays.
`void`	`Set(String[][] parameter_table, boolean replace)` Sets all of the entries of an array of String arrays as Configuration parameters.
`boolean`	`Set(String pathname, Object value)` Sets the value of a parameter at a pathname.
`boolean`	`Set(String pathname, Object value, boolean replace)` Sets a parameter at a specified pathname location to the value of an Object.
`String`	`Source()` Gets the name of the source from which the Configuration parameters have been set.
`Configuration`	`Source(String source)` Resets the Configuration from the contents of the source.
`Parameter`	`Specific_Parameter(String pathname)` Gets the specific Parameter for a pathname.
`static void`	`Usage()` Prints the command line usage syntax.

Methods inherited from class PIRL.PVL.Parameter
Absolute_Pathname, Absolute_Pathname, Add, add, Add, Add, adopt, Basename, Classification_Name, Classification_Name, Classification, Classification, Classification, Comments, Comments, Data, Data, Data, 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, toString, Value, Value, Value, Value, Value, Value, Value, Value, Value, Warning, Write, Write, Write, Write, Write, Write, Write, Write

Methods inherited from class PIRL.PVL.Parameter

Absolute_Pathname, Absolute_Pathname, Add, add, Add, Add, adopt, Basename, Classification_Name, Classification_Name, Classification, Classification, Classification, Comments, Comments, Data, Data, Data, 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, toString, 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 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 name and version identification.

See Also:: Constant Field Values

CLASSPATH

public static final String CLASSPATH

The parameter name for the Java CLASSPATH: "Classpath".

See Also:: Constant Field Values

HOST

public static final String HOST

The parameter name for the application-specific hostname: "Host".

See Also:: Constant Field Values

USER

public static final String USER

The parameter name for the application-specific username: "User".

See Also:: Constant Field Values

ALIAS

public static final String ALIAS

The parameter name for a linked parameter used to create a new Configuration: "Alias".

See Also:: Group(String), Constant Field Values

ENVIRONMENT

public static final String ENVIRONMENT

The name of the Group containing the environment variable parameters: "/Environment".

See Also:: Add_Environment()

INCLUDE

public static final String INCLUDE

The name of a parameter that refers to a file of parameters to be included at that point in the Configuration: "@Include".

See Also:: Constant Field Values

Include_Default

public static boolean Include_Default

The default automatic Include state.

INCLUDE_START

public static final String INCLUDE_START

Parameter name prefix for the start of an Include file when tracing is enabled.

See Also:: Constant Field Values

INCLUDE_ERROR

public static final String INCLUDE_ERROR

Parameter name prefix for an ignored error report from an Include file when tracing is enabled.

See Also:: Constant Field Values

INCLUDE_END

public static final String INCLUDE_END

Parameter name prefix for the end of an Include file when tracing is enabled.

See Also:: Constant Field Values

Include_Tracing_Default

public static boolean Include_Tracing_Default

The default automatic Include tracing flag.

CONTINUE_INCLUDE_ON_ERROR_FLAG

public static final String CONTINUE_INCLUDE_ON_ERROR_FLAG

INCLUDE parameter value flag that, when found at the beginning of the value, causes an error on the include - the source does not exists - to be ignored and the include skipped.

See Also:: Constant Field Values

DEFAULTS

public static final String DEFAULTS

The name of the internal default parameters: "DEFAULTS".

See Also:: Constant Field Values

Default_Source

public static String Default_Source

The name of the default configuration source: initially "DEFAULTS".

Defaults

public static final Parameter Defaults

The default parameters conditionally set during configuration.

The default parameters are:

CLASSPATH: The "java.class.path" System Property.
USER: The "user.name" System Property.
HOST: The "localhost" String.

Defaults_Default

public static boolean Defaults_Default

The default automatic Defaults state.

PREFER_FIRST_PARAMETER

public static final int PREFER_FIRST_PARAMETER

The first duplicate parameter in the list gets preference when coalescing.

When a duplicate Assignment parameter pathname is found while coalescing the Configuration, give preference to the first parameter; i.e. remove all but the first of any duplicate pathname parameters.

See Also:: Constant Field Values

PREFER_LAST_PARAMETER

public static final int PREFER_LAST_PARAMETER

The last duplicate parameter in the list gets preference when coalescing.

When a duplicate Assignment Parameter pathname is found while coalescing the Configuration, give preference to the last parameter; i.e. remove all but the last of any duplicate pathname parameters.

See Also:: Constant Field Values

THROW_ON_DUPLICATE_PARAMETERS

public static final int THROW_ON_DUPLICATE_PARAMETERS

Duplicate parameters in the list when coalescing causes an exception.

When a duplicate Assignment Parameter pathname is found while coalescing the Configuration, a Configuration_Exception will be thrown.

See Also:: Constant Field Values

Duplicate_Parameter_Action_Default

public static int Duplicate_Parameter_Action_Default

The default Duplicate_Parameter_Action().

Case_Sensitive_Default

public static boolean Case_Sensitive_Default

The default Case_Sensitive() state.

NL

public static final String NL

Constructor Detail

Configuration

public Configuration()

Constructs a default Configuration.

The Defaults are used to set the initial parameters. DEFAULTS is the name of this Configuration.

Configuration

public Configuration(String source)
              throws Configuration_Exception

Constructs a Configuration using the specified source.

Parameters:: source - The source String reference for the Configuration PVL. This may be in the form of a URL representation. If null, the Default_Source is used.
Throws:: IllegalArgumentException - If the source is not a URL and no file or system resource can be found with the source name.; Configuration_Exception - If the source can not be read or successfully parsed for parameters, INCLUDE files could not be included, or there was a problem coalescing the parameters (probably due to a duplicate parameter name).
See Also:: Configure(String), Include(boolean)

Configuration

public Configuration(URL url)
              throws Configuration_Exception

Constructs a Configuration using the specified URL.

Parameters:: url - A URL object to use as the source of Configuration PVL.
Throws:: Configuration_Exception - If a stream can not be opened from the URL, there was a problem while parsing the source for parameters, INCLUDE files could not be included, or there was a problem coalescing the parameters (probably due to a duplicate parameter name).
See Also:: Configure(URL), Include(boolean)

Configuration

public Configuration(InputStream stream)
              throws Configuration_Exception

Constructs a Configuration using the specified InputStream.

Parameters:: stream - An InputStream object to use as the source of Configuration PVL.
Throws:: Configuration_Exception - If there was a problem while parsing the stream for parameters, INCLUDE files could not be included, or there was a problem coalescing the parameters (probably due to a duplicate parameter name).
See Also:: Configure(InputStream), Include(boolean)

Configuration

public Configuration(Parameter parameter)
              throws Configuration_Exception

Constructs a Configuration from a Parameter.

If the Parameter is null or empty (has the Parameter.UNKNOWN classification) an empty Configuration with the name Parser.CONTAINER_NAME is constructed. If the Parameter is an Assignment it becomes the only parameter in a Configuration with the name Parser.CONTAINER_NAME. If the Parameter is an Aggregate, its Parameter list is copied into the new Configuration which is given the name of the Aggregate (the Configuration is a copy of the Parameter).

If automatic include is enabled any INCLUDE parameters are processed. Finally, the results are Coalesced.

N.B.: Only the provided Parameter is included in the new Configuration; Defaults are not included.

Parameters:: parameter - The Parameter which will be copied into this Configuration.
Throws:: Configuration_Exception - If the Parameter contents could not be added to the new Configuration, INCLUDE files could not be included, or there was a problem coalescing the results (probably due to duplicate parameter names).
See Also:: Coalesce(), Include(boolean)

Configuration

public Configuration(Configuration configuration)
              throws Configuration_Exception

Copies a Configuration.

This is the same as constructing a Configuration from a Parameter, followed by copying over the Configuration characteristics case sensitivity, duplicate parameter handling, Include processing, Include tracing, Defaults parameters inclusion and the filename if non-null;

N.B.: The state of this Configuration is used during the copy, not the state of the copied Configuration. For example, copied INCLUDE parameters are processed if automatic Include is enabled for this Configuration; the automatic Include state of the Configuration being copied is not used.

Parameters:: configuration - The Configuration to be copied.
Throws:: Configuration_Exception - If the Parameter contents could not be added to the new Configuration, or there was a problem coalescing the results (probably due to duplicate parameter names).
See Also:: Configuration(Parameter)

Method Detail

clone

public Object clone()

Clones a Configurtion.

Overrides:: clone in class Parameter

Returns:: An Object of class Configuration that is a copy of this Configuration. This will be null if there was a problem making the copy.
See Also:: Configuration(Configuration), Object.clone(), Cloneable

Get

public Vector Get(String pathname,
                  boolean specific)

Gets the value(s) for a parameter at a pathname.

If specific is true then the values will be obtained from the Specific_Parameter, otherwise the Effective_Parameter will be used.

Parameters:: pathname - A parameter pathname.; specific - true if only a parameter at the specific pathname is acceptable, otherwise default values from an effective parameter will do.
Returns:: A Vector of zero or more values. Each element of the Vector is either the String representation of a single value, or is itself a Vector of the same kind.

Get

public Vector Get(String pathname,
                  boolean specific,
                  int skip)

Gets the value(s) for a parameter at the Nth pathname.

Parameters:: pathname - A parameter pathname.; specific - true if only a parameter at the specific pathname is acceptable, otherwise default values from an effective parameter will do.; skip - The number of matching parameters to skip before selecting a parameter.
Returns:: A Vector of zero or more values. Each element of the Vector is either the String representation of a single value, or is itself a Vector of the same kind.
See Also:: Get(String, boolean), Parameter(String, boolean, int)

Get_Specific

public Vector Get_Specific(String pathname)

Gets the value(s) for a parameter at a specific pathname.

This is the same as using the Get method with the specific argument being true.

Parameters:: pathname - A parameter pathname.
Returns:: A Vector of zero or more values. Each element of the Vector is either the String representation of a single value, or is itself a Vector of the same kind.

Get_Specific_One

public String Get_Specific_One(String pathname)

Gets one String value from the specific pathname.

Parameters:: pathname - A parameter pathname.
Returns:: The first String value from the specific parameter, or null if there is no parameter value.
See Also:: Get_Specific(String), Get_One(Vector)

Get

public Vector Get(String pathname)

Gets the value(s) for the effective parameter at a pathname.

This is the same as using the Get method with the specific argument being false.

Parameters:: pathname - A parameter pathname.
Returns:: A Vector of zero or more values. Each element of the Vector is either the String representation of a single value, or is itself a Vector of the same kind.

Get_One

public String Get_One(String pathname)

Gets one String value for the effective parameter at a pathname.

Parameters:: pathname - A parameter pathname.
Returns:: The first String value from the effective parameter, or null if there is no value.
See Also:: Get(String), Get_One(Vector)

Get_Linked

public Vector Get_Linked(String pathname)

Gets the value(s) for the effective parameter at a pathname where the parameter may be linked to another parameter through its value.

A linked parameter is an assignment of a single String value in which the value is the pathname of some other effective parameter. If the parameter has more than one value it is not linked. The returned Vector contains the value(s) of the first non-linked parameter found. An empty Vector will be returned if no parameter is found.

Parameters:: pathname - A parameter pathname.
Returns:: A Vector of zero or more values. Each element of the Vector is either the String representation of a single value, or is itself a Vector of the same kind.

Get_Linked_One

public String Get_Linked_One(String pathname)

Gets one String value for the effective, and possibly linked, parameter at a pathname.

Parameters:: pathname - A parameter pathname.
Returns:: The first String value from the effective parameter, or null if there is no value.
See Also:: Get_Linked(String), Get_One(Vector)

Get

public Vector Get(Parameter parameter)

Gets the value(s) for a Parameter.

Parameters:: parameter - The Parameter from which to get value(s).
Returns:: A Vector of zero or more values. Each element of the Vector is either the String representation of a single value, or is itself a Vector of the same kind.
See Also:: Get(Value)

Get_One

public String Get_One(Parameter parameter)

Gets one String value from the Get Vector.

Parameters:: parameter - The Parameter from which to get a value.
Returns:: The first String value from the Vector, or null if there is no value.
See Also:: Get(Parameter), Get_One(Vector)

Get

public static Vector Get(Value value)

Gets the value(s) for a Parameter Value.

Parameters:: value - The Value from which to get value(s).
Returns:: A Vector of zero or more values. Each element of the Vector is either the String representation of a single value, or is itself a Vector of the same kind.

Get_One

public String Get_One(Value value)

Gets one String value from the Get Vector.

Parameters:: value - The Value from which to get a value.
Returns:: The first String value from the Vector, or null if there is no value.
See Also:: Get(Value), Get_One(Vector)

Get_One

public static String Get_One(Vector values)

Gets the first String value from a Vector of values.

Parameters:: values - The Vector to search.
Returns:: The first String from the Vector, or null if none is found.
See Also:: Get_One(Vector, int)

Get_One

public static String Get_One(Vector values,
                             int index)

Gets the indexed String value from a Vector of values.

The Vector is searched for the first non-Vector Object and its toString value is returned. Vector Objects are searched as they are encountered (i.e. depth-wise). Since the Vector is presumed to be the values Vector returned from a Get method, the first non-Vector Object should be the first String value of a Configuration parameter (nevertheless, all Objects should have a toString method).

Parameters:: values - The Vector to search.; index - The index of the element in the values.
Returns:: The indexed String from the Vector, or null if none is found.

Get_Number

public double Get_Number(String pathname,
                         double default_value)

Gets a numerical value.

The first available parameter value found at the pathname is converted to a binary double value.

Parameters:: pathname - A parameter pathname.; default_value - The default value to use if the parameter can not be found.
Returns:: The numerical value of the parameter, or the default value if the parameter can not be found or does not have a numerical value.

Enabled

public boolean Enabled(String pathname,
                       boolean default_flag)

Tests if a parameter has a logically true value.

The first available parameter value found at the pathname is examined for a logically true value. A paremeter is considered to have a logically true value if it is any one of (case ignored): "ENABLED", "TRUE", "YES", "ON", "Y", or "1".

Parameters:: pathname - A parameter pathname.; default_flag - The default value to use if the parameter can not be found.
Returns:: true if the parameter has an enabled value; false otherwise. The default_flag value is returned if the parameter can not be found.

Group

public Configuration Group(String group)
                    throws Configuration_Exception

Gets the Configuration parameters for a group.

All parameters for a named group, plus all default parameters for the group, are collected into a new Configuration that will have the name of the group. Default parameters are all Assignment parameters in all parents of the group parameter. These parameters are Set_Conditionally in the new configuration such that parameters closest to the group (a parent is closer than a grandparent) have precedence when there are parameters with the same name.

If an Assignment parameter with the group name is found instead of an Aggregate parameter, its value is taken to be the name of the Aggregate parameter name to use. Such a parameter is a "link" to the actual group parameter, which gives the group parameter an "alias" name. This allows configuration parameter groups to be known by different names. Link parameters may refer to other link parameters. If the extracted configuration is an alias it will be given an ALIAS parameter having the value that is the name of the alias group.

Parameters:: group - The name of the configuration group to extract.
Returns:: A Configuration with all of the group's parameters, or null if the group could not be found.
Throws:: Configuration_Exception - If the Parameter group could not be assembled into a new Configuration.

Set

public boolean Set(String pathname,
                   Object value,
                   boolean replace)
            throws Configuration_Exception

Sets a parameter at a specified pathname location to the value of an Object.

The Object may be of any type acceptable for use in creating a Parameter Value. This includes Vectors of Objects which will set the parameter to the corresponding Value array. A null value will result in an empty, Token, parameter.

When the value of an existing parameter is not to be replaced, the availability of an Effective_Parameter is sufficient to prevent the creation of a new parameter. However, when replace is true, a parameter will be created at the specific pathname if it does not already exist. Note: If an existing parameter is found for the pathname, whether specific or effective, that does not have a value, its always assigned the new value.

Only parameters assigned a value - not parameter groups - may have their value set. If the parameter does not exist a new parameter is created and assigned the value.

Parameters:: pathname - The pathname of the parameter whose value is to be set.; value - The value that will be assigned to the parameter.; replace - If true, replace the values of existing parameters with the new value; if false, do not replace existing values.
Returns:: true if a previous value was replaced, or false if the parameter is being set for the first time.
Throws:: Configuration_Exception - If a new parameter could not be created (possibly because the pathname is null), or the value could not be set.
See Also:: Parameter.Value(Object)

Set

public boolean Set(String pathname,
                   Object value)
            throws Configuration_Exception

Sets the value of a parameter at a pathname.

A new parameter is created with the value if a parameter with the pathname does not exist. Otherwise the existing value is replaced. This is the same as using the Set method with a replace argument of true.

Parameters:: pathname - The pathname of the parameter whose value is to be set.; value - The value that will be assigned to the parameter.
Returns:: true if a previous value was replaced, or false if the parameter is being set for the first time.
Throws:: Configuration_Exception
See Also:: Set(String, Object, boolean)

Set_Conditionally

public boolean Set_Conditionally(String pathname,
                                 Object value)
                          throws Configuration_Exception

Sets the value of a new parameter at a pathname.

A new parameter is created with the value if a parameter with the pathname does not exist. Otherwise the existing value is left unchanged. This is the same as using the Set method with a replace argument of false.

Parameters:: pathname - The name of the new parameter.; value - The value that will be assigned to the parameter.
Returns:: true if a previous value was replaced, or false if the parameter is being set for the first time.
Throws:: Configuration_Exception - If there was a problem setting any parameter value.
See Also:: Set(String, Object, boolean)

Set

public void Set(String[][] parameter_table,
                boolean replace)
         throws Configuration_Exception

Sets all of the entries of an array of String arrays as Configuration parameters.

Each entry of the primary array is taken to be an array of Strings. The first String is a parameter pathname and all remaining Strings in the array are values for the parameter. A parameter pathname without any following parameter value(s) will be skipped.

Parameters:: parameter_table - The table of parameter names and values.; replace - If true, replace the values of existing parameters with the new value; if false, do not replace existing values.
Throws:: Configuration_Exception - If there was a problem setting any parameter value.
See Also:: Set(String, Object, boolean)

Set

public void Set(String[][] parameter_table)
         throws Configuration_Exception

Sets all of the entries of an array of String arrays.

An existing parameter has its value replaced, otherwise a new parameter is created

Parameters:: parameter_table - The table of parameter names and values.
Throws:: Configuration_Exception - If there was a problem setting any parameter value.
See Also:: Set(String[][], boolean), Set(String, Object)

Set_Conditionally

public void Set_Conditionally(String[][] parameter_table)
                       throws Configuration_Exception

Conditionally sets all of the entries of an array of String arrays.

New parameters are created; existing parameters are unchanged.

Parameters:: parameter_table - The table of parameter names and values.
Throws:: Configuration_Exception - If there was a problem setting any parameter value.
See Also:: Set(String[][], boolean), Set_Conditionally(String, Object)

Set

public void Set(Parameter parameter,
                boolean replace)
         throws Configuration_Exception

Sets parameters in the Configuration to correspond with the contents of another parameter.

For an Assignment parameter, a parameter in the Configuration at the same pathname location is assigned the same parameter value. For a parameter group, all of its members are recursivley set in the Configuration.

The pathname of each parameter that is set is made to appear to be rooted at the Configuration root. Thus the location of each parameter set in the Configuration will be at the same relative location of the source parameter in its own hierarchy according to its own pathname. Referencing a source parameter nested somewhere down in a hierachy will then produce a Configuration parameter that is nested down to the same relative location. However, when the intention is to root the Configuration parameters relative to the source parameter being at the root itself, then the source parameter should be copied before being provided to this method:

Set (new Parameter (parameter), replace);

Note: Freestanding source parameters (that are not located in a group hierarchy) set Configuration parameters located at the root.

Parameters:: parameter - The source Parameter for setting in the Configuration.; replace - If true, replace the values of existing parameters with the new value; if false, do not replace existing values.
Throws:: Configuration_Exception - If there was a problem setting any parameter in the Configuration.
See Also:: Set(String, Object, boolean)

Set

public void Set(Parameter parameter)
         throws Configuration_Exception

Sets parameters in the Configuration to correspond with the contents of another parameter.

An existing Configuration parameter has its value replaced, otherwise a new parameter is created

Parameters:: parameter - The source Parameter for setting in the Configuration.
Throws:: Configuration_Exception - If there was a problem setting any parameter value.
See Also:: Set(Parameter, boolean)

Set_Conditionally

public void Set_Conditionally(Parameter parameter)
                       throws Configuration_Exception

Conditionally sets parameters in the Configuration to correspond with the contents of another parameter.

New parameters are created; existing parameters are unchanged.

Parameters:: parameter - The source Parameter for setting in the Configuration.
Throws:: Configuration_Exception - If there was a problem setting any parameter value.
See Also:: Set(Parameter, boolean), Set_Conditionally(String, Object)

Set_All

public boolean Set_All(String name,
                       Object value)
                throws Configuration_Exception

Sets all occurances of a parameter with the specified name to have the specified value.

Only existing parameters have their value reset. If there are no parameters with the specified name, no new parameter is created.

Parameters:: name - The parameter name to find. This should be a simple name, not a pathname. If a pathname is specified, then only parameters at the pathname will be modified; an absolute pathname can only apply to a single parameter, but a relative pathname may apply to more than one.; value - The Object to be assigned as the value of each parameter found.
Returns:: true if at least one parameter was found, false otherwise.
Throws:: Configuration_Exception - If there was a problem replacing a parameter's value.

Remove

public boolean Remove(String pathname,
                      boolean specific)

Removes the parameter(s) at a pathname.

Parameters:: pathname - A parameter pathname.; specific - If true, remove only the parameter at the specific pathname, otherwise remove all effective parameters for the pathname.
Returns:: true if a previous value was removed, or false if there is no parameter at the pathname.

Remove

public boolean Remove(String pathname)

Removes the all of the effective parameters for the pathname.

This is the same as using the Remove method with the specific argument being false.

Parameters:: pathname - A parameter pathname.
Returns:: true If a previous value was removed, or false if there were no effective parameters for the pathname.

Remove_Specific

public boolean Remove_Specific(String pathname)

Removes the parameter at the specific pathname.

This is the same as using the Remove method with the specific argument being true.

Parameters:: pathname - A parameter pathname.
Returns:: true If a previous value was removed, or false if there was no parameter at the pathname.

Remove_Group

public boolean Remove_Group(String pathname)

Removes a group of parameters at a pathname.

The group of parameters at the pathname is removed.

Parameters:: pathname - A group pathname.
Returns:: true If a group was removed, or false if there was no group at the pathname.

Source

public String Source()

Gets the name of the source from which the Configuration parameters have been set.

Returns:: The source name String for the Configuration. This will be a source file pathname or URL if the Configuration was constructed from such a source. This will be DEFAULTS if the Configuration is based soley on the internal default parameters. It will be the Parser.CONTAINER_NAME if the Configuration was constructed from an Assignment Parameter (including an empty Parameter) rather than an Aggregate. If the Configuration was constructed from an Aggregate Parameter it will be the name of the Aggregate Parameter.

Filename

public String Filename()

Deprecated. Replaced by Source()

Gets the name of the file from which the Configuration parameters have been set.

Source

public Configuration Source(String source)
                     throws Configuration_Exception

Resets the Configuration from the contents of the source.

Parameters:: source - The name of the configuration source.
Returns:: This Configuration.
Throws:: Configuration_Exception - If the source can not be read or successfully parsed for parameters, or there was a problem coalescing the parameters (probably due to a duplicate parameter name).
See Also:: Configure(String)

Filename

public Configuration Filename(String filename)
                       throws Configuration_Exception

Deprecated. Replaced by Source(String)

Resets the Configuration from the contents of the source file.

Parameters:: filename - The name of the configuration file.
Throws:: Configuration_Exception

Default_Source

public static void Default_Source(String source)

Sets the default source name.

Parameters:: source - The name of the new default source. If null, the DEFAULTS name will be used.

Default_Filename

public static void Default_Filename(String filename)

Deprecated. Replaced by Default_Source(String)

Sets the default filename.

Parameters:: filename - The new default filename. If null, the DEFAULTS name will be used.

Default_Source

public static String Default_Source()

Gets the default source name.

Returns:: The default source name.
See Also:: Default_Source(String)

Default_Filename

public static String Default_Filename()

Deprecated. Replaced by Default_Source()

Gets the default source name.

Returns:: The default source name.

Relative_to_Class

public static void Relative_to_Class(Class related_class)

Sets the class relative to which a configuration file may be sought.

Parameters:: related_class - The Class related to the configuration file to be loaded.
See Also:: Configure(String)

Relative_to_Class

public static Class Relative_to_Class()

Gets the class relative to which a configuration file may be sought.

Returns:: The Class related to the configuration file to be loaded.
See Also:: Relative_to_Class(Class)

Case_Sensitive

public boolean Case_Sensitive(boolean enable)

Sets the case sensitive mode for finding parameter names. It is initially disabled by default.

Parameters:: enable - If true, case sensitive matching is used.
Returns:: The previous case sensitive mode;

Case_Sensitive

public boolean Case_Sensitive()

Gets the case sensitive mode for finding parameter names.

Returns:: The case sensitive mode: true if case sensitive matching is enabled.
See Also:: Case_Sensitive(boolean)

Defaults

public boolean Defaults(boolean enable)

Enables or disables automatic inclusion of Defaults parameters.

N.B.: This method controls the automatic inclusion of Defaults parameters for subsequent Configure operations. The default automatic defaults state is applied to the construction of new Configuration objects.

Parameters:: enable - true if Defaults parameters are to be automatically included; false otherwise.
Returns:: The previous automatic Defaults state.

Description

public String Description()

Provides a String description of a Configuration formatted as a list of the parameters and their values.

The description is suitable for saving to a file for later input.

Overrides:: Description in class Parameter

Returns:: The String listing all of the Configuration parameters.
See Also:: Parameter.Description(Lister)

Configure

public void Configure(String source)
               throws Configuration_Exception

Loads a Configuration from a configuration file.

If the source String is null or empty, the Default_Source String is used. If this is null the DEFAULTS name is used.

If the source String equals the DEFAULTS name the Configuration is loaded from a null stream.

If a URL can be constructred from the source String the Configuration is loaded from the URL.

An attempt is made to open a file input stream use the source String as the file's pathname. If this fails and the source String is a simple filename - it has no directory components - the user's home directory pathname is prepended and another attempt is made to open a file input stream (unless the simple filename is for the same file in the user's home directory). If a stream is opened it is used to load the Configuration.

The source String is then treated as a system resource location in the JVM classpath. This includes finding configuration files located in jar files. If this fails, a relative-to Class has been specified and the source String is a simple filename then the class's package pathname, if it can be determined, is prepended to the source name and another attempt is made to locate the system resource. If a system resource location is found the Configuration is loaded from the URL.

When a input source is found the Source is set to the name of the source. If the source is a local file the absolute pathname will be used. If the source is a URL, including a system resource location URL, the URL will be used.

Parameters:: source - A URL specification, pathname of a disk file or jar resource, or the special DEFAULTS name. If null, the Default_Source will be used.
Throws:: Configuration_Exception - If the source does not refer to a source that can be found, read or successfully parsed for parameters, or there was a problem coalescing the parameters (probably due to a duplicate parameter name).; IllegalArgumentException - If no configuration source can be found for the source name.
See Also:: Configure(URL), Configure(InputStream), Source()

Configure

public void Configure(URL url)
               throws Configuration_Exception

Loads a Configuration from a URL.

The URL is used to open an InputStream as a source of configuration parameters. If the URL is null then a null stream will be used. If a stream is successfully opened from the URL, then the Configuration's Source will be set to the URL String. The Configuration is loaded from the InputStream.

Parameters:: url - The URL source of configuration parameters. May be null.
Throws:: Configuration_Exception - If an InputStream can not be opened from the URL, the stream could not be successfully parsed for parameters, or there was a problem coalescing the parameters (probably due to a duplicate parameter name).
See Also:: Configure(InputStream)

Configure

public void Configure(InputStream stream)
               throws Configuration_Exception

Loads a Configuration from an InputStream.

The stream is parsed for configuration parameters and their values (parameter = value).

This method will first Remove_All current parameters from the Configuration. The InputStream is used to construct a Parser from which all available parameters are Added into this Configuration. If automatic Defaults are enabled the internal parameter Defaults are then Set_Conditionally. If automatic file Includes is enabled any INCLUDE parameters are found and the parameters from the files they reference are Included. Finally all parameters are Coalesced together.

If, however, the InputStream is null, then only the Defaults will be used. The Configuration's Source will be set to the special DEFAULTS name.

If this Configuration's Source is not null, then the Name will be set to the same String; otherwise it will simply be set to "InputStream."

Parameters:: stream - The InputStream source of configuration parameters.
Throws:: Configuration_Exception - If the stream can not be read or successfully parsed for parameters, or there was a problem coalescing the parameters (probably due to a duplicate parameter name).
See Also:: Parser.Parser(InputStream)

Add_Environment

public Configuration Add_Environment()
                              throws Configuration_Exception

Adds environment variables to the Configuration.

All environment variables that can be obtained from the runtime environment are added to the ENVIRONMENT group. If the group doesn't exist, it is appended to the end of the Configuration. Each environment variable is used to conditionally set a parameter in the Environment group; i.e. any existing parameters with the same name as an environment variable do not have their values changed. The value of an environment variable is always a single String regardless of embedded spaces or commas.

Returns:: This Configuration.
Throws:: Configuration_Exception
See Also:: Host.Environment()

Include

public boolean Include(boolean enable)

Enables or disables automatic Includes.

N.B.: This method controls the automatic include state for subsequent Configure operations. The Include_Default state is applied to the construction of new Configuration objects.

Parameters:: enable - true if automatic file includes is enabled; false otherwise.
Returns:: The previous automatic include state.

Include_Tracing

public boolean Include_Tracing(boolean enable)

Enables or disables Include file tracing.

Include file tracing inserts a TOKEN parameter at the beginning of the included parameters with a name of the form:

INCLUDE_START:source

where source is the URL or canonical pathname of the file that was included. At the end of the included parameters another TOKEN is inserted that has the same form, but with "START" replaced by "END". If the source can not be found and the CONTINUE_INCLUDE_ON_ERROR_FLAG is specified as the include file prefix, then a parameter with a name of the same form, but with "START" replaced by "ERROR", is inserted, and its value is the error message.

Warning: When the resulting parameters are Coalesced the included parameters may be moved to new locations outside the INCLUDE_START to INCLUDE_END sequence. Thus include file tracing can only be advisory.

N.B.: This method controls include file tracing for subsequent Configure operations. The Include_Tracing_Default state is applied to the construction of new Configuration objects.

Parameters:: enable - true if include file tracing is enabled; false otherwise.
Returns:: The previous include file tracing state.

Include

public Configuration Include()
                      throws Configuration_Exception

Includes parameters from include files.

Every parameter named INCLUDE is replaced with the parameters included from the file named by the parameter's value. The value may contain nested parameter references that are Resolved against the parameters currently in the Configuration; this includes all parameters that have been included so far.

Relative pathnames for include files are taken to be relative to the directory of the file that contains the include parameter, if this can be determined. This will be the location of the Configuration file itself for top level include parameters.

Include parameters may refer to a URL. If this is a "file" URL, then its directory can be used for relative includes contained within it. Other types of URLs may also be used, but they may not contain include parameters with relative filename references. Relative filename references that do not have a including file from which a directory can be determined (URLs or a Configuration that was not constructed from a file with an identified pathname) will be located using the same process as that used to Configure from a source name.

Recursive includes - an include parameter that refers to a parent include file - are not allowed (throw a Configuration_Exception).

Parameters that are Aggregates or the Value is an Array are ignored.

An include reference that begins with the CONTINUE_INCLUDE_ON_ERROR_FLAG will not cause an exception to be thrown if the reference can not be accessed. This is particularly useful if the existence of the include file is uncertain and its lack is acceptable.

Returns:: This Configuration.
Throws:: Configuration_Exception - If an include filename contains a nested reference that can not be resolved; would result in a recursive include; does not refer to a source that can be found, read or successfully parsed for parameters; or there was a problem coalescing its parameters (probably due to a duplicate parameter name).

Pathname_Uncle

public static String Pathname_Uncle(String pathname)

Gets the pathname for a parameter at the previous group level.

The Basename is removed from the pathname. Then the pathname is shortened by one additional segment and the basename appended back again. This has the effect of producing a pathname with the same basename but at the same level as the parent (thus it is the "uncle" to the original pathname :-). This is used when percolating up a Parameter hierarchy looking for an effective (default) parameter of a given name.

Parameters:: pathname - The pathname to modify.
Returns:: The pathname with the parent segment removed, or null if the pathname has no parent segment.

Path_Name_to_Pathname

public static String Path_Name_to_Pathname(String pathname)

Gets the Configuration pathname for a Parameter Path_Name.

A Parameter Path_Name includes the name of the root Aggregate parameter. A Configuration pathname does not include the root name segment.

Parameters:: pathname - A Parameter Path_Name.
Returns:: The pathname stripped of the root segment, or the empty String if the pathname only has a root segment.

Pathname

public static String Pathname(Parameter parameter)

Gets the Configuration pathaname for a parameter.

Parameters:: parameter - A parameter.
Returns:: The pathname String for the parameter.
See Also:: Path_Name_to_Pathname(String)

Effective_Pathname

public String Effective_Pathname(String pathname)

Gets the effective pathname for a specified pathname.

The effective pathname is the pathname of the Effective_Parameter for the pathname.

Parameters:: pathname - A parameter pathname.
Returns:: The effective pathname for the pathname, or null if there is none.

Group_Pathname

public String Group_Pathname(String group)

Gets the pathname to a parameter group.

Links will be followed: When an Assignment Parameter with the name of the group is found its value will be taken as the new group name to be sought until an Aggregate Parameter is found. A link chain is not allowed to loop back to the original group name.

Parameters:: group - The name of an Aggregate Parameter to be found.
Returns:: The fully qualified pathname to the parameter group, or null if the group can not be found.

Parameter

public Parameter Parameter(String pathname,
                           boolean specific)

Gets the parameter for a pathname.

When specific is false and there is no parameter in the Configuration at the specified pathname location, then a parameter with the same Basename is sought at progressively higher levels of the path. The first parameter found is returned, or null if no parameter is found.

Note: Only an Assignment (or Token) parameter will be found. Aggregate parameters do not qualify because they have no value. A Token has no value but can be assigned one.

Parameters:: pathname - A parameter pathname.; specific - true if only a parameter at the specific pathname is acceptable, otherwise an effective parameter will do.
Returns:: The Parameter for the pathname, or null if there is none.
See Also:: Pathname_Uncle(String)

Parameter

public Parameter Parameter(String pathname,
                           boolean specific,
                           int skip)

Gets the Nth parameter for a pathname.

The parameter is selected after skip parameters have been found that match the pathname. If skip is 0, the first matching parameter is selected; if skip is N, N matching parameters must be found before the next matching parameter will be selected.

Parameters:: pathname - A parameter pathname.; specific - true if only a parameter at the specific pathname is acceptable, otherwise an effective parameter will do.; skip - The number of matching parameters to skip.
Returns:: The Parameter for the pathname, or null if there is none found.
See Also:: Parameter(String, boolean)

Parameter_at

public Parameter Parameter_at(String pathname)

Gets the parameter or parameter group at a pathname.

Only the parameter at the specific pathname will be found. This is similar to the Parameter method used with specific=true. But unlike that method, this method may return an Aggregate if that is what is found.

Parameters:: pathname - A parameter pathname.
Returns:: The Parameter for the pathname, or null if there is none.

Specific_Parameter

public Parameter Specific_Parameter(String pathname)

Gets the specific Parameter for a pathname.

This is the same as using the Parameter method with the specfic argument being true.

Parameters:: pathname - A parameter pathname.
Returns:: The Parameter for the pathname, or null if there is none.

Effective_Parameter

public Parameter Effective_Parameter(String pathname)

Gets the effective Parameter for a pathname.

This is the same as using the Parameter method with the specific argument being false.

Parameters:: pathname - A parameter pathname.
Returns:: The effective Parameter for the pathname, or null if there is none.

Duplicate_Parameter_Action

public Configuration Duplicate_Parameter_Action(int action)

Sets the duplicate parameter action during coalescing.

One of these actions may be specified:

PREFER_FIRST_PARAMETER (>0): When a duplicate Assignment Parameter pathname is found while coalescing the Configuration, give preference to the first parameter; i.e. remove all but the first of any duplicate pathname parameters.
PREFER_LAST_PARAMETER (<0): When a duplicate Assignment Parameter pathname is found while coalescing the Configuration, give preference to the last parameter; i.e. remove all but the last of any duplicate pathname parameters.
THROW_ON_DUPLICATE_PARAMETERS (0): When a duplicate Assignment Parameter pathname is found while coalescing the Configuration, a Configuration_Exception will be thrown.

The default action is to THROW_ON_DUPLICATE_PARAMETERS.

Parameters:: action - The duplicate parameter action.
Returns:: This Configuration
See Also:: Coalesce()

Duplicate_Parameter_Action

public int Duplicate_Parameter_Action()

Gets the duplicate parameter action during coalescing.

Returns:: The default parameter action.
See Also:: Duplicate_Parameter_Action(int)

Coalesce

public void Coalesce()
              throws Configuration_Exception

Coalesce all Aggregate parameters of the same name together.

Each Aggregate in the current list is compared, by name, against all other Aggregates in the list. When a duplicate name is found the parameters it contains are added to the end of the first parameter in the list having the same name. Finally each Aggregate is recursively coalesced in the same manner.

In addition, all Assignment (i.e. non-Aggregate) parameters in each Aggregate are checked for duplicates and moved to the front of the list of parameters.

The action taken when duplicate Assignment Parameter is encountered depends on the current Duplicate_Parameter_Action. Byt default the actions is to throw a Configuration_Exception.

Throws:: Configuration_Exception - If there was a duplicate Assignment parameter and the Duplicate_Parameter_Action is THROW_ON_DUPLICATE_PARAMETERS, or there was a problem moving parameters around in the list.

main

public static void main(String[] arguments)

Assemble and report on the contents of a configuration.

The command line syntax is described by the Usage method.

Exit status:

0 - Success
1 - Command line syntax problem
2 - Unable to assemble the configuration
3 - The source file could not be found

Usage

public static void Usage()

Prints the command line usage syntax.

Usage: Configuration <Options> <source>
  Options -
    -Query | -Find <pathname>
    [-Not_]Case_sensitive
    -Pattern

Only the source of the configuration parameters is required. This may be a filename or a URL.

The entire configuration, with all included configurations, will be listed unless a specific parameter pathname is specified with the -query or -find option. The only difference between -query and -find is that the former never lists parameter comments. A parameter pathname may be absolute or relative. All parameters having the pathname will be listed. Pathname matching is not case sensitive unless the -case_sensitive option is specified. If -pattern is specified the pathname is taken to be a regular expression Pattern. The -query/-find option may be used more than once to find more than one parameter.

N.B.This method always results in a System.exit with a status of 1.

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

PIRL.Configuration Class Configuration

ID

CLASSPATH

HOST

USER

ALIAS

ENVIRONMENT

INCLUDE

Include_Default

INCLUDE_START

INCLUDE_ERROR

INCLUDE_END

Include_Tracing_Default

CONTINUE_INCLUDE_ON_ERROR_FLAG

DEFAULTS

Default_Source

Defaults

Defaults_Default

PREFER_FIRST_PARAMETER

PREFER_LAST_PARAMETER

THROW_ON_DUPLICATE_PARAMETERS

Duplicate_Parameter_Action_Default

Case_Sensitive_Default

NL

Configuration

Configuration

Configuration

Configuration

Configuration

Configuration

clone

Get

Get

Get_Specific

Get_Specific_One

Get

Get_One

Get_Linked

Get_Linked_One

Get

Get_One

Get

Get_One

Get_One

Get_One

Get_Number

Enabled

Group

Set

Set

Set_Conditionally

Set

Set

Set_Conditionally

Set

Set

Set_Conditionally

Set_All

Remove

Remove

Remove_Specific

Remove_Group

Source

Filename

Source

Filename

Default_Source

Default_Filename

Default_Source

Default_Filename

Relative_to_Class

Relative_to_Class

Case_Sensitive

Case_Sensitive

Defaults

Description

Configure

Configure

Configure

Add_Environment

PIRL.Configuration
Class Configuration