All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class com.trumphurst.utils.TProperties

java.lang.Object
   |
   +----com.trumphurst.utils.TProperties

public class TProperties
extends Object

A hashed property list which contains properties with validation. Separate methods are provided for amending existing properties and adding new properties. Methods are also provided for amending or adding properties given only a human-readable command string, so that a TProperties list can easily be used with a simple command parser to allow humans to edit the properties without any danger of the properties containing invalid values.

See Also:: TProperty

TProperties(): The default (only) constructor is public.

add(String): Add a new TStringProperty to the list.
add(String, TProperty): Add an arbitrary property to the list.
addnew(String): Add an arbitrary TProperty to the list.
fullload(DataInputStream): Load a list of arbitrary properties from a stream.
fullload(DataInputStream, ValidationExceptionHandler): Load a list of arbitrary properties from a stream.
fullsave(PrintStream): Save the property list to a stream.
fullsaveSorted(PrintStream): Save the property list to a stream.
get(String): Return the property for a particular key.
getBoolean(String): A convenience method to return the value of the TBooleanProperty for a particular key.
getDouble(String): A convenience method to return the value of the TDoubleProperty for a particular key.
getInt(String): A convenience method to return the value of the TIntegerProperty for a particular key.
getLong(String): A convenience method to return the value of the TLongProperty for a particular key.
getString(String): A convenience method to return the value of the TStringProperty for a particular key.
keys(): Return an Enumeration which iterates over the keys of the property list.
load(DataInputStream): Load the list of properties from a stream.
load(DataInputStream, ValidationExceptionHandler): Load the list of properties from a stream.
remove(String): Removes a property.
save(PrintStream): Save the property list to a stream.
saveSorted(PrintStream): Save the property list to a stream.
set(String): Sets an existing property to a new value, validating the value.
set(String, String): Sets an existing property to a new value, validating the value.
set(String, TProperty): Changes an existing property to an arbitrary new one.
sortedKeys(): Return a SortedEnumeration which iterates over the keys of the property list.

TProperties

 public TProperties()

The default (only) constructor is public.

add

 public void add(String key,
                 TProperty p)

Add an arbitrary property to the list. Note that any existing property with the same key will be replaced.

Parameters:: key - the name or key of this property; p - the property to add
See Also:: TStringProperty

add

 public boolean add(String setcmd)

Add a new TStringProperty to the list. Note that any existing property with the same key will be replaced. This method is here to provide a complete programmers interface. As it allows the type of a property to be changed, it would not normally be used.

Parameters:: setcmd - user-entered command of the form "key=value"
Returns:: true if the command was syntactically correct (the string was added)

addnew

 public boolean addnew(String setcmd) throws ValidationException, ClassNotFoundException, InstantiationException, IllegalAccessException, ClassCastException

Add an arbitrary TProperty to the list. This powerful method allows the user to add any kind of property, using dynamic class loading. It is mainly for testing the TProperties class, and by fullload.

Parameters:: setcmd - user-entered command of the form "key=classname(parameters)"
Returns:: true if the command was valid, classname implements TProperty, and the parameters were valid
Throws: ValidationException: if the value argument is invalid for the new property
Throws: ClassNotFoundException: if the classname could not be loaded
Throws: InstantiationException: if the classname could not be instantiated
Throws: IllegalAccessException: if the classname is not accessable from trumphurst.utils
Throws: ClassCastException: if the classname does not implement TProperty
See Also:: fullload

remove

 public TProperty remove(String key)

Removes a property.

Parameters:: key - the key of the property to remove
Returns:: the property removed, or null if there was no property with that key

set

 public boolean set(String key,
                    TProperty p)

Changes an existing property to an arbitrary new one. This method is here to help provide a complete programmers interface. As it allows the type of a property to be changed, it would not normally be used.

Parameters:: key - the key of the property to change; p - the new property to replace the existing one
Returns:: true if the old property exists and was replaced, false if not

set

 public boolean set(String key,
                    String value) throws ValidationException

Sets an existing property to a new value, validating the value. This is the heart of the functionality provided - it allows a string value to be validated to ensure it is a correct value for the property.

Parameters:: key - the key of the existing property; value - the string representation of the new value
Returns:: true if the key exists and the value is valid
Throws: ValidationException: value is not a valid value for the existing property

set

 public boolean set(String setcmd) throws ValidationException

Sets an existing property to a new value, validating the value. This is the method that would be called from a user command processor. It splits up the setcmd into key and value, and calls set(key, value).

Parameters:: setcmd - user-entered command of the form "key=value"
Returns:: true if the setcmd is syntactically correct, the key exists and the value is valid
Throws: ValidationException: value is not a valid value for the existing property

get

 public TProperty get(String key)

Return the property for a particular key.

Parameters:: key - the key to look up
Returns:: the property, or null if there wasn't one for that key

getString

 public String getString(String key)

A convenience method to return the value of the TStringProperty for a particular key.

Parameters:: key - the key to look up
Returns:: the String value of the property, or null if there wasn't one for that key, or the property wasn't a TStringProperty
See Also:: TStringProperty

getInt

 public int getInt(String key)

A convenience method to return the value of the TIntegerProperty for a particular key.

Parameters:: key - the key to look up
Returns:: the int value of the property, or null if there wasn't one for that key, or the property wasn't a TIntegerProperty
See Also:: TIntegerProperty

getLong

 public long getLong(String key)

A convenience method to return the value of the TLongProperty for a particular key.

Parameters:: key - the key to look up
Returns:: the long value of the property, or null if there wasn't one for that key, or the property wasn't a TLongProperty
See Also:: TLongProperty

getDouble

 public double getDouble(String key)

A convenience method to return the value of the TDoubleProperty for a particular key.

Parameters:: key - the key to look up
Returns:: the double value of the property, or null if there wasn't one for that key, or the property wasn't a TDoubleProperty
See Also:: TDoubleProperty

getBoolean

 public boolean getBoolean(String key)

A convenience method to return the value of the TBooleanProperty for a particular key.

Parameters:: key - the key to look up
Returns:: the boolean value of the property, or null if there wasn't one for that key, or the property wasn't a TBooleanProperty
See Also:: TBooleanProperty

keys

 public Enumeration keys()

Return an Enumeration which iterates over the keys of the property list.

sortedKeys

 public Enumeration sortedKeys()

Return a SortedEnumeration which iterates over the keys of the property list.

load

 public void load(DataInputStream in,
                  ValidationExceptionHandler handler) throws IOException

Load the list of properties from a stream. The stream consists of lines of the form "key=value". Lines starting with ";", or which don't take the correct form, are ignored. Each line is loaded and parsed, then used as an argument to set. If a property with that key does not already exist, a TStringProperty with that value is added. If set throws a ValidationException (because the value is not valid for that property), the handler is called. The return value from the handler may be ...

Null, or the original line: The original property is replaced with a TStringProperty containing the value
A string starting with ";", or an invalid command line: The original property is left unchanged
A different valid command line: The new command line is reparsed, and reprocessed in the same way

Parameters:: in - the stream to load; handler - a handler to deal with exceptions that occur during the load.
Throws: IOException: if an IOException is thrown by in.readline

load

 public void load(DataInputStream in) throws IOException

Parameters:: in - the stream to load
Throws: IOException: if an IOException is thrown by in.readline

fullload

 public void fullload(DataInputStream in,
                      ValidationExceptionHandler handler) throws IOException

Load a list of arbitrary properties from a stream. The stream consists of lines of the form "key=classname(params)", or "key=value". Lines starting with ";", or which don't take the correct form, are ignored. Each line is loaded and parsed. If it takes the second form, a TStringProperty with that value is added. Otherwise, the line is used as an argument to addnew. If addnew throws an Exception (because the value is not valid for the new property, or some kind of class loading exception occurs), the handler is called. The return value from the handler may be ...

Null, or the original line: A new TStringProperty containing everything to the right of the '=' is added
A string starting with ";", or an invalid command line: The line is ignored.
A different valid command line: The new command line is reparsed, and reprocessed in the same way

Parameters:: in - the stream to load; handler - a handler to deal with exceptions that occur during the load.
Throws: IOException: if an IOException is thrown by in.readline
See Also:: addnew

fullload

 public void fullload(DataInputStream in) throws IOException

Parameters:: in - the stream to load
Throws: IOException: if an IOException is thrown by in.readline
See Also:: addnew

save

 public void save(PrintStream out)

Save the property list to a stream. Saves each property in the form "key=value", one per line, to the stream.

Parameters:: out - the stream
See Also:: load

saveSorted

 public void saveSorted(PrintStream out)

Save the property list to a stream. Saves each property in the form "key=value", one per line, to the stream. Sorts the output.

Parameters:: out - the stream
See Also:: load

fullsave

 public void fullsave(PrintStream out)

Save the property list to a stream. Saves each property in the form "key=classname(params)", one per line, to the stream.

Parameters:: out - the stream
See Also:: fullload

fullsaveSorted

 public void fullsaveSorted(PrintStream out)

Save the property list to a stream. Saves each property in the form "key=classname(params)", one per line, to the stream. Sorts the output.

Parameters:: out - the stream
See Also:: fullload

All Packages  Class Hierarchy  This Package  Previous  Next  Index