jade.util
Class BasicProperties

java.lang.Object
  |
  +--jade.util.BasicProperties
Direct Known Subclasses:
ImportableProperties

public class BasicProperties
extends java.lang.Object

Provides the foundation class for property management. It is designed to be usable in the restrictive J2ME CLDC environment. It provides enhanced property management as well as providing support for values containing strings of the form ${key}.

A property may be set such that it can't be altered by ending the key value with a '!'. For example:

      agentClass!=com.hp.agent.Foo
 
One still references this property as ${agentClass}.

This class relates to four others as follows:

  1. ImportableProperties - This abstract class extends BasicProperties and serves as a basis for supporting the ability to import properties from files. Those files may also contain further import dirrectives. It is also usable in the restrictive J2ME CLDC environment. Since file support will be handled differently in different environments, it contains one abstract method fileReader which given the name of a file (its URL) must return a Reader object. Extending classes will provide that method in a suitable fashion. For example, in the desktop world this would be:
          return new InputStreamReader(new FileInputStream(aFileName));
     
    whereas in the CLDC environment it would be:
     
          return new InputStreamReader(Connector.openInputStream(aFileName));
     
  2. EnhancedProperties - Provides a concrete implementation of ImportableProperties useable in the J2SE (desktop) world.
  3. ExpandedProperties - Extends EnhancedProperties and adds support for fetching system environment variables (those usable from the OS shell). This class would need to be carefully considered in different environments.
  4. PropertiesException - Extends RuntimeException and is thrown under various error conditions by these classes.
Properties presented via parseArgs or read from an input stream may be specified in either of two formats: key=value or key:value. To substitute the value of a key in a value use the format ${key}.

Author:
Dick Cowan - HP Labs

Constructor Summary
BasicProperties()
          Construct empty property collection.
BasicProperties(java.lang.String[] theArgs)
          Construct properties from arguments.
 
Method Summary
protected  void addFromReader(java.io.Reader reader)
          Add properties from Reader.
 void copyProperties(BasicProperties 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.
 BasicProperties extractSubset(java.lang.String anArgPrefix)
          Create a new PropertiesCollection from this one by coping those attributes which begin with a particular prefix string.
 java.lang.Object get(java.lang.String 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.
protected  java.lang.String getEnvironmentProperty(java.lang.String key)
          Fetch environment property by looking calling System.getProperty.
 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  boolean isCandidate(java.lang.String arg)
          Called by parseArgument to determine if an argument is a candidate key, value combination.
protected  java.lang.String isolateKey(java.lang.String arg)
          Called by parseArgument to extract the key component from an argument.
protected  java.lang.String isolateValue(java.lang.String arg)
          Called by parseArgument to extract the value component from the current argument.
 java.util.Enumeration keys()
           
 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.
protected  int nextArgIndex(java.lang.String[] args, int argIndex)
          Called by parseArgs to set the next argument index.
 void parseArgs(java.lang.String[] args)
          Parse the arguments and place them in this properties collection.
protected  void parseArgument(java.lang.String arg)
          Called to handle either an argument or line from an import file.
protected  java.lang.String[] prepareArgs(java.lang.String[] args)
          Called by parseArgs to perform any preprocessing of the arguments.
 java.lang.Object put(java.lang.String 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 setProperty(java.lang.String aKey, java.lang.String aValue)
          Set property value.
 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 enumertion of this properties keys.
protected  void specialHandling(java.lang.String arg)
          Called by parseArgument when the isCandidate method returns false.
protected  boolean storableProperty(java.lang.String key, java.lang.String value)
          Called by parseArgument as a final step prior to actually storing the key=value pair.
 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 java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

BasicProperties

public BasicProperties()
Construct empty property collection.

BasicProperties

public BasicProperties(java.lang.String[] theArgs)
Construct properties from arguments.
Parameters:
theArgs - 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.
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.
Parameters:
out - An output stream.
header - A description of the property list - may be null.
Throws:
java.io.IOException - if anything goes wrong.

keys

public java.util.Enumeration keys()

sortedKeys

public java.util.Enumeration sortedKeys()
Return a sorted enumertion of this properties keys.
Returns:
Enumeration Sorted enumeration.

parseArgs

public void parseArgs(java.lang.String[] args)
Parse the arguments and place them in this properties collection. This method uses a number of protected helper methods to accomplish its parsing. This enables an extending class to easily change its behavior without completely replacing this method. For additional understanding see prepareArgs, isCandidate, specialHandling, isolateKey, isolateValue, and nextArgIndex.
Parameters:
args - The array of arguments - typically from a command line. If null, this method does nothing.

parseArgument

protected void parseArgument(java.lang.String arg)
Called to handle either an argument or line from an import file.
Parameters:
arg - The argument or line. Typically of the form key=value.

prepareArgs

protected java.lang.String[] prepareArgs(java.lang.String[] args)
Called by parseArgs to perform any preprocessing of the arguments. By default this method does nothing and simply returns the parameter its passed. However an extending class could override this method to modify the original arguments if necessary.
Parameters:
args - The original arguments passed to parseArgs.
Returns:
String[] The collection which parseArgs will actually use.

isCandidate

protected boolean isCandidate(java.lang.String arg)
Called by parseArgument to determine if an argument is a candidate key, value combination. By default this method will return true if the argument similar to any of the following:
  1. key=value
  2. key:value
  3. -key This form is a shorthand for key:true
An extending class may override this method to implement a different strategy for recognizing candidates.
Parameters:
arg - The argument being processed.
Returns:
True if it is a candidate, false if not.

specialHandling

protected void specialHandling(java.lang.String arg)
Called by parseArgument when the isCandidate method returns false. This allows an extending class to override this method and provide whatever special processing may be required. The default behavior is simply to throw a PropertiesException indicating which property was unrecognized.
Parameters:
arg - The argument being processed.

isolateKey

protected java.lang.String isolateKey(java.lang.String arg)
Called by parseArgument to extract the key component from an argument.
Parameters:
arg - The argument being processed.
index - Index into args of current argument.

isolateValue

protected java.lang.String isolateValue(java.lang.String arg)
Called by parseArgument to extract the value component from the current argument. By default, any value of the form 'hello world' will be returned as "hello world". A value of '' (two single quotes) will be returned as an empty string. An argument of the form "key=" will return null for its value and cause the key to be removed from the properties.
Parameters:
arg - The argument being processed.
Returns:
String The resultant value, may be null.

storableProperty

protected boolean storableProperty(java.lang.String key,
                                   java.lang.String value)
Called by parseArgument as a final step prior to actually storing the key=value pair. By default it simply returns true, which directs parseArgs to store the pair. An extending class could change this behavior to say look for something special such as an import directive and take different action.
Parameters:
key - The key string.
value - The value string.
Returns:
True if the key=value pair should be stored, false otherwise.

nextArgIndex

protected int nextArgIndex(java.lang.String[] args,
                           int argIndex)
Called by parseArgs to set the next argument index. By default it simply returns the current index + 1.
Returns:
int If the returned value is negative or greater than or equal to args.length, parseArgs will stop parsing. Otherwise parseArgs will use the returned value as its next index.

copyProperties

public void copyProperties(BasicProperties source)
Copy a data from standard Properties.
Parameters:
source - The Hashtable to copy from.

extractSubset

public BasicProperties extractSubset(java.lang.String anArgPrefix)
Create a new PropertiesCollection from this one by coping those attributes which begin with a particular prefix string. The prefix of selected attributes is deleted when those keys are placed in the new collection.
Parameters:
anArgPrefix - The prefix string. Ex: "server."

get

public java.lang.Object get(java.lang.String aKey)
Get the object associated with a key.
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.String aKey,
                            java.lang.Object aValue)
Set property value to specified 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.
Parameters:
aKey - Key for desired property.
Returns:
The keys value with substitutions done.

setProperty

public java.lang.Object setProperty(java.lang.String aKey,
                                    java.lang.String aValue)
Set property value. If value is null the property (key and value) will be removed.
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 value to be stored, if null they property will be removed.
Returns:
The previous value of the specified key, or null if it did not have one.

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.

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.
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.

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.

getEnvironmentProperty

protected java.lang.String getEnvironmentProperty(java.lang.String key)
Fetch environment property by looking calling System.getProperty.
Parameters:
key - The key of the desired property.
Returns:
The resultant property if it exists or null.

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=".
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[].