/*
 * Copyright 1999-2004 The Apache Software Foundation
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.collections.iterators;

import java.util.Collection;
import java.util.Enumeration;
import java.util.Iterator;

/** Adapter to make {@link Enumeration Enumeration} instances appear
  * to be {@link Iterator Iterator} instances.
  *
  * @since 1.0
  * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
  * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
  */
public class EnumerationIterator implements Iterator {
    
    private Collection collection;

    private Enumeration enumeration;

    private Object last;
    
    /**
     *  Constructs a new <Code>EnumerationIterator</Code> that will not
     *  function until {@link #setEnumeration(Enumeration)} is called.
     */
    public EnumerationIterator() {
        this(null, null);
    }

    /**
     *  Constructs a new <Code>EnumerationIterator</Code> that provides
     *  an iterator view of the given enumeration.
     *
     *  @param enumeration  the enumeration to use
     */
    public EnumerationIterator( Enumeration enumeration ) {
        this(enumeration, null);
    }

    /**
     *  Constructs a new <Code>EnumerationIterator</Code> that will remove
     *  elements from the specified collection.
     *
     *  @param enumeration  the enumeration to use
     *  @param collection  the collection to remove elements from
     */
    public EnumerationIterator( Enumeration enumeration, Collection collection ) {
        this.enumeration = enumeration;
        this.collection = collection;
        this.last = null;
    }

    // Iterator interface
    //-------------------------------------------------------------------------

    /**
     *  Returns true if the underlying enumeration has more elements.
     *
     *  @return true if the underlying enumeration has more elements
     *  @throws NullPointerException  if the underlying enumeration is null
     */
    public boolean hasNext() {
        return enumeration.hasMoreElements();
    }

    /**
     *  Returns the next object from the enumeration.
     *
     *  @return the next object from the enumeration
     *  @throws NullPointerException if the enumeration is null
     */
    public Object next() {
        last = enumeration.nextElement();
        return last;
    }

    /**
     * Functions if an associated <code>Collection</code> is known.
     * If so, the first occurrence of the last returned object from this
     * iterator will be removed from the collection.
     *
     * @exception IllegalStateException <code>next()</code> not called.
     * @exception UnsupportedOperationException No associated
     * <code>Collection</code>.
     */
    public void remove() {
        if (collection != null) {
            if (last != null) {
                collection.remove(last);
            }
            else {
                throw new IllegalStateException
                    ("next() must have been called for remove() to function");
            }
        }
        else {
            throw new UnsupportedOperationException
                ("No Collection associated with this Iterator");
        }
    }

    // Properties
    //-------------------------------------------------------------------------

    /**
     *  Returns the underlying enumeration.
     *
     *  @return the underlying enumeration
     */
    public Enumeration getEnumeration() {
        return enumeration;
    }

    /**
     *  Sets the underlying enumeration.
     *
     *  @param enumeration  the new underlying enumeration
     */
    public void setEnumeration( Enumeration enumeration ) {
        this.enumeration = enumeration;
    }
}
