com.tangosol.util.stream.RemoteStream Maven / Gradle / Ivy
Show all versions of coherence Show documentation
/*
* Copyright (c) 2000, 2021, Oracle and/or its affiliates.
*
* Licensed under the Universal Permissive License v 1.0 as shown at
* http://oss.oracle.com/licenses/upl.
*/
package com.tangosol.util.stream;
import com.tangosol.internal.util.invoke.Lambdas;
import com.tangosol.internal.util.stream.StreamSupport;
import com.tangosol.util.Filters;
import com.tangosol.util.InvocableMap;
import com.tangosol.util.ValueExtractor;
import com.tangosol.util.comparator.ExtractorComparator;
import com.tangosol.util.comparator.InverseComparator;
import com.tangosol.util.function.Remote;
import java.util.Comparator;
import java.util.Optional;
import java.util.function.BiConsumer;
import java.util.function.BiFunction;
import java.util.function.BinaryOperator;
import java.util.function.Consumer;
import java.util.function.Function;
import java.util.function.IntFunction;
import java.util.function.Predicate;
import java.util.function.Supplier;
import java.util.function.ToDoubleFunction;
import java.util.function.ToIntFunction;
import java.util.function.ToLongFunction;
import java.util.stream.Collector;
import java.util.stream.DoubleStream;
import java.util.stream.IntStream;
import java.util.stream.LongStream;
import java.util.stream.Stream;
/**
* This interface is an extension of {@code java.util.stream.Stream} that captures
* lambdas used as method arguments as serializable lambdas.
*
* @param the type of the stream elements
*
* @author as 2014.08.11
* @since 12.2.1
*
* @see RemoteIntStream
* @see RemoteLongStream
* @see RemoteDoubleStream
* @see com.tangosol.util.stream
*/
public interface RemoteStream
extends Stream, BaseRemoteStream>
{
/**
* Create a {@link RemoteStream} of specified map's entries.
*
* @param map the map to create a remote stream for
* @param the type of map keys
* @param the type of map values
*
* @return a {@link RemoteStream} of specified map's entries
*/
public static RemoteStream> entrySet(InvocableMap map)
{
return StreamSupport
.entryStream(map, true, null, Filters.always());
}
/**
* Create a {@link RemoteStream} of specified map's keys.
*
* @param map the map to create a remote stream for
* @param the type of map keys
* @param the type of map values
*
* @return a {@link RemoteStream} of specified map's keys
*/
public static RemoteStream keySet(InvocableMap map)
{
return StreamSupport
.entryStream(map, true, null, Filters.always())
.map(InvocableMap.Entry::getKey);
}
/**
* Create a {@link RemoteStream} of specified map's values.
*
* @param map the map to create a remote stream for
* @param the type of map keys
* @param the type of map values
*
* @return a {@link RemoteStream} of specified map's values
*/
public static RemoteStream values(InvocableMap map)
{
return StreamSupport
.entryStream(map, true, null, Filters.always())
.map(InvocableMap.Entry::getValue);
}
/**
* Returns an equivalent stream that is sequential. May return itself,
* either because the stream was already sequential, or because the
* underlying stream state was modified to be sequential.
*
* This is an intermediate operation.
*
* @return a sequential stream
*/
RemoteStream sequential();
/**
* Returns an equivalent stream that is parallel. May return itself, either
* because the stream was already parallel, or because the underlying stream
* state was modified to be parallel.
*
* This is an intermediate operation.
*
* @return a parallel stream
*/
RemoteStream parallel();
/**
* Returns an equivalent stream that is unordered.
* May return itself, either because the stream was already unordered, or
* because the underlying stream state670G was modified to be unordered.
*
* This is an intermediate operation.
*
* @return an unordered stream
*/
RemoteStream unordered();
/**
* Returns a stream consisting of the elements of this stream that match the
* given predicate.
*
* This is an intermediate operation.
*
* @param predicate a non-interfering, stateless predicate to apply to each
* element to determine if it should be included
*
* @return the new stream
*/
RemoteStream filter(Predicate predicate);
/**
* Returns a stream consisting of the elements of this stream that match the
* given predicate.
*
* This is an intermediate operation.
*
* @param predicate a non-interfering, stateless predicate to apply to each
* element to determine if it should be included
*
* @return the new stream
*/
default RemoteStream filter(Remote.Predicate predicate)
{
return filter((Predicate) predicate);
}
/**
* Returns a stream consisting of the results of applying the given function
* to the elements of this stream.
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
RemoteStream map(Function mapper);
/**
* Returns a stream consisting of the results of applying the given function
* to the elements of this stream.
*
* This is an intermediate operation.
*
* @param the type of resulting stream elements
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
default RemoteStream map(Remote.Function mapper)
{
return map((Function) mapper);
}
/**
* Returns a stream consisting of the results of applying the given extractor
* to the elements of this stream.
*
* This is an intermediate operation.
*
* @param the type of resulting stream elements
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
default RemoteStream map(ValueExtractor mapper)
{
return map((Function) Lambdas.ensureRemotable(mapper));
}
/**
* Returns an {@code IntStream} consisting of the results of applying the
* given function to the elements of this stream.
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
RemoteIntStream mapToInt(ToIntFunction mapper);
/**
* Returns an {@code IntStream} consisting of the results of applying the
* given function to the elements of this stream.
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
default RemoteIntStream mapToInt(Remote.ToIntFunction mapper)
{
return mapToInt((ToIntFunction) mapper);
}
/**
* Returns an {@code IntStream} consisting of the results of applying the
* given extractor to the elements of this stream.
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
default RemoteIntStream mapToInt(ValueExtractor mapper)
{
return mapToInt((ToIntFunction) Lambdas.ensureRemotable(mapper));
}
/**
* Returns a {@code LongStream} consisting of the results of applying the
* given function to the elements of this stream.
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
RemoteLongStream mapToLong(ToLongFunction mapper);
/**
* Returns a {@code LongStream} consisting of the results of applying the
* given function to the elements of this stream.
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
default RemoteLongStream mapToLong(Remote.ToLongFunction mapper)
{
return mapToLong((ToLongFunction) mapper);
}
/**
* Returns an {@code LongStream} consisting of the results of applying the
* given extractor to the elements of this stream.
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
default RemoteLongStream mapToLong(ValueExtractor mapper)
{
return mapToLong((ToLongFunction) Lambdas.ensureRemotable(mapper));
}
/**
* Returns a {@code DoubleStream} consisting of the results of applying the
* given function to the elements of this stream.
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
RemoteDoubleStream mapToDouble(ToDoubleFunction mapper);
/**
* Returns a {@code DoubleStream} consisting of the results of applying the
* given function to the elements of this stream.
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
default RemoteDoubleStream mapToDouble(Remote.ToDoubleFunction mapper)
{
return mapToDouble((ToDoubleFunction) mapper);
}
/**
* Returns an {@code DoubleStream} consisting of the results of applying the
* given extractor to the elements of this stream.
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
default RemoteDoubleStream mapToDouble(ValueExtractor mapper)
{
return mapToDouble((ToDoubleFunction) Lambdas.ensureRemotable(mapper));
}
/**
* Returns a stream consisting of the results of replacing each element of
* this stream with the contents of a mapped stream produced by applying
* the provided mapping function to each element. Each mapped stream is
* {@link BaseRemoteStream#close() closed} after its contents have been placed
* into this stream. (If a mapped stream is {@code null} an empty stream
* is used, instead.)
*
* This is an intermediate operation.
*
* @param The element type of the new stream
* @param mapper a non-interfering, stateless
* function to apply to each element which produces a stream
* of new values
*
* @return the new stream
*/
RemoteStream flatMap(Function> mapper);
/**
* Returns a stream consisting of the results of replacing each element of
* this stream with the contents of a mapped stream produced by applying
* the provided mapping function to each element. Each mapped stream is
* {@link BaseRemoteStream#close() closed} after its contents have been placed
* into this stream. (If a mapped stream is {@code null} an empty stream
* is used, instead.)
*
* This is an intermediate operation.
*
* @param The element type of the new stream
* @param mapper a non-interfering, stateless
* function to apply to each element which produces a stream
* of new values
*
* @return the new stream
*/
default RemoteStream flatMap(Remote.Function> mapper)
{
Function> safeMapper =
Remote.function(t -> t == null ? null : mapper.apply(t));
return flatMap(safeMapper);
}
/**
* Returns an {@code IntStream} consisting of the results of replacing each
* element of this stream with the contents of a mapped stream produced by
* applying the provided mapping function to each element. Each mapped
* stream is {@link BaseRemoteStream#close() closed} after its contents have been
* placed into this stream. (If a mapped stream is {@code null} an empty
* stream is used, instead.)
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element which produces a stream
* of new values
*
* @return the new stream
*
* @see #flatMap(Function)
*/
RemoteIntStream flatMapToInt(Function mapper);
/**
* Returns an {@code IntStream} consisting of the results of replacing each
* element of this stream with the contents of a mapped stream produced by
* applying the provided mapping function to each element. Each mapped
* stream is {@link BaseRemoteStream#close() closed} after its contents have been
* placed into this stream. (If a mapped stream is {@code null} an empty
* stream is used, instead.)
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element which produces a stream
* of new values
*
* @return the new stream
*
* @see #flatMap(Function)
*/
default RemoteIntStream flatMapToInt(Remote.Function mapper)
{
Function safeMapper =
Remote.function(t -> t == null ? null : mapper.apply(t));
return flatMapToInt(safeMapper);
}
/**
* Returns an {@code LongStream} consisting of the results of replacing each
* element of this stream with the contents of a mapped stream produced by
* applying the provided mapping function to each element. Each mapped
* stream is {@link BaseRemoteStream#close() closed} after its contents have been
* placed into this stream. (If a mapped stream is {@code null} an empty
* stream is used, instead.)
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element which produces a stream
* of new values
*
* @return the new stream
*
* @see #flatMap(Function)
*/
RemoteLongStream flatMapToLong(Function mapper);
/**
* Returns an {@code LongStream} consisting of the results of replacing each
* element of this stream with the contents of a mapped stream produced by
* applying the provided mapping function to each element. Each mapped
* stream is {@link BaseRemoteStream#close() closed} after its contents have been
* placed into this stream. (If a mapped stream is {@code null} an empty
* stream is used, instead.)
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element which produces a stream
* of new values
*
* @return the new stream
*
* @see #flatMap(Function)
*/
default RemoteLongStream flatMapToLong(Remote.Function mapper)
{
Function safeMapper =
Remote.function(t -> t == null ? null : mapper.apply(t));
return flatMapToLong(safeMapper);
}
/**
* Returns an {@code DoubleStream} consisting of the results of replacing
* each element of this stream with the contents of a mapped stream produced
* by applying the provided mapping function to each element. Each mapped
* stream is {@link BaseRemoteStream#close() closed} after its contents have been
* placed into this stream. (If a mapped stream is {@code null} an empty
* stream is used, instead.)
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element which produces a stream
* of new values
*
* @return the new stream
*
* @see #flatMap(Function)
*/
RemoteDoubleStream flatMapToDouble(Function mapper);
/**
* Returns an {@code DoubleStream} consisting of the results of replacing
* each element of this stream with the contents of a mapped stream produced
* by applying the provided mapping function to each element. Each mapped
* stream is {@link BaseRemoteStream#close() closed} after its contents have been
* placed into this stream. (If a mapped stream is {@code null} an empty
* stream is used, instead.)
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element which produces a stream
* of new values
*
* @return the new stream
*
* @see #flatMap(Function)
*/
default RemoteDoubleStream flatMapToDouble(Remote.Function mapper)
{
Function safeMapper =
Remote.function(t -> t == null ? null : mapper.apply(t));
return flatMapToDouble(safeMapper);
}
/**
* Returns a stream consisting of the elements of this stream, additionally
* performing the provided action on each element as elements are consumed
* from the resulting stream.
*
* This is an intermediate operation.
*
* For parallel stream pipelines, the action may be called at whatever
* time and in whatever thread the element is made available by the upstream
* operation. If the action modifies shared state, it is responsible for
* providing the required synchronization.
*
* @param action a non-interfering action to perform on the elements as they
* are consumed from the stream
*
* @return the new stream
*/
RemoteStream peek(Consumer action);
/**
* Returns a stream consisting of the elements of this stream, additionally
* performing the provided action on each element as elements are consumed
* from the resulting stream.
*
* This is an intermediate operation.
*
* For parallel stream pipelines, the action may be called at whatever
* time and in whatever thread the element is made available by the upstream
* operation. If the action modifies shared state, it is responsible for
* providing the required synchronization.
*
* @param action a non-interfering action to perform on the elements as they
* are consumed from the stream
*
* @return the new stream
*/
default RemoteStream peek(Remote.Consumer action)
{
return peek((Consumer) action);
}
/**
* Returns a stream consisting of the elements of this stream, truncated to
* be no longer than {@code maxSize} in length.
*
* This is a short-circuiting stateful intermediate operation.
*
* @param maxSize the number of elements the stream should be limited to
*
* @return the new stream
*
* @throws IllegalArgumentException if {@code maxSize} is negative
*/
Stream limit(long maxSize);
/**
* Returns a stream consisting of the remaining elements of this stream
* after discarding the first {@code n} elements of the stream.
* If this stream contains fewer than {@code n} elements then an
* empty stream will be returned.
*
* This is a stateful intermediate operation.
*
* @param n the number of leading elements to skip
*
* @return the new stream
*
* @throws IllegalArgumentException if {@code n} is negative
*/
Stream skip(long n);
/**
* Returns a stream consisting of the distinct elements (according to
* {@link Object#equals(Object)}) of this stream.
*
* For ordered streams, the selection of distinct elements is stable
* (for duplicated elements, the element appearing first in the encounter
* order is preserved.) For unordered streams, no stability guarantees
* are made.
*
* This is a stateful intermediate operation.
*
* @return the new stream
*/
Stream distinct();
/**
* Returns a stream consisting of the elements of this stream, sorted
* according to natural order. If the elements of this stream are not
* {@code Comparable}, a {@code java.lang.ClassCastException} may be thrown
* when the terminal operation is executed.
*
* For ordered streams, the sort is stable. For unordered streams, no
* stability guarantees are made.
*
* This is a stateful intermediate operation.
*
* @return the new stream
*/
RemoteStream sorted();
/**
* Returns a stream consisting of the elements of this stream, sorted
* according to the provided {@code Comparator}.
*
* For ordered streams, the sort is stable. For unordered streams, no
* stability guarantees are made.
*
* This is a stateful intermediate operation.
*
* @param comparator a non-interfering, stateless
* {@code Comparator} to be used to compare stream elements
*
* @return the new stream
*/
RemoteStream sorted(Comparator comparator);
/**
* Returns a stream consisting of the elements of this stream, sorted
* according to the provided {@code Comparator}.
*
* For ordered streams, the sort is stable. For unordered streams, no
* stability guarantees are made.
*
*
This is a stateful
* intermediate operation.
*
* @param comparator a non-interfering, stateless
* {@code Comparator} to be used to compare stream elements
*
* @return the new stream
*/
default RemoteStream sorted(Remote.Comparator comparator)
{
return sorted(comparator, false);
}
/**
* Returns a stream consisting of the elements of this stream, sorted
* according to the provided {@code Comparator}.
*
* For ordered streams, the sort is stable. For unordered streams, no
* stability guarantees are made.
*
*
This is a stateful
* intermediate operation.
*
* @param comparator a non-interfering, stateless
* {@code Comparator} to be used to compare stream elements
* @param fInverse a flag specifying whether to invert the sort order
*
* @return the new stream
*/
default RemoteStream sorted(Remote.Comparator comparator, boolean fInverse)
{
Comparator c = fInverse ? new InverseComparator<>(comparator) : comparator;
return sorted(c);
}
/**
* Returns a stream consisting of the elements of this stream, sorted
* according to attribute extracted by the provided {@code ValueExtractor}.
*
* For ordered streams, the sort is stable. For unordered streams, no
* stability guarantees are made.
*
*
This is a stateful
* intermediate operation.
*
* @param a super type of the value to extract from
* @param extractor a non-interfering, stateless
* {@code ValueExtractor} to be used to extract the attribute
* that should be used to compare stream elements
*
* @return the new stream
*/
default RemoteStream sorted(ValueExtractor extractor)
{
return sorted(extractor, false);
}
/**
* Returns a stream consisting of the elements of this stream, sorted
* according to attribute extracted by the provided {@code ValueExtractor}.
*
* For ordered streams, the sort is stable. For unordered streams, no
* stability guarantees are made.
*
*
This is a stateful
* intermediate operation.
*
* @param the super type of value to extract from
* @param extractor a non-interfering, stateless
* {@code ValueExtractor} to be used to extract the attribute
* that should be used to compare stream elements
* @param fInverse a flag specifying whether to invert natural sort order
*
* @return the new stream
*/
default RemoteStream sorted(ValueExtractor extractor, boolean fInverse)
{
Comparator comparator = new ExtractorComparator(extractor);
if (fInverse)
{
comparator = new InverseComparator<>(comparator);
}
return sorted(comparator);
}
/**
* Performs an action for each element of this stream.
*
* This is a terminal operation.
*
* @param action a non-interfering action to perform on the elements
*/
void forEach(Consumer action);
/**
* Performs an action for each element of this stream, in the encounter
* order of the stream if the stream has a defined encounter order.
*
* This is a terminal operation.
*
* This operation processes the elements one at a time, in encounter
* order if one exists. Performing the action for one element
* happens-before performing the action for subsequent elements,
* but for any given element, the action may be performed in whatever thread
* the library chooses.
*
* @param action a non-interfering action to perform on the elements
*
* @see #forEach(Consumer)
*/
void forEachOrdered(Consumer action);
/**
* Returns an array containing the elements of this stream.
*
* This is a terminal operation.
*
* @return an array containing the elements of this stream
*/
Object[] toArray();
/**
* Returns an array containing the elements of this stream, using the
* provided {@code generator} function to allocate the returned array, as
* well as any additional arrays that might be required for a partitioned
* execution or for resizing.
*