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     */
018    package org.apache.hadoop.mapreduce.lib.join;
019    
020    import java.io.IOException;
021    
022    import org.apache.hadoop.classification.InterfaceAudience;
023    import org.apache.hadoop.classification.InterfaceStability;
024    import 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
033    public 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    }