jade.util

Class ExtendedProperties

java.lang.Object

java.util.Dictionary<K,V>

java.util.Hashtable<java.lang.Object,java.lang.Object>

java.util.Properties

jade.util.leap.Properties

jade.util.ExtendedProperties

All Implemented Interfaces:

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

public class ExtendedProperties
extends Properties

Provides enhanced property management.
1) Allows specifying property values containing strings of the form ${key}. Such strings are properly replaced with the value of the key variable that may represent another property, a system property or an environment variable.

2) Allows specifying boolean properties in the form -key. Such format is equivalent to key=true.

3) Allows importing properties from external property files by means of the special key import. E.g. specifying the property
import = a-property-file-name
results in automatically adding all properties defined in the specified property file

4) Allows declaring a property as read-only. In order to do that it is sufficient to end its key with a '!'. For example:

      agentClass!=com.hp.agent.Foo
 

The value of the property can be accessed including the '!' in the key or not indifferently

This class is designed to be usable in the restrictive J2ME CDC environment.

Author:

Dick Cowan - HP Labs

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	IMPORT_KEY

Fields inherited from class java.util.Properties

defaults

Constructor Summary

Constructors

Constructor and Description
ExtendedProperties() Construct empty property collection.
ExtendedProperties(java.lang.String[] propesStr) Construct a ExtendedProperties object from an array of stringified properties of the form =.

Method Summary

Modifier and Type	Method and Description
protected void	addFromReader(java.io.Reader reader) Add properties from Reader.
void	addProperties(java.lang.String[] propsStr) Add to this Properties object the stringified properties included in a given array.
protected void	addProperty(java.lang.String propStr) Add to this Properties object a stringified property of the form key = value or -key
void	copyProperties(ExtendedProperties source) Copy a data from standard Properties.
java.lang.String	doSubstitutions(java.lang.String anInputString) Replace all substrings of the form ${xxx} with the property value using the key xxx.
java.lang.String	doSubstitutions(java.lang.String anInputString, boolean allowUndefined) Replace all substrings of the form ${xxx} with the property value using the key xxx.
ExtendedProperties	extractSubset(java.lang.String prefix) Create a new Properties object by coping those properties whose key begins with a particular prefix string.
java.lang.Object	get(java.lang.Object aKey) Get the object associated with a key.
boolean	getBooleanProperty(java.lang.String aKey, boolean aDefaultValue) Extract a string value ("true" or "false") and convert it to a boolean.
int	getIntProperty(java.lang.String aKey, int aDefaultValue) Extract a string value and convert it to an integer.
protected java.lang.String	getOneLine(java.io.Reader reader) Get a logical line.
java.lang.String	getProperty(java.lang.String aKey) Override getProperty in base class so all occurances of the form ${key} are replaced by their associated value.
java.lang.String	getProperty(java.lang.String aKey, java.lang.String defaultValue) Perform substitution when a value is fetched.
java.lang.String	getPropertyIgnoreCase(java.lang.String aKey) Use this method to fetch a property ignoring case of key.
java.lang.String	getRawProperty(java.lang.String aKey) Fetch property value for key which may contain strings of the form ${key}.
protected int	getSeparatorIndex(java.lang.String propStr) Retrieve the position of the first valid key-value separator character ('=' or ':') in a stringified property.
void	list(java.io.PrintStream out) List properties to provided PrintStream.
void	load(java.io.InputStream inStream) Add properties from a specified InputStream.
static void	main(java.lang.String[] args) For testing.
java.lang.Object	put(java.lang.Object aKey, java.lang.Object aValue) Set property value to specified object.
protected java.lang.String	readLine(java.io.Reader aReader) Read one line from the Reader.
java.lang.Object	renameKey(java.lang.String existingKey, java.lang.String newKey) Change key string associated with existing value.
void	setBooleanProperty(java.lang.String aKey, boolean aValue) Store a boolean as a string ("true" or "false") with the specified key.
int	setIntProperty(java.lang.String aKey, int aValue) Store an int as a string with the specified key.
java.lang.Object	setPropertyIfNot(java.lang.String aKey, java.lang.String value) Set property value only if its not set already.
java.util.Enumeration	sortedKeys() Return a sorted enumeration of this properties keys.
void	store(java.io.OutputStream out, java.lang.String header) Writes this property collection to the output stream in a format suitable for loading into a Properties table using the load method.
java.lang.String[]	toStringArray() Create a String[] for the properties with one key=value pair per array entry.
protected java.lang.String	valueFilter(java.lang.String key, java.lang.String value) Called by getProperty(key, default) to perform any post processing of the value string.

Methods inherited from class jade.util.leap.Properties

load, store, toLeapProperties

Methods inherited from class java.util.Properties

list, load, loadFromXML, propertyNames, save, setProperty, store, storeToXML, storeToXML, stringPropertyNames

Methods inherited from class java.util.Hashtable

clear, clone, compute, computeIfAbsent, computeIfPresent, contains, containsKey, containsValue, elements, entrySet, equals, forEach, getOrDefault, hashCode, isEmpty, keys, keySet, merge, putAll, putIfAbsent, rehash, remove, remove, replace, replace, replaceAll, size, toString, values

Methods inherited from class java.lang.Object

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

Field Detail

IMPORT_KEY

public static final java.lang.String IMPORT_KEY

See Also:

Constant Field Values

Constructor Detail

ExtendedProperties

public ExtendedProperties()

Construct empty property collection.

ExtendedProperties

public ExtendedProperties(java.lang.String[] propesStr)

Construct a ExtendedProperties object from an array of stringified properties of the form =.

Parameters:

propesStr - The applications original arguments.

Method Detail

main

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

For testing. Simply pass command line arguments to constructor then display all key=value pairs using sorted enumeration.

load

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

Add properties from a specified InputStream. Properties will be added to any existing collection.

Overrides:

load in class java.util.Properties

Parameters:

aFileName - The name of the file.

Throws:

java.io.IOException - if anything goes wrong.

store

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

Writes this property collection to the output stream in a format suitable for loading into a Properties table using the load method.

Overrides:

store in class java.util.Properties

Parameters:

out - An output stream.

header - A description of the property list - may be null.

Throws:

java.io.IOException - if anything goes wrong.

sortedKeys

public java.util.Enumeration sortedKeys()

Return a sorted enumeration of this properties keys.

Returns:

Enumeration Sorted enumeration.

addProperties

public void addProperties(java.lang.String[] propsStr)

Add to this Properties object the stringified properties included in a given array.

Parameters:

propsStr - The array of stringified properties. If null, this method does nothing.

addProperty

protected void addProperty(java.lang.String propStr)

Add to this Properties object a stringified property of the form key = value or -key

Parameters:

propStr - The string representation of the property to be parsed

getSeparatorIndex

protected int getSeparatorIndex(java.lang.String propStr)

Retrieve the position of the first valid key-value separator character ('=' or ':') in a stringified property.

Parameters:

propStr - The stringified property.

copyProperties

public void copyProperties(ExtendedProperties source)

Copy a data from standard Properties.

Parameters:

source - The properties to copy from.

extractSubset

public ExtendedProperties extractSubset(java.lang.String prefix)

Create a new Properties object by coping those properties whose key begins with a particular prefix string. The prefix is removed from the keys inserted into the extracted Properties object

Parameters:

prefix - The prefix string. Ex: "server."

get

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

Get the object associated with a key. Note that, unlike getProperty(), this method does not perform substitutions of variables of the form ${x} in property values since such values may be non-string objects.

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:

aKey - Key for desired property.

Returns:

The object associated with this key or null if none exits.

put

public java.lang.Object put(java.lang.Object aKey,
                            java.lang.Object aValue)

Set property value to specified object.

Specified by:

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

Overrides:

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

Parameters:

aKey - The key used to store the data. The key may contain strings of the form ${key} which will be evaluated first.

aValue - The object to be stored.

Returns:

The previous value of the specified key, or null if it did not have one.

getProperty

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

Override getProperty in base class so all occurances of the form ${key} are replaced by their associated value.

Overrides:

getProperty in class java.util.Properties

Parameters:

aKey - Key for desired property.

Returns:

The keys value with substitutions done.

getProperty

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

Perform substitution when a value is fetched. Traps circular definitions, and calls valueFilter with value prior to returning it.

Overrides:

getProperty in class java.util.Properties

Parameters:

aKey - The property key.

defaultValue - Value to return if property not defined. May be null. If non null it will be passes to valueFilter first.

Returns:

The resultant value - could be null or empty.

Throws:

PropertiesException - if circular definition.

setPropertyIfNot

public java.lang.Object setPropertyIfNot(java.lang.String aKey,
                                         java.lang.String value)

Set property value only if its not set already.

Parameters:

aKey - The key used to store the data. The key may contain strings of the form ${key} which will be evaluated first.

value - The value to be stored.

Returns:

Null if store was done, non-null indicates store not done and the returned value in the current properties value.

getRawProperty

public java.lang.String getRawProperty(java.lang.String aKey)

Fetch property value for key which may contain strings of the form ${key}.

Parameters:

aKey - Key for desired property.

Returns:

The keys value with no substitutions done.

getPropertyIgnoreCase

public java.lang.String getPropertyIgnoreCase(java.lang.String aKey)

Use this method to fetch a property ignoring case of key.

Parameters:

aKey - The key of the environment property.

Returns:

The key's value or null if not found.

valueFilter

protected java.lang.String valueFilter(java.lang.String key,
                                       java.lang.String value)

Called by getProperty(key, default) to perform any post processing of the value string. By default, this method provides special processing on the value associated with any property whose key name has the string "path" as part of it (ex: "classpath", "sourcepath", "mypath"). When the value for such keys is fetched any occurance of '|' will be converted to a ':' on Unix systems and a ';' on Windows systems. Therefore to increase the direct reuse of your property files, always use a '|' as a separator and always assign a key name which has "path" as part of it.

Parameters:

key - The properties key.

value - The properties value.

Returns:

String New potentially altered value.

getIntProperty

public int getIntProperty(java.lang.String aKey,
                          int aDefaultValue)

Extract a string value and convert it to an integer. If there isn't one or there is a problem with the conversion, return the default value.

Parameters:

aKey - The key which will be used to fetch the attribute.

aDefaultValue - Specifies the default value for the int.

Returns:

int The result.

setIntProperty

public int setIntProperty(java.lang.String aKey,
                          int aValue)

Store an int as a string with the specified key.

Parameters:

aKey - The key which will be used to store the attribute.

aValue - The int value.

getBooleanProperty

public boolean getBooleanProperty(java.lang.String aKey,
                                  boolean aDefaultValue)

Extract a string value ("true" or "false") and convert it to a boolean. If there isn't one or there is a problem with the conversion, return the default value.

Parameters:

aKey - The key which will be used to fetch the attribute.

aDefaultValue - Specifies the default value for the boolean.

Returns:

boolean The result.

setBooleanProperty

public void setBooleanProperty(java.lang.String aKey,
                               boolean aValue)

Store a boolean as a string ("true" or "false") with the specified key.

Parameters:

aKey - The key which will be used to store the attribute.

aValue - The boolean value.

renameKey

public java.lang.Object renameKey(java.lang.String existingKey,
                                  java.lang.String newKey)

Change key string associated with existing value.

Parameters:

existintKey - The current key.

newKey - The new key.

Returns:

Non null is former value of object associated with new key. Null indicates that either the existing key didn't exist or there was no former value associated with the new key. i.e. null => success.

doSubstitutions

public java.lang.String doSubstitutions(java.lang.String anInputString)

Replace all substrings of the form ${xxx} with the property value using the key xxx. Calls doSubstitutions(anInputString, false).

Parameters:

anInputString - The input string - may be null.

Returns:

The resultant line with all substitutions done or null if input string was.

doSubstitutions

public java.lang.String doSubstitutions(java.lang.String anInputString,
                                        boolean allowUndefined)

Replace all substrings of the form ${xxx} with the property value using the key xxx. If the key is all caps then the property is considered to be a system property.

Parameters:

anInputString - The input string - may be null.

allowUndefined - If true, undefined strings will remain as is, if false, an exception will be thrown.

Returns:

The resultant line with all substitutions done or null if input string was.

addFromReader

protected void addFromReader(java.io.Reader reader)
                      throws java.io.IOException

Add properties from Reader. Explicitly handled so as to enable handling of import= directive. Blank lines as well as those beginning with a '#' character (comments) are ignored.

Parameters:

reader - The buffered reader to read from. to catch circular imports.

Throws:

java.io.IOException - if anything goes wrong.

getOneLine

protected java.lang.String getOneLine(java.io.Reader reader)
                               throws java.io.IOException

Get a logical line. Any physical line ending in '\' is considered to continue on the next line.

Parameters:

reader - The input reader to read.

Returns:

The resultant logical line which may have been constructed from one or more physical lines.

Throws:

java.io.IOException - if anything goes wrong.

readLine

protected java.lang.String readLine(java.io.Reader aReader)
                             throws java.io.IOException

Read one line from the Reader. A line may be terminated by a single CR or LF, or the pair CR LF.

Parameters:

aReader - The Reader to read characters from.

Returns:

Next physical line.

Throws:

java.io.IOException - if anything goes wrong.

list

public void list(java.io.PrintStream out)

List properties to provided PrintStream. Output will be in sorted key sequence. If a value is null, it will appear as "key=".

Overrides:

list in class java.util.Properties

Parameters:

out - The print stream.

toStringArray

public java.lang.String[] toStringArray()

Create a String[] for the properties with one key=value pair per array entry. If a value is null, it will appear as "key=".

Returns:

The resultant String[].