The unit of work representation central to the ARM model. More...

Inheritance diagram for org.opengroup.arm40.transaction.ArmTransaction:

Public Member Functions
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.
String	getContextURIValue ()
	gets the URI context value.
String	getContextValue (int index)
	gets a context property value.
ArmCorrelator	getCorrelator ()
	returns a reference to the correlator for the current transaction.
ArmCorrelator	getParentCorrelator ()
	returns the parent correlator, if set for this transaction.
int	getStatus ()
	returns the last status value set on a `stop()` method.
ArmTransactionDefinition	getDefinition ()
	gets the definition metadata for this transaction.
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 (String value)
	sets the URI context value.
int	setContextValue (int index, 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 (byte[] parentCorr)
	indicates when a transaction begins.
int	start (byte[] parentCorr, int offset)
	indicates when a transaction begins.
int	start (ArmCorrelator parentCorr)
	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, 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.
long	blocked (ArmBlockCause cause)
	indicates that the transaction instance is blocked.
boolean	isAutomaticBindThread ()
	gets the current status of the automatic bind thread.
int	setAutomaticBindThread (boolean b)
	indicates that a thread is executing on behalf of a transaction at the moment `start()` executes.

Detailed Description

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:

Just prior to executing a transaction, such as a remote procedure call, call start() to signal to ARM that the measurable transaction is beginning. start() causes ARM to capture the current time. If a correlation token was received when your program was invoked, pass it as a parameter on the start().
Just after executing start(), and just prior to executing the transaction, call getCorrelator() to get a correlation token that can be sent along with the other transaction parameters to the receiver. Not all programs use correlators, but their use is highly recommended, because without them, it is usually impossible to drill down to understand the components of a transaction, where they executed, what resources they used, etc.
Execute the transaction (e.g., make the remote procedure call).
As soon as it ends, call stop(), passing a status to indicate whether the transaction succeeded. stop() causes ARM to capture the current time. The response time is determined by calculating the duration between the start() and stop() events.

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:

Descriptive metadata has been moved from ArmTransaction to ArmApplicationDefinition and ArmTransactionDefinition.
Three methods that were in ARM 3.0 are removed. These methods were almost never used. They also placed restrictions on implementations that could be unacceptable because they required an ARM implementation to return a value that had not been provided by the application. They can be contrasted with other getter methods that return data previously set by the application using ARM: getRespTime(),getStopTime(), and getTranHandle().
The return type for stop() is changed from long to int. The long returned in ARM 3.0 was the response time, and the requirement to return it is considered unacceptable. The int return value is an error indicator (if it is negative).

Objects implementing this interface are created using ArmTransactionFactory#newArmTransaction.

Author:: ARM Working Group of The Open Group

Member Function Documentation

int org.opengroup.arm40.transaction.ArmTransaction.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 org.opengroup.arm40.transaction.ArmInterface).

long org.opengroup.arm40.transaction.ArmTransaction.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.

long org.opengroup.arm40.transaction.ArmTransaction.blocked ( ArmBlockCause cause )

indicates that the transaction instance is blocked.

See the description of blocked().

Parameters:

cause

describes the cause of the blocking.

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

Since:: ARM 4.1

ArmApplication org.opengroup.arm40.transaction.ArmTransaction.getApplication ( )

gets the contaning application instance.

returns the value passed to the newArmTransaction() method of ArmTransactionFactory.

Returns:: the containing ArmApplication.

String org.opengroup.arm40.transaction.ArmTransaction.getContextURIValue ( )

gets the URI context value.

See the description of getContextURIValue().

Returns:: the URI context value, or null.

String org.opengroup.arm40.transaction.ArmTransaction.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.

ArmCorrelator org.opengroup.arm40.transaction.ArmTransaction.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.

ArmTransactionDefinition org.opengroup.arm40.transaction.ArmTransaction.getDefinition ( )

gets the definition metadata for this transaction.

returns the value passed to the newArmTransaction() method of ArmTransactionFactory.

Returns:: the ArmTransactionDefinition metadata.

ArmCorrelator org.opengroup.arm40.transaction.ArmTransaction.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.

int org.opengroup.arm40.transaction.ArmTransaction.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.

ArmUser org.opengroup.arm40.transaction.ArmTransaction.getUser ( )

returns the ArmUser currently asociated with this transaction instance.

See description of setUser(ArmUser).

Returns:: an ArmUser, or null.

boolean org.opengroup.arm40.transaction.ArmTransaction.isAutomaticBindThread ( )

gets the current status of the automatic bind thread.

Returns:: the current status of the automatic bind thread flag.

Since:: ARM 4.1

boolean org.opengroup.arm40.transaction.ArmTransaction.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.

int org.opengroup.arm40.transaction.ArmTransaction.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 org.opengroup.arm40.transaction.ArmInterface).

int org.opengroup.arm40.transaction.ArmTransaction.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 org.opengroup.arm40.transaction.ArmInterface).

int org.opengroup.arm40.transaction.ArmTransaction.setAutomaticBindThread ( boolean b )

indicates that a thread is executing on behalf of a transaction at the moment start() executes.

It is used in place of bindThread(). The motivation is to avoid needing to make another method call to bindThread() in the common case where each transaction executes as a separate thread. setAutomaticBindThread(false) resets this behavior.

Parameters:

b

new status of the automatic bind thread flag.

Returns:: 0 on success; otherwise, a non-zero error code is returned (as specified in org.opengroup.arm40.transaction.ArmInterface).

Since:: ARM 4.1

int org.opengroup.arm40.transaction.ArmTransaction.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 org.opengroup.arm40.transaction.ArmInterface).

int org.opengroup.arm40.transaction.ArmTransaction.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. 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 org.opengroup.arm40.transaction.ArmInterface).

int org.opengroup.arm40.transaction.ArmTransaction.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 org.opengroup.arm40.transaction.ArmInterface).

int org.opengroup.arm40.transaction.ArmTransaction.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 org.opengroup.arm40.transaction.ArmInterface).

int org.opengroup.arm40.transaction.ArmTransaction.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 org.opengroup.arm40.transaction.ArmInterface).

int org.opengroup.arm40.transaction.ArmTransaction.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 org.opengroup.arm40.transaction.ArmInterface).

int org.opengroup.arm40.transaction.ArmTransaction.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 org.opengroup.arm40.transaction.ArmInterface).

int org.opengroup.arm40.transaction.ArmTransaction.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 org.opengroup.arm40.transaction.ArmInterface).

int org.opengroup.arm40.transaction.ArmTransaction.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 org.opengroup.arm40.transaction.ArmInterface).

int org.opengroup.arm40.transaction.ArmTransaction.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 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 org.opengroup.arm40.transaction.ArmInterface).

int org.opengroup.arm40.transaction.ArmTransaction.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 org.opengroup.arm40.transaction.ArmInterface).

int org.opengroup.arm40.transaction.ArmTransaction.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 org.opengroup.arm40.transaction.ArmInterface).

int org.opengroup.arm40.transaction.ArmTransaction.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:

It serves as a heartbeat to show that a transaction is still executing. This is especially useful if the transaction is a long-running job.
When used with org.opengroup.arm40.metric.ArmTransactionWithMetrics, a subclass of ArmTransaction, any of the metric values can be provided with an update().

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

The documentation for this interface was generated from the following file:

org/opengroup/arm40/transaction/ArmTransaction.java

All Classes Functions Variables

MyARM - Application Response Measurement (ARM) supported APIs

org.opengroup.arm40.transaction.ArmTransaction Interface Reference
[ARM 4.0 Transactions]

Public Member Functions

Detailed Description

Member Function Documentation

MyARM - Application Response Measurement (ARM) supported APIs

org.opengroup.arm40.transaction.ArmTransaction Interface Reference [ARM 4.0 Transactions]

Public Member Functions

Detailed Description

Member Function Documentation

org.opengroup.arm40.transaction.ArmTransaction Interface Reference
[ARM 4.0 Transactions]