org.opengroup.arm40.transaction
Interface ArmTransaction

All Superinterfaces:
ArmInterface
All Known Subinterfaces:
ArmTransactionWithMetrics
All Known Implementing Classes:
ArmTranReport, ArmTranReportWithMetrics, ArmTransaction, ArmTransactionWithMetrics

public interface ArmTransaction
extends ArmInterface

The unit of work representation central to the ARM model.

For most applications, this is the most important of all the ARM classes, and the most frequently used. Many applications operate only on ArmTransaction objects after some initialization (using ArmTransactionFactory,ArmApplicationDefinition, ArmApplication, and ArmTransactionDefinition). 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 Java© Virtual Machine instance. Examples include a remote procedure call, a database transaction, and a batch job. It is not necessary that an ARM transaction implement robust functions such as commit and rollback.

The application creates as many instances as it needs. This will typically be at least as many as the number of transactions that can be executing simultaneously. An application may create a pool of ArmTransaction objects, take one from the pool to use when a transaction starts, and put it back in the pool after the transaction ends for later reuse. Another strategy is to create one instance of each type per thread, which eliminates the need to manage the pool, handle synchronization if the pool is depleted, etc.

The metadata common to all instances is contained in the ArmTransactionDefinition used to create the object. Each transaction is scoped by an application instance, represented by ArmApplication.

The most frequently (and often the only) used methods are start(),getCorrelator(), and stop(). A typical sequence is as follows:

See the description of the individual methods below for details about each method. All methods that return an int are returning an error code that the application may but need not test. Refer to ArmTransactionFactoryand the ARM 4.0 Java Binding Specification for more information about handling errors.

Note that there are some changes from ARM 3.0:

Objects implementing this interface are created using ArmTransactionFactory.newArmTransaction(org.opengroup.arm40.transaction.ArmApplication, org.opengroup.arm40.transaction.ArmTransactionDefinition).

Author:
ARM Working Group of The Open Group

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.
 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 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 interface org.opengroup.arm40.transaction.ArmInterface
getErrorCode, getErrorMessage, setErrorCode
 

Method Detail

bindThread

int bindThread()
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 unbindThread() is executed in this thread or stop() or reset() is executed.

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

blocked

long blocked()
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(). 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.

Returns:
handle to be passed to a matching unblocked() method call.

getApplication

ArmApplication getApplication()
gets the contaning application instance. returns the value passed to the newArmTransaction() method of ArmTransactionFactory.

Returns:
the containing ArmApplication.

getContextURIValue

java.lang.String getContextURIValue()
gets the URI context value. See the description of getContextURIValue().

Returns:
the URI context value, or null.

getContextValue

java.lang.String getContextValue(int index)
gets a context property value. See the description of setContextValue(int, String).

Parameters:
index - index into the context properties array.
Returns:
the context value at index index, or null.

getCorrelator

ArmCorrelator getCorrelator()
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.

Returns:
a correlator object. Validity of its content depends on the context of execution, see method description.

getParentCorrelator

ArmCorrelator getParentCorrelator()
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.

Returns:
the parent correlator, or null.

getStatus

int getStatus()
returns the last status value set on a stop() method. If stop() has never executed, it returns STATUS_INVALID.

Returns:
one of the status values defined in ArmConstants.

getDefinition

ArmTransactionDefinition getDefinition()
gets the definition metadata for this transaction. returns the value passed to the newArmTransaction() method of ArmTransactionFactory.

Returns:
the ArmTransactionDefinition metadata.

getUser

ArmUser getUser()
returns the ArmUser currently asociated with this transaction instance. See description of setUser(ArmUser).

Returns:
an ArmUser, or null.

isTraceRequested

boolean isTraceRequested()
gets the current trace request state. The initial trace request state is false. See description of setTraceRequested(boolean).

Returns:
the current trace request state.

reset

int reset()
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.

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

setArrivalTime

int setArrivalTime()
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.

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

setContextURIValue

int setContextURIValue(java.lang.String value)
sets the URI context value. 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.

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

setContextValue

int setContextValue(int index,
                    java.lang.String value)
sets a context property value. This method sets one of the maximum 20 context properties that may change for each transaction instance. 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.

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

int setTraceRequested(boolean traceState)
Toggles request for tracing this transaction. This method is used to suggest or withdraw a suggestion from an application that a transaction be traced. 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.

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

setUser

int setUser(ArmUser user)
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.

getUser() returns the last value that was set.

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

int start()
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.

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

start

int start(byte[] parentCorr)
indicates when a transaction begins. See the description of start().

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

int start(byte[] parentCorr,
          int offset)
indicates when a transaction begins. See the description of start().

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

int start(ArmCorrelator parentCorr)
indicates when a transaction begins. See the description of start().

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

int stop(int status)
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.

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

int stop(int status,
         java.lang.String diagnosticDetail)
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 stop(int).

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

int unbindThread()
indicates current thread not executing on behalf of this transaction any more. See decription of bindThread().

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

unblocked

int unblocked(long blockHandle)
indicates that the transaction instance is not blocked any more. See the description of blocked().

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

int update()
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:

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