001: package org.apache.commons.events.observable;
002:
003: import java.util.Collection;
004: import java.util.Iterator;
005:
006: import org.apache.commons.collections.collection.AbstractCollectionDecorator;
007: import org.apache.commons.collections.iterators.AbstractIteratorDecorator;
008:
009: /**
010: * Decorates a <code>Collection</code> implementation to observe modifications.
011: * <p>
012: * Each modifying method call made on this <code>Collection</code> is forwarded to a
013: * {@link ModificationHandler}.
014: * The handler manages the event, notifying listeners and optionally vetoing changes.
015: * The default handler is {@link StandardModificationHandler}.
016: * See this class for details of configuration available.
017: *
018: * @since Commons Events 1.0
019: * @version $Revision: 155443 $ $Date: 2005-02-26 06:19:51 -0700 (Sat, 26 Feb 2005) $
020: *
021: * @author Stephen Colebourne
022: */
023: public class ConstrainedCollection extends AbstractCollectionDecorator {
024:
025: // ObservableCollection factories
026: //-----------------------------------------------------------------------
027: /**
028: * Factory method to create an observable collection.
029: * <p>
030: * A {@link StandardModificationHandler} will be created.
031: * This can be accessed by {@link #getHandler()} to add listeners.
032: *
033: * @param coll the collection to decorate, must not be null
034: * @return the observed collection
035: * @throws IllegalArgumentException if the collection is null
036: */
037: public static ConstrainedCollection decorate(final Collection coll) {
038: return new ConstrainedCollection(coll, null);
039: }
040:
041: /**
042: * Factory method to create an observable collection using a listener or a handler.
043: * <p>
044: * A lot of functionality is available through this method.
045: * If you don't need the extra functionality, simply implement the
046: * {@link org.apache.commons.events.observable.standard.StandardModificationListener}
047: * interface and pass it in as the second parameter.
048: * <p>
049: * Internally, an <code>ObservableCollection</code> relies on a {@link ModificationHandler}.
050: * The handler receives all the events and processes them, typically by
051: * calling listeners. Different handler implementations can be plugged in
052: * to provide a flexible event system.
053: * <p>
054: * The handler implementation is determined by the listener parameter via
055: * the registered factories. The listener may be a manually configured
056: * <code>ModificationHandler</code> instance.
057: * <p>
058: * The listener is defined as an Object for maximum flexibility.
059: * It does not have to be a listener in the classic JavaBean sense.
060: * It is entirely up to the factory and handler as to how the parameter
061: * is interpretted. An IllegalArgumentException is thrown if no suitable
062: * handler can be found for this listener.
063: * <p>
064: * A <code>null</code> listener will create a {@link StandardModificationHandler}.
065: *
066: * @param coll the collection to decorate, must not be null
067: * @param listener collection listener, may be null
068: * @return the observed collection
069: * @throws IllegalArgumentException if the collection is null
070: * @throws IllegalArgumentException if there is no valid handler for the listener
071: */
072: public static ConstrainedCollection decorate(final Collection coll,
073: final Object listener) {
074:
075: if (coll == null) {
076: throw new IllegalArgumentException(
077: "Collection must not be null");
078: }
079: return new ConstrainedCollection(coll, listener);
080: }
081:
082: // Constructors
083: //-----------------------------------------------------------------------
084: /**
085: * Constructor that wraps (not copies) and takes a handler.
086: * <p>
087: * The handler implementation is determined by the listener parameter via
088: * the registered factories. The listener may be a manually configured
089: * <code>ModificationHandler</code> instance.
090: *
091: * @param coll the collection to decorate, must not be null
092: * @param listener the observing handler, may be null
093: * @throws IllegalArgumentException if the collection is null
094: */
095: protected ConstrainedCollection(final Collection coll,
096: final Object listener) {
097: super (coll);
098: }
099:
100: /**
101: * Constructor used by subclass views, such as subList.
102: *
103: * @param coll the collection to decorate, must not be null
104: * @throws IllegalArgumentException if the collection is null
105: */
106: protected ConstrainedCollection(final Collection coll) {
107: super(coll);
108: }
109:
110: }
|