com.linecorp.armeria.common.stream

Interface StreamMessage<T>

Type Parameters:

T - the type of element signaled

All Superinterfaces:

org.reactivestreams.Publisher<T>

All Known Subinterfaces:

HttpRequest, HttpRequestWriter, HttpResponse, HttpResponseWriter

All Known Implementing Classes:

DefaultHttpRequest, DefaultHttpResponse, DefaultStreamMessage, DeferredHttpResponse, DeferredStreamMessage, EmptyFixedStreamMessage, FilteredHttpResponse, FilteredStreamMessage, OneElementFixedStreamMessage, PublisherBasedStreamMessage, RegularFixedStreamMessage, StreamMessageWrapper, TwoElementFixedStreamMessage

public interface StreamMessage<T>
extends org.reactivestreams.Publisher<T>

A variant of Reactive Streams Publisher, which allows only one Subscriber. Unlike a usual Publisher, a StreamMessage can stream itself only once. It has the following additional operations on top of what the Reactive Streams API provides:

• isOpen()
• isEmpty()
• completionFuture()
• abort()

When is a StreamMessage fully consumed?

A StreamMessage is complete (or 'fully consumed') when:

• the Subscriber consumes all elements and Subscriber.onComplete() is invoked,
• an error occurred and Subscriber.onError(Throwable) is invoked,
• the Subscription has been cancelled or
• abort() has been requested.

When fully consumed, the CompletableFuture returned by completionFuture() will complete, which you may find useful because Subscriber does not notify you when a stream is cancelled.

Publication and Consumption of ReferenceCounted objects

StreamMessage will reject the publication request of a ReferenceCounted object except ByteBuf and ByteBufHolder.

StreamMessage will discard the publication request of a ByteBuf or a ByteBufHolder silently and release it automatically when the publication is attempted after the stream is closed.

For ByteBuf and ByteBufHolder, StreamMessage will convert them into their respective unpooled versions that never leak, so that the Subscriber does not need to worry about leaks.

If a Subscriber does not want a StreamMessage to make a copy of a ByteBufHolder, specify SubscriptionOption.WITH_POOLED_OBJECTS when you subscribe. Note that the Subscriber is responsible for releasing the objects given with Subscriber.onNext(Object).

Subscriber.onError(Throwable) is invoked when any exception is raised except the CancelledSubscriptionException which is caused by Subscription.cancel(). If you want your Subscriber get notified by Subscriber.onError(Throwable) when Subscription.cancel() is called, specify SubscriptionOption.NOTIFY_CANCELLATION when you subscribe.

Method Summary

Modifier and Type	Method and Description
void	abort() Closes this stream with AbortedStreamException and prevents further subscription.
void	abort(Throwable cause) Closes this stream with the specified Throwable and prevents further subscription.
default CompletableFuture<Void>	closeFuture() Deprecated. Use completionFuture() instead.
CompletableFuture<Void>	completionFuture() Returns a CompletableFuture that completes when this stream is complete, either successfully or exceptionally, including cancellation and abortion.
CompletableFuture<List<T>>	drainAll() Subscribes to this StreamMessage and retrieves all elements from it.
CompletableFuture<List<T>>	drainAll(boolean withPooledObjects) Deprecated. Use drainAll(SubscriptionOption...).
CompletableFuture<List<T>>	drainAll(io.netty.util.concurrent.EventExecutor executor) Subscribes to this StreamMessage and retrieves all elements from it.
CompletableFuture<List<T>>	drainAll(io.netty.util.concurrent.EventExecutor executor, boolean withPooledObjects) Deprecated. Use drainAll(EventExecutor, SubscriptionOption...).
CompletableFuture<List<T>>	drainAll(io.netty.util.concurrent.EventExecutor executor, SubscriptionOption... options) Subscribes to this StreamMessage and retrieves all elements from it.
CompletableFuture<List<T>>	drainAll(SubscriptionOption... options) Subscribes to this StreamMessage and retrieves all elements from it.
default boolean	isComplete() Returns true if this stream is complete, either successfully or exceptionally, including cancellation and abortion.
boolean	isEmpty() Returns true if this stream has been closed and did not publish any elements.
boolean	isOpen() Returns true if this stream is not closed yet.
static <T> StreamMessage<T>	of() Creates a new StreamMessage that will publish no objects, just a close event.
static <T> StreamMessage<T>	of(T... objs) Creates a new StreamMessage that will publish the given objs.
static <T> StreamMessage<T>	of(T obj) Creates a new StreamMessage that will publish the single obj.
static <T> StreamMessage<T>	of(T obj1, T obj2) Creates a new StreamMessage that will publish the two obj1 and obj2.
void	subscribe(org.reactivestreams.Subscriber<? super T> subscriber) Requests to start streaming data to the specified Subscriber.
void	subscribe(org.reactivestreams.Subscriber<? super T> subscriber, boolean withPooledObjects) Deprecated. Use subscribe(Subscriber, SubscriptionOption...).
void	subscribe(org.reactivestreams.Subscriber<? super T> subscriber, io.netty.util.concurrent.EventExecutor executor) Requests to start streaming data to the specified Subscriber.
void	subscribe(org.reactivestreams.Subscriber<? super T> subscriber, io.netty.util.concurrent.EventExecutor executor, boolean withPooledObjects) Deprecated. Use subscribe(Subscriber, EventExecutor, SubscriptionOption...).
void	subscribe(org.reactivestreams.Subscriber<? super T> subscriber, io.netty.util.concurrent.EventExecutor executor, SubscriptionOption... options) Requests to start streaming data to the specified Subscriber.
void	subscribe(org.reactivestreams.Subscriber<? super T> subscriber, SubscriptionOption... options) Requests to start streaming data to the specified Subscriber.

Method Detail

of

static <T> StreamMessage<T> of()

Creates a new StreamMessage that will publish no objects, just a close event.

of

static <T> StreamMessage<T> of(T obj)

Creates a new StreamMessage that will publish the single obj.

of

static <T> StreamMessage<T> of(T obj1,
                               T obj2)

Creates a new StreamMessage that will publish the two obj1 and obj2.

of

@SafeVarargs
static <T> StreamMessage<T> of(T... objs)

Creates a new StreamMessage that will publish the given objs.

isOpen

boolean isOpen()

Returns true if this stream is not closed yet. Note that a stream may not be complete even if it's closed; a stream is complete when it's fully consumed by a Subscriber.

isEmpty

boolean isEmpty()

Returns true if this stream has been closed and did not publish any elements. Note that this method will not return true when the stream is open even if it has not published anything so far, because it may publish something later.

isComplete

default boolean isComplete()

Returns true if this stream is complete, either successfully or exceptionally, including cancellation and abortion.

A StreamMessage is complete (or 'fully consumed') when:

• the Subscriber consumes all elements and Subscriber.onComplete() is invoked,
• an error occurred and Subscriber.onError(Throwable) is invoked,
• the Subscription has been cancelled or
• abort() has been requested.

completionFuture

CompletableFuture<Void> completionFuture()

Returns a CompletableFuture that completes when this stream is complete, either successfully or exceptionally, including cancellation and abortion.

A StreamMessage is complete (or 'fully consumed') when:

• the Subscriber consumes all elements and Subscriber.onComplete() is invoked,
• an error occurred and Subscriber.onError(Throwable) is invoked,
• the Subscription has been cancelled or
• abort() has been requested.

closeFuture

@Deprecated
default CompletableFuture<Void> closeFuture()

Deprecated. Use completionFuture() instead.

Returns a CompletableFuture that completes when this stream is complete, either successfully or exceptionally, including cancellation and abortion.

subscribe

void subscribe(org.reactivestreams.Subscriber<? super T> subscriber)

Requests to start streaming data to the specified Subscriber. If there is a problem subscribing, Subscriber.onError(Throwable) will be invoked with one of the following exceptions:

• IllegalStateException if other Subscriber subscribed to this stream already.
• AbortedStreamException if this stream has been aborted.
• CancelledSubscriptionException if this stream has been cancelled and SubscriptionOption.NOTIFY_CANCELLATION is specified when subscribed.
• Other exceptions that occurred due to an error while retrieving the elements.

Specified by:

subscribe in interface org.reactivestreams.Publisher<T>

subscribe

void subscribe(org.reactivestreams.Subscriber<? super T> subscriber,
               SubscriptionOption... options)

Requests to start streaming data to the specified Subscriber. If there is a problem subscribing, Subscriber.onError(Throwable) will be invoked with one of the following exceptions:

• IllegalStateException if other Subscriber subscribed to this stream already.
• AbortedStreamException if this stream has been aborted.
• CancelledSubscriptionException if this stream has been cancelled and SubscriptionOption.NOTIFY_CANCELLATION is specified when subscribed.
• Other exceptions that occurred due to an error while retrieving the elements.

Parameters:

options - SubscriptionOptions to subscribe with

subscribe

void subscribe(org.reactivestreams.Subscriber<? super T> subscriber,
               io.netty.util.concurrent.EventExecutor executor)

Requests to start streaming data to the specified Subscriber. If there is a problem subscribing, Subscriber.onError(Throwable) will be invoked with one of the following exceptions:

• IllegalStateException if other Subscriber subscribed to this stream already.
• AbortedStreamException if this stream has been aborted.
• CancelledSubscriptionException if this stream has been cancelled and SubscriptionOption.NOTIFY_CANCELLATION is specified when subscribed.
• Other exceptions that occurred due to an error while retrieving the elements.

Parameters:

executor - the executor to subscribe

subscribe

void subscribe(org.reactivestreams.Subscriber<? super T> subscriber,
               io.netty.util.concurrent.EventExecutor executor,
               SubscriptionOption... options)

Requests to start streaming data to the specified Subscriber. If there is a problem subscribing, Subscriber.onError(Throwable) will be invoked with one of the following exceptions:

• IllegalStateException if other Subscriber subscribed to this stream already.
• AbortedStreamException if this stream has been aborted.
• CancelledSubscriptionException if this stream has been cancelled and SubscriptionOption.NOTIFY_CANCELLATION is specified when subscribed.
• Other exceptions that occurred due to an error while retrieving the elements.

Parameters:

executor - the executor to subscribe

options - SubscriptionOptions to subscribe with

subscribe

@Deprecated
void subscribe(org.reactivestreams.Subscriber<? super T> subscriber,
                           boolean withPooledObjects)

Deprecated. Use subscribe(Subscriber, SubscriptionOption...).

Requests to start streaming data to the specified Subscriber. If there is a problem subscribing, Subscriber.onError(Throwable) will be invoked with one of the following exceptions:

• IllegalStateException if other Subscriber subscribed to this stream already.
• AbortedStreamException if this stream has been aborted.
• CancelledSubscriptionException if this stream has been cancelled and SubscriptionOption.NOTIFY_CANCELLATION is specified when subscribed.
• Other exceptions that occurred due to an error while retrieving the elements.

subscribe

@Deprecated
void subscribe(org.reactivestreams.Subscriber<? super T> subscriber,
                           io.netty.util.concurrent.EventExecutor executor,
                           boolean withPooledObjects)

Deprecated. Use subscribe(Subscriber, EventExecutor, SubscriptionOption...).

Requests to start streaming data, invoking the specified Subscriber from the specified Executor. If there is a problem subscribing, Subscriber.onError(Throwable) will be invoked with one of the following exceptions:

• IllegalStateException if other Subscriber subscribed to this stream already.
• AbortedStreamException if this stream has been aborted.
• CancelledSubscriptionException if this stream has been cancelled and SubscriptionOption.NOTIFY_CANCELLATION is specified when subscribed.
• Other exceptions that occurred due to an error while retrieving the elements.

Parameters:

executor - the executor to subscribe

drainAll

CompletableFuture<List<T>> drainAll()

Subscribes to this StreamMessage and retrieves all elements from it. The returned CompletableFuture may be completed exceptionally with the following exceptions:

• IllegalStateException if other Subscriber subscribed to this stream already.
• AbortedStreamException if this stream has been aborted.
• Other exceptions that occurred due to an error while retrieving the elements.

Returns:

the CompletableFuture which will be completed with the list of the elements retrieved.

drainAll

@Deprecated
CompletableFuture<List<T>> drainAll(boolean withPooledObjects)

Deprecated. Use drainAll(SubscriptionOption...).

Subscribes to this StreamMessage and retrieves all elements from it. The returned CompletableFuture may be completed exceptionally with the following exceptions:

• IllegalStateException if other Subscriber subscribed to this stream already.
• AbortedStreamException if this stream has been aborted.
• Other exceptions that occurred due to an error while retrieving the elements.

Returns:

the CompletableFuture which will be completed with the list of the elements retrieved.

drainAll

@Deprecated
CompletableFuture<List<T>> drainAll(io.netty.util.concurrent.EventExecutor executor,
                                                boolean withPooledObjects)

Deprecated. Use drainAll(EventExecutor, SubscriptionOption...).

Subscribes to this StreamMessage and retrieves all elements from it. The returned CompletableFuture may be completed exceptionally with the following exceptions:

• IllegalStateException if other Subscriber subscribed to this stream already.
• AbortedStreamException if this stream has been aborted.
• Other exceptions that occurred due to an error while retrieving the elements.

Parameters:

executor - the executor to retrieve all elements

Returns:

the CompletableFuture which will be completed with the list of the elements retrieved.

drainAll

CompletableFuture<List<T>> drainAll(SubscriptionOption... options)

Subscribes to this StreamMessage and retrieves all elements from it. The returned CompletableFuture may be completed exceptionally with the following exceptions:

• IllegalStateException if other Subscriber subscribed to this stream already.
• AbortedStreamException if this stream has been aborted.
• Other exceptions that occurred due to an error while retrieving the elements.

Parameters:

options - SubscriptionOptions to subscribe with. Note that SubscriptionOption.NOTIFY_CANCELLATION is ineffective because there's no cancelling while draining all elements.

Returns:

the CompletableFuture which will be completed with the list of the elements retrieved.

drainAll

CompletableFuture<List<T>> drainAll(io.netty.util.concurrent.EventExecutor executor)

Subscribes to this StreamMessage and retrieves all elements from it. The returned CompletableFuture may be completed exceptionally with the following exceptions:

• IllegalStateException if other Subscriber subscribed to this stream already.
• AbortedStreamException if this stream has been aborted.
• Other exceptions that occurred due to an error while retrieving the elements.

Parameters:

executor - the executor to retrieve all elements

Returns:

the CompletableFuture which will be completed with the list of the elements retrieved.

drainAll

CompletableFuture<List<T>> drainAll(io.netty.util.concurrent.EventExecutor executor,
                                    SubscriptionOption... options)

Subscribes to this StreamMessage and retrieves all elements from it. The returned CompletableFuture may be completed exceptionally with the following exceptions:

• IllegalStateException if other Subscriber subscribed to this stream already.
• AbortedStreamException if this stream has been aborted.
• Other exceptions that occurred due to an error while retrieving the elements.

Parameters:

executor - the executor to retrieve all elements

options - SubscriptionOptions to subscribe with. Note that SubscriptionOption.NOTIFY_CANCELLATION is ineffective because there's no cancelling while draining all elements.

Returns:

the CompletableFuture which will be completed with the list of the elements retrieved.

abort

void abort()

Closes this stream with AbortedStreamException and prevents further subscription. A Subscriber that attempts to subscribe to an aborted stream will be notified with an AbortedStreamException via Subscriber.onError(Throwable). Calling this method on a closed or aborted stream has no effect.

abort

void abort(Throwable cause)

Closes this stream with the specified Throwable and prevents further subscription. A Subscriber that attempts to subscribe to an aborted stream will be notified with the specified Throwable via Subscriber.onError(Throwable). Calling this method on a closed or aborted stream has no effect.