spark/launcher/SparkAppHandle.java

0001 /*
0002  * Licensed to the Apache Software Foundation (ASF) under one or more
0003  * contributor license agreements.  See the NOTICE file distributed with
0004  * this work for additional information regarding copyright ownership.
0005  * The ASF licenses this file to You under the Apache License, Version 2.0
0006  * (the "License"); you may not use this file except in compliance with
0007  * the License.  You may obtain a copy of the License at
0008  *
0009  *    http://www.apache.org/licenses/LICENSE-2.0
0010  *
0011  * Unless required by applicable law or agreed to in writing, software
0012  * distributed under the License is distributed on an "AS IS" BASIS,
0013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014  * See the License for the specific language governing permissions and
0015  * limitations under the License.
0016  */
0017
0018 package org.apache.spark.launcher;
0019
0020 import java.util.Optional;
0021
0022 /**
0023  * A handle to a running Spark application.
0024  * <p>
0025  * Provides runtime information about the underlying Spark application, and actions to control it.
0026  *
0027  * @since 1.6.0
0028  */
0029 public interface SparkAppHandle {
0030
0031   /**
0032    * Represents the application's state. A state can be "final", in which case it will not change
0033    * after it's reached, and means the application is not running anymore.
0034    *
0035    * @since 1.6.0
0036    */
0037   enum State {
0038     /** The application has not reported back yet. */
0039     UNKNOWN(false),
0040     /** The application has connected to the handle. */
0041     CONNECTED(false),
0042     /** The application has been submitted to the cluster. */
0043     SUBMITTED(false),
0044     /** The application is running. */
0045     RUNNING(false),
0046     /** The application finished with a successful status. */
0047     FINISHED(true),
0048     /** The application finished with a failed status. */
0049     FAILED(true),
0050     /** The application was killed. */
0051     KILLED(true),
0052     /** The Spark Submit JVM exited with a unknown status. */
0053     LOST(true);
0054
0055     private final boolean isFinal;
0056
0057     State(boolean isFinal) {
0058       this.isFinal = isFinal;
0059     }
0060
0061     /**
0062      * Whether this state is a final state, meaning the application is not running anymore
0063      * once it's reached.
0064      */
0065     public boolean isFinal() {
0066       return isFinal;
0067     }
0068   }
0069
0070   /**
0071    * Adds a listener to be notified of changes to the handle's information. Listeners will be called
0072    * from the thread processing updates from the application, so they should avoid blocking or
0073    * long-running operations.
0074    *
0075    * @param l Listener to add.
0076    */
0077   void addListener(Listener l);
0078
0079   /** Returns the current application state. */
0080   State getState();
0081
0082   /** Returns the application ID, or <code>null</code> if not yet known. */
0083   String getAppId();
0084
0085   /**
0086    * Asks the application to stop. This is best-effort, since the application may fail to receive
0087    * or act on the command. Callers should watch for a state transition that indicates the
0088    * application has really stopped.
0089    */
0090   void stop();
0091
0092   /**
0093    * Tries to kill the underlying application. Implies {@link #disconnect()}. This will not send
0094    * a {@link #stop()} message to the application, so it's recommended that users first try to
0095    * stop the application cleanly and only resort to this method if that fails.
0096    */
0097   void kill();
0098
0099   /**
0100    * Disconnects the handle from the application, without stopping it. After this method is called,
0101    * the handle will not be able to communicate with the application anymore.
0102    */
0103   void disconnect();
0104
0105   /**
0106    * If the application failed due to an error, return the underlying error. If the app
0107    * succeeded, this method returns an empty {@link Optional}.
0108    */
0109   Optional<Throwable> getError();
0110
0111   /**
0112    * Listener for updates to a handle's state. The callbacks do not receive information about
0113    * what exactly has changed, just that an update has occurred.
0114    *
0115    * @since 1.6.0
0116    */
0117   public interface Listener {
0118
0119     /**
0120      * Callback for changes in the handle's state.
0121      *
0122      * @param handle The updated handle.
0123      * @see SparkAppHandle#getState()
0124      */
0125     void stateChanged(SparkAppHandle handle);
0126
0127     /**
0128      * Callback for changes in any information that is not the handle's state.
0129      *
0130      * @param handle The updated handle.
0131      */
0132     void infoChanged(SparkAppHandle handle);
0133
0134   }
0135
0136 }