Package edu.uiuc.ncsa.security.core.configuration

Class XProperties

  • All Implemented Interfaces:
    Serializable, Cloneable, Map<Object,​Object>
    Direct Known Subclasses:
    NSProperties, XXProperties
    public class XProperties
extends Properties
    A subclass of java.util.Properties with many, many features. This is huge, boring and extremely useful.

    Usage

    This may be used wherever a Properties object may be used.

    Lifecycle

    Instantiate as needed. Since this is a subclass of Properties, it is effectively a replacement for it.

    The specific problems it solves are as follows.

    • methods for saving/getting specific types (see below) This saves having a lot of little snippets to make things like dates and numbers over and over. Also, error handling is better and only runtime exceptions are ever thrown.
    • methods for adding (vs. simply replacing) values from another property file
    • methods for loading from other sources without replacing all the properties
    • a few more convenient constructors

    There is a main method to test this. It takes a single argument which is a file name which will be created (thereby allowing a test of writing a file and reading it.)

    Property types

    Here is a list of the types supported. The type is given in the first column and either the suffix for the setter of getter is given (so Int as an entry means there are two methods named setInt and getInt) or the explicit names of these are given. The last column gives a bit more description.

    Property Summary
    Type Set/Get Description
    java.util.Date Date A standard Java date. This is actually stored as a long.
    integer Int An integer.
    long Long A long
    String String A string. Note that the values are escaped in the resulting properties file.
    boolean Boolean A boolean value. This automatically parses values of
    yes, on, enable(d), ok, true, yup, yeah, 1
    to be logical true and
    false,no, disable(d), nope, off, nay, 0
    to be logical false. These are case insensitive. If the value is not recognized an exception is thrown.
    bytes array Bytes This will store or retrieve an arbitrary array of bytes
    url, uri URL, URI urls and uris.
    double Double a double value
    serializable java object Serializable Works if the object implements the java.io.Serializable interface.
    serializable list SerializableList An array of java objects each of which implements the java.io.Serializable interface.
    file getFile(key), getFile(key, parent), setFileName This will store a file name in the properties. There are two getters, so that if the users needs to resolve the file against a specific parent (vs. the java default of the invocation directory) it may be done.
    Version:
    1.0
    Author:
    Jeff Gaynor
    See Also:
    Serialized Form

    • Field Detail

      • DEFAULT_LIST_SEPARATOR

        public static String DEFAULT_LIST_SEPARATOR
        The default separator for lists. This is a comma.

      • storeFileName

        protected String storeFileName

      • LOGICAL_TRUES

        public static String[] LOGICAL_TRUES
        Strings that this will treat as equivalent to logical true.

      • LOGICAL_FALSES

        public static String[] LOGICAL_FALSES
        Strings this will treat as equivalent to logical false.

    • Constructor Detail

      • XProperties

        public XProperties()
        Creates a new instance of XProperty

      • XProperties

        public XProperties​(String fileName)
        Convenience method. This loads all the properties in the given file.
        Parameters:
        fileName -

      • XProperties

        public XProperties​(File file)
        Create a new XProperties object by parsing a properties file.
        Parameters:
        file - the (standard) properties file.

      • XProperties

        public XProperties​(Properties p)
        Same as the constructor in the superclass, this gives this object all the same properties as the argument.

        Grrrrr this is busted in the super class (!!). This works here...

      • XProperties

        public XProperties​(Properties[] sources,
                   boolean overwrite)
        This will allow for an array of Properties objects. Note that the order is important if overwriting is enabled, since this starts with an empty properties list so earlier sources have right of way over later ones.
        Parameters:
        sources - an array of Properties
        overwrite -

      • XProperties

        public XProperties​(Properties[] sources,
                   boolean[] overwrite)
        This will instantiate the properties taking the value ssupplied. Each given source Properties object as an associated flag indicating overwrite permission. Therefore, order is important for loading these.
        Parameters:
        sources -
        overwrite -

    • Method Detail

      • getListSeparator

        public String getListSeparator()
        Get the list separator. The default is in DEFAULT_LIST_SEPARATOR.
        Returns:
        the list separator

      • setListSeparator

        public void setListSeparator​(String listSeparator)
        Set the list separator
        Parameters:
        listSeparator - the list separator

      • getBoolean

        public boolean getBoolean​(String key)
        Retrieves the boolean value. Any of LOGICAL_TRUES are equivalent to logical true. Any of LOGICAL_FALSES are equivalent to logical false. All comparisons are done case-insensitive
        Parameters:
        key -
        Returns:
        the boolean value of the property.

      • setBoolean

        public void setBoolean​(String key,
                       boolean value)
        Sets the given boolean value.
        Parameters:
        key -
        value -

      • getInt

        public int getInt​(String key)
        Get the value associated with this key as an integer.
        Parameters:
        key -
        Returns:
        Throws:
        Exception - if the value cannot be parsed as an integer

      • setInt

        public void setInt​(String key,
                   int value)
        Set the property from the integer value.
        Parameters:
        key -
        value -

      • getLong

        public long getLong​(String key)
        Get the property as a long.
        Parameters:
        key -
        Returns:
        the long value
        Throws:
        Exception - if the value cannot be interpreted as a long.

      • setLong

        public void setLong​(String key,
                    long value)
        Set the value of the property from the give long.
        Parameters:
        key -
        value -

      • getFile

        public File getFile​(String key)
        Retrieve the file stored by this key, resolving it against the given invocation directory.
        Parameters:
        key -
        Returns:
        the File object.

      • getFile

        public File getFile​(String key,
                    File parent)
        Retrieve the file stored by this key, resolving it against the given file.
        Parameters:
        key -
        parent -
        Returns:

      • setFile

        public void setFile​(String key,
                    File f)
        Puts the file name into the properties, (not) the contents! This will not be portable between platforms, since this is the full path, properly escaped.
        Parameters:
        key -
        f -

      • getString

        public String getString​(String key)
        Gets the value corresponding to the key as a string. This always works.
        Parameters:
        key -
        Returns:

      • setString

        public void setString​(String key,
                      String value)
        Sets the value of the key with the given string.
        Parameters:
        key -
        value -

      • getSerializable

        public Object getSerializable​(String key)
        Gets a single serializable java object.
        Parameters:
        key -
        Returns:

      • setSerializable

        public void setSerializable​(String key,
                            Serializable object)
        Retrieves a single serializable java object.Don't forget that you need to have any classes for this available to the current virtual machine to correctly deserialize the result.
        Parameters:
        object - the serializable object

      • setSerializableList

        public void setSerializableList​(String key,
                                Object[] oList)
        Stores a list of serializable java objects in the properties.
        Parameters:
        key -
        oList -

      • getSerializableList

        public Object[] getSerializableList​(String key)
        Retrieves a list of serializable objects from the property. Don't for get that you need to have the classes for these available to the current virtual machine to correctly deserialize these.
        Parameters:
        key -
        Returns:

      • getBytes

        public byte[] getBytes​(String key)
        Returns the value associated with this key as a byte array.
        Parameters:
        key -
        Returns:
        the byte array

      • setBytes

        public void setBytes​(String key,
                     byte[] ba)
        Sets the value for the given key to the byte array.
        Parameters:
        key -
        ba -

      • setDouble

        public void setDouble​(String key,
                      double value)
        Set the value associated with this key to the given double value.
        Parameters:
        key -
        value -

      • getDouble

        public double getDouble​(String key)
        Attempts to retrieve the value associated with the key as a double.
        Parameters:
        key -
        Returns:

      • setProperty

        public Object setProperty​(String key,
                          String value)
        A bug fix for Properties... Attempting to set a non-existent property with a null value throws a NullPointerException. This is intercepted here.
        Overrides:
        setProperty in class Properties

      • add

        public void add​(Map source,
                boolean overwrite)

      • add

        public void add​(Properties[] sources,
                boolean overwrite)
        Adds each of the given array of properties. The flag deteremines if pre-exisiting key-value pairs should be replaced. This uses the same flag for every property.
        Parameters:
        sources -
        overwrite -

      • add

        public void add​(Properties[] sources,
                boolean[] overwrite)
        Adds each property set with a flag for the set indicating overwrite permission.
        Parameters:
        sources -
        overwrite -
        Throws:
        Exception - thrown if the arguments are not the same length.

      • setDate

        public void setDate​(String key,
                    Date d)
        Set the value of with the given Date. Note: internally this is actually stored as a long.
        Parameters:
        key -
        d -
        Throws:
        Exception

      • getURI

        public URI getURI​(String key)
        Get the value as a uri
        Parameters:
        key -
        Returns:
        the URI
        Throws:
        Exception - if the value cannot be parsed as a URI.

      • setURI

        public void setURI​(String key,
                   URI uri)
        Sets the value for the key from the URI
        Parameters:
        key -
        uri -
        Throws:
        Exception

      • setURI

        public void setURI​(String key,
                   String uriString)
        A convenience. This takes a string and checks that it is a valid URI before setting the property.
        Parameters:
        key -
        uriString - the uri
        Throws:
        Exception - if the supplied string cannot be parsed as a URI.

      • getURL

        public URL getURL​(String key)
        Gets the value as a URL.
        Parameters:
        key -
        Returns:
        the URL

      • setURL

        public void setURL​(String key,
                   URL url)
        Set the value from the given URL
        Parameters:
        key -
        url - the new value
        Throws:
        Exception

      • setURL

        public void setURL​(String key,
                   String urlString)
        A convenience. This takes a string and checks that it is a valid URL before setting the property.
        Parameters:
        key -
        urlString -
        Throws:
        Exception

      • getDate

        public Date getDate​(String key)
        Get the value as a date.
        Parameters:
        key -
        Returns:
        the date
        Throws:
        Exception - if the value is not parseable as a long.

      • getList

        public String[] getList​(String key,
                        String separator)
        This will take a c list separated by a string and return a vector of strings.
        Parameters:
        key -
        separator - a string that separates each element of the list.
        Throws:
        Exception

      • getList

        public String[] getList​(String key)
        Gets the value associated with the key and splits it into an array of strings using the value from getListSeparator
        Parameters:
        key -
        Returns:
        the array of strings
        Throws:
        Exception

      • setStoreFileName

        public void setStoreFileName​(String fileName)
        Sets the name of the file that calling the default store() method will write to. It may be changed at any time.
        Parameters:
        fileName - the name of the file

      • getStoreFileName

        public String getStoreFileName()
        Get the name of the store file
        Returns:
        the name of the file.

      • load

        public void load()
        Loads the content of the file in getStoreFileName
        Throws:
        Exception - if the file cannot be read

      • load

        public void load​(String storeFileName)
        Load the content of the given file into the current properties object, over-writing any duplicate values.
        Parameters:
        storeFileName -

      • load

        public void load​(File f)
        Loads from a file rather than from a stream. The parent class really needs one of these... Note that this does not set the default property file name for this object! This allows you to load multiple property files into the current properties object. Be advised that no vetting of the result occurs -- a property's value will be the last one loaded.
        Parameters:
        f - the file

      • setList

        public void setList​(String key,
                    String list)
        This sets a list directly, so the list itself is not touched. This is equivalent to calling setString(key,list) and is simply provided as a convenience.
        Parameters:
        key -
        list -

      • setList

        public void setList​(String key,
                    String[] list)
        Set the value of a list using the default separator.
        Parameters:
        key -
        list - the array of strings to store as a list

      • isList

        public boolean isList​(String key)

      • isList

        public boolean isList​(String key,
                      String separator)
        check if a string is in list format. This is not a clever test! It is unaware of any structure for the list.
        Parameters:
        key -
        separator -
        Returns:

      • store

        public void store​(String header)
        Writes the properties to the store file. The header is written at the start of the file. It may be empty.
        Parameters:
        header - the header (i.e. intial comment) for the file
        Throws:
        IOException - if no store file has been set.

      • store

        public void store()
        This just invokes store with an empty header.

      • setList

        public void setList​(String key,
                    String[] list,
                    String separator)
        Sets the value from an array of strings, delimiting them with the supplied separator.
        Parameters:
        key -
        list - the array of strings
        separator -

      • isEmpty

        public boolean isEmpty()
        This will return true if the current properties has no entries and false otherwise.
        Specified by:
        isEmpty in interface Map<Object,​Object>
        Overrides:
        isEmpty in class Properties

      • clone

        public Object clone()
        Creates a deep copy of this object.
        Overrides:
        clone in class Properties
        Returns:
        the XProperties object

      • getClone

        public XProperties getClone()
        Gets a clone of this object. Note that each call causes a new clone to be produced.
        Returns:
        the XProperties object as an XProperties object, so unlike the clone method no casting is required.

      • equals

        public boolean equals​(Object obj)
        Checks if this XProperties object is the same as a given object. Note that if these are large this might be expensive.
        Specified by:
        equals in interface Map<Object,​Object>
        Overrides:
        equals in class Properties
        Parameters:
        obj - the Object to compare to

      • keySubset

        protected boolean keySubset​(XProperties b)
        Checks that the keys of b are a subset of the keys in this XProperties.
        Parameters:
        b - the XProperties to check against.

      • main

        public static void main​(String[] args)
        This exists simply for testing this object. You supply the name of a file that will be written so that this can check that it does read and write files correctly. It will also put various properties in and retrieve them. The file is left should you want to look at it.
        Parameters:
        args -

      • toString

        public String toString​(int indent)