001/************************************************************************
002 * Licensed under Public Domain (CC0)                                    *
003 *                                                                       *
004 * To the extent possible under law, the person who associated CC0 with  *
005 * this code has waived all copyright and related or neighboring         *
006 * rights to this code.                                                  *
007 *                                                                       *
008 * You should have received a copy of the CC0 legalcode along with this  *
009 * work. If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.*
010 ************************************************************************/
011
012package org.reactivestreams;
013
014/**
015 * Will receive call to {@link #onSubscribe(Subscription)} once after passing an instance of {@link Subscriber} to {@link Publisher#subscribe(Subscriber)}.
016 * <p>
017 * No further notifications will be received until {@link Subscription#request(long)} is called.
018 * <p>
019 * After signaling demand:
020 * <ul>
021 * <li>One or more invocations of {@link #onNext(Object)} up to the maximum number defined by {@link Subscription#request(long)}</li>
022 * <li>Single invocation of {@link #onError(Throwable)} or {@link Subscriber#onComplete()} which signals a terminal state after which no further events will be sent.
023 * </ul>
024 * <p>
025 * Demand can be signaled via {@link Subscription#request(long)} whenever the {@link Subscriber} instance is capable of handling more.
026 *
027 * @param <T> the type of element signaled.
028 */
029public interface Subscriber<T> {
030    /**
031     * Invoked after calling {@link Publisher#subscribe(Subscriber)}.
032     * <p>
033     * No data will start flowing until {@link Subscription#request(long)} is invoked.
034     * <p>
035     * It is the responsibility of this {@link Subscriber} instance to call {@link Subscription#request(long)} whenever more data is wanted.
036     * <p>
037     * The {@link Publisher} will send notifications only in response to {@link Subscription#request(long)}.
038     * 
039     * @param s
040     *            {@link Subscription} that allows requesting data via {@link Subscription#request(long)}
041     */
042    public void onSubscribe(Subscription s);
043
044    /**
045     * Data notification sent by the {@link Publisher} in response to requests to {@link Subscription#request(long)}.
046     * 
047     * @param t the element signaled
048     */
049    public void onNext(T t);
050
051    /**
052     * Failed terminal state.
053     * <p>
054     * No further events will be sent even if {@link Subscription#request(long)} is invoked again.
055     *
056     * @param t the throwable signaled
057     */
058    public void onError(Throwable t);
059
060    /**
061     * Successful terminal state.
062     * <p>
063     * No further events will be sent even if {@link Subscription#request(long)} is invoked again.
064     */
065    public void onComplete();
066}