001    /*
002     *  Licensed to the Apache Software Foundation (ASF) under one or more
003     *  contributor license agreements.  See the NOTICE file distributed with
004     *  this work for additional information regarding copyright ownership.
005     *  The ASF licenses this file to You under the Apache License, Version 2.0
006     *  (the "License"); you may not use this file except in compliance with
007     *  the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     *  Unless required by applicable law or agreed to in writing, software
012     *  distributed under the License is distributed on an "AS IS" BASIS,
013     *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     *  See the License for the specific language governing permissions and
015     *  limitations under the License.
016     */
017    package org.apache.commons.collections.collection;
018    
019    import java.util.Collection;
020    import java.util.Iterator;
021    
022    /**
023     * Decorates another <code>Collection</code> to provide additional behaviour.
024     * <p>
025     * Each method call made on this <code>Collection</code> is forwarded to the
026     * decorated <code>Collection</code>. This class is used as a framework on which
027     * to build to extensions such as synchronized and unmodifiable behaviour. The
028     * main advantage of decoration is that one decorator can wrap any implementation
029     * of <code>Collection</code>, whereas sub-classing requires a new class to be
030     * written for each implementation.
031     * <p>
032     * This implementation does not perform any special processing with
033     * {@link #iterator()}. Instead it simply returns the value from the 
034     * wrapped collection. This may be undesirable, for example if you are trying
035     * to write an unmodifiable implementation it might provide a loophole.
036     *
037     * @since Commons Collections 3.0
038     * @version $Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
039     * 
040     * @author Stephen Colebourne
041     * @author Paul Jack
042     */
043    public abstract class AbstractCollectionDecorator implements Collection {
044    
045        /** The collection being decorated */
046        protected Collection collection;
047    
048        /**
049         * Constructor only used in deserialization, do not use otherwise.
050         * @since Commons Collections 3.1
051         */
052        protected AbstractCollectionDecorator() {
053            super();
054        }
055    
056        /**
057         * Constructor that wraps (not copies).
058         * 
059         * @param coll  the collection to decorate, must not be null
060         * @throws IllegalArgumentException if the collection is null
061         */
062        protected AbstractCollectionDecorator(Collection coll) {
063            if (coll == null) {
064                throw new IllegalArgumentException("Collection must not be null");
065            }
066            this.collection = coll;
067        }
068    
069        /**
070         * Gets the collection being decorated.
071         * 
072         * @return the decorated collection
073         */
074        protected Collection getCollection() {
075            return collection;
076        }
077    
078        //-----------------------------------------------------------------------
079        public boolean add(Object object) {
080            return collection.add(object);
081        }
082    
083        public boolean addAll(Collection coll) {
084            return collection.addAll(coll);
085        }
086    
087        public void clear() {
088            collection.clear();
089        }
090    
091        public boolean contains(Object object) {
092            return collection.contains(object);
093        }
094    
095        public boolean isEmpty() {
096            return collection.isEmpty();
097        }
098    
099        public Iterator iterator() {
100            return collection.iterator();
101        }
102    
103        public boolean remove(Object object) {
104            return collection.remove(object);
105        }
106    
107        public int size() {
108            return collection.size();
109        }
110    
111        public Object[] toArray() {
112            return collection.toArray();
113        }
114    
115        public Object[] toArray(Object[] object) {
116            return collection.toArray(object);
117        }
118    
119        public boolean containsAll(Collection coll) {
120            return collection.containsAll(coll);
121        }
122    
123        public boolean removeAll(Collection coll) {
124            return collection.removeAll(coll);
125        }
126    
127        public boolean retainAll(Collection coll) {
128            return collection.retainAll(coll);
129        }
130    
131        public boolean equals(Object object) {
132            if (object == this) {
133                return true;
134            }
135            return collection.equals(object);
136        }
137    
138        public int hashCode() {
139            return collection.hashCode();
140        }
141    
142        public String toString() {
143            return collection.toString();
144        }
145    
146    }