001/**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.hadoop.mapreduce.lib.join;
019
020import java.io.IOException;
021
022import org.apache.hadoop.classification.InterfaceAudience;
023import org.apache.hadoop.classification.InterfaceStability;
024import org.apache.hadoop.io.Writable;
025
026/**
027 * This defines an interface to a stateful Iterator that can replay elements
028 * added to it directly.
029 * Note that this does not extend {@link java.util.Iterator}.
030 */
031@InterfaceAudience.Public
032@InterfaceStability.Stable
033public interface ResetableIterator<T extends Writable> {
034
035  public static class EMPTY<U extends Writable>
036    implements ResetableIterator<U> {
037    public boolean hasNext() { return false; }
038    public void reset() { }
039    public void close() throws IOException { }
040    public void clear() { }
041    public boolean next(U val) throws IOException {
042      return false;
043    }
044    public boolean replay(U val) throws IOException {
045      return false;
046    }
047    public void add(U item) throws IOException {
048      throw new UnsupportedOperationException();
049    }
050  }
051
052  /**
053   * True if a call to next may return a value. This is permitted false
054   * positives, but not false negatives.
055   */
056  public boolean hasNext();
057
058  /**
059   * Assign next value to actual.
060   * It is required that elements added to a ResetableIterator be returned in
061   * the same order after a call to {@link #reset} (FIFO).
062   *
063   * Note that a call to this may fail for nested joins (i.e. more elements
064   * available, but none satisfying the constraints of the join)
065   */
066  public boolean next(T val) throws IOException;
067
068  /**
069   * Assign last value returned to actual.
070   */
071  public boolean replay(T val) throws IOException;
072
073  /**
074   * Set iterator to return to the start of its range. Must be called after
075   * calling {@link #add} to avoid a ConcurrentModificationException.
076   */
077  public void reset();
078
079  /**
080   * Add an element to the collection of elements to iterate over.
081   */
082  public void add(T item) throws IOException;
083
084  /**
085   * Close datasources and release resources. Calling methods on the iterator
086   * after calling close has undefined behavior.
087   */
088  // XXX is this necessary?
089  public void close() throws IOException;
090
091  /**
092   * Close datasources, but do not release internal resources. Calling this
093   * method should permit the object to be reused with a different datasource.
094   */
095  public void clear();
096
097}