This project has retired. For details please refer to its Attic page.

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

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

All Implemented Interfaces:

Callable<T>, XCallable<T>

Direct Known Subclasses:

BundleJobChangeXCommand, BundleJobsXCommand, BundleJobXCommand, BundlePurgeXCommand, CoordinatorXCommand, SLAEventsXCommand, 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

static String	DEFAULT_LOCK_TIMEOUT
static Long	DEFAULT_REQUEUE_DELAY
protected boolean	dryrun
protected Instrumentation	instrumentation
static String	INSTRUMENTATION_GROUP
XLog	LOG
protected XLog.Info	logInfo

Constructor Summary

XCommand(String name, String type, int priority)
Create a command.

XCommand(String name, String type, int priority, boolean dryrun)

Method Summary

T	call() Implements the XCommand life-cycle.
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.
long	getCreatedTime() Returns the creation time of the command.
protected 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
String	getType() Return the callable type.
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()
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, toString, 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 Long DEFAULT_REQUEUE_DELAY

LOG

public XLog LOG

dryrun

protected boolean dryrun

instrumentation

protected Instrumentation instrumentation

logInfo

protected XLog.Info logInfo

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

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

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

protected abstract String getEntityKey()

Return the entity key for the command.

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

Returns:

delay time when requeue itself

getKey

public String getKey()

Get command key

Specified by:

getKey in interface XCallable<T>

Returns:

command key

getLog

public XLog getLog()

Get XLog log

Returns:

XLog