org.opengroup.arm40.tranreport
Interface ArmTranReport

All Superinterfaces:
ArmInterface
All Known Subinterfaces:
ArmTranReportWithMetrics
All Known Implementing Classes:
ArmTranReport, ArmTranReportWithMetrics

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 report(int, long).

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.newArmTranReport(org.opengroup.arm40.transaction.ArmApplication, org.opengroup.arm40.transaction.ArmTransactionDefinition).

Author:
ARM Working Group of The Open Group

Method Summary
 ArmCorrelator generateCorrelator()
          Generates a new correlator for the transaction instance.
 ArmApplication getApplication()
           
 java.lang.String getContextURIValue()
          gets the context URI value.
 java.lang.String getContextValue(int index)
          gets a context property value.
 ArmCorrelator getCorrelator()
          gets the current correlator for this transaction instance.
 ArmTransactionDefinition getDefinition()
           
 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.
 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, long stopTime, java.lang.String diagnosticDetail)
          provide measurements about a completed transaction.
 int report(int status, long respTimeNanos, java.lang.String diagnosticDetail)
          provide measurements about a completed transaction.
 int setContextURIValue(java.lang.String value)
          sets the URI context value.
 int setContextValue(int index, java.lang.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.
 
Methods inherited from interface org.opengroup.arm40.transaction.ArmInterface
getErrorCode, getErrorMessage, setErrorCode
 

Method Detail

generateCorrelator

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

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

getContextURIValue

java.lang.String getContextURIValue()
gets the context URI value.

Returns:
the context URI value, or null

getContextValue

java.lang.String 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.

getCorrelator

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.

getParentCorrelator

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

Returns:
the last value set with setParentCorrelator(org.opengroup.arm40.transaction.ArmCorrelator). The vaue may be null.

getResponseTime

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

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.

getDefinition

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

getUser

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

report

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

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

int report(int status,
           long respTimeNanos,
           java.lang.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

int report(int status,
           long respTimeNanos,
           long stopTime,
           java.lang.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

int setContextURIValue(java.lang.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

int setContextValue(int index,
                    java.lang.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

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

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