Public Member Functions

OpenGroup::arm40::Provisional::tranreport::IArmTranReport Interface Reference
[ARM 4.0 Transactions]

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

Inheritance diagram for OpenGroup::arm40::Provisional::tranreport::IArmTranReport:
OpenGroup::arm40::Provisional::transaction::IArmInterface OpenGroup::arm40::Provisional::metric::IArmTranReportWithMetrics

List of all members.

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 on start() and stop() events. With IArmTranReport, the application measures the response time, and reports it with a single report() event.
  • With IArmTransaction, the transaction always executes on the local system within the same process. With IArmTranReport, 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 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 IArmTransaction's start handle). getCorrelator() returns the most recently generated IArmCorrelator 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. This is the same value as it can be onbtained via TimeSpan 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 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 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 of IArmTranReport.
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, or null.
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 of IArmTranReport.
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 (  ) 

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

Returns:
the response time as of the last report() call.
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, or null
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
MyARM
Documentation generated on Thu May 24 2018 22:24:16. © 2018 by MyARM GmbH