0
# Data Transfer Objects
1

2
Comprehensive request and response models for all REST API operations with proper validation, serialization, and type safety. All DTOs follow consistent patterns and integrate with Flink's REST framework.
3

4
## Capabilities
5

6
### Request Bodies
7

8
Base and specialized request bodies for different JAR operations and API endpoints.
9

10
#### Base JAR Request Body
11

12
```java { .api }
13
/**
14
 * Abstract base request body for JAR operations containing common parameters
15
 */
16
public abstract class JarRequestBody implements RequestBody {
17
    /**
18
     * Get the main class name for job execution
19
     * @return fully qualified class name of the job's main method
20
     */
21
    public String getEntryClassName();
22
    
23
    /**
24
     * Get program arguments passed to the job's main method
25
     * @return list of command line arguments
26
     */
27
    public List<String> getProgramArgumentsList();
28
    
29
    /**
30
     * Get job parallelism override
31
     * @return parallelism level or null for default
32
     */
33
    public Integer getParallelism();
34
    
35
    /**
36
     * Get the job ID for the execution
37
     * @return JobID for the execution
38
     */
39
    public JobID getJobId();
40
    
41
    /**
42
     * Get Flink configuration overrides
43
     * @return Configuration object with overrides
44
     */
45
    public Configuration getFlinkConfiguration();
46
}
47
```
48

49
#### JAR Run Request Body
50

51
```java { .api }
52
/**
53
 * Request body for running JAR files with savepoint and recovery options
54
 */
55
public class JarRunRequestBody extends JarRequestBody implements RequestBody {
56
    /**
57
     * Whether to allow non-restored state when restoring from savepoint
58
     * @return true to allow missing state, false to require exact match
59
     */
60
    public Boolean getAllowNonRestoredState();
61
    
62
    /**
63
     * Path to savepoint for job restoration
64
     * @return savepoint path or null for fresh start
65
     */
66
    public String getSavepointPath();
67
    
68
    /**
69
     * Recovery claim mode for savepoint restoration
70
     * @return claim mode enum value
71
     */
72
    public RecoveryClaimMode getRecoveryClaimMode();
73
}
74
```
75

76
**Usage Example:**
77

78
```java
79
// Create JAR run request
80
JarRunRequestBody request = new JarRunRequestBody();
81
request.setEntryClass("com.example.WordCount");
82
request.setProgramArgs(Arrays.asList("--input", "input.txt", "--output", "output.txt"));
83
request.setParallelism(4);
84
request.setSavepointPath("hdfs://savepoints/savepoint-123");
85
request.setAllowNonRestoredState(false);
86
request.setRecoveryClaimMode(RecoveryClaimMode.CLAIM);
87
```
88

89
#### JAR Plan Request Body
90

91
```java { .api }
92
/**
93
 * Request body for JAR execution plan generation
94
 * Inherits all common parameters from JarRequestBody
95
 */
96
public class JarPlanRequestBody extends JarRequestBody implements RequestBody {
97
    // No additional fields - uses inherited entryClass, programArgs, parallelism
98
}
99
```
100

101
### Response Bodies
102

103
Structured response models for all API operations with consistent error handling and serialization.
104

105
#### JAR Upload Response
106

107
```java { .api }
108
/**
109
 * Response for JAR upload operations with upload status
110
 */
111
public class JarUploadResponseBody implements ResponseBody {
112
    /**
113
     * Create upload response with filename
114
     * @param filename name of the uploaded JAR file
115
     */
116
    public JarUploadResponseBody(String filename);
117
    
118
    /**
119
     * Get the uploaded filename
120
     * @return filename of uploaded JAR
121
     */
122
    public String getFilename();
123
    
124
    /**
125
     * Get upload operation status
126
     * @return status enum indicating success or failure
127
     */
128
    public UploadStatus getStatus();
129
    
130
    /**
131
     * Upload operation status enumeration
132
     */
133
    public enum UploadStatus {
134
        success
135
    }
136
}
137
```
138

139
#### JAR Run Response
140

141
```java { .api }
142
/**
143
 * Response for JAR execution operations with job information
144
 */
145
public class JarRunResponseBody implements ResponseBody {
146
    /**
147
     * Create run response with job ID
148
     * @param jobId ID of the submitted job
149
     */
150
    public JarRunResponseBody(JobID jobId);
151
    
152
    /**
153
     * Get the submitted job ID
154
     * @return job ID for tracking execution
155
     */
156
    public JobID getJobId();
157
}
158
```
159

160
#### JAR List Response
161

162
```java { .api }
163
/**
164
 * Response containing list of uploaded JARs with complete metadata
165
 */
166
public class JarListInfo implements ResponseBody {
167
    /**
168
     * Create JAR list response
169
     * @param address server address for file access
170
     * @param jarFileList list of uploaded JAR files with metadata
171
     */
172
    public JarListInfo(String address, List<JarFileInfo> jarFileList);
173
    
174
    /**
175
     * Get server address for JAR file access
176
     * @return base server address
177
     */
178
    public String getAddress();
179
    
180
    /**
181
     * Get list of uploaded JAR files
182
     * @return list of JAR file information objects
183
     */
184
    public List<JarFileInfo> getFiles();
185
    
186
    /**
187
     * Individual JAR file metadata with entry point information
188
     */
189
    public static class JarFileInfo {
190
        /**
191
         * Get unique JAR file identifier
192
         * @return JAR ID for API operations
193
         */
194
        public String getId();
195
        
196
        /**
197
         * Get original JAR filename
198
         * @return filename as uploaded
199
         */
200
        public String getName();
201
        
202
        /**
203
         * Get upload timestamp
204
         * @return timestamp in milliseconds since epoch
205
         */
206
        public long getUploaded();
207
        
208
        /**
209
         * Get list of detected entry points
210
         * @return list of main classes found in JAR
211
         */
212
        public List<JarEntryInfo> getEntry();
213
    }
214
    
215
    /**
216
     * Entry point information for a main class in the JAR
217
     */
218
    public static class JarEntryInfo {
219
        /**
220
         * Get fully qualified class name
221
         * @return class name with package
222
         */
223
        public String getName();
224
        
225
        /**
226
         * Get human-readable description of the entry point
227
         * @return description of what this class does
228
         */
229
        public String getDescription();
230
    }
231
}
232
```
233

234
**Response Example:**
235

236
```json
237
{
238
  "address": "http://localhost:8081", 
239
  "files": [
240
    {
241
      "id": "jar_12345_MyJob.jar",
242
      "name": "MyJob.jar",
243
      "uploaded": 1609459200000,
244
      "entry": [
245
        {
246
          "name": "com.example.WordCount",
247
          "description": "Word counting example job"
248
        },
249
        {
250
          "name": "com.example.StreamingJob", 
251
          "description": "Streaming data processing job"
252
        }
253
      ]
254
    }
255
  ]
256
}
257
```
258

259
### Message Parameters
260

261
Type-safe path and query parameters for REST endpoints with validation and conversion.
262

263
#### Path Parameters
264

265
```java { .api }
266
/**
267
 * Path parameter for identifying JAR files by unique ID
268
 */
269
public class JarIdPathParameter extends MessagePathParameter<String> {
270
    public static final String KEY = "jarid";
271
    
272
    /**
273
     * Convert and validate JAR ID from URL path
274
     * @param value raw path parameter value
275
     * @return validated JAR ID
276
     * @throws ConversionException if ID format is invalid
277
     */
278
    public String convertFromString(String value) throws ConversionException;
279
    
280
    /**
281
     * Get parameter description for API documentation
282
     * @return human-readable parameter description
283
     */
284
    public String getDescription();
285
}
286
```
287

288
#### Query Parameters
289

290
```java { .api }
291
/**
292
 * Job parallelism query parameter with validation
293
 */
294
public class ParallelismQueryParameter extends MessageQueryParameter<Integer> {
295
    public static final String KEY = "parallelism";
296
    
297
    /**
298
     * Convert string parallelism value to integer with validation
299
     * @param value string representation of parallelism
300
     * @return validated parallelism value
301
     * @throws ConversionException if value is not a valid positive integer
302
     */
303
    public Integer convertStringToValue(String value) throws ConversionException;
304
}
305

306
/**
307
 * Entry class query parameter for specifying main class
308
 */
309
public class EntryClassQueryParameter extends MessageQueryParameter<String> {
310
    public static final String KEY = "entryClass";
311
    
312
    /**
313
     * Validate fully qualified class name format
314
     * @param value class name to validate
315
     * @return validated class name
316
     * @throws ConversionException if class name format is invalid
317
     */
318
    public String convertStringToValue(String value) throws ConversionException;
319
}
320

321
/**
322
 * Program arguments query parameter supporting multiple values
323
 */
324
public class ProgramArgQueryParameter extends MessageQueryParameter<List<String>> {
325
    public static final String KEY = "programArgs";
326
    
327
    /**
328
     * Parse program arguments from query string
329
     * @param value comma-separated or repeated query parameter values
330
     * @return list of program arguments
331
     * @throws ConversionException if parsing fails
332
     */
333
    public List<String> convertStringToValue(String value) throws ConversionException;
334
}
335

336
/**
337
 * Savepoint path query parameter with path validation
338
 */
339
public class SavepointPathQueryParameter extends MessageQueryParameter<String> {
340
    public static final String KEY = "savepointPath";
341
    
342
    /**
343
     * Validate savepoint path format (file://, hdfs://, s3://, etc.)
344
     * @param value savepoint path to validate
345
     * @return validated savepoint path
346
     * @throws ConversionException if path format is invalid
347
     */
348
    public String convertStringToValue(String value) throws ConversionException;
349
}
350

351
/**
352
 * Boolean parameter for allowing non-restored state during savepoint recovery
353
 */
354
public class AllowNonRestoredStateQueryParameter extends MessageQueryParameter<Boolean> {
355
    public static final String KEY = "allowNonRestoredState";
356
    
357
    /**
358
     * Convert string boolean values (true/false, yes/no, 1/0)
359
     * @param value string representation of boolean
360
     * @return boolean value
361
     * @throws ConversionException if value cannot be parsed as boolean
362
     */
363
    public Boolean convertStringToValue(String value) throws ConversionException;
364
}
365

366
/**
367
 * Generic string query parameter with optional validation
368
 */
369
public class StringQueryParameter extends MessageQueryParameter<String> {
370
    /**
371
     * Create string query parameter with key and validation
372
     * @param key parameter name
373
     * @param description parameter description for documentation
374
     */
375
    public StringQueryParameter(String key, String description);
376
    
377
    /**
378
     * Convert and optionally validate string parameter
379
     * @param value raw parameter value
380
     * @return validated string value
381
     * @throws ConversionException if validation fails
382
     */
383
    public String convertStringToValue(String value) throws ConversionException;
384
}
385
```
386

387
### Message Parameters Containers
388

389
```java { .api }
390
/**
391
 * Message parameters for JAR run operations
392
 */
393
public class JarRunMessageParameters implements MessageParameters<JarRunMessageParameters> {
394
    /**
395
     * Get JAR ID path parameter
396
     * @return JAR ID parameter specification
397
     */
398
    public JarIdPathParameter getJarIdPathParameter();
399
    
400
    /**
401
     * Get all query parameters for run operation
402
     * @return collection of supported query parameters
403
     */
404
    public Collection<MessageQueryParameter<?>> getQueryParameters();
405
}
406

407
/**
408
 * Message parameters for JAR plan operations
409
 */
410
public class JarPlanMessageParameters implements MessageParameters<JarPlanMessageParameters> {
411
    /**
412
     * Get JAR ID path parameter
413
     * @return JAR ID parameter specification
414
     */
415
    public JarIdPathParameter getJarIdPathParameter();
416
    
417
    /**
418
     * Get all query parameters for plan operation
419
     * @return collection of supported query parameters
420
     */
421
    public Collection<MessageQueryParameter<?>> getQueryParameters();
422
}
423

424
/**
425
 * Message parameters for JAR delete operations
426
 */
427
public class JarDeleteMessageParameters implements MessageParameters<JarDeleteMessageParameters> {
428
    /**
429
     * Get JAR ID path parameter
430
     * @return JAR ID parameter specification
431
     */
432
    public JarIdPathParameter getJarIdPathParameter();
433
}
434
```
435

436
## Serialization and Validation
437

438
### JSON Serialization
439

440
All DTOs support automatic JSON serialization/deserialization using Jackson:
441

442
```java
443
// Serialize to JSON
444
ObjectMapper mapper = new ObjectMapper();
445
JarRunRequestBody request = new JarRunRequestBody();
446
request.setEntryClass("com.example.Job");
447
String json = mapper.writeValueAsString(request);
448

449
// Deserialize from JSON  
450
JarRunRequestBody parsed = mapper.readValue(json, JarRunRequestBody.class);
451
```
452

453
### Request Validation
454

455
DTOs include built-in validation for common scenarios:
456

457
```java
458
// Validation examples
459
public class ValidationUtils {
460
    public static void validateJarRunRequest(JarRunRequestBody request) {
461
        if (request.getEntryClass() != null && !isValidClassName(request.getEntryClass())) {
462
            throw new RestHandlerException("Invalid entry class format", HttpResponseStatus.BAD_REQUEST);
463
        }
464
        
465
        if (request.getParallelism() != null && request.getParallelism() <= 0) {
466
            throw new RestHandlerException("Parallelism must be positive", HttpResponseStatus.BAD_REQUEST);
467
        }
468
        
469
        if (request.getSavepointPath() != null && !isValidPath(request.getSavepointPath())) {
470
            throw new RestHandlerException("Invalid savepoint path", HttpResponseStatus.BAD_REQUEST);
471
        }
472
    }
473
}
474
```
475

476
## Usage Patterns
477

478
### Creating Request Bodies
479

480
```java
481
// Programmatic request creation
482
JarRunRequestBody createRunRequest(String entryClass, int parallelism, String savepointPath) {
483
    JarRunRequestBody request = new JarRunRequestBody();
484
    request.setEntryClass(entryClass);
485
    request.setParallelism(parallelism);
486
    request.setSavepointPath(savepointPath);
487
    request.setAllowNonRestoredState(false);
488
    request.setProgramArgs(Arrays.asList("--arg1", "value1", "--arg2", "value2"));
489
    return request;
490
}
491
```
492

493
### Processing Response Bodies
494

495
```java
496
// Response processing
497
public void handleJarListResponse(JarListInfo response) {
498
    System.out.println("Server address: " + response.getAddress());
499
    
500
    for (JarListInfo.JarFileInfo jarFile : response.getFiles()) {
501
        System.out.println("JAR: " + jarFile.getName() + " (ID: " + jarFile.getId() + ")");
502
        System.out.println("Uploaded: " + new Date(jarFile.getUploaded()));
503
        
504
        for (JarListInfo.JarEntryInfo entry : jarFile.getEntry()) {
505
            System.out.println("  Entry: " + entry.getName() + " - " + entry.getDescription());
506
        }
507
    }
508
}
509
```
510

511
The DTO system provides comprehensive type safety, validation, and consistent serialization patterns for all REST API operations in the Flink Runtime Web module.