Consumer used to conduct values through the stages of
a stream pipeline, with additional methods to manage size information,
control flow, etc. Before calling the accept() method on a
Sink for the first time, you must first call the begin()
method to inform it that data is coming (optionally informing the sink how
much data is coming), and after all data has been sent, you must call the
end() method. After calling end(), you should not call
accept() without again calling begin(). Sink also
offers a mechanism by which the sink can cooperatively signal that it does
not wish to receive any more data (the cancellationRequested()
method), which a source can poll before sending more data to the
Sink.
A sink may be in one of two states: an initial state and an active state.
It starts out in the initial state; the begin() method transitions
it to the active state, and the end() method transitions it back into
the initial state, where it can be re-used. Data-accepting methods (such as
accept() are only valid in the active state.
API Note
A stream pipeline consists of a source, zero or more intermediate stages (such as filtering or mapping), and a terminal stage, such as reduction or for-each. For concreteness, consider the pipeline:
int longestStringLengthStartingWithA
= strings.stream()
.filter(s -> s.startsWith("A"))
.mapToInt(String::length)
.max();
Here, we have three stages, filtering, mapping, and reducing. The filtering stage consumes strings and emits a subset of those strings; the mapping stage consumes strings and emits ints; the reduction stage consumes those ints and computes the maximal value.
A Sink instance is used to represent each stage of this pipeline,
whether the stage accepts objects, ints, longs, or doubles. Sink has entry
points for accept(Object), accept(int), etc, so that we do
not need a specialized interface for each primitive specialization. (It
might be called a "kitchen sink" for this omnivorous tendency.) The entry
point to the pipeline is the Sink for the filtering stage, which
sends some elements "downstream" -- into the Sink for the mapping
stage, which in turn sends integral values downstream into the Sink
for the reduction stage. The Sink implementations associated with a
given stage is expected to know the data type for the next stage, and call
the correct accept method on its downstream Sink. Similarly,
each stage must implement the correct accept method corresponding to
the data type it accepts.
The specialized subtypes such as Sink. override
accept(Object) to call the appropriate primitive specialization of
accept, implement the appropriate primitive specialization of
Consumer, and re-abstract the appropriate primitive specialization of
accept.
The chaining subtypes such as ChainedInt not only implement
Sink.OfInt, but also maintain a downstream field which
represents the downstream Sink, and implement the methods
begin(), end(), and cancellationRequested() to
delegate to the downstream Sink. Most implementations of
intermediate operations will use these chaining wrappers. For example, the
mapping stage in the above example would look like:
IntSink is = new Sink.ChainedReference<U>(sink) {
public void accept(U u) {
downstream.accept(mapper.applyAsInt(u));
}
};
Here, we implement Sink.ChainedReference<U>, meaning that we expect
to receive elements of type U as input, and pass the downstream sink
to the constructor. Because the next stage expects to receive integers, we
must call the accept(int) method when emitting values to the downstream.
The accept() method applies the mapping function from U to
int and passes the resulting value to the downstream Sink.
| Modifier and Type | Class and Description |
|---|---|
| public abstract static class | |
| public abstract static class | |
| public abstract static class | |
| public abstract static class | |
| public static interface | Sink.
|
| public static interface | Sink.
|
| public static interface | Sink.
|
| Modifier and Type | Method and Description |
|---|---|
| public default void | |
| public default void | |
| public default void | |
| public default void | begin(long
The exact size of the data to be pushed downstream, if
known or size)-1 if unknown or infinite.
Prior to this call, the sink must be in the initial state, and after this call it is in the active state. Resets the sink state to receive a fresh data set. |
| public default boolean | Returns: true if cancellation is requestedIndicates that this |
| public default void |
| accept | back to summary |
|---|---|
| public default void accept(int value) Implements java. Accepts an int value. Implementation Specification The default implementation throws IllegalStateException.
| |
| accept | back to summary |
|---|---|
| public default void accept(long value) Implements java. Accepts a long value. Implementation Specification The default implementation throws IllegalStateException.
| |
| accept | back to summary |
|---|---|
| public default void accept(double value) Implements java. Accepts a double value. Implementation Specification The default implementation throws IllegalStateException.
| |
| begin | back to summary |
|---|---|
| public default void begin(long size) Resets the sink state to receive a fresh data set. This must be called
before sending any data to the sink. After calling
| |
| cancellationRequested | back to summary |
|---|---|
| public default boolean cancellationRequested() Indicates that this Implementation Specification The default implementation always returns false.
| |
| end | back to summary |
|---|---|
| public default void end() Indicates that all elements have been pushed. If the Prior to this call, the sink must be in the active state, and after this call it is returned to the initial state. | |
Sink implementation designed for creating chains of
sinks. The begin, end, and
cancellationRequested methods are wired to chain to the
downstream Sink. This implementation takes a downstream
Sink of unknown input shape and produces a Sink.OfDouble.
The implementation of the accept() method must call the correct
accept() method on the downstream Sink.
| Modifier and Type | Field and Description |
|---|---|
| protected final Sink |
| Access | Constructor and Description |
|---|---|
| public |
| Modifier and Type | Method and Description |
|---|---|
| public void | begin(long size)
Overrides default java. Resets the sink state to receive a fresh data set. |
| public boolean | cancellationRequested()
Overrides default java. Indicates that this |
| public void |
| downstream | back to summary |
|---|---|
| protected final Sink<? super E_OUT> downstream | |
| ChainedDouble | back to summary |
|---|---|
| public ChainedDouble(Sink<? super E_OUT> downstream) | |
| begin | back to summary |
|---|---|
| public void begin(long size) Overrides default java. Doc from java. Resets the sink state to receive a fresh data set. This must be called
before sending any data to the sink. After calling
| |
| cancellationRequested | back to summary |
|---|---|
| public boolean cancellationRequested() Overrides default java. Doc from java. Indicates that this
| |
| end | back to summary |
|---|---|
| public void end() Overrides default java. Doc from java. Indicates that all elements have been pushed. If the Prior to this call, the sink must be in the active state, and after this call it is returned to the initial state.
| |
Sink implementation designed for creating chains of
sinks. The begin, end, and
cancellationRequested methods are wired to chain to the
downstream Sink. This implementation takes a downstream
Sink of unknown input shape and produces a Sink.OfInt.
The implementation of the accept() method must call the correct
accept() method on the downstream Sink.
| Modifier and Type | Field and Description |
|---|---|
| protected final Sink |
| Access | Constructor and Description |
|---|---|
| public |
| Modifier and Type | Method and Description |
|---|---|
| public void | begin(long size)
Overrides default java. Resets the sink state to receive a fresh data set. |
| public boolean | cancellationRequested()
Overrides default java. Indicates that this |
| public void |
| downstream | back to summary |
|---|---|
| protected final Sink<? super E_OUT> downstream | |
| ChainedInt | back to summary |
|---|---|
| public ChainedInt(Sink<? super E_OUT> downstream) | |
| begin | back to summary |
|---|---|
| public void begin(long size) Overrides default java. Doc from java. Resets the sink state to receive a fresh data set. This must be called
before sending any data to the sink. After calling
| |
| cancellationRequested | back to summary |
|---|---|
| public boolean cancellationRequested() Overrides default java. Doc from java. Indicates that this
| |
| end | back to summary |
|---|---|
| public void end() Overrides default java. Doc from java. Indicates that all elements have been pushed. If the Prior to this call, the sink must be in the active state, and after this call it is returned to the initial state.
| |
Sink implementation designed for creating chains of
sinks. The begin, end, and
cancellationRequested methods are wired to chain to the
downstream Sink. This implementation takes a downstream
Sink of unknown input shape and produces a Sink.OfLong.
The implementation of the accept() method must call the correct
accept() method on the downstream Sink.
| Modifier and Type | Field and Description |
|---|---|
| protected final Sink |
| Access | Constructor and Description |
|---|---|
| public |
| Modifier and Type | Method and Description |
|---|---|
| public void | begin(long size)
Overrides default java. Resets the sink state to receive a fresh data set. |
| public boolean | cancellationRequested()
Overrides default java. Indicates that this |
| public void |
| downstream | back to summary |
|---|---|
| protected final Sink<? super E_OUT> downstream | |
| ChainedLong | back to summary |
|---|---|
| public ChainedLong(Sink<? super E_OUT> downstream) | |
| begin | back to summary |
|---|---|
| public void begin(long size) Overrides default java. Doc from java. Resets the sink state to receive a fresh data set. This must be called
before sending any data to the sink. After calling
| |
| cancellationRequested | back to summary |
|---|---|
| public boolean cancellationRequested() Overrides default java. Doc from java. Indicates that this
| |
| end | back to summary |
|---|---|
| public void end() Overrides default java. Doc from java. Indicates that all elements have been pushed. If the Prior to this call, the sink must be in the active state, and after this call it is returned to the initial state.
| |
Sink implementation for creating chains of
sinks. The begin, end, and
cancellationRequested methods are wired to chain to the
downstream Sink. This implementation takes a downstream
Sink of unknown input shape and produces a Sink<T>. The
implementation of the accept() method must call the correct
accept() method on the downstream Sink.
| Modifier and Type | Field and Description |
|---|---|
| protected final Sink |
| Access | Constructor and Description |
|---|---|
| public |
| Modifier and Type | Method and Description |
|---|---|
| public void | begin(long size)
Overrides default java. Resets the sink state to receive a fresh data set. |
| public boolean | cancellationRequested()
Overrides default java. Indicates that this |
| public void |
| downstream | back to summary |
|---|---|
| protected final Sink<? super E_OUT> downstream | |
| ChainedReference | back to summary |
|---|---|
| public ChainedReference(Sink<? super E_OUT> downstream) | |
| begin | back to summary |
|---|---|
| public void begin(long size) Overrides default java. Doc from java. Resets the sink state to receive a fresh data set. This must be called
before sending any data to the sink. After calling
| |
| cancellationRequested | back to summary |
|---|---|
| public boolean cancellationRequested() Overrides default java. Doc from java. Indicates that this
| |
| end | back to summary |
|---|---|
| public void end() Overrides default java. Doc from java. Indicates that all elements have been pushed. If the Prior to this call, the sink must be in the active state, and after this call it is returned to the initial state.
| |
Sink that implements Sink<Double>, re-abstracts
accept(double), and wires accept(Double) to bridge to
accept(double).
| Modifier and Type | Method and Description |
|---|---|
| public void | accept(double value)
Redeclares java. Redeclares as abstract: java. Accepts a double value. |
| public default void | accept(Double i)
Implements java. Performs this operation on the given argument. |
| accept | back to summary |
|---|---|
| public void accept(double value) Redeclares java. Redeclares as abstract: java. Doc from java. Accepts a double value.
| |
| accept | back to summary |
|---|---|
| public default void accept(Double i) Implements java. Doc from java. Performs this operation on the given argument.
| |
Sink that implements Sink<Integer>, re-abstracts
accept(int), and wires accept(Integer) to bridge to
accept(int).
| Modifier and Type | Method and Description |
|---|---|
| public void | accept(int value)
Redeclares java. Redeclares as abstract: java. Accepts an int value. |
| public default void | accept(Integer i)
Implements java. Performs this operation on the given argument. |
| accept | back to summary |
|---|---|
| public void accept(int value) Redeclares java. Redeclares as abstract: java. Doc from java. Accepts an int value.
| |
| accept | back to summary |
|---|---|
| public default void accept(Integer i) Implements java. Doc from java. Performs this operation on the given argument.
| |
Sink that implements Sink<Long>, re-abstracts
accept(long), and wires accept(Long) to bridge to
accept(long).
| Modifier and Type | Method and Description |
|---|---|
| public void | accept(long value)
Redeclares java. Redeclares as abstract: java. Accepts a long value. |
| public default void | accept(Long i)
Implements java. Performs this operation on the given argument. |
| accept | back to summary |
|---|---|
| public void accept(long value) Redeclares java. Redeclares as abstract: java. Doc from java. Accepts a long value.
| |
| accept | back to summary |
|---|---|
| public default void accept(Long i) Implements java. Doc from java. Performs this operation on the given argument.
| |