org.apache.oozie.command

Class XCommand<T>

java.lang.Object

org.apache.oozie.command.XCommand<T>

All Implemented Interfaces:

java.util.concurrent.Callable<T>, XCallable<T>

Direct Known Subclasses:

BulkBundleXCommand, BulkCoordXCommand, BulkJobsXCommand, BundleJobChangeXCommand, BundleJobsXCommand, BundleJobXCommand, CoordinatorXCommand, NotificationXCommand, PurgeXCommand, SLAEventsXCommand, StatusTransitXCommand, StatusUpdateXCommand, TransitionXCommand, WorkflowXCommand

public abstract class XCommand<T>
extends java.lang.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 java.lang.String	DEFAULT_LOCK_TIMEOUT
static java.lang.String	DEFAULT_REQUEUE_DELAY
protected boolean	dryrun
protected static EventHandlerService	eventService
protected Instrumentation	instrumentation
static java.lang.String	INSTRUMENTATION_GROUP
XLog	LOG

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
T	call() Implements the XCommand life-cycle.
T	call(java.lang.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 java.lang.String	getEntityKey() Return the entity key for the command.
protected Instrumentation	getInstrumentation() Return the Instrumentation instance in use.
java.lang.String	getKey() Get command key
protected long	getLockTimeOut() Return the time out when acquiring a lock.
XLog	getLog() Get XLog log
java.lang.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}.
java.lang.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.
java.lang.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 java.lang.String DEFAULT_LOCK_TIMEOUT

See Also:

Constant Field Values

INSTRUMENTATION_GROUP

public static final java.lang.String INSTRUMENTATION_GROUP

See Also:

Constant Field Values

DEFAULT_REQUEUE_DELAY

public static final java.lang.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(java.lang.String name,
        java.lang.String type,
        int priority)

Create a command.

Parameters:

name - command name.

type - command type.

priority - command priority.

XCommand

public XCommand(java.lang.String name,
        java.lang.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 java.lang.String getName()

Return the command name.

Specified by:

getName in interface XCallable<T>

Returns:

the command name.

getType

public java.lang.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 java.util.concurrent.Callable<T>

Returns:

the {link #execute} return value.

Throws:

java.lang.Exception - thrown if the command could not be executed.

CommandException

call

public final T call(java.lang.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 java.lang.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 java.lang.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 java.lang.String toString()

String for the command - key

Overrides:

toString in class java.lang.Object

Returns:

String