OpenGroup::arm40::Provisional::tranreport::IArmTranReport Interface Reference
[ARM 4.0 Transactions]
Transaction instance for application-based and/or remote time measurement. More...
Public Member Functions | |
IArmApplication | getApplication () |
returns the associated IArmApplication . | |
IArmCorrelator | getCorrelator () |
gets the current correlator for this transaction instance. | |
long | getResponseTime () |
returns the last response time set on a report() method. | |
int | getStatus () |
returns the last status value set on a report() method. | |
IArmTransactionDefinition | getDefinition () |
returns the associated IArmTransactionDefinition instance. | |
IArmCorrelator | generateCorrelator () |
Generates a new correlator for the transaction instance. | |
string | getContextURIValue () |
gets the context URI value. | |
string | getContextValue (int index) |
gets a context property value. | |
IArmCorrelator | getParentCorrelator () |
gets the correlator of the parent transaction, if any. | |
IArmUser | getUser () |
returns the user associated with this transaction instance. | |
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 (IArmCorrelator parent) |
sets the correlator of the parent transaction. | |
int | setUser (IArmUser user) |
associates a user, represented by an instance of IArmUser , to the IArmTranReport instance. |
Detailed Description
IArmTranReport
is similar to IArmTransaction
. Both are used to provide data about executing transactions. Instances of both are created based on metadata represented by an IArmTransactionDefinition
, which in turn is scoped by an application definition. Both are scoped by a running application instance, represented by IArmApplication. There are two fundamental differences:
-
With
IArmTransaction
, the response time is measured based onstart()
andstop()
events. WithIArmTranReport
, the application measures the response time, and reports it with a singlereport()
event. -
With
IArmTransaction
, the transaction always executes on the local system within the same process. WithIArmTranReport
, 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 IArmTranReport
object is created with an IArmApplication
. When executing in a different process on the same system or on a different system, the IArmTranReport
object is created with an IArmApplicationRemote
(a subclass of IArmApplication
).
The two key methods of IArmTranReport are generateCorrelator() and report(int, long) or report(int,long,long,string)
-
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 thatgenerateCorrelator()
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 ofIArmTransaction
's start handle).getCorrelator()
returns the most recently generatedIArmCorrelator
or null, ifgenerateCorrelator()
has never been executed. -
report()
is used to provide measurements about a completed transaction. There are two forms. Both provide the status (one of theSTATUS_///
constants inArmConstants
) and the response time, measured in nanoseconds. One also provides a stop time in the form of milliseconds since January 1, 1970. This is the same value as it can be onbtained viaTimeSpan TS = (TimeSpan)(DateTime.UtcNow - new DateTime(1970,1,1)); double milliseconds = TS.TotalMilliseconds();
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 thereport()
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 thanSTATUS_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()
andreport()
are used in pairs. FirstgenerateCorrelator()
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 casereport()
does not update the transaction instance identifier.
In addition to the identity properties from AIrmApplication
and IArmTransactionDefinition
, 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 IArmTranReportFactory.newArmTranReport
Member Function Documentation
IArmCorrelator OpenGroup::arm40::Provisional::tranreport::IArmTranReport::generateCorrelator | ( | ) |
See the discussion of this method in the interface description above.
- Returns:
- a new
IArmCorrelator
IArmApplication OpenGroup::arm40::Provisional::tranreport::IArmTranReport::getApplication | ( | ) |
- Returns:
- the
IArmApplication
used in the factory method to create this instance ofIArmTranReport
.
string OpenGroup::arm40::Provisional::tranreport::IArmTranReport::getContextURIValue | ( | ) |
- Returns:
- the context URI value, or
null
string OpenGroup::arm40::Provisional::tranreport::IArmTranReport::getContextValue | ( | int | index | ) |
See the description of setContextValue(int, String)
- Parameters:
-
index index into the array aof context properties.
- Returns:
- the value at
index
, ornull
.
IArmCorrelator OpenGroup::arm40::Provisional::tranreport::IArmTranReport::getCorrelator | ( | ) |
See the discussion in the interface description above for when the state of the instance affecting the correlator is updated.
- Returns:
- an
IArmCorrelator
for this transaction instance.
IArmTransactionDefinition OpenGroup::arm40::Provisional::tranreport::IArmTranReport::getDefinition | ( | ) |
- Returns:
- the
IArmTransactionDefinition
used in the factory method to create this instance ofIArmTranReport
.
IArmCorrelator OpenGroup::arm40::Provisional::tranreport::IArmTranReport::getParentCorrelator | ( | ) |
- Returns:
- the last value set with setParentCorrelator The vaue may be
null
.
long OpenGroup::arm40::Provisional::tranreport::IArmTranReport::getResponseTime | ( | ) |
int OpenGroup::arm40::Provisional::tranreport::IArmTranReport::getStatus | ( | ) |
If report()
has never executed, it returns STATUS_INVALID
.
- Returns:
- one of the status values defined in OpenGroup.arm40.Provisional.transaction.ArmConstants
IArmUser OpenGroup::arm40::Provisional::tranreport::IArmTranReport::getUser | ( | ) |
- Returns:
- the user associated with this transaction instance, if set with setUser(IArmUser), or
null
.
int OpenGroup::arm40::Provisional::tranreport::IArmTranReport::report | ( | int | status, | |
long | respTimeNanos, | |||
string | diagnosticDetail | |||
) |
See the discussion of this method in the interface description above.
- Parameters:
-
status transaction status. See OpenGroup.arm40.Provisional.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 OpenGroup.arm40.Provisional.transaction.IArmInterface
int OpenGroup::arm40::Provisional::tranreport::IArmTranReport::report | ( | int | status, | |
long | respTimeNanos | |||
) |
See the discussion of this method in the interface description above.
- Parameters:
-
status transaction status. See OpenGroup.arm40.Provisional.transaction.ArmConstants respTimeNanos response time (in nanoseconds)
- Returns:
- 0 on sucess; otherwise, a non-zero error code is returned (as specified in OpenGroup.arm40.Provisional.transaction.IArmInterface
int OpenGroup::arm40::Provisional::tranreport::IArmTranReport::report | ( | int | status, | |
long | respTimeNanos, | |||
long | stopTime, | |||
string | diagnosticDetail | |||
) |
See the discussion of this method in the interface description above.
- Parameters:
-
status transaction status. See OpenGroup.arm40.Provisional.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 OpenGroup.arm40.Provisional.transaction.IArmInterface
int OpenGroup::arm40::Provisional::tranreport::IArmTranReport::report | ( | int | status, | |
long | respTimeNanos, | |||
long | stopTime | |||
) |
See the discussion of this method in the interface description above.
- Parameters:
-
status transaction status. See OpenGroup.arm40.Provisional.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 OpenGroup.arm40.Provisional.transaction.IArmInterface
int OpenGroup::arm40::Provisional::tranreport::IArmTranReport::setContextURIValue | ( | string | value | ) |
- Parameters:
-
value the new 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::tranreport::IArmTranReport::setContextValue | ( | int | index, | |
string | 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 IArmTransactionDefinition
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 OpenGroup.arm40.Provisional.transaction.IArmInterface
int OpenGroup::arm40::Provisional::tranreport::IArmTranReport::setParentCorrelator | ( | IArmCorrelator | parent | ) |
- Parameters:
-
parent an OpenGroup.arm40.Provisional.transaction.IArmCorrelator object referring to the parent transaction, or null
.
- Returns:
- 0 on sucess; otherwise, a non-zero error code is returned (as specified in OpenGroup.arm40.Provisional.transaction.IArmInterface
int OpenGroup::arm40::Provisional::tranreport::IArmTranReport::setUser | ( | IArmUser | user | ) |
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 IArmUser
.
- Parameters:
-
user an IArmUser
, ornull
- 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/tranreport/IArmTranReport.cs