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

Inheritance diagram for OpenGroup::arm40::Provisional::transaction::IArmTransaction:

Public Member Functions
IArmApplication	getApplication ()
	gets the contaning application instance.
IArmCorrelator	getCorrelator ()
	returns a reference to the correlator for the current transaction.
int	getStatus ()
	returns the last status value set on a `stop()` method.
IArmTransactionDefinition	getDefinition ()
	gets the definition metadata for this transaction.
int	bindThread ()
	indicates current thread executing on behalf of this transaction.
long	blocked ()
	indicates that the transaction instance is blocked.
string	getContextURIValue ()
	gets the URI context value.
string	getContextValue (int index)
	gets a context property value.
IArmCorrelator	getParentCorrelator ()
	returns the parent correlator, if set for this transaction.
IArmUser	getUser ()
	returns the `IArmUser` currently asociated with this transaction instance.
bool	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_Renamed)
	sets the URI context value.
int	setContextValue (int index, string value_Renamed)
	sets a context property value.
int	setTraceRequested (bool traceState)
	Toggles request for tracing this transaction.
int	setUser (IArmUser user)
	associates a user to the `IArmTransaction` 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 (IArmCorrelator 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 (IArmBlockCause cause)
	indicates that the transaction instance is blocked.
bool	isAutomaticBindThread ()
	gets the current status of the automatic bind thread.
int	setAutomaticBindThread (bool b)
	indicates that a thread is executing on behalf of a transaction at the moment `start()` executes.

Detailed Description

For most applications, this is the most important of all the ARM classes, and the most frequently used. Many applications operate only on IArmTransaction objects after some initialization (using IArmTransactionFactory,IArmApplicationDefinition, IArmApplication, and IArmTransactionDefinition). Instances of IArmTransaction 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 process 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 IArmTransaction 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 IArmTransactionDefinition used to create the object. Each transaction is scoped by an application instance, represented by IArmApplication.

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.

Note that there are some changes from ARM 3.0:

Descriptive metadata has been moved from IArmTransaction to IArmApplicationDefinition and IArmTransactionDefinition.
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 IArmTransactionFactory.newArmTransaction

Member Function Documentation

int OpenGroup::arm40::Provisional::transaction::IArmTransaction::bindThread ( )

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 OpenGroup.arm40.Provisional.transaction.IArmInterface

long OpenGroup::arm40::Provisional::transaction::IArmTransaction::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 OpenGroup::arm40::Provisional::transaction::IArmTransaction::blocked ( IArmBlockCause cause )

See the description of blocked().

Parameters:

cause

cause describes the cause of the blocking.

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

Since:: ARM 4.1

IArmApplication OpenGroup::arm40::Provisional::transaction::IArmTransaction::getApplication ( )

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

Returns:: the containing IArmApplication.

string OpenGroup::arm40::Provisional::transaction::IArmTransaction::getContextURIValue ( )

See the description of setContextURIValue

Returns:: the URI context value, or null.

string OpenGroup::arm40::Provisional::transaction::IArmTransaction::getContextValue ( int index )

See the description of setContextValue(int, String)

Parameters:

index

index into the context properties array.

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

IArmCorrelator OpenGroup::arm40::Provisional::transaction::IArmTransaction::getCorrelator ( )

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 IArmCorrelator object, but the data within the IArmCorrelator 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.

IArmTransactionDefinition OpenGroup::arm40::Provisional::transaction::IArmTransaction::getDefinition ( )

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

Returns:: the IArmTransactionDefinition metadata.

IArmCorrelator OpenGroup::arm40::Provisional::transaction::IArmTransaction::getParentCorrelator ( )

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 OpenGroup::arm40::Provisional::transaction::IArmTransaction::getStatus ( )

If stop() has never executed, it returns STATUS_INVALID.

Returns:: one of the status values defined in ArmConstants

IArmUser OpenGroup::arm40::Provisional::transaction::IArmTransaction::getUser ( )

See description of setUser(IArmUser)

Returns:: an IArmUser, or null.

bool OpenGroup::arm40::Provisional::transaction::IArmTransaction::isAutomaticBindThread ( )

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

Since:: ARM 4.1

bool OpenGroup::arm40::Provisional::transaction::IArmTransaction::isTraceRequested ( )

The initial trace request state is false. See description of setTraceRequested(bool)

Returns:: the current trace request state.

int OpenGroup::arm40::Provisional::transaction::IArmTransaction::reset ( )

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 OpenGroup.arm40.Provisional.transaction.IArmInterface

int OpenGroup::arm40::Provisional::transaction::IArmTransaction::setArrivalTime ( )

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 OpenGroup.arm40.Provisional.transaction.IArmInterface

int OpenGroup::arm40::Provisional::transaction::IArmTransaction::setAutomaticBindThread ( bool b )

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 OpenGroup.arm40.Provisional.transaction.IArmInterface).

Since:: ARM 4.1

int OpenGroup::arm40::Provisional::transaction::IArmTransaction::setContextURIValue ( string value_Renamed )

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_Renamed

the URI context value.

Returns:: 0 on sucess; otherwise, a non-zero error code is returned (as specified in OpenGroup.arm40.Provisional.transaction.IArmInterface

int OpenGroup::arm40::Provisional::transaction::IArmTransaction::setContextValue	(	int	index,
		string	value_Renamed
	)

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 IArmIdentityProperties for more details). The context property name at the specified array index must have been set to a non-null value when the IArmTransactionDefinition 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_Renamed	the new context property value.

Returns:: 0 on sucess; otherwise, a non-zero error code is returned (as specified in OpenGroup.arm40.Provisional.transaction.IArmInterface

int OpenGroup::arm40::Provisional::transaction::IArmTransaction::setTraceRequested ( bool traceState )

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 OpenGroup.arm40.Provisional.transaction.IArmInterface

int OpenGroup::arm40::Provisional::transaction::IArmTransaction::setUser ( IArmUser user )

This user, represented by an instance of IArmUser, 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 OpenGroup.arm40.Provisional.transaction.IArmInterface

int OpenGroup::arm40::Provisional::transaction::IArmTransaction::start ( )

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 OpenGroup.arm40.Provisional.transaction.IArmInterface

int OpenGroup::arm40::Provisional::transaction::IArmTransaction::start	(	byte[]	parentCorr,
		int	offset
	)

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 OpenGroup.arm40.Provisional.transaction.IArmInterface

int OpenGroup::arm40::Provisional::transaction::IArmTransaction::start ( byte[] parentCorr )

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 OpenGroup.arm40.Provisional.transaction.IArmInterface

int OpenGroup::arm40::Provisional::transaction::IArmTransaction::start ( IArmCorrelator parentCorr )

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 OpenGroup.arm40.Provisional.transaction.IArmInterface

int OpenGroup::arm40::Provisional::transaction::IArmTransaction::stop ( int status )

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 OpenGroup.arm40.Provisional.transaction.IArmInterface

int OpenGroup::arm40::Provisional::transaction::IArmTransaction::stop	(	int	status,
		string	diagnosticDetail
	)

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 OpenGroup.arm40.Provisional.transaction.IArmInterface

int OpenGroup::arm40::Provisional::transaction::IArmTransaction::unbindThread ( )

See decription of bindThread()

Returns:: 0 on sucess; otherwise, a non-zero error code is returned (as specified in OpenGroup.arm40.Provisional.transaction.IArmInterface

int OpenGroup::arm40::Provisional::transaction::IArmTransaction::unblocked ( long blockHandle )

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 OpenGroup.arm40.Provisional.transaction.IArmInterface

int OpenGroup::arm40::Provisional::transaction::IArmTransaction::update ( )

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 OpenGroup.arm40.Provisional.metric.IArmTransactionWithMetrics, a subclass of IArmTransaction, 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 OpenGroup.arm40.Provisional.transaction.IArmInterface

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

opengroup/arm40/provisional/transaction/IArmTransaction.cs

All Classes Namespaces Functions Variables Properties

MyARM - Application Response Measurement (ARM) supported APIs

OpenGroup::arm40::Provisional::transaction::IArmTransaction Interface Reference
[ARM 4.0 Transactions]

Public Member Functions

Detailed Description

Member Function Documentation

MyARM - Application Response Measurement (ARM) supported APIs

OpenGroup::arm40::Provisional::transaction::IArmTransaction Interface Reference [ARM 4.0 Transactions]

Public Member Functions

Detailed Description

Member Function Documentation

OpenGroup::arm40::Provisional::transaction::IArmTransaction Interface Reference
[ARM 4.0 Transactions]