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 Subscription} represents a one-to-one lifecycle of a {@link Subscriber} subscribing to a {@link Publisher}.
016 * <p>
017 * It can only be used once by a single {@link Subscriber}.
018 * <p>
019 * It is used to both signal desire for data and cancel demand (and allow resource cleanup).
020 *
021 */
022public interface Subscription {
023    /**
024     * No events will be sent by a {@link Publisher} until demand is signaled via this method.
025     * <p>
026     * It can be called however often and whenever needed—but the outstanding cumulative demand must never exceed Long.MAX_VALUE.
027     * An outstanding cumulative demand of Long.MAX_VALUE may be treated by the {@link Publisher} as "effectively unbounded".
028     * <p>
029     * Whatever has been requested can be sent by the {@link Publisher} so only signal demand for what can be safely handled.
030     * <p>
031     * A {@link Publisher} can send less than is requested if the stream ends but
032     * then must emit either {@link Subscriber#onError(Throwable)} or {@link Subscriber#onComplete()}.
033     * 
034     * @param n the strictly positive number of elements to requests to the upstream {@link Publisher}
035     */
036    public void request(long n);
037
038    /**
039     * Request the {@link Publisher} to stop sending data and clean up resources.
040     * <p>
041     * Data may still be sent to meet previously signalled demand after calling cancel.
042     */
043    public void cancel();
044}