com.cometway.props
Class Props

java.lang.Object
  com.cometway.props.Props

Direct Known Subclasses:

Agent, AgentController, AgentMessage, Message

public class Props
extends java.lang.Object

The Props object keeps track of a set of properties. Similar to a hashtable but includes many useful utilities. Props allows listeners to be added so that other objects can be notified when properties in this Props object get changed. There are also methods that return specific types of objects instead of the Object type and set properties with specific types.

Constructor Summary

Props()
Creates a new Props based on a PropsContainer.

Props(IPropsContainer container)
Creates a new Props based on a given IPropsContainer.

Method Summary

boolean	addListener(IPropsChangeListener l) Adds an IPropsChangeListener to the list of listeners for this object.
void	append(java.lang.String key, java.lang.String s) If the specified object is a String, it is the specified String is appended to it.
boolean	copy(Props srcProps, java.lang.String key) Copies the value of the property with the same name as key from srcProps into the IPropsContainer for this object.
void	copyFrom(Props srcProps) Copies the contents of the specified Props into this one.
void	copyTo(Props destProps) Copies the contents of this Props into the one specified.
void	decrementInteger(java.lang.String key) Decrements the integer value of the specified key by 1.
void	dump() Dumps a list of properties and their values to System.out.
void	enableListeners()
java.util.Enumeration	enumerateKeys() Returns an Enumeration of keys representing properties contained by this object's IPropsContainer.
java.lang.String	format(java.lang.String pattern) Uses the specified MessageFormat pattern this method generates a string containing the inserted values from the cooresponding properties.
boolean	getBoolean(java.lang.String key) Returns the boolean value of the requested property
byte[]	getByteArray(java.lang.String key) Returns specified object as a byte array.
char	getCharacter(java.lang.String key) Returns the char value of the requested property
java.util.Date	getDate(java.lang.String key) Returns the Date value of the requested property.
java.util.Date	getDate(java.lang.String key, java.text.DateFormat df) Returns the Date value of the requested property.
java.lang.String	getDateString(java.lang.String key, java.text.DateFormat df) Returns a formatted date using the Date stored in the specified property.
double	getDouble(java.lang.String key) Returns the double value of the requested property
float	getFloat(java.lang.String key) Returns the float value of the requested property
java.lang.String	getHexString(java.lang.String key) Returns the specified object as a String of hexidecimal bytes.
int	getInteger(java.lang.String key) Returns the int value of the requested property
java.util.Vector	getKeys() Returns a Vector containing the names of property keys currently accessible by getProperty.
long	getLong(java.lang.String key) Returns the long value of the requested property
protected java.lang.String	getNextKey(java.lang.String source, int start) Used by parse() method to find the next key to replace.
java.lang.Object	getProperty(java.lang.String key) Returns the property with the same name as the key parameter if available.
java.lang.Object	getProperty(java.lang.String key, PropsSchema schema) Returns the property with the same name as the key parameter if available.
IPropsContainer	getPropsContainer() Returns a reference to the IPropfsContainer referenced by this object.
int	getSize(java.lang.String key) Returns the size of the specified object.
java.lang.String	getString() Returns the entire Props as a formatted String.
java.lang.String	getString(java.lang.String key) Returns the String value of the requested property
java.util.Vector	getTokens(java.lang.String key) Returns a Vector of Strings representing the tokens stored stored in the specified property separated by a comma, semi-colon, carriage return, or line-feed.
java.util.Vector	getTokens(java.lang.String key, java.lang.String tokenSeparators) Returns a Vector of Strings representing the tokens stored stored in the specified property separated by any of the characters specified by tokenSeparators.
java.lang.String	getTrimmedString(java.lang.String key) Returns the specified object as a trimmed String.
java.util.Vector	getVector(java.lang.String key) Returns the specified object as a Vector.
boolean	hasProperty(java.lang.String key) Tests the existence of the specified property.
void	incrementInteger(java.lang.String key) Increments the integer value of the specified key by 1.
java.lang.String	insertProps(java.lang.String str) Inserts property String values into the passed string where property names are surrounded by angle brackets.
static Props	loadProps(java.lang.String file) Loads a Props from the specified plain text file.
void	notifyPropsChanged(java.lang.String key) Can be called externally to manually send props changes messages to all registered IPropsChangeListeners.
void	notifyPropsChangedIgnore(java.lang.String[] changedKeys, IPropsChangeListener ignore) Can be called externally to manually send props changes messages to all registered IPropsChangeListeners, except the one passed.
void	notifyPropsChangedIgnore(java.lang.String key, IPropsChangeListener ignore) Can be called externally to manually send props changes messages to all registered IPropsChangeListeners, except the one passed.
void	parse(java.lang.String source, java.lang.String pattern) Parses the source using the specified pattern, setting the specified properties with their coresponding values.
boolean	propertyMatchesRegEx(java.lang.String key, java.lang.String regex) Matches the string against the regular expression stored in the specified property.
static Props	readFromFile(java.lang.String file) Reads a serialized Props from a file.
boolean	regExPropertyMatches(java.lang.String key, java.lang.String str) Matches the string against the regular expression stored in the specified property.
void	removeAll() Removes all properties referenced by this class.
boolean	removeListener(IPropsChangeListener l) Removes an IPropsChangeListener from the list of listeners for this object.
boolean	removeProperty(java.lang.String key) Removes the property with the same name as the key parameter if available.
void	resumeNotify() Resumes the automatic notification of IPropsChangeListeners.
static boolean	saveProps(java.lang.String file, Props p) Saves the specified Props to a plain text file.
void	set(java.lang.String key, java.lang.Object value) Sets the property key to the passed value.
void	setBoolean(java.lang.String key, boolean value) Sets the property key to a Boolean of the passed value.
void	setCharacter(java.lang.String key, char value) Sets the property key to a Character of the passed value.
void	setDefault(java.lang.String key, java.lang.Object defaultValue) If there is no value for the specified object, it is set to the value specified as default.
void	setDouble(java.lang.String key, double value) Sets the property key to a Double of the passed value.
void	setFloat(java.lang.String key, float value) Sets the property key to a Float of the passed value.
void	setInteger(java.lang.String key, int value) Sets the property key to a Integer of the passed value.
void	setLong(java.lang.String key, long value) Sets the property key to a Long of the passed value.
void	setProperty(java.lang.String key, java.lang.Object value) Sets the property key to the passed value.
void	setProperty(java.lang.String key, Props srcProps) Sets the property value for key to the value retrieved using the same key from srcProps.
void	setProperty(java.lang.String key, Props srcProps, java.lang.String srcKey) Sets the property value for key to the value retrieved using srcKey from srcProps.
void	setPropsContainer(IPropsContainer container) Sets the IPropsContainer used to access and store properties for this object.
void	suspendNotify() Suspends the automatic notification of IPropsChangeListeners.
java.lang.String	toString() Returns the entire Props as a formatted String.
static void	writeToFile(java.lang.String file, Props p) Writes the serialized Props to a plain text file.

Methods inherited from class java.lang.Object

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

Constructor Detail

Props

public Props()

Creates a new Props based on a PropsContainer.

See Also:

IPropsContainer, PropsContainer

Props

public Props(IPropsContainer container)

Creates a new Props based on a given IPropsContainer.

Parameters:

c - a reference to an IPropsContainer.

See Also:

IPropsContainer

Method Detail

addListener

public boolean addListener(IPropsChangeListener l)

Adds an IPropsChangeListener to the list of listeners for this object.

Parameters:

l - a reference to an IPropsChangeListener.

Returns:

true if the listener already exists.

append

public void append(java.lang.String key,
                   java.lang.String s)

If the specified object is a String, it is the specified String is appended to it. Otherwise the call is ignored.

copy

public boolean copy(Props srcProps,
                    java.lang.String key)

Copies the value of the property with the same name as key from srcProps into the IPropsContainer for this object.

Parameters:

srcProps - a reference to the source Props.

key - the name of the property to copy.

copyFrom

public void copyFrom(Props srcProps)

Copies the contents of the specified Props into this one.

copyTo

public void copyTo(Props destProps)

Copies the contents of this Props into the one specified.

decrementInteger

public void decrementInteger(java.lang.String key)

Decrements the integer value of the specified key by 1.

dump

public void dump()

Dumps a list of properties and their values to System.out.

enumerateKeys

public java.util.Enumeration enumerateKeys()

Returns an Enumeration of keys representing properties contained by this object's IPropsContainer.

Returns:

an Enumeration of String objects.

enableListeners

public void enableListeners()

format

public java.lang.String format(java.lang.String pattern)
                        throws PropsException

Uses the specified MessageFormat pattern this method generates a string containing the inserted values from the cooresponding properties. The pattern string is passed to java.text.MessageFormat.format() after substituting appropriate argument indexes for property names. The pattern string contains number format patterns in the syntax { PropsKey, FormatType, FormatStyle } where formatType 'number' uses the NumberFormat class (none, integer, currency, percent, custom NumberFormat pattern), formatType 'date' uses the DateFormat class (none, short, medium, long, full, custom DateFormat pattern), formatType 'time' uses the DateFormat class (none, short, medium, long, full, custom DateFormat pattern), and formatType 'choice' uses the ChoiceFormat (custom ChoiceFormat pattern) class. eg: "At {my_date,time} on {my_date,date}, there was {my_event_name} on planet {my_planet_name,number,integer}." eg: "The disk \"{disk_name}\" contains {file_count} file(s)."

Throws:

PropsException

getBoolean

public boolean getBoolean(java.lang.String key)

Returns the boolean value of the requested property

Parameters:

key - the name of the property to process and retrieve.

Returns:

the boolean value of the requested property.

getByteArray

public byte[] getByteArray(java.lang.String key)

Returns specified object as a byte array. If the object is a String its getBytes methods is called to obtain a byte array. Otherwise, the object's String value is used to obtain a byte array.

getCharacter

public char getCharacter(java.lang.String key)

Returns the char value of the requested property

Parameters:

key - the name of the property to process and retrieve.

Returns:

the char value of the requested property.

getDate

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

Returns the Date value of the requested property. If the property value is a String, it is automatically parsed as a ISO8601 date using the DateFormat 'yyyyMMddThhmmss'.

Parameters:

key - the name of the property to process and retrieve.

Returns:

the Date value of the requested property.

getDate

public java.util.Date getDate(java.lang.String key,
                              java.text.DateFormat df)

Returns the Date value of the requested property. If the property value is a String, it is automatically parsed as a date using the specified DateFormat.

Parameters:

key - the name of the property to process and retrieve.

df - the DateFormat used to parse this property if it is a String.

Returns:

the Date value of the requested property.

getDateString

public java.lang.String getDateString(java.lang.String key,
                                      java.text.DateFormat df)

Returns a formatted date using the Date stored in the specified property. If the property is not a Date, the returned String will be zero length.

Parameters:

key - the name of the property to format and return.

df - the DateFormat used to format this property if it is a Date.

Returns:

the formatted String value of the requested property.

getDouble

public double getDouble(java.lang.String key)

Returns the double value of the requested property

Parameters:

key - the name of the property to process and retrieve.

Returns:

the double value of the requested property.

getFloat

public float getFloat(java.lang.String key)

Returns the float value of the requested property

Parameters:

key - the name of the property to process and retrieve.

Returns:

the float value of the requested property.

getHexString

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

Returns the specified object as a String of hexidecimal bytes.

getInteger

public int getInteger(java.lang.String key)

Returns the int value of the requested property

Parameters:

key - the name of the property to process and retrieve.

Returns:

the int value of the requested property.

getLong

public long getLong(java.lang.String key)

Returns the long value of the requested property

Parameters:

key - the name of the property to process and retrieve.

Returns:

the long value of the requested property.

getKeys

public java.util.Vector getKeys()

Returns a Vector containing the names of property keys currently accessible by getProperty.

getNextKey

protected java.lang.String getNextKey(java.lang.String source,
                                      int start)

Used by parse() method to find the next key to replace.

getProperty

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

Returns the property with the same name as the key parameter if available. If the requested property does not exist, null is returned instead.

Parameters:

key - the name of the property to retrieve.

Returns:

an Object reference; null if the requested property does not exist.

getProperty

public java.lang.Object getProperty(java.lang.String key,
                                    PropsSchema schema)
                             throws PropsException

Returns the property with the same name as the key parameter if available. If the requested property does not exist, null is returned instead.

Parameters:

key - the name of the property to retrieve.

schema - the PropsSchema used to determine the returned object type and style.

Returns:

an Object reference; null if the requested property does not exist.

Throws:

PropsException

getPropsContainer

public IPropsContainer getPropsContainer()

Returns a reference to the IPropfsContainer referenced by this object.

Returns:

a refernce to an IPropscontiner.

getSize

public int getSize(java.lang.String key)

Returns the size of the specified object. If the object is a Vector or VectorPropsContainer, the number of elements it contains is returned. If the object is a List, its length is returned. For other objects a value of 1 is returned. If the object does not exist, zero is returned.

getString

public java.lang.String getString()

Returns the entire Props as a formatted String.

getString

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

Returns the String value of the requested property

Parameters:

key - the name of the property to process and retrieve.

Returns:

the String value of the requested property.

getTokens

public java.util.Vector getTokens(java.lang.String key)

Returns a Vector of Strings representing the tokens stored stored in the specified property separated by a comma, semi-colon, carriage return, or line-feed.

getTokens

public java.util.Vector getTokens(java.lang.String key,
                                  java.lang.String tokenSeparators)

Returns a Vector of Strings representing the tokens stored stored in the specified property separated by any of the characters specified by tokenSeparators.

getTrimmedString

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

Returns the specified object as a trimmed String.

getVector

public java.util.Vector getVector(java.lang.String key)

Returns the specified object as a Vector. If the specified object is not a Vector, it is placed in a Vector and returned. if the object does not exist, an empty Vector is returned.

hasProperty

public boolean hasProperty(java.lang.String key)

Tests the existence of the specified property.

Parameters:

key - the name of the property to test.

Returns:

true if the property exists; false otherwise.

incrementInteger

public void incrementInteger(java.lang.String key)

Increments the integer value of the specified key by 1.

insertProps

public java.lang.String insertProps(java.lang.String str)

Inserts property String values into the passed string where property names are surrounded by angle brackets.

Parameters:

str - a String containing text with with property names surrounded by angle brackets.

notifyPropsChanged

public void notifyPropsChanged(java.lang.String key)

Can be called externally to manually send props changes messages to all registered IPropsChangeListeners.

Parameters:

key - the property that has changed.

notifyPropsChangedIgnore

public void notifyPropsChangedIgnore(java.lang.String key,
                                     IPropsChangeListener ignore)

Can be called externally to manually send props changes messages to all registered IPropsChangeListeners, except the one passed. Passing a null IPropsChangeLister will result in the notification of all registered listeners; the same as notifyPropsChanged.

Parameters:

key - the property that has changed.

l - a reference to an IPropsChangeListener.

notifyPropsChangedIgnore

public void notifyPropsChangedIgnore(java.lang.String[] changedKeys,
                                     IPropsChangeListener ignore)

Can be called externally to manually send props changes messages to all registered IPropsChangeListeners, except the one passed. Passing a null IPropsChangeLister will result in the notification of all registered listeners; the same as notifyPropsChanged.

Parameters:

key - the property that has changed.

l - a reference to an IPropsChangeListener.

parse

public void parse(java.lang.String source,
                  java.lang.String pattern)
           throws java.text.ParseException

Parses the source using the specified pattern, setting the specified properties with their coresponding values. The pattern string is passed to java.text.MessageFormat after substituting the property names for variable indexes. This allows the parser to set the corresponding properties based on the results. Throws java.text.ParseException if there is an error.

Throws:

java.text.ParseException

propertyMatchesRegEx

public boolean propertyMatchesRegEx(java.lang.String key,
                                    java.lang.String regex)

Matches the string against the regular expression stored in the specified property.

Parameters:

key - the property containing the String to match against.

regex - the regular expression used for matching.

Returns:

true if the match was successful; false otherwise.

regExPropertyMatches

public boolean regExPropertyMatches(java.lang.String key,
                                    java.lang.String str)

Matches the string against the regular expression stored in the specified property.

Parameters:

key - the property that contains a regular expression

str - the String that the regular expression is matched against.

Returns:

true if the match was successful; false otherwise.

removeAll

public void removeAll()

Removes all properties referenced by this class.

removeListener

public boolean removeListener(IPropsChangeListener l)

Removes an IPropsChangeListener from the list of listeners for this object.

Parameters:

l - a reference to an IPropsChangeListener.

Returns:

true if the listener was removed; false otherwise.

removeProperty

public boolean removeProperty(java.lang.String key)

Removes the property with the same name as the key parameter if available. If the requested property does not exist, false is returned.

Parameters:

key - the name of the property to retrieve.

Returns:

true if the property was removed; false otherwise.

resumeNotify

public void resumeNotify()

Resumes the automatic notification of IPropsChangeListeners. Calling this method will immediately call the propsChanged method of its IPropsChangeListeners passing an array of property names which have changed since suspendNotify was called.

set

public void set(java.lang.String key,
                java.lang.Object value)

Sets the property key to the passed value. Calling this method automatically calls notifyChanged with a reference to the key parameter.

This method id deprecated. Use IPropsChangeListeners instead.

Parameters:

key - the name of the property to set.

value - a reference to an Object.

setBoolean

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

Sets the property key to a Boolean of the passed value.

Parameters:

key - the name of the property to set.

value - a boolean.

setCharacter

public void setCharacter(java.lang.String key,
                         char value)

Sets the property key to a Character of the passed value.

Parameters:

key - the name of the property to set.

value - a char.

setDefault

public void setDefault(java.lang.String key,
                       java.lang.Object defaultValue)

If there is no value for the specified object, it is set to the value specified as default.

setDouble

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

Sets the property key to a Double of the passed value.

Parameters:

key - the name of the property to set.

value - a double.

setFloat

public void setFloat(java.lang.String key,
                     float value)

Sets the property key to a Float of the passed value.

Parameters:

key - the name of the property to set.

value - a float.

setInteger

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

Sets the property key to a Integer of the passed value.

Parameters:

key - the name of the property to set.

value - an int.

setLong

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

Sets the property key to a Long of the passed value.

Parameters:

key - the name of the property to set.

value - a long.

setProperty

public void setProperty(java.lang.String key,
                        java.lang.Object value)

Sets the property key to the passed value.

Parameters:

key - the name of the property to set.

value - a reference to an Object.

setProperty

public void setProperty(java.lang.String key,
                        Props srcProps)

Sets the property value for key to the value retrieved using the same key from srcProps.

Parameters:

key - the name of the property to set.

value - a reference to an Object.

setProperty

public void setProperty(java.lang.String key,
                        Props srcProps,
                        java.lang.String srcKey)

Sets the property value for key to the value retrieved using srcKey from srcProps.

Parameters:

key - the name of the property to set.

value - a reference to an Object.

setPropsContainer

public void setPropsContainer(IPropsContainer container)

Sets the IPropsContainer used to access and store properties for this object.

Parameters:

container - a reference to an IPropsContainer.

suspendNotify

public void suspendNotify()

Suspends the automatic notification of IPropsChangeListeners. This is useful for when several property changes need to be made without calling the propsChanged method of the IPropsChangeListeners for each one. After this method is called, property changes are queued until the resumeNotify method is called. Each successive call to this method must be matched with a call to resumeNotify in order for notification to work correctly.

toString

public java.lang.String toString()

Returns the entire Props as a formatted String.

Overrides:

toString in class java.lang.Object

loadProps

public static Props loadProps(java.lang.String file)

Loads a Props from the specified plain text file. Each line of the file contains a = statement that will be evaluated as a String.

readFromFile

public static Props readFromFile(java.lang.String file)

Reads a serialized Props from a file. This method will always return a Props even if the specified file was not found.

saveProps

public static boolean saveProps(java.lang.String file,
                                Props p)

Saves the specified Props to a plain text file. Each line of the file contains a = statement that will be evaluated as a String. Returns true on success; false otherwise.

writeToFile

public static void writeToFile(java.lang.String file,
                               Props p)

Writes the serialized Props to a plain text file.