com.sas.collection
Class PropertyBag

com.sas.collection.PropertyBag

All Implemented Interfaces:

PropertyBagChangedListener, PropertyBagChangedSource, PropertyBagInterface, StaticPropertyBagInterface, com.sas.DeepClonable, com.sas.PublicClonable, com.sas.util.Countable, java.beans.PropertyChangeListener, java.io.ObjectInputValidation, java.io.Serializable, java.lang.Cloneable, java.util.EventListener

Direct Known Subclasses:

BorderStyle, CellStyle, CellVectorStyle, FontStyle, NodeStyle, RangeSegment, TextElement

public class PropertyBag
implements PropertyBagInterface, PropertyBagChangedListener, java.io.Serializable, java.io.ObjectInputValidation, java.beans.PropertyChangeListener, com.sas.DeepClonable

A PropertyBag defines a collection of properties, much like a Dictionary but simpler. Keys must be interned Strings and lookup is done with == tests, not equals() method calls. PropertyBag is also similar to but not quite like a Properties object for the same reasons. The property bag does not support Enumerations and is not a collection as defined by StaticCollectionInterface. Also, it is not a com.sas.Component or implement com.sas.ComponentInterface. Abstractly, a PropertyBag is like a Java Bean with a set of dynamic as opposed to fixed properties. The set of properties on an instance can change over time. The PropertyBag sends property change events when a property is added, removed, replaced, or when that property value changes its state, provided it sends PropertyChangeEvents or PropertyBagChangedEvents (for example, the property may be another PropertyBag). See the setProperties(java.lang.Object, StaticPropertyBagInterface)

Please note that it is the caller's responsibility to intern all strings keys (property names) passed to the PropertyBag. You need not intern Java string literals (quoted constants in your program); the class loader and Java Virtual Machine does that for you, so the use of static final String constants and literals is recommended. If you obtain strings from some other source (such as concatenation or other expressions, or I/O), you should intern the key first with

    string = string.intern();
 

This class is not fully synchronized. The purpose of this class is to be used for small internal implementation state and it is assumed multi-threaded synchronization control is performed at a higher level. Also, the intended use is in situations where the list of properties is small.

See Also:

DictionaryInterface, Serialized Form

Field Summary

protected PropertyBagChangedListenerList	allPropertyBagChangedListeners list if listeners for PropertyBagChangedEvents
protected StaticPropertyBagInterface	defaults The defaults to look in when an item is not found.
protected java.lang.String[]	keys The set of property keys: all interned strings
static java.lang.Object	NO_SUCH_ELEMENT The NO_SUCH_ELEMENT object is a useful item to use as a default object in get(String key, Object default) calls as a way of indicating that no item with the specified key was found.
protected int	numProperties The number of properties (may be less than values.length)
protected int	pendingEventGateCount Used when events are suppressed
protected java.lang.Object[]	values The set of property values

Constructor Summary

PropertyBag()
Construct an empty property bag.

PropertyBag(StaticPropertyBagInterface defaults)
Construct a property bag which looks through to a default property bag when items are not found.

Method Summary

PropertyBagInterface	addItems(java.util.Properties props) Copy the the key/values from a Properties object into this property bag.
static PropertyBagInterface	addItems(PropertyBagInterface bag, java.util.Properties properties) Copy the the key/values from a Properties object into a property bag.
void	addPropertyBagChangedListener(PropertyBagChangedListener listener) Add a listener for the PropertyBagChangedEvent event.
protected boolean	anyListeners() Return true if there are any listeners for PropertyBagChangedEvent
java.lang.Object	clone() Clone a property bag.
java.lang.Object	clone(com.sas.DeepCloneSupport support, boolean deeply) Clone a property bag, optionally cloning deeply.
static int	collect(PropertyBagInterface target, PropertyBagInterface query, StaticPropertyBagInterface source) Collect values from a source property bag, according to the elements in the query property bag, merging results into the target property bag.
boolean	containsKey(java.lang.String key) Determine if this property bag contains a property with this name.
int	count() Return the number of key/property values in this property bag.
void	disableEvents() Ask this property bag to suppress delivery of PropertyBagChangedEvents on subsequent changes to this property bag or its contents.
void	enableEvents(HowChanged howChanged) Undo a call.
boolean	equals(java.lang.Object o) Compare to another object.
boolean	equals(PropertyBag bag) Compare this property bag to another PropertyBag to see if they have the same contents.
protected boolean	eventsEnabled() Return true if events are enabled.
void	firePropertyBagChanged(PropertyBagChangedEvent propertyBagChangedEvent) Deliver a PropertyBagChangedEvent.
void	firePropertyBagChanged(java.lang.String propertyName, java.lang.Object oldValue, java.lang.Object newValue, HowChanged howChanged) Fire a PropertyBagChangedEvent to inform listeners that this property bag's contents have changed.
protected boolean	firingEvents() Returns true if there is a PropertyBagChangedEvent listener registered and event delivery has not been suspended.
java.lang.Object	get(java.lang.String key) Get an item from a property bag.
java.lang.Object	get(java.lang.String key, java.lang.Object defaultValue) Get an item from a property bag, or return a default if it does not exist in this property bag (or the defaults).
StaticPropertyBagInterface	getDefaults() Return the defaults for item not found in this property bag.
protected void	growPropertyBag() Grow this property bag to accommodate more properties.
protected void	invalidateKeyList() Call each time the internal array of keys is modified.
java.lang.String[]	listKeys() Return a list of the keys for this property bag.
void	load(java.io.InputStream stream) Load properties from an input stream.
static void	load(PropertyBagInterface properties, java.io.InputStream stream) Load properties from an input stream.
void	merge(StaticPropertyBagInterface other) Merge into this property bag any property from the other property bag which does not exist in this bag.
void	merge(java.lang.String key, java.lang.Object otherValue) Merge the other value onto this PropertyBag, using the key.
protected void	notifyListeners(java.lang.Object source) Send a PropertyBagChangedEvent event to all listeners.
void	propertyBagChanged(PropertyBagChangedEvent event) Handle a property bag changed event.
void	propertyChange(java.beans.PropertyChangeEvent event) Handle a property change event from an inner property bag.
protected int	propertyIndex(java.lang.String key) Return the index of a property.
void	remove(java.lang.String key) Remove a property from this property bag.
void	remove(java.lang.String key, boolean aggressive) Remove a property from this property bag.
void	removeAll() Remove all items from this property bag.
void	removePropertyBagChangedListener(PropertyBagChangedListener listener) Remove a listener for the PropertyBagChangedEvent event.
protected void	resize(int newSize) Resize the internal arrays.
void	save(java.io.OutputStream stream, java.lang.String header) Save properties from an Output stream.
static void	save(StaticPropertyBagInterface properties, java.io.OutputStream stream, java.lang.String header) Save properties to an Output stream.
void	set(StaticPropertyBagInterface other) Add the contents of another property list to this property list.
void	set(java.lang.String key, java.lang.Object property) Put a property in this property bag.
void	set(java.lang.String key, java.lang.Object property, boolean aggressive) Put a property in this property bag.
void	setDefaults(StaticPropertyBagInterface defaults) Set the defaults property bag.
void	setProperties(java.lang.Object bean) Extract the properties from the property bag properties and apply them to the public properties of the bean.
static void	setProperties(java.lang.Object bean, StaticPropertyBagInterface properties) Extract the properties from the property bag properties and apply them to the public properties of the bean.
protected void	swap(int i, int j)
protected void	swapSources(java.lang.Object oldProperty, java.lang.Object newProperty, boolean aggressive) Add or remove this property bag as a PropertyChangeListener.
DictionaryInterface	toDictionary(DictionaryInterface initialDictionary) Place this property bag's items into a dictionary and return that dictionary.
java.util.Properties	toProperties(java.util.Properties properties) Copy the key/value pairs from this property bag into a Properties object.
static java.util.Properties	toProperties(StaticPropertyBagInterface propertyBag, java.util.Properties properties) Copy the key/value pairs from a property bag into a Properties object.
java.lang.String	toString() Convert a property bag to a String representation.
void	validateObject() After deserialization, reestablish this property bag as a listener.

Field Detail

NO_SUCH_ELEMENT

public static final java.lang.Object NO_SUCH_ELEMENT

The NO_SUCH_ELEMENT object is a useful item to use as a default object in get(String key, Object default) calls as a way of indicating that no item with the specified key was found. You could use two method calls:

    if (propertyBag.containsKey(key)) {
       Object object = propertyBag.get(key);
       process the object
       }
    else
       object not found
 

or you can use get(key, PropertyBag.NO_SUCH_ELEMENT) and use a less expensive comparison to NO_SUCH_ELEMENT to indicate the value does not exist:

 Object object = propertyBag.get(key, PropertyBag.NO_SUCH_ELEMENT);
 if (object == PropertyBag.NO_SUCH_ELEMENT)
    object not found
 else
    process the object
 

keys

protected java.lang.String[] keys

The set of property keys: all interned strings

values

protected java.lang.Object[] values

The set of property values

numProperties

protected int numProperties

The number of properties (may be less than values.length)

allPropertyBagChangedListeners

protected transient PropertyBagChangedListenerList allPropertyBagChangedListeners

list if listeners for PropertyBagChangedEvents

pendingEventGateCount

protected int pendingEventGateCount

Used when events are suppressed

defaults

protected StaticPropertyBagInterface defaults

The defaults to look in when an item is not found.

Constructor Detail

PropertyBag

public PropertyBag()

Construct an empty property bag.

PropertyBag

public PropertyBag(StaticPropertyBagInterface defaults)

Construct a property bag which looks through to a default property bag when items are not found. The new property bag does not listen for change events from defalts.

Parameters:

defaults - another property bag which contains default values to search when an item is not found in this new property bag. The defaults may itself hav defaults, etc.

Method Detail

setDefaults

public void setDefaults(StaticPropertyBagInterface defaults)

Set the defaults property bag. When looking up an item, if it does not exist in this property bag, delegate the search to this defaults.

Parameters:

defaults - the new set of defaults

getDefaults

public StaticPropertyBagInterface getDefaults()

Return the defaults for item not found in this property bag.

Returns:

the defaults property bag

set

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

Put a property in this property bag.

Specified by:

set in interface PropertyBagInterface

Parameters:

key - the name of the property. This string must be an interned string and may not be null. (Use aString.intern() to create an interned string.)

property - the value to associate with the property name. Property values may be null.

set

public void set(java.lang.String key,
                java.lang.Object property,
                boolean aggressive)

Put a property in this property bag.

Parameters:

key - the name of the property. This string must be an interned string and may not be null. (Use aString.intern() to create an interned string.)

property - the value to associate with the property name Property values may be null.

aggressive - if true, then an aggressive but much slower check (using reflection) is made to see if the property value implements addPropertyChangeListener(PropertyChangeListener) By default, the quick check is just to test if the object implements the PropertyChangeSource interface. If the object emits property change events, this property bag will listen for property changes from it and fire a PropertyBagChangedEvent when the property changes.

invalidateKeyList

protected final void invalidateKeyList()

Call each time the internal array of keys is modified. This sets keys to null, do that listKeys() will allocate a new array.

swapSources

protected void swapSources(java.lang.Object oldProperty,
                           java.lang.Object newProperty,
                           boolean aggressive)

Add or remove this property bag as a PropertyChangeListener. Used when adding/deleting/replacing items in this property bag.

Parameters:

oldProperty - an object being removed from this PropertyBag. If it implements PropertyBagChangedSource (or if aggressive is true and the object has a public removePropertyBagChangedListener(PropertyBagChangedListener) method), remove this property bag from its PropertyBagChangedEvent listener list.

newProperty - an object being removed from this property bag. If it implements PropertyBagChangedSource (or if aggressive is true and the object has a public addPropertyBagChangedListener(PropertyBagChangedListener) method), add this property bag from its PropertyBagChangedEvent listener list.

aggressive - if false, do not perform slower introspection of the property to find the add/removePropertyChangeListener method. The default if false is to only do the add/removePropertyBagChangedListener if the object implements the PropertyBagChangedSource interface.

growPropertyBag

protected void growPropertyBag()

Grow this property bag to accommodate more properties. The growth factor is 4 + 5N/4

resize

protected void resize(int newSize)

Resize the internal arrays. assumes newSize >= numProperties. Note that this method is unconditional, even if the array length == newSize; the clone() method takes advantage of this.

Parameters:

newSize - the new array size.

propertyIndex

protected int propertyIndex(java.lang.String key)

Return the index of a property.

Parameters:

key - the property name. This string must be an interned string and may not be null. (Use aString.intern() to create an interned string.)

Returns:

the index where the property was found, or -1

swap

protected void swap(int i,
                    int j)

containsKey

public boolean containsKey(java.lang.String key)

Determine if this property bag contains a property with this name.

Specified by:

containsKey in interface StaticPropertyBagInterface

Parameters:

key - the name of the property. This string must be an interned string and may not be null. (Use aString.intern() to create an interned string.)

Returns:

true if this property bag contains the property.

remove

public void remove(java.lang.String key)

Remove a property from this property bag. After removing, containsKey(key) will return false and get(key) will throw a NoSuchElementException

Specified by:

remove in interface PropertyBagInterface

Parameters:

key - the name of the property. This string must be an interned string and may not be null. (Use aString.intern() to create an interned string.)

Throws:

java.util.NoSuchElementException - if the bag does not contains the named element.

remove

public void remove(java.lang.String key,
                   boolean aggressive)

Remove a property from this property bag. After removing, containsKey(key) will return false and get(key) will throw a NoSuchElementException

Parameters:

key - the name of the property. This string must be an interned string and may not be null. (Use aString.intern() to create an interned string.)

aggressive - if true, then an aggressive but much slower check (using reflection) is made to see if the property value implements removePropertyChangeListener(java.beans.PropertyChangeListener) By default, the quick check is just to test if the object implements the com.sas.beans.PropertyChangeSource interface.

Throws:

java.util.NoSuchElementException - if the bag does not contains the named element.

removeAll

public void removeAll()

Remove all items from this property bag.

Specified by:

removeAll in interface PropertyBagInterface

get

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

Get an item from a property bag.

Specified by:

get in interface StaticPropertyBagInterface

Parameters:

key - the name of the property. This string must be an interned string and may not be null. (Use aString.intern() to create an interned string.)

Returns:

the object associated with the key

Throws:

java.util.NoSuchElementException - if there is no such property in this property bag or in the defaults property bag.

See Also:

PropertyBag(StaticPropertyBagInterface), getDefaults(), setDefaults(StaticPropertyBagInterface)

get

public java.lang.Object get(java.lang.String key,
                            java.lang.Object defaultValue)

Get an item from a property bag, or return a default if it does not exist in this property bag (or the defaults).

Specified by:

get in interface StaticPropertyBagInterface

Parameters:

key - the name of the property. This string must be an interned string and may not be null. (Use aString.intern() to create an interned string.)

defaultValue - a default value to return if the named property does not exist in this property bag.

Returns:

the object associated with the key

See Also:

getDefaults()

toDictionary

public DictionaryInterface toDictionary(DictionaryInterface initialDictionary)

Place this property bag's items into a dictionary and return that dictionary. The defaults property bag is ignored.

Specified by:

toDictionary in interface StaticPropertyBagInterface

Parameters:

initialDictionary - a dictionary into which this property bag places its values. This may be null, in which case a new dictionary is created.

Returns:

the dictionary containing this property bag's contents.

listKeys

public java.lang.String[] listKeys()

Return a list of the keys for this property bag. The defaults property bag is ignored.

Specified by:

listKeys in interface StaticPropertyBagInterface

Returns:

an array containing the property keys

See Also:

StringCollection

set

public void set(StaticPropertyBagInterface other)

Add the contents of another property list to this property list. This does set(key, property) on this property bag for each the key/property pair from the other property bag.

Specified by:

set in interface PropertyBagInterface

Parameters:

other - another property bag

See Also:

PropertyBagInterface.merge(com.sas.collection.StaticPropertyBagInterface)

merge

public void merge(StaticPropertyBagInterface other)

Merge into this property bag any property from the other property bag which does not exist in this bag. For items which exists in both property bags, if both items are also property bags, merge the element from the inner bag from other into the element from this PropertyBag recursively.

Specified by:

merge in interface PropertyBagInterface

Parameters:

other - another property bag

See Also:

PropertyBagInterface.merge(com.sas.collection.StaticPropertyBagInterface)

merge

public void merge(java.lang.String key,
                  java.lang.Object otherValue)

Merge the other value onto this PropertyBag, using the key. If this bag does not contains a value for the key, then set the otherValue on this bag, using the key. If there is already a value for the key, and both values are property bags (i.e. the value in this bag is an instance of PropertyBagInterface and the otherValue is a StaticPropertyBagInterface), then merge the other value into the value in this bag.

Parameters:

key - the key to merge on

otherValue - the value to merge into this property bag.

count

public int count()

Return the number of key/property values in this property bag.

Specified by:

count in interface StaticPropertyBagInterface

Specified by:

count in interface com.sas.util.Countable

Returns:

the number of key/property values in this property bag.

anyListeners

protected boolean anyListeners()

Return true if there are any listeners for PropertyBagChangedEvent

Returns:

true if a non-null property listener has been assigned.

firingEvents

protected final boolean firingEvents()

Returns true if there is a PropertyBagChangedEvent listener registered and event delivery has not been suspended.

Returns:

anyListeners() && eventsEnabled()

firePropertyBagChanged

public void firePropertyBagChanged(java.lang.String propertyName,
                                   java.lang.Object oldValue,
                                   java.lang.Object newValue,
                                   HowChanged howChanged)

Fire a PropertyBagChangedEvent to inform listeners that this property bag's contents have changed. The event is also fired as a PropertyChangeEvent for any property change listeners.

Parameters:

propertyName - the name of the property than changed

oldValue - the old value of the property

newValue - the new value of the property. Note that if the property is itself another property bag, oldValue may be == to newValue and the contents of the inner property bag may have changed.

howChanged - indicates how the property has changed.

addPropertyBagChangedListener

public void addPropertyBagChangedListener(PropertyBagChangedListener listener)

Add a listener for the PropertyBagChangedEvent event.

Specified by:

addPropertyBagChangedListener in interface PropertyBagChangedSource

Parameters:

listener - an object which handles PropertyBagChangedEvent events the listener is not added a second time if it already exists in the list of listeners for this event.

See Also:

PropertyBagChangedSource

removePropertyBagChangedListener

public void removePropertyBagChangedListener(PropertyBagChangedListener listener)

Remove a listener for the PropertyBagChangedEvent event. Nothing happens if the listener is not in the list of listeners for this event.

Specified by:

removePropertyBagChangedListener in interface PropertyBagChangedSource

Parameters:

listener - an object which handles PropertyBagChangedEvent events

See Also:

PropertyBagChangedSource

firePropertyBagChanged

public void firePropertyBagChanged(PropertyBagChangedEvent propertyBagChangedEvent)

Deliver a PropertyBagChangedEvent. If firingEvents() returns false, do nothing, else invoke the listener's propertyBagChanged(PropertyBagChangedEvent) method

Parameters:

propertyBagChangedEvent - a PropertyBagChangedEvent

propertyChange

public void propertyChange(java.beans.PropertyChangeEvent event)

Handle a property change event from an inner property bag. Fire a new property bag changed event from this property bag to all listeners if the event source is one of the properties.

Specified by:

propertyChange in interface java.beans.PropertyChangeListener

Parameters:

event - the change event

propertyBagChanged

public void propertyBagChanged(PropertyBagChangedEvent event)

Handle a property bag changed event. Since the only objects we listen for are items in this property bag itself, we assume the event came from one of these items. We repackage the event as a property bag changed event from this property bag.

Specified by:

propertyBagChanged in interface PropertyBagChangedListener

Parameters:

event - the change event

notifyListeners

protected void notifyListeners(java.lang.Object source)

Send a PropertyBagChangedEvent event to all listeners. Finds the property by name, using a sequential search; this should be sufficient for most property bags which normally have small sets of properties. This method provides the implementation for propertyChange(java.beans.PropertyChangeEvent) and propertyBagChanged(PropertyBagChangedEvent)

Parameters:

source - the object which has changed. This can be either an object which fired a PropertyChangeEvent, or another PropertyBagChangedSource which has fired a PropertyBagChangedEvent

disableEvents

public void disableEvents()

Ask this property bag to suppress delivery of PropertyBagChangedEvents on subsequent changes to this property bag or its contents.

This call should appear in a try { } block, with the matching enableEvents(HowChanged) method in the finally { } block.

enableEvents

public void enableEvents(HowChanged howChanged)

Undo a call. This may or may not cause this collection to start sending events again. If there are no other pending suppress/allow gates on this collection, it will send a single PropertyBagChangeEvent and then subsequent changes to this collection will also fire PropertyBagChangeEvent

This call should always appear in a finally { } block; the disableEvents calls should be in the try { }block.

eventsEnabled

protected boolean eventsEnabled()

Return true if events are enabled.

Returns:

false if disableEvents() has been called without the corresponding enableEvents(HowChanged) being called.

equals

public boolean equals(java.lang.Object o)

Compare to another object.

Overrides:

equals in class java.lang.Object

Parameters:

o - another object

Returns:

if o is another PropertyBag, then returns equals((PropertyBag) o), else returns false

equals

public boolean equals(PropertyBag bag)

Compare this property bag to another PropertyBag to see if they have the same contents.

Parameters:

bag - another PropertyBag

Returns:

true if the two bags are equal. They are equal if they have the same set of keys and the corresponding values are equal. If two like named items are also PropertyBags, the comparison is performed recursively.

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Clone a property bag. The defaults, if any, are not cloned

Specified by:

clone in interface StaticPropertyBagInterface

Specified by:

clone in interface com.sas.PublicClonable

Overrides:

clone in class java.lang.Object

Returns:

a clone of this property bag

Throws:

java.lang.CloneNotSupportedException - if the object cannot be cloned.

clone

public java.lang.Object clone(com.sas.DeepCloneSupport support,
                              boolean deeply)
                       throws java.lang.CloneNotSupportedException

Clone a property bag, optionally cloning deeply. This clones any subobjects that are themselves a StaticPropertyBagInterface objects which implement DeepClonable. The defaults are not cloned, as they may be used by other property bags.

Specified by:

clone in interface com.sas.DeepClonable

Parameters:

support - an object to keep track of cloned objects. If null, then this method does not try to preserve structure or avoid infinite loops, and may result in a StackOverflowError.

deeply - if true, clone deeply: elements which are themselves StaticPropertyBagInterface objects will be cloned as well.

Throws:

java.lang.CloneNotSupportedException

validateObject

public void validateObject()

After deserialization, reestablish this property bag as a listener. This is called during deserialization, after all objects have been read in (their PropertyChange listener lists are now available)

Specified by:

validateObject in interface java.io.ObjectInputValidation

toString

public java.lang.String toString()

Convert a property bag to a String representation. This consists of n pairs of the form key=value

Overrides:

toString in class java.lang.Object

Returns:

the string representation of a PropertyBag

collect

public static int collect(PropertyBagInterface target,
                          PropertyBagInterface query,
                          StaticPropertyBagInterface source)

Collect values from a source property bag, according to the elements in the query property bag, merging results into the target property bag. This method is static since it has side effects on more than one property bag.

For a scenario where this collect method is useful, consider a display or publishing system where elements are organized hierarchically, such as cells within rows within pages of a table, or words within paragraphs within sections of a document. Each of these elements may have certain style properties associated with them, represented by property bags. Complex properties such as a font, may be represented by an embedded property sheet, which can allow unspecified properties such as the font size filter down from the corresponsing font size property of the enclosing element. If an element does not have a property value for a specific property, such as foregroundColor, or for a complex property like font.face, then this value is inherited from the next hierer level in the hierarchy. So, a word in a document may only specify a foreground color and a font style of BOLD, while the paragraph may specify foreground and background colors, justification font family, size, and style, and the section may specify a marginWidth, font, and colors:

 wordStyle = {foregroundColor=Blue font={style=Bold}}
 paraStyle = {foregroundColor=Black backgroundColor=White font={family=SansSerif size=12 style=NORMAL}}
 sectStyle = {foregroundColor=Black backgroundColor=White font={family=Serif size=12 style=NORMAL} marginWidth=1}
 

Given these values, the successive calls to collect will yield a full set of unique properties from the wordStyle, paraStyle, and sectStyle, with the more specific properties masking the more general values:

 PropertyBag target = new PropertyBag();
 PropertyBag query = new PropertyBag();
 query = bag.set("foregroundColor", Color.blue);
 query = bag.set("backgroundColor", Color.blue);
 PropertyBag font = new PropertyBag();
 font.set("style", null);
 font.set("family", null);
 font.set("size", null);
 font.set("style", null);
 query = bag.set("font", font);
 PropertyBag.collect(target, query, wordStyle);
 PropertyBag.collect(target, query, paraStyle);
 PropertyBag.collect(target, query, sectStyle);
 

These three calls to collect leave target with the values {foregroundColor=Blue backgroundColor=White font{style=Boldfamily=SansSerif size=12 style=NORMAL} } Note that marginWidth does not appear in the result, since it is not part of the query.

Parameters:

target - a property bag where values are collected. Values from source are merged into this bag. Normally you start with an empty target property bag.

query - is a property bag which lists which properties to merge from each successive source property bag. Atomic items are merged into the the target, then removed from the querey bag. Items from the query which implement the PropertyBagInterface are collected recursively. If the recursive collect action leaves the query's item property bag empty, the item bag is removed from query

source - where the values are to come from.

Returns:

the number of values merged into the top level property bag. This count includes 1 for each atomic item collected, and 1 for each embedded bag contained in query for which items were collected from the corresponding embedded bag from source

See Also:

merge(com.sas.collection.StaticPropertyBagInterface), merge(java.lang.String, java.lang.Object)

setProperties

public void setProperties(java.lang.Object bean)

Extract the properties from the property bag properties and apply them to the public properties of the bean. This uses reflection to set properties of a bean, based on the property names in the properties. If a specific value from the properties bag is another StaticPropertyBagInterface, then setProperties will recurse on the corresponding property, if its type is not a primitive or an array. There is one exception to this. If the value from the property bag is another StaticPropertyBagInterface, and the it contains only one value, and it's name is null or empty; this indicates the value to assign to the named property is the nested property bag, rather than recursing.

Parameters:

bean - an object that properties should be assigned to.

properties - a property bag containing properties to set on the bean

Throws:

java.lang.RuntimeException - if a property cannot be set.

setProperties

public static void setProperties(java.lang.Object bean,
                                 StaticPropertyBagInterface properties)

Extract the properties from the property bag properties and apply them to the public properties of the bean. This uses reflection to set properties of a bean, based on the property names in the properties. If a specific value from the properties bag is another StaticPropertyBagInterface, then setProperties will recurse on the corresponding property, if its type is not a primitive or an array. There is one exception to this. If the value from the property bag is another StaticPropertyBagInterface, and the it contains only one value, and it's name is null or empty; this indicates the value to assign to the named property is the nested property bag, rather than recursing.

Parameters:

bean - an object that properties should be assigned to.

properties - a property bag containing properties to set on the bean

Throws:

java.lang.RuntimeException - if a property cannot be set.

Since:

version 2.0

load

public void load(java.io.InputStream stream)
          throws java.io.IOException

Load properties from an input stream. This works like load(InputStream) in java.util.Properties.

Parameters:

properties - a property bag to load with the properties read from the stream

stream - an input stream of property values.

Throws:

java.io.IOException

Since:

version 2.0

load

public static void load(PropertyBagInterface properties,
                        java.io.InputStream stream)
                 throws java.io.IOException

Load properties from an input stream. This works like load(InputStream) in java.util.Properties.

Parameters:

properties - a property bag to load with the properties read from the stream

stream - an input stream of property values.

Throws:

java.io.IOException

Since:

version 2.0

save

public void save(java.io.OutputStream stream,
                 java.lang.String header)
          throws java.io.IOException

Save properties from an Output stream. This works like Properties.save(java.io.OutputStream, java.lang.String)

Parameters:

properties - a property bag to save with the properties read from the stream

stream - an Output stream of property values.

header - a comment to put into the string.

Throws:

java.io.IOException

Since:

version 2.0

save

public static void save(StaticPropertyBagInterface properties,
                        java.io.OutputStream stream,
                        java.lang.String header)
                 throws java.io.IOException

Save properties to an Output stream. This works like Properties.save(java.io.OutputStream, java.lang.String).

Parameters:

properties - a property bag to save with the properties read from the stream

stream - an Output stream of property values.

header - a comment to put into the string.

Throws:

java.io.IOException

Since:

version 2.0

addItems

public PropertyBagInterface addItems(java.util.Properties props)

Copy the the key/values from a Properties object into this property bag. like load(InputStream) in java.util.Properties.

Parameters:

properties - a Properties object; its contents are copied into the property bag.

Returns:

this property bag.

Since:

version 2.0

addItems

public static PropertyBagInterface addItems(PropertyBagInterface bag,
                                            java.util.Properties properties)

Copy the the key/values from a Properties object into a property bag.

Parameters:

properties - a Properties object; its contents are copied into the property bag.

bag - the target property bag. If null, a new PropertyBag is constructed and returned.

Returns:

the target property bag.

Since:

version 2.0

toProperties

public java.util.Properties toProperties(java.util.Properties properties)

Copy the key/value pairs from this property bag into a Properties object.

Parameters:

properties - the Properties object to populate. If null, a new Properties object is created.

Returns:

a Properties object (the input properties if not null) that contains the keys and values of this property bag.

Since:

version 2.0

toProperties

public static java.util.Properties toProperties(StaticPropertyBagInterface propertyBag,
                                                java.util.Properties properties)

Copy the key/value pairs from a property bag into a Properties object.

Parameters:

bag - a property bag from which key/value pairs are copied.

properties - the Properties object to populate. If null, a new Properties object is created.

Returns:

a Properties object (the input properties if not null) that contains the keys and values of this property bag

Since:

version 2.0