org.arm4.arm40.transaction
Class ArmTransaction

java.lang.Object
  extended by org.arm4.arm40.transaction.ArmInterface
      extended by org.arm4.arm40.transaction.ArmTransaction
All Implemented Interfaces:
ArmInterface, ArmTransaction
Direct Known Subclasses:
ArmTranReport, ArmTransactionWithMetrics

public class ArmTransaction
extends ArmInterface
implements ArmTransaction

For most applications, ArmTransaction is the most important of all the ARM classes, and the most frequently used. Instances of ArmTransaction represent transactions when they execute. A "transaction" is any unit of work that has a clearly understood beginning and ending point, and which begins and ends in the same VM. ArmTransaction is created with the newArmTransaction() method of ArmTransactionFactory.

                ArmConstants.STATUS_ABORT - if the transaction was blocked on a thread.
      ArmConstants.STATUS_FAILED - If the transaction failed.
      ArmConstants.STATUS_GOOD - If a transaction has successfully started or has been updated.
      ArmConstants.STATUS_INVALID - When a transaction is instructed to be stopped, the transaction will be marked invlid and it should never execute again.
      ArmConstants.STATUS_UNKNOWN - When a transaction is first created it will be in an unknown state.
 

Version:
$Revision$ $Date$
Author:
dcarter

Field Summary
static int ARM_SUCCESS
           
protected  ArmApplication m_application
           
protected  long m_arrivalTime
           
protected  java.lang.String m_contextUri
           
protected  java.util.ArrayList m_contextValues
           
protected  ArmCorrelator m_currentCorrelator
           
protected  ArmTransactionDefinition m_definition
           
protected  ArmMetricGroup m_metricGroup
           
protected  ArmCorrelator m_parentCorrelator
           
protected  int m_status
           
protected  boolean m_traceRequested
           
protected  long m_transactionHandle
           
protected  ArmUser m_user
           
 
Fields inherited from class org.arm4.arm40.transaction.ArmInterface
m_errorCode, m_factory
 
Constructor Summary
ArmTransaction(ArmApplication app, ArmTransactionDefinition def, ArmFactory factory)
          Create the ARM Transaction.
ArmTransaction(ArmApplication app, ArmTransactionDefinition def, ArmMetricGroup group, ArmFactory factory)
          Create the ARM Transaction.
 
Method Summary
 int bindThread()
          indicates current thread executing on behalf of this transaction.
 long blocked()
          indicates that the transaction instance is blocked.
 ArmApplication getApplication()
          gets the contaning application instance.
 java.lang.String getContextURIValue()
          gets the URI context value.
 java.lang.String getContextValue(int index)
          gets a context property value.
 ArmCorrelator getCorrelator()
          returns a reference to the correlator for the current transaction.
 ArmTransactionDefinition getDefinition()
          gets the definition metadata for this transaction.
protected  ArmMetricGroup getMetricGroup()
          Get the metric group.
 ArmCorrelator getParentCorrelator()
          returns the parent correlator, if set for this transaction.
 int getStatus()
          returns the last status value set on a stop() method.
 ArmUser getUser()
          returns the ArmUser currently asociated with this transaction instance.
 boolean isTraceRequested()
          gets the current trace request state.
 int reset()
          Resets a transaction if it is currently executing.
 int setArrivalTime()
          sets the actual transaction start time for the next start().
 int setContextURIValue(java.lang.String value)
          sets the URI context value.
 int setContextValue(int index, java.lang.String value)
          sets a context property value.
 int setCorrelator(ArmCorrelator correlator)
          Set the correlator.
 int setParentCorrelator(ArmCorrelator parent)
          Set the parent correlator.
 int setTraceRequested(boolean traceState)
          Toggles request for tracing this transaction.
 int setUser(ArmUser user)
          associates a user to the ArmTransaction instance.
 int start()
          indicates when a transaction begins.
 int start(ArmCorrelator parentCorr)
          indicates when a transaction begins.
 int start(byte[] parentCorr)
          indicates when a transaction begins.
 int start(byte[] parentCorr, int offset)
          indicates when a transaction begins.
 int stop(int status)
          indicates when a transaction ends and what the status of the transaction was.
 int stop(int status, java.lang.String diagnosticDetail)
          indicates when a transaction ends and what the status of the transaction was.
 int unbindThread()
          indicates current thread not executing on behalf of this transaction any more.
 int unblocked(long blockHandle)
          indicates that the transaction instance is not blocked any more.
 int update()
          provides heartbeat and/or metric value update functionality.
 
Methods inherited from class org.arm4.arm40.transaction.ArmInterface
getErrorCode, getErrorMessage, getFactory, setErrorCode, setFactory
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.opengroup.arm40.transaction.ArmInterface
getErrorCode, getErrorMessage, setErrorCode
 

Field Detail

ARM_SUCCESS

public static final int ARM_SUCCESS
See Also:
Constant Field Values

m_application

protected ArmApplication m_application

m_definition

protected ArmTransactionDefinition m_definition

m_parentCorrelator

protected ArmCorrelator m_parentCorrelator

m_currentCorrelator

protected ArmCorrelator m_currentCorrelator

m_user

protected ArmUser m_user

m_arrivalTime

protected long m_arrivalTime

m_transactionHandle

protected long m_transactionHandle

m_status

protected int m_status

m_traceRequested

protected boolean m_traceRequested

m_contextUri

protected java.lang.String m_contextUri

m_contextValues

protected java.util.ArrayList m_contextValues

m_metricGroup

protected ArmMetricGroup m_metricGroup
Constructor Detail

ArmTransaction

public ArmTransaction(ArmApplication app,
                      ArmTransactionDefinition def,
                      ArmFactory factory)
Create the ARM Transaction.

Parameters:
app -
def -
factory -

ArmTransaction

public ArmTransaction(ArmApplication app,
                      ArmTransactionDefinition def,
                      ArmMetricGroup group,
                      ArmFactory factory)
Create the ARM Transaction.

Parameters:
app -
def -
group -
factory -
Method Detail

bindThread

public int bindThread()
Description copied from interface: ArmTransaction
indicates current thread executing on behalf of this transaction. This method can be called from any thread to indicate that the thread is executing on behalf of the transaction instance. This is useful when multiple threads execute the same logical (ARM) transaction, because instrumentation of resource consumption at the thread level can be more precise. The thread remains bound to this transaction until ArmTransaction.unbindThread() is executed in this thread or stop() or reset() is executed.

Specified by:
bindThread in interface ArmTransaction
Returns:
0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).

blocked

public long blocked()
Description copied from interface: ArmTransaction
indicates that the transaction instance is blocked. Blocked in this context means that the transaction is waiting on an external transaction (which may or may not be instrumented with ARM) or some other event to complete. It has been found useful to separate out this "blocked" time from the elapsed time between the start() and stop(). ArmTransaction.unblocked(long) indicates when the blocking condition has ended. A transaction may be blocked by multiple conditions simultaneously. A "block handle" returned by block() is the input parameter to unblocked() to indicate which blocking condition has ended.

Specified by:
blocked in interface ArmTransaction
Returns:
handle to be passed to a matching unblocked() method call.

getApplication

public ArmApplication getApplication()
Description copied from interface: ArmTransaction
gets the contaning application instance. returns the value passed to the newArmTransaction() method of ArmTransactionFactory.

Specified by:
getApplication in interface ArmTransaction
Returns:
the containing ArmApplication.

getContextURIValue

public java.lang.String getContextURIValue()
Description copied from interface: ArmTransaction
gets the URI context value. See the description of ArmTransaction.getContextURIValue().

Specified by:
getContextURIValue in interface ArmTransaction
Returns:
the URI context value, or null.

getContextValue

public java.lang.String getContextValue(int index)
Description copied from interface: ArmTransaction
gets a context property value. See the description of ArmTransaction.setContextValue(int, String).

Specified by:
getContextValue in interface ArmTransaction
Parameters:
index - index into the context properties array.
Returns:
the context value at index index, or null.

getCorrelator

public ArmCorrelator getCorrelator()
Description copied from interface: ArmTransaction
returns a reference to the correlator for the current transaction. It may be a newly created object. It can be executed anytime after start() is executed. Each time it is executed, it will return the same value until the next stop() or reset() is executed. If it is executed at any other time, it will return an ArmCorrelator object, but the data within the ArmCorrelator object is undefined and should not be used.

Specified by:
getCorrelator in interface ArmTransaction
Returns:
a correlator object. Validity of its content depends on the context of execution, see method description.

getParentCorrelator

public ArmCorrelator getParentCorrelator()
Description copied from interface: ArmTransaction
returns the parent correlator, if set for this transaction. Returns the last value set on a start() method. If no value was set on the start() method, or if start() has never executed, it returns null.

Specified by:
getParentCorrelator in interface ArmTransaction
Returns:
the parent correlator, or null.

getStatus

public int getStatus()
Description copied from interface: ArmTransaction
returns the last status value set on a stop() method. If stop() has never executed, it returns STATUS_INVALID.

Specified by:
getStatus in interface ArmTransaction
Returns:
one of the status values defined in ArmConstants.

getDefinition

public ArmTransactionDefinition getDefinition()
Description copied from interface: ArmTransaction
gets the definition metadata for this transaction. returns the value passed to the newArmTransaction() method of ArmTransactionFactory.

Specified by:
getDefinition in interface ArmTransaction
Returns:
the ArmTransactionDefinition metadata.

getUser

public ArmUser getUser()
Description copied from interface: ArmTransaction
returns the ArmUser currently asociated with this transaction instance. See description of ArmTransaction.setUser(ArmUser).

Specified by:
getUser in interface ArmTransaction
Returns:
an ArmUser, or null.

isTraceRequested

public boolean isTraceRequested()
Description copied from interface: ArmTransaction
gets the current trace request state. The initial trace request state is false. See description of ArmTransaction.setTraceRequested(boolean).

Specified by:
isTraceRequested in interface ArmTransaction
Returns:
the current trace request state.

reset

public int reset()
Description copied from interface: ArmTransaction
Resets a transaction if it is currently executing.

This can be executed at any time. If a transaction is currently executing [start() executed without a matching stop()], the current transaction is discarded and treated as if the start() never executed. If no transaction is currently executing, the state of the object is unchanged. If there is any doubt about the state of an object, reset() gets the object into a known state in which a start() may be executed. reset() clears the arrival time and the current correlator; it does not change traceRequested or any of the context URI, context values, or user.

Specified by:
reset in interface ArmTransaction
Returns:
0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).

setArrivalTime

public int setArrivalTime()
Description copied from interface: ArmTransaction
sets the actual transaction start time for the next start(). This method can be used in situations in which the context of a transaction is not known when the transaction begins to execute, and for which there is a non-trivial delay before the context is known. ARM requires that the full context of a transaction be known when start() is executed (because the correlator is generated at this time). In ARM 2.0 and 3.0 there is no way to capture any time spent processing the transaction before the context is known. ARM 4.0 introduces the concept of an "arrival time". The "arrival time" is when processing of the transaction commenced. By default it is the moment in time when start() executes. If the delay between the start of processing and the execution of start() is significant, the application can capture the arrival time by invoking setArrivalTime(). This establishes a timestamp that will be used at the next start(), after which the value will be reset within the ArmTransaction object. The reset() and stop() methods also clear the value.

Specified by:
setArrivalTime in interface ArmTransaction
Returns:
0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).

setContextURIValue

public int setContextURIValue(java.lang.String value)
Description copied from interface: ArmTransaction
sets the URI context value. ArmTransaction.getContextURIValue() returns the value. In most scenarios, a URI would be used as a transaction identity property or a context property, but not both. The only allowed exception is when the base part of the URI is used as an identity property, and the full URI (e.g., with the parameters) is used as a context property. Any other use of URIs as both identity and context properties is invalid.

Specified by:
setContextURIValue in interface ArmTransaction
Parameters:
value - the URI context value.
Returns:
0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).

setContextValue

public int setContextValue(int index,
                           java.lang.String value)
Description copied from interface: ArmTransaction
sets a context property value. This method sets one of the maximum 20 context properties that may change for each transaction instance. ArmTransaction.getContextValue(int) returns the value. The "name" part is available via getDefinition().getIdentityProperties().getContextName(). The values are position-sensitive - they match the position in the referenced context name array (see the discussion at ArmIdentityProperties for more details). The context property name at the specified array index must have been set to a non-null value when the ArmTransactionDefinition object was created. If the name is null or a zero-length string, both the name and value are ignored. If the value is null or a zero-length string, the meaning is that there is no value for this instance. The value should not contain trailing blank characters or consist of only blank characters.

Specified by:
setContextValue in interface ArmTransaction
Parameters:
index - index into the context properties array.
value - the new context property value.
Returns:
0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).

setTraceRequested

public int setTraceRequested(boolean traceState)
Description copied from interface: ArmTransaction
Toggles request for tracing this transaction. This method is used to suggest or withdraw a suggestion from an application that a transaction be traced. ArmTransaction.isTraceRequested() is used to query the current trace request state. The initial state is false. Once set, it remains in that state until set to a different state.

Specified by:
setTraceRequested in interface ArmTransaction
Parameters:
traceState - trace request state.
Returns:
0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).

setUser

public int setUser(ArmUser user)
Description copied from interface: ArmTransaction
associates a user to the ArmTransaction instance. This user, represented by an instance of ArmUser, is assumed to be the user for all start()/ stop() pairs until the association is changed or cleared.

ArmTransaction.getUser() returns the last value that was set.

Specified by:
setUser in interface ArmTransaction
Parameters:
user - the user to be associated with this transaction instance. When null, clears any existing association to an ArmUser
Returns:
0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).

start

public int start()
Description copied from interface: ArmTransaction
indicates when a transaction begins.

Because the response time depends on when start() executes, it should execute as close to the actual start time as possible. After start() executes, it should not be executed again until reset() or stop() is executed. If start() executes consecutively, the behavior is undefined.

There are four versions of start(), depending on whether a parent correlator is provided, and if one is provided, the format of the input data. The length of the correlator is in the first two bytes of the correlator byte array, with the bytes in network byte order. When the input is a byte array, the length of the array does not matter, as long as it is at least long enough to hold the correlator, based on the two-byte length field.

Specified by:
start in interface ArmTransaction
Returns:
0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).

start

public int start(byte[] parentCorr)
Description copied from interface: ArmTransaction
indicates when a transaction begins. See the description of ArmTransaction.start().

Specified by:
start in interface ArmTransaction
Parameters:
parentCorr - a parent correlator for this transaction, represented as an array of bytes.
Returns:
0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).

start

public int start(byte[] parentCorr,
                 int offset)
Description copied from interface: ArmTransaction
indicates when a transaction begins. See the description of ArmTransaction.start().

Specified by:
start in interface ArmTransaction
Parameters:
parentCorr - a parent correlator for this transaction, represented as an array of bytes.
offset - the offset into byte array parentCorr pointing at the start of the acual correlator data.
Returns:
0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).

start

public int start(ArmCorrelator parentCorr)
Description copied from interface: ArmTransaction
indicates when a transaction begins. See the description of ArmTransaction.start().

Specified by:
start in interface ArmTransaction
Parameters:
parentCorr - a parent correlator object for this transaction.
Returns:
0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).

stop

public int stop(int status)
Description copied from interface: ArmTransaction
indicates when a transaction ends and what the status of the transaction was. Because the response time depends on when stop() executes, it should execute as close to the actual stop time as possible. If stop() is erroneously issued when there is no transaction active [start() issued without a matching stop()], it is ignored.

Specified by:
stop in interface ArmTransaction
Parameters:
status - one of STATUS_ABORT, STATUS_FAILED, STATUS_GOOD, or STATUS_UNKNOWN (all defined in ArmConstants).
Returns:
0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).

stop

public int stop(int status,
                java.lang.String diagnosticDetail)
Description copied from interface: ArmTransaction
indicates when a transaction ends and what the status of the transaction was. This is an optional form of stop() as a way for an application to provide additional diagnostic details when the status is something other than STATUS_GOOD. See the desription of ArmTransaction.stop(int).

Specified by:
stop in interface ArmTransaction
Parameters:
status - one of STATUS_ABORT, STATUS_FAILED, STATUS_GOOD, or STATUS_UNKNOWN (all defined in ArmConstants).
diagnosticDetail - string with additional diagnostic details provided by the application
Returns:
0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).

unbindThread

public int unbindThread()
Description copied from interface: ArmTransaction
indicates current thread not executing on behalf of this transaction any more. See decription of ArmTransaction.bindThread().

Specified by:
unbindThread in interface ArmTransaction
Returns:
0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).

unblocked

public int unblocked(long blockHandle)
Description copied from interface: ArmTransaction
indicates that the transaction instance is not blocked any more. See the description of ArmTransaction.blocked().

Specified by:
unblocked in interface ArmTransaction
Parameters:
blockHandle - handle returned from a previous blocked() method call.
Returns:
0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).

update

public int update()
Description copied from interface: ArmTransaction
provides heartbeat and/or metric value update functionality.

After a start() there can be any number of update() calls until a stop(). If it is executed at any other time, it is ignored. The behavior of update() issued at any other time is undefined. It is used for two purposes:

Specified by:
update in interface ArmTransaction
Returns:
0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).

setParentCorrelator

public int setParentCorrelator(ArmCorrelator parent)
Set the parent correlator.

Parameters:
parent -
Returns:

setCorrelator

public int setCorrelator(ArmCorrelator correlator)
Set the correlator.

Parameters:
correlator -
Returns:

getMetricGroup

protected ArmMetricGroup getMetricGroup()
Get the metric group.

Returns: