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 }