maspack.properties

Class PropertyList

java.lang.Object

maspack.properties.PropertyList

All Implemented Interfaces:

java.lang.Iterable<PropertyInfo>, PropertyInfoList

Direct Known Subclasses:

FieldPropertyList

public class PropertyList
extends java.lang.Object
implements PropertyInfoList

Implements a list of exported properties.

Constructor Summary

Constructors

Constructor and Description
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.

Method Summary

Modifier and Type	Method and Description
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 propertreturn myProps;y.
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, java.lang.Object ref) 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.Object ref, java.lang.String[] exclude) Identical to writeNonDefaultProps(host,pw,fmt,obj) but also takes an optional array of property names which are to be excluded.
void	writeProps(HasProperties host, java.io.PrintWriter pw, NumberFormat fmt, java.lang.Object ref) Writes properties in this list to a PrintWriter.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

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 a specified ancestor class of the host class.

Parameters:

hostClass - class exporting the properties

superClass - ancestor class containing properties to copy

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:

• NE, NeverEdit Disables interactive editing. This will cause PropertyInfo.getEditing to return Edit.Never.

• AE, AlwaysEdit Enables interactive editing. This will cause PropertyInfo.getEditing to return Edit.Always.

• 1E, SingleEdit Enables interactive editing for one property host at a time. This will cause PropertyInfo.getEditing to return Edit.Single.

• NW, NoAutoWrite Disable auto-write. This will cause PropertyInfo.getAutoWrite to return false.

• AW, AutoWrite Enables auto-write. This will cause PropertyInfo.getAutoWrite to return true, if the property is not read-only.

• SH, Sharable Indicates that the property value can be shared among several hosts.

• [l,u] Sets a numeric range with a lower bound of l and an upper bound of u. The numeric range is returned by PropertyInfo.getDefaultNumericRange.

• fmt Sets a print format, using a printf-style format string beginning with '%'. The print format is returned by PropertyInfo.getPrintFormat and is used for printing numeric property values.

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 propertreturn myProps;y. 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,
                       java.lang.Object ref)
                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.

ref - Reference object. 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.Object ref)
                             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.

Specified by:

writeNonDefaultProps in interface PropertyInfoList

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 written is itself Scannable, in which case it is passed to that value's write method.

ref - Reference object. This is only used when the value to be written 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.Object ref,
                                    java.lang.String[] exclude)
                             throws java.io.IOException

Identical to writeNonDefaultProps(host,pw,fmt,obj) 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 written is itself Scannable, in which case it is passed to that value's write method.

ref - Reference object. This is only used when the value to be written 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