Package org.apache.beam.sdk.transforms.windowing

Class Trigger

java.lang.Object
org.apache.beam.sdk.transforms.windowing.Trigger
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
AfterEach, AfterWatermark.AfterWatermarkEarlyAndLate, DefaultTrigger, OrFinallyTrigger, Repeatedly, ReshuffleTrigger, Trigger.OnceTrigger
public abstract class Trigger extends Object implements 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:

See Also:

  • Field Details

    • subTriggers

      protected final List<Trigger> subTriggers

  • Constructor Details

    • Trigger

      protected Trigger(List<Trigger> subTriggers)

    • Trigger

      protected Trigger()

  • Method Details

    • subTriggers

      public 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

      protected abstract Trigger getContinuationTrigger(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 - 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.

    • mayFinish

      @Internal public abstract boolean mayFinish()
      For internal use only; no backwards-compatibility guarantees.

      Indicates whether this trigger may "finish". A top level trigger that finishes can cause data loss, so is rejected by GroupByKey validation.

    • 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 String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(@Nullable Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class 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).