REST API Specifications

/**
 * REST API specification for JAR file upload endpoint.
 * Defines the contract for POST /jars/upload operations.
 */
public class JarUploadHeaders implements MessageHeaders<EmptyRequestBody, JarUploadResponseBody, EmptyMessageParameters> {
    /**
     * Get the singleton instance of JAR upload headers.
     * 
     * @return The JAR upload headers instance
     */
    public static JarUploadHeaders getInstance();
    
    /**
     * Get the HTTP method for this endpoint.
     * 
     * @return HttpMethodWrapper.POST
     */
    public HttpMethodWrapper getHttpMethod();
    
    /**
     * Get the URL pattern for this endpoint.
     * 
     * @return "/jars/upload"
     */
    public String getTargetRestEndpointURL();
    
    /**
     * Get the request body class.
     * 
     * @return EmptyRequestBody.class
     */
    public Class<EmptyRequestBody> getRequestClass();
    
    /**
     * Get the response body class.
     * 
     * @return JarUploadResponseBody.class
     */
    public Class<JarUploadResponseBody> getResponseClass();
    
    /**
     * Get the message parameters class.
     * 
     * @return EmptyMessageParameters.class
     */
    public Class<EmptyMessageParameters> getUnresolvedMessageParameters();
}

/**
 * REST API specification for JAR execution endpoint.
 * Defines the contract for POST /jars/:jarId/run operations.
 */
public class JarRunHeaders implements MessageHeaders<JarRunRequestBody, JarRunResponseBody, JarRunMessageParameters> {
    /**
     * Get the singleton instance of JAR run headers.
     * 
     * @return The JAR run headers instance
     */
    public static JarRunHeaders getInstance();
    
    /**
     * Get the HTTP method for this endpoint.
     * 
     * @return HttpMethodWrapper.POST
     */
    public HttpMethodWrapper getHttpMethod();
    
    /**
     * Get the URL pattern for this endpoint.
     * 
     * @return "/jars/:jarId/run"
     */
    public String getTargetRestEndpointURL();
    
    /**
     * Get the request body class.
     * 
     * @return JarRunRequestBody.class
     */
    public Class<JarRunRequestBody> getRequestClass();
    
    /**
     * Get the response body class.
     * 
     * @return JarRunResponseBody.class
     */
    public Class<JarRunResponseBody> getResponseClass();
    
    /**
     * Get the message parameters class.
     * 
     * @return JarRunMessageParameters.class
     */
    public Class<JarRunMessageParameters> getUnresolvedMessageParameters();
}

/**
 * REST API specification for JAR listing endpoint.
 * Defines the contract for GET /jars operations.
 */
public class JarListHeaders implements MessageHeaders<EmptyRequestBody, JarListInfo, EmptyMessageParameters> {
    /**
     * Get the singleton instance of JAR list headers.
     * 
     * @return The JAR list headers instance
     */
    public static JarListHeaders getInstance();
    
    /**
     * Get the HTTP method for this endpoint.
     * 
     * @return HttpMethodWrapper.GET
     */
    public HttpMethodWrapper getHttpMethod();
    
    /**
     * Get the URL pattern for this endpoint.
     * 
     * @return "/jars"
     */
    public String getTargetRestEndpointURL();
}

/**
 * REST API specification for JAR deletion endpoint.
 * Defines the contract for DELETE /jars/:jarId operations.
 */
public class JarDeleteHeaders implements MessageHeaders<EmptyRequestBody, EmptyResponseBody, JarDeleteMessageParameters> {
    /**
     * Get the singleton instance of JAR delete headers.
     * 
     * @return The JAR delete headers instance
     */
    public static JarDeleteHeaders getInstance();
    
    /**
     * Get the HTTP method for this endpoint.
     * 
     * @return HttpMethodWrapper.DELETE
     */
    public HttpMethodWrapper getHttpMethod();
    
    /**
     * Get the URL pattern for this endpoint.
     * 
     * @return "/jars/:jarId"
     */
    public String getTargetRestEndpointURL();
}

/**
 * REST API specification for JAR plan retrieval via GET.
 * Defines the contract for GET /jars/:jarId/plan operations.
 */
public class JarPlanGetHeaders implements MessageHeaders<EmptyRequestBody, JobPlanInfo, JarPlanMessageParameters> {
    public static JarPlanGetHeaders getInstance();
    public HttpMethodWrapper getHttpMethod(); // GET
    public String getTargetRestEndpointURL(); // "/jars/:jarId/plan"
}

/**
 * REST API specification for JAR plan generation via POST.
 * Defines the contract for POST /jars/:jarId/plan operations with request body.
 */
public class JarPlanPostHeaders implements MessageHeaders<JarPlanRequestBody, JobPlanInfo, JarPlanMessageParameters> {
    public static JarPlanPostHeaders getInstance();
    public HttpMethodWrapper getHttpMethod(); // POST
    public String getTargetRestEndpointURL(); // "/jars/:jarId/plan"
}

/**
 * Abstract base class for JAR plan API specifications.
 * Provides common functionality for both GET and POST plan endpoints.
 */
public abstract class AbstractJarPlanHeaders implements MessageHeaders {
    /**
     * Get the description of this endpoint.
     * 
     * @return Description string for the plan endpoint
     */
    public String getDescription();
}

/**
 * Path parameter for JAR file identification in REST URLs.
 * Used in endpoints like /jars/:jarId/run, /jars/:jarId/plan, etc.
 */
public class JarIdPathParameter extends MessagePathParameter<String> {
    /**
     * Get the parameter key used in URL templates.
     * 
     * @return "jarId"
     */
    public String getKey();
    
    /**
     * Convert path value to typed parameter.
     * 
     * @param value String value from URL path
     * @return The JAR ID as a string
     */
    public String convertFromString(String value);
    
    /**
     * Convert typed parameter to path value.
     * 
     * @param object The JAR ID object
     * @return String representation for URL path
     */
    public String convertToString(String object);
    
    /**
     * Get the description of this parameter.
     * 
     * @return Description of the JAR ID parameter
     */
    public String getDescription();
}

/**
 * Query parameter for specifying the entry class (main class) of a JAR file.
 * Used in JAR execution and plan generation endpoints.
 */
public class EntryClassQueryParameter extends MessageQueryParameter<String> {
    /**
     * Get the parameter key used in query strings.
     * 
     * @return "entry-class"
     */
    public String getKey();
    
    /**
     * Convert query value to typed parameter.
     * 
     * @param value String value from query string
     * @return The entry class name
     */
    public String convertFromString(String value);
    
    /**
     * Get the description of this parameter.
     * 
     * @return Description of the entry class parameter
     */
    public String getDescription();
    
    /**
     * Check if this parameter is mandatory.
     * 
     * @return false (entry class is optional)
     */
    public boolean isMandatory();
}

/**
 * Query parameter for specifying the parallelism of a Flink job.
 * Used in JAR execution endpoints to override default parallelism.
 */
public class ParallelismQueryParameter extends MessageQueryParameter<Integer> {
    /**
     * Get the parameter key used in query strings.
     * 
     * @return "parallelism"
     */
    public String getKey();
    
    /**
     * Convert query value to typed parameter.
     * 
     * @param value String value from query string
     * @return The parallelism as an integer
     */
    public Integer convertFromString(String value);
    
    /**
     * Get the description of this parameter.
     * 
     * @return Description of the parallelism parameter
     */
    public String getDescription();
    
    /**
     * Check if this parameter is mandatory.
     * 
     * @return false (parallelism is optional)
     */
    public boolean isMandatory();
}

/**
 * Query parameter for passing individual program arguments to JAR execution.
 * Can be specified multiple times to pass multiple arguments.
 */
public class ProgramArgQueryParameter extends MessageQueryParameter<String> {
    public String getKey(); // "program-arg"
    public String convertFromString(String value);
    public String getDescription();
    public boolean isMandatory(); // false
}

/**
 * Query parameter for passing all program arguments as a single string.
 * Arguments are tokenized and passed to the program.
 */
public class ProgramArgsQueryParameter extends MessageQueryParameter<String> {
    public String getKey(); // "program-args"
    public String convertFromString(String value);
    public String getDescription();
    public boolean isMandatory(); // false
}

/**
 * Query parameter for specifying savepoint path for job restoration.
 * Used when starting jobs from a specific savepoint.
 */
public class SavepointPathQueryParameter extends MessageQueryParameter<String> {
    public String getKey(); // "savepointPath"
    public String convertFromString(String value);
    public String getDescription();
    public boolean isMandatory(); // false
}

/**
 * Query parameter for allowing non-restored state when restoring from savepoint.
 * Controls whether jobs can start even if some state cannot be restored.
 */
public class AllowNonRestoredStateQueryParameter extends MessageQueryParameter<Boolean> {
    public String getKey(); // "allowNonRestoredState"
    public Boolean convertFromString(String value);
    public String getDescription();
    public boolean isMandatory(); // false
}

/**
 * Base class for string-based query parameters.
 * Provides common functionality for string parameter handling.
 */
public class StringQueryParameter extends MessageQueryParameter<String> {
    /**
     * Create a string query parameter.
     * 
     * @param key The parameter key
     * @param description Description of the parameter
     */
    public StringQueryParameter(String key, String description);
    
    /**
     * Convert query value to string (identity conversion).
     * 
     * @param value String value from query string
     * @return The same string value
     */
    public String convertFromString(String value);
    
    /**
     * Check if this parameter is mandatory.
     * 
     * @return false (optional by default)
     */
    public boolean isMandatory();
}

/**
 * Base message parameters for JAR-related operations.
 * Provides common parameter handling for JAR endpoints.
 */
public class JarMessageParameters extends MessageParameters {
    /**
     * Get the JAR ID path parameter.
     * 
     * @return JarIdPathParameter instance
     */
    public JarIdPathParameter getJarIdPathParameter();
    
    /**
     * Get all path parameters for this message.
     * 
     * @return Collection of path parameters
     */
    public Collection<MessagePathParameter<?>> getPathParameters();
    
    /**
     * Get all query parameters for this message.
     * 
     * @return Collection of query parameters
     */
    public Collection<MessageQueryParameter<?>> getQueryParameters();
}

/**
 * Message parameters for JAR deletion operations.
 * Includes only the JAR ID path parameter.
 */
public class JarDeleteMessageParameters extends JarMessageParameters {
    // Inherits JAR ID path parameter
}

/**
 * Message parameters for JAR execution operations.
 * Includes JAR ID and optional query parameters for job configuration.
 */
public class JarRunMessageParameters extends JarMessageParameters {
    // Includes parallelism, entry class, program args, savepoint parameters
}

/**
 * Message parameters for JAR plan operations.
 * Includes JAR ID and optional query parameters for plan generation.
 */
public class JarPlanMessageParameters extends JarMessageParameters {
    // Includes entry class and program args parameters
}

import org.apache.flink.runtime.webmonitor.handlers.*;

// Use headers to create type-safe handlers
JarUploadHeaders uploadHeaders = JarUploadHeaders.getInstance();
JarRunHeaders runHeaders = JarRunHeaders.getInstance(); 
JarListHeaders listHeaders = JarListHeaders.getInstance();

// Headers provide compile-time type safety
Class<JarRunRequestBody> requestType = runHeaders.getRequestClass();
Class<JarRunResponseBody> responseType = runHeaders.getResponseClass();
String endpoint = runHeaders.getTargetRestEndpointURL(); // "/jars/:jarId/run"

// Extract and validate parameters from requests
JarRunMessageParameters messageParams = new JarRunMessageParameters();
Collection<MessagePathParameter<?>> pathParams = messageParams.getPathParameters();
Collection<MessageQueryParameter<?>> queryParams = messageParams.getQueryParameters();

// Type-safe parameter access
JarIdPathParameter jarIdParam = messageParams.getJarIdPathParameter();
String jarId = jarIdParam.convertFromString(pathValue);

// Query parameter validation
ParallelismQueryParameter parallelismParam = new ParallelismQueryParameter();
if (!parallelismParam.isMandatory() && queryString.contains("parallelism")) {
    Integer parallelism = parallelismParam.convertFromString(queryValue);
}