org.khaleesi.carfield.tools.sparkjobserver.api.ISparkJobServerClient Maven / Gradle / Ivy
Show all versions of spark-job-server-client Show documentation
package org.khaleesi.carfield.tools.sparkjobserver.api;
import java.io.File;
import java.io.InputStream;
import java.util.List;
import java.util.Map;
/**
* A client implements all the Rest APIs described by the
* Spark Job Server (https://github.com/ooyala/spark-jobserver).
*
* @author bluebreezecf
* @since 2014-09-07
*/
public interface ISparkJobServerClient {
/**
* Lists all the information of jars for potential jobs to be running
* in the Spark Cluster behind the Spark Job Server.
*
*
* This method implements the Rest API 'GET /jars' of the
* Spark Job Server.
*
* @return a list containing information of Spark Job jars
* @throws SparkJobServerClientException error occurs when trying to get
* information of spark job jars
*/
List getJars() throws SparkJobServerClientException;
/**
* Uploads a jar containing spark job to the Spark Job Server under
* the given application name.
*
*
* This method implements the Rest API 'POST /jars/<appName>'
* of the Spark Job Server.
*
* @param jarData the instance of InputStream contains the
* contents of the target jar file to be uploaded
* @param appName the application name under which the related Spark Job
* is about to run, meanwhile the application name also be the alias
* name of the uploaded jar file.
* @return true if the operation of uploading is successful, false otherwise
* @throws SparkJobServerClientException if the given parameter jarData or
* appName is null, or error occurs when uploading the related spark job
* jar
*/
boolean uploadSparkJobJar(InputStream jarData, String appName)
throws SparkJobServerClientException;
/**
* Uploads a jar containing spark job to the Spark Job Server under
* the given application name.
*
*
* This method implements the Rest API 'POST /jars/<appName>'
* of the Spark Job Server.
*
* @param jarFile the jar file
* @param appName the application name under which the related Spark Job
* is about to run, meanwhile the application name also be the alias
* name of the uploaded jar file.
* @return true if the operation of uploading is successful, false otherwise
* @throws SparkJobServerClientException if the given parameter jarData or
* appName is null, or error occurs when uploading the related spark job
* jar
*/
boolean uploadSparkJobJar(File jarFile, String appName)
throws SparkJobServerClientException;
/**
* Lists all the contexts available in the Spark Job Server.
*
*
* This method implements the Rest API 'GET /contexts '
* of the Spark Job Server.
*
* @return a list containing names of current contexts
* @throws SparkJobServerClientException error occurs when trying to get
* information of contexts
*/
List getContexts() throws SparkJobServerClientException;
/**
* Creates a new context in the Spark Job Server with the given context name.
*
*
* This method implements the Rest API 'POST /contexts/<name>'
* of the Spark Job Server.
*
* @param contextName the name of the new context to be created, it should be not null
* and should begin with letter.
* @param params a map containing the key-value pairs appended to appoint the context
* settings if there is a need to configure the new created context, or null indicates
* the new context with the default configuration
* @return true if the operation of creating is successful, false it failed to create
* the context because a context with the same name already exists
* @throws SparkJobServerClientException when the given contextName is null or empty string,
* or I/O error occurs while trying to create context in spark job server.
*/
boolean createContext(String contextName, Map params) throws SparkJobServerClientException;
/**
* Delete a context with the given name in the Spark Job Server.
* All the jobs running in it will be stopped consequently.
*
*
* This method implements the Rest API 'DELETE /contexts/<name>'
* of the Spark Job Server.
*
* @param contextName the name of the target context to be deleted, it should be not null
* and should begin with letter.
* @return true if the operation of the deleting is successful, false otherwise
* @throws SparkJobServerClientException when the given contextName is null or empty string,
* or I/O error occurs while trying to delete context in spark job server.
*/
boolean deleteContext(String contextName) throws SparkJobServerClientException;
/**
* Lists the last N jobs in the Spark Job Server.
*
*
* This method implements the Rest API 'GET /jobs' of the Spark
* Job Server.
*
* @return a list containing information of the jobs
* @throws SparkJobServerClientException error occurs when trying to get
* information of jobs
*/
List getJobs() throws SparkJobServerClientException;
/**
* Start a new job with the given parameters.
*
*
* This method implements the Rest API 'POST /jobs' of the Spark
* Job Server.
*
* @param data contains the the data processed by the target job.
*
* If it is null, it means the target spark job doesn't needs any data set
* in the job configuration.
*
* If it is not null, the format should be like a key-value pair, such as
* dataKey=dataValue, what the dataKey is determined by the
* one used in the target spark job main class which is assigned by
* ISparkJobServerClientConstants.PARAM_CLASS_PATH.
* @param params a non-null map containing parameters to start the job.
* the key should be the following ones:
* i. ISparkJobServerClientConstants.PARAM_APP_NAME, necessary
* one and should be one of the existing name in the calling of GET /jars.
* That means the appName is the alias name of the uploaded spark job jars.
*
* ii.ISparkJobServerClientConstants.PARAM_CLASS_PATH, necessary one
*
* iii.ISparkJobServerClientConstants.PARAM_CONTEXT, optional one
*
* iv.ISparkJobServerClientConstants.PARAM_SYNC, optional one
*
* @return the corresponding job status or job result
* @throws SparkJobServerClientException the given parameters exist null or empty value,
* or I/O error occurs when trying to start the new job
*/
SparkJobResult startJob(String data, Map params) throws SparkJobServerClientException;
/**
* Gets the result or status of a specific job in the Spark Job Server.
*
*
* This method implements the Rest API 'GET /jobs/<jobId>'
* of the Spark Job Server.
*
* @param jobId the id of the target job
* @return the corresponding SparkJobResult instance if the job
* with the given jobId exists, or null if there is no corresponding job or
* the target job has no result.
* @throws SparkJobServerClientException error occurs when trying to get
* information of the target job
*/
SparkJobResult getJobResult(String jobId) throws SparkJobServerClientException;
/**
* Gets the job configuration of a specific job.
*
*
* This method implements the Rest API 'GET /jobs/<jobId>/config'
* of the Spark Job Server.
*
* @param jobId the id of the target job
* @return the corresponding SparkJobConfig instance if the job
* with the given jobId exists, or null if there is no corresponding job in
* the spark job server.
* @throws SparkJobServerClientException error occurs when trying to get
* information of the target job configuration
*/
SparkJobConfig getConfig(String jobId) throws SparkJobServerClientException;
}