Transaction instance for application-based and/or remote time measurement. More...

Inheritance diagram for org.opengroup.arm40.tranreport.ArmTranReport:

Public Member Functions
ArmCorrelator	generateCorrelator ()
	Generates a new correlator for the transaction instance.
ArmApplication	getApplication ()
String	getContextURIValue ()
	gets the context URI value.
String	getContextValue (int index)
	gets a context property value.
ArmCorrelator	getCorrelator ()
	gets the current correlator for this transaction instance.
ArmCorrelator	getParentCorrelator ()
	gets the correlator of the parent transaction, if any.
long	getResponseTime ()
	returns the last response time set on a `report()` method.
int	getStatus ()
	returns the last status value set on a `report()` method.
ArmTransactionDefinition	getDefinition ()
ArmUser	getUser ()
int	report (int status, long respTimeNanos)
	provide measurements about a completed transaction.
int	report (int status, long respTimeNanos, long stopTime)
	provides measurements about a completed transaction.
int	report (int status, long respTimeNanos, String diagnosticDetail)
	provide measurements about a completed transaction.
int	report (int status, long respTimeNanos, long stopTime, String diagnosticDetail)
	provide measurements about a completed transaction.
int	setContextURIValue (String value)
	sets the URI context value.
int	setContextValue (int index, String value)
	sets a context property value.
int	setParentCorrelator (ArmCorrelator parent)
	sets the correlator of the parent transaction.
int	setUser (ArmUser user)
	associates a user, represented by an instance of `ArmUser`, to the ArmTranReport instance.

Detailed Description

Transaction instance for application-based and/or remote time measurement.

ArmTranReport is similar to ArmTransaction. Both are used to provide data about executing transactions. Instances of both are created based on metadata represented by an ArmTransactionDefinition, which in turn is scoped by an application definition. Both are scoped by a running application instance, represented by ArmApplication. There are two fundamental differences:

With ArmTransaction, the response time is measured based on start() and stop() events. With ArmTranReport, the application measures the response time, and reports it with a single report() event.
With ArmTransaction, the transaction always executes on the local system in the same JVM (Java Virtual Machine). With ArmTranReport, the transaction may execute in the same JVM, in a different JVM on the same system, or on a different system.

When executing in the same JVM, the ArmTranReport object is created with an ArmApplication. When executing in a different JVM on the same system or on a different system, the ArmTranReport object is created with an ArmApplicationRemote (a subclass of ArmApplication).

The two key methods of ArmTranReport are generateCorrelator() and report.

generateCorrelator() generates a new correlator using the immutable data set in the factory method and the current property values set by the four setter methods. It is assumed that generateCorrelator() is executed zero or once per transaction instance. The practical ramification is that the method implementation will update its internal state to have a unique identifier for an instance (the equivalent of ArmTransaction's start handle). getCorrelator() returns the most recently generated ArmCorrelator or null, if generateCorrelator() has never been executed.
report() is used to provide measurements about a completed transaction. There are two forms. Both provide the status (one of the STATUS_* constants in ArmConstants) and the response time, measured in nanoseconds. One also provides a stop time in the form of milliseconds since January 1, 1970, which is the same format returned by java.lang.System.currentTimeMillis(). If a stop time is not provided, or a stop time of -1 (USE_CURRENT_TIME) is provided, the ARM implementation substitutes the current time; that is, the time when the report() method executes. The optional form that takes a string is a way for an application to provide additional diagnostic details when the status is something other than STATUS_GOOD.

As noted above, generateCorrelator() updates the internal state for a new transaction instance. The first time report() executes after generateCorrelator(), report() will not update the internal state for a new transaction instance; it will use the instance identifier from the generateCorrelator(). If report() executes twice in succession, or if generateCorrelator() has never been executed, report() will update the internal state for a new transaction instance. Summarizing, there are two patterns:

If correlators for the current transaction are not requested, generateCorrelator() is not used. report() is executed after each instance completes, and each time it generates a new instance identifier, like a start handle.
If correlators for the current transaction are requested, generateCorrelator() and report() are used in pairs. First generateCorrelator() establishes the transaction instance identifiers, as well as creating a correlator. This correlator is sent to downstream transactions. After the downstream transactions complete, and the current instance completes, report() provides the measurements. In this case report() does not update the transaction instance identifier.

In addition to the identity properties from ArmApplication and ArmTransactionDefinition, there are four optional setter methods to establish additional instance-level context. They can be used at any time to update the attribute within the object. The only time the properties are meaningful is when generateCorrelator() or report() executes. At the moment either method executes, the current values are used, any or all of which may be null. See the description provided for the individual methods below.

Objects implementing this interface are created using ArmTranReportFactory#newArmTranReport.

Author:: ARM Working Group of The Open Group

Member Function Documentation

ArmCorrelator org.opengroup.arm40.tranreport.ArmTranReport.generateCorrelator ( )

Generates a new correlator for the transaction instance.

See the discussion of this method in the interface description above.

Returns:: a new ArmCorrelator

ArmApplication org.opengroup.arm40.tranreport.ArmTranReport.getApplication ( )

Returns:: the ArmApplication used in the factory method to create this instance of ArmTranReport.

String org.opengroup.arm40.tranreport.ArmTranReport.getContextURIValue ( )

gets the context URI value.

Returns:: the context URI value, or null

String org.opengroup.arm40.tranreport.ArmTranReport.getContextValue ( int index )

gets a context property value.

See the description of setContextValue(int, String).

Parameters:

index

index into the array aof context properties.

Returns:: the value at index, or null.

ArmCorrelator org.opengroup.arm40.tranreport.ArmTranReport.getCorrelator ( )

gets the current correlator for this transaction instance.

See the discussion in the interface description above for when the state of the instance affecting the correlator is updated.

Returns:: an ArmCorrelator for this transcation instance.

ArmTransactionDefinition org.opengroup.arm40.tranreport.ArmTranReport.getDefinition ( )

Returns:: the ArmTransactionDefinition used in the factory method to create this instance of ArmTranReport.

ArmCorrelator org.opengroup.arm40.tranreport.ArmTranReport.getParentCorrelator ( )

gets the correlator of the parent transaction, if any.

Returns:: the last value set with setParentCorrelator. The vaue may be null.

long org.opengroup.arm40.tranreport.ArmTranReport.getResponseTime ( )

returns the last response time set on a report() method.

If report() has never executed, the return value is implementation dependent.

Returns:: the response time as of the last report() call.

int org.opengroup.arm40.tranreport.ArmTranReport.getStatus ( )

returns the last status value set on a report() method.

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

Returns:: one of the status values defined in org.opengroup.arm40.transaction.ArmConstants.

ArmUser org.opengroup.arm40.tranreport.ArmTranReport.getUser ( )

Returns:: the user associated with this transaction instance, if set with setUser(ArmUser), or null.

int org.opengroup.arm40.tranreport.ArmTranReport.report	(	int	status,
		long	respTimeNanos,
		long	stopTime,
		String	diagnosticDetail
	)

provide measurements about a completed transaction.

See the discussion of this method in the interface description above.

Parameters:

	status	transaction status. See org.opengroup.arm40.transaction.ArmConstants.
	respTimeNanos	response time (in nanoseconds)
	stopTime	stop time (milliseconds since January 1, 1970)
	diagnosticDetail	additional details, used when status other than `ArmConstants.STATUS_GOOD`

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

int org.opengroup.arm40.tranreport.ArmTranReport.report	(	int	status,
		long	respTimeNanos
	)

provide measurements about a completed transaction.

See the discussion of this method in the interface description above.

Parameters:

	status	transaction status. See org.opengroup.arm40.transaction.ArmConstants.
	respTimeNanos	response time (in nanoseconds)

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

int org.opengroup.arm40.tranreport.ArmTranReport.report	(	int	status,
		long	respTimeNanos,
		String	diagnosticDetail
	)

provide measurements about a completed transaction.

See the discussion of this method in the interface description above.

Parameters:

	status	transaction status. See org.opengroup.arm40.transaction.ArmConstants.
	respTimeNanos	response time (in nanoseconds)
	diagnosticDetail	additional details, used when status other than `ArmConstants.STATUS_GOOD`

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

int org.opengroup.arm40.tranreport.ArmTranReport.report	(	int	status,
		long	respTimeNanos,
		long	stopTime
	)

provides measurements about a completed transaction.

See the discussion of this method in the interface description above.

Parameters:

	status	transaction status. See org.opengroup.arm40.transaction.ArmConstants.
	respTimeNanos	response time (nanoseconds)
	stopTime	stop time (milliseconds since January 1, 1970)

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

int org.opengroup.arm40.tranreport.ArmTranReport.setContextURIValue ( String value )

sets the URI context value.

Parameters:

value

the new 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.tranreport.ArmTranReport.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. 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, the value will be set to null.

Parameters:

	index	index into the array aof context properties.
	value	the new 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.tranreport.ArmTranReport.setParentCorrelator ( ArmCorrelator parent )

sets the correlator of the parent transaction.

Parameters:

parent an org.opengroup.arm40.transaction.ArmCorrelator object referring to the parent transaction, or null.

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

int org.opengroup.arm40.tranreport.ArmTranReport.setUser ( ArmUser user )

associates a user, represented by an instance of ArmUser, to the ArmTranReport instance.

This user is assumed to be the user for all start()/stop() pairs until the association is changed or cleared. setUser(null) clears any existing association to an ArmUser.

Parameters:

user an ArmUser, or null

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/tranreport/ArmTranReport.java

All Classes Functions Variables

MyARM - Application Response Measurement (ARM) supported APIs

org.opengroup.arm40.tranreport.ArmTranReport Interface Reference
[ARM 4.0 Transactions]

Public Member Functions

Detailed Description

Member Function Documentation

MyARM - Application Response Measurement (ARM) supported APIs

org.opengroup.arm40.tranreport.ArmTranReport Interface Reference [ARM 4.0 Transactions]

Public Member Functions

Detailed Description

Member Function Documentation

org.opengroup.arm40.tranreport.ArmTranReport Interface Reference
[ARM 4.0 Transactions]