001: package org.apache.commons.events.observable;
002:
003: import java.util.Collection;
004: import java.util.Map;
005:
006: /**
007: * <p>
008: * This interface defines a factory for the production of
009: * CollectionChangeEvents. The purpose of this factory is to provide a means
010: * of instantiating custom, user-defined CollectionChangeEvents without
011: * modification to the BoundCollection or ConstrainedCollection classes.
012: * Should users decide to write their own CollectionChangeEvents which
013: * provide more information than the supplied classes, they would need to
014: * implement this interface and supply an instance to the appropriate
015: * ObservedCollection class.
016: * </p>
017: *
018: * @see CollectionChangeEvent
019: * @see CollectionChangeType
020: * @see BoundCollection
021: * @see ConstrainedCollection
022: * @author Bryce Nordgren / USDA Forest Service
023: * @since 0.1
024: */
025: public interface CollectionChangeEventFactory extends Cloneable {
026:
027: /**
028: * Returns the collection responsible for events constructed by this
029: * factory. This must be one of the decorator classes defined in
030: * this package.
031: * @return source of CollectionChangeEvents.
032: */
033: public Object getCollection();
034:
035: /**
036: * Sets the collection responsible for events constructed by this
037: * factory. This must be one of the decorator classes defined in
038: * this package. The type of this property is <code>Object</code>
039: * because <code>java.util.Map</code>, while part of the Collections
040: * framework, does not share a common parentage with
041: * <code>java.util.Collection</code>. Legal values are instances or
042: * subclasses of:
043: * <ul>
044: * <li> BoundCollection </li>
045: * <li> ConstrainedCollection </li>
046: * <li> BoundMap </li>
047: * </ul>
048: * This method is only allowed to be called
049: * once. Subsequent calls should result in an
050: * UnsupportedOperationException.
051: * @param source The source of CollectionChangeEvents.
052: * @throws IllegalArgumentException if <code>source</code> is not
053: * a BoundCollection or a ConstrainedCollection.
054: * @throws UnsupportedOperationException if the source has already
055: * been set.
056: */
057: public void setCollection(Object source);
058:
059: /**
060: * <p>
061: * Clones a <code>CollectionChangeEventFactory</code> by
062: * constructing a copy of the existing factory, <i>without</i> copying the
063: * event source. The user <i>must</i> call <code>setCollection()</code>
064: * on the returned factory prior to use. In effect, this event factory
065: * suffers from inadequate separation of concerns because it is required to
066: * know the details of event construction as well as the specific object
067: * which caused the event. This clone method causes duplication of the
068: * event construction logic while permitting the caller to specify a
069: * different event source. As such, implementors should ensure that all
070: * configuration and setup from the original object is duplicated in the
071: * returned object <i>except for the event source</i>.
072: * </p>
073: * <p>
074: * This method exists so that sub lists (and other derivative collections)
075: * can use the same event factory as the original list.
076: * </p>
077: * @return A duplicate of this factory, except the event source is not set.
078: */
079: public Object clone();
080:
081: /**
082: * Instantiates and returns a <code>CollectionChangeEvent</code>
083: * of type <code>ADD</code>.
084: *
085: * @param element The element added to the collection.
086: * @param changed <code>True</code> if the element was added to the
087: * collecton, <code>false</code> otherwise.
088: * @return A new event, properly initialized and ready to fire.
089: */
090: public CollectionChangeEvent createAdd(Object element,
091: boolean changed);
092:
093: /**
094: * Instantiates and returns a <code>CollectionChangeEvent</code>
095: * of type <code>ADD_INDEXED</code>. The "parameter"
096: * property is initialized to contain the index.
097: *
098: * @param element The element added to the collection.
099: * @param index The index at which the item is added.
100: * @param changed <code>True</code> if the element was added to the
101: * collecton, <code>false</code> otherwise.
102: * @return A new event, properly initialized and ready to fire.
103: */
104: public CollectionChangeEvent createAddIndexed(int index,
105: Object element, boolean changed);
106:
107: /**
108: * Instantiates and returns a <code>CollectionChangeEvent</code>
109: * of type <code>ADD_NCOPIES</code>. The "parameter"
110: * property is initialized to contain the specified number of copies.
111: *
112: * @param element The element added to the collection.
113: * @param copies How many copies to add.
114: * @param changed <code>True</code> if the element was added to the
115: * collecton, <code>false</code> otherwise.
116: * @return A new event, properly initialized and ready to fire.
117: */
118: public CollectionChangeEvent createAddNCopies(int copies,
119: Object element, boolean changed);
120:
121: /**
122: * Instantiates and returns a <code>CollectionChangeEvent</code>
123: * of type <code>ADD_ITERATED</code>. The "parameter"
124: * property is initialized to contain the index.
125: *
126: * @param element The element added to the collection.
127: * @param index The index at which the item is added.
128: * @param changed <code>True</code> if the element was added to the
129: * collecton, <code>false</code> otherwise.
130: * @return A new event, properly initialized and ready to fire.
131: */
132: public CollectionChangeEvent createAddIterated(int index,
133: Object element, boolean changed);
134:
135: /**
136: * Instantiates and returns a <code>CollectionChangeEvent</code>
137: * of type <code>ADD_ALL</code>.
138: *
139: * @param element The collection containing all the elements to be added.
140: * @param changed <code>True</code> if the element was added to the
141: * collecton, <code>false</code> otherwise.
142: * @return A new event, properly initialized and ready to fire.
143: */
144: public CollectionChangeEvent createAddAll(Collection element,
145: boolean changed);
146:
147: /**
148: * Instantiates and returns a <code>CollectionChangeEvent</code>
149: * of type <code>ADD_ALL_INDEXED</code>. The "parameter"
150: * property is initialized to contain the index.
151: *
152: * @param element The collection containing all the elements to be added.
153: * @param index The index at which the collection is added.
154: * @param changed <code>True</code> if the element was added to the
155: * collecton, <code>false</code> otherwise.
156: * @return A new event, properly initialized and ready to fire.
157: */
158: public CollectionChangeEvent createAddAllIndexed(int index,
159: Collection element, boolean changed);
160:
161: /**
162: * Instantiates and returns a <code>CollectionChangeEvent</code>
163: * of type <code>CLEAR</code>.
164: *
165: * @param changed <code>True</code> if the collection was nonempty
166: * before it was cleared, <code>false</code> otherwise.
167: * @return A new event, properly initialized and ready to fire.
168: */
169: public CollectionChangeEvent createClear(boolean changed);
170:
171: /**
172: * Instantiates and returns a <code>CollectionChangeEvent</code>
173: * of type <code>REMOVE</code>.
174: *
175: * @param element The element removed from the collection.
176: * @param changed <code>True</code> if the element was removed from the
177: * collecton, <code>false</code> otherwise.
178: * @return A new event, properly initialized and ready to fire.
179: */
180: public CollectionChangeEvent createRemove(Object element,
181: boolean changed);
182:
183: /**
184: * Instantiates and returns a <code>CollectionChangeEvent</code>
185: * of type <code>REMOVE_INDEXED</code>. The "parameter"
186: * property is initialized to contain the index.
187: *
188: * @param element The element removed from the collection.
189: * @param index The index of the removed item.
190: * @param changed <code>True</code> if the element was removed from the
191: * collecton, <code>false</code> otherwise.
192: * @return A new event, properly initialized and ready to fire.
193: */
194: public CollectionChangeEvent createRemoveIndexed(int index,
195: Object element, boolean changed);
196:
197: /**
198: * Instantiates and returns a <code>CollectionChangeEvent</code>
199: * of type <code>REMOVE_NCOPIES</code>. The "parameter"
200: * property is initialized to contain the index.
201: *
202: * @param element The element removed from the collection.
203: * @param copies The number of copies to remove.
204: * @param changed <code>True</code> if the element was removed from the
205: * collecton, <code>false</code> otherwise.
206: * @return A new event, properly initialized and ready to fire.
207: */
208: public CollectionChangeEvent createRemoveNCopies(int copies,
209: Object element, boolean changed);
210:
211: /**
212: * Instantiates and returns a <code>CollectionChangeEvent</code>
213: * of type <code>REMOVE_NEXT</code>. The "parameter"
214: * property is initialized to contain the index. This event
215: * applies to a buffer.
216: *
217: * @param element The element removed from the buffer.
218: * @param changed <code>True</code> if the element was removed from the
219: * collecton, <code>false</code> otherwise.
220: * @return A new event, properly initialized and ready to fire.
221: */
222: public CollectionChangeEvent createRemoveNext(Object element,
223: boolean changed);
224:
225: /**
226: * Instantiates and returns a <code>CollectionChangeEvent</code>
227: * of type <code>REMOVE_ITERATED</code>. The "parameter"
228: * property is initialized to contain the index.
229: *
230: * @param element The element removed from the collection.
231: * @param index The index of the iterator when remove was called.
232: * @param changed <code>True</code> if the element was removed from the
233: * collecton, <code>false</code> otherwise.
234: * @return A new event, properly initialized and ready to fire.
235: */
236: public CollectionChangeEvent createRemoveIterated(int index,
237: Object element, boolean changed);
238:
239: /**
240: * Instantiates and returns a <code>CollectionChangeEvent</code>
241: * of type <code>REMOVE_ALL</code>.
242: *
243: * @param element The collection containing all items to remove from
244: * this collection.
245: * @param changed <code>True</code> if the element was removed from the
246: * collecton, <code>false</code> otherwise.
247: * @return A new event, properly initialized and ready to fire.
248: */
249: public CollectionChangeEvent createRemoveAll(Collection element,
250: boolean changed);
251:
252: /**
253: * Instantiates and returns a <code>CollectionChangeEvent</code>
254: * of type <code>RETAIN_ALL</code>.
255: *
256: * @param element The Collection containing all elements to be retained.
257: * @param changed <code>True</code> if the observed collection was
258: * changed.
259: * @return A new event, properly initialized and ready to fire.
260: */
261: public CollectionChangeEvent createRetainAll(Collection element,
262: boolean changed);
263:
264: /**
265: * Instantiates and returns a <code>CollectionChangeEvent</code>
266: * of type <code>SET_INDEXED</code>. The "parameter"
267: * property is initialized to contain the index. Additionally, the
268: * <code>oldValue</code> and <code>newValue</code> properties are
269: * set to the former and current values of the element at the index,
270: * respectively.
271: *
272: * @param element The new value of the element at <code>index</code>.
273: * This is stored in the <code>element</code> and <code>newValue</code>
274: * properties.
275: * @param oldValue The former value of the element at <code>index</code>.
276: * This is stored in the <code>oldValue</code> property.
277: * @param index The index of the changed item.
278: * @param changed <code>True</code> if the element was changed,
279: * <code>false</code> otherwise.
280: * @return A new event, properly initialized and ready to fire.
281: */
282: public CollectionChangeEvent createSetIndexed(int index,
283: Object oldValue, Object element, boolean changed);
284:
285: /**
286: * Instantiates and returns a <code>CollectionChangeEvent</code>
287: * of type <code>SET_ITERATED</code>. The "parameter"
288: * property is initialized to contain the index. Additionally, the
289: * <code>oldValue</code> and <code>newValue</code> properties are
290: * set to the former and current values of the element at the index,
291: * respectively.
292: *
293: * @param element The new value of the element at <code>index</code>.
294: * This is stored in the <code>element</code> and <code>newValue</code>
295: * properties.
296: * @param oldValue The former value of the element at <code>index</code>.
297: * This is stored in the <code>oldValue</code> property.
298: * @param index The index of the changed item.
299: * @param changed <code>True</code> if the element was changed,
300: * <code>false</code> otherwise.
301: * @return A new event, properly initialized and ready to fire.
302: */
303: public CollectionChangeEvent createSetIterated(int index,
304: Object oldValue, Object element, boolean changed);
305:
306: /**
307: * Instantiates and returns a <code>CollectionChangeEvent</code>
308: * of type <code>PUT</code>. This is unique among the
309: * <code>CollectionChangeEvents</code> in that a single addition
310: * involves two objects, namely a key-value pair. Additionally,
311: * the if the key was already present in the map, the former
312: * value is returned. The former and present "values" are
313: * stored in <code>oldValue</code> and <code>newValue</code> properties,
314: * respectively. The <code>element</code> property is set to the key.
315: *
316: * @param key The key provided to the <code>put()</code> method.
317: * @param value The value provided to the <code>put()</code> method.
318: * @param oldValue The value returned by the call to <code>put()</code>.
319: * @param changed <code>True</code> if the element was changed,
320: * <code>false</code> otherwise.
321: * @return A new event, properly initialized and ready to fire.
322: */
323: public CollectionChangeEvent createPut(Object key, Object value,
324: Object oldValue, boolean changed);
325:
326: /**
327: * Instantiates and returns a <code>CollectionChangeEvent</code>
328: * of type <code>PUT_ALL</code>. The <code>element</code> property
329: * is set to the Map containing all the entries to be added.
330: *
331: * @param newElements The map containing the entries to add.
332: * @param changed <code>True</code> if the element was changed,
333: * <code>false</code> otherwise.
334: * @return A new event, properly initialized and ready to fire.
335: */
336: public CollectionChangeEvent createPutAll(Map newElements,
337: boolean changed);
338:
339: }
|