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    
018    package org.apache.commons.pipeline.stage;
019    
020    import java.util.Collection;
021    import java.util.Collections;
022    import org.apache.commons.pipeline.validation.ConsumedTypes;
023    import org.apache.commons.pipeline.validation.ProducesConsumed;
024    
025    /**
026     * This is a simple stage in the pipeline which will add each processed object 
027     * to the specified collection. 
028     *
029     * For the purposes of validation, this stage is considered to be able to consume
030     * objects of any class although the process() method may throw a ClassCastException
031     * if a processed object cannot be added to the collection.
032     */
033    @ConsumedTypes(Object.class)
034    @ProducesConsumed
035    public class AddToCollectionStage<T> extends BaseStage {
036        
037        /**
038         * Holds value of property collection.
039         */
040        private Collection<T> collection;
041    
042        /** 
043         * Creates a new instance of AddToCollectionStage.  This constructor
044         * will synchronized the collection by default.
045         */
046        public AddToCollectionStage(Collection<T> collection) {
047            this(collection, true);
048        }
049        
050        /** 
051         * Creates a new instance of AddToCollectionStage.
052         * @param collection The collection in which to add objects to
053         * @param synchronized A flag value that determines whether or not accesses
054         * to the underlying collection are synchronized.
055         */
056        public AddToCollectionStage(Collection<T> collection, boolean synchronize) {
057            if (collection == null){
058                throw new IllegalArgumentException("Argument 'collection' can not be null.");
059            }
060            
061            this.collection = synchronize ? Collections.synchronizedCollection(collection) : collection;
062        }
063        
064        /** 
065         * Adds the object to the underlying collection.
066         *
067         * @throws ClassCastException if the object is not of a suitable type to be added
068         * to the collection.
069         */
070        public void process(Object obj) throws org.apache.commons.pipeline.StageException {
071            this.collection.add((T) obj);
072            this.emit(obj);
073        }
074        
075        /**
076         * Returns the collection to which elements have been added during
077         * processing.
078         */
079        public Collection<T> getCollection() {
080            return this.collection;
081        }    
082    }