IBM Rational Performance Tester SDK

com.ibm.rational.test.lt.kernel.action
Interface IKAction

All Superinterfaces:
ICountable, IKLog, IKSemaphore, ITestExecutionServices, Runnable
All Known Subinterfaces:
ICondition, IContainer, IEngine, IFor, IIf, IKChannel, IKLoadTestSchedule, IKTransaction, IKUserGroup, ILoop, IPacedLoop, IParallel, IWhile
All Known Implementing Classes:
com.ibm.rational.test.lt.kernel.action.impl.Container, com.ibm.rational.test.lt.kernel.action.impl.KAction, KCatchRPTEvent, com.ibm.rational.test.lt.kernel.action.impl.KContainer, com.ibm.rational.test.lt.kernel.action.impl.KScript, LTTestScript

public interface IKAction
extends ICountable, IKLog, IKSemaphore, ITestExecutionServices, Runnable

Defines basic functionality that all Kernel actions should implement.

This interface is the base interface for all Kernel actions. These actions may represent loops, conditions, or other arbitrary code constructs.

Implementing this interface will ensure that the resultant class is capable of being scheduled along with all other "actions" within the Pleiades Kernel.

Basic Design Premise

The action defines the basic interface. At run-time, each action gets assigned to an execution queue. When its turn comes, the action has an execute() method that is called by a Worker thread. During the execution of this method, the method should, in general, provide a result. This could be in the form of a String, an int, or some arbitrary Object about which the caller knows. The resultant value is often used elsewhere in the script.

Containers

Every action is constrained by its IContainer. This container class is the basic unit of scheduling within the Kernel and is also used to share values with other actions.

Execution

When an action begins its execution, it should call the start() method in the base class. When execution has completed, the action should call finish(). If an action needs more time to complete (e.g., in the case of a non-blocking I/O call) but doesn't want to block the queue from executing (which it should be very careful not to do), it should call start() the first time it is called, but not call finish() at the end of the execute() method. This will cause the Kernel to re-queue the action and call the execute() method again after a short time has elapsed. This goes on, ad infinitum, until the action decides that it has completed and calls the finish() method on the action.

An action can determine if it is already running by calling the isRunning() method.

When the top-most parent container completes execution, reset() is called on all the actions in the container and all sub-containers.

Accessing other actions

Every action has a unique name within its container. When the action is added to the container, the uniqueness of the name is confirmed. If the name has not been specified, a unique name will be generated and available via a call to getName(). If the name has been specified, but is not unique, the name will be altered slightly to make it unique.

When another action (within the container) needs to access data provided by another action, it will call the get() method of the parent container (i.e., the container of the action to retrieve).

For example, to access an action specifically named "GetAmazonHomePage", another action in the container could call:

IKAction a = getContainer().get("GetAmazonHomePage");

The action could then request the result string of the object (e.g., the HTML page returned by a HTTP get request) via:

String str = a.getResultString();

The action may not be interested in setting a string result. The action may maintain any object type it chooses (see the documentation for each action) and returns this object through a call to getResultObject(). The object will, of course, need to be type-cast to the proper type.

Reset

All actions need to reset themselves to a reasonable state when a call to reset() is received. Common activities would be to call super.reset() (which should reset the result string and the result integer), reset any result object this action maintains, and reset any variables or counters to a known state.

NOTE: The reset() method will be called on each action as initialization before it is first called by the Kernel.

See Also:
IContainer, IContainer.get(String)

Field Summary
static int ABANDONED
           
static String DP_ENCRYPTED_VALUES_KEY
           
static int EXECUTING
           
static int FINISHED
           
static int HANDLETIMER
           
static int SEMWAIT
           
static int SLEEPING
           
static String[] Status
           
static int UNSTARTED
           
 
Fields inherited from interface com.ibm.rational.test.lt.kernel.logging.IKLog
HISTORY_ALL, HISTORY_NONE, HISTORY_PAGES, HISTORY_REQUESTS, HISTORY_SCHEDULE, LOG_ALL, LOG_CONFIG, LOG_FINE, LOG_FINER, LOG_FINEST, LOG_INFO, LOG_NONE, LOG_SEVERE, LOG_WARNING, STATISTIC_ALL, STATISTIC_NONE, STATISTIC_PAGES
 
Fields inherited from interface com.ibm.rational.test.lt.kernel.services.ITestExecutionServices
STORAGE_LOCAL, STORAGE_USER
 
Method Summary
 void abandon()
          Abandon execution.
 void addEventBehavior(RPTEvent event, RPTEvent behavior)
          This method will allow users to map an RPTEvent to the type of behavior it should throw.
 void blocked()
          Provide an entry point for handling an action that has been in execute() beyond the blockedTimeout limit.
 void execute()
          Execute this action.
 void executeAction()
          Execute this action.
 long executionTime()
          Get the total time executing this action.
 IDataArea findDataArea(String name)
          Get the specified DataArea.
 void finish()
          Indicate that processing has finished for this action.
 long getBlockedTimeout()
          Get time action is permitted to remain in blocked state.
 IHistory getHistory()
          get the execution history to which events should be sent.
 int getHistoryType()
          get the history type for this action.
 String getId()
          Get the ID of this action.
 String getName()
          Get the name of this instance of this action.
 IContainer getParent()
          Get the container object to which this action belongs.
 int getResultInteger()
          Deprecated. 
 Object getResultObject()
          Deprecated. 
 StringBuffer getResultString()
          Deprecated. 
 com.ibm.rational.test.lt.kernel.util.Trinary getRtbEnabled()
          Get the value of the Response Time Breakdown enabled flag.
 IStatTree getStatTree()
          Get the root of the Statistics Tree that contains counters
 boolean getStopRequested()
          Request to stop.
 IKSubsystem getSubsystem(String className)
          Get the named subsystem.
 long getTimeoutDuration()
           
 int getTimeoutScheme()
           
 String getVirtualUserName()
          Get the Virtual User Name.
 Thread getWorkerThread()
          Get the Engine worker thread executing this action.
 boolean hasFinished()
          Has this action already finished?
 boolean hasStarted()
          Has this action been started?
 boolean isRunning()
          Is this action currently running?
 void reset()
          Reset this action.
 void setBlockedTimeout(long l)
          Set amount of time action may remain in blocked state.
 void setDispatchingAction(IKAction action)
          Sets an action as the action that caused dispatching the current action into the main execution queue.
 void setHistory(IHistory history)
          set the current execution history for this action and its offspring
 int setHistoryType(int type)
          set the history type for this action and its offspring.
 void setId(String id)
          Assign an ID to an action.
 void setResultInteger(int integer)
          Deprecated. 
 void setResultObject(Object object)
          Deprecated. 
 void setResultString(String string)
          Deprecated. 
 void setResultString(StringBuffer buffer)
          Deprecated. 
 void setRtbEnabled(boolean f)
          Set the Response Time Breakdown enabled flag
 void setStatTree(IStatTree root)
          Set the root of the Statistics Tree for this action and its offspring
 void start()
          Indicate that processing has begun on this action.
 String status()
          Returns action status.
 void stop()
          Stop this action.
 void stop(long l)
          Stop this action with timeout.
 void stopAction()
          Deprecated.  
 
Methods inherited from interface com.ibm.rational.test.lt.kernel.ICountable
addCounter, getCounter, getCounters, resetCounters
 
Methods inherited from interface com.ibm.rational.test.lt.kernel.logging.IKLog
getHistoryLevel, getHistoryLevel, getLogLevel, getStatisticsLevel, getVirtualUserGUID, log, log, log, log, reportEvent, reportEvent, reportEvent, reportMessage, reportMessage, reportMessage, reportVerdict, reportVerdict, reportVerdict, reportVerdict, reportVerificationPoint, reportVerificationPoint, reportVerificationPoint, reportVerificationPoint, reportVerificationPoint, reportVerificationPoint, wouldARM, wouldLog, wouldReportHistory, wouldReportHistory, wouldReportStatistics
 
Methods inherited from interface com.ibm.rational.test.lt.kernel.action.IKSemaphore
acquire, availablePermits, getQueue, getQueueLength, reducePermits, release, release, toString, tryAcquire, tryAcquire
 
Methods inherited from interface com.ibm.rational.test.lt.kernel.services.ITestExecutionServices
getARM, getLoopControl, getPDLogManager, getStatisticsManager, getTestLogManager, getTime, getTransaction, getValue, setValue
 
Methods inherited from interface java.lang.Runnable
run
 

Field Detail

UNSTARTED

static final int UNSTARTED
See Also:
Constant Field Values

EXECUTING

static final int EXECUTING
See Also:
Constant Field Values

SEMWAIT

static final int SEMWAIT
See Also:
Constant Field Values

SLEEPING

static final int SLEEPING
See Also:
Constant Field Values

HANDLETIMER

static final int HANDLETIMER
See Also:
Constant Field Values

FINISHED

static final int FINISHED
See Also:
Constant Field Values

ABANDONED

static final int ABANDONED
See Also:
Constant Field Values

Status

static final String[] Status

DP_ENCRYPTED_VALUES_KEY

static final String DP_ENCRYPTED_VALUES_KEY
See Also:
Constant Field Values
Method Detail

getResultString

@Deprecated
StringBuffer getResultString()
Deprecated. 

Get the string result.

Note: See the implementing actions for details on the meaning of this result.

Returns:
the string result
Throws:
ActionException - if the action has not been started
See Also:
IKAction.setResultString(String), IKAction.setResultString(StringBuffer), IKAction.getResultInteger(), IKAction.getResultObject()

setResultString

@Deprecated
void setResultString(String string)
Deprecated. 

Set the string result.

Note: See the implementing actions for details on the meaning of this result.

Parameters:
string - the string result
Throws:
ActionException - if the action has not been started
See Also:
IKAction.getResultString(), IKAction.setResultString(StringBuffer)

setResultString

@Deprecated
void setResultString(StringBuffer buffer)
Deprecated. 

Set the string result.

Note: See the implementing actions for details on the meaning of this result.

Parameters:
buffer - the string result
Throws:
ActionException - if the action has not been started
See Also:
IKAction.getResultString(), IKAction.setResultString(String)

getResultInteger

@Deprecated
int getResultInteger()
Deprecated. 

Get the integer result.

Note: See the implementing actions for details on the meaning of this result.

Returns:
the integer result or Integer.MIN_VALUE if not set
Throws:
ActionException - if the action has not been started
See Also:
Integer, IKAction.setResultInteger(int)

setResultInteger

@Deprecated
void setResultInteger(int integer)
Deprecated. 

Set the integer result.

Note: See the implementing actions for details on the meaning of this result.

Parameters:
integer - integer result
Throws:
ActionException - if the action has not been started
See Also:
IKAction.getResultInteger()

getResultObject

@Deprecated
Object getResultObject()
Deprecated. 

Get the "result object".

Note: See the implementing actions for details on the meaning of this result and its type.

Throws:
ActionException - if the action has not been started
See Also:
IKAction.setResultObject(Object)

setResultObject

@Deprecated
void setResultObject(Object object)
Deprecated. 

Set the "result object".

Note: See the implementing actions for details on the meaning of this result.

Throws:
ActionException - if the action has not been started
See Also:
IKAction.getResultObject()

executeAction

void executeAction()
Execute this action.

Called by the kernel when it is time to execute.

In general, this method should not be overridden. If it is, then it must call the superclass to ensure proper processing.

See Also:
IKAction.hasStarted(), IKAction.hasFinished(), IKAction.isRunning(), IKAction.start(), IKAction.finish(), IKAction.execute()

execute

void execute()
Execute this action.

Called indirectly by the kernel when it is time to execute.

If processing is finished for this action, call finish() from this method to indicate.

Note: This method is implemented by the protocol, the code generator, or by the programmer/user creating the script.

See Also:
IKAction.hasStarted(), IKAction.hasFinished(), IKAction.isRunning(), IKAction.start(), IKAction.finish()

stopAction

void stopAction()
Deprecated. 

Stop this action.

Called by the kernel when it is time to stop.

In general, this method should not be overridden. If it is, then it must call the superclass to ensure proper processing.

Remove at Caspian! This is an internal kernel interface. Customers should use stop().

See Also:
IKAction.hasStarted(), IKAction.hasFinished(), IKAction.isRunning(), IKAction.start(), IKAction.finish(), IKAction.execute()

stop

void stop()
Stop this action.

Called indirectly by the kernel when it is time to stop.

Note: This method is implemented by the protocol, the code generator, or by the programmer/user creating the script.

See Also:
IKAction.hasStarted(), IKAction.hasFinished(), IKAction.isRunning(), IKAction.start(), IKAction.finish()

stop

void stop(long l)
Stop this action with timeout.

Parameters:
l - timeout

reset

void reset()
Reset this action.

This method is called by the kernel when the top-most parent container completes. In addition, it is called as an initializer.

Note: if this method is overridden, it should first call super.reset() and then continue its processing.

See Also:
IKAction.hasStarted()

getName

String getName()
Get the name of this instance of this action.

Note: this name is unique amongst the actions within a given container.

Returns:
the name
See Also:
IKAction

getParent

IContainer getParent()
Get the container object to which this action belongs.

Returns:
the parent container for this action

hasStarted

boolean hasStarted()
Has this action been started?

Returns:
true if the action has started
See Also:
IKAction.start(), IKAction.finish()

isRunning

boolean isRunning()
Is this action currently running?

Equivalent to:

(hasStarted() && !hasFinished())

Returns:
true if the action has started but not finished
See Also:
IKAction.start(), IKAction.finish(), IKAction.hasStarted(), IKAction.hasFinished()

hasFinished

boolean hasFinished()
Has this action already finished?

Returns:
true if the action has finished
See Also:
IKAction.start(), IKAction.finish()

start

void start()
Indicate that processing has begun on this action.

Throws:
ActionException - if the action is already started
See Also:
IKAction.execute(), IKAction.finish(), IKAction.isRunning()

finish

void finish()
Indicate that processing has finished for this action.

Note: The implication here is that the action is complete and the container should continue on to the next action in the container.

Throws:
ActionException - if the action has not been started
See Also:
IKAction.execute(), IKAction.start(), IKAction.isRunning()

setId

void setId(String id)
Assign an ID to an action.

Each action should have a unique identifier. One is created for each action when it is created, but the value may be overridden by a client after the action has been instantiated.

Parameters:
id - the ID to assign to this action

getId

String getId()
Get the ID of this action.

Returns:
String the ID

executionTime

long executionTime()
Get the total time executing this action.

Returns:
the time in msecs

getVirtualUserName

String getVirtualUserName()
Get the Virtual User Name.

Returns:
Virtual User name.

getTimeoutDuration

long getTimeoutDuration()

getTimeoutScheme

int getTimeoutScheme()

getStatTree

IStatTree getStatTree()
Get the root of the Statistics Tree that contains counters

Returns:
root of the tree

setStatTree

void setStatTree(IStatTree root)
Set the root of the Statistics Tree for this action and its offspring

Parameters:
root - the statistics tree

getHistory

IHistory getHistory()
get the execution history to which events should be sent.

Returns:
the current execution history

setHistory

void setHistory(IHistory history)
set the current execution history for this action and its offspring

Parameters:
history -

setHistoryType

int setHistoryType(int type)
set the history type for this action and its offspring. The history type is the history level for which events reported by this action are active.

Parameters:
type -
Returns:
the previous value of the history type

getHistoryType

int getHistoryType()
get the history type for this action. The history type is the history level for which events reported by this action are active.

Returns:
int history type

findDataArea

IDataArea findDataArea(String name)
Get the specified DataArea.

Specified by:
findDataArea in interface ITestExecutionServices
Parameters:
name - DataArea name.
Returns:
IDataArea DataArea.

blocked

void blocked()
Provide an entry point for handling an action that has been in execute() beyond the blockedTimeout limit.


getBlockedTimeout

long getBlockedTimeout()
Get time action is permitted to remain in blocked state.

Returns:
Blocked timeout in milliseconds.

setBlockedTimeout

void setBlockedTimeout(long l)
Set amount of time action may remain in blocked state.

Parameters:
l - Blocked timeout value in milliseconds.

getWorkerThread

Thread getWorkerThread()
Get the Engine worker thread executing this action.

Returns:
Engine worker thread.

setRtbEnabled

void setRtbEnabled(boolean f)
Set the Response Time Breakdown enabled flag

Parameters:
f -

getRtbEnabled

com.ibm.rational.test.lt.kernel.util.Trinary getRtbEnabled()
Get the value of the Response Time Breakdown enabled flag. If not set in this action check the parent value. If not set in any ancestor the value will be Trinary.UNKNOWN

Returns:
Trinary

getSubsystem

IKSubsystem getSubsystem(String className)
Get the named subsystem. Subsystems provide long running services to actions. An example would be support for non-blocking work an action wishes to perform.

Returns:
Subsystem

setDispatchingAction

void setDispatchingAction(IKAction action)
Sets an action as the action that caused dispatching the current action into the main execution queue.

Parameters:
action - IKAction

status

String status()
Returns action status. Includes any specific action status or one of these base action status values: Not started Executing Semaphore Wait Sleeping Handle Timer Finished Abandoned

Returns:
String Action status.

getStopRequested

boolean getStopRequested()
Request to stop. Indicates true if an action has been asked to stop.

Returns:
boolean

abandon

void abandon()
Abandon execution. Sets state to ABANDON. Prevents normal finish. An action that is misbehaving can be set to state abandon. If the thread executing the action tries to finish the action normally it will not be allowed to do so. The parent is informed the action has effectively ended.


addEventBehavior

void addEventBehavior(RPTEvent event,
                      RPTEvent behavior)
This method will allow users to map an RPTEvent to the type of behavior it should throw. The behavior could be null, which would mean to ignore the event and continue operating.

Parameters:
event - - the event to look for (vpEvent, connectEvent, things like that)
behavior - - the behavior to perform (stop test, loop, things like that)

IBM Rational Performance Tester SDK

© Copyright IBM Corp. 2012. All rights reserved.