package org.webslinger.collections;

 import java.util.Iterator;

 import java.util.NoSuchElementException;

 /** 

  * <p>A class that makes writing {@link java.util.Iterator Iterators}

  * easier.

  * <p>This class handles the interation logic of {@link #hasNext()

  * hasNext()} and {@link #next() next()}, and calls single methods to

  * actually get at the data.

  *

  * @author <a href="mailto:doogie@brainfood.com">Adam Heath</a>

  */

 public abstract class BaseIterator<T> implements Iterator<T> {

     private boolean iterate = true;

     private boolean beenRemoved = false;

     private boolean hasNextObject = false;

     private T item;

     /**

      * <p>Returns the next element in the interation.

      *

      * @return the next element in the iteration.

      * @throws <code>NoSuchElementException</code> - iteration has no

      * more elements.

      */

     public T next() {

         if (!hasNext()) throw new NoSuchElementException("No such element");

         iterate = true;

         return item;

     }

     /**

      * <p>Returns true if the iteration has more elements.  (In other

      * words, returns true if next would return an element rather than

      * throwing an exception.)

      *

      * @return <code>true</code> if the iterator has more elements.

      */

     public boolean hasNext() {

         if (!iterate) return hasNextObject;

         iterate = false;

         beenRemoved = false;

         hasNextObject = getNext();

         return hasNextObject;

     }

     /**

      * <p>This is called to fetch next object.

      *

      * @return true if a new object was fetched.

      */

     protected abstract boolean getNext();

     /**

      * <p>A convenience method that allows sub-classes to see the current

      * item value.

      *

      * @return The current item.

      */

     protected T getItem() {

         return item;

     }

     /**

      * <p>This is called from {@link #getNext() getNext()} to set the

      * object to be returned by {@link #next() next()}.

      *

      * @param item The object to be returned by {@link #next() next()}.

      */

     protected void setItem(T item) {

         this.item = item;

     }

     /**

      * <p>This is called from {@link #remove() remove()} to remove the

      * current object from the {@link java.util.Collection Collection}

      * that this iterator is being backed by.

      */

     protected abstract void removeItem();

     /**

      * <p>Removes from the underlying collection the last element

      * returned by the iterator(optional operation).  This method can be

      * called only once per call to next.  The behavior of an iterator

      * is unspecified if the underlying collection is modified while the

      * iteration is in progress in any way other than by calling this

      * method.

      *

      * @throws <code>UnsupportedOperationException</code> - if the remove

      * operation is not supported by this Iterator.

      * @throws <code>IllegalStateException</code> - if the next method

      * has not yet been called, or the remove method has already been

      * called after the last call to the next method.

      */

     public void remove() {

         if (beenRemoved) throw new IllegalStateException("item has already been removed");

         beenRemoved = true;

         removeItem();

     }

 }