001package org.reactivestreams;
002
003/**
004 * Will receive call to {@link #onSubscribe(Subscription)} once after passing an instance of {@link Subscriber} to {@link Publisher#subscribe(Subscriber)}.
005 * <p>
006 * No further notifications will be received until {@link Subscription#request(long)} is called.
007 * <p>
008 * After signaling demand:
009 * <ul>
010 * <li>One or more invocations of {@link #onNext(Object)} up to the maximum number defined by {@link Subscription#request(long)}</li>
011 * <li>Single invocation of {@link #onError(Throwable)} or {@link Subscriber#onComplete()} which signals a terminal state after which no further events will be sent.
012 * </ul>
013 * <p>
014 * Demand can be signaled via {@link Subscription#request(long)} whenever the {@link Subscriber} instance is capable of handling more.
015 *
016 * @param <T> the type of element signaled.
017 */
018public interface Subscriber<T> {
019    /**
020     * Invoked after calling {@link Publisher#subscribe(Subscriber)}.
021     * <p>
022     * No data will start flowing until {@link Subscription#request(long)} is invoked.
023     * <p>
024     * It is the responsibility of this {@link Subscriber} instance to call {@link Subscription#request(long)} whenever more data is wanted.
025     * <p>
026     * The {@link Publisher} will send notifications only in response to {@link Subscription#request(long)}.
027     * 
028     * @param s
029     *            {@link Subscription} that allows requesting data via {@link Subscription#request(long)}
030     */
031    public void onSubscribe(Subscription s);
032
033    /**
034     * Data notification sent by the {@link Publisher} in response to requests to {@link Subscription#request(long)}.
035     * 
036     * @param t the element signaled
037     */
038    public void onNext(T t);
039
040    /**
041     * Failed terminal state.
042     * <p>
043     * No further events will be sent even if {@link Subscription#request(long)} is invoked again.
044     *
045     * @param t the throwable signaled
046     */
047    public void onError(Throwable t);
048
049    /**
050     * Successful terminal state.
051     * <p>
052     * No further events will be sent even if {@link Subscription#request(long)} is invoked again.
053     */
054    public void onComplete();
055}