org.apache.oozie.client
Class OozieClient

java.lang.Object
  extended by 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:

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_SLA_APPNAME
           
static String FILTER_SLA_ID
           
static String FILTER_SLA_NOMINAL_END
           
static String FILTER_SLA_NOMINAL_START
           
static String FILTER_SLA_PARENT_ID
           
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 OOZIE_SUSPEND_ON_NODES
           
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
           
static long WS_PROTOCOL_VERSION_1
           
 
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
 JMSConnectionInfo getJMSConnectionInfo()
          Get the JMS Connection info
 String getJMSTopicName(String jobId)
          Gets the JMS topic name for a particular job
 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_1

public static final long WS_PROTOCOL_VERSION_1
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

FILTER_SLA_APPNAME

public static final String FILTER_SLA_APPNAME
See Also:
Constant Field Values

FILTER_SLA_ID

public static final String FILTER_SLA_ID
See Also:
Constant Field Values

FILTER_SLA_PARENT_ID

public static final String FILTER_SLA_PARENT_ID
See Also:
Constant Field Values

FILTER_SLA_NOMINAL_START

public static final String FILTER_SLA_NOMINAL_START
See Also:
Constant Field Values

FILTER_SLA_NOMINAL_END

public static final String FILTER_SLA_NOMINAL_END
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

OOZIE_SUSPEND_ON_NODES

public static final String OOZIE_SUSPEND_ON_NODES
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.

getJMSConnectionInfo

public JMSConnectionInfo getJMSConnectionInfo()
                                       throws OozieClientException
Get the JMS Connection info

Returns:
JMSConnectionInfo object
Throws:
OozieClientException

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.

getJMSTopicName

public String getJMSTopicName(String jobId)
                       throws OozieClientException
Gets the JMS topic name for a particular job

Parameters:
jobId - given jobId
Returns:
the JMS topic name
Throws:
OozieClientException

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


Copyright © 2013 Apache Software Foundation. All Rights Reserved.