org.openadaptor.util
Class SuperProperties

java.lang.Object
  java.util.Dictionary<K,V>
      java.util.Hashtable<java.lang.Object,java.lang.Object>
          java.util.Properties
              org.openadaptor.util.SuperProperties

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.util.Map<java.lang.Object,java.lang.Object>

Direct Known Subclasses:

TypedProperties

public class SuperProperties
extends java.util.Properties
implements java.io.Serializable

 SuperProperties enhances standard properties files with the following features.

        -       line continuations
        -       #include [[+]prefix] file
        -       # comment lines
  -     ${variable} replacement in resource key and value, and #include prefix and file
  -     nested variable references are supported
  -     by default, variable references in values are evaluated when the property value
                is requested
        -       variable references in keys and #include directives are always evaluated as the
                properties file is read
        -       replace ++ with auto-incremented number in key++ = value

 SuperProperties can also read xml format properties and supports:

  -      processing instruction
  -     openadaptor namespace tags to specify use of wildcard and variable references
       in property keys, and autoincrement of property keys. For example:

 
 
 
   
     
       1
     
   
   
     
       2
     
   
   
     3
   
   
     
       
         z1
       
     
   
 
 

 Known restrictions with this version:

   -    save() method cannot save auto-numbered keys as auto-numbered keys. An
        auto-numbered key is saved with the assigned auto-number

 Now uses the dom4j libraries rather than the jdom ones (which are no longer
 being supported).
 
 

Issue316: By default SuperProperties variables aren't substituted until getProperty() called.

• So if your source/pipe/sink code passes the SuperProperties object to your own class which then treats it as a Map (ie. accesses the entries directly without calling getProperty()) then the variable substitution does not take place :-(
• The workaround exploits the copy constructor of SuperProperties which calls getProperty() on all properties and so causes the variables to be substituted:
  • Properties myProps = new SuperProperties(props, System.getProperties());

Author:

Colin Prosser, Russ Fennell

See Also:

Serialized Form

Field Summary

protected ConfigData	cfgData A ConfigData object containing all hierarchical keys/values.
(package private) static org.apache.log4j.Logger	log
(package private) static org.dom4j.Namespace	oaNamespace openadaptor XML namespace
(package private) static long	serialVersionUID
static int	UNSETVAR_KEEP_REFERENCE
static int	UNSETVAR_SET_EMPTY
static int	UNSETVAR_THROW_EXCEPTION Option values for handling unset ${variable} references
static int	VAR_KEEP_REFERENCE
static int	VAR_SET_VALUE_ON_GET Option values for handling ${variable} referemces in values.
static int	VAR_SET_VALUE_ON_LOAD

Fields inherited from class java.util.Properties

defaults

Constructor Summary

SuperProperties()
Creates an empty property list with no default values.

SuperProperties(java.util.Properties defaults)
Creates an empty property list with the specified defaults.

SuperProperties(java.util.Properties props, java.util.Properties defaults)
Creates a property list initialised from the specified properties objects and with the specified defaults.

Method Summary

protected org.dom4j.Element	addChildElement(org.dom4j.Element parent, java.lang.String tag) Adds a child node with the specified tag to the given parent element.
protected void	addNamespaceDeclarationToRoot(org.dom4j.Element node, org.dom4j.Namespace namespace)
java.lang.String	asXML() Returns the properties list represented as an XML string.
java.lang.String	asXML(boolean withComments) Returns the properties list represented as an XML string.
protected void	autoNumberPropertyKey(ConfigEntry file, int lineNo, java.lang.StringBuffer line, int index, java.lang.StringBuffer keyBuf) Process auto-number indicator (trailing '++') in a property name
java.lang.Object	clone()
protected void	delete(java.lang.StringBuffer buf, int start, int end) Delete characters from StringBuffer.
boolean	equals(java.lang.Object o) Compares the specified Object with this SuperProperties for equality.
protected int	evaluateVariable(java.lang.String resource, java.util.Hashtable varList, java.lang.StringBuffer value, int start) Recursively process ${variable} references in value of getProperty() call, where variable is a property name.
java.lang.Object	get(java.lang.Object key) Deprecated. Use getProperty()
java.lang.String[]	getComments(java.lang.String key) Returns comments associated with the specified key in this property list.
java.lang.String	getProperty(java.lang.String key) Searches for the property with the specified key in this property list.
protected java.lang.String	getProperty(java.lang.String key, int variableOption)
java.lang.String	getProperty(java.lang.String key, java.lang.String defaultValue) Searches for the property with the specified key in this property list.
SuperProperties	getSubset(java.lang.String prefix) Finds the subset of properties, if any, starting with prefix and strips prefix from the found property keys.
SuperProperties	getSubset(java.lang.String oldPrefix, java.lang.String newPrefix) Finds the subset of properties, if any, starting with oldPrefix and substitutes newPrefix for oldPrefix in the found property keys.
int	getUnsetVariableOption()
boolean	getUseRestrictedKeys() Getter/Setter methods for _useRestrictedKeys
int	getVariableOption()
(package private) boolean	isWhitespace(java.lang.String text) Determine whether a text string is empty or contains only whitespace.
protected void	load(java.io.BufferedReader rdr, java.io.File srcFile, java.lang.String prefix) Reads a standard or xml format properties list from a Reader.
void	load(java.io.File name) Reads a standard or xml format properties list from the specified file.
void	load(java.io.File name, java.lang.String prefix) Reads a standard or xml format properties list from the specified file.
void	load(java.io.InputStream in) Reads a standard or xml format properties list from an input stream.
protected void	load(java.io.InputStream in, java.io.File srcFile, java.lang.String prefix) Reads a standard or xml format properties list from an input stream.
void	load(java.lang.String filename) Reads a standard or xml format properties list from the specified file name.
void	loadXML(java.lang.String xml) Reads standard or xml format properties from a string.
static void	main(java.lang.String[] args)
protected org.dom4j.Element	makeElementPath(org.dom4j.Element xml, java.lang.String path) Finds and constructs an xml element tree given a dotted path.
protected java.io.File	makeFilePath(java.lang.String filename, java.lang.String path)
protected int	mapEscapedChar(ConfigEntry file, int lineNo, java.lang.StringBuffer line, int index, java.lang.StringBuffer valBuf, boolean isKey) Maps an escaped input character in an input line to its escaped value and returns the updated line index.
protected int	mapEscapedCharInKey(ConfigEntry file, int lineNo, java.lang.StringBuffer line, int index, java.lang.StringBuffer valBuf) Maps an escaped input character in an input key to its escaped value and returns the updated line index.
protected int	mapEscapedCharInValue(ConfigEntry file, int lineNo, java.lang.StringBuffer line, int index, java.lang.StringBuffer valBuf) Maps an escaped input character in an input value to its escaped value and returns the updated line index.
java.util.Enumeration	propertyNames() Returns an enumeration of all the keys in this property list, including the keys in the default property list.
protected int	readAssignmentOperator(ConfigEntry file, int lineNo, java.lang.StringBuffer line, int index) Process optional assignment operator part of resource setting
protected java.util.Vector	readComments(ConfigEntry file, int lineNo, java.util.Vector commentv, java.lang.String path) Adds a comment block to the ConfigEntry chain.
protected int	readEscapeSequence(ConfigEntry file, int lineNo, java.lang.StringBuffer line, int index, java.lang.StringBuffer valBuf, boolean isKey) Process an escape sequence
protected boolean	readIncludeDirective(ConfigEntry file, int lineNo, java.lang.StringBuffer line, int index, java.lang.String prefix, java.lang.String xmlPath, java.util.Vector commentv) Process a #include directive.
protected int	readPropertyKey(ConfigEntry file, int lineNo, java.lang.StringBuffer line, int index, java.lang.StringBuffer keyBuf, java.lang.String prefix, boolean isVariable) Process key name part of resource setting.
protected int	readPropertyKeyRestricted(ConfigEntry file, int lineNo, java.lang.StringBuffer line, int index, java.lang.StringBuffer keyBuf, boolean isVariable) Process key name part of resource setting or variable name using restricted character set.
protected int	readPropertyKeyUnRestricted(ConfigEntry file, int lineNo, java.lang.StringBuffer line, int index, java.lang.StringBuffer keyBuf, boolean isVariable) Process key name part of resource setting or variable name using unrestricted character set.
protected int	readPropertyValue(java.lang.String key, ConfigEntry file, int lineNo, java.lang.StringBuffer line, int index, java.lang.StringBuffer valBuf, boolean logWarning)
protected int	readPropertyValue(java.lang.String key, ConfigEntry file, int lineNo, java.lang.StringBuffer line, int index, java.lang.StringBuffer valBuf, boolean logWarning, int variableOption) Process value part of resource setting
protected void	readResource(ConfigEntry file, int lineNo, java.lang.StringBuffer line, int index, java.lang.String prefix) Process a resource setting.
protected int	readVariable(ConfigEntry file, int lineNo, java.lang.StringBuffer line, int index, java.lang.StringBuffer varBuf, int varOption) Process ${variable} reference when reading properties file, where variable is a property name.
protected void	readXMLAttributes(java.util.List attributes, ConfigEntry file, java.lang.String prefix, java.lang.String xmlPath) Reads property settings from an XML document or element attributes
protected void	readXMLContent(java.util.List content, ConfigEntry file, java.lang.String prefix, java.lang.String xmlPath) Reads property settings from XML content
void	removeProperty(java.lang.String key) Removes the property with the specified key from this property list.
protected ConfigEntry	save(ConfigEntry from, java.io.PrintWriter prnt, java.lang.String path, boolean withComments, boolean preserveIncludes, java.lang.String stripPrefix, org.dom4j.Element xml) Saves a ConfigEntry chain to the specified output writer.
void	save(java.io.OutputStream out, java.lang.String header) Deprecated. As of JDK 1.2. Use the store(OutputStream out, String header) method.
void	save(java.io.PrintWriter prnt, java.lang.String path, boolean withComments, boolean preserveIncludes, boolean asXML) Saves this property list to the specified file.
void	save(java.lang.String path, java.lang.String filename, boolean withComments, boolean preserveIncludes) Saves this property list to the specified file.
void	save(java.lang.String path, java.lang.String filename, boolean withComments, boolean preserveIncludes, boolean asXML)
protected void	saveComment(org.dom4j.Element xml, ConfigEntry entry) Saves a comment block as an XML Element
protected void	saveComment(java.io.PrintWriter prnt, ConfigEntry entry) Saves a comment block.
protected void	saveProperty(org.dom4j.Element xml, ConfigEntry entry, java.lang.String stripPrefix) Saves a resource value as an XML element.
protected void	saveProperty(java.io.PrintWriter prnt, ConfigEntry entry, java.lang.String stripPrefix) Saves a resource value.
protected java.lang.String	setCharEscapes(java.lang.String value, boolean isKey, java.lang.String extraCharsToEscape, boolean xml)
protected java.lang.String	setCharEscapesInKey(java.lang.String value) Scans a string for characters that need to be converted to an escape sequence on output and maps then to the appropriate escape sequence.
protected java.lang.String	setCharEscapesInKey(java.lang.String value, java.lang.String extraCharsToEscape)
protected java.lang.String	setCharEscapesInValue(java.lang.String value)
protected java.lang.String	setCharEscapesInValue(java.lang.String value, boolean xml)
protected java.lang.String	setCharEscapesInValue(java.lang.String value, java.lang.String extraCharsToEscape, boolean xml)
void	setComment(ConfigEntry file, int lineNo, java.lang.String text, java.lang.String path) Adds a comment string to the ConfigEntry chain.
void	setComment(ConfigEntry file, int lineNo, java.util.Vector commentv, java.lang.String path) Adds a comment block to the ConfigEntry chain.
void	setProcessingInstruction(ConfigEntry file, int lineNo, java.lang.String name, java.lang.String data, java.lang.String path) Adds an XML processing instruction to the ConfigEntry chain.
java.lang.Object	setProperty(java.lang.String key, java.lang.String value) Sets a property key/value pair.
java.lang.Object	setProperty(java.lang.String key, java.lang.String value, boolean logWarning) Sets a property key/value pair.
java.lang.Object	setProperty(java.lang.String key, java.lang.String value, ConfigEntry file, int lineno, boolean logWarning) Sets a property key/value pair.
java.lang.Object	setProperty(java.lang.String key, java.lang.String value, ConfigEntry file, int lineno, boolean logWarning, int type)
void	setUnsetVariableOption(int option)
void	setUseRestrictedKeys(boolean useRestrictedKeys)
void	setVariableOption(int option)
void	store(java.io.OutputStream out, java.lang.String header) Override Properties.store() to get required escape mappings.
protected int	unfold(java.lang.StringBuffer line, java.io.BufferedReader rdr) Unfolds input continuation lines.

Methods inherited from class java.util.Properties

list, list, loadFromXML, storeToXML, storeToXML

Methods inherited from class java.util.Hashtable

clear, contains, containsKey, containsValue, elements, entrySet, hashCode, isEmpty, keys, keySet, put, putAll, rehash, remove, size, toString, values

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

log

static org.apache.log4j.Logger log

serialVersionUID

static final long serialVersionUID

See Also:

Constant Field Values

oaNamespace

static final org.dom4j.Namespace oaNamespace

openadaptor XML namespace

VAR_SET_VALUE_ON_GET

public static final int VAR_SET_VALUE_ON_GET

Option values for handling ${variable} referemces in values. Note that VAR_KEEP_REFERENCE or VAR_SET_VALUE_ON_GET allow variable references to be preserved when properties are saved, but VAR_SET_VALUE_ON_LOAD means that the expanded value will be saved.

See Also:

Constant Field Values

VAR_SET_VALUE_ON_LOAD

public static final int VAR_SET_VALUE_ON_LOAD

See Also:

Constant Field Values

VAR_KEEP_REFERENCE

public static final int VAR_KEEP_REFERENCE

See Also:

Constant Field Values

UNSETVAR_THROW_EXCEPTION

public static final int UNSETVAR_THROW_EXCEPTION

Option values for handling unset ${variable} references

See Also:

Constant Field Values

UNSETVAR_KEEP_REFERENCE

public static final int UNSETVAR_KEEP_REFERENCE

See Also:

Constant Field Values

UNSETVAR_SET_EMPTY

public static final int UNSETVAR_SET_EMPTY

See Also:

Constant Field Values

cfgData

protected ConfigData cfgData

A ConfigData object containing all hierarchical keys/values.

Constructor Detail

SuperProperties

public SuperProperties()

Creates an empty property list with no default values.

SuperProperties

public SuperProperties(java.util.Properties defaults)

Creates an empty property list with the specified defaults.

Parameters:

defaults - the defaults.

SuperProperties

public SuperProperties(java.util.Properties props,
                       java.util.Properties defaults)

Creates a property list initialised from the specified properties objects and with the specified defaults.

Parameters:

props - the initial set of properties

defaults - the defaults to use

Method Detail

load

public void load(java.lang.String filename)
          throws java.io.IOException

Reads a standard or xml format properties list from the specified file name.

Parameters:

filename - the input files name.

Throws:

java.io.IOException - if an error occurred when reading from the input stream.

load

public void load(java.io.File name)
          throws java.io.IOException

Reads a standard or xml format properties list from the specified file.

Parameters:

name - the input File object.

Throws:

java.io.IOException - if an error occurred when reading from the input stream.

load

public void load(java.io.File name,
                 java.lang.String prefix)
          throws java.io.IOException

Reads a standard or xml format properties list from the specified file.

Parameters:

name - the input File object.

prefix - the prefix to insert before each entry.

Throws:

java.io.IOException - if an error occurred when reading from the input stream.

load

public void load(java.io.InputStream in)
          throws java.io.IOException

Reads a standard or xml format properties list from an input stream.

Overrides:

load in class java.util.Properties

Parameters:

in - the input stream.

Throws:

java.io.IOException - if an error occurred when reading from the input stream.

load

protected void load(java.io.InputStream in,
                    java.io.File srcFile,
                    java.lang.String prefix)
             throws java.io.IOException,
                    PropertyFormatException

Reads a standard or xml format properties list from an input stream.

Parameters:

in - the input stream

prefix - the prefix, if any, to prepend to resource names

Throws:

java.io.IOException - if an error occurred when reading from the input stream

PropertyFormatException - if a badly formed #include directive, variable reference, or resource setting is found

loadXML

public void loadXML(java.lang.String xml)
             throws java.io.IOException,
                    PropertyFormatException

Reads standard or xml format properties from a string.

Throws:

java.io.IOException

PropertyFormatException

load

protected void load(java.io.BufferedReader rdr,
                    java.io.File srcFile,
                    java.lang.String prefix)
             throws java.io.IOException,
                    PropertyFormatException

Reads a standard or xml format properties list from a Reader.

Parameters:

rdr - the input stream

prefix - the prefix, if any, to prepend to resource names

Throws:

java.io.IOException - if an error occurred when reading from the input stream

PropertyFormatException - if a badly formed #include directive, variable reference, or resource setting is found

readXMLContent

protected void readXMLContent(java.util.List content,
                              ConfigEntry file,
                              java.lang.String prefix,
                              java.lang.String xmlPath)
                       throws java.io.IOException

Reads property settings from XML content

Parameters:

content - the XML content

file - ConfigEntry for the file name

prefix - the prefix, if any, to prepend to resource names

xmlPath - any additional prefix implied by nested xml element path

Throws:

java.io.IOException - if error reading

readXMLAttributes

protected void readXMLAttributes(java.util.List attributes,
                                 ConfigEntry file,
                                 java.lang.String prefix,
                                 java.lang.String xmlPath)

Reads property settings from an XML document or element attributes

Parameters:

attributes - the XML document or element attributes

file - ConfigEntry for the file name

prefix - the prefix, if any, to prepend to resource names

xmlPath - any additional prefix implied by nested xml element path

makeElementPath

protected org.dom4j.Element makeElementPath(org.dom4j.Element xml,
                                            java.lang.String path)

Finds and constructs an xml element tree given a dotted path.

Parameters:

xml - the parent xml element

path - dotted path

Returns:

the leaf element represented by the path

addChildElement

protected org.dom4j.Element addChildElement(org.dom4j.Element parent,
                                            java.lang.String tag)

Adds a child node with the specified tag to the given parent element.

If the tag is special (e.g. wildcard or contains variable or or is auto-incremented) then create a special node in the openadaptor namespace to hold the tag value. A declaration of the openadaptor namespace is added to the root element if necessary.

Parameters:

parent -

tag -

Returns:

addNamespaceDeclarationToRoot

protected void addNamespaceDeclarationToRoot(org.dom4j.Element node,
                                             org.dom4j.Namespace namespace)

unfold

protected int unfold(java.lang.StringBuffer line,
                     java.io.BufferedReader rdr)
              throws java.io.IOException

Unfolds input continuation lines. Lines ending with an unescaped '\' continue to the next real line. This method contructs a single logical line from a sequence of continuation lines. Leading whitespace on a continuation line is discarded.

Parameters:

line - start line of possible continuation sequence

rdr - input reader

Returns:

number of continuation lines unfolded

Throws:

java.io.IOException - if an error occurred when reading from the input stream

readComments

protected java.util.Vector readComments(ConfigEntry file,
                                        int lineNo,
                                        java.util.Vector commentv,
                                        java.lang.String path)

Adds a comment block to the ConfigEntry chain.

Parameters:

file - the ConfigEntry for the file containing the comment block

lineNo - the line number in the containing file of the last line in the comment block

commentv - the comment block

path - if non-null, the prefix the element path is associated with

Returns:

an empty comment block vector

readIncludeDirective

protected boolean readIncludeDirective(ConfigEntry file,
                                       int lineNo,
                                       java.lang.StringBuffer line,
                                       int index,
                                       java.lang.String prefix,
                                       java.lang.String xmlPath,
                                       java.util.Vector commentv)
                                throws java.io.IOException,
                                       PropertyFormatException

Process a #include directive.

Parameters:

file - the ConfigEntry for the file containing the comment block

lineNo - the line number in the containing file of the last line in the comment block

line - the input line to process

index - the index in line to start parsing

prefix - the prefix to insert before each entry.

xmlPath - any additional prefix implied by nested xml element path

commentv - any comment block preceding the input line

Returns:

true if really an #include directive, else false (really a comment) or, an empty comment block vector if it contained a #include directive

Throws:

java.io.IOException - if an error occurred when reading from the input stream.

PropertyFormatException - if the #include directive is badly formed

readResource

protected void readResource(ConfigEntry file,
                            int lineNo,
                            java.lang.StringBuffer line,
                            int index,
                            java.lang.String prefix)
                     throws PropertyFormatException

Process a resource setting.

Parameters:

file - the ConfigEntry for the file containing the comment block

lineNo - the line number in the containing file of the last line in the comment block

line - the input line to process

index - the index in line to start parsing

Throws:

PropertyFormatException - if the resource is badly formed

readPropertyKey

protected int readPropertyKey(ConfigEntry file,
                              int lineNo,
                              java.lang.StringBuffer line,
                              int index,
                              java.lang.StringBuffer keyBuf,
                              java.lang.String prefix,
                              boolean isVariable)
                       throws PropertyFormatException

Process key name part of resource setting.

Parameters:

file - the ConfigEntry for the file containing the comment block

lineNo - the line number in the containing file of the last line in the comment block

line - the input line to process

index - the index in line to start parsing

keyBuf - storage for the key name

Returns:

updated index in line

Throws:

PropertyFormatException - if the resource is badly formed

readPropertyKeyRestricted

protected int readPropertyKeyRestricted(ConfigEntry file,
                                        int lineNo,
                                        java.lang.StringBuffer line,
                                        int index,
                                        java.lang.StringBuffer keyBuf,
                                        boolean isVariable)
                                 throws PropertyFormatException

Process key name part of resource setting or variable name using restricted character set.

Parameters:

file - the ConfigEntry for the file containing the comment block

lineNo - the line number in the containing file of the last line in the comment block

line - the input line to process

index - the index in line to start parsing

keyBuf - storage for the key name

isVariable - true if processing property name in context of ${variable} name

Returns:

updated index in line

Throws:

PropertyFormatException - if the resource is badly formed

readPropertyKeyUnRestricted

protected int readPropertyKeyUnRestricted(ConfigEntry file,
                                          int lineNo,
                                          java.lang.StringBuffer line,
                                          int index,
                                          java.lang.StringBuffer keyBuf,
                                          boolean isVariable)
                                   throws PropertyFormatException

Process key name part of resource setting or variable name using unrestricted character set.

Parameters:

file - the ConfigEntry for the file containing the comment block

lineNo - the line number in the containing file of the last line in the comment block

line - the input line to process

index - the index in line to start parsing

keyBuf - storage for the key name

isVariable - true if processing property name in context of ${variable} name

Returns:

updated index in line

Throws:

PropertyFormatException - if the resource is badly formed

readAssignmentOperator

protected int readAssignmentOperator(ConfigEntry file,
                                     int lineNo,
                                     java.lang.StringBuffer line,
                                     int index)

Process optional assignment operator part of resource setting

Parameters:

file - the ConfigEntry for the file containing the comment block

lineNo - the line number in the containing file of the last line in the comment block

line - the input line to start parsing

index - the index in line to start parsing

Returns:

updated index in line

readPropertyValue

protected int readPropertyValue(java.lang.String key,
                                ConfigEntry file,
                                int lineNo,
                                java.lang.StringBuffer line,
                                int index,
                                java.lang.StringBuffer valBuf,
                                boolean logWarning,
                                int variableOption)
                         throws PropertyFormatException

Process value part of resource setting

Parameters:

key - the property name

file - the ConfigEntry for the file containing the comment block

lineNo - the line number in the containing file of the last line in the comment block

line - the input line to process

index - the index in line to start parsing

valBuf - storage for the value

logWarning - if true, warn if key non-null and value has non-escaped trailing whitespace

Returns:

updated index in line

Throws:

PropertyFormatException - if the resource is badly formed

readPropertyValue

protected int readPropertyValue(java.lang.String key,
                                ConfigEntry file,
                                int lineNo,
                                java.lang.StringBuffer line,
                                int index,
                                java.lang.StringBuffer valBuf,
                                boolean logWarning)
                         throws PropertyFormatException

Throws:

PropertyFormatException

readEscapeSequence

protected int readEscapeSequence(ConfigEntry file,
                                 int lineNo,
                                 java.lang.StringBuffer line,
                                 int index,
                                 java.lang.StringBuffer valBuf,
                                 boolean isKey)
                          throws PropertyFormatException

Process an escape sequence

Parameters:

file - the ConfigEntry for the file containing the escape sequence

lineNo - the line number in the containing file

line - the input line

index - the index in line to start parsing

valBuf - storage for the value

Returns:

updated index in line

Throws:

PropertyFormatException - if the resource is badly formed

readVariable

protected int readVariable(ConfigEntry file,
                           int lineNo,
                           java.lang.StringBuffer line,
                           int index,
                           java.lang.StringBuffer varBuf,
                           int varOption)
                    throws PropertyFormatException

Process ${variable} reference when reading properties file, where variable is a property name. But treat as literal if trailing $ or $x where x is not {.

Parameters:

file - the ConfigEntry for the file containing the comment block

lineNo - the line number in the containing file of the last line in the comment block

line - the input line to process

index - the index in line to start parsing

varBuf - storage for the reference property value

varOption - the value of the variable handling option to use

Returns:

updated index in line

Throws:

PropertyFormatException - if the resource is badly formed

evaluateVariable

protected int evaluateVariable(java.lang.String resource,
                               java.util.Hashtable varList,
                               java.lang.StringBuffer value,
                               int start)
                        throws PropertyFormatException

Recursively process ${variable} references in value of getProperty() call, where variable is a property name.

Parameters:

resource - the resource whose value is being evaluated

varList - list of variables referenced (to detect recursion)

value - the buffer in which to expand variable values

start - the index in value to start processing

Returns:

the index immediately following the expanded variable value

Throws:

PropertyFormatException - if the variable reference is badly formed

delete

protected void delete(java.lang.StringBuffer buf,
                      int start,
                      int end)

Delete characters from StringBuffer.

autoNumberPropertyKey

protected void autoNumberPropertyKey(ConfigEntry file,
                                     int lineNo,
                                     java.lang.StringBuffer line,
                                     int index,
                                     java.lang.StringBuffer keyBuf)
                              throws PropertyFormatException

Process auto-number indicator (trailing '++') in a property name

Parameters:

file - the ConfigEntry for the file containing the comment block

lineNo - the line number in the containing file of the last line in the comment block

line - the input line to process

index - the index in line to start parsing

keyBuf - storage for the key // * @return updated index in line

Throws:

PropertyFormatException - if the resource is badly formed

getUseRestrictedKeys

public boolean getUseRestrictedKeys()

Getter/Setter methods for _useRestrictedKeys

setUseRestrictedKeys

public void setUseRestrictedKeys(boolean useRestrictedKeys)

mapEscapedCharInKey

protected int mapEscapedCharInKey(ConfigEntry file,
                                  int lineNo,
                                  java.lang.StringBuffer line,
                                  int index,
                                  java.lang.StringBuffer valBuf)
                           throws PropertyFormatException

Maps an escaped input character in an input key to its escaped value and returns the updated line index.

Parameters:

file - the ConfigEntry for the file containing the escape sequence

lineNo - the line number in the containing file

line - the input line

index - the index in line to start parsing

valBuf - storage for the value

Returns:

updated index in line

Throws:

PropertyFormatException - if the escape sequence is badly formed

mapEscapedCharInValue

protected int mapEscapedCharInValue(ConfigEntry file,
                                    int lineNo,
                                    java.lang.StringBuffer line,
                                    int index,
                                    java.lang.StringBuffer valBuf)
                             throws PropertyFormatException

Maps an escaped input character in an input value to its escaped value and returns the updated line index.

Parameters:

file - the ConfigEntry for the file containing the escape sequence

lineNo - the line number in the containing file

line - the input line

index - the index in line to start parsing

valBuf - storage for the value

Returns:

updated index in line

Throws:

PropertyFormatException - if the escape sequence is badly formed

mapEscapedChar

protected int mapEscapedChar(ConfigEntry file,
                             int lineNo,
                             java.lang.StringBuffer line,
                             int index,
                             java.lang.StringBuffer valBuf,
                             boolean isKey)
                      throws PropertyFormatException

Maps an escaped input character in an input line to its escaped value and returns the updated line index.

Parameters:

file - the ConfigEntry for the file containing the escape sequence

lineNo - the line number in the containing file

line - the input line

index - the index in line to start parsing

valBuf - storage for the value

isKey - true if the input is a key, false if it is a resource value

Returns:

updated index in line

Throws:

PropertyFormatException - if the escape sequence is badly formed

setCharEscapesInKey

protected java.lang.String setCharEscapesInKey(java.lang.String value)

Scans a string for characters that need to be converted to an escape sequence on output and maps then to the appropriate escape sequence.

setCharEscapesInKey

protected java.lang.String setCharEscapesInKey(java.lang.String value,
                                               java.lang.String extraCharsToEscape)

setCharEscapesInValue

protected java.lang.String setCharEscapesInValue(java.lang.String value)

setCharEscapesInValue

protected java.lang.String setCharEscapesInValue(java.lang.String value,
                                                 boolean xml)

setCharEscapesInValue

protected java.lang.String setCharEscapesInValue(java.lang.String value,
                                                 java.lang.String extraCharsToEscape,
                                                 boolean xml)

setCharEscapes

protected java.lang.String setCharEscapes(java.lang.String value,
                                          boolean isKey,
                                          java.lang.String extraCharsToEscape,
                                          boolean xml)

propertyNames

public java.util.Enumeration propertyNames()

Returns an enumeration of all the keys in this property list, including the keys in the default property list. Overrides Properties.propertyNames() because it calls private method enumerate() which in turn calls get() which SuperProperties now overrides.

Overrides:

propertyNames in class java.util.Properties

Returns:

an enumeration of all the keys in this property list, including the keys in the default property list.

See Also:

Enumeration, Properties.defaults

getSubset

public SuperProperties getSubset(java.lang.String oldPrefix,
                                 java.lang.String newPrefix)

Finds the subset of properties, if any, starting with oldPrefix and substitutes newPrefix for oldPrefix in the found property keys. If the subset is empty, the returned SuperProperties object will contain no properties.

Important: the returned subset does not contain wildcard entries which might be matched in a call to getProperty(). If oldPrefix contains wildcard characters only the wildcard entries with exactly that prefix will be returned.

Parameters:

oldPrefix - Prefix to use to find the subset of properties

newPrefix - The new prefix to use in place of oldPrefix

Returns:

SuperProperties object containing the requested subset.

getSubset

public SuperProperties getSubset(java.lang.String prefix)

Finds the subset of properties, if any, starting with prefix and strips prefix from the found property keys. If the subset is empty, the returned SuperProperties object will contain no properties.

Important: the returned subset does not contain wildcard entries which might be matched in a call to getProperty(). If oldPrefix contains wildcard characters only the wildcard entries with exactly that prefix will be returned.

Parameters:

prefix - Prefix to use to find the subset of properties

Returns:

SuperProperties object containing the requested subset.

equals

public boolean equals(java.lang.Object o)

Compares the specified Object with this SuperProperties for equality. Overrides Hashtable.equals() use of get() because SuperProperties now overrides get(). Note that this version of equals() should be usable with JDK 1.1.8.

Specified by:

equals in interface java.util.Map<java.lang.Object,java.lang.Object>

Overrides:

equals in class java.util.Hashtable<java.lang.Object,java.lang.Object>

Returns:

true if the specified Object is equal to this SuperProperties.

See Also:

Hashtable.equals(Object)

asXML

public java.lang.String asXML()
                       throws java.io.IOException

Returns the properties list represented as an XML string.

Throws:

java.io.IOException

asXML

public java.lang.String asXML(boolean withComments)
                       throws java.io.IOException

Returns the properties list represented as an XML string.

Parameters:

withComments - if true, include comments in the XML returned

Throws:

java.io.IOException

store

public void store(java.io.OutputStream out,
                  java.lang.String header)
           throws java.io.IOException

Override Properties.store() to get required escape mappings.

Overrides:

store in class java.util.Properties

Parameters:

out - the output stream.

header - optional comment

Throws:

java.io.IOException - If error writing to output stream

save

public void save(java.io.OutputStream out,
                 java.lang.String header)

Deprecated. As of JDK 1.2. Use the store(OutputStream out, String header) method.

Override Properties.save() method to get required escape mappings. Needed by JDK 1.1 users. Also, for compatibility with JDK 1.1 does not throw IOException.

Overrides:

save in class java.util.Properties

Parameters:

out - the output stream.

header - optional comment

save

public void save(java.lang.String path,
                 java.lang.String filename,
                 boolean withComments,
                 boolean preserveIncludes)
          throws java.io.IOException

Saves this property list to the specified file.

Parameters:

path - output path prefix.

filename - output filename.

withComments - if true saves comments.

preserveIncludes - if true preserves #include file structure otherwise #include'd values are saved as if they were read in the main properties file // * @param asXML if true, writes an xml format file

Throws:

java.io.IOException - if an error occurred when saving the output

save

public void save(java.lang.String path,
                 java.lang.String filename,
                 boolean withComments,
                 boolean preserveIncludes,
                 boolean asXML)
          throws java.io.IOException

Throws:

java.io.IOException

save

public void save(java.io.PrintWriter prnt,
                 java.lang.String path,
                 boolean withComments,
                 boolean preserveIncludes,
                 boolean asXML)
          throws java.io.IOException

Saves this property list to the specified file.

Parameters:

prnt - the output writer

path - output path prefix.

withComments - if true saves comments.

preserveIncludes - if true preserves #include file structure otherwise #include'd values are saved as if they were read in the main properties file

asXML - if true, writes an xml format file

Throws:

java.io.IOException - if an error occurred when saving the output

save

protected ConfigEntry save(ConfigEntry from,
                           java.io.PrintWriter prnt,
                           java.lang.String path,
                           boolean withComments,
                           boolean preserveIncludes,
                           java.lang.String stripPrefix,
                           org.dom4j.Element xml)
                    throws java.io.IOException

Saves a ConfigEntry chain to the specified output writer.

Parameters:

from - start of ConfigEntry chain

prnt - output writer (not used if xml document specified)

path - output path prefix.

withComments - if true saves comments.

preserveIncludes - if true preserves #include file structure otherwise #include'd values are saved as if they were read in the main properties file

stripPrefix - leading prefix to strip from preserved #include file entries

xml - if non-null, add elements to an xml document (instead of using prnt)

Throws:

java.io.IOException - if an error occurred when saving the output

makeFilePath

protected java.io.File makeFilePath(java.lang.String filename,
                                    java.lang.String path)
                             throws java.io.IOException

Throws:

java.io.IOException

saveProperty

protected void saveProperty(org.dom4j.Element xml,
                            ConfigEntry entry,
                            java.lang.String stripPrefix)

Saves a resource value as an XML element. Variable references in the value are preserved provided VAR_SET_VALUE_ON_LOAD was not set when the properties file was read, otherwise the variable values are output. Variable references in the key are not preserved.

Parameters:

xml - xml element to which to add the resource element

entry - the ConfigEntry for the resource to be saved

stripPrefix - leading prefix to remove

saveProperty

protected void saveProperty(java.io.PrintWriter prnt,
                            ConfigEntry entry,
                            java.lang.String stripPrefix)

Saves a resource value. Variable references in the value are preserved provided VAR_SET_VALUE_ON_LOAD was not set when the properties file was read, otherwise the variable values are output. Variable references in the key are not preserved.

Parameters:

prnt - output writer

entry - the ConfigEntry for the resource to be saved

stripPrefix - leading prefix to remove

saveComment

protected void saveComment(org.dom4j.Element xml,
                           ConfigEntry entry)
                    throws java.io.IOException

Saves a comment block as an XML Element

Parameters:

xml - the xml element to which to add the comment

entry - the ConfigEntry for the comment block to be saved

Throws:

java.io.IOException - if an error occurred when saving the output

saveComment

protected void saveComment(java.io.PrintWriter prnt,
                           ConfigEntry entry)
                    throws java.io.IOException

Saves a comment block.

Parameters:

prnt - output writer

entry - the ConfigEntry for the comment block to be saved

Throws:

java.io.IOException - if an error occurred when saving the output

isWhitespace

boolean isWhitespace(java.lang.String text)

Determine whether a text string is empty or contains only whitespace.

Parameters:

text - The string to check

Returns:

true if string is empty or contains only whitespace

get

public java.lang.Object get(java.lang.Object key)

Deprecated. Use getProperty()

Override Hashtable.get() to call getProperty() when the given key is a String. This method is deprecated. The getProperty() method should be used instead. It is provided only as a trap for the cases where people have erroneously coded calls to get() instead of to getProperty().

Specified by:

get in interface java.util.Map<java.lang.Object,java.lang.Object>

Overrides:

get in class java.util.Hashtable<java.lang.Object,java.lang.Object>

Parameters:

key - the property key.

Returns:

the value in this property list with the specified key value.

See Also:

Hashtable.get(Object)

getProperty

public java.lang.String getProperty(java.lang.String key)

Searches for the property with the specified key in this property list. If the key is not found in this hierarchical property list, the non-hierarchical property list, the default property list, and its defaults, recursively, are then checked. The method returns null if the property is not found.

Overrides:

getProperty in class java.util.Properties

Parameters:

key - the property key.

Returns:

the value in this property list with the specified key value.

See Also:

Properties.defaults

getProperty

protected java.lang.String getProperty(java.lang.String key,
                                       int variableOption)

getProperty

public java.lang.String getProperty(java.lang.String key,
                                    java.lang.String defaultValue)

Searches for the property with the specified key in this property list. If the key is not found in this property list, the default property list, and its defaults, recursively, are then checked. The method returns the default value argument if the property is not found.

Overrides:

getProperty in class java.util.Properties

Parameters:

key - the hashtable key.

defaultValue - a default value.

Returns:

the value in this property list with the specified key value.

See Also:

Properties.defaults

getComments

public java.lang.String[] getComments(java.lang.String key)

Returns comments associated with the specified key in this property list. The method returns null if the property is not found.

Parameters:

key - the property key.

Returns:

the comments associated with this property

setComment

public void setComment(ConfigEntry file,
                       int lineNo,
                       java.util.Vector commentv,
                       java.lang.String path)

Adds a comment block to the ConfigEntry chain.

Parameters:

file - the ConfigEntry for the file containing the comment block

lineNo - the line number in the containing file of the last line in the comment block

commentv - the comment block

path - if non-null, the prefix the element path is associated with

setComment

public void setComment(ConfigEntry file,
                       int lineNo,
                       java.lang.String text,
                       java.lang.String path)

Adds a comment string to the ConfigEntry chain.

Parameters:

file - the ConfigEntry for the file containing the comment text

lineNo - the line number in the containing file of the last line in the comment block

text - the comment string; if null, then means blank line in classic properties file

path - if non-null, the prefix the element path is associated with

setProcessingInstruction

public void setProcessingInstruction(ConfigEntry file,
                                     int lineNo,
                                     java.lang.String name,
                                     java.lang.String data,
                                     java.lang.String path)

Adds an XML processing instruction to the ConfigEntry chain.

Parameters:

file - the ConfigEntry for the file containing the comment block

lineNo - the line number in the containing file of the last line in the comment block

name - the processsing instruction name

data - if non-null, the processing instruction data

path - if non-null, the prefix the element path is associated with

setProperty

public java.lang.Object setProperty(java.lang.String key,
                                    java.lang.String value)
                             throws java.lang.IllegalArgumentException

Sets a property key/value pair.

Overrides:

setProperty in class java.util.Properties

Parameters:

key - the property name

value - the property value

Returns:

the previous value for this key (a String).

Throws:

java.lang.IllegalArgumentException

setProperty

public java.lang.Object setProperty(java.lang.String key,
                                    java.lang.String value,
                                    boolean logWarning)
                             throws java.lang.IllegalArgumentException

Sets a property key/value pair.

Parameters:

key - this propertys name

value - this propertys value

logWarning - if true, will log a warning message if this property displaces another

Returns:

the previous value for this key (a String).

Throws:

java.lang.IllegalArgumentException

setProperty

public java.lang.Object setProperty(java.lang.String key,
                                    java.lang.String value,
                                    ConfigEntry file,
                                    int lineno,
                                    boolean logWarning)
                             throws java.lang.IllegalArgumentException

Sets a property key/value pair.

Parameters:

key - this propertys name

value - this propertys value // * @param filename the associated filename

lineno - the associated line number

logWarning - if true, will log a warning message if this property displaces another // * @param type the resource type (for xml)

Returns:

the previous value for this key (a String).

Throws:

java.lang.IllegalArgumentException

setProperty

public java.lang.Object setProperty(java.lang.String key,
                                    java.lang.String value,
                                    ConfigEntry file,
                                    int lineno,
                                    boolean logWarning,
                                    int type)
                             throws java.lang.IllegalArgumentException

Throws:

java.lang.IllegalArgumentException

removeProperty

public void removeProperty(java.lang.String key)

Removes the property with the specified key from this property list. The key is also removed from the default property list.

Parameters:

key - the hashtable key.

clone

public java.lang.Object clone()

Overrides:

clone in class java.util.Hashtable<java.lang.Object,java.lang.Object>

getVariableOption

public int getVariableOption()

getUnsetVariableOption

public int getUnsetVariableOption()

setVariableOption

public void setVariableOption(int option)
                       throws java.lang.Exception

Throws:

java.lang.Exception

setUnsetVariableOption

public void setUnsetVariableOption(int option)
                            throws java.lang.Exception

Throws:

java.lang.Exception

main

public static void main(java.lang.String[] args)