org.infinispan

Interface BaseCacheStream<T,S extends java.util.stream.BaseStream<T,S>>

All Superinterfaces:

java.lang.AutoCloseable, java.util.stream.BaseStream<T,S>

All Known Subinterfaces:

CacheStream<R>, DoubleCacheStream, IntCacheStream, LockedStream<K,V>, LongCacheStream

public interface BaseCacheStream<T,S extends java.util.stream.BaseStream<T,S>>
extends java.util.stream.BaseStream<T,S>

Interface that defines the base methods of all streams returned from a Cache. This interface is useful to hold a reference to any of the types while still being able to invoke some methods.

Since:

9.0

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	BaseCacheStream.SegmentCompletionListener Functional interface that is used as a callback when segments are completed.

Method Summary

Modifier and Type	Method and Description
BaseCacheStream	disableRehashAware() Disables tracking of rehash events that could occur to the underlying cache.
BaseCacheStream	distributedBatchSize(int batchSize) Controls how many keys are returned from a remote node when using a stream terminal operation with a distributed cache to back this stream.
BaseCacheStream	filterKeys(java.util.Set<?> keys) Filters which entries are returned by only returning ones that map to the given key.
BaseCacheStream	filterKeySegments(IntSet segments) Filters which entries are returned by what segment they are present in.
BaseCacheStream	filterKeySegments(java.util.Set<java.lang.Integer> segments) Deprecated. since 9.3 This is to be replaced by filterKeySegments(IntSet)
BaseCacheStream	parallelDistribution() This would enable sending requests to all other remote nodes when a terminal operator is performed.
BaseCacheStream	segmentCompletionListener(BaseCacheStream.SegmentCompletionListener listener) Allows registration of a segment completion listener that is notified when a segment has completed processing.
BaseCacheStream	sequentialDistribution() This would disable sending requests to all other remote nodes compared to one at a time.
BaseCacheStream	timeout(long timeout, java.util.concurrent.TimeUnit unit) Sets a given time to wait for a remote operation to respond by.

Methods inherited from interface java.util.stream.BaseStream

close, isParallel, iterator, onClose, parallel, sequential, spliterator, unordered

Method Detail

sequentialDistribution

BaseCacheStream sequentialDistribution()

This would disable sending requests to all other remote nodes compared to one at a time. This can reduce memory pressure on the originator node at the cost of performance.

Parallel distribution is enabled by default except for CacheStream.iterator() and CacheStream.spliterator()

Returns:

a stream with parallel distribution disabled

parallelDistribution

BaseCacheStream parallelDistribution()

This would enable sending requests to all other remote nodes when a terminal operator is performed. This requires additional overhead as it must process results concurrently from various nodes, but should perform faster in the majority of cases.

Parallel distribution is enabled by default except for CacheStream.iterator() and CacheStream.spliterator()

Returns:

a stream with parallel distribution enabled.

filterKeySegments

BaseCacheStream filterKeySegments(java.util.Set<java.lang.Integer> segments)

Deprecated. since 9.3 This is to be replaced by filterKeySegments(IntSet)

Filters which entries are returned by what segment they are present in. This method can be substantially more efficient than using a regular CacheStream.filter(Predicate) method as this can control what nodes are asked for data and what entries are read from the underlying CacheStore if present.

Parameters:

segments - The segments to use for this stream operation. Any segments not in this set will be ignored.

Returns:

a stream with the segments filtered.

filterKeySegments

BaseCacheStream filterKeySegments(IntSet segments)

Filters which entries are returned by what segment they are present in. This method can be substantially more efficient than using a regular CacheStream.filter(Predicate) method as this can control what nodes are asked for data and what entries are read from the underlying CacheStore if present.

Parameters:

segments - The segments to use for this stream operation. Any segments not in this set will be ignored.

Returns:

a stream with the segments filtered.

Since:

9.3

filterKeys

BaseCacheStream filterKeys(java.util.Set<?> keys)

Filters which entries are returned by only returning ones that map to the given key. This method will be faster than a regular CacheStream.filter(Predicate) if the filter is holding references to the same keys.

Parameters:

keys - The keys that this stream will only operate on.

Returns:

a stream with the keys filtered.

distributedBatchSize

BaseCacheStream distributedBatchSize(int batchSize)

Controls how many keys are returned from a remote node when using a stream terminal operation with a distributed cache to back this stream. This value is ignored when terminal operators that don't track keys are used. Key tracking terminal operators are CacheStream.iterator(), CacheStream.spliterator(), CacheStream.forEach(Consumer). Please see those methods for additional information on how this value may affect them.

This value may be used in the case of a a terminal operator that doesn't track keys if an intermediate operation is performed that requires bringing keys locally to do computations. Examples of such intermediate operations are CacheStream.sorted(), CacheStream.sorted(Comparator), CacheStream.distinct(), CacheStream.limit(long), CacheStream.skip(long)

This value is always ignored when this stream is backed by a cache that is not distributed as all values are already local.

Parameters:

batchSize - The size of each batch. This defaults to the state transfer chunk size.

Returns:

a stream with the batch size updated

segmentCompletionListener

BaseCacheStream segmentCompletionListener(BaseCacheStream.SegmentCompletionListener listener)

Allows registration of a segment completion listener that is notified when a segment has completed processing. If the terminal operator has a short circuit this listener may never be called.

This method is designed for the sole purpose of use with the CacheStream.iterator() to allow for a user to track completion of segments as they are returned from the iterator. Behavior of other methods is not specified. Please see CacheStream.iterator() for more information.

Multiple listeners may be registered upon multiple invocations of this method. The ordering of notified listeners is not specified.

This is only used if this stream did not invoke disableRehashAware() and has no flat map based operations. If this is done no segments will be notified.

Parameters:

listener - The listener that will be called back as segments are completed.

Returns:

a stream with the listener registered.

disableRehashAware

BaseCacheStream disableRehashAware()

Disables tracking of rehash events that could occur to the underlying cache. If a rehash event occurs while a terminal operation is being performed it is possible for some values that are in the cache to not be found. Note that you will never have an entry duplicated when rehash awareness is disabled, only lost values.

Most terminal operations will run faster with rehash awareness disabled even without a rehash occuring. However if a rehash occurs with this disabled be prepared to possibly receive only a subset of values.

Returns:

a stream with rehash awareness disabled.

timeout

BaseCacheStream timeout(long timeout,
                        java.util.concurrent.TimeUnit unit)

Sets a given time to wait for a remote operation to respond by. This timeout does nothing if the terminal operation does not go remote.

If a timeout does occur then a TimeoutException is thrown from the terminal operation invoking thread or on the next call to the Iterator or Spliterator.

Note that if a rehash occurs this timeout value is reset for the subsequent retry if rehash aware is enabled.

Parameters:

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

a stream with the timeout set