com.google.cloud.dataflow.sdk.transforms.windowing

Class Trigger<W extends BoundedWindow>

java.lang.Object

com.google.cloud.dataflow.sdk.transforms.windowing.Trigger<W>

Type Parameters:

W - BoundedWindow subclass used to represent the windows used by this Trigger

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

AfterEach, DefaultTrigger, Repeatedly, Trigger.OnceTrigger

@Experimental(value=TRIGGER)
public abstract class Trigger<W extends BoundedWindow>
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 the Window by the WindowFn, and then passed to the associated Trigger to determine if the Windows 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 a pane. Triggers are evaluated against the elements in the current pane, and when fired, will output those elements. Depending on the trigger, this will either finish the trigger (and the window) or start a new pane.

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(com.google.cloud.dataflow.sdk.transforms.windowing.Trigger<W>) to create a trigger that executes forever. Any time its argument finishes it gets reset and starts over. Can be combined with orFinally(com.google.cloud.dataflow.sdk.transforms.windowing.Trigger.OnceTrigger<W>) to specify a condition that causes the repetition to stop.
• AfterEach.inOrder(com.google.cloud.dataflow.sdk.transforms.windowing.Trigger<W>...) 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(com.google.cloud.dataflow.sdk.transforms.windowing.Trigger.OnceTrigger<W>...) to create a trigger that fires after at least one of its arguments fires. An AfterFirst trigger finishes after it fires once.
• AfterAll.of(com.google.cloud.dataflow.sdk.transforms.windowing.Trigger.OnceTrigger<W>...) to create a trigger that fires after all least one of its arguments have fired at least once. An AfterFirst trigger finishes after it fires once.

Each trigger tree is instantiated per-key and per-window. Every trigger in the tree is in one of the following states:

• Never Existed - before the trigger has started executing, there is no state associated with it anywhere in the system. A trigger moves to the executing state as soon as it processes in the current pane.
• Executing - while the trigger is receiving items and may fire. While it is in this state, it may persist book-keeping information to DoFn.KeyedState, set timers, etc.
• Finished - after a trigger finishes, all of its book-keeping data is cleaned up, and the system remembers only that it is finished. Entering this state causes us to discard any elements in the buffer for that window, as well.

Once finished, a trigger cannot return itself back to an earlier state, however a composite trigger could reset its sub-triggers.

Triggers should not build up any state internally since they may be recreated between invocations of the callbacks. All important values should be persisted to DoFn.KeyedState before the callback returns.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Trigger.OnceTrigger<W extends BoundedWindow> Triggers that are guaranteed to fire at most once should extend from this, rather than the general Trigger class to indicate that behavior.
static class	Trigger.OnElementEvent<W> Details about an invocation of onElement(com.google.cloud.dataflow.sdk.transforms.windowing.Trigger.TriggerContext<W>, com.google.cloud.dataflow.sdk.transforms.windowing.Trigger.OnElementEvent<W>).
static class	Trigger.OnMergeEvent<W> Details about an invocation of onMerge(com.google.cloud.dataflow.sdk.transforms.windowing.Trigger.TriggerContext<W>, com.google.cloud.dataflow.sdk.transforms.windowing.Trigger.OnMergeEvent<W>).
static class	Trigger.OnTimerEvent<W extends BoundedWindow> Details about an invocation of onTimer(com.google.cloud.dataflow.sdk.transforms.windowing.Trigger.TriggerContext<W>, com.google.cloud.dataflow.sdk.transforms.windowing.Trigger.OnTimerEvent<W>).
static class	Trigger.TimeDomain Triggers operate on both timestamps of elements that are being processed and the current (real-world) time as reported while processing.
static interface	Trigger.TriggerContext<W extends BoundedWindow> Information accessible to all of the callbacks that are executed on a trigger.
static class	Trigger.TriggerId<W extends BoundedWindow> Identifies a unique trigger instance, by the window it is in and the path through the trigger tree.
static class	Trigger.TriggerResult TriggerResult enumerates the possible result a trigger can have when it is executed.
static class	Trigger.WindowStatus WindowStatus indicates the status of the window that an element is being processed in.

Constructor Summary

Constructors

Constructor and Description
Trigger()

Method Summary

Methods

Modifier and Type	Method and Description
abstract void	clear(Trigger.TriggerContext<W> c, W window) Clear any state associated with this trigger in the given window.
abstract Instant	getWatermarkCutoff(W window) Returns a bound in watermark time by which this trigger would have fired at least once for a given window had there been input data.
abstract boolean	isCompatible(Trigger<?> other) Returns whether this performs the same triggering as the given Trigger.
abstract Trigger.TriggerResult	onElement(Trigger.TriggerContext<W> c, Trigger.OnElementEvent<W> e) Called immediately after an element is first incorporated into a window.
abstract Trigger.TriggerResult	onMerge(Trigger.TriggerContext<W> c, Trigger.OnMergeEvent<W> e) Called immediately after windows have been merged.
abstract Trigger.TriggerResult	onTimer(Trigger.TriggerContext<W> c, Trigger.OnTimerEvent<W> e) Called when a timer has fired for the trigger or one of it’s sub-triggers.
Trigger<W>	orFinally(Trigger.OnceTrigger<W> until) Specify an ending condition for this trigger.
boolean	willNeverFinish() Return true if the trigger is guaranteed to never finish.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Trigger

public Trigger()

Method Detail

onElement

public abstract Trigger.TriggerResult onElement(Trigger.TriggerContext<W> c,
                              Trigger.OnElementEvent<W> e)
                                         throws java.lang.Exception

Called immediately after an element is first incorporated into a window.

Parameters:

c - the context to interact with

e - an event describing the cause of this callback being executed

Throws:

java.lang.Exception

onMerge

public abstract Trigger.TriggerResult onMerge(Trigger.TriggerContext<W> c,
                            Trigger.OnMergeEvent<W> e)
                                       throws java.lang.Exception

Called immediately after windows have been merged.

This will only be called if the trigger hasn't finished in any of the oldWindows. If it had finished, we assume that it is also finished in the resulting window.

The implementation does not need to clear out any state associated with the old windows. That will automatically be done by the trigger execution layer.

Parameters:

c - the context to interact with

e - an event describnig the cause of this callback being executed

Throws:

java.lang.Exception

onTimer

public abstract Trigger.TriggerResult onTimer(Trigger.TriggerContext<W> c,
                            Trigger.OnTimerEvent<W> e)
                                       throws java.lang.Exception

Called when a timer has fired for the trigger or one of it’s sub-triggers.

Parameters:

c - the context to interact with

e - identifier for the trigger that the timer is for.

Throws:

java.lang.Exception

clear

public abstract void clear(Trigger.TriggerContext<W> c,
         W window)
                    throws java.lang.Exception

Clear any state associated with this trigger in the given window.

This is called after a trigger has indicated it will never fire again. The trigger system keeps enough information to know that the trigger is finished, so this trigger should clear all of its state.

Parameters:

c - the context to interact with

window - the window that is being cleared

Throws:

java.lang.Exception

willNeverFinish

public boolean willNeverFinish()

Return true if the trigger is guaranteed to never finish.

getWatermarkCutoff

public abstract Instant getWatermarkCutoff(W window)

Returns a bound in watermark time by which this trigger would have fired at least once for a given window had there been input data. This is a static property of a trigger that does not depend on its state.

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

isCompatible

public abstract boolean isCompatible(Trigger<?> other)

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

orFinally

public Trigger<W> orFinally(Trigger.OnceTrigger<W> until)

Specify an ending condition for this trigger. If the until 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.

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