Package io.helidon.common.http

Interface Content

All Superinterfaces:

Flow.Publisher<DataChunk>

public interface Content
extends Flow.Publisher<DataChunk>

Represents an HTTP entity as a publisher of chunks with specific features.

Default publisher contract

Default publisher accepts only single subscriber. Other subscribers receives onError().

DataChunk provided by onNext() method must be consumed in this method call. Buffer can be reused by network infrastructure as soon as onNext() method returns. This behavior can be inconvenient yet it helps to provide excellent performance.

Publisher Overwrite.

It is possible to modify contract of the original publisher by registration of a new publisher using registerFilter(Function) method. It can be used to wrap or replace previously registered (or default) publisher.

Entity Readers

It is possible to register function to convert publisher to CompletionStage of a single entity using registerReader(Class, Reader) or registerReader(Predicate, Reader) methods. It is then possible to use as(Class) method to obtain such entity.

Method Summary

Modifier and Type	Method and Description
<T> CompletionStage<T>	as(Class<T> type) Consumes and converts the request content into a completion stage of the requested type.
void	registerFilter(Function<Flow.Publisher<DataChunk>,Flow.Publisher<DataChunk>> function) Registers a filter that allows a control of the original publisher.
<T> void	registerReader(Class<T> type, Reader<T> reader) Registers a reader for a later use with an appropriate as(Class) method call.
<T> void	registerReader(Predicate<Class<?>> predicate, Reader<T> reader) Registers a reader for a later use with an appropriate as(Class) method call.
void	subscribe(Flow.Subscriber<? super DataChunk> subscriber) If possible, adds the given Subscriber to this publisher.

Method Detail

subscribe

void subscribe(Flow.Subscriber<? super DataChunk> subscriber)

If possible, adds the given Subscriber to this publisher. This publisher is effectively either the original publisher or the last publisher registered by the method registerFilter(Function).

Note that the original publisher allows only a single subscriber and requires the passed DataChunk in the Flow.Subscriber#onNext(Object) call to be consumed before the method completes as specified by the Default Publisher Contract.

Specified by:

subscribe in interface Flow.Publisher<DataChunk>

Parameters:

subscriber - the subscriber

Throws:

NullPointerException - if subscriber is null

registerFilter

void registerFilter(Function<Flow.Publisher<DataChunk>,Flow.Publisher<DataChunk>> function)

Registers a filter that allows a control of the original publisher.

The provided function is evaluated upon calling either of subscribe(Flow.Subscriber) or as(Class). The first evaluation of the function transforms the original publisher to a new publisher. Any subsequent evaluation receives the publisher transformed by the last previously registered filter. It is up to the implementor of the given function to respect the contract of both the original publisher and the previously registered ones.

Parameters:

function - a function that transforms a given publisher (that is either the original publisher or the publisher transformed by the last previously registered filter).

registerReader

<T> void registerReader(Class<T> type,
                        Reader<T> reader)

Registers a reader for a later use with an appropriate as(Class) method call.

The reader must transform the published byte buffers into a completion stage of the requested type.

Upon calling as(Class) a matching reader is searched in the same order as the readers were registered. If no matching reader is found, or when the function throws an exception, the resulting completion stage ends exceptionally.

Type Parameters:

T - the requested type

Parameters:

type - the requested type the completion stage is be associated with.

reader - the reader as a function that transforms a publisher into completion stage. If an exception is thrown, the resulting completion stage of as(Class) method call ends exceptionally.

registerReader

<T> void registerReader(Predicate<Class<?>> predicate,
                        Reader<T> reader)

Registers a reader for a later use with an appropriate as(Class) method call.

The reader must transform the published byte buffers into a completion stage of the requested type.

Upon calling as(Class) a matching reader is searched in the same order as the readers were registered. If no matching reader is found or when the predicate throws an exception, or when the function throws an exception, the resulting completion stage ends exceptionally.

Type Parameters:

T - the requested type

Parameters:

predicate - the predicate that determines whether the registered reader can handle the requested type. If an exception is thrown, the resulting completion stage of as(Class) method call ends exceptionally.

reader - the reader as a function that transforms a publisher into completion stage. If an exception is thrown, the resulting completion stage of as(Class) method call ends exceptionally.

as

<T> CompletionStage<T> as(Class<T> type)

Consumes and converts the request content into a completion stage of the requested type.

The conversion requires an appropriate reader to be already registered (see registerReader(Predicate, Reader)). If no such reader is found, the resulting completion stage ends exceptionally.

Type Parameters:

T - the requested type

Parameters:

type - the requested type class

Returns:

a completion stage of the requested type