org.opengroup.arm40.transaction

Interface ArmTransaction

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.

Author: ARM Working Group of The Open Group

Method Summary
intbindThread()
indicates current thread executing on behalf of this transaction.
longblocked()
indicates that the transaction instance is blocked.
ArmApplicationgetApplication()
gets the contaning application instance. returns the value passed to the newArmTransaction() method of ArmTransactionFactory.
StringgetContextURIValue()
gets the URI context value.
StringgetContextValue(int index)
gets a context property value.
ArmCorrelatorgetCorrelator()
returns a reference to the correlator for the current transaction.
ArmTransactionDefinitiongetDefinition()
gets the definition metadata for this transaction. returns the value passed to the newArmTransaction() method of ArmTransactionFactory.
ArmCorrelatorgetParentCorrelator()
returns the parent correlator, if set for this transaction.
intgetStatus()
returns the last status value set on a stop() method.
ArmUsergetUser()
returns the ArmUser currently asociated with this transaction instance.
booleanisTraceRequested()
gets the current trace request state.
intreset()
Resets a transaction if it is currently executing.
intsetArrivalTime()
sets the actual transaction start time for the next start().
intsetContextURIValue(String value)
sets the URI context value. getContextURIValue returns the value.
intsetContextValue(int index, String value)
sets a context property value.
intsetTraceRequested(boolean traceState)
Toggles request for tracing this transaction.
intsetUser(ArmUser user)
associates a user to the ArmTransaction instance.
intstart()
indicates when a transaction begins.
intstart(byte[] parentCorr)
indicates when a transaction begins.
intstart(byte[] parentCorr, int offset)
indicates when a transaction begins.
intstart(ArmCorrelator parentCorr)
indicates when a transaction begins.
intstop(int status)
indicates when a transaction ends and what the status of the transaction was.
intstop(int status, String diagnosticDetail)
indicates when a transaction ends and what the status of the transaction was.
intunbindThread()
indicates current thread not executing on behalf of this transaction any more.
intunblocked(long blockHandle)
indicates that the transaction instance is not blocked any more.
intupdate()
provides heartbeat and/or metric value update functionality.

Method Detail

bindThread

public 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 ArmTransaction 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

public 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(). ArmTransaction 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

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

Returns: the containing ArmApplication.

getContextURIValue

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

Returns: the URI context value, or null.

getContextValue

public String getContextValue(int index)
gets a context property value. See the description of ArmTransaction.

Parameters: index index into the context properties array.

Returns: the context value at index index, or null.

getCorrelator

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

getDefinition

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

Returns: the ArmTransactionDefinition metadata.

getParentCorrelator

public 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

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

getUser

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

Returns: an ArmUser, or null.

isTraceRequested

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

Returns: the current trace request state.

reset

public 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

public 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

public int setContextURIValue(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

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

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

public 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

public 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

public 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

public 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

public 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

public 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

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

public 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

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