XCommand (Apache Oozie Core 4.2.0 API)

java.lang.Object
- org.apache.oozie.command.XCommand<T>

All Implemented Interfaces:

Callable<T>, XCallable<T>

Direct Known Subclasses:

BulkBundleXCommand, BulkCoordXCommand, BulkJobsXCommand, BundleJobChangeXCommand, BundleJobsXCommand, BundleJobXCommand, CoordinatorXCommand, NotificationXCommand, PurgeXCommand, SLAAlertsXCommand, SLAEventsXCommand, StatusTransitXCommand, StatusUpdateXCommand, TransitionXCommand, WorkflowXCommand
```
public abstract class XCommand<T>
extends Object
implements XCallable<T>
```
Base class for synchronous and asynchronous commands.
It enables by API the following pattern:
- single execution: a command instance can be executed only once
- eager data loading: loads data for eager precondition check
- eager precondition check: verify precondition before obtaining lock
- data loading: loads data for precondition check and execution
- precondition check: verifies precondition for execution is still met
- locking: obtains exclusive lock on key before executing the command
- execution: command logic
It has built in instrumentation and logging.

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`DEFAULT_LOCK_TIMEOUT`
`static String`	`DEFAULT_REQUEUE_DELAY`
`protected boolean`	`dryrun`
`protected static EventHandlerService`	`eventService`
`protected Instrumentation`	`instrumentation`
`static String`	`INSTRUMENTATION_GROUP`
`XLog`	`LOG`

Constructor Summary

Constructors
Constructor and Description
`XCommand(String name, String type, int priority)` Create a command.
`XCommand(String name, String type, int priority, boolean dryrun)`

Method Summary

Methods
Modifier and Type	Method and Description
`T`	`call()` Implements the XCommand life-cycle.
`T`	`call(String callerEntityKey)` Call this command synchronously from its caller.
`protected void`	`eagerLoadState()` Load the necessary state to perform an eager precondition check.
`protected void`	`eagerVerifyPrecondition()` Verify the precondition for the command before obtaining a lock.
`protected abstract T`	`execute()` Command execution body.
`protected void`	`executeInterrupts()` Check for the existence of interrupts for the same lock key Execute them if exist.
`long`	`getCreatedTime()` Returns the creation time of the command.
`abstract String`	`getEntityKey()` Return the entity key for the command.
`protected Instrumentation`	`getInstrumentation()` Return the `Instrumentation` instance in use.
`String`	`getKey()` Get command key
`protected long`	`getLockTimeOut()` Return the time out when acquiring a lock.
`XLog`	`getLog()` Get XLog log
`String`	`getName()` Return the command name.
`int`	`getPriority()` Return the priority of the command.
`protected long`	`getRequeueDelay()` Return the delay time for requeue The value is loaded from the Oozie configuration, the property {link #DEFAULT_REQUEUE_DELAY}.
`String`	`getType()` Return the callable type.
`boolean`	`inInterruptMode()`
`protected abstract boolean`	`isLockRequired()` Indicate if the the command requires locking.
`protected boolean`	`isReQueueRequired()` Indicate if the the command requires to requeue itself if the lock is not acquired.
`protected abstract void`	`loadState()` Load the necessary state to perform the precondition check and to execute the command.
`protected void`	`queue(XCommand<?> command)` Queue a command for execution after the current command execution completes.
`protected void`	`queue(XCommand<?> command, long msDelay)` Queue a command for delayed execution after the current command execution completes.
`void`	`resetUsed()`
`void`	`setInterruptMode(boolean mode)` set the mode of execution for the callable.
`protected void`	`setLogInfo()` Set the thread local logInfo with the context of this command and reset log prefix.
`String`	`toString()` String for the command - key
`protected abstract void`	`verifyPrecondition()` Verify the precondition for the command after a lock has been obtain, just before executing the command.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - DEFAULT_LOCK_TIMEOUT
```
public static final String DEFAULT_LOCK_TIMEOUT
```
    See Also:
    Constant Field Values
  - INSTRUMENTATION_GROUP
```
public static final String INSTRUMENTATION_GROUP
```
    See Also:
    Constant Field Values
  - DEFAULT_REQUEUE_DELAY
```
public static final String DEFAULT_REQUEUE_DELAY
```
    See Also:
    Constant Field Values
  - LOG
```
public XLog LOG
```
  - dryrun
```
protected boolean dryrun
```
  - instrumentation
```
protected Instrumentation instrumentation
```
  - eventService
```
protected static EventHandlerService eventService
```
- Constructor Detail
  - XCommand
```
public XCommand(String name,
        String type,
        int priority)
```
    Create a command.
    
    Parameters:
    name - command name.
    type - command type.
    priority - command priority.
  - XCommand
```
public XCommand(String name,
        String type,
        int priority,
        boolean dryrun)
```
    Parameters:
    name - command name.
    type - command type.
    priority - command priority.
    dryrun - indicates if dryrun option is enabled. if enabled bundle will show a diagnostic output without really running the job
- Method Detail
  - setLogInfo
```
protected void setLogInfo()
```
    Set the thread local logInfo with the context of this command and reset log prefix.
  - getName
```
public String getName()
```
    Return the command name.
    
    Specified by:
    
    getName in interface XCallable<T>
    
    Returns:
    the command name.
  - getType
```
public String getType()
```
    Return the callable type.
    The command type is used for concurrency throttling in the CallableQueueService.
    
    Specified by:
    
    getType in interface XCallable<T>
    
    Returns:
    the command type.
  - getPriority
```
public int getPriority()
```
    Return the priority of the command.
    
    Specified by:
    
    getPriority in interface XCallable<T>
    
    Returns:
    the command priority.
  - getCreatedTime
```
public long getCreatedTime()
```
    Returns the creation time of the command.
    
    Specified by:
    
    getCreatedTime in interface XCallable<T>
    
    Returns:
    the command creation time, in milliseconds.
  - queue
```
protected void queue(XCommand<?> command)
```
    Queue a command for execution after the current command execution completes.
    All commands queued during the execution of the current command will be queued for a single serial execution.
    If the command execution throws an exception, no command will be effectively queued.
    
    Parameters:
    command - command to queue.
  - queue
```
protected void queue(XCommand<?> command,
         long msDelay)
```
    Queue a command for delayed execution after the current command execution completes.
    All commands queued during the execution of the current command with the same delay will be queued for a single serial execution.
    If the command execution throws an exception, no command will be effectively queued.
    
    Parameters:
    command - command to queue.
    msDelay - delay in milliseconds.
  - call
```
public final T call()
             throws CommandException
```
    Implements the XCommand life-cycle.
    
    Specified by:
    
    call in interface Callable<T>
    
    Returns:
    the {link #execute} return value.
    
    Throws:
    
    Exception - thrown if the command could not be executed.
    
    CommandException
  - call
```
public final T call(String callerEntityKey)
             throws CommandException
```
    Call this command synchronously from its caller. This benefits faster execution of command lifecycle for control nodes and kicking off subsequent actions
    
    Parameters:
    callerEntityKey -
    
    Returns:
    the {link #execute} return value.
    
    Throws:
    
    CommandException
  - executeInterrupts
```
protected void executeInterrupts()
```
    Check for the existence of interrupts for the same lock key Execute them if exist.
  - getLockTimeOut
```
protected long getLockTimeOut()
```
    Return the time out when acquiring a lock.
    The value is loaded from the Oozie configuration, the property {link #DEFAULT_LOCK_TIMEOUT}.
    Subclasses should override this method if they want to use a different time out.
    
    Returns:
    the lock time out in milliseconds.
  - isLockRequired
```
protected abstract boolean isLockRequired()
```
    Indicate if the the command requires locking.
    Subclasses should override this method if they require locking.
    
    Returns:
    true/false
  - getEntityKey
```
public abstract String getEntityKey()
```
    Return the entity key for the command.
    
    Specified by:
    
    getEntityKey in interface XCallable<T>
    
    Returns:
    the entity key for the command.
  - isReQueueRequired
```
protected boolean isReQueueRequired()
```
    Indicate if the the command requires to requeue itself if the lock is not acquired.
    Subclasses should override this method if they don't want to requeue.
    Default is true.
    
    Returns:
    true/false
  - eagerLoadState
```
protected void eagerLoadState()
                       throws CommandException
```
    Load the necessary state to perform an eager precondition check.
    This implementation does a NOP.
    Subclasses should override this method and load the state needed to do an eager precondition check.
    A trivial implementation is calling {link #loadState}.
    
    Throws:
    
    CommandException
  - eagerVerifyPrecondition
```
protected void eagerVerifyPrecondition()
                                throws CommandException,
                                       PreconditionException
```
    Verify the precondition for the command before obtaining a lock.
    This implementation does a NOP.
    A trivial implementation is calling {link #verifyPrecondition}.
    
    Throws:
    
    CommandException - thrown if the precondition is not met.
    
    PreconditionException
  - loadState
```
protected abstract void loadState()
                           throws CommandException
```
    Load the necessary state to perform the precondition check and to execute the command.
    Subclasses must implement this method and load the state needed to do the precondition check and execute the command.
    
    Throws:
    
    CommandException
  - verifyPrecondition
```
protected abstract void verifyPrecondition()
                                    throws CommandException,
                                           PreconditionException
```
    Verify the precondition for the command after a lock has been obtain, just before executing the command.
    
    Throws:
    
    CommandException - thrown if the precondition is not met.
    
    PreconditionException
  - execute
```
protected abstract T execute()
                      throws CommandException
```
    Command execution body.
    This method will be invoked after the {link #loadState} and {link #verifyPrecondition} methods.
    If the command requires locking, this method will be invoked ONLY if the lock has been acquired.
    
    Returns:
    a return value from the execution of the command, only meaningful if the command is executed synchronously.
    
    Throws:
    
    CommandException - thrown if the command execution failed.
  - getInstrumentation
```
protected Instrumentation getInstrumentation()
```
    Return the Instrumentation instance in use.
    
    Returns:
    the Instrumentation instance in use.
  - resetUsed
```
public void resetUsed()
```
    Parameters:
    used - set false to the used
  - getRequeueDelay
```
protected long getRequeueDelay()
```
    Return the delay time for requeue
    The value is loaded from the Oozie configuration, the property {link #DEFAULT_REQUEUE_DELAY}.
    Subclasses should override this method if they want to use a different requeue delay time
    
    Returns:
    delay time when requeue itself
  - getKey
```
public String getKey()
```
    Get command key
    
    Specified by:
    
    getKey in interface XCallable<T>
    
    Returns:
    command key
  - setInterruptMode
```
public void setInterruptMode(boolean mode)
```
    set the mode of execution for the callable. True if in interrupt, false if not
    
    Specified by:
    
    setInterruptMode in interface XCallable<T>
  - inInterruptMode
```
public boolean inInterruptMode()
```
    Specified by:
    
    inInterruptMode in interface XCallable<T>
    
    Returns:
    the mode of execution. true if it is executed as an Interrupt, false otherwise
  - getLog
```
public XLog getLog()
```
    Get XLog log
    
    Returns:
    XLog
  - toString
```
public String toString()
```
    String for the command - key
    
    Overrides:
    
    toString in class Object
    
    Returns:
    String

Class XCommand<T>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_LOCK_TIMEOUT

INSTRUMENTATION_GROUP

DEFAULT_REQUEUE_DELAY

LOG

dryrun

instrumentation

eventService

Constructor Detail

XCommand

XCommand

Method Detail

setLogInfo

getName

getType

getPriority

getCreatedTime

queue

queue

call

call

executeInterrupts

getLockTimeOut

isLockRequired

getEntityKey

isReQueueRequired

eagerLoadState

eagerVerifyPrecondition

loadState

verifyPrecondition

execute

getInstrumentation

resetUsed

getRequeueDelay

getKey

setInterruptMode

inInterruptMode

getLog

toString