TStream (Quarks v0.4.0)

Type Parameters:

T - Tuple type.

All Superinterfaces:

TopologyElement
```
public interface TStream<T>
extends TopologyElement
```
A TStream is a declaration of a continuous sequence of tuples. A connected topology of streams and functional transformations is built using Topology.
Generic methods on this interface provide the ability to filter, map (or transform) or sink this declared stream using a function.
TStream is not a runtime representation of a stream, it is a declaration used in building a topology. The actual runtime stream is created once the topology is submitted to a runtime.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`TStream<java.lang.String>`	`asString()` Convert this stream to a stream of `String` tuples by calling `toString()` on each tuple.
`TStream<T>`	`filter(Predicate<T> predicate)` Declare a new stream that filters tuples from this stream.
`<U> TStream<U>`	`flatMap(Function<T,java.lang.Iterable<U>> mapper)` Declare a new stream that maps tuples from this stream into one or more (or zero) tuples of a different type `U`.
`java.util.Set<java.lang.String>`	`getTags()` Returns the set of tags associated with this stream.
`<K> TWindow<T,K>`	`last(int count, Function<T,K> keyFunction)` Declare a partitioned window that continually represents the last `count` tuples on this stream for each partition.
`<K> TWindow<T,K>`	`last(long time, java.util.concurrent.TimeUnit unit, Function<T,K> keyFunction)` Declare a partitioned window that continually represents the last `time` seconds of tuples on this stream for each partition.
`<U> TStream<U>`	`map(Function<T,U> mapper)` Declare a new stream that maps (or transforms) each tuple from this stream into one (or zero) tuple of a different type `U`.
`TStream<T>`	`modify(UnaryOperator<T> modifier)` Declare a new stream that modifies each tuple from this stream into one (or zero) tuple of the same type `T`.
`TStream<T>`	`peek(Consumer<T> peeker)` Declare a stream that contains the same contents as this stream while peeking at each element using `peeker`.
`<U> TStream<U>`	`pipe(Pipe<T,U> pipe)` Declare a stream that contains the output of the specified `Pipe` oplet applied to this stream.
`TSink<T>`	`print()` Utility method to print the contents of this stream to `System.out` at runtime.
`TSink<T>`	`sink(Consumer<T> sinker)` Sink (terminate) this stream using a function.
`TSink<T>`	`sink(Sink<T> oplet)` Sink (terminate) this stream using a oplet.
`java.util.List<TStream<T>>`	`split(int n, ToIntFunction<T> splitter)` Split a stream's tuples among `n` streams as specified by `splitter`.
`TStream<T>`	`tag(java.lang.String... values)` Adds the specified tags to the stream.
`TStream<T>`	`union(java.util.Set<TStream<T>> others)` Declare a stream that will contain all tuples from this stream and all the streams in `others`.
`TStream<T>`	`union(TStream<T> other)` Declare a stream that will contain all tuples from this stream and `other`.

Methods inherited from interface quarks.topology.TopologyElement
topology

- Method Detail
 - filter
```
TStream<T> filter(Predicate<T> predicate)
```
 Declare a new stream that filters tuples from this stream. Each tuple t on this stream will appear in the returned stream if filter.test(t) returns true. If filter.test(t) returns false then then t will not appear in the returned stream.
 Examples of filtering out all empty strings from stream s of type String
```
 
 TStream<String> s = ...
 TStream<String> filtered = s.filter(t -> !t.isEmpty());
 
 
 
```
 Parameters:
 
 predicate - Filtering logic to be executed against each tuple.
 
 Returns:
 
 Filtered stream
 - map
```
 TStream map(Function<T,U> mapper)
```
 Declare a new stream that maps (or transforms) each tuple from this stream into one (or zero) tuple of a different type U. For each tuple t on this stream, the returned stream will contain a tuple that is the result of mapper.apply(t) when the return is not null. If mapper.apply(t) returns null then no tuple is submitted to the returned stream for t.
 Examples of transforming a stream containing numeric values as String objects into a stream of Double values.
```
 
 // Using lambda expression
 TStream<String> strings = ...
 TStream<Double> doubles = strings.map(v -> Double.valueOf(v));
 
 // Using method reference
 TStream<String> strings = ...
 TStream<Double> doubles = strings.map(Double::valueOf);
 
 
 
```
 Parameters:
 
 mapper - Mapping logic to be executed against each tuple.
 
 Returns:
 
 Stream that will contain tuples of type U mapped from this stream's tuples.
 - flatMap
```
 TStream flatMap(Function<T,java.lang.Iterable> mapper)
```
 Declare a new stream that maps tuples from this stream into one or more (or zero) tuples of a different type U. For each tuple t on this stream, the returned stream will contain all non-null tuples in the Iterator that is the result of mapper.apply(t). Tuples will be added to the returned stream in the order the iterator returns them.
 If the return is null or an empty iterator then no tuples are added to the returned stream for input tuple t.
 Examples of mapping a stream containing lines of text into a stream of words split out from each line. The order of the words in the stream will match the order of the words in the lines.
```
 
 TStream<String> lines = ...
 TStream<String> words = lines.flatMap(
 line -> Arrays.asList(line.split(" ")));
 
 
 
```
 Type Parameters:
 
 U - Type of mapped input tuples.
 
 Parameters:
 
 mapper - Mapper logic to be executed against each tuple.
 
 Returns:
 
 Stream that will contain tuples of type U mapped and flattened from this stream's tuples.
 - split
```
java.util.List<TStream<T>> split(int n,
 ToIntFunction<T> splitter)
```
 Split a stream's tuples among n streams as specified by splitter.
 For each tuple on the stream, splitter.applyAsInt(tuple) is called. The return value r determines the destination stream:
```
 if r < 0 the tuple is discarded
 else it is sent to the stream at position (r % n) in the returned array.
 
```
 Each split TStream is exposed by the API. The user has full control over the each stream's processing pipeline. Each stream's pipeline must be declared explicitly. Each stream can have different processing pipelines.
 
 An N-way split() is logically equivalent to a collection of N filter() invocations, each with a predicate to select the tuples for its stream. split() is more efficient. Each tuple is analyzed only once by a single splitter instance to identify the destination stream. For example, these are logically equivalent:
```
 List<TStream<String>> streams = stream.split(2, tuple -> tuple.length());
 
 TStream<String> stream0 = stream.filter(tuple -> (tuple.length() % 2) == 0);
 TStream<String> stream1 = stream.filter(tuple -> (tuple.length() % 2) == 1);
 
```
 Example of splitting a stream of log records by their level attribute:
```
 
 TStream<LogRecord> lrs = ...
 List<<TStream<LogRecord>> splits = lrr.split(3, lr -> {
 if (SEVERE.equals(lr.getLevel()))
 return 0;
 else if (WARNING.equals(lr.getLevel()))
 return 1;
 else
 return 2;
 });
 splits.get(0). ... // SEVERE log record processing pipeline
 splits.get(1). ... // WARNING log record processing pipeline
 splits.get(2). ... // "other" log record processing pipeline
 
 
```
 Parameters:
 
 n - the number of output streams
 
 splitter - the splitter function
 
 Returns:
 
 List of n streams
 
 Throws:
 
 java.lang.IllegalArgumentException - if n <= 0
 - peek
```
TStream<T> peek(Consumer<T> peeker)
```
 Declare a stream that contains the same contents as this stream while peeking at each element using peeker.
 For each tuple t on this stream, peeker.accept(t) will be called.
 
 Parameters:
 
 peeker - Function to be called for each tuple.
 
 Returns:
 
 this
 - sink
```
TSink<T> sink(Consumer<T> sinker)
```
 Sink (terminate) this stream using a function. For each tuple t on this stream sinker.accept(t) will be called. This is typically used to send information to external systems, such as databases or dashboards.
 If sinker implements AutoCloseable, its close() method will be called when the topology's execution is terminated.
 Example of terminating a stream of String tuples by printing them to System.out.
```
 
 TStream<String> values = ...
 values.sink(t -> System.out.println(tuple));
 
 
```
 Parameters:
 
 sinker - Logic to be executed against each tuple on this stream.
 
 Returns:
 
 sink element representing termination of this stream.
 - sink
```
TSink<T> sink(Sink<T> oplet)
```
 Sink (terminate) this stream using a oplet. This provides a richer api for a sink than sink(Consumer) with a full life-cycle of the oplet as well as easy access to runtime services.
 
 Parameters:
 
 oplet - Oplet processes each tuple without producing output.
 
 Returns:
 
 sink element representing termination of this stream.
 - pipe
```
 TStream pipe(Pipe<T,U> pipe)
```
 Declare a stream that contains the output of the specified Pipe oplet applied to this stream.
 
 Type Parameters:
 
 U - Tuple type of the returned stream.
 
 Parameters:
 
 pipe - The Pipe oplet.
 
 Returns:
 
 Declared stream that contains the tuples emitted by the pipe oplet.
 - modify
```
TStream<T> modify(UnaryOperator<T> modifier)
```
 Declare a new stream that modifies each tuple from this stream into one (or zero) tuple of the same type T. For each tuple t on this stream, the returned stream will contain a tuple that is the result of modifier.apply(t) when the return is not null. The function may return the same reference as its input t or a different object of the same type. If modifier.apply(t) returns null then no tuple is submitted to the returned stream for t.
 Example of modifying a stream String values by adding the suffix 'extra'.
```
 
 TStream<String> strings = ...
 TStream<String> modifiedStrings = strings.modify(t -> t.concat("extra"));
 
 
```
 This method is equivalent to map(Function<T,T> modifier).
 
 Parameters:
 
 modifier - Modifier logic to be executed against each tuple.
 
 Returns:
 
 Stream that will contain tuples of type T modified from this stream's tuples.
 - asString
```
TStream<java.lang.String> asString()
```
 Convert this stream to a stream of String tuples by calling toString() on each tuple. This is equivalent to map(Object::toString).
 
 Returns:
 
 Declared stream that will contain each the string representation of each tuple on this stream.
 - print
```
TSink<T> print()
```
 Utility method to print the contents of this stream to System.out at runtime. Each tuple is printed using System.out.println(tuple).
 
 Returns:
 
 TSink for the sink processing.
 - last
```
<K> TWindow<T,K> last(int count,
 Function<T,K> keyFunction)
```
 Declare a partitioned window that continually represents the last count tuples on this stream for each partition. Each partition independently maintains the last count tuples for each key seen on this stream. If no tuples have been seen on the stream for a key then the corresponding partition will be empty.
 The window is partitioned by each tuple's key, obtained by keyFunction. For each tuple on the stream keyFunction.apply(tuple) is called and the returned value is the tuple's key. For any two tuples ta,tb in a partition keyFunction.apply(ta).equals(keyFunction.apply(tb)) is true.
 The key function must return keys that implement equals() and hashCode() correctly.
 To create a window partitioned using the tuple as the key use identity() as the key function.
 
 To create an unpartitioned window use a key function that returns a constant, by convention unpartitioned() is recommended.
 
 Type Parameters:
 
 K - Key type.
 
 Parameters:
 
 count - Number of tuples to maintain in each partition.
 
 keyFunction - Function that defines the key for each tuple.
 
 Returns:
 
 Window on this stream representing the last count tuples for each partition.
 - last
```
<K> TWindow<T,K> last(long time,
 java.util.concurrent.TimeUnit unit,
 Function<T,K> keyFunction)
```
 Declare a partitioned window that continually represents the last time seconds of tuples on this stream for each partition. If no tuples have been seen on the stream for a key in the last time seconds then the partition will be empty. Each partition independently maintains the last count tuples for each key seen on this stream.
 The window is partitioned by each tuple's key, obtained by keyFunction. For each tuple on the stream keyFunction.apply(tuple) is called and the returned value is the tuple's key. For any two tuples ta,tb in a partition keyFunction.apply(ta).equals(keyFunction.apply(tb)) is true.
 The key function must return keys that implement equals() and hashCode() correctly.
 To create a window partitioned using the tuple as the key use identity() as the key function.
 
 To create an unpartitioned window use a key function that returns a constant, by convention unpartitioned() is recommended.
 
 Type Parameters:
 
 K - Key type.
 
 Parameters:
 
 time - Time to retain a tuple in a partition.
 
 unit - Unit for time.
 
 keyFunction - Function that defines the key for each tuple.
 
 Returns:
 
 Partitioned window on this stream representing the last count tuple.
 - union
```
TStream<T> union(TStream<T> other)
```
 Declare a stream that will contain all tuples from this stream and other. A stream cannot be unioned with itself, in this case this will be returned.
 
 Parameters:
 
 other -
 
 Returns:
 
 A stream that is the union of this and other.
 - union
```
TStream<T> union(java.util.Set<TStream<T>> others)
```
 Declare a stream that will contain all tuples from this stream and all the streams in others. A stream cannot be unioned with itself, in this case the union will only contain tuples from this stream once. If others is empty or only contains this then this is returned.
 
 Parameters:
 
 others - Stream to union with this stream.
 
 Returns:
 
 A stream that is the union of this and others.
 - tag
```
TStream<T> tag(java.lang.String... values)
```
 Adds the specified tags to the stream. Adding the same tag to a stream multiple times will not change the result beyond the initial application.
 
 Parameters:
 
 values - Tag values.
 
 Returns:
 
 The tagged stream.
 - getTags
```
java.util.Set<java.lang.String> getTags()
```
 Returns the set of tags associated with this stream.
 
 Returns:
 
 set of tags

Methods inherited from interface quarks.topology.TopologyElement

filter

map

flatMap

split

peek

sink

sink

pipe

modify

asString

print

last

last

union

union

tag

getTags