Implementation:Apache Spark SparkAppHandle

Metadata

Field	Value
Source Type	Repo
Source Name	Apache Spark
Source URL	https://github.com/apache/spark
Domains	Monitoring
Type	API Doc

Overview

Java interface for monitoring and controlling running Spark application lifecycle.

Description

SparkAppHandle is a public interface providing runtime information about a running Spark application. It exposes:

• Application state — via the State enum with terminal and non-terminal states
• Application ID — the cluster-assigned identifier for the running application
• Error information — optional Throwable for diagnosing failures
• Control actions — stop(), kill(), and disconnect() for lifecycle management

The Listener nested interface enables event-driven monitoring via stateChanged() and infoChanged() callbacks, eliminating the need for polling.

Usage

Use when you need programmatic access to application state after submission via SparkLauncher.startApplication().

Code Reference

Source: Repository apache/spark, File launcher/src/main/java/org/apache/spark/launcher/SparkAppHandle.java, Lines 29-136

Signature (Java)

public interface SparkAppHandle {

    enum State {
        UNKNOWN, CONNECTED, SUBMITTED, RUNNING,
        FINISHED, FAILED, KILLED, LOST;

        public boolean isFinal() { ... }
    }

    State getState();
    String getAppId();
    void stop();
    void kill();
    void disconnect();
    Optional<Throwable> getError();
    void addListener(Listener l);

    interface Listener {
        void stateChanged(SparkAppHandle handle);
        void infoChanged(SparkAppHandle handle);
    }
}

Import

import org.apache.spark.launcher.SparkAppHandle;

I/O

Inputs

Input	Type	Description
Running SparkAppHandle	SparkAppHandle	Handle returned from SparkLauncher.startApplication()

Outputs

Output	Type	Description
State	SparkAppHandle.State enum	Current application lifecycle state
Application ID	String	Cluster-assigned application identifier (null until assigned)
Error	Optional<Throwable>	Error information if the application failed

Examples

Polling-Based Monitoring

while (!handle.getState().isFinal()) {
    Thread.sleep(1000);
}
System.out.println("Final state: " + handle.getState());

Listener-Based Monitoring

handle.addListener(new SparkAppHandle.Listener() {
    @Override
    public void stateChanged(SparkAppHandle h) {
        if (h.getState().isFinal()) {
            System.out.println("Done: " + h.getState());
        }
    }

    @Override
    public void infoChanged(SparkAppHandle h) {
        if (h.getAppId() != null) {
            System.out.println("App ID: " + h.getAppId());
        }
    }
});

Related

• Principle:Apache_Spark_Application_Lifecycle_Monitoring