org.apache.beam.sdk.transforms.windowing

Class Trigger

java.lang.Object

org.apache.beam.sdk.transforms.windowing.Trigger

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

AfterEach, AfterWatermark.AfterWatermarkEarlyAndLate, DefaultTrigger, OrFinallyTrigger, Repeatedly, ReshuffleTrigger, Trigger.OnceTrigger

@Experimental(value=TRIGGER)
public abstract class Trigger
extends java.lang.Object
implements java.io.Serializable

Triggers control when the elements for a specific key and window are output. As elements arrive, they are put into one or more windows by a Window transform and its associated WindowFn, and then passed to the associated Trigger to determine if the Window's contents should be output.

See GroupByKey and Window for more information about how grouping with windows works.

The elements that are assigned to a window since the last time it was fired (or since the window was created) are placed into the current window pane. Triggers are evaluated against the elements as they are added. When the root trigger fires, the elements in the current pane will be output. When the root trigger finishes (indicating it will never fire again), the window is closed and any new elements assigned to that window are discarded.

Several predefined triggers are provided:

• AfterWatermark for firing when the watermark passes a timestamp determined from either the end of the window or the arrival of the first element in a pane.
• AfterProcessingTime for firing after some amount of processing time has elapsed (typically since the first element in a pane).
• AfterPane for firing off a property of the elements in the current pane, such as the number of elements that have been assigned to the current pane.

In addition, triggers can be combined in a variety of ways:

• Repeatedly.forever(org.apache.beam.sdk.transforms.windowing.Trigger) to create a trigger that executes forever. Any time its argument finishes it gets reset and starts over. Can be combined with orFinally(org.apache.beam.sdk.transforms.windowing.Trigger.OnceTrigger) to specify a condition that causes the repetition to stop.
• AfterEach.inOrder(org.apache.beam.sdk.transforms.windowing.Trigger...) to execute each trigger in sequence, firing each (and every) time that a trigger fires, and advancing to the next trigger in the sequence when it finishes.
• AfterFirst.of(org.apache.beam.sdk.transforms.windowing.Trigger.OnceTrigger...) to create a trigger that fires after at least one of its arguments fires. An AfterFirst trigger finishes after it fires once.
• AfterAll.of(org.apache.beam.sdk.transforms.windowing.Trigger.OnceTrigger...) to create a trigger that fires after all least one of its arguments have fired at least once. An AfterAll trigger finishes after it fires once.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Trigger.OnceTrigger For internal use only; no backwards-compatibility guarantees.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.List<Trigger>	subTriggers

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Trigger()
protected	Trigger(java.util.List<Trigger> subTriggers)

Method Summary

Modifier and Type	Method and Description
boolean	equals(java.lang.Object obj)
Trigger	getContinuationTrigger() Return a trigger to use after a GroupByKey to preserve the intention of this trigger.
protected abstract Trigger	getContinuationTrigger(java.util.List<Trigger> continuationTriggers) Subclasses should override this to return the getContinuationTrigger() of this Trigger.
abstract Instant	getWatermarkThatGuaranteesFiring(BoundedWindow window) For internal use only; no backwards-compatibility guarantees.
int	hashCode()
boolean	isCompatible(Trigger other) For internal use only; no backwards-compatibility guarantees.
OrFinallyTrigger	orFinally(Trigger.OnceTrigger until) Specify an ending condition for this trigger.
java.util.List<Trigger>	subTriggers()
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

subTriggers

@Nullable
protected final java.util.List<Trigger> subTriggers

Constructor Detail

Trigger

protected Trigger(@Nullable
                  java.util.List<Trigger> subTriggers)

Trigger

protected Trigger()

Method Detail

subTriggers

public java.util.List<Trigger> subTriggers()

getContinuationTrigger

public Trigger getContinuationTrigger()

Return a trigger to use after a GroupByKey to preserve the intention of this trigger. Specifically, triggers that are time based and intended to provide speculative results should continue providing speculative results. Triggers that fire once (or multiple times) should continue firing once (or multiple times).

If this method is not overridden, its default implementation delegates its behavior to getContinuationTrigger(List) which is expected to be implemented by subclasses.

getContinuationTrigger

@Nullable
protected abstract Trigger getContinuationTrigger(@Nullable
                                                            java.util.List<Trigger> continuationTriggers)

Subclasses should override this to return the getContinuationTrigger() of this Trigger. For convenience, this is provided the continuation trigger of each of the sub-triggers in the same order as subTriggers.

Parameters:

continuationTriggers - null if subTriggers is null, otherwise contains the result of getContinuationTrigger() on each of the subTriggers in the same order.

getWatermarkThatGuaranteesFiring

@Internal
public abstract Instant getWatermarkThatGuaranteesFiring(BoundedWindow window)

For internal use only; no backwards-compatibility guarantees.

Returns a bound in event time by which this trigger would have fired at least once for a given window had there been input data.

For triggers that do not fire based on the watermark advancing, returns BoundedWindow.TIMESTAMP_MAX_VALUE.

This estimate may be used, for example, to determine that there are no elements in a side-input window, which causes the default value to be used instead.

isCompatible

@Internal
public boolean isCompatible(Trigger other)

For internal use only; no backwards-compatibility guarantees.

Returns whether this performs the same triggering as the given Trigger.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

orFinally

public OrFinallyTrigger orFinally(Trigger.OnceTrigger until)

Specify an ending condition for this trigger. If the until Trigger fires then the combination fires.

The expression t1.orFinally(t2) fires every time t1 fires, and finishes as soon as either t1 finishes or t2 fires, in which case it fires one last time for t2. Both t1 and t2 are executed in parallel. This means that t1 may have fired since t2 started, so not all of the elements that t2 has seen are necessarily in the current pane.

For example the final firing of the following trigger may only have 1 element:

 Repeatedly.forever(AfterPane.elementCountAtLeast(2))
     .orFinally(AfterPane.elementCountAtLeast(5))
 

Note that if t1 is Trigger.OnceTrigger, then t1.orFinally(t2) is the same as AfterFirst.of(t1, t2).