PageRenderTime 11ms CodeModel.GetById 2ms app.highlight 6ms RepoModel.GetById 1ms app.codeStats 0ms

/src/com/google/appengine/datanucleus/query/AbstractIterator.java

http://datanucleus-appengine.googlecode.com/
Java | 153 lines | 50 code | 13 blank | 90 comment | 6 complexity | 3945570889f78cbd7e64489073e2096e MD5 | raw file
  1/*
  2 * Copyright (C) 2007 Google Inc.
  3 *
  4 * Licensed under the Apache License, Version 2.0 (the "License");
  5 * you may not use this file except in compliance with the License.
  6 * You may obtain a copy of the License at
  7 *
  8 * http://www.apache.org/licenses/LICENSE-2.0
  9 *
 10 * Unless required by applicable law or agreed to in writing, software
 11 * distributed under the License is distributed on an "AS IS" BASIS,
 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 13 * See the License for the specific language governing permissions and
 14 * limitations under the License.
 15 */
 16package com.google.appengine.datanucleus.query;
 17
 18import java.util.Iterator;
 19import java.util.NoSuchElementException;
 20
 21/**
 22 * This class provides a skeletal implementation of the {@code Iterator}
 23 * interface, to make this interface easier to implement for certain types of
 24 * data sources.
 25 *
 26 * <p>{@code Iterator} requires its implementations to support querying the
 27 * end-of-data status without changing the iterator's state, using the {@link
 28 * #hasNext} method. But many data sources, such as {@link
 29 * java.io.Reader#read()}), do not expose this information; the only way to
 30 * discover whether there is any data left is by trying to retrieve it. These
 31 * types of data sources are ordinarily difficult to write iterators for. But
 32 * using this class, one must implement only the {@link #computeNext} method,
 33 * and invoke the {@link #endOfData} method when appropriate.
 34 *
 35 * <p>Another example is an iterator that skips over null elements in a backing
 36 * iterator. This could be implemented as: <pre>   {@code
 37 *
 38 *   public static Iterator<String> skipNulls(final Iterator<String> in) {
 39 *     return new AbstractIterator<String>() {
 40 *       protected String computeNext() {
 41 *         while (in.hasNext()) {
 42 *           String s = in.next();
 43 *           if (s != null) {
 44 *             return s;
 45 *           }
 46 *         }
 47 *         return endOfData();
 48 *       }
 49 *     };
 50 *   }}</pre>
 51 *
 52 * This class supports iterators that include null elements. The {@link
 53 * #remove()} method throws an {@link UnsupportedOperationException}, but
 54 * this can be overridden to support removal.
 55 *
 56 * @author Kevin Bourrillion
 57 */
 58abstract class AbstractIterator<T> implements Iterator<T> {
 59  private State state = State.NOT_READY;
 60
 61  private enum State {
 62    /** We have computed the next element and haven't returned it yet. */
 63    READY,
 64
 65    /** We haven't yet computed or have already returned the element. */
 66    NOT_READY,
 67
 68    /** We have reached the end of the data and are finished. */
 69    DONE,
 70
 71    /** We've suffered an exception and are kaput. */
 72    FAILED,
 73  }
 74
 75  private T next;
 76
 77  /**
 78   * Returns the next element. <b>Note:</b> the implementation must call {@link
 79   * #endOfData} when there are no elements left in the iteration. Failure to do
 80   * so could result in an infinite loop.
 81   *
 82   * <p>The initial invocation of {@link #hasNext()} or {@link #next()} calls
 83   * this method, as does the first invocation of {@code hasNext} or
 84   * {@code next} following each successful call to {@code next}. Once the
 85   * implementation either invokes {@code endOfData} or throws an exception,
 86   * {@code computeNext} is guaranteed to never be called again.
 87   *
 88   * <p>If this method throws an exception, it will propagate outward to the
 89   * {@code hasNext()} or {@code next()} invocation that invoked this method.
 90   * Any further attempts to use the iterator will result in an {@link
 91   * IllegalStateException}.
 92   *
 93   * @return the next element if there was one. If {@code endOfData} was called
 94   *     during execution, the return value will be ignored.
 95   * @throws RuntimeException if any unrecoverable error happens. This exception
 96   *     will propagate outward to the {@code hasNext()}, {@code next()}, or
 97   *     {@code peek()} invocation that invoked this method. Any further
 98   *     attempts to use the iterator will result in an
 99   *     {@link IllegalStateException}.
100   */
101  protected abstract T computeNext();
102
103  /**
104   * Implementations of {@code computeNext} <b>must</b> invoke this method when
105   * there are no elements left in the iteration.
106   *
107   * @return {@code null}; a convenience so your {@link #computeNext}
108   *     implementation can use the simple statement {@code return endOfData();}
109   */
110  protected final T endOfData() {
111    state = State.DONE;
112    return null;
113  }
114
115  public boolean hasNext() {
116    if (state == State.FAILED) {
117      throw new IllegalStateException();
118    }
119    switch (state) {
120      case DONE:
121        return false;
122      case READY:
123        return true;
124      default:
125    }
126    return tryToComputeNext();
127  }
128
129  private boolean tryToComputeNext() {
130    state = State.FAILED; // temporary pessimism
131    next = computeNext();
132    if (state != State.DONE) {
133      state = State.READY;
134      return true;
135    }
136    return false;
137  }
138
139  public T next() {
140    if (!hasNext()) {
141      throw new NoSuchElementException();
142    }
143    state = State.NOT_READY;
144    return next;
145  }
146
147  /**
148   * This method is not supported.
149   */
150  public void remove() {
151    throw new UnsupportedOperationException();
152  }
153}