net.sourceforge.jezxmlconfig
Class XmlConfig

java.lang.Object
  extended bynet.sourceforge.jezxmlconfig.XmlConfig
public final class XmlConfig
extends java.lang.Object

This class provide an easy way to read, write and manage configuration parameters in a XML format file.
It is optimized to be very fast when accessing configuration parameters.

Description

For reading, defined parameter values will be directly accessible in following formats:

Supported object types:
TYPE_BOOLEAN
Parameter value must corresponds to a boolean value.
TYPE_CHAR
Parameter value must corresponds to a char value (Length must be just one character long).
TYPE_BYTE
Parameter value must corresponds to a byte value (From -128 to 127).
TYPE_SHORT
Parameter value must corresponds to a short value (From -32768 to 32767).
TYPE_INT
Parameter value must corresponds to a int value (From -2147483648 to 2147483647).
TYPE_LONG
Parameter value must corresponds to a long value (From -9223372036854775808 to 9223372036854775807).
TYPE_FLOAT
Parameter value must corresponds to a float value (see Float.parseFloat(String value) method).
TYPE_DOUBLE
Parameter value must corresponds to a double value (see Double.parseDouble(String value) method).
TYPE_BIG_INTEGER
Parameter value must corresponds to a big integer (see java.math.BigInteger method).
TYPE_BIG_DECIMAL
Parameter value must corresponds to a big decimal (see java.math.BigDecimal method).
TYPE_FILE
Parameter value must corresponds to an existing local file.
TYPE_DIR
Parameter value must corresponds to an existing local directory.
TYPE_BIT_SET
Each character of the parameter value is interpreted as a bit with following rules:
TYPE_INET_ADDRESS
Parameter value must corresponds to an existing machine on the network.
TYPE_URL
Parameter value must corresponds to an well formed URL.
And integer types (BYTE, SHORT, INT and LONG) could be in following formats (begins with a minus sign if negative):
Octal
Begins with a zero
Decimal
Begins with a digit from 1 to 9
Hexadecimal
Begins with a "#" or "0x".

Named constants could be defined. They could be used in parameter values with the ${constant_name} format.
Note: Calling an unknown constant will not raise an error: parameter value will simply appears "as is" (Without interpretation of "${}" syntax). Only strings like "${existing_constant_name}" will be replaced with constant values.

This syntax could also be used with system properties, exactly the same way as constants.

XML configuration file must be complient with following DTD: 

   <?xml version="1.0" encoding="ISO-8859-1" ?>
   <!ELEMENT configuration (constants?,parameters)>
   <!ELEMENT constants (constant+)>
   <!ELEMENT constant EMPTY>
   <!ATTLIST constant
           name CDATA #REQUIRED
           value CDATA #REQUIRED
   >
   <!ELEMENT parameters (section+)>
   <!ELEMENT section (section*,param+)>
   <!ATTLIST section
           name CDATA #REQUIRED
   >
   <!ELEMENT param EMPTY>
   <!ATTLIST param
           name CDATA #REQUIRED
           value CDATA #REQUIRED
   >

Simple use example

XML configuration file: 

   <?xml version="1.0" encoding="ISO-8859-1" ?>
   <!DOCTYPE configuration SYSTEM "XmlConfig.dtd">
   <configuration>
       <constants>
           <constant name="rootPath" value="/tmp" />
       </constants>
       <parameters>
           <section name="machines">
               <section name="gateway">
                   <param name="host" value="Jupiter" />
                   <param name="port" value="2222" />
               </section>
               <section name="comp">
                   <param name="host" value="Saturn" />
                   <param name="port" value="3333" />
               </section>
               <param name="netAdminName" value="James BOND" />
               <param name="netAdminEmail" value="jbond@007.net" />
           </section>
           <section name="applications">
               <section name="spaceNavigation">
                   <param name="localDir" value="${rootPath}/spaceNav" />
                   <param name="logFile" value="${rootPath}/spaceNav.log" />
                   <param name="units" value="parsec,light year,kilometer" />
               </section>
               <param name="numberInProd" value="0" />
           </section>
       </parameters>
   </configuration>
At main program start 
     ...

     // Get configuration instance
     XmlConfig config = XmlConfig.getInstance();

     // Load an XML configuration file
     try {
         // Variable 'myConfigFile' of type java.io.File corresponds to my existing configuration file
         config.loadFile(myConfigFile);
     }
     catch(XmlConfigException xce) {
         // Load error (File not found, not accessible, bad format...)
         xce.printStackTrace();
     }

    ...
When using parameter values 
     ...

     // Get configuration instance
     XmlConfig config = XmlConfig.getInstance(); // Or from JNDI: XmlConfig config = XmlConfig.jndiLookup("configJndiName");

     // Read parameter values:
     // Throw a XmlConfigException if a parameter is not found and a default value is not provided.
     try {
         // Computing machine name
         String host = config.getStringParameter("machines.comp", "host");

         // Communication port for computing machine
         // No possible XmlConfigException: default value DEFAULT_PORT is provided if parameter is not found
         int port = config.getIntParameter("machines.comp", "port", DEFAULT_PORT);

         // Local work directory (XmlConfigException thrown if parameter is not found)
         File localDirectory = (File)config.getObjectParameter(TYPE_DIR, "applications.spaceNavigation", "localDir");

         // Log file (XmlConfigException thrown if parameter is not found)
         File fichierLog = (File)config.getObjectParameter(TYPE_FILE, "applications.spaceNavigation", "logFile");

         // Units ("units" array will have a length of 3, and elements will be: "parsec", "light year" et "kilometer")
         String[] units = config.getMultiStringParameter("applications.spaceNavigation", "units");
     }
     catch(XmlConfigException xce) {
         // Parameter not found (detail available in xce.getMessage())
         xce.printStackTrace();
     }

     ...
You can also build and update configuration at runtime: 
     // We have never access configuration: It will be initialized empty
     XmlConfig config = XmlConfig.getInstance();

     // Add a constant
     config.addConstant("myConst", "toto");

     // Add sections
     config.addSection("general");
     config.addSection("general.version");
     config.addSection("general.detail");

     // Add parameters
     config.addParameter("general", "parametre1", "valeur1");
     config.addParameter("general.version", "type", "release");
     config.addParameter("general.version", "nom", "2.1");
     config.addParameter("general.detail", "p2", "${myConst}"); // Utilisation d'une constante définie
     config.addParameter("general.detail", "userName", "${user.name}"); // Utilisation d'une "system property"

     // Move "general.detail" section to be the "detail" root section.
     config.moveSection("general", null, "detail");

     // Rename a constant: All references to this constant in parameter values will be updated indeed...
     config.renameConstant("myConst", "newConstantName");

     ...

Version:
2.1 - august 12, 2004
Author:
Frederic DE STEUR

Field Summary
static java.lang.String CONSTANT_NAME_PREFIX
           
static java.lang.String CONSTANT_NAME_SUFFIX
           
static java.lang.String DEFAULT_SET
           
static int MODE_DEFAULT
           
static int MODE_READ_ONLY
           
static int MODE_THREAD_SAFE
           
static java.lang.String SECTION_SEPARATOR
           
static int TYPE_BIG_DECIMAL
           
static int TYPE_BIG_INTEGER
           
static int TYPE_BIT_SET
           
static int TYPE_BOOLEAN
           
static int TYPE_BYTE
           
static int TYPE_CHAR
           
static int TYPE_DIR
           
static int TYPE_DOUBLE
           
static int TYPE_FILE
           
static int TYPE_FLOAT
           
static int TYPE_INET_ADDRESS
           
static int TYPE_INT
           
static int TYPE_LONG
           
static int TYPE_SHORT
           
static int TYPE_UNKNOWN
           
static int TYPE_URL
           
 
Method Summary
 void addConstant(java.lang.String name, java.lang.String value)
          Add a constant in configuration.
 void addParameter(java.lang.String section, java.lang.String name, java.lang.String value)
          Add parameter in existing section.
 void addSection(java.lang.String name)
          Add a section in configuration.
 void addSection(java.lang.String name, boolean createParents)
          Add a section in configuration.
 void dump(java.io.PrintStream out)
          This method is provided for debug purpose.
 boolean getBooleanParameter(java.lang.String section, java.lang.String key)
          Give the boolean value of specified parameter.
 boolean getBooleanParameter(java.lang.String section, java.lang.String key, boolean defaultValue)
          Give the boolean value of specified parameter.
 java.lang.String getBrutParameter(java.lang.String sectionPath, java.lang.String paramName)
          Give a parameter brut value (without constant replacement) for specified section.
 byte getByteParameter(java.lang.String section, java.lang.String key)
          Give the byte value of specified parameter.
 byte getByteParameter(java.lang.String section, java.lang.String key, byte defaultValue)
          Give the byte value of specified parameter.
 char getCharParameter(java.lang.String section, java.lang.String key)
          Give the character value of specified parameter.
 char getCharParameter(java.lang.String section, java.lang.String key, char defaultValue)
          Give the character value of specified parameter.
 java.lang.String getConfigPath()
          Give loaded XML configuration path.
 java.lang.String getConstant(java.lang.String name)
          Give a constant value.
 java.lang.String getConstant(java.lang.String name, java.lang.String defaultValue)
          Give a constant value, or a default value if constant does not exist.
 java.lang.String[] getConstantNames()
          Give defined constant names in XML configuration file read order.
 java.io.File getCurrentFile()
          Give the file corresponding to loaded configuration.
 int getDeepestParamLevel(java.lang.String key)
          Test if a section contains parameters in itself or in its sub-sections recursively.
 double getDoubleParameter(java.lang.String section, java.lang.String key)
          Give the double precision float value of specified parameter.
 double getDoubleParameter(java.lang.String section, java.lang.String key, double defaultValue)
          Give the double precision float value of specified parameter.
 float getFloatParameter(java.lang.String section, java.lang.String key)
          Give the float value of specified parameter.
 float getFloatParameter(java.lang.String section, java.lang.String key, float defaultValue)
          Give the float value of specified parameter.
static XmlConfig getInstance()
          Give the only instance of default configuration set.
static XmlConfig getInstance(java.lang.String configSet, int mode)
          Give the only instance of specified configuration set.
 int getIntParameter(java.lang.String section, java.lang.String key)
          Give the integer value of specified parameter.
 int getIntParameter(java.lang.String section, java.lang.String key, int defaultValue)
          Give the integer value of specified parameter.
 javax.naming.Context getJndiContext()
          Get JEZXmlConfig JNDI context.
 java.lang.String getJndiName()
          Get JNDI name of current configuration.
 long getLongParameter(java.lang.String section, java.lang.String key)
          Give the long integer value of specified parameter.
 long getLongParameter(java.lang.String section, java.lang.String key, long defaultValue)
          Give the long integer value of specified parameter.
 java.lang.Object[] getMultiObjectParameter(int type, java.lang.String section, java.lang.String key)
          Give parameter multi-values for specified section.
 java.lang.Object[] getMultiObjectParameter(int type, java.lang.String section, java.lang.String key, java.lang.Object[] defaultValues)
          Give parameter multi-values for specified section.
 java.lang.Object[] getMultiObjectParameter(int type, java.lang.String section, java.lang.String key, java.lang.Object[] defaultValues, java.lang.String separator)
          Give parameter multi-values for specified section.
 java.lang.Object[] getMultiObjectParameter(int type, java.lang.String section, java.lang.String key, java.lang.String separator)
          Give parameter multi-values for specified section.
 java.lang.String[] getMultiStringParameter(java.lang.String section, java.lang.String paramName)
          Give parameter multi-values for specified section.
 java.lang.String[] getMultiStringParameter(java.lang.String section, java.lang.String paramName, java.lang.String separator)
          Give parameter multi-values for specified section.
 java.lang.String[] getMultiStringParameter(java.lang.String section, java.lang.String paramName, java.lang.String[] defaultValues)
          Give parameter multi-values for specified section.
 java.lang.String[] getMultiStringParameter(java.lang.String section, java.lang.String paramName, java.lang.String[] defaultValues, java.lang.String separator)
          Give parameter multi-values for specified section.
 java.lang.Object getObjectParameter(int type, java.lang.String section, java.lang.String key)
          Give a parameter value in specified object type.
 java.lang.Object getObjectParameter(int type, java.lang.String section, java.lang.String key, java.lang.Object defaultValue)
          Give a parameter value in specified object type.
 java.lang.String[] getParamNames(java.lang.String sectionName)
          Give parameter names of specified section in XML configuration file read order.
 java.lang.String[] getRootSectionNames()
          Give root section names.
 java.lang.String[] getSectionPaths()
          Give section list in XML configuration file read order.
 short getShortParameter(java.lang.String section, java.lang.String key)
          Give the short integer value of specified parameter.
 short getShortParameter(java.lang.String section, java.lang.String key, short defaultValue)
          Give the sort integer value of specified parameter.
 java.lang.String getStringParameter(java.lang.String sectionPath, java.lang.String paramName)
          Give a parameter value for specified section.
 java.lang.String getStringParameter(java.lang.String sectionPath, java.lang.String paramName, java.lang.String defaultValue)
          Give a parameter value for specified section.
 java.lang.String[] getSubSectionNames(java.lang.String sectionName)
          Give sub-section of specified section (non recursive).
 boolean getValidation()
          Indicate if configuration is validated with DTD.
 void insertSection(java.lang.String before, java.lang.String name)
          Insert a new section before an other sibling one.
 boolean isConstantExist(java.lang.String key)
          Test if a constant exists.
 boolean isParamExist(java.lang.String section, java.lang.String key)
          Test if a parameter exists in a section.
 boolean isSectionEmpty(java.lang.String key)
          Test if a section is empty.
 boolean isSectionExist(java.lang.String section)
          Test if a section exists.
static java.util.List jndiList()
          List available configurations from root directory of JEZXmlConfig JNDI service provider.
static java.util.List jndiList(java.lang.String subdir)
          List available configurations from specified subdirectory of JEZXmlConfig JNDI service provider.
static java.util.List jndiListAll()
          List all available configurations with full path from JEZXmlConfig JNDI service provider.
static XmlConfig jndiLookup(java.lang.String jndiName)
          Lookup given configuration from JEZXmlConfig JNDI service provider, and give an instance corresponding to it.
 void load(java.io.File configFile)
          Load specified XML configuration file in memory.
 void load(java.io.InputStream inputStream, java.lang.String path)
          Load specified XML configuration in memory from given input stream.
 void load(java.lang.String path)
          Load specified XML configuration in memory.
 void load(java.net.URL configFileUrl)
          Load specified XML configuration in memory from a given URL.
 void loadProperties(java.io.File configFile)
          Load specified property file in memory.
 void loadProperties(java.io.InputStream inputStream, java.lang.String path)
          Load specified properties in memory from given input stream.
 void loadProperties(java.lang.String path)
          Load specified properties in memory.
 void loadProperties(java.net.URL configFileUrl)
          Load specified properties in memory from a given URL.
static void main(java.lang.String[] args)
          FOR UNIT TESTS ONLY.
 void moveParameter(java.lang.String oldSection, java.lang.String newSection, java.lang.String name)
          Move a parameter from a section to another one.
 void moveSection(java.lang.String oldParent, java.lang.String newParent, java.lang.String name)
          Move a section.
static void removeAllInstances()
           
 void removeConstant(java.lang.String name)
          Delete a constant.
static void removeInstance(java.lang.String configSet)
           
 void removeParameter(java.lang.String section, java.lang.String name)
          Delete a parameter.
 void removeSection(java.lang.String name)
          Delete specified section including all its content recursively.
 void renameConstant(java.lang.String oldName, java.lang.String newName)
          Rename a constant.
 void renameParameter(java.lang.String section, java.lang.String oldName, java.lang.String newName)
          Rename a parameter.
 void renameSection(java.lang.String parent, java.lang.String simpleOldName, java.lang.String simpleNewName)
          Rename a section.
 void reset()
          Completely empty the configuration.
 void save()
          Save configuration in the same file it was loaded (or with same JNDI name if obtained from JNDI).
 void save(java.io.File outputFile)
          Save configuration content in specified file.
 void save(java.lang.String path)
          Save configuration content in specified file.
 void saveJndi()
          Save configuration with same JNDI name.
 void saveJndi(java.lang.String jndiName)
          Save configuration with given JNDI name.
 void saveJndi(java.lang.String jndiName, boolean overwrite)
          Save configuration with given JNDI name.
 void saveProperties(java.io.File outputFile)
          Save configuration content in specified file with Java properties format.
 void setValidation(boolean validate)
          Indicate if configuration content must be validated with DTD.
 void updateConstant(java.lang.String name, java.lang.String value)
          Change a constant value.
 void updateParameter(java.lang.String section, java.lang.String name, java.lang.String value)
          Change a parameter value.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SECTION_SEPARATOR

public static final java.lang.String SECTION_SEPARATOR
See Also:
Constant Field Values

CONSTANT_NAME_PREFIX

public static final java.lang.String CONSTANT_NAME_PREFIX
See Also:
Constant Field Values

CONSTANT_NAME_SUFFIX

public static final java.lang.String CONSTANT_NAME_SUFFIX
See Also:
Constant Field Values

DEFAULT_SET

public static final java.lang.String DEFAULT_SET
See Also:
Constant Field Values

MODE_DEFAULT

public static final int MODE_DEFAULT
See Also:
Constant Field Values

MODE_THREAD_SAFE

public static final int MODE_THREAD_SAFE
See Also:
Constant Field Values

MODE_READ_ONLY

public static final int MODE_READ_ONLY
See Also:
Constant Field Values

TYPE_UNKNOWN

public static final int TYPE_UNKNOWN
See Also:
Constant Field Values

TYPE_BOOLEAN

public static final int TYPE_BOOLEAN
See Also:
Constant Field Values

TYPE_CHAR

public static final int TYPE_CHAR
See Also:
Constant Field Values

TYPE_BYTE

public static final int TYPE_BYTE
See Also:
Constant Field Values

TYPE_SHORT

public static final int TYPE_SHORT
See Also:
Constant Field Values

TYPE_INT

public static final int TYPE_INT
See Also:
Constant Field Values

TYPE_LONG

public static final int TYPE_LONG
See Also:
Constant Field Values

TYPE_FLOAT

public static final int TYPE_FLOAT
See Also:
Constant Field Values

TYPE_DOUBLE

public static final int TYPE_DOUBLE
See Also:
Constant Field Values

TYPE_DIR

public static final int TYPE_DIR
See Also:
Constant Field Values

TYPE_FILE

public static final int TYPE_FILE
See Also:
Constant Field Values

TYPE_BIT_SET

public static final int TYPE_BIT_SET
See Also:
Constant Field Values

TYPE_INET_ADDRESS

public static final int TYPE_INET_ADDRESS
See Also:
Constant Field Values

TYPE_URL

public static final int TYPE_URL
See Also:
Constant Field Values

TYPE_BIG_INTEGER

public static final int TYPE_BIG_INTEGER
See Also:
Constant Field Values

TYPE_BIG_DECIMAL

public static final int TYPE_BIG_DECIMAL
See Also:
Constant Field Values
Method Detail

getValidation

public boolean getValidation()
Indicate if configuration is validated with DTD.

Returns:
true if configuration is validated with DTD.

getJndiContext

public javax.naming.Context getJndiContext()
Get JEZXmlConfig JNDI context.

Returns:
The JNDI context, or null if JNDI was never called.

getJndiName

public java.lang.String getJndiName()
Get JNDI name of current configuration.

Returns:
The JNDI name, or null/CODE> if configuration is neither obtained nor saved with JNDI.

getConfigPath

public java.lang.String getConfigPath()
Give loaded XML configuration path.

getCurrentFile

public java.io.File getCurrentFile()
Give the file corresponding to loaded configuration.

Returns:
Loaded configuration file, or null if we have loaded a configuration from an URL or a classloader relative path.

getConstantNames

public java.lang.String[] getConstantNames()
Give defined constant names in XML configuration file read order.

Returns:
A string array that contains constant names, or an empty array (not null) if no constant defined.

getConstant

public java.lang.String getConstant(java.lang.String name)
                             throws net.sourceforge.jezxmlconfig.XmlConfigException
Give a constant value.

Parameters:
name - Constant name.
Returns:
The constant value.
Throws:
XmlConfigException - If specified constant does not exist.

getConstant

public java.lang.String getConstant(java.lang.String name,
                                    java.lang.String defaultValue)
Give a constant value, or a default value if constant does not exist.

Parameters:
name - Constant name.
defaultValue - Default value.
Returns:
The constant value or specified default value if not found.

getSectionPaths

public java.lang.String[] getSectionPaths()
Give section list in XML configuration file read order.

Returns:
A string array that contains full section paths.

isSectionExist

public boolean isSectionExist(java.lang.String section)
Test if a section exists.

Parameters:
section - Full qualified section name.
Returns:
true if specified section exists.
Since:
1.4

isSectionEmpty

public boolean isSectionEmpty(java.lang.String key)
                       throws net.sourceforge.jezxmlconfig.XmlConfigException
Test if a section is empty.

Parameters:
key - Full qualified section name.
Returns:
true if specified section does not contains any sub-section or parameter.
Throws:
net.sourceforge.jezxmlconfig.XmlConfigException
Since:
1.4

isConstantExist

public boolean isConstantExist(java.lang.String key)
Test if a constant exists.

Parameters:
key - Constant name.
Returns:
true if specified constant exists.
Since:
1.4

isParamExist

public boolean isParamExist(java.lang.String section,
                            java.lang.String key)
Test if a parameter exists in a section.

Parameters:
section - Full qualified section name.
key - Parameter name.
Returns:
true if specified parameter exists.
Since:
1.4

getDeepestParamLevel

public int getDeepestParamLevel(java.lang.String key)
                         throws net.sourceforge.jezxmlconfig.XmlConfigException
Test if a section contains parameters in itself or in its sub-sections recursively.

Parameters:
key - Full qualified section name.
Returns:
-1 if specified section does not contains any parameter at any level.
0 if specified section contains parameters only at its level. N deepest level of sub-section that have parameters.
Throws:
net.sourceforge.jezxmlconfig.XmlConfigException
Since:
1.4

getRootSectionNames

public java.lang.String[] getRootSectionNames()
Give root section names.

Returns:
A string array that contains root section paths.

getSubSectionNames

public java.lang.String[] getSubSectionNames(java.lang.String sectionName)
Give sub-section of specified section (non recursive).

Parameters:
sectionName - Full qualified section name.
Returns:
A string array that contains sub-section names, or null if specified section does not exist.

getParamNames

public java.lang.String[] getParamNames(java.lang.String sectionName)
Give parameter names of specified section in XML configuration file read order.

Returns:
A string array that contains parameter names, or null if specified section does not exist.

getBrutParameter

public java.lang.String getBrutParameter(java.lang.String sectionPath,
                                         java.lang.String paramName)
                                  throws net.sourceforge.jezxmlconfig.XmlConfigException
Give a parameter brut value (without constant replacement) for specified section.
WARNING: This method is not performant.

Parameters:
sectionPath - Full qualified section name.
paramName - Parameter name.
Returns:
The parameter value.
Throws:
XmlConfigException - If specified parameter does not exist.
Since:
1.3

getStringParameter

public java.lang.String getStringParameter(java.lang.String sectionPath,
                                           java.lang.String paramName)
                                    throws net.sourceforge.jezxmlconfig.XmlConfigException
Give a parameter value for specified section.

Parameters:
sectionPath - Full qualified section name.
paramName - Parameter name.
Returns:
The parameter value.
Throws:
XmlConfigException - If specified parameter does not exist.

getStringParameter

public java.lang.String getStringParameter(java.lang.String sectionPath,
                                           java.lang.String paramName,
                                           java.lang.String defaultValue)
Give a parameter value for specified section. If specified parameter is not found, a default value is provided.

Parameters:
sectionPath - Full qualified section name.
paramName - Parameter name.
defaultValue - Default value.
Returns:
The parameter value, or specified default value if parameter does not exist.

getMultiStringParameter

public java.lang.String[] getMultiStringParameter(java.lang.String section,
                                                  java.lang.String paramName)
                                           throws net.sourceforge.jezxmlconfig.XmlConfigException
Give parameter multi-values for specified section. Values are separated in configuration file with default separator ",".

Parameters:
section - Full qualified section name.
paramName - Parameter name.
Returns:
Parameter values.
Throws:
XmlConfigException - if parameter is not found.

getMultiStringParameter

public java.lang.String[] getMultiStringParameter(java.lang.String section,
                                                  java.lang.String paramName,
                                                  java.lang.String[] defaultValues)
Give parameter multi-values for specified section. Values are separated in configuration file with default separator ",".

Parameters:
section - Full qualified section name.
paramName - Parameter name.
defaultValues - Default values.
Returns:
Parameter values, or specified default values if parameter does not exist.

getMultiStringParameter

public java.lang.String[] getMultiStringParameter(java.lang.String section,
                                                  java.lang.String paramName,
                                                  java.lang.String separator)
                                           throws net.sourceforge.jezxmlconfig.XmlConfigException
Give parameter multi-values for specified section. Values are separated in configuration file with specified separator.

Parameters:
section - Full qualified section name.
paramName - Parameter name.
separator - The separator to be used when parsing values.
Returns:
Parameter values.
Throws:
XmlConfigException - if parameter is not found.

getMultiStringParameter

public java.lang.String[] getMultiStringParameter(java.lang.String section,
                                                  java.lang.String paramName,
                                                  java.lang.String[] defaultValues,
                                                  java.lang.String separator)
Give parameter multi-values for specified section. Values are separated in configuration file with specified separator.

Parameters:
section - Full qualified section name.
paramName - Parameter name.
defaultValues - Default values.
separator - The separator to be used when parsing values.
Returns:
Parameter values, or specified default values if parameter does not exist.

getCharParameter

public char getCharParameter(java.lang.String section,
                             java.lang.String key)
                      throws net.sourceforge.jezxmlconfig.XmlConfigException
Give the character value of specified parameter.

Parameters:
section - Full qualified section name.
key - Parameter name.
Returns:
Parameter value.
Throws:
XmlConfigException - if parameter does not exist, or its value is not a valid character.

getCharParameter

public char getCharParameter(java.lang.String section,
                             java.lang.String key,
                             char defaultValue)
Give the character value of specified parameter.

Parameters:
section - Full qualified section name.
key - Parameter name.
defaultValue - Default value.
Returns:
Parameter value, or provided default one if parameter is not found or its value is not a valid character.

getByteParameter

public byte getByteParameter(java.lang.String section,
                             java.lang.String key)
                      throws net.sourceforge.jezxmlconfig.XmlConfigException
Give the byte value of specified parameter.

Value can be negative. In this case, it must begin with the minus character '-'. It can be one of following formats:

Octal
Begins with a zero
Decimal
Begins with a digit from 1 to 9
Hexadecimal
Begins with a "#" or "0x".

Parameters:
section - Full qualified section name.
key - Parameter name.
Returns:
Parameter value.
Throws:
XmlConfigException - if parameter is not found or its value is out of range or not in a valid format.

getByteParameter

public byte getByteParameter(java.lang.String section,
                             java.lang.String key,
                             byte defaultValue)
Give the byte value of specified parameter.

Value can be negative. In this case, it must begin with the minus character '-'. It can be one of following formats:

Octal
Begins with a zero
Decimal
Begins with a digit from 1 to 9
Hexadecimal
Begins with a "#" or "0x".

Parameters:
section - Full qualified section name.
key - Parameter name.
defaultValue - Default value.
Returns:
Parameter value, or specified default one if parameter is not found or its value is out of range or not in a valid format.

getShortParameter

public short getShortParameter(java.lang.String section,
                               java.lang.String key)
                        throws net.sourceforge.jezxmlconfig.XmlConfigException
Give the short integer value of specified parameter.

Value can be negative. In this case, it must begin with the minus character '-'. It can be one of following formats:

Octal
Begins with a zero
Decimal
Begins with a digit from 1 to 9
Hexadecimal
Begins with a "#" or "0x".

Parameters:
section - Full qualified section name.
key - Parameter name.
Returns:
Parameter value.
Throws:
XmlConfigException - if parameter is not found or its value is out of range or not in a valid format.

getShortParameter

public short getShortParameter(java.lang.String section,
                               java.lang.String key,
                               short defaultValue)
Give the sort integer value of specified parameter.

Value can be negative. In this case, it must begin with the minus character '-'. It can be one of following formats:

Octal
Begins with a zero
Decimal
Begins with a digit from 1 to 9
Hexadecimal
Begins with a "#" or "0x".

Parameters:
section - Full qualified section name.
key - Parameter name.
defaultValue - Default value.
Returns:
Parameter value, or specified default one if parameter is not found or its value is out of range or not in a valid format.

getIntParameter

public int getIntParameter(java.lang.String section,
                           java.lang.String key)
                    throws net.sourceforge.jezxmlconfig.XmlConfigException
Give the integer value of specified parameter.

Value can be negative. In this case, it must begin with the minus character '-'. It can be one of following formats:

Octal
Begins with a zero
Decimal
Begins with a digit from 1 to 9
Hexadecimal
Begins with a "#" or "0x".

Parameters:
section - Full qualified section name.
key - Parameter name.
Returns:
Parameter value.
Throws:
XmlConfigException - if parameter is not found or its value is out of range or not in a valid format.

getIntParameter

public int getIntParameter(java.lang.String section,
                           java.lang.String key,
                           int defaultValue)
Give the integer value of specified parameter.

Value can be negative. In this case, it must begin with the minus character '-'. It can be one of following formats:

Octal
Begins with a zero
Decimal
Begins with a digit from 1 to 9
Hexadecimal
Begins with a "#" or "0x".

Parameters:
section - Full qualified section name.
key - Parameter name.
defaultValue - Default value.
Returns:
Parameter value, or specified default one if parameter is not found or its value is out of range or not in a valid format.

getLongParameter

public long getLongParameter(java.lang.String section,
                             java.lang.String key)
                      throws net.sourceforge.jezxmlconfig.XmlConfigException
Give the long integer value of specified parameter.

Value can be negative. In this case, it must begin with the minus character '-'. It can be one of following formats:

Octal
Begins with a zero
Decimal
Begins with a digit from 1 to 9
Hexadecimal
Begins with a "#" or "0x".

Parameters:
section - Full qualified section name.
key - Parameter name.
Returns:
Parameter value.
Throws:
XmlConfigException - if parameter is not found or its value is out of range or not in a valid format.

getLongParameter

public long getLongParameter(java.lang.String section,
                             java.lang.String key,
                             long defaultValue)
Give the long integer value of specified parameter.

Value can be negative. In this case, it must begin with the minus character '-'. It can be one of following formats:

Octal
Begins with a zero
Decimal
Begins with a digit from 1 to 9
Hexadecimal
Begins with a "#" or "0x".

Parameters:
section - Full qualified section name.
key - Parameter name.
defaultValue - Default value.
Returns:
Parameter value, or specified default one if parameter is not found or its value is out of range or not in a valid format.

getFloatParameter

public float getFloatParameter(java.lang.String section,
                               java.lang.String key)
                        throws net.sourceforge.jezxmlconfig.XmlConfigException
Give the float value of specified parameter.

Value can be negative. In this case, it must begin with the minus character '-'. It can also be given in format supported by Float.parseFloat(String value) method.

If value is too large, no exception is thrown and return value is Float.POSITIVE_INFINITY or Float.NEGATIVE_INFINITY depending on sign.
This case can be tested with following code: boolean isInfinite = new Float(result).isInfinite()

Parameters:
section - Full qualified section name.
key - Parameter name.
Returns:
Parameter value.
Throws:
XmlConfigException - if parameter is not found or its value is not in a valid format.

getFloatParameter

public float getFloatParameter(java.lang.String section,
                               java.lang.String key,
                               float defaultValue)
Give the float value of specified parameter.

Value can be negative. In this case, it must begin with the minus character '-'. It can also be given in format supported by Float.parseFloat(String value) method.

If value is too large, no exception is thrown and return value is Float.POSITIVE_INFINITY or Float.NEGATIVE_INFINITY depending on sign.
This case can be tested with following code: boolean isInfinite = new Float(result).isInfinite()

Parameters:
section - Full qualified section name.
key - Parameter name.
defaultValue - Default value.
Returns:
Parameter value, or specified default one if parameter is not found or its value is not in a valid format.

getDoubleParameter

public double getDoubleParameter(java.lang.String section,
                                 java.lang.String key)
                          throws net.sourceforge.jezxmlconfig.XmlConfigException
Give the double precision float value of specified parameter.

Value can be negative. In this case, it must begin with the minus character '-'. It can also be given in format supported by Double.parseDouble(String value) method.

If value is too large, no exception is thrown and return value is Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY depending on sign.
This case can be tested with following code: boolean isInfinite = new Double(result).isInfinite()

Parameters:
section - Full qualified section name.
key - Parameter name.
Returns:
Parameter value.
Throws:
XmlConfigException - if parameter is not found or its value is not in a valid format.

getDoubleParameter

public double getDoubleParameter(java.lang.String section,
                                 java.lang.String key,
                                 double defaultValue)
Give the double precision float value of specified parameter.

Value can be negative. In this case, it must begin with the minus character '-'. It can also be given in format supported by Double.parseDouble(String value) method.

If value is too large, no exception is thrown and return value is Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY depending on sign.
This case can be tested with following code: boolean isInfinite = new Double(result).isInfinite()

Parameters:
section - Full qualified section name.
key - Parameter name.
defaultValue - Default value.
Returns:
Parameter value, or specified default one if parameter is not found or its value is not in a valid format.

getBooleanParameter

public boolean getBooleanParameter(java.lang.String section,
                                   java.lang.String key)
                            throws net.sourceforge.jezxmlconfig.XmlConfigException
Give the boolean value of specified parameter.
Following values are known "true" (case insensitive): "TRUE", "VRAI", letter "T", letter "V", "YES", "OUI", letter "Y", letter "O" or digit "1".
All other values are interpreted as "false".

Parameters:
section - Full qualified section name.
key - Parameter name.
Returns:
Parameter value.
Throws:
XmlConfigException - If specified parameter does not exist.

getBooleanParameter

public boolean getBooleanParameter(java.lang.String section,
                                   java.lang.String key,
                                   boolean defaultValue)
Give the boolean value of specified parameter. Following values are known "true" (case insensitive): "TRUE", "VRAI", letter "T", letter "V", "YES", "OUI", letter "Y", letter "O" or digit "1".
All other values are interpreted as "false".

Parameters:
section - Full qualified section name.
key - Parameter name.
defaultValue - Default value.
Returns:
Parameter value, or default one if specified parameter does not exist.

getObjectParameter

public java.lang.Object getObjectParameter(int type,
                                           java.lang.String section,
                                           java.lang.String key)
                                    throws net.sourceforge.jezxmlconfig.XmlConfigException
Give a parameter value in specified object type.

Parameters:
type - The wanted type for value (See class general documentation for more information).
section - Full qualified section name.
key - Parameter name.
Returns:
Parameter values.
Throws:
XmlConfigException - If specified parameter is not found or its value is not in a valid format.
Since:
1.3

getObjectParameter

public java.lang.Object getObjectParameter(int type,
                                           java.lang.String section,
                                           java.lang.String key,
                                           java.lang.Object defaultValue)
Give a parameter value in specified object type.

Parameters:
type - The wanted type for value (See class general documentation for more information).
section - Full qualified section name.
key - Parameter name.
defaultValue - Default value.
Returns:
Parameter values, or default one if specified parameter is not found or its value is not in a valid format.
Since:
1.3

getMultiObjectParameter

public java.lang.Object[] getMultiObjectParameter(int type,
                                                  java.lang.String section,
                                                  java.lang.String key)
                                           throws net.sourceforge.jezxmlconfig.XmlConfigException
Give parameter multi-values for specified section. Values are separated in configuration file with default separator ",".

Parameters:
type -
section - Full qualified section name.
key - Parameter name.
Returns:
Parameter values.
Throws:
XmlConfigException - If specified parameter is not found or its value is not in a valid format.
Since:
1.3

getMultiObjectParameter

public java.lang.Object[] getMultiObjectParameter(int type,
                                                  java.lang.String section,
                                                  java.lang.String key,
                                                  java.lang.Object[] defaultValues)
Give parameter multi-values for specified section. Values are separated in configuration file with default separator ",".

Parameters:
type -
section - Full qualified section name.
key - Parameter name.
defaultValues - Default values.
Returns:
Parameter values, or specified default values if parameter does not exist.
Since:
1.3

getMultiObjectParameter

public java.lang.Object[] getMultiObjectParameter(int type,
                                                  java.lang.String section,
                                                  java.lang.String key,
                                                  java.lang.String separator)
                                           throws net.sourceforge.jezxmlconfig.XmlConfigException
Give parameter multi-values for specified section. Values are separated in configuration file with specified separator.

Parameters:
type -
section - Full qualified section name.
key - Parameter name.
Returns:
Parameter values.
Throws:
XmlConfigException - If specified parameter is not found or its value is not in a valid format.
Since:
1.3

getMultiObjectParameter

public java.lang.Object[] getMultiObjectParameter(int type,
                                                  java.lang.String section,
                                                  java.lang.String key,
                                                  java.lang.Object[] defaultValues,
                                                  java.lang.String separator)
Give parameter multi-values for specified section. Values are separated in configuration file with specified separator.

Parameters:
type -
section - Full qualified section name.
key - Parameter name.
defaultValues - Default values.
Returns:
Parameter values, or specified default values if parameter does not exist.
Since:
1.3

setValidation

public void setValidation(boolean validate)
Indicate if configuration content must be validated with DTD.

Parameters:
validate - Must be true to validate XML configuration file with DTD.

addConstant

public void addConstant(java.lang.String name,
                        java.lang.String value)
                 throws net.sourceforge.jezxmlconfig.XmlConfigException
Add a constant in configuration.

Parameters:
name - constant name.
value - Constant value.
Throws:
XmlConfigException - If a constant already exist with the same name.
java.lang.SecurityException - If configuration is in readonly mode.

addSection

public void addSection(java.lang.String name)
                throws net.sourceforge.jezxmlconfig.XmlConfigException
Add a section in configuration.

Parameters:
name - Full qualified constant name.
Throws:
XmlConfigException - If section already exist or parent does not exist.
java.lang.SecurityException - If configuration is in readonly mode.

addSection

public void addSection(java.lang.String name,
                       boolean createParents)
                throws net.sourceforge.jezxmlconfig.XmlConfigException
Add a section in configuration. Parents are automaticaly created if flag is set.

Parameters:
name - Full qualified constant name.
createParents - Must be true if you want non existing parents to be automaticaly created as well.
Throws:
XmlConfigException - If section already exist or parent does not exist.
java.lang.SecurityException - If configuration is in readonly mode.
Since:
1.4

insertSection

public void insertSection(java.lang.String before,
                          java.lang.String name)
                   throws net.sourceforge.jezxmlconfig.XmlConfigException
Insert a new section before an other sibling one.

Parameters:
before - Full qualified section name of existing sibling (The new section will be inserted just before this one).
name - New section simple name.
Throws:
XmlConfigException - If section already exist, or specified sibling section does not exist.
java.lang.SecurityException - If configuration is in readonly mode.

addParameter

public void addParameter(java.lang.String section,
                         java.lang.String name,
                         java.lang.String value)
                  throws net.sourceforge.jezxmlconfig.XmlConfigException
Add parameter in existing section.

Parameters:
section - Full qualified section name.
name - Parameter name.
value - Parameter value (can contain a reference to a constant or a system property with format ${constantName}).
Throws:
XmlConfigException - If parameter already exist or if specified section does not exist.
java.lang.SecurityException - If configuration is in readonly mode.

removeConstant

public void removeConstant(java.lang.String name)
                    throws net.sourceforge.jezxmlconfig.XmlConfigException
Delete a constant.

Parameters:
name - Constant name.
Throws:
XmlConfigException - If specified constant does not exist.
java.lang.SecurityException - If configuration is in readonly mode.

removeSection

public void removeSection(java.lang.String name)
                   throws net.sourceforge.jezxmlconfig.XmlConfigException
Delete specified section including all its content recursively. All sub-sections will be deleted as well.

Parameters:
name - Full qualified section name.
Throws:
XmlConfigException - If specified section does not exist.
java.lang.SecurityException - If configuration is in readonly mode.

removeParameter

public void removeParameter(java.lang.String section,
                            java.lang.String name)
                     throws net.sourceforge.jezxmlconfig.XmlConfigException
Delete a parameter.

Parameters:
section - Full qualified section name.
name - Parameter name.
Throws:
XmlConfigException - If specified section or parameter does not exist.
java.lang.SecurityException - If configuration is in readonly mode.

renameConstant

public void renameConstant(java.lang.String oldName,
                           java.lang.String newName)
                    throws net.sourceforge.jezxmlconfig.XmlConfigException
Rename a constant.
If old and new name are identical nothing happens and this method returns normaly.
All references of this constant in configuration parameter values will be updated.

Parameters:
oldName - Old constant name.
newName - New constant name.
Throws:
XmlConfigException - If old constant does not exist or new constant already exist.
java.lang.SecurityException - If configuration is in readonly mode.

updateConstant

public void updateConstant(java.lang.String name,
                           java.lang.String value)
                    throws net.sourceforge.jezxmlconfig.XmlConfigException
Change a constant value.

Parameters:
name - Constant name.
value - New constant value.
Throws:
XmlConfigException - If specified constant does not exist.
java.lang.SecurityException - If configuration is in readonly mode.

renameSection

public void renameSection(java.lang.String parent,
                          java.lang.String simpleOldName,
                          java.lang.String simpleNewName)
                   throws net.sourceforge.jezxmlconfig.XmlConfigException
Rename a section.
If old and new name are identical nothing happens and this method returns normaly.

Note: This method just rename a section and cannot move it in an other parent section. To do that, use moveSection() method.

Parameters:
parent - Full qualified parent section name, or null if you want to rename a root section.
simpleOldName - Old simple section name.
simpleNewName - New simple section name.
Throws:
XmlConfigException - If parent section or the section itself does not exist, or new section already exist.
java.lang.SecurityException - If configuration is in readonly mode.

moveSection

public void moveSection(java.lang.String oldParent,
                        java.lang.String newParent,
                        java.lang.String name)
                 throws net.sourceforge.jezxmlconfig.XmlConfigException
Move a section.
If source and destination are identical nothing happens and this method returns normaly.

Parameters:
oldParent - Full qualified olf parent section name, or null if you want to move a root section.
newParent - Full qualified new parent section name, or null if you want the section to become a root one.
name - Simple name of section you want to move.
Throws:
XmlConfigException - If one of these following case is true:
  • The section you want to move does not exist.
  • The new parent section does not exist.
  • The new parent section already contains a section with name of the one you want to move.
java.lang.SecurityException - If configuration is in readonly mode.

renameParameter

public void renameParameter(java.lang.String section,
                            java.lang.String oldName,
                            java.lang.String newName)
                     throws net.sourceforge.jezxmlconfig.XmlConfigException
Rename a parameter.
If old and new name are identical nothing happens and this method returns normaly.

Parameters:
section - Full qualified section name.
oldName - Old parameter name.
newName - New parameter name.
Throws:
XmlConfigException - If one of these following case is true:
  • The section does not exist.
  • The parameter does not exist.
  • The section already contains a parameter with the new name.
java.lang.SecurityException - If configuration is in readonly mode.

moveParameter

public void moveParameter(java.lang.String oldSection,
                          java.lang.String newSection,
                          java.lang.String name)
                   throws net.sourceforge.jezxmlconfig.XmlConfigException
Move a parameter from a section to another one.
If source and destination are identical nothing happens and this method returns normaly.

Parameters:
oldSection - Full qualified old section name.
newSection - Full qualified new section name.
name - Parameter name.
Throws:
XmlConfigException - If one of these following case is true:
  • old or new section does not exist.
  • Parameter does not exist.
  • The new section already contains a parameter with name of the one you want to move.
java.lang.SecurityException - If configuration is in readonly mode.

updateParameter

public void updateParameter(java.lang.String section,
                            java.lang.String name,
                            java.lang.String value)
                     throws net.sourceforge.jezxmlconfig.XmlConfigException
Change a parameter value.

Parameters:
section - Full qualified section name.
name - Parameter name.
value - New parameter value (can contain a reference to a constant or a system property with format ${constantName}).
Throws:
XmlConfigException - If section or parameter does not exist.
java.lang.SecurityException - If configuration is in readonly mode.

reset

public void reset()
           throws net.sourceforge.jezxmlconfig.XmlConfigException
Completely empty the configuration.

WARNING: All constants, sections and parameters will be permanetly delete.

Throws:
XmlConfigException - If the system cannot obtain an XML document factory (No XML parser found).
java.lang.SecurityException - If configuration is in readonly mode.

save

public void save()
          throws net.sourceforge.jezxmlconfig.XmlConfigException
Save configuration in the same file it was loaded (or with same JNDI name if obtained from JNDI). Note: No effect if configuration was loaded from an URL or a classloader relative path.

Throws:
XmlConfigException - If file is readonly or an I/O exception occurs.

saveJndi

public void saveJndi()
              throws net.sourceforge.jezxmlconfig.XmlConfigException
Save configuration with same JNDI name.

Throws:
XmlConfigException - if configuration was not obtained from JNDI or if cannot be saved.

saveJndi

public void saveJndi(java.lang.String jndiName)
              throws net.sourceforge.jezxmlconfig.XmlConfigException
Save configuration with given JNDI name. No configuration must exist with specified JNDI name.

Parameters:
jndiName - JNDI name for saving configuration
Throws:
XmlConfigException - if configuration cannot be saved, or if a configuration with specified JNDI name already exist.

saveJndi

public void saveJndi(java.lang.String jndiName,
                     boolean overwrite)
              throws net.sourceforge.jezxmlconfig.XmlConfigException
Save configuration with given JNDI name.

Parameters:
jndiName - JNDI name for saving configuration.
overwrite - Must be true to successfully update a configuration on an already existing JNDI name.
Throws:
XmlConfigException - if configuration cannot be saved.

save

public void save(java.lang.String path)
          throws net.sourceforge.jezxmlconfig.XmlConfigException
Save configuration content in specified file.
If given file already exist this method overwrite it, else it is created.

Parameters:
path - File (with path) where configuration must be saved.
Throws:
XmlConfigException - If file cannot be created or overwriten, or an I/O exception occurs.

save

public void save(java.io.File outputFile)
          throws net.sourceforge.jezxmlconfig.XmlConfigException
Save configuration content in specified file.
If given file already exist this method overwrite it, else it is created.

Parameters:
outputFile - File where configuration must be saved.
Throws:
XmlConfigException - If file cannot be created or overwriten, or an I/O exception occurs.

saveProperties

public void saveProperties(java.io.File outputFile)
                    throws net.sourceforge.jezxmlconfig.XmlConfigException
Save configuration content in specified file with Java properties format.
If given file already exist this method overwrite it, else it is created.

Parameters:
outputFile - File where configuration must be saved.
Throws:
XmlConfigException - If file cannot be created or overwriten, or an I/O exception occurs.
Since:
1.4

load

public void load(java.io.File configFile)
          throws net.sourceforge.jezxmlconfig.XmlConfigException
Load specified XML configuration file in memory.

Parameters:
configFile - Configuration file.
Throws:
XmlConfigException - If specified file does not exist or cannot be read, if an I/O exception occurs, or if file content cannot be parsed correctly.
java.lang.SecurityException - If configuration is in readonly mode and a load() method have already been called.

load

public void load(java.net.URL configFileUrl)
          throws net.sourceforge.jezxmlconfig.XmlConfigException
Load specified XML configuration in memory from a given URL.

Parameters:
configFileUrl - An URL that provide an XML configuration.
Throws:
XmlConfigException - If an I/O exception occurs, or if file content cannot be parsed correctly.
java.lang.SecurityException - If configuration is in readonly mode and a load() method have already been called.

load

public void load(java.lang.String path)
          throws net.sourceforge.jezxmlconfig.XmlConfigException
Load specified XML configuration in memory.

Parameters:
path - Configuration path. Could be given with one of the following way (with priority order):
  1. An URL.
  2. A ClassLoader relative path (usefull to laod configuration in a JAR file for example).
  3. An absolute or relative disk file path.
Throws:
XmlConfigException - If specified file does not exist or cannot be read, if an I/O exception occurs, or if file content cannot be parsed correctly.
java.lang.SecurityException - If configuration is in readonly mode and a load() method have already been called.

load

public void load(java.io.InputStream inputStream,
                 java.lang.String path)
          throws net.sourceforge.jezxmlconfig.XmlConfigException
Load specified XML configuration in memory from given input stream.

Parameters:
inputStream - Input stream from which configuration will be loaded.
path - The path associated to this configuration. It is only used for display purpose (never computed or interpreted).
Throws:
XmlConfigException - If an I/O exception occurs, or file content cannot be parsed correctly.
java.lang.SecurityException - If configuration is in readonly mode and a load() method have already been called.

loadProperties

public void loadProperties(java.io.File configFile)
                    throws net.sourceforge.jezxmlconfig.XmlConfigException
Load specified property file in memory.

Warning: A parameter is always in a section. Then, in your property file, things will be interpreted as the following:

word1.word2.word3=value1
will be the parameter word3 in sub-section word2 of root section word1.
word0=value2
will be the constant word0.

Parameters:
configFile - Property file.
Throws:
XmlConfigException - If specified file does not exist or cannot be read, if an I/O exception occurs, or if file content cannot be parsed correctly.
java.lang.SecurityException - If configuration is in readonly mode and a load() method have already been called.
Since:
1.4

loadProperties

public void loadProperties(java.net.URL configFileUrl)
                    throws net.sourceforge.jezxmlconfig.XmlConfigException
Load specified properties in memory from a given URL.

Warning: A parameter is always in a section. Then, in your property file, things will be interpreted as the following:

word1.word2.word3=value1
will be the parameter word3 in sub-section word2 of root section word1.
word0=value2
will be the constant word0.

Parameters:
configFileUrl - An URL that provide data in Java properties format.
Throws:
XmlConfigException - If an I/O exception occurs, or if file content cannot be parsed correctly.
java.lang.SecurityException - If configuration is in readonly mode and a load() method have already been called.
Since:
1.4

loadProperties

public void loadProperties(java.lang.String path)
                    throws net.sourceforge.jezxmlconfig.XmlConfigException
Load specified properties in memory.

Warning: A parameter is always in a section. Then, in your property file, things will be interpreted as the following:

word1.word2.word3=value1
will be the parameter word3 in sub-section word2 of root section word1.
word0=value2
will be the constant word0.

Parameters:
path - Configuration path. Could be given with one of the following way (with priority order):
  1. An URL.
  2. A ClassLoader relative path (usefull to laod configuration in a JAR file for example).
  3. An absolute or relative disk file path.
Throws:
XmlConfigException - If specified file does not exist or cannot be read, if an I/O exception occurs, or if file content cannot be parsed correctly.
java.lang.SecurityException - If configuration is in readonly mode and a load() method have already been called.
Since:
1.4

loadProperties

public void loadProperties(java.io.InputStream inputStream,
                           java.lang.String path)
                    throws net.sourceforge.jezxmlconfig.XmlConfigException
Load specified properties in memory from given input stream.

Warning: A parameter is always in a section. Then, in your property file, things will be interpreted as the following:

word1.word2.word3=value1
will be the parameter word3 in sub-section word2 of root section word1.
word0=value2
will be the constant word0.

Parameters:
inputStream - Input stream from which configuration will be loaded.
path - The path associated to this configuration. It is only used for display purpose (never computed or interpreted).
Throws:
XmlConfigException - If an I/O exception occurs, or file content cannot be parsed correctly.
java.lang.SecurityException - If configuration is in readonly mode and a load() method have already been called.
Since:
1.4

dump

public void dump(java.io.PrintStream out)
This method is provided for debug purpose.

It displays whole configuration content as a readable text on the specified output.

Parameters:
out - The output where configuration will be dumped.

getInstance

public static XmlConfig getInstance()
                             throws net.sourceforge.jezxmlconfig.XmlConfigException
Give the only instance of default configuration set.

If this is the very first time this method is called, an empty configuration is built.

Returns:
A XmlConfig object corresponding to the only instance of default configuration set.
Throws:
XmlConfigException - Only at very first call and if XML document corresponding to an empty configuration cannot be initialized.

jndiLookup

public static XmlConfig jndiLookup(java.lang.String jndiName)
                            throws net.sourceforge.jezxmlconfig.XmlConfigException
Lookup given configuration from JEZXmlConfig JNDI service provider, and give an instance corresponding to it.

Returns:
A XmlConfig object corresponding to the only instance of default configuration set.
Throws:
XmlConfigException - Only at very first call and if XML document corresponding to an empty configuration cannot be initialized.

jndiList

public static java.util.List jndiList()
                               throws net.sourceforge.jezxmlconfig.XmlConfigException
List available configurations from root directory of JEZXmlConfig JNDI service provider.

Returns:
A list that contains available configuration JNDI names (String objects).
Throws:
XmlConfigException - If cannot access JNDI successfully.

jndiList

public static java.util.List jndiList(java.lang.String subdir)
                               throws net.sourceforge.jezxmlconfig.XmlConfigException
List available configurations from specified subdirectory of JEZXmlConfig JNDI service provider.

Parameters:
subdir - The subdirectory where we want to list configurations.
Returns:
A list that contains available configuration JNDI names (String objects).
Throws:
XmlConfigException - If cannot access JNDI successfully.

jndiListAll

public static java.util.List jndiListAll()
                                  throws net.sourceforge.jezxmlconfig.XmlConfigException
List all available configurations with full path from JEZXmlConfig JNDI service provider.

Returns:
A list that contains available configuration JNDI names (String objects).
Throws:
XmlConfigException - If cannot access JNDI successfully.

getInstance

public static XmlConfig getInstance(java.lang.String configSet,
                                    int mode)
                             throws net.sourceforge.jezxmlconfig.XmlConfigException
Give the only instance of specified configuration set.

If this is the very first time this method is called for this configuration set, an empty configuration is built.

Parameters:
configSet - The configuration set name.
mode - This parameter is only used at very first time this method is called for the specified configuration set. It will be ignored for other calls.
Following values are supported:
MODE_READONLY
If you want to forbid configuration updates.
MODE_THREAD_SAFE
You must select this mode if your configuration could be updated by different threads at the same time.
MODE_DEFAULT
Default mode is neither readonly nor thread safe.
Returns:
A XmlConfig object corresponding to the only instance of specified configuration set.
Throws:
XmlConfigException - Only at very first call and if XML document corresponding to an empty configuration cannot be initialized, or if given mode is unknown.
Since:
1.4

removeInstance

public static void removeInstance(java.lang.String configSet)

removeAllInstances

public static void removeAllInstances()

main

public static void main(java.lang.String[] args)
FOR UNIT TESTS ONLY.

This main method just load given file and displays its content on standard output using the dump() method.

One argument is needed: The file to load.