org.nees.util
Class XProperties

java.lang.Object
  java.util.Dictionary
      java.util.Hashtable
          java.util.Properties
              org.nees.util.XProperties

All Implemented Interfaces:

java.lang.Cloneable, java.util.Map, java.io.Serializable

Direct Known Subclasses:

ScraperConfiguration

public class XProperties

extends java.util.Properties

Usage

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

Lifecycle

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

An extended properties class. 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
- methods for adding (vs. simply replacing) values from another property file
- methods for loading from other sources
- 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, enable(d), ok, true, yup, yeah and 1 to be logical true and false, no, disable(d), nope, off, nay or 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
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 Summary

static java.lang.String	DEFAULT_LIST_SEPARATOR
static java.lang.String[]	LOGICAL_FALSES Strings this will treat as equivalent to logical false.
static java.lang.String[]	LOGICAL_TRUES Strings that this will treat as equivalent to logical true.

Fields inherited from class java.util.Properties

defaults

Constructor Summary

XProperties()
Creates a new instance of XProperty

XProperties(java.io.File file)

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

XProperties(java.util.Properties[] sources, boolean overwrite)
This will allow for an array of Properties objects.

XProperties(java.util.Properties[] sources, boolean[] overwrite)
This will instantiate the properties taking the value ssupplied.

XProperties(java.lang.String fileName)
Convenience method.

Method Summary

void	add(java.util.Properties[] sources, boolean overwrite)
void	add(java.util.Properties[] sources, boolean[] overwrite) Adds each property set with a flag for the set indicating overwrite permission.
void	add(java.util.Properties source, boolean overwrite)
java.lang.Object	clone()
boolean	equals(java.lang.Object obj)
boolean	getBoolean(java.lang.String key) Retrieves the boolean value.
byte[]	getBytes(java.lang.String key)
XProperties	getClone()
java.util.Date	getDate(java.lang.String key)
double	getDouble(java.lang.String key)
java.io.File	getFile(java.lang.String key) Retrieve the file stored by this key, resolving it against the given invocation directory.
java.io.File	getFile(java.lang.String key, java.io.File parent) Retrieve the file stored by this key, resolving it against the given file.
int	getInt(java.lang.String key)
java.lang.String[]	getList(java.lang.String key)
java.lang.String[]	getList(java.lang.String key, java.lang.String separator) This will take a comma separated list and return a vector of strings.
java.lang.String	getListSeparator()
long	getLong(java.lang.String key)
java.lang.Object	getSerializable(java.lang.String key) Stores a single serializable java object.
java.lang.Object[]	getSerializableList(java.lang.String key) Retrieves a list of serializable objects from the property.
java.lang.String	getString(java.lang.String key)
java.net.URI	getURI(java.lang.String key)
boolean	isEmpty() This will return true if the current properties has no entries and false otherwise.
protected boolean	keySubset(XProperties b) Checks that the keys of b are a subset of the keys in this.
void	load(java.io.File f) The parent class really needs one of these...
static void	main(java.lang.String[] args) This exists simply for testing this object.
void	setBoolean(java.lang.String key, boolean value) Sets the given boolean value.
void	setBytes(java.lang.String key, byte[] ba)
void	setDate(java.lang.String key, java.util.Date d)
void	setDouble(java.lang.String key, double value)
void	setFile(java.lang.String key, java.io.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.
void	setInt(java.lang.String key, int value)
void	setList(java.lang.String key, java.lang.String list) This sets a list directly, so the list itself is not touched.
void	setList(java.lang.String key, java.lang.String[] list)
void	setList(java.lang.String key, java.lang.String[] list, java.lang.String separator)
void	setListSeparator(java.lang.String listSeparator)
void	setLong(java.lang.String key, long value)
java.lang.Object	setProperty(java.lang.String key, java.lang.String value) A bug fix for Properties...
void	setSerializable(java.lang.String key, java.io.Serializable object) Retrieves a single serializable java object.Don't for get that you need to have any classes for this available to the current virtual machine to correctly deserialize the result.
void	setSerializableList(java.lang.String key, java.lang.Object[] oList) Stores a list of serializable java objects in the properties.
void	setString(java.lang.String key, java.lang.String value)
void	setURI(java.lang.String key, java.lang.String uriString) A convenience.
void	setURI(java.lang.String key, java.net.URI uri)

Methods inherited from class java.util.Properties

getProperty, getProperty, list, list, load, propertyNames, save, store

Methods inherited from class java.util.Hashtable

clear, contains, containsKey, containsValue, elements, entrySet, get, hashCode, keys, keySet, put, putAll, rehash, remove, size, toString, values

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_LIST_SEPARATOR

public static java.lang.String DEFAULT_LIST_SEPARATOR

LOGICAL_TRUES

public static java.lang.String[] LOGICAL_TRUES

Strings that this will treat as equivalent to logical true.

LOGICAL_FALSES

public static java.lang.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(java.lang.String fileName)
            throws java.lang.Exception

Convenience method. This loads all the properties in the given file.

Parameters:

fileName -

Throws:

java.lang.Exception

XProperties

public XProperties(java.io.File file)
            throws java.lang.Exception

XProperties

public XProperties(java.util.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(java.util.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 -

overwrite -

XProperties

public XProperties(java.util.Properties[] sources,
                   boolean[] overwrite)
            throws java.lang.Exception

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 -

Throws:

java.lang.Exception - thrown if the list of properties and flags is not the same length.

Method Detail

getListSeparator

public java.lang.String getListSeparator()

setListSeparator

public void setListSeparator(java.lang.String listSeparator)

getBoolean

public boolean getBoolean(java.lang.String key)
                   throws java.lang.Exception

Retrieves the boolean value. Any of true, ok, yes, 1 are equivalent to logical true. Any of false, no, 0 are equivalent to logical false. All comparisons are done case-insensitive

Parameters:

key -

Returns:

Throws:

java.lang.Exception - if no recognized logical value is supplied.

setBoolean

public void setBoolean(java.lang.String key,
                       boolean value)

Sets the given boolean value.

Parameters:

key -

value -

getInt

public int getInt(java.lang.String key)
           throws java.lang.Exception

Parameters:

key -

Returns:

Throws:

java.lang.Exception

setInt

public void setInt(java.lang.String key,
                   int value)

Parameters:

key -

value -

getLong

public long getLong(java.lang.String key)
             throws java.lang.Exception

Parameters:

key -

Returns:

Throws:

java.lang.Exception

setLong

public void setLong(java.lang.String key,
                    long value)

Parameters:

key -

value -

getFile

public java.io.File getFile(java.lang.String key)
                     throws java.lang.Exception

Retrieve the file stored by this key, resolving it against the given invocation directory.

Parameters:

key -

Returns:

Throws:

java.lang.Exception

getFile

public java.io.File getFile(java.lang.String key,
                            java.io.File parent)
                     throws java.lang.Exception

Retrieve the file stored by this key, resolving it against the given file.

Parameters:

key -

parent -

Returns:

Throws:

java.lang.Exception

setFile

public void setFile(java.lang.String key,
                    java.io.File f)
             throws java.lang.Exception

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 -

Throws:

java.lang.Exception

getString

public java.lang.String getString(java.lang.String key)

Parameters:

key -

Returns:

setString

public void setString(java.lang.String key,
                      java.lang.String value)

Parameters:

key -

value -

getSerializable

public java.lang.Object getSerializable(java.lang.String key)

Stores a single serializable java object.

Parameters:

key -

Returns:

setSerializable

public void setSerializable(java.lang.String key,
                            java.io.Serializable object)

Retrieves a single serializable java object.Don't for get that you need to have any classes for this available to the current virtual machine to correctly deserialize the result.

Parameters:

key -

object -

setSerializableList

public void setSerializableList(java.lang.String key,
                                java.lang.Object[] oList)
                         throws java.lang.Exception

Stores a list of serializable java objects in the properties.

Parameters:

key -

oList -

Throws:

java.lang.Exception

getSerializableList

public java.lang.Object[] getSerializableList(java.lang.String key)
                                       throws java.lang.Exception

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:

Throws:

java.lang.Exception

getBytes

public byte[] getBytes(java.lang.String key)
                throws java.lang.Exception

Parameters:

key -

Returns:

Throws:

java.lang.Exception

setBytes

public void setBytes(java.lang.String key,
                     byte[] ba)
              throws java.lang.Exception

Parameters:

key -

ba -

Throws:

java.lang.Exception

setDouble

public void setDouble(java.lang.String key,
                      double value)
               throws java.lang.Exception

Parameters:

key -

value -

Throws:

java.lang.Exception

getDouble

public double getDouble(java.lang.String key)
                 throws java.lang.Exception

Parameters:

key -

Returns:

Throws:

java.lang.Exception

load

public void load(java.io.File f)
          throws java.lang.Exception

The parent class really needs one of these... Loads from a file rather than from a stream.

Parameters:

f - the file

Throws:

java.lang.Exception

setProperty

public java.lang.Object setProperty(java.lang.String key,
                                    java.lang.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.

add

public void add(java.util.Properties source,
                boolean overwrite)

add

public void add(java.util.Properties[] sources,
                boolean overwrite)

Parameters:

sources -

overwrite -

add

public void add(java.util.Properties[] sources,
                boolean[] overwrite)
         throws java.lang.Exception

Adds each property set with a flag for the set indicating overwrite permission.

Parameters:

sources -

overwrite -

Throws:

java.lang.Exception - thrown if the arguments are not the same length.

setDate

public void setDate(java.lang.String key,
                    java.util.Date d)
             throws java.lang.Exception

Parameters:

key -

d -

Throws:

java.lang.Exception

getURI

public java.net.URI getURI(java.lang.String key)
                    throws java.lang.Exception

Throws:

java.lang.Exception

setURI

public void setURI(java.lang.String key,
                   java.net.URI uri)
            throws java.lang.Exception

Throws:

java.lang.Exception

setURI

public void setURI(java.lang.String key,
                   java.lang.String uriString)
            throws java.lang.Exception

A convenience. This takes a string and checks that it is a valid URI before setting the property.

Throws:

java.lang.Exception

getDate

public java.util.Date getDate(java.lang.String key)
                       throws java.lang.Exception

Parameters:

key -

Returns:

Throws:

java.lang.Exception

getList

public java.lang.String[] getList(java.lang.String key,
                                  java.lang.String separator)
                           throws java.lang.Exception

This will take a comma separated list and return a vector of strings.

Throws:

java.lang.Exception

getList

public java.lang.String[] getList(java.lang.String key)
                           throws java.lang.Exception

Throws:

java.lang.Exception

setList

public void setList(java.lang.String key,
                    java.lang.String list)
             throws java.lang.Exception

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.

Throws:

java.lang.Exception

setList

public void setList(java.lang.String key,
                    java.lang.String[] list)
             throws java.lang.Exception

Throws:

java.lang.Exception

setList

public void setList(java.lang.String key,
                    java.lang.String[] list,
                    java.lang.String separator)
             throws java.lang.Exception

Throws:

java.lang.Exception

isEmpty

public boolean isEmpty()

This will return true if the current properties has no entries and false otherwise.

clone

public java.lang.Object clone()

getClone

public XProperties getClone()

equals

public boolean equals(java.lang.Object obj)

keySubset

protected boolean keySubset(XProperties b)

Checks that the keys of b are a subset of the keys in this.

main

public static void main(java.lang.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 -