SingletonIterator.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.apache.commons.collections4.iterators;

  18. import java.util.NoSuchElementException;

  19. import org.apache.commons.collections4.ResettableIterator;

  20. /**
  21.  * {@code SingletonIterator} is an {@link java.util.Iterator} over a single
  22.  * object instance.
  23.  *
  24.  * @param <E> the type of elements returned by this iterator.
  25.  * @since 2.0
  26.  */
  27. public class SingletonIterator<E>
  28.         implements ResettableIterator<E> {

  29.     /** Whether remove is allowed */
  30.     private final boolean removeAllowed;
  31.     /** Is the cursor before the first element */
  32.     private boolean beforeFirst = true;
  33.     /** Has the element been removed */
  34.     private boolean removed;
  35.     /** The object */
  36.     private E object;

  37.     /**
  38.      * Constructs a new {@code SingletonIterator} where {@code remove}
  39.      * is a permitted operation.
  40.      *
  41.      * @param object  the single object to return from the iterator
  42.      */
  43.     public SingletonIterator(final E object) {
  44.         this(object, true);
  45.     }

  46.     /**
  47.      * Constructs a new {@code SingletonIterator} optionally choosing if
  48.      * {@code remove} is a permitted operation.
  49.      *
  50.      * @param object  the single object to return from the iterator
  51.      * @param removeAllowed  true if remove is allowed
  52.      * @since 3.1
  53.      */
  54.     public SingletonIterator(final E object, final boolean removeAllowed) {
  55.         this.object = object;
  56.         this.removeAllowed = removeAllowed;
  57.     }

  58.     /**
  59.      * Is another object available from the iterator?
  60.      * <p>
  61.      * This returns true if the single object hasn't been returned yet.
  62.      *
  63.      * @return true if the single object hasn't been returned yet
  64.      */
  65.     @Override
  66.     public boolean hasNext() {
  67.         return beforeFirst && !removed;
  68.     }

  69.     /**
  70.      * Gets the next object from the iterator.
  71.      * <p>
  72.      * This returns the single object if it hasn't been returned yet.
  73.      *
  74.      * @return the single object
  75.      * @throws NoSuchElementException if the single object has already
  76.      *    been returned
  77.      */
  78.     @Override
  79.     public E next() {
  80.         if (!beforeFirst || removed) {
  81.             throw new NoSuchElementException();
  82.         }
  83.         beforeFirst = false;
  84.         return object;
  85.     }

  86.     /**
  87.      * Remove the object from this iterator.
  88.      *
  89.      * @throws IllegalStateException if the {@code next} method has not
  90.      *        yet been called, or the {@code remove} method has already
  91.      *        been called after the last call to the {@code next}
  92.      *        method.
  93.      * @throws UnsupportedOperationException if remove is not supported
  94.      */
  95.     @Override
  96.     public void remove() {
  97.         if (!removeAllowed) {
  98.             throw new UnsupportedOperationException();
  99.         }
  100.         if (removed || beforeFirst) {
  101.             throw new IllegalStateException();
  102.         }
  103.         object = null;
  104.         removed = true;
  105.     }

  106.     /**
  107.      * Reset the iterator to the start.
  108.      */
  109.     @Override
  110.     public void reset() {
  111.         beforeFirst = true;
  112.     }

  113. }