StreamWindow (IBM Streams Java Operator API)

```
public interface StreamWindow<T>
```
A window connected to an input port (stream). A window's type is either tumbling or sliding.
A tumbling window has an eviction policy that determines when all tuples are evicted and the window tumbles.
A sliding window has an eviction policy that defines how tuples are evicted (the slide) and a trigger policy that determines when a trigger event is generated.
An operator registers a listener against a window to handle the defined window events such as insertion and eviction.

The StreamWindow maintains the logical collection of ordered tuples that are contained in the window, ordered by arrival time, from oldest to most recent. The logical collection by default includes the reference to the tuple object that contains the tuple's attribute values, its data. The window event listener may remove the tuple reference from the window while handling an event, if it no longer requires the tuple's data to maintain its state. This allows reduction of memory usage by a window, by potentially allowing the tuple to be garbage collected.
While the tuple reference will be removed from the window, logically the tuple remains in the window, though its attribute values are no longer available. This is to ensure correct eviction processing, for example removing a tuple reference does not reduce the number of logical tuples in the window ensuring eviction for a count based policy is honored correctly.

The StreamWindow manages ordering of StreamWindowEvent processing so that only a single event is being processed at any time and events are always processed by the StreamEventListener in the correct order.

See Also:

StreamWindowEvent.Type, StreamWindowListener

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static class StreamWindow.Policy
Policy type for eviction and trigger policies.

static class StreamWindow.Type
Window type.

Nested Classes
Modifier and Type	Interface and Description
`static class`	`StreamWindow.Policy` Policy type for eviction and trigger policies.
`static class`	`StreamWindow.Type` Window type.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`evictPartition(java.lang.Object partition)` Evict a partition and its tuples from the window.
`StreamWindow.Policy`	`getEvictionPolicy()` Get the eviction policy for the window.
`StreamingInput<T>`	`getInputPort()` Get the StreamingInput reference for the input port this window is for.
`OperatorContext`	`getOperatorContext()` Return the `OperatorContext` for this window's operator invocation.
`java.util.Collection<?>`	`getPartitions()` Get a read-only copy of the partition keys in the window.
`StreamWindow.Policy`	`getTriggerPolicy()` Get the trigger policy for a sliding window.
`StreamWindow.Type`	`getType()` Return the type of the window defined against the port.
`boolean`	`isPartitioned()` Is this window partitioned.
`boolean`	`needsPartitionEviction()` Determine if partition eviction is required according to policy.
`void`	`registerListener(StreamWindowListener<T> listener, boolean useAsynchronousTasks)` Register a listener to handle window events.
`void`	`registerPartitioner(StreamWindowPartitioner<T,?> partitioner)` Register a StreamWindowPartitioner for the window.

- Method Detail
  - getType
```
StreamWindow.Type getType()
```
    Return the type of the window defined against the port.
    
    Returns:
    
    NONE, TUMBLING or SLIDING.
  - getInputPort
```
StreamingInput<T> getInputPort()
```
    Get the StreamingInput reference for the input port this window is for.
    
    Returns:
    
    The input port for the window.
  - getEvictionPolicy
```
StreamWindow.Policy getEvictionPolicy()
```
    Get the eviction policy for the window.
    
    Returns:
    
    The eviction policy or NONE if the port is not windowed.
  - getTriggerPolicy
```
StreamWindow.Policy getTriggerPolicy()
```
    Get the trigger policy for a sliding window.
    
    Returns:
    
    The trigger policy or NONE for a tumbling window.
  - isPartitioned
```
boolean isPartitioned()
```
    Is this window partitioned. The window definition only indicates if the window should be partitioned, the operator implementation defines the partitions and the tuple to partitioning mapping.
    
    Returns:
    
    True if the window is partitioned, false otherwise..
  - registerListener
```
void registerListener(StreamWindowListener<T> listener,
                      boolean useAsynchronousTasks)
```
    Register a listener to handle window events. The listener replaces the previous listener as only a single listener is supported. If useAsynchronousTasks is set to true then threads that generated the event (such as the thread handling the arrival of a tuple at a port) may not wait for the completion of the event's handling. Use of asynchronous does not change the guaranteed ordering of event handling.
    The listener must be registered during Operator.initialize() to guarantee that all tuples and punctuation arriving on the port are handled by the listener.
    
    If listener also implements StateHandler then it is also registered as an operator's state handler.
    Operators must ensure that instances of StateHandler and StreamWindowListener are registered in a consistent order to ensure the order of information written to a checkpoint and read from a checkpoint upon reset is consistent.
    
    Parameters:
    
    listener - Listener to handle events.
    
    useAsynchronousTasks - Where possible execute the event handling as an asynchronous task.
  - registerPartitioner
```
void registerPartitioner(StreamWindowPartitioner<T,?> partitioner)
```
    Register a StreamWindowPartitioner for the window. The getPartition() method of partitioner will be called for each tuple inserted into the window. The returned partition will set as the partition value for the corresponding StreamWindowEvent objects related to the tuple.
    
    Parameters:
    
    partitioner - Window partitioner logic.
  - evictPartition
```
void evictPartition(java.lang.Object partition)
             throws java.lang.Exception
```
    Evict a partition and its tuples from the window. Eviction of a partition results in a window event of type StreamWindowEvent.Type.PARTITION_EVICTION.
    
    Parameters:
    
    partition - The partition to be evicted. If the partition does not exist in the window then no action is taken.
    
    Throws:
    
    java.lang.IllegalStateException - Window is not partitioned.
    
    java.lang.Exception - Exception thrown handling the PARTITION_EVICTION event.
    
    Since:
    
    InfoSphere® Streams Version 2.0.0.3
  - getPartitions
```
java.util.Collection<?> getPartitions()
```
    Get a read-only copy of the partition keys in the window. The partition keys are the values returned by StreamWindowPartitioner.getPartition(Object).
    When the window has no partition eviction specified in SPL the ordering of iteration of the elements is undefined.
    
    When partition eviction is defined, iterating over the Collection is ordered by the time of the last tuple insertion into the partition, with the partition with the oldest insertion first, and the partition with the most recent insertion last.
    
    Throws:
    
    java.lang.IllegalStateException - - Window is not partitioned.
    
    Since:
    
    InfoSphere® Streams Version 2.0.0.3
  - needsPartitionEviction
```
boolean needsPartitionEviction()
```
    Determine if partition eviction is required according to policy. Returns true when the window is partitioned, has a partition eviction policy of partitionCount() or tupleCount() and partitions need to be evicted to honor the policy.
    
    Returns:
    
    True if the number of partitions or tuples exceed the eviction policy. False if the partition eviction policy is age based or no count based eviction is required.
    
    Throws:
    
    java.lang.IllegalStateException - - Window is not partitioned.
    
    Since:
    
    InfoSphere® Streams Version 2.0.0.3
    
    See Also:
    
    StreamWindowEvent.Type.PARTITION_EVICTION
  - getOperatorContext
```
OperatorContext getOperatorContext()
```
    Return the OperatorContext for this window's operator invocation.
    
    Returns:
    
    Context for this window's operator invocation.
    
    Since:
    
    InfoSphere® Streams Version 4.0

getType

getInputPort

getEvictionPolicy

getTriggerPolicy

isPartitioned

registerListener

registerPartitioner

evictPartition

getPartitions

needsPartitionEviction

getOperatorContext