001: /*
002: * Copyright (C) 2004 NNL Technology AB
003: * Visit www.infonode.net for information about InfoNode(R)
004: * products and how to contact NNL Technology AB.
005: *
006: * This program is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU General Public License
008: * as published by the Free Software Foundation; either version 2
009: * of the License, or (at your option) any later version.
010: *
011: * This program is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
014: * GNU General Public License for more details.
015: *
016: * You should have received a copy of the GNU General Public License
017: * along with this program; if not, write to the Free Software
018: * Foundation, Inc., 59 Temple Place - Suite 330, Boston,
019: * MA 02111-1307, USA.
020: */
021:
022: // $Id: PropertyMap.java,v 1.20 2005/02/16 11:28:15 jesper Exp $
023: package net.infonode.properties.propertymap;
024:
025: import net.infonode.properties.base.Property;
026: import net.infonode.properties.base.exception.InvalidPropertyException;
027: import net.infonode.properties.base.exception.InvalidPropertyTypeException;
028: import net.infonode.properties.util.PropertyChangeListener;
029: import net.infonode.util.ReadWritable;
030:
031: import java.io.IOException;
032: import java.io.ObjectInputStream;
033: import java.io.ObjectOutputStream;
034:
035: /**
036: * A property map contains values for some or all properties in a {@link PropertyMapGroup}. A property map
037: * can have any number of super maps from which property values are inherited. Super maps that are searched for
038: * values in the reverse order they were added to the property map. Property values are always set in the property
039: * map specified.
040: * <p>
041: * Properties of type {@link PropertyMapProperty} in the {@link PropertyMapGroup} will automatically be assigned
042: * new PropertyMap's as values. These PropertyMap's are called child maps. These property values cannot be
043: * modified.
044: * <p>
045: * Listeners can be added to a PropertyMap. The listeners are notified when a property value is modified in the
046: * PropertyMap or, if the property value is not overridden, one of it's super maps. A tree listener can also
047: * be added that listens for value changes in the property map, it's super maps and it's child mapss.
048: * <p>
049: * Property maps are created using the factory methods in {@link PropertyMapFactory}.
050: *
051: * @author $Author: jesper $
052: * @version $Revision: 1.20 $
053: */
054: public interface PropertyMap extends ReadWritable {
055: /**
056: * Adds a listener that listens for value changes in this PropertyMap.
057: * This listener will be notified of updates to values in this PropertyMap and super maps unless the property
058: * value is overridden.
059: *
060: * @param listener the listener
061: */
062: void addListener(PropertyMapListener listener);
063:
064: /**
065: * Removes a listener which was previously added with {@link #addListener(PropertyMapListener)}.
066: *
067: * @param listener the listener
068: */
069: void removeListener(PropertyMapListener listener);
070:
071: /**
072: * Adds a tree listener that listens for value changes in this PropertyMap or any child maps.
073: * This listener will be notified of updates to values in this PropertyMap, any child map recusively and super
074: * maps unless the property value is overridden.
075: *
076: * @param listener the listener
077: */
078: void addTreeListener(PropertyMapTreeListener listener);
079:
080: /**
081: * Removes a previously added tree listener.
082: *
083: * @param listener the listener
084: */
085: void removeTreeListener(PropertyMapTreeListener listener);
086:
087: /**
088: * Adds a property listener that listens for value changes for a specific property.
089: * This listener will be notified of value changes for the property in this PropertyMap and super maps unless
090: * the property value is overridden.
091: *
092: * @param property the property to listen to changes on
093: * @param listener the listener
094: */
095: void addPropertyChangeListener(Property property,
096: PropertyChangeListener listener);
097:
098: /**
099: * Removes a previously added property listener.
100: *
101: * @param property the property which the listener listens to changes on
102: * @param listener the listener
103: */
104: void removePropertyChangeListener(Property property,
105: PropertyChangeListener listener);
106:
107: /**
108: * Adds a super map to this map.
109: * If a property value is not found in this property map, the super maps will be searched recursively. The
110: * super map last added will be searched first.
111: *
112: * @param superMap the super map
113: */
114: void addSuperMap(PropertyMap super Map);
115:
116: /**
117: * Removes the most recently added super map.
118: *
119: * @return the super map removed
120: */
121: PropertyMap removeSuperMap();
122:
123: /**
124: * Removes a super map that has previously been added using {@link #addSuperMap(PropertyMap)}.
125: *
126: * @param superMap the super map to remove
127: * @return true if the super map was found and removed, otherwise false
128: * @since IDW 1.3.0
129: */
130: boolean removeSuperMap(PropertyMap super Map);
131:
132: /**
133: * Replaces a super map that has previously been added using {@link #addSuperMap(PropertyMap)}.
134: *
135: * @param oldSuperMap the super map to replace
136: * @param newSuperMap the super map to replace it with
137: * @return true if the super map was found and replaced, otherwise false
138: * @since IDW 1.3.0
139: */
140: boolean replaceSuperMap(PropertyMap oldSuperMap,
141: PropertyMap newSuperMap);
142:
143: /**
144: * Returns the most recently added super map.
145: *
146: * @return the super map
147: */
148: PropertyMap getSuperMap();
149:
150: /**
151: * Creates a relative reference from one property value to another property value.
152: * <p>
153: * When the value of the <tt>fromProperty</tt> is read, it will return the value of the <tt>toProperty</tt> in the
154: * <tt>toMap</tt>.
155: * <p>
156: * Sub maps of this property map will inherit this reference relative to themselves, ie the reference in the sub
157: * map is converted to a reference relative to the sub map if possible, otherwise the reference is the same as
158: * for the super map. Here is an example:
159: * <p>
160: * <ul>
161: * <li>Property map A contains value 5 for property X.</li>
162: * <li>A relative reference is created in map A from property Y to property X. Getting the property value for Y in
163: * A will now return 5.</li>
164: * <li>A property map B is created and A is added as super map to B. Note that now B.Y will reference B.X and
165: * not A.X! Getting B.X now returns 5 and B.Y also returns 5.</li>
166: * <li>X is set to 7 in B. Getting B.Y will now return 7 as expected. Map A is unchanged and will still return
167: * 5 as value for property Y.</li>
168: * <li>A.Y is set to 1 which destroys the reference to A.X, and also the reference B.Y -> B.X. Getting B.Y will now
169: * return 1 as it's inherited from A.Y.
170: * </ul>
171: * <p>
172: * Changes to the referenced property value will be propagated to listeners of this property.
173: *
174: * @param fromProperty the property value that will hold the reference
175: * @param toMap the property map that holds the property value that is referenced
176: * @param toProperty the property which value is referenced
177: * @return the old value that the fromProperty had in this property map
178: * @throws InvalidPropertyTypeException
179: */
180: Object createRelativeRef(Property fromProperty, PropertyMap toMap,
181: Property toProperty) throws InvalidPropertyTypeException;
182:
183: /**
184: * Removes a property value.
185: *
186: * @param property the property
187: * @return the value removed
188: * @throws InvalidPropertyException if values for this property can't be stored in this property map
189: */
190: Object removeValue(Property property)
191: throws InvalidPropertyException;
192:
193: /**
194: * Returns true if this property map doesn't contain any property values.
195: *
196: * @param recursive true if child maps should be recursively checked
197: * @return true if this property map doesn't contain any property values
198: */
199: boolean isEmpty(boolean recursive);
200:
201: /**
202: * Removes all property values in this property map.
203: *
204: * @param recursive true if child maps should be cleared recursively
205: */
206: void clear(boolean recursive);
207:
208: /**
209: * Returns true if all the values in this property map is equal to the values in the given map.
210: * The property values are compared using {@link Object#equals}.
211: *
212: * @param propertyMap the map to compare values with
213: * @param recursive true if child maps should be recursively checked
214: * @return true if all the values in this property map is equal to the values in the given map
215: */
216: boolean valuesEqualTo(PropertyMap propertyMap, boolean recursive);
217:
218: /**
219: * Serializes the serializable values of this property map. Values not implementing the {@link java.io.Serializable}
220: * interface will not be written to the stream. The properties are identified using their names.
221: *
222: * @param out the stream on which to serialize this map
223: * @param recursive true if child maps should be recursively serialized
224: * @throws IOException if there is an error in the stream
225: */
226: void write(ObjectOutputStream out, boolean recursive)
227: throws IOException;
228:
229: /**
230: * <p>
231: * Serializes the serializable values of this property map. Values not implementing the {@link java.io.Serializable}
232: * interface will not be written to the stream. The properties are identified using their names.
233: * </p>
234: * <p>
235: * This method recursively writes all child maps.
236: * </p>
237: *
238: * @param out the stream
239: * @throws IOException if there is a stream error
240: */
241: void write(ObjectOutputStream out) throws IOException;
242:
243: /**
244: * Reads property values from a stream and sets them in this map.
245: * Will overwrite existing values, but not remove values not found in the stream.
246: * The properties are identified using their names.
247: * If no property is found for a property name read from the stream the value is skipped and no error is reported.
248: * If a value for a property in the stream is a reference to a another property value that cannot be resolved,
249: * the property is not modified.
250: *
251: * @param in the stream from which to read property values
252: * @throws IOException if there is an error in the stream
253: */
254: void read(ObjectInputStream in) throws IOException;
255:
256: /**
257: * Creates a copy of this map. The method copies the values and optionally the references to super maps.
258: *
259: * @param copySuperMapRefs if true, copies the references to super maps
260: * @param recursive if true, copies all child maps as well
261: * @return a copy of this map
262: * @since IDW 1.3.0
263: */
264: PropertyMap copy(boolean copySuperMapRefs, boolean recursive);
265: }
|