0
# Runtime Providers and Program Execution
1

2
Core runtime integration that enables Spark 1.x programs to run within the CDAP platform with full lifecycle management, resource allocation, and proper integration with CDAP's program execution framework.
3

4
## Capabilities
5

6
### Spark 1.x Program Runtime Provider
7

8
Main runtime provider that integrates Spark 1.x applications with CDAP's program execution lifecycle, handling deployment, execution, and cleanup.
9

10
```java { .api }
11
/**
12
 * Runtime provider for Spark 1.x programs in CDAP
13
 * Extends SparkProgramRuntimeProvider with Spark 1.x specific compatibility
14
 */
15
@ProgramRuntimeProvider.SupportedProgramType(ProgramType.SPARK)
16
public class Spark1ProgramRuntimeProvider extends SparkProgramRuntimeProvider {
17
    /**
18
     * Creates a Spark 1.x runtime provider with SPARK1_2_10 compatibility
19
     */
20
    public Spark1ProgramRuntimeProvider();
21
}
22

23
/**
24
 * Abstract base class for Spark program runtime providers  
25
 * Handles class loading, runner creation, and program lifecycle management
26
 */
27
public abstract class SparkProgramRuntimeProvider implements ProgramRuntimeProvider {
28
    /**
29
     * Creates a program runner for the specified program type and execution mode
30
     * @param type The type of program (must be SPARK)
31
     * @param mode Execution mode (LOCAL or DISTRIBUTED)
32
     * @param injector Guice injector for dependency injection
33
     * @return ProgramRunner instance for executing the program
34
     * @throws IllegalArgumentException if program type is not SPARK
35
     */
36
    public ProgramRunner createProgramRunner(ProgramType type, Mode mode, Injector injector);
37
    
38
    /**
39
     * Checks if the specified program type is supported
40
     * @param programType The program type to check
41
     * @param cConf CDAP configuration  
42
     * @return true if program type is SPARK
43
     */
44
    public boolean isSupported(ProgramType programType, CConfiguration cConf);
45
    
46
    /**
47
     * Gets the Spark compatibility version for this provider
48
     * @return SparkCompat enum value (SPARK1_2_10, SPARK2_2_11, etc.)
49
     */
50
    protected SparkCompat getSparkCompat();
51
}
52
```
53

54
### Program Controller Interface
55

56
Interface for controlling Spark program execution, providing lifecycle management and command handling capabilities.
57

58
```java { .api }
59
/**
60
 * Controller interface for managing program execution lifecycle
61
 */
62
public interface ProgramController {
63
    /**
64
     * Sends a command to the running program
65
     * @param name Command name
66
     * @param value Command value
67
     * @return Future representing the command execution result
68
     */
69
    ListenableFuture<ProgramController> command(String name, Object value);
70
    
71
    /**
72
     * Stops the running program gracefully
73
     * @return Future representing the stop operation
74
     */
75
    ListenableFuture<ProgramController> stop();
76
    
77
    /**
78
     * Suspends the running program
79
     * @return Future representing the suspend operation
80
     */
81
    ListenableFuture<ProgramController> suspend();
82
    
83
    /**
84
     * Resumes a suspended program
85
     * @return Future representing the resume operation
86
     */
87
    ListenableFuture<ProgramController> resume();
88
    
89
    /**
90
     * Gets the current state of the program
91
     * @return Current program state
92
     */
93
    State getState();
94
    
95
    /**
96
     * Gets the program run ID
97
     * @return ProgramRunId for this execution
98
     */
99
    ProgramRunId getProgramRunId();
100
}
101
```
102

103
## Usage Examples
104

105
**Basic Runtime Provider Setup:**
106

107
```java
108
import co.cask.cdap.app.runtime.spark.Spark1ProgramRuntimeProvider;
109
import co.cask.cdap.proto.ProgramType;
110
import co.cask.cdap.app.runtime.ProgramRunner;
111

112
// Create runtime provider
113
Spark1ProgramRuntimeProvider provider = new Spark1ProgramRuntimeProvider();
114

115
// Verify it handles Spark programs
116
ProgramType supportedType = provider.getProgramType();
117
assert supportedType == ProgramType.SPARK;
118

119
// Check if program type is supported
120
boolean isSupported = provider.isSupported(ProgramType.SPARK, cConf);
121

122
// Create program runner
123
ProgramRunner runner = provider.createProgramRunner(ProgramType.SPARK, Mode.DISTRIBUTED, injector);
124
```
125

126
**Program Lifecycle Management:**
127

128
```java
129
import co.cask.cdap.app.runtime.ProgramController;
130
import co.cask.cdap.app.runtime.ProgramController.State;
131

132
// Get program controller (typically from program runner execution)
133
ProgramController controller = // ... obtained from program execution
134

135
// Monitor program state
136
State currentState = controller.getState();
137
System.out.println("Program state: " + currentState);
138

139
// Send command to program
140
controller.command("checkpoint", "/path/to/checkpoint").get();
141

142
// Suspend program
143
controller.suspend().get();
144

145
// Resume program
146
controller.resume().get();
147

148
// Stop program gracefully
149
controller.stop().get();
150
```
151

152
## Types
153

154
```java { .api }
155
/**
156
 * Enumeration of possible program states
157
 */
158
public enum State {
159
    STARTING,     // Program is initializing
160
    ALIVE,        // Program is running normally
161
    SUSPENDING,   // Program is being suspended
162
    SUSPENDED,    // Program is suspended
163
    RESUMING,     // Program is resuming from suspension
164
    STOPPING,     // Program is shutting down
165
    COMPLETED,    // Program completed successfully
166
    KILLED,       // Program was forcibly terminated
167
    ERROR         // Program encountered an error
168
}
169

170
/**
171
 * Program type enumeration
172
 */
173
public enum ProgramType {
174
    MAPREDUCE,   // MapReduce programs
175
    WORKFLOW,    // Workflow programs
176
    SERVICE,     // Service programs
177
    SPARK,       // Spark programs
178
    WORKER       // Worker programs
179
}
180

181
/**
182
 * Unique identifier for a program run
183
 */
184
public class ProgramRunId {
185
    /**
186
     * Gets the namespace containing the program
187
     * @return Namespace name
188
     */
189
    public String getNamespace();
190
    
191
    /**
192
     * Gets the application containing the program
193
     * @return Application name
194
     */
195
    public String getApplication();
196
    
197
    /**
198
     * Gets the program type
199
     * @return ProgramType of this program
200
     */
201
    public ProgramType getType();
202
    
203
    /**
204
     * Gets the program name
205
     * @return Program name
206
     */
207
    public String getProgram();
208
    
209
    /**
210
     * Gets the run ID
211
     * @return Unique run identifier
212
     */
213
    public String getRun();
214
}
215

216
/**
217
 * Configuration options for program execution
218
 */
219
public class ProgramOptions {
220
    /**
221
     * Gets runtime arguments for the program
222
     * @return Map of argument key-value pairs
223
     */
224
    public Map<String, String> getArguments();
225
    
226
    /**
227
     * Gets user-provided arguments
228
     * @return Map of user argument key-value pairs
229
     */
230
    public Map<String, String> getUserArguments();
231
    
232
    /**
233
     * Checks if debug mode is enabled
234
     * @return true if debug mode is enabled
235
     */
236
    public boolean isDebug();
237
    
238
    /**
239
     * Gets the program JAR location
240
     * @return Location of the program JAR file
241
     */
242
    public Location getProgramJarLocation();
243
}
244

245
/**
246
 * Interface for program runners that execute CDAP programs
247
 */
248
public interface ProgramRunner {
249
    /**
250
     * Runs a program with the specified options
251
     * @param programOptions Configuration for the program execution
252
     * @return ProgramController for managing the running program
253
     */
254
    ProgramController run(ProgramOptions programOptions);
255
}
256

257
/**
258
 * Execution mode enumeration for programs
259
 */
260
public enum Mode {
261
    LOCAL,        // Local execution mode
262
    DISTRIBUTED   // Distributed execution mode
263
}
264

265
/**
266
 * Guice injector interface for dependency injection
267
 */
268
public interface Injector {
269
    /**
270
     * Gets an instance of the specified type
271
     * @param type Class type to instantiate
272
     * @param <T> Type parameter
273
     * @return Instance of the specified type
274
     */
275
    <T> T getInstance(Class<T> type);
276
}
277
```