public interface ArmTranReport extends ArmInterface
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:
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.
ArmTransaction
, the transaction always executes on
the local system in the same JVM (Java Virtual Machine). With
ArmTranReport
, the transaction may execute in the same
JVM, in a different JVM on the same system, or on a different system.
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)
.
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 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, which is the same format returned by
java.lang.System.currentTimeMillis()
. 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
.
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:
generateCorrelator()
is not used. report()
is
executed after each instance completes, and each time it generates a new
instance identifier, like a start handle.
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.
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)
.Modifier and Type | Method and Description |
---|---|
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. |
getErrorCode, getErrorMessage, setErrorCode
ArmCorrelator generateCorrelator()
ArmCorrelator
ArmApplication getApplication()
ArmApplication
used in the factory method
to create this instance of ArmTranReport
.java.lang.String getContextURIValue()
null
java.lang.String getContextValue(int index)
setContextValue(int, String)
.index
- index into the array aof context properties.index
, or null
.ArmCorrelator getCorrelator()
ArmCorrelator
for this transcation instance.ArmCorrelator getParentCorrelator()
setParentCorrelator(org.opengroup.arm40.transaction.ArmCorrelator)
.
The vaue may be null
.long getResponseTime()
report()
method.
If report()
has never executed, the return value
is implementation dependent.report()
call.int getStatus()
report()
method.
If report()
has never executed, it returns
STATUS_INVALID
.ArmConstants
.ArmTransactionDefinition getDefinition()
ArmTransactionDefinition
used in the
factory method to create this instance of
ArmTranReport
.ArmUser getUser()
setUser(ArmUser)
, or null
.int report(int status, long respTimeNanos)
status
- transaction status.
See ArmConstants
.respTimeNanos
- response time (in nanoseconds)ArmInterface
).int report(int status, long respTimeNanos, long stopTime)
status
- transaction status.
See ArmConstants
.respTimeNanos
- response time (nanoseconds)stopTime
- stop time (milliseconds since January 1, 1970)ArmInterface
).int report(int status, long respTimeNanos, java.lang.String diagnosticDetail)
status
- transaction status.
See ArmConstants
.respTimeNanos
- response time (in nanoseconds)diagnosticDetail
- additional details, used when status other than
ArmConstants.STATUS_GOOD
ArmInterface
).int report(int status, long respTimeNanos, long stopTime, java.lang.String diagnosticDetail)
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
ArmInterface
).int setContextURIValue(java.lang.String value)
value
- the new URI context value.ArmInterface
).int setContextValue(int index, java.lang.String value)
null
value when the
ArmTransactionDefinition
object was created.
If the name is null
, the value will be set to
null
.index
- index into the array aof context properties.value
- the new context value.ArmInterface
).int setParentCorrelator(ArmCorrelator parent)
parent
- an ArmCorrelator
object referring to the parent transaction, or
null
.ArmInterface
).int setUser(ArmUser user)
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
.user
- an ArmUser
, or null
ArmInterface
).