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