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.iterators;
018    
019    import java.util.Collection;
020    import java.util.Enumeration;
021    import java.util.Iterator;
022    
023    /** 
024     * Adapter to make {@link Enumeration Enumeration} instances appear
025     * to be {@link Iterator Iterator} instances.
026     *
027     * @since Commons Collections 1.0
028     * @version $Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
029     * 
030     * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
031     * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
032     */
033    public class EnumerationIterator implements Iterator {
034        
035        /** The collection to remove elements from */
036        private Collection collection;
037        /** The enumeration being converted */
038        private Enumeration enumeration;
039        /** The last object retrieved */
040        private Object last;
041        
042        // Constructors
043        //-----------------------------------------------------------------------
044        /**
045         * Constructs a new <code>EnumerationIterator</code> that will not
046         * function until {@link #setEnumeration(Enumeration)} is called.
047         */
048        public EnumerationIterator() {
049            this(null, null);
050        }
051    
052        /**
053         * Constructs a new <code>EnumerationIterator</code> that provides
054         * an iterator view of the given enumeration.
055         *
056         * @param enumeration  the enumeration to use
057         */
058        public EnumerationIterator(final Enumeration enumeration) {
059            this(enumeration, null);
060        }
061    
062        /**
063         * Constructs a new <code>EnumerationIterator</code> that will remove
064         * elements from the specified collection.
065         *
066         * @param enumeration  the enumeration to use
067         * @param collection  the collection to remove elements form
068         */
069        public EnumerationIterator(final Enumeration enumeration, final Collection collection) {
070            super();
071            this.enumeration = enumeration;
072            this.collection = collection;
073            this.last = null;
074        }
075    
076        // Iterator interface
077        //-----------------------------------------------------------------------
078        /**
079         * Returns true if the underlying enumeration has more elements.
080         *
081         * @return true if the underlying enumeration has more elements
082         * @throws NullPointerException  if the underlying enumeration is null
083         */
084        public boolean hasNext() {
085            return enumeration.hasMoreElements();
086        }
087    
088        /**
089         * Returns the next object from the enumeration.
090         *
091         * @return the next object from the enumeration
092         * @throws NullPointerException if the enumeration is null
093         */
094        public Object next() {
095            last = enumeration.nextElement();
096            return last;
097        }
098    
099        /**
100         * Removes the last retrieved element if a collection is attached.
101         * <p>
102         * Functions if an associated <code>Collection</code> is known.
103         * If so, the first occurrence of the last returned object from this
104         * iterator will be removed from the collection.
105         *
106         * @exception IllegalStateException <code>next()</code> not called.
107         * @exception UnsupportedOperationException if no associated collection
108         */
109        public void remove() {
110            if (collection != null) {
111                if (last != null) {
112                    collection.remove(last);
113                } else {
114                    throw new IllegalStateException("next() must have been called for remove() to function");
115                }
116            } else {
117                throw new UnsupportedOperationException("No Collection associated with this Iterator");
118            }
119        }
120    
121        // Properties
122        //-----------------------------------------------------------------------
123        /**
124         * Returns the underlying enumeration.
125         *
126         * @return the underlying enumeration
127         */
128        public Enumeration getEnumeration() {
129            return enumeration;
130        }
131    
132        /**
133         * Sets the underlying enumeration.
134         *
135         * @param enumeration  the new underlying enumeration
136         */
137        public void setEnumeration(final Enumeration enumeration) {
138            this.enumeration = enumeration;
139        }
140        
141    }