001/***************************************************
002 * Licensed under MIT No Attribution (SPDX: MIT-0) *
003 ***************************************************/
004
005package org.reactivestreams;
006
007/**
008 * A {@link Subscription} represents a one-to-one lifecycle of a {@link Subscriber} subscribing to a {@link Publisher}.
009 * <p>
010 * It can only be used once by a single {@link Subscriber}.
011 * <p>
012 * It is used to both signal desire for data and cancel demand (and allow resource cleanup).
013 */
014public interface Subscription {
015
016    /**
017     * No events will be sent by a {@link Publisher} until demand is signaled via this method.
018     * <p>
019     *  It can be called however often and whenever needed—but if the outstanding cumulative demand ever becomes Long.MAX_VALUE or more,
020     *  it may be treated by the {@link Publisher} as "effectively unbounded".
021     * <p>
022     * Whatever has been requested can be sent by the {@link Publisher} so only signal demand for what can be safely handled.
023     * <p>
024     * A {@link Publisher} can send less than is requested if the stream ends but
025     * then must emit either {@link Subscriber#onError(Throwable)} or {@link Subscriber#onComplete()}.
026     * 
027     * @param n the strictly positive number of elements to requests to the upstream {@link Publisher}
028     */
029    public void request(long n);
030
031    /**
032     * Request the {@link Publisher} to stop sending data and clean up resources.
033     * <p>
034     * Data may still be sent to meet previously signalled demand after calling cancel.
035     */
036    public void cancel();
037}