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

java.lang.Object
  extended by org.apache.oozie.command.XCommand<T>
All Implemented Interfaces:
Callable<T>, XCallable<T>
Direct Known Subclasses:
BulkJobsXCommand, 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:

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.
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
 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 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

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

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


Copyright © 2012 Apache Software Foundation. All Rights Reserved.