maspack.properties
Class PropertyList

java.lang.Object
  extended by maspack.properties.PropertyList
All Implemented Interfaces:
java.lang.Iterable<PropertyInfo>, PropertyInfoList

public class PropertyList
extends java.lang.Object
implements PropertyInfoList

Implements a list of exported properties.


Constructor Summary
PropertyList(java.lang.Class<?> hostClass)
          Creates an empty property list for a specified exporting host class.
PropertyList(java.lang.Class<?> hostClass, java.lang.Class<?> superClass)
          Creates a property list for a specified exporting host class.
PropertyList(java.lang.Class<?> hostClass, PropertyList list)
           
 
Method Summary
 void add(PropertyDesc desc)
          Adds a new property to this list.
 PropertyDesc add(java.lang.String nameAndMethods, java.lang.String description, java.lang.Object defaultValue)
          Adds a new property to this list, creating the appropriate description from the supplied arguments.
 PropertyDesc add(java.lang.String nameAndMethods, java.lang.String description, java.lang.Object defaultValue, java.lang.String options)
          Adds a new property to this list, creating the appropriate description from the supplied arguments.
 PropertyDesc addInheritable(java.lang.String nameAndMethods, java.lang.String description, java.lang.Object defaultValue)
          Adds a new inheritable property to this list, creating the appropriate description from the supplied arguments.
 PropertyDesc addInheritable(java.lang.String nameAndMethods, java.lang.String description, java.lang.Object defaultValue, java.lang.String options)
          Adds a new inheritable property to this list, creating the appropriate description from the supplied arguments.
 PropertyDesc addReadOnly(java.lang.String nameAndMethods, java.lang.String description)
          Adds a new read-only property to this list, creating the appropriate description from the supplied arguments.
 PropertyDesc addReadOnly(java.lang.String nameAndMethods, java.lang.String description, java.lang.String options)
          Adds a new read-only property to this list, creating the appropriate description from the supplied arguments.
static PropertyInfoList findPropertyInfoList(java.lang.Class<?> hostClass)
           
 PropertyDesc get(int idx)
          Gets a descriptor for a specific property by index, where index describes the numeric location of the property within this list.
 PropertyDesc get(java.lang.String name)
          Gets a descriptor for a specific named property.
static Property getProperty(java.lang.String pathName, HasProperties host)
          Recursively locates a property within this list and creates a handle for it.
 boolean hasNoInheritableProperties()
          Returns tree if any properties in this list are inheritable.
 java.util.Iterator<PropertyInfo> iterator()
          Returns an iterator over all PropertyInfo structures contained in this list.
 boolean remove(PropertyDesc desc)
          Removes a specific property from this list.
 boolean remove(java.lang.String name)
          Removes a specific named property from this list.
 void scanNamedProp(HasProperties host, java.lang.String name, ReaderTokenizer rtok)
           
 boolean scanProp(HasProperties host, ReaderTokenizer rtok)
          Scans a property from a ReaderTokenizer.
 void setDefaultModes(HasProperties host)
           
 void setDefaultValue(java.lang.String name, java.lang.Object value)
           
 void setDefaultValues(HasProperties host)
           
 void setDefaultValuesAndModes(HasProperties host)
           
 void setOptions(java.lang.String name, java.lang.String optionStr)
          Sets options for a specifed property within this list.
 int size()
          Returns the number of properties described in this list.
 PropertyDesc[] toArray()
          Returns an array of all the PropertyDesc objects in this list.
 boolean writeNonDefaultProps(HasProperties host, java.io.PrintWriter pw, NumberFormat fmt)
          Writes properties in this list whose current values differ from their default values to a PrintWriter.
 boolean writeNonDefaultProps(HasProperties host, java.io.PrintWriter pw, NumberFormat fmt, java.lang.String[] exclude)
          Identical to writeNonDefaultProps(host,pw,fmt) but also takes an optional array of property names which are to be excluded.
 void writeProps(HasProperties host, java.io.PrintWriter pw, NumberFormat fmt)
          Writes properties in this list to a PrintWriter.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PropertyList

public PropertyList(java.lang.Class<?> hostClass)
Creates an empty property list for a specified exporting host class.

Parameters:
hostClass - class exporting the properties

PropertyList

public PropertyList(java.lang.Class<?> hostClass,
                    java.lang.Class<?> superClass)
Creates a property list for a specified exporting host class. The list is initialized by copying the properties from s specified ancestor class of the host class.

Parameters:
hostClass - class exporting the properties
superClass - ancestor class containing properties to copy

PropertyList

public PropertyList(java.lang.Class<?> hostClass,
                    PropertyList list)
Method Detail

findPropertyInfoList

public static PropertyInfoList findPropertyInfoList(java.lang.Class<?> hostClass)

add

public void add(PropertyDesc desc)
Adds a new property to this list.

Parameters:
desc - descriptor for the property to be exported

add

public PropertyDesc add(java.lang.String nameAndMethods,
                        java.lang.String description,
                        java.lang.Object defaultValue,
                        java.lang.String options)
Adds a new property to this list, creating the appropriate description from the supplied arguments.

Parameters:
nameAndMethods - a string giving the name of the property, optionally followed by the names of host class get and set methods which should be used to get and set the property's value. The property and method names should be separated by whitespace. If the method names are absent, or are specified using the character `*`, then the default method names getProp or setProp will be used, as appropriate, where Prop is the capitalized property name.
description - a textual description of the property, for use in constructing documentation or GUI tool-tips, etc.
defaultValue - a default value for the property. Generally, this should be the value assigned to the property when the class is initialized.
options - a string setting various property options, having the same format as that used by setOptions.
Returns:
descriptor which was created for the property

add

public PropertyDesc add(java.lang.String nameAndMethods,
                        java.lang.String description,
                        java.lang.Object defaultValue)
Adds a new property to this list, creating the appropriate description from the supplied arguments.

Parameters:
nameAndMethods - a string giving the name of the property, optionally followed by the names of host class get and set methods which should be used to get and set the property's value. The property and method names should be separated by whitespace. If the method names are absent, or are specified using the character `*`, then the default method names getProp or setProp will be used, as appropriate, where Prop is the capitalized property name.
description - a textual description of the property, for use in constructing documentation or GUI tool-tips, etc.
defaultValue - a default value for the property. Generally, this should be the value assigned to the property when the class is initialized.
Returns:
descriptor which was created for the property

setOptions

public void setOptions(java.lang.String name,
                       java.lang.String optionStr)
Sets options for a specifed property within this list. The options are specified as whitespace-separated tokens within a string, and may appear in any order. Available options are:

Parameters:
name - name of the property for which options are to be set
optionStr - option string, conforming to the format described above
Throws:
java.lang.IllegalArgumentException - if the specified property is not found, or if one of the tokens in the option string is not recognized.

setDefaultValue

public void setDefaultValue(java.lang.String name,
                            java.lang.Object value)

addInheritable

public PropertyDesc addInheritable(java.lang.String nameAndMethods,
                                   java.lang.String description,
                                   java.lang.Object defaultValue,
                                   java.lang.String options)
Adds a new inheritable property to this list, creating the appropriate description from the supplied arguments.

Parameters:
nameAndMethods - a string giving the name of the property, optionally followed by the names of host class get and set methods for both the propertie's value and its mode. The property and method names should be separated by whitespace. If the method names are absent, or are specified using the character `*`, then the default method names getProp, setProp, getPropMode, and setPropMode will be used, as appropriate, where Prop is the capitalized property name.
description - a textual description of the property, for use in constructing documentation or GUI tool-tips, etc.
defaultValue - a default value for the property. Generally, this should be the value assigned to the property when the class is initialized.
options - a string setting various property options, having the same format as that used by setOptions.
Returns:
descriptor which was created for the property

addInheritable

public PropertyDesc addInheritable(java.lang.String nameAndMethods,
                                   java.lang.String description,
                                   java.lang.Object defaultValue)
Adds a new inheritable property to this list, creating the appropriate description from the supplied arguments.

Parameters:
nameAndMethods - a string giving the name of the property, optionally followed by the names of host class get and set methods for both the propertie's value and its mode. The property and method names should be separated by whitespace. If the method names are absent, or are specified using the character `*`, then the default method names getProp, setProp, getPropMode, and setPropMode will be used, as appropriate, where Prop is the capitalized property name.
description - a textual description of the property, for use in constructing documentation or GUI tool-tips, etc.
defaultValue - a default value for the property. Generally, this should be the value assigned to the property when the class is initialized.
Returns:
descriptor which was created for the property

addReadOnly

public PropertyDesc addReadOnly(java.lang.String nameAndMethods,
                                java.lang.String description,
                                java.lang.String options)
Adds a new read-only property to this list, creating the appropriate description from the supplied arguments.

Parameters:
nameAndMethods - a string giving the name of the property, optionally followed by the name of the host class get method which should be used to get the property's value. The property and method names should be separated by whitespace. If the method names are absent, or are specified using the character `*`, then the default method name getProp will be used, where Prop is the capitalized property name.
description - a textual description of the property, for use in constructing documentation or GUI tool-tips, etc.
options - a string setting various property options, having the same format as that used by setOptions.
Returns:
descriptor which was created for the property

addReadOnly

public PropertyDesc addReadOnly(java.lang.String nameAndMethods,
                                java.lang.String description)
Adds a new read-only property to this list, creating the appropriate description from the supplied arguments.

Parameters:
nameAndMethods - a string giving the name of the property, optionally followed by the name of the host class get method which should be used to get the property's value. The property and method names should be separated by whitespace. If the method names are absent, or are specified using the character `*`, then the default method name getProp will be used, where Prop is the capitalized property name.
description - a textual description of the property, for use in constructing documentation or GUI tool-tips, etc.
Returns:
descriptor which was created for the property

remove

public boolean remove(PropertyDesc desc)
Removes a specific property from this list.

Parameters:
desc - descriptor of the property to remove
Returns:
true if the property was present and actually removed

remove

public boolean remove(java.lang.String name)
Removes a specific named property from this list.

Parameters:
name - name of the property to remove
Returns:
true if the property was present and actually removed

get

public PropertyDesc get(java.lang.String name)
Gets a descriptor for a specific named property. If the named property is not defined in this list, null is returned.

Specified by:
get in interface PropertyInfoList
Parameters:
name - name of the property
Returns:
descriptor for this property, if present

get

public PropertyDesc get(int idx)
Gets a descriptor for a specific property by index, where index describes the numeric location of the property within this list.

Parameters:
idx - index of the property within this list
Returns:
descriptor for this property
Throws:
java.lang.ArrayIndexOutOfBoundsException - if index is not in the range [0, size()-1].

getProperty

public static Property getProperty(java.lang.String pathName,
                                   HasProperties host)
Recursively locates a property within this list and creates a handle for it. Used by a host class to implement HasProperties.getProperty.

Parameters:
pathName - property name
host - host object exporting the property

iterator

public java.util.Iterator<PropertyInfo> iterator()
Returns an iterator over all PropertyInfo structures contained in this list.

Specified by:
iterator in interface java.lang.Iterable<PropertyInfo>
Specified by:
iterator in interface PropertyInfoList
Returns:
iterator for this list

toArray

public PropertyDesc[] toArray()
Returns an array of all the PropertyDesc objects in this list.

Returns:
array of all PropertyDesc objects

writeProps

public void writeProps(HasProperties host,
                       java.io.PrintWriter pw,
                       NumberFormat fmt)
                throws java.io.IOException
Writes properties in this list to a PrintWriter. Only those properties for which PropertyInfo.getAutoWrite returns true are written. Properties are written in the format
    <propertyName> = <value>
 
i.e., the property name, followed by an = sign, followed by the property's current value.

Parameters:
host - class exporting the properties
pw - PrintWriter to which properties are written
fmt - Numeric formatting information. This is only used when the value to be writtem is itself Scannable, in which case it is passed to that value's write method.
Throws:
java.io.IOException - if an I/O error occurred writing to the stream

writeNonDefaultProps

public boolean writeNonDefaultProps(HasProperties host,
                                    java.io.PrintWriter pw,
                                    NumberFormat fmt)
                             throws java.io.IOException
Writes properties in this list whose current values differ from their default values to a PrintWriter. This allows the conservation of space within persistent storage. Otherwise, the behaviour of this method is identical to writeProps; in particular only those properties for which PropertyInfo.getAutoWrite returns true are written.

Parameters:
host - class exporting the properties
pw - PrintWriter to which properties are written
fmt - Numeric formatting information. This is only used when the value to be writtem is itself Scannable, in which case it is passed to that value's write method.
Throws:
java.io.IOException - if an I/O error occurred writing to the stream

writeNonDefaultProps

public boolean writeNonDefaultProps(HasProperties host,
                                    java.io.PrintWriter pw,
                                    NumberFormat fmt,
                                    java.lang.String[] exclude)
                             throws java.io.IOException
Identical to writeNonDefaultProps(host,pw,fmt) but also takes an optional array of property names which are to be excluded.

Parameters:
host - class exporting the properties
pw - PrintWriter to which properties are written
fmt - Numeric formatting information. This is only used when the value to be writtem is itself Scannable, in which case it is passed to that value's write method.
exclude - optional array of property names which are to be excluded.
Throws:
java.io.IOException - if an I/O error occurred writing to the stream

setDefaultModes

public void setDefaultModes(HasProperties host)

setDefaultValues

public void setDefaultValues(HasProperties host)

setDefaultValuesAndModes

public void setDefaultValuesAndModes(HasProperties host)

scanProp

public boolean scanProp(HasProperties host,
                        ReaderTokenizer rtok)
                 throws java.io.IOException
Scans a property from a ReaderTokenizer. The input is expected to be arranged as
    <propertyName> = <value>
 
i.e., the property name, followed by an = sign, followed by the property's value.

If the first token read is not a word, or if it does not correspond to the name of a known property on this list, then the token is pushed back and this routine returns false. Otherwise, the remaining input is expected to consist of an = equal sign followed by whatever input is required to specify the property, and an exception is thrown if this is not the case.

Parameters:
host - Object exporting the property
rtok - Tokenizer stream from which the property is read
Returns:
true if a property known to this list was successfully read, or false if the first input token is not a word or does not identify a property known to this list.
Throws:
java.io.IOException - if an I/O error occurred or if the input does not conform to the required format.

scanNamedProp

public void scanNamedProp(HasProperties host,
                          java.lang.String name,
                          ReaderTokenizer rtok)
                   throws java.io.IOException
Throws:
java.io.IOException

size

public int size()
Returns the number of properties described in this list.

Specified by:
size in interface PropertyInfoList
Returns:
size of this list

hasNoInheritableProperties

public boolean hasNoInheritableProperties()
Returns tree if any properties in this list are inheritable.

Specified by:
hasNoInheritableProperties in interface PropertyInfoList
Returns:
true if list contains inheritable properties