All Libraries | This Library | Package | Class | Use | Tree | Deprecated | Index | Grand Index | Help
|  | Components |
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 `PropertyChangeEvent`s or `PropertyBagChangedEvent`s (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 `PropertyBagChangedEvent`s
`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 `PropertyBagChangedEvent`s 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 `PropertyBagChangedEvent`s

### 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 `PropertyBagChangedEvent`s 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 `PropertyBag`s, 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

All Libraries | This Library | Package | Class | Use | Tree | Deprecated | Index | Grand Index | Help
|  | Components |
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2009 SAS Institute Inc. All Rights Reserved.