Package jade.util

Class ExtendedProperties

  • All Implemented Interfaces:
    Serializable, Serializable, Cloneable, Map<Object,​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

    • Constructor Detail

      • ExtendedProperties

        public ExtendedProperties()
        Construct empty property collection.

      • ExtendedProperties

        public ExtendedProperties​(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​(String[] args)
        For testing. Simply pass command line arguments to constructor then display all key=value pairs using sorted enumeration.

      • load

        public void load​(InputStream inStream)
          throws IOException
        Add properties from a specified InputStream. Properties will be added to any existing collection.
        Overrides:
        load in class Properties
        Parameters:
        aFileName - The name of the file.
        Throws:
        IOException - if anything goes wrong.

      • store

        public void store​(OutputStream out,
                  String header)
           throws 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 Properties
        Parameters:
        out - An output stream.
        header - A description of the property list - may be null.
        Throws:
        IOException - if anything goes wrong.

      • sortedKeys

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

      • addProperties

        public void addProperties​(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​(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​(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​(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 Object get​(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 Map<Object,​Object>
        Overrides:
        get in class Properties
        Parameters:
        aKey - Key for desired property.
        Returns:
        The object associated with this key or null if none exits.

      • put

        public Object put​(Object aKey,
                  Object aValue)
        Set property value to specified object.
        Specified by:
        put in interface Map<Object,​Object>
        Overrides:
        put in class Properties
        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 String getProperty​(String aKey)
        Override getProperty in base class so all occurances of the form ${key} are replaced by their associated value.
        Overrides:
        getProperty in class Properties
        Parameters:
        aKey - Key for desired property.
        Returns:
        The keys value with substitutions done.

      • getProperty

        public String getProperty​(String aKey,
                          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 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 Object setPropertyIfNot​(String aKey,
                               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 String getRawProperty​(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 String getPropertyIgnoreCase​(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 String valueFilter​(String key,
                             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​(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​(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​(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​(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 Object renameKey​(String existingKey,
                        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 String doSubstitutions​(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 String doSubstitutions​(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​(Reader reader)
                      throws 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:
        IOException - if anything goes wrong.

      • getOneLine

        protected String getOneLine​(Reader reader)
                     throws 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:
        IOException - if anything goes wrong.

      • readLine

        protected String readLine​(Reader aReader)
                   throws 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:
        IOException - if anything goes wrong.

      • list

        public void list​(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 Properties
        Parameters:
        out - The print stream.

      • toStringArray

        public 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[].