1   package eu.fbk.knowledgestore.data;
2   
3   import java.util.Iterator;
4   
5   import javax.annotation.Nullable;
6   
7   /**
8    * A handler accepting a sequence of elements, one at a time.
9    * <p>
10   * Implementations of this interface are accepted by methods that performs an internal, push-style
11   * iteration by forwarding a sequence of elements, one at a time, to a supplied Handler; to this
12   * respect, this interface complements the {@link Iterator} which supports an external, pull-style
13   * iteration.
14   * </p>
15   * <p>
16   * A Handler implements a single method {@link #handle(Object)} that is called for each object of
17   * the sequence, which MUST not be null; at the end of the sequence, the method is called a last
18   * time passing null as sentinel value. This interface does not specify how to interrupt the
19   * iteration and how to deal with exceptions, which depend on (and are documented as part of) the
20   * specific method accepting a Handler. In particular:
21   * </p>
22   * <ul>
23   * <li>interruption of iteration MAY be implemented using the standard mechanism of thread
24   * interruption (see {@link Thread#interrupt()}), which may be triggered inside the
25   * {@code handle()} method and will cause, eventually, the end of the iteration;</li>
26   * <li>exceptions thrown by the Handler MAY cause the iteration to stop immediately, without the
27   * end of sequence being propagated.</li>
28   * </ul>
29   * <p>
30   * Implementations of this interface are not expected to be thread safe. It is a responsibility of
31   * the caller of {@link #handle(Object)} to never invoke this method multiple times concurrently.
32   * </p>
33   * 
34   * @param <T>
35   *            the type of element
36   */
37  public interface Handler<T> {
38  
39      /**
40       * Callback method called for each non-null element of the sequence, and with a null value at
41       * the end of the sequence.
42       * 
43       * @param element
44       *            the element
45       * @throws Throwable
46       *             on failure
47       */
48      void handle(@Nullable T element) throws Throwable;
49  
50  }