0
# Data Transfer Objects
1
2
Comprehensive request and response body classes for all API operations. These classes provide type-safe data exchange between client and server, ensuring consistent JSON serialization and validation across the Flink web interface.
3
4
## Capabilities
5
6
### Request Body Classes
7
8
#### JAR Request Body (Base Class)
9
10
Abstract base class for all JAR operation requests.
11
12
```java { .api }
13
/**
14
* Abstract base class for JAR operation request bodies.
15
* Provides common properties for JAR execution and plan generation.
16
*/
17
public abstract class JarRequestBody implements RequestBody {
18
/**
19
* Default constructor for JAR request body.
20
*/
21
protected JarRequestBody();
22
23
/**
24
* Create a JAR request body with specified parameters.
25
*
26
* @param entryClassName Entry class (main class) name for the JAR
27
* @param programArguments Program arguments as a single string
28
* @param programArgumentsList Program arguments as a list of strings
29
* @param parallelism Parallelism setting for the job
30
* @param jobId Job ID for the operation
31
*/
32
protected JarRequestBody(
33
String entryClassName,
34
String programArguments,
35
List<String> programArgumentsList,
36
Integer parallelism,
37
JobID jobId
38
);
39
40
/**
41
* Get the entry class (main class) name for the JAR.
42
*
43
* @return The fully qualified entry class name, or null if not specified
44
*/
45
public String getEntryClassName();
46
47
48
/**
49
* Get the program arguments as a single string.
50
*
51
* @return Program arguments as a string, or null if none specified
52
*/
53
public String getProgramArguments();
54
55
/**
56
* Get the program arguments as a list of strings.
57
*
58
* @return List of program arguments, or null if none specified
59
*/
60
public List<String> getProgramArgumentsList();
61
62
/**
63
* Get the parallelism setting for the job.
64
*
65
* @return The parallelism value, or null to use default
66
*/
67
public Integer getParallelism();
68
69
/**
70
* Get the job ID for the operation.
71
*
72
* @return The job ID, or null if not specified
73
*/
74
public JobID getJobId();
75
}
76
```
77
78
#### JAR Run Request Body
79
80
Request body for JAR execution operations with savepoint support.
81
82
```java { .api }
83
/**
84
* Request body for JAR execution operations.
85
* Extends base JAR request with savepoint-specific options.
86
*/
87
public class JarRunRequestBody extends JarRequestBody {
88
/**
89
* Default constructor for JAR run request body.
90
*/
91
public JarRunRequestBody();
92
93
/**
94
* Create a JAR run request body with specified parameters.
95
*
96
* @param entryClassName Entry class (main class) name for the JAR
97
* @param programArguments Program arguments as a single string
98
* @param programArgumentsList Program arguments as a list of strings
99
* @param parallelism Parallelism setting for the job
100
* @param jobId Job ID for the operation
101
* @param allowNonRestoredState Whether to allow non-restored state when restoring from savepoint
102
* @param savepointPath Path to savepoint file for job restoration
103
*/
104
public JarRunRequestBody(
105
String entryClassName,
106
String programArguments,
107
List<String> programArgumentsList,
108
Integer parallelism,
109
JobID jobId,
110
Boolean allowNonRestoredState,
111
String savepointPath
112
);
113
114
/**
115
* Get whether to allow non-restored state when restoring from savepoint.
116
*
117
* @return true to allow non-restored state, false to require exact match, null for default
118
*/
119
public Boolean getAllowNonRestoredState();
120
121
/**
122
* Get the savepoint path for job restoration.
123
*
124
* @return Path to savepoint file, or null if not restoring from savepoint
125
*/
126
public String getSavepointPath();
127
}
128
```
129
130
#### JAR Plan Request Body
131
132
Request body for execution plan generation.
133
134
```java { .api }
135
/**
136
* Request body for JAR execution plan generation.
137
* Uses base JAR request properties without savepoint options.
138
*/
139
public class JarPlanRequestBody extends JarRequestBody {
140
// Inherits all properties from JarRequestBody
141
// No additional properties specific to plan generation
142
}
143
```
144
145
### Response Body Classes
146
147
#### JAR Upload Response Body
148
149
Response for JAR upload operations.
150
151
```java { .api }
152
/**
153
* Response body for JAR upload operations.
154
* Contains upload status and file information.
155
*/
156
public class JarUploadResponseBody implements ResponseBody {
157
/**
158
* Create a JAR upload response.
159
*
160
* @param filename Name of the uploaded JAR file
161
*/
162
public JarUploadResponseBody(String filename);
163
164
/**
165
* Get the upload status.
166
*
167
* @return Status string (typically "success")
168
*/
169
public String getStatus();
170
171
/**
172
* Get the filename of the uploaded JAR.
173
*
174
* @return The JAR filename
175
*/
176
public String getFilename();
177
178
/**
179
* Set the upload status.
180
*
181
* @param status Status string
182
*/
183
public void setStatus(String status);
184
185
/**
186
* Set the filename of the uploaded JAR.
187
*
188
* @param filename The JAR filename
189
*/
190
public void setFilename(String filename);
191
}
192
```
193
194
#### JAR Run Response Body
195
196
Response for JAR execution operations.
197
198
```java { .api }
199
/**
200
* Response body for JAR execution operations.
201
* Contains the job ID of the submitted job.
202
*/
203
public class JarRunResponseBody implements ResponseBody {
204
/**
205
* Create a JAR run response.
206
*
207
* @param jobId The ID of the submitted job
208
*/
209
public JarRunResponseBody(JobID jobId);
210
211
/**
212
* Get the job ID of the submitted job.
213
*
214
* @return The job ID
215
*/
216
public JobID getJobId();
217
218
/**
219
* Set the job ID.
220
*
221
* @param jobId The job ID
222
*/
223
public void setJobId(JobID jobId);
224
}
225
```
226
227
#### JAR List Response Body
228
229
Complex response for JAR listing operations with nested information classes.
230
231
```java { .api }
232
/**
233
* Response body for JAR listing operations.
234
* Contains comprehensive information about all uploaded JARs.
235
*/
236
public class JarListInfo implements ResponseBody {
237
/**
238
* Create a JAR list response.
239
*
240
* @param address Server address information
241
* @param jarFileInfos List of JAR file information
242
*/
243
public JarListInfo(String address, List<JarFileInfo> jarFileInfos);
244
245
/**
246
* Get the server address.
247
*
248
* @return Server address string
249
*/
250
public String getAddress();
251
252
/**
253
* Get the list of JAR file information.
254
*
255
* @return List of JarFileInfo objects
256
*/
257
public List<JarFileInfo> getFiles();
258
259
/**
260
* Information about an individual JAR file.
261
* Contains file metadata and available entry points.
262
*/
263
public static class JarFileInfo {
264
/**
265
* Create JAR file information.
266
*
267
* @param id Unique identifier for the JAR
268
* @param name Original filename of the JAR
269
* @param uploaded Timestamp when JAR was uploaded
270
* @param entry List of available entry points
271
*/
272
public JarFileInfo(String id, String name, long uploaded, List<JarEntryInfo> entry);
273
274
/**
275
* Get the JAR ID.
276
*
277
* @return Unique JAR identifier
278
*/
279
public String getId();
280
281
/**
282
* Get the JAR filename.
283
*
284
* @return Original filename
285
*/
286
public String getName();
287
288
/**
289
* Get the upload timestamp.
290
*
291
* @return Timestamp in milliseconds
292
*/
293
public long getUploaded();
294
295
/**
296
* Get the list of available entry points.
297
*
298
* @return List of JarEntryInfo objects
299
*/
300
public List<JarEntryInfo> getEntry();
301
}
302
303
/**
304
* Information about a JAR entry point (main class).
305
* Contains class name and description.
306
*/
307
public static class JarEntryInfo {
308
/**
309
* Create JAR entry information.
310
*
311
* @param name Fully qualified class name
312
* @param description Description of the entry point
313
*/
314
public JarEntryInfo(String name, String description);
315
316
/**
317
* Get the entry class name.
318
*
319
* @return Fully qualified class name
320
*/
321
public String getName();
322
323
/**
324
* Get the entry description.
325
*
326
* @return Description string
327
*/
328
public String getDescription();
329
}
330
}
331
```
332
333
## Usage Examples
334
335
### Creating Request Bodies
336
337
```java
338
import org.apache.flink.runtime.webmonitor.handlers.*;
339
import org.apache.flink.api.common.JobID;
340
import java.util.Arrays;
341
342
// Create JAR run request with constructor
343
JarRunRequestBody runRequest = new JarRunRequestBody(
344
"com.example.MyFlinkJob", // entryClassName
345
null, // programArguments (string)
346
Arrays.asList("--input", "/path/to/input", "--output", "/path/to/output"), // programArgumentsList
347
4, // parallelism
348
JobID.generate(), // jobId
349
true, // allowNonRestoredState
350
"/path/to/savepoint" // savepointPath
351
);
352
353
// Create JAR plan request
354
JarPlanRequestBody planRequest = new JarPlanRequestBody(
355
"com.example.MyFlinkJob", // entryClassName
356
null, // programArguments (string)
357
Arrays.asList("--mode", "plan"), // programArgumentsList
358
null, // parallelism
359
null // jobId
360
);
361
```
362
363
### Processing Response Bodies
364
365
```java
366
// Handle JAR upload response
367
JarUploadResponseBody uploadResponse = uploadHandler.handleRequest(uploadRequest, gateway).get();
368
if ("success".equals(uploadResponse.getStatus())) {
369
String filename = uploadResponse.getFilename();
370
System.out.println("JAR uploaded successfully: " + filename);
371
}
372
373
// Handle JAR run response
374
JarRunResponseBody runResponse = runHandler.handleRequest(runRequest, gateway).get();
375
JobID jobId = runResponse.getJobId();
376
System.out.println("Job submitted with ID: " + jobId);
377
378
// Handle JAR list response
379
JarListInfo listResponse = listHandler.handleRequest(listRequest, gateway).get();
380
for (JarListInfo.JarFileInfo jarInfo : listResponse.getFiles()) {
381
System.out.println("JAR: " + jarInfo.getName() + " (ID: " + jarInfo.getId() + ")");
382
for (JarListInfo.JarEntryInfo entryInfo : jarInfo.getEntry()) {
383
System.out.println(" Entry: " + entryInfo.getName() + " - " + entryInfo.getDescription());
384
}
385
}
386
```
387
388
### JSON Serialization Examples
389
390
The data transfer objects are designed for JSON serialization. Here are examples of the JSON formats:
391
392
#### JAR Run Request JSON
393
394
```json
395
{
396
"entryClassName": "com.example.MyFlinkJob",
397
"programArguments": ["--input", "/path/to/input", "--output", "/path/to/output"],
398
"parallelism": 4,
399
"jobId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
400
"savepointPath": "/path/to/savepoint",
401
"allowNonRestoredState": true
402
}
403
```
404
405
#### JAR Upload Response JSON
406
407
```json
408
{
409
"status": "success",
410
"filename": "my-flink-job.jar"
411
}
412
```
413
414
#### JAR Run Response JSON
415
416
```json
417
{
418
"jobId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
419
}
420
```
421
422
#### JAR List Response JSON
423
424
```json
425
{
426
"address": "http://localhost:8081",
427
"files": [
428
{
429
"id": "example-jar_2.12-1.0.jar",
430
"name": "example-jar_2.12-1.0.jar",
431
"uploaded": 1609459200000,
432
"entry": [
433
{
434
"name": "com.example.WordCount",
435
"description": "Word count streaming job"
436
},
437
{
438
"name": "com.example.WindowSum",
439
"description": "Windowed sum calculation"
440
}
441
]
442
}
443
]
444
}
445
```
446
447
### Validation and Error Handling
448
449
Data transfer objects include built-in validation for common scenarios:
450
451
```java
452
// Validation example
453
JarRunRequestBody request = new JarRunRequestBody();
454
455
// Validate required fields
456
if (request.getEntryClassName() == null || request.getEntryClassName().isEmpty()) {
457
throw new BadRequestException("Entry class name is required");
458
}
459
460
// Validate parallelism
461
Integer parallelism = request.getParallelism();
462
if (parallelism != null && parallelism <= 0) {
463
throw new BadRequestException("Parallelism must be positive");
464
}
465
466
// Validate program arguments
467
List<String> args = request.getProgramArguments();
468
if (args != null) {
469
for (String arg : args) {
470
if (arg == null) {
471
throw new BadRequestException("Program arguments cannot contain null values");
472
}
473
}
474
}
475
```
476
477
### Builder Pattern Support
478
479
For complex request construction, consider using builder patterns:
480
481
```java
482
// Custom builder for complex requests
483
public class JarRunRequestBuilder {
484
private JarRunRequestBody request = new JarRunRequestBody();
485
486
public JarRunRequestBuilder entryClass(String className) {
487
request.setEntryClassName(className);
488
return this;
489
}
490
491
public JarRunRequestBuilder parallelism(int parallelism) {
492
request.setParallelism(parallelism);
493
return this;
494
}
495
496
public JarRunRequestBuilder args(String... args) {
497
request.setProgramArguments(Arrays.asList(args));
498
return this;
499
}
500
501
public JarRunRequestBuilder savepoint(String path, boolean allowNonRestored) {
502
request.setSavepointPath(path);
503
request.setAllowNonRestoredState(allowNonRestored);
504
return this;
505
}
506
507
public JarRunRequestBody build() {
508
return request;
509
}
510
}
511
512
// Usage
513
JarRunRequestBody request = new JarRunRequestBuilder()
514
.entryClass("com.example.MyJob")
515
.parallelism(8)
516
.args("--input", "/data/input", "--output", "/data/output")
517
.savepoint("/checkpoints/savepoint-123", true)
518
.build();
519
```
520
521
These data transfer objects provide a complete, type-safe foundation for all REST API communication in the Flink web interface.