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 * A {@link Publisher} is a provider of a potentially unbounded number of sequenced elements, publishing them according to
016 * the demand received from its {@link Subscriber}(s).
017 * <p>
018 * A {@link Publisher} can serve multiple {@link Subscriber}s subscribed {@link #subscribe(Subscriber)} dynamically
019 * at various points in time.
020 *
021 * @param <T> the type of element signaled.
022 */
023public interface Publisher<T> {
024
025    /**
026     * Request {@link Publisher} to start streaming data.
027     * <p>
028     * This is a "factory method" and can be called multiple times, each time starting a new {@link Subscription}.
029     * <p>
030     * Each {@link Subscription} will work for only a single {@link Subscriber}.
031     * <p>
032     * A {@link Subscriber} should only subscribe once to a single {@link Publisher}.
033     * <p>
034     * If the {@link Publisher} rejects the subscription attempt or otherwise fails it will
035     * signal the error via {@link Subscriber#onError}.
036     *
037     * @param s the {@link Subscriber} that will consume signals from this {@link Publisher}
038     */
039    public void subscribe(Subscriber<? super T> s);
040}