org.apache.oozie.client
Class OozieClient

java.lang.Object
  org.apache.oozie.client.OozieClient

Direct Known Subclasses:

XOozieClient

public class OozieClient
extends Object

Client API to submit and manage Oozie workflow jobs against an Oozie intance.

This class is thread safe.

Syntax for filter for the getJobsInfo(String) getJobsInfo(String, int, int) methods: [NAME=VALUE][;NAME=VALUE]*.

Valid filter names are:

• name: the workflow application name from the workflow definition.
• user: the user that submitted the job.
• group: the group for the job.
• status: the status of the job.

The query will do an AND among all the filter names. The query will do an OR among all the filter values for the same name. Multiple values must be specified as different name value pairs.

Nested Class Summary

protected class	OozieClient.ClientCallable<T>
static class	OozieClient.SYSTEM_MODE

Field Summary

static String	ACTION_MAX_RETRIES
static String	ACTION_NOTIFICATION_URL
static String	ACTION_RETRY_INTERVAL
static String	APP_PATH
static String	BUNDLE_APP_PATH
static String	BUNDLE_ID
static String	CHANGE_VALUE_CONCURRENCY
static String	CHANGE_VALUE_ENDTIME
static String	CHANGE_VALUE_PAUSETIME
static String	COORD_ACTION_NOTIFICATION_URL
static String	COORDINATOR_APP_PATH
int	debugMode debugMode =0 means no debugging.
static String	EXTERNAL_ID
static String	FILTER_APPNAME
static String	FILTER_FREQUENCY
static String	FILTER_GROUP
static String	FILTER_ID
static String	FILTER_JOBID
static String	FILTER_NAME
static String	FILTER_STATUS
static String	FILTER_UNIT
static String	FILTER_USER
static String	GROUP_NAME Deprecated.
static String	JOB_ACL
static String	LIBPATH
static String	LOG_TOKEN
static String	RERUN_FAIL_NODES
static String	RERUN_SKIP_NODES
static String	USE_SYSTEM_LIBPATH
static String	USER_NAME
static String	WORKFLOW_NOTIFICATION_URL
static long	WS_PROTOCOL_VERSION
static long	WS_PROTOCOL_VERSION_0

Constructor Summary

protected	OozieClient()
	OozieClient(String oozieUrl) Create a Workflow client instance.

Method Summary

void	change(String jobId, String changeValue) Change a coordinator job.
Properties	createConfiguration() Create an empty configuration with just the USER_NAME set to the JVM user name.
protected HttpURLConnection	createConnection(URL url, String method) Create http connection to oozie server.
static <T> T	doAs(String userName, Callable<T> callable) Allows to impersonate other users in the Oozie server.
String	dryrun(Properties conf) dryrun for a given job
List<BulkResponse>	getBulkInfo(String filter, int start, int len)
BundleJob	getBundleJobInfo(String jobId) Get the info of a bundle job.
List<BundleJob>	getBundleJobsInfo(String filter, int start, int len) Return the info of the bundle jobs that match the filter.
String	getClientBuildVersion() Return the Oozie client build version.
CoordinatorAction	getCoordActionInfo(String actionId) Get the info of a coordinator action.
CoordinatorJob	getCoordJobInfo(String jobId) Get the info of a coordinator job.
CoordinatorJob	getCoordJobInfo(String jobId, String filter, int start, int len) Get the info of a coordinator job and subset actions.
List<CoordinatorJob>	getCoordJobsInfo(String filter, int start, int len) Return the info of the coordinator jobs that match the filter.
int	getDebugMode()
String	getHeader(String name) Get the value of a set HTTP header from the workflow instance.
Iterator<String>	getHeaderNames() Return an iterator with all the header names set in the workflow instance.
Map<String,String>	getHeaders() Get the set HTTP header
String	getJobDefinition(String jobId) Get the definition of a workflow job.
String	getJobId(String externalId) Return the workflow job Id for an external Id.
WorkflowJob	getJobInfo(String jobId) Get the info of a workflow job.
WorkflowJob	getJobInfo(String jobId, int start, int len) Get the info of a workflow job and subset actions.
String	getJobLog(String jobId) Get the log of a workflow job.
void	getJobLog(String jobId, String logRetrievalType, String logRetrievalScope, PrintStream ps) Get the log of a job.
List<WorkflowJob>	getJobsInfo(String filter) Return the info of the workflow jobs that match the filter.
List<WorkflowJob>	getJobsInfo(String filter, int start, int len) Return the info of the workflow jobs that match the filter.
String	getOozieUrl() Return the Oozie URL of the workflow client instance.
String	getProtocolUrl() Return the Oozie URL used by the client and server for WS communications.
List<String>	getQueueDump() Return the Oozie queue's commands' dump
String	getServerBuildVersion() Return the Oozie server build version.
void	getSlaInfo(int start, int len, String filter) Print sla info about coordinator and workflow jobs and actions.
OozieClient.SYSTEM_MODE	getSystemMode() Returns if Oozie is in safe mode or not.
WorkflowAction	getWorkflowActionInfo(String actionId) Get the info of a workflow action.
void	kill(String jobId) Kill a workflow job.
static String	notEmpty(String str, String name) Check if the string is not null or not empty.
static <T> T	notNull(T obj, String name) Check if the object is not null.
void	removeHeader(String name) Remove a HTTP header from the workflow client instance.
void	reRun(String jobId, Properties conf) Rerun a workflow job.
Void	reRunBundle(String jobId, String coordScope, String dateScope, boolean refresh, boolean noCleanup) Rerun bundle coordinators.
List<CoordinatorAction>	reRunCoord(String jobId, String rerunType, String scope, boolean refresh, boolean noCleanup) Rerun coordinator actions.
void	resume(String jobId) Resume a workflow job.
String	run(Properties conf) Submit and start a workflow job.
void	setDebugMode(int debugMode) Set debug mode.
void	setHeader(String name, String value) Set a HTTP header to be used in the WS requests by the workflow instance.
void	setSystemMode(OozieClient.SYSTEM_MODE status) Enable or disable safe mode.
void	start(String jobId) Start a workflow job.
String	submit(Properties conf) Submit a workflow job.
void	suspend(String jobId) Suspend a workflow job.
void	validateWSVersion() Validate that the Oozie client and server instances are protocol compatible.
void	writeToXml(Properties props, OutputStream out)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

WS_PROTOCOL_VERSION_0

public static final long WS_PROTOCOL_VERSION_0

See Also:

Constant Field Values

WS_PROTOCOL_VERSION

public static final long WS_PROTOCOL_VERSION

See Also:

Constant Field Values

USER_NAME

public static final String USER_NAME

See Also:

Constant Field Values

GROUP_NAME

@Deprecated
public static final String GROUP_NAME

Deprecated.

See Also:

Constant Field Values

JOB_ACL

public static final String JOB_ACL

See Also:

Constant Field Values

APP_PATH

public static final String APP_PATH

See Also:

Constant Field Values

COORDINATOR_APP_PATH

public static final String COORDINATOR_APP_PATH

See Also:

Constant Field Values

BUNDLE_APP_PATH

public static final String BUNDLE_APP_PATH

See Also:

Constant Field Values

BUNDLE_ID

public static final String BUNDLE_ID

See Also:

Constant Field Values

EXTERNAL_ID

public static final String EXTERNAL_ID

See Also:

Constant Field Values

WORKFLOW_NOTIFICATION_URL

public static final String WORKFLOW_NOTIFICATION_URL

See Also:

Constant Field Values

ACTION_NOTIFICATION_URL

public static final String ACTION_NOTIFICATION_URL

See Also:

Constant Field Values

COORD_ACTION_NOTIFICATION_URL

public static final String COORD_ACTION_NOTIFICATION_URL

See Also:

Constant Field Values

RERUN_SKIP_NODES

public static final String RERUN_SKIP_NODES

See Also:

Constant Field Values

RERUN_FAIL_NODES

public static final String RERUN_FAIL_NODES

See Also:

Constant Field Values

LOG_TOKEN

public static final String LOG_TOKEN

See Also:

Constant Field Values

ACTION_MAX_RETRIES

public static final String ACTION_MAX_RETRIES

See Also:

Constant Field Values

ACTION_RETRY_INTERVAL

public static final String ACTION_RETRY_INTERVAL

See Also:

Constant Field Values

FILTER_USER

public static final String FILTER_USER

See Also:

Constant Field Values

FILTER_GROUP

public static final String FILTER_GROUP

See Also:

Constant Field Values

FILTER_NAME

public static final String FILTER_NAME

See Also:

Constant Field Values

FILTER_STATUS

public static final String FILTER_STATUS

See Also:

Constant Field Values

FILTER_FREQUENCY

public static final String FILTER_FREQUENCY

See Also:

Constant Field Values

FILTER_ID

public static final String FILTER_ID

See Also:

Constant Field Values

FILTER_UNIT

public static final String FILTER_UNIT

See Also:

Constant Field Values

FILTER_JOBID

public static final String FILTER_JOBID

See Also:

Constant Field Values

FILTER_APPNAME

public static final String FILTER_APPNAME

See Also:

Constant Field Values

CHANGE_VALUE_ENDTIME

public static final String CHANGE_VALUE_ENDTIME

See Also:

Constant Field Values

CHANGE_VALUE_PAUSETIME

public static final String CHANGE_VALUE_PAUSETIME

See Also:

Constant Field Values

CHANGE_VALUE_CONCURRENCY

public static final String CHANGE_VALUE_CONCURRENCY

See Also:

Constant Field Values

LIBPATH

public static final String LIBPATH

See Also:

Constant Field Values

USE_SYSTEM_LIBPATH

public static final String USE_SYSTEM_LIBPATH

See Also:

Constant Field Values

debugMode

public int debugMode

debugMode =0 means no debugging. > 0 means debugging on.

Constructor Detail

OozieClient

protected OozieClient()

OozieClient

public OozieClient(String oozieUrl)

Create a Workflow client instance.

Parameters:

oozieUrl - URL of the Oozie instance it will interact with.

Method Detail

doAs

public static <T> T doAs(String userName,
                         Callable<T> callable)
              throws Exception

Allows to impersonate other users in the Oozie server. The current user must be configured as a proxyuser in Oozie.

IMPORTANT: impersonation happens only with Oozie client requests done within doAs() calls.

Parameters:

userName - user to impersonate.

callable - callable with OozieClient calls impersonating the specified user.

Returns:

any response returned by the Callable.call() method.

Throws:

Exception - thrown by the Callable.call() method.

getOozieUrl

public String getOozieUrl()

Return the Oozie URL of the workflow client instance.

This URL is the base URL fo the Oozie system, with not protocol versioning.

Returns:

the Oozie URL of the workflow client instance.

getProtocolUrl

public String getProtocolUrl()
                      throws OozieClientException

Return the Oozie URL used by the client and server for WS communications.

This URL is the original URL plus the versioning element path.

Returns:

the Oozie URL used by the client and server for communication.

Throws:

OozieClientException - thrown in the client and the server are not protocol compatible.

getDebugMode

public int getDebugMode()

Returns:

current debug Mode

setDebugMode

public void setDebugMode(int debugMode)

Set debug mode.

Parameters:

debugMode - : 0 means no debugging. > 0 means debugging

validateWSVersion

public void validateWSVersion()
                       throws OozieClientException

Validate that the Oozie client and server instances are protocol compatible.

Throws:

OozieClientException - thrown in the client and the server are not protocol compatible.

createConfiguration

public Properties createConfiguration()

Create an empty configuration with just the USER_NAME set to the JVM user name.

Returns:

an empty configuration.

setHeader

public void setHeader(String name,
                      String value)

Set a HTTP header to be used in the WS requests by the workflow instance.

Parameters:

name - header name.

value - header value.

getHeader

public String getHeader(String name)

Get the value of a set HTTP header from the workflow instance.

Parameters:

name - header name.

Returns:

header value, null if not set.

getHeaders

public Map<String,String> getHeaders()

Get the set HTTP header

Returns:

map of header key and value

removeHeader

public void removeHeader(String name)

Remove a HTTP header from the workflow client instance.

Parameters:

name - header name.

getHeaderNames

public Iterator<String> getHeaderNames()

Return an iterator with all the header names set in the workflow instance.

Returns:

header names.

createConnection

protected HttpURLConnection createConnection(URL url,
                                             String method)
                                      throws IOException,
                                             OozieClientException

Create http connection to oozie server.

Parameters:

url -

method -

Returns:

connection

Throws:

IOException

OozieClientException

writeToXml

public void writeToXml(Properties props,
                       OutputStream out)
                throws IOException

Throws:

IOException

submit

public String submit(Properties conf)
              throws OozieClientException

Submit a workflow job.

Parameters:

conf - job configuration.

Returns:

the job Id.

Throws:

OozieClientException - thrown if the job could not be submitted.

dryrun

public String dryrun(Properties conf)
              throws OozieClientException

dryrun for a given job

Parameters:

conf - Job configuration.

Throws:

OozieClientException

start

public void start(String jobId)
           throws OozieClientException

Start a workflow job.

Parameters:

jobId - job Id.

Throws:

OozieClientException - thrown if the job could not be started.

run

public String run(Properties conf)
           throws OozieClientException

Submit and start a workflow job.

Parameters:

conf - job configuration.

Returns:

the job Id.

Throws:

OozieClientException - thrown if the job could not be submitted.

reRun

public void reRun(String jobId,
                  Properties conf)
           throws OozieClientException

Rerun a workflow job.

Parameters:

jobId - job Id to rerun.

conf - configuration information for the rerun.

Throws:

OozieClientException - thrown if the job could not be started.

suspend

public void suspend(String jobId)
             throws OozieClientException

Suspend a workflow job.

Parameters:

jobId - job Id.

Throws:

OozieClientException - thrown if the job could not be suspended.

resume

public void resume(String jobId)
            throws OozieClientException

Resume a workflow job.

Parameters:

jobId - job Id.

Throws:

OozieClientException - thrown if the job could not be resume.

kill

public void kill(String jobId)
          throws OozieClientException

Kill a workflow job.

Parameters:

jobId - job Id.

Throws:

OozieClientException - thrown if the job could not be killed.

change

public void change(String jobId,
                   String changeValue)
            throws OozieClientException

Change a coordinator job.

Parameters:

jobId - job Id.

changeValue - change value.

Throws:

OozieClientException - thrown if the job could not be changed.

getJobInfo

public WorkflowJob getJobInfo(String jobId)
                       throws OozieClientException

Get the info of a workflow job.

Parameters:

jobId - job Id.

Returns:

the job info.

Throws:

OozieClientException - thrown if the job info could not be retrieved.

getJobInfo

public WorkflowJob getJobInfo(String jobId,
                              int start,
                              int len)
                       throws OozieClientException

Get the info of a workflow job and subset actions.

Parameters:

jobId - job Id.

start - starting index in the list of actions belonging to the job

len - number of actions to be returned

Returns:

the job info.

Throws:

OozieClientException - thrown if the job info could not be retrieved.

getWorkflowActionInfo

public WorkflowAction getWorkflowActionInfo(String actionId)
                                     throws OozieClientException

Get the info of a workflow action.

Parameters:

actionId - Id.

Returns:

the workflow action info.

Throws:

OozieClientException - thrown if the job info could not be retrieved.

getJobLog

public String getJobLog(String jobId)
                 throws OozieClientException

Get the log of a workflow job.

Parameters:

jobId - job Id.

Returns:

the job log.

Throws:

OozieClientException - thrown if the job info could not be retrieved.

getJobLog

public void getJobLog(String jobId,
                      String logRetrievalType,
                      String logRetrievalScope,
                      PrintStream ps)
               throws OozieClientException

Get the log of a job.

Parameters:

jobId - job Id.

logRetrievalType - Based on which filter criteria the log is retrieved

logRetrievalScope - Value for the retrieval type

ps - Printstream of command line interface

Throws:

OozieClientException - thrown if the job info could not be retrieved.

getJobDefinition

public String getJobDefinition(String jobId)
                        throws OozieClientException

Get the definition of a workflow job.

Parameters:

jobId - job Id.

Returns:

the job log.

Throws:

OozieClientException - thrown if the job info could not be retrieved.

getBundleJobInfo

public BundleJob getBundleJobInfo(String jobId)
                           throws OozieClientException

Get the info of a bundle job.

Parameters:

jobId - job Id.

Returns:

the job info.

Throws:

OozieClientException - thrown if the job info could not be retrieved.

getCoordJobInfo

public CoordinatorJob getCoordJobInfo(String jobId)
                               throws OozieClientException

Get the info of a coordinator job.

Parameters:

jobId - job Id.

Returns:

the job info.

Throws:

OozieClientException - thrown if the job info could not be retrieved.

getCoordJobInfo

public CoordinatorJob getCoordJobInfo(String jobId,
                                      String filter,
                                      int start,
                                      int len)
                               throws OozieClientException

Get the info of a coordinator job and subset actions.

Parameters:

jobId - job Id.

filter - filter the status filter

start - starting index in the list of actions belonging to the job

len - number of actions to be returned

Returns:

the job info.

Throws:

OozieClientException - thrown if the job info could not be retrieved.

getCoordActionInfo

public CoordinatorAction getCoordActionInfo(String actionId)
                                     throws OozieClientException

Get the info of a coordinator action.

Parameters:

actionId - Id.

Returns:

the coordinator action info.

Throws:

OozieClientException - thrown if the job info could not be retrieved.

reRunCoord

public List<CoordinatorAction> reRunCoord(String jobId,
                                          String rerunType,
                                          String scope,
                                          boolean refresh,
                                          boolean noCleanup)
                                   throws OozieClientException

Rerun coordinator actions.

Parameters:

jobId - coordinator jobId

rerunType - rerun type 'date' if -date is used, 'action-id' if -action is used

scope - rerun scope for date or actionIds

refresh - true if -refresh is given in command option

noCleanup - true if -nocleanup is given in command option

Throws:

OozieClientException

reRunBundle

public Void reRunBundle(String jobId,
                        String coordScope,
                        String dateScope,
                        boolean refresh,
                        boolean noCleanup)
                 throws OozieClientException

Rerun bundle coordinators.

Parameters:

jobId - bundle jobId

coordScope - rerun scope for coordinator jobs

dateScope - rerun scope for date

refresh - true if -refresh is given in command option

noCleanup - true if -nocleanup is given in command option

Throws:

OozieClientException

getJobsInfo

public List<WorkflowJob> getJobsInfo(String filter,
                                     int start,
                                     int len)
                              throws OozieClientException

Return the info of the workflow jobs that match the filter.

Parameters:

filter - job filter. Refer to the OozieClient for the filter syntax.

start - jobs offset, base 1.

len - number of jobs to return.

Returns:

a list with the workflow jobs info, without node details.

Throws:

OozieClientException - thrown if the jobs info could not be retrieved.

getJobsInfo

public List<WorkflowJob> getJobsInfo(String filter)
                              throws OozieClientException

Return the info of the workflow jobs that match the filter.

It returns the first 100 jobs that match the filter.

Parameters:

filter - job filter. Refer to the OozieClient for the filter syntax.

Returns:

a list with the workflow jobs info, without node details.

Throws:

OozieClientException - thrown if the jobs info could not be retrieved.

getSlaInfo

public void getSlaInfo(int start,
                       int len,
                       String filter)
                throws OozieClientException

Print sla info about coordinator and workflow jobs and actions.

Parameters:

start - starting offset

len - number of results

Throws:

OozieClientException

getJobId

public String getJobId(String externalId)
                throws OozieClientException

Return the workflow job Id for an external Id.

The external Id must have provided at job creation time.

Parameters:

externalId - external Id given at job creation time.

Returns:

the workflow job Id for an external Id, null if none.

Throws:

OozieClientException - thrown if the operation could not be done.

setSystemMode

public void setSystemMode(OozieClient.SYSTEM_MODE status)
                   throws OozieClientException

Enable or disable safe mode. Used by OozieCLI. In safe mode, Oozie would not accept any commands except status command to change and view the safe mode status.

Parameters:

status - true to enable safe mode, false to disable safe mode.

Throws:

OozieClientException - if it fails to set the safe mode status.

getSystemMode

public OozieClient.SYSTEM_MODE getSystemMode()
                                      throws OozieClientException

Returns if Oozie is in safe mode or not.

Returns:

true if safe mode is ON
false if safe mode is OFF

Throws:

OozieClientException - throw if it could not obtain the safe mode status.

getServerBuildVersion

public String getServerBuildVersion()
                             throws OozieClientException

Return the Oozie server build version.

Returns:

the Oozie server build version.

Throws:

OozieClientException - throw if it the server build version could not be retrieved.

getClientBuildVersion

public String getClientBuildVersion()

Return the Oozie client build version.

Returns:

the Oozie client build version.

getCoordJobsInfo

public List<CoordinatorJob> getCoordJobsInfo(String filter,
                                             int start,
                                             int len)
                                      throws OozieClientException

Return the info of the coordinator jobs that match the filter.

Parameters:

filter - job filter. Refer to the OozieClient for the filter syntax.

start - jobs offset, base 1.

len - number of jobs to return.

Returns:

a list with the coordinator jobs info

Throws:

OozieClientException - thrown if the jobs info could not be retrieved.

getBundleJobsInfo

public List<BundleJob> getBundleJobsInfo(String filter,
                                         int start,
                                         int len)
                                  throws OozieClientException

Return the info of the bundle jobs that match the filter.

Parameters:

filter - job filter. Refer to the OozieClient for the filter syntax.

start - jobs offset, base 1.

len - number of jobs to return.

Returns:

a list with the bundle jobs info

Throws:

OozieClientException - thrown if the jobs info could not be retrieved.

getBulkInfo

public List<BulkResponse> getBulkInfo(String filter,
                                      int start,
                                      int len)
                               throws OozieClientException

Throws:

OozieClientException

getQueueDump

public List<String> getQueueDump()
                          throws OozieClientException

Return the Oozie queue's commands' dump

Returns:

the list of strings of callable identification in queue

Throws:

OozieClientException - throw if it the queue dump could not be retrieved.

notEmpty

public static String notEmpty(String str,
                              String name)

Check if the string is not null or not empty.

Parameters:

str -

name -

Returns:

string

notNull

public static <T> T notNull(T obj,
                            String name)

Check if the object is not null.

Type Parameters:

T -

Parameters:

obj -

name -

Returns:

string