Implementation:Apache Beam PipelineMessageReceiver

Knowledge Sources	Apache_Beam Beam Programming Guide
Domains	Data_Processing, Runner_Infrastructure
Last Updated	2026-02-09 00:00 GMT

Overview

Concrete callback interface for receiving terminal pipeline execution events (failures, cancellations, completions) in the Apache Beam local runner.

Description

The PipelineMessageReceiver interface defines four callback methods that allow pipeline execution components to report terminal outcomes to a central handler. It supports two flavors of failure reporting (Exception and Error), a cancelled() callback for user-initiated cancellation, and a completed() callback for successful termination. This interface acts as the communication channel between the execution engine (e.g., ExecutorServiceParallelExecutor) and the result handler (e.g., DirectPipelineResult).

Usage

Use this interface when implementing a pipeline result handler that needs to be notified of execution outcomes. The DirectRunner wires an implementation of this interface to its parallel executor so that the executor can signal completion, cancellation, or failure. Not typically imported by end users; it is a runner-internal API.

Code Reference

Source Location

• Repository: Apache_Beam
• File: runners/local-java/src/main/java/org/apache/beam/runners/local/PipelineMessageReceiver.java
• Lines: 18-33

Signature

public interface PipelineMessageReceiver {

    /** Report that a failure has occurred (checked exception). */
    void failed(Exception e);

    /** Report that a failure has occurred (unchecked error). */
    void failed(Error e);

    /** Report that the pipeline has been cancelled. */
    void cancelled();

    /** Report that the pipeline has successfully completed. */
    void completed();
}

Import

import org.apache.beam.runners.local.PipelineMessageReceiver;

I/O Contract

Inputs

Name	Type	Required	Description
e (failed)	Exception	Yes (for Exception variant)	The checked exception that caused the failure
e (failed)	Error	Yes (for Error variant)	The unchecked error that caused the failure

Outputs

Name	Type	Description
(side effect)	void	All methods are void; they mutate the receiver's internal state to record the terminal event

Usage Examples

Implementing a Pipeline Result Handler

import org.apache.beam.runners.local.PipelineMessageReceiver;

// A simple implementation that tracks pipeline state
public class SimplePipelineResultHandler implements PipelineMessageReceiver {
    private volatile State state = State.RUNNING;
    private volatile Throwable failure;

    @Override
    public void failed(Exception e) {
        this.failure = e;
        this.state = State.FAILED;
    }

    @Override
    public void failed(Error e) {
        this.failure = e;
        this.state = State.FAILED;
    }

    @Override
    public void cancelled() {
        this.state = State.CANCELLED;
    }

    @Override
    public void completed() {
        this.state = State.DONE;
    }

    public State getState() { return state; }
    public Throwable getFailure() { return failure; }

    enum State { RUNNING, DONE, FAILED, CANCELLED }
}

Related Pages

• Environment:Apache_Beam_Java_Build_Environment