jade.util
Class ExpandedProperties

java.lang.Object
  |
  +--jade.util.BasicProperties
        |
        +--jade.util.ImportableProperties
              |
              +--jade.util.EnhancedProperties
                    |
                    +--jade.util.ExpandedProperties

public class ExpandedProperties

extends EnhancedProperties

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. This class relates to four others as follows:

1. BasicProperties - This class provides the foundation class. 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}.
2. 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));
    

3. EnhancedProperties - Provides a concrete implementation of ImportableProperties useable in the J2SE (desktop) world.
4. PropertiesException - Extends RuntimeException and is thrown under various error conditions by these classes.

   Author:

   Dick Cowan - HP Labs

   Constructor Summary

   ExpandedProperties()
   Construct empty property collection.

   ExpandedProperties(java.lang.String aFileName)
   Construct properties from specified file.

   ExpandedProperties(java.lang.String[] theArgs)
   Construct properties from arguments.

   Method Summary

   protected static java.lang.String	getCommandOutput(java.lang.String aCommand, boolean isShellCommand) Execute a command and return its output as a string.
   static BasicProperties	getEnvironmentProperties() Fetch the system's environment properties and return them in an EnhancedProperties object.
   protected java.lang.String	getEnvironmentProperty(java.lang.String key) Fetch environment property by looking calling System.getProperty.
   protected BasicProperties	getEnvProperties() Used to fetch environment properties and initialize environment properties object if this is first invocation.
   java.lang.String	locatePropertyFile(java.lang.String aPropertyFileName, java.lang.String aSearchCeiling) Locate property file.
   static void	main(java.lang.String[] args) For testing.
   protected java.lang.String	scanDirectory(java.lang.String aPropertyFileName, java.lang.String aPath, int depth) Scan a directory for a property file and examine just first level of subdirectories.
   protected java.lang.String	testPropertyFile(java.lang.String aPropertyFileName) Once the property file search has expanded beyond the current directory this method is used to examine property files which match the desired name - if it contains an import directive then return the value of that directive otherwise return the name of the property file.

   Methods inherited from class jade.util.EnhancedProperties

   fileReader

   Methods inherited from class jade.util.ImportableProperties

   addFromFile, getImportKey, setImportKey, storableProperty

   Methods inherited from class jade.util.BasicProperties

   addFromReader, copyProperties, doSubstitutions, doSubstitutions, extractSubset, get, getBooleanProperty, getIntProperty, getOneLine, getProperty, getProperty, getPropertyIgnoreCase, getRawProperty, isCandidate, isolateKey, isolateValue, keys, list, load, nextArgIndex, parseArgs, parseArgument, prepareArgs, put, readLine, renameKey, setBooleanProperty, setIntProperty, setProperty, setPropertyIfNot, sortedKeys, specialHandling, store, toStringArray, valueFilter

   Methods inherited from class java.lang.Object

   clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

   Constructor Detail

   ExpandedProperties

   public ExpandedProperties()

   Construct empty property collection.

   ExpandedProperties

   public ExpandedProperties(java.lang.String[] theArgs)

   Construct properties from arguments.

   Parameters:

   theArgs - The applications original arguments.

   ExpandedProperties

   public ExpandedProperties(java.lang.String aFileName)
                      throws java.io.IOException

   Construct properties from specified file.

   Parameters:

   aFileName - The name of the properties file.

   Throws:

   java.io.IOException - if anything goes wrong.

   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.

   getEnvironmentProperty

   protected java.lang.String getEnvironmentProperty(java.lang.String key)

   Description copied from class: BasicProperties

   Fetch environment property by looking calling System.getProperty.

   Overrides:

   getEnvironmentProperty in class BasicProperties

   Tags copied from class: BasicProperties

   Parameters:

   key - The key of the desired property.

   Returns:

   The resultant property if it exists or null.

   getEnvProperties

   protected BasicProperties getEnvProperties()

   Used to fetch environment properties and initialize environment properties object if this is first invocation.

   Returns:

   Properties The environment properties.

   getEnvironmentProperties

   public static BasicProperties getEnvironmentProperties()

   Fetch the system's environment properties and return them in an EnhancedProperties object. The fetching will be done using the appropriate shell command based on the OS. Based on method initially created by David Bell.

   Returns:

   EnhancedProperties fetched from environment.

   locatePropertyFile

   public java.lang.String locatePropertyFile(java.lang.String aPropertyFileName,
                                              java.lang.String aSearchCeiling)

   Locate property file. The search follows the following algorithm:

   1. Look in current directory.
   2. Move up one level in directory and search it as well as just first level of immediate subdirectories.
   3. Repeat above step until it is found or there are no more parent directories.

   Parameters:

   aPropertyFileName - Name of desired property file.

   aSearchCeiling - If none null then this specifies the uppermost directory name where at which the search should ston.

   Returns:

   The full name of the located property file or null if not found.

   getCommandOutput

   protected static java.lang.String getCommandOutput(java.lang.String aCommand,
                                                      boolean isShellCommand)

   Execute a command and return its output as a string. If the command generates multiple lines, each line will be separated using a separator obtianed from Java's System.getProperty("line.separator"). If the command fails in any way the result will be null.

   Parameters:

   aCommand - The command to run.

   isShellCommand - If true, then the command will be prefixed with the appropriate system dependent shell invocation (cmd.exe, command.com, or /bin/sh/).

   Returns:

   String The commands output or null on failure.

   scanDirectory

   protected java.lang.String scanDirectory(java.lang.String aPropertyFileName,
                                            java.lang.String aPath,
                                            int depth)

   Scan a directory for a property file and examine just first level of subdirectories.

   Parameters:

   aPropertyFileName - Name of desired property file.

   aPath - Current full path.

   depth - Current depth - used to control recursive search depth of only first level subdirectories.

   Returns:

   The property file name or null.

   testPropertyFile

   protected java.lang.String testPropertyFile(java.lang.String aPropertyFileName)

   Once the property file search has expanded beyond the current directory this method is used to examine property files which match the desired name - if it contains an import directive then return the value of that directive otherwise return the name of the property file. If any problem are encountered reading the property file return null.

   Parameters:

   aPropertyFileName - Name of property file.

   Returns:

   The property file name or null.