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

Inheritance diagram for arm4::ArmTranReport:

Public Member Functions
	ArmTranReport (const ArmApplication &app, const ArmTransactionDefinition &definition)
	Constructs an object that represents an instance of a transaction.
const ArmCorrelator &	generateCorrelator ()
	Generates a new correlator for the transaction instance.
const ArmApplication &	getApplication () const
	returns a reference to the associated application instance.
const std::string &	getContextURIValue () const
	gets the context URI value.
const std::string &	getContextValue (int32_t index) const
	gets a context property value.
const ArmCorrelator &	getCorrelator () const
	gets the current correlator for this transaction instance.
const ArmCorrelator &	getParentCorrelator () const
	gets the correlator of the parent transaction, if any.
int64_t	getResponseTime () const
	returns the last response time set on a `report()` method.
int32_t	getStatus () const
	returns the last status value set on a `report()` method.
const ArmTransactionDefinition &	getDefinition () const
	returns a reference the associated transaction definition.
const ArmUser &	getUser () const
	returns a reference to the associated user.
int32_t	report (int32_t status, int64_t respTimeNanos, int64_t stopTime=ArmConstants::USE_CURRENT_TIME, const std::string &diagnosticDetail=NullString)
	provide measurements about a completed transaction.
int32_t	setContextURIValue (const std::string &value)
	sets the URI context value.
int32_t	setContextValue (int32_t index, const std::string &value)
	sets a context property value.
int32_t	setParentCorrelator (const ArmCorrelator &parent)
	sets the correlator of the parent transaction.
int32_t	setUser (const 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 process. With ArmTranReport, the transaction may execute in the same process, in a different process on the same system, or on a different system.

When executing in the same process, the ArmTranReport object is created with an ArmApplication. When executing in a different process 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 ArmCorrelator::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. 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.

Note:: ArmTranReport should only be used within a single thread. It does not make much sense to use an instance of this class across threads thus no locking is implemented.

Author:: ARM Working Group of The Open Group, MyARM GmbH

Constructor & Destructor Documentation

arm4::ArmTranReport::ArmTranReport	(	const ArmApplication &	app,
		const ArmTransactionDefinition &	definition
	)

Constructs an object that represents an instance of a transaction.

The metadata is supplied in an ArmTransactionDefinition object. It is scoped by an application instance, represented by ArmApplication (or its subclass, ArmApplicationRemote).

Parameters:

	app	the application instance the transaction belongs to.
	definition	the metadata describing the type of the transaction.

Member Function Documentation

const ArmCorrelator& arm4::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

const ArmApplication& arm4::ArmTranReport::getApplication ( ) const

returns a reference to the associated application instance.

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

const std::string& arm4::ArmTranReport::getContextURIValue ( ) const

gets the context URI value.

Returns:: the context URI value, or null

const std::string& arm4::ArmTranReport::getContextValue ( int32_t index ) const

gets a context property value.

See the description of setContextValue().

Parameters:

index

index into the array aof context properties.

Returns:: the value at index, or null.

const ArmCorrelator& arm4::ArmTranReport::getCorrelator ( ) const

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.

const ArmTransactionDefinition& arm4::ArmTranReport::getDefinition ( ) const

returns a reference the associated transaction definition.

Returns:: the ArmTransactionDefinition used in the constructor.

const ArmCorrelator& arm4::ArmTranReport::getParentCorrelator ( ) const

gets the correlator of the parent transaction, if any.

Returns:: the last value set with setParentCorrelator(). The vaue may be a ArmCorrelator::Null.

int64_t arm4::ArmTranReport::getResponseTime ( ) const

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.

int32_t arm4::ArmTranReport::getStatus ( ) const

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

const ArmUser& arm4::ArmTranReport::getUser ( ) const

returns a reference to the associated user.

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

int32_t arm4::ArmTranReport::report	(	int32_t	status,
		int64_t	respTimeNanos,
		int64_t	stopTime = `ArmConstants::USE_CURRENT_TIME`,
		const std::string &	diagnosticDetail = `NullString`
	)

provide measurements about a completed transaction.

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

Parameters:

	status	transaction status. See 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 ArmInterface).

int32_t arm4::ArmTranReport::setContextURIValue ( const std::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 ArmInterface).

int32_t arm4::ArmTranReport::setContextValue	(	int32_t	index,
		const std::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-NullString value when the ArmTransactionDefinition object was created. If the name is a NullString, the value will be set to NullString.

Parameters:

	index	index into the array of context properties.
	value	the new context value.

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

int32_t arm4::ArmTranReport::setParentCorrelator ( const ArmCorrelator & parent )

sets the correlator of the parent transaction.

Parameters:

parent an ArmCorrelator object referring to the parent transaction, or ArmCorrelator::Null.

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

int32_t arm4::ArmTranReport::setUser ( const 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(ArmUser::Null) clears any existing association to an ArmUser.

Parameters:

user an ArmUser, or ArmUser::Null