net.infonode.properties.propertymap

Interface PropertyMap

public interface PropertyMap extends ReadWritable

A property map contains values for some or all properties in a PropertyMapGroup. A property map can have any number of super maps from which property values are inherited. Super maps that are searched for values in the reverse order they were added to the property map. Property values are always set in the property map specified.

Properties of type PropertyMapProperty in the PropertyMapGroup will automatically be assigned new PropertyMap's as values. These PropertyMap's are called child maps. These property values cannot be modified.

Listeners can be added to a PropertyMap. The listeners are notified when a property value is modified in the PropertyMap or, if the property value is not overridden, one of it's super maps. A tree listener can also be added that listens for value changes in the property map, it's super maps and it's child mapss.

Property maps are created using the factory methods in PropertyMapFactory.

Version: $Revision: 1.20 $

Author: $Author: jesper $

Method Summary
voidaddListener(PropertyMapListener listener)
Adds a listener that listens for value changes in this PropertyMap.
voidaddPropertyChangeListener(Property property, PropertyChangeListener listener)
Adds a property listener that listens for value changes for a specific property.
voidaddSuperMap(PropertyMap superMap)
Adds a super map to this map.
voidaddTreeListener(PropertyMapTreeListener listener)
Adds a tree listener that listens for value changes in this PropertyMap or any child maps.
voidclear(boolean recursive)
Removes all property values in this property map.
PropertyMapcopy(boolean copySuperMapRefs, boolean recursive)
Creates a copy of this map.
ObjectcreateRelativeRef(Property fromProperty, PropertyMap toMap, Property toProperty)
Creates a relative reference from one property value to another property value.
PropertyMapgetSuperMap()
Returns the most recently added super map.
booleanisEmpty(boolean recursive)
Returns true if this property map doesn't contain any property values.
voidread(ObjectInputStream in)
Reads property values from a stream and sets them in this map.
voidremoveListener(PropertyMapListener listener)
Removes a listener which was previously added with addListener.
voidremovePropertyChangeListener(Property property, PropertyChangeListener listener)
Removes a previously added property listener.
PropertyMapremoveSuperMap()
Removes the most recently added super map.
booleanremoveSuperMap(PropertyMap superMap)
Removes a super map that has previously been added using addSuperMap.
voidremoveTreeListener(PropertyMapTreeListener listener)
Removes a previously added tree listener.
ObjectremoveValue(Property property)
Removes a property value.
booleanreplaceSuperMap(PropertyMap oldSuperMap, PropertyMap newSuperMap)
Replaces a super map that has previously been added using addSuperMap.
booleanvaluesEqualTo(PropertyMap propertyMap, boolean recursive)
Returns true if all the values in this property map is equal to the values in the given map.
voidwrite(ObjectOutputStream out, boolean recursive)
Serializes the serializable values of this property map.
voidwrite(ObjectOutputStream out)

Serializes the serializable values of this property map.

Method Detail

addListener

public void addListener(PropertyMapListener listener)
Adds a listener that listens for value changes in this PropertyMap. This listener will be notified of updates to values in this PropertyMap and super maps unless the property value is overridden.

Parameters: listener the listener

addPropertyChangeListener

public void addPropertyChangeListener(Property property, PropertyChangeListener listener)
Adds a property listener that listens for value changes for a specific property. This listener will be notified of value changes for the property in this PropertyMap and super maps unless the property value is overridden.

Parameters: property the property to listen to changes on listener the listener

addSuperMap

public void addSuperMap(PropertyMap superMap)
Adds a super map to this map. If a property value is not found in this property map, the super maps will be searched recursively. The super map last added will be searched first.

Parameters: superMap the super map

addTreeListener

public void addTreeListener(PropertyMapTreeListener listener)
Adds a tree listener that listens for value changes in this PropertyMap or any child maps. This listener will be notified of updates to values in this PropertyMap, any child map recusively and super maps unless the property value is overridden.

Parameters: listener the listener

clear

public void clear(boolean recursive)
Removes all property values in this property map.

Parameters: recursive true if child maps should be cleared recursively

copy

public PropertyMap copy(boolean copySuperMapRefs, boolean recursive)
Creates a copy of this map. The method copies the values and optionally the references to super maps.

Parameters: copySuperMapRefs if true, copies the references to super maps recursive if true, copies all child maps as well

Returns: a copy of this map

Since: IDW 1.3.0

createRelativeRef

public Object createRelativeRef(Property fromProperty, PropertyMap toMap, Property toProperty)
Creates a relative reference from one property value to another property value.

When the value of the fromProperty is read, it will return the value of the toProperty in the toMap.

Sub maps of this property map will inherit this reference relative to themselves, ie the reference in the sub map is converted to a reference relative to the sub map if possible, otherwise the reference is the same as for the super map. Here is an example:

Changes to the referenced property value will be propagated to listeners of this property.

Parameters: fromProperty the property value that will hold the reference toMap the property map that holds the property value that is referenced toProperty the property which value is referenced

Returns: the old value that the fromProperty had in this property map

Throws: InvalidPropertyTypeException

getSuperMap

public PropertyMap getSuperMap()
Returns the most recently added super map.

Returns: the super map

isEmpty

public boolean isEmpty(boolean recursive)
Returns true if this property map doesn't contain any property values.

Parameters: recursive true if child maps should be recursively checked

Returns: true if this property map doesn't contain any property values

read

public void read(ObjectInputStream in)
Reads property values from a stream and sets them in this map. Will overwrite existing values, but not remove values not found in the stream. The properties are identified using their names. If no property is found for a property name read from the stream the value is skipped and no error is reported. If a value for a property in the stream is a reference to a another property value that cannot be resolved, the property is not modified.

Parameters: in the stream from which to read property values

Throws: IOException if there is an error in the stream

removeListener

public void removeListener(PropertyMapListener listener)
Removes a listener which was previously added with addListener.

Parameters: listener the listener

removePropertyChangeListener

public void removePropertyChangeListener(Property property, PropertyChangeListener listener)
Removes a previously added property listener.

Parameters: property the property which the listener listens to changes on listener the listener

removeSuperMap

public PropertyMap removeSuperMap()
Removes the most recently added super map.

Returns: the super map removed

removeSuperMap

public boolean removeSuperMap(PropertyMap superMap)
Removes a super map that has previously been added using addSuperMap.

Parameters: superMap the super map to remove

Returns: true if the super map was found and removed, otherwise false

Since: IDW 1.3.0

removeTreeListener

public void removeTreeListener(PropertyMapTreeListener listener)
Removes a previously added tree listener.

Parameters: listener the listener

removeValue

public Object removeValue(Property property)
Removes a property value.

Parameters: property the property

Returns: the value removed

Throws: InvalidPropertyException if values for this property can't be stored in this property map

replaceSuperMap

public boolean replaceSuperMap(PropertyMap oldSuperMap, PropertyMap newSuperMap)
Replaces a super map that has previously been added using addSuperMap.

Parameters: oldSuperMap the super map to replace newSuperMap the super map to replace it with

Returns: true if the super map was found and replaced, otherwise false

Since: IDW 1.3.0

valuesEqualTo

public boolean valuesEqualTo(PropertyMap propertyMap, boolean recursive)
Returns true if all the values in this property map is equal to the values in the given map. The property values are compared using Object#equals.

Parameters: propertyMap the map to compare values with recursive true if child maps should be recursively checked

Returns: true if all the values in this property map is equal to the values in the given map

write

public void write(ObjectOutputStream out, boolean recursive)
Serializes the serializable values of this property map. Values not implementing the java.io.Serializable interface will not be written to the stream. The properties are identified using their names.

Parameters: out the stream on which to serialize this map recursive true if child maps should be recursively serialized

Throws: IOException if there is an error in the stream

write

public void write(ObjectOutputStream out)

Serializes the serializable values of this property map. Values not implementing the java.io.Serializable interface will not be written to the stream. The properties are identified using their names.

This method recursively writes all child maps.

Parameters: out the stream

Throws: IOException if there is a stream error