org.opengroup.arm40.tranreport

Interface ArmTranReport

public interface ArmTranReport extends ArmInterface

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:

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

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

Author: ARM Working Group of The Open Group

Method Summary
ArmCorrelatorgenerateCorrelator()
Generates a new correlator for the transaction instance.
ArmApplicationgetApplication()
StringgetContextURIValue()
gets the context URI value.
StringgetContextValue(int index)
gets a context property value.
ArmCorrelatorgetCorrelator()
gets the current correlator for this transaction instance.
ArmTransactionDefinitiongetDefinition()
ArmCorrelatorgetParentCorrelator()
gets the correlator of the parent transaction, if any.
longgetResponseTime()
returns the last response time set on a report() method.
intgetStatus()
returns the last status value set on a report() method.
ArmUsergetUser()
intreport(int status, long respTimeNanos)
provide measurements about a completed transaction.
intreport(int status, long respTimeNanos, long stopTime)
provides measurements about a completed transaction.
intreport(int status, long respTimeNanos, String diagnosticDetail)
provide measurements about a completed transaction.
intreport(int status, long respTimeNanos, long stopTime, String diagnosticDetail)
provide measurements about a completed transaction.
intsetContextURIValue(String value)
sets the URI context value.
intsetContextValue(int index, String value)
sets a context property value.
intsetParentCorrelator(ArmCorrelator parent)
sets the correlator of the parent transaction.
intsetUser(ArmUser user)
associates a user, represented by an instance of ArmUser, to the ArmTranReport instance.

Method Detail

generateCorrelator

public ArmCorrelator generateCorrelator()
Generates a new correlator for the transaction instance. See the discussion of this method in the interface description above.

Returns: a new ArmCorrelator

getApplication

public ArmApplication getApplication()

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

getContextURIValue

public String getContextURIValue()
gets the context URI value.

Returns: the context URI value, or null

getContextValue

public String getContextValue(int index)
gets a context property value. See the description of ArmTranReport.

Parameters: index index into the array aof context properties.

Returns: the value at index, or null.

getCorrelator

public ArmCorrelator 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.

getDefinition

public ArmTransactionDefinition getDefinition()

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

getParentCorrelator

public ArmCorrelator getParentCorrelator()
gets the correlator of the parent transaction, if any.

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

getResponseTime

public long 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.

getStatus

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

getUser

public ArmUser getUser()

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

report

public int 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 ArmConstants. respTimeNanos response time (in nanoseconds)

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

report

public int 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 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 ArmInterface).

report

public int 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 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 ArmInterface).

report

public int 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 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).

setContextURIValue

public int 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 ArmInterface).

setContextValue

public int 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 ArmInterface).

setParentCorrelator

public int setParentCorrelator(ArmCorrelator parent)
sets the correlator of the parent transaction.

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

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

setUser

public int 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 ArmInterface).