Data Transfer Objects

/**
 * Abstract base request body for JAR operations containing common parameters
 */
public abstract class JarRequestBody implements RequestBody {
    /**
     * Get the main class name for job execution
     * @return fully qualified class name of the job's main method
     */
    public String getEntryClassName();
    
    /**
     * Get program arguments passed to the job's main method
     * @return list of command line arguments
     */
    public List<String> getProgramArgumentsList();
    
    /**
     * Get job parallelism override
     * @return parallelism level or null for default
     */
    public Integer getParallelism();
    
    /**
     * Get the job ID for the execution
     * @return JobID for the execution
     */
    public JobID getJobId();
    
    /**
     * Get Flink configuration overrides
     * @return Configuration object with overrides
     */
    public Configuration getFlinkConfiguration();
}

/**
 * Request body for running JAR files with savepoint and recovery options
 */
public class JarRunRequestBody extends JarRequestBody implements RequestBody {
    /**
     * Whether to allow non-restored state when restoring from savepoint
     * @return true to allow missing state, false to require exact match
     */
    public Boolean getAllowNonRestoredState();
    
    /**
     * Path to savepoint for job restoration
     * @return savepoint path or null for fresh start
     */
    public String getSavepointPath();
    
    /**
     * Recovery claim mode for savepoint restoration
     * @return claim mode enum value
     */
    public RecoveryClaimMode getRecoveryClaimMode();
}

// Create JAR run request
JarRunRequestBody request = new JarRunRequestBody();
request.setEntryClass("com.example.WordCount");
request.setProgramArgs(Arrays.asList("--input", "input.txt", "--output", "output.txt"));
request.setParallelism(4);
request.setSavepointPath("hdfs://savepoints/savepoint-123");
request.setAllowNonRestoredState(false);
request.setRecoveryClaimMode(RecoveryClaimMode.CLAIM);

/**
 * Request body for JAR execution plan generation
 * Inherits all common parameters from JarRequestBody
 */
public class JarPlanRequestBody extends JarRequestBody implements RequestBody {
    // No additional fields - uses inherited entryClass, programArgs, parallelism
}

/**
 * Response for JAR upload operations with upload status
 */
public class JarUploadResponseBody implements ResponseBody {
    /**
     * Create upload response with filename
     * @param filename name of the uploaded JAR file
     */
    public JarUploadResponseBody(String filename);
    
    /**
     * Get the uploaded filename
     * @return filename of uploaded JAR
     */
    public String getFilename();
    
    /**
     * Get upload operation status
     * @return status enum indicating success or failure
     */
    public UploadStatus getStatus();
    
    /**
     * Upload operation status enumeration
     */
    public enum UploadStatus {
        success
    }
}

/**
 * Response for JAR execution operations with job information
 */
public class JarRunResponseBody implements ResponseBody {
    /**
     * Create run response with job ID
     * @param jobId ID of the submitted job
     */
    public JarRunResponseBody(JobID jobId);
    
    /**
     * Get the submitted job ID
     * @return job ID for tracking execution
     */
    public JobID getJobId();
}

/**
 * Response containing list of uploaded JARs with complete metadata
 */
public class JarListInfo implements ResponseBody {
    /**
     * Create JAR list response
     * @param address server address for file access
     * @param jarFileList list of uploaded JAR files with metadata
     */
    public JarListInfo(String address, List<JarFileInfo> jarFileList);
    
    /**
     * Get server address for JAR file access
     * @return base server address
     */
    public String getAddress();
    
    /**
     * Get list of uploaded JAR files
     * @return list of JAR file information objects
     */
    public List<JarFileInfo> getFiles();
    
    /**
     * Individual JAR file metadata with entry point information
     */
    public static class JarFileInfo {
        /**
         * Get unique JAR file identifier
         * @return JAR ID for API operations
         */
        public String getId();
        
        /**
         * Get original JAR filename
         * @return filename as uploaded
         */
        public String getName();
        
        /**
         * Get upload timestamp
         * @return timestamp in milliseconds since epoch
         */
        public long getUploaded();
        
        /**
         * Get list of detected entry points
         * @return list of main classes found in JAR
         */
        public List<JarEntryInfo> getEntry();
    }
    
    /**
     * Entry point information for a main class in the JAR
     */
    public static class JarEntryInfo {
        /**
         * Get fully qualified class name
         * @return class name with package
         */
        public String getName();
        
        /**
         * Get human-readable description of the entry point
         * @return description of what this class does
         */
        public String getDescription();
    }
}

{
  "address": "http://localhost:8081", 
  "files": [
    {
      "id": "jar_12345_MyJob.jar",
      "name": "MyJob.jar",
      "uploaded": 1609459200000,
      "entry": [
        {
          "name": "com.example.WordCount",
          "description": "Word counting example job"
        },
        {
          "name": "com.example.StreamingJob", 
          "description": "Streaming data processing job"
        }
      ]
    }
  ]
}

/**
 * Path parameter for identifying JAR files by unique ID
 */
public class JarIdPathParameter extends MessagePathParameter<String> {
    public static final String KEY = "jarid";
    
    /**
     * Convert and validate JAR ID from URL path
     * @param value raw path parameter value
     * @return validated JAR ID
     * @throws ConversionException if ID format is invalid
     */
    public String convertFromString(String value) throws ConversionException;
    
    /**
     * Get parameter description for API documentation
     * @return human-readable parameter description
     */
    public String getDescription();
}

/**
 * Job parallelism query parameter with validation
 */
public class ParallelismQueryParameter extends MessageQueryParameter<Integer> {
    public static final String KEY = "parallelism";
    
    /**
     * Convert string parallelism value to integer with validation
     * @param value string representation of parallelism
     * @return validated parallelism value
     * @throws ConversionException if value is not a valid positive integer
     */
    public Integer convertStringToValue(String value) throws ConversionException;
}

/**
 * Entry class query parameter for specifying main class
 */
public class EntryClassQueryParameter extends MessageQueryParameter<String> {
    public static final String KEY = "entryClass";
    
    /**
     * Validate fully qualified class name format
     * @param value class name to validate
     * @return validated class name
     * @throws ConversionException if class name format is invalid
     */
    public String convertStringToValue(String value) throws ConversionException;
}

/**
 * Program arguments query parameter supporting multiple values
 */
public class ProgramArgQueryParameter extends MessageQueryParameter<List<String>> {
    public static final String KEY = "programArgs";
    
    /**
     * Parse program arguments from query string
     * @param value comma-separated or repeated query parameter values
     * @return list of program arguments
     * @throws ConversionException if parsing fails
     */
    public List<String> convertStringToValue(String value) throws ConversionException;
}

/**
 * Savepoint path query parameter with path validation
 */
public class SavepointPathQueryParameter extends MessageQueryParameter<String> {
    public static final String KEY = "savepointPath";
    
    /**
     * Validate savepoint path format (file://, hdfs://, s3://, etc.)
     * @param value savepoint path to validate
     * @return validated savepoint path
     * @throws ConversionException if path format is invalid
     */
    public String convertStringToValue(String value) throws ConversionException;
}

/**
 * Boolean parameter for allowing non-restored state during savepoint recovery
 */
public class AllowNonRestoredStateQueryParameter extends MessageQueryParameter<Boolean> {
    public static final String KEY = "allowNonRestoredState";
    
    /**
     * Convert string boolean values (true/false, yes/no, 1/0)
     * @param value string representation of boolean
     * @return boolean value
     * @throws ConversionException if value cannot be parsed as boolean
     */
    public Boolean convertStringToValue(String value) throws ConversionException;
}

/**
 * Generic string query parameter with optional validation
 */
public class StringQueryParameter extends MessageQueryParameter<String> {
    /**
     * Create string query parameter with key and validation
     * @param key parameter name
     * @param description parameter description for documentation
     */
    public StringQueryParameter(String key, String description);
    
    /**
     * Convert and optionally validate string parameter
     * @param value raw parameter value
     * @return validated string value
     * @throws ConversionException if validation fails
     */
    public String convertStringToValue(String value) throws ConversionException;
}

/**
 * Message parameters for JAR run operations
 */
public class JarRunMessageParameters implements MessageParameters<JarRunMessageParameters> {
    /**
     * Get JAR ID path parameter
     * @return JAR ID parameter specification
     */
    public JarIdPathParameter getJarIdPathParameter();
    
    /**
     * Get all query parameters for run operation
     * @return collection of supported query parameters
     */
    public Collection<MessageQueryParameter<?>> getQueryParameters();
}

/**
 * Message parameters for JAR plan operations
 */
public class JarPlanMessageParameters implements MessageParameters<JarPlanMessageParameters> {
    /**
     * Get JAR ID path parameter
     * @return JAR ID parameter specification
     */
    public JarIdPathParameter getJarIdPathParameter();
    
    /**
     * Get all query parameters for plan operation
     * @return collection of supported query parameters
     */
    public Collection<MessageQueryParameter<?>> getQueryParameters();
}

/**
 * Message parameters for JAR delete operations
 */
public class JarDeleteMessageParameters implements MessageParameters<JarDeleteMessageParameters> {
    /**
     * Get JAR ID path parameter
     * @return JAR ID parameter specification
     */
    public JarIdPathParameter getJarIdPathParameter();
}

// Serialize to JSON
ObjectMapper mapper = new ObjectMapper();
JarRunRequestBody request = new JarRunRequestBody();
request.setEntryClass("com.example.Job");
String json = mapper.writeValueAsString(request);

// Deserialize from JSON  
JarRunRequestBody parsed = mapper.readValue(json, JarRunRequestBody.class);

// Validation examples
public class ValidationUtils {
    public static void validateJarRunRequest(JarRunRequestBody request) {
        if (request.getEntryClass() != null && !isValidClassName(request.getEntryClass())) {
            throw new RestHandlerException("Invalid entry class format", HttpResponseStatus.BAD_REQUEST);
        }
        
        if (request.getParallelism() != null && request.getParallelism() <= 0) {
            throw new RestHandlerException("Parallelism must be positive", HttpResponseStatus.BAD_REQUEST);
        }
        
        if (request.getSavepointPath() != null && !isValidPath(request.getSavepointPath())) {
            throw new RestHandlerException("Invalid savepoint path", HttpResponseStatus.BAD_REQUEST);
        }
    }
}

// Programmatic request creation
JarRunRequestBody createRunRequest(String entryClass, int parallelism, String savepointPath) {
    JarRunRequestBody request = new JarRunRequestBody();
    request.setEntryClass(entryClass);
    request.setParallelism(parallelism);
    request.setSavepointPath(savepointPath);
    request.setAllowNonRestoredState(false);
    request.setProgramArgs(Arrays.asList("--arg1", "value1", "--arg2", "value2"));
    return request;
}

// Response processing
public void handleJarListResponse(JarListInfo response) {
    System.out.println("Server address: " + response.getAddress());
    
    for (JarListInfo.JarFileInfo jarFile : response.getFiles()) {
        System.out.println("JAR: " + jarFile.getName() + " (ID: " + jarFile.getId() + ")");
        System.out.println("Uploaded: " + new Date(jarFile.getUploaded()));
        
        for (JarListInfo.JarEntryInfo entry : jarFile.getEntry()) {
            System.out.println("  Entry: " + entry.getName() + " - " + entry.getDescription());
        }
    }
}