public interface ArmTransaction extends ArmInterface
ArmTransaction
objects after some initialization (using
ArmTransactionFactory
,ArmApplicationDefinition
,
ArmApplication
, and ArmTransactionDefinition
).
Instances of ArmTransaction
represent transactions when they
execute. A "transaction" is any unit of work that has a clearly understood
beginning and ending point, and which begins and ends in the same Java©
Virtual Machine instance. Examples include a remote procedure call, a
database transaction, and a batch job. It is not necessary that an ARM
transaction implement robust functions such as commit and rollback. The
application creates as many instances as it needs. This will typically be at
least as many as the number of transactions that can be executing
simultaneously. An application may create a pool of
ArmTransaction
objects, take one from the pool to use when a
transaction starts, and put it back in the pool after the transaction ends
for later reuse. Another strategy is to create one instance of each type per
thread, which eliminates the need to manage the pool, handle synchronization
if the pool is depleted, etc. The metadata common to all instances is
contained in the ArmTransactionDefinition
used to create the
object. Each transaction is scoped by an application instance, represented by
ArmApplication
.The most frequently (and often the only)
used methods are start()
,getCorrelator()
,
and stop()
. A typical sequence is as follows:
start()
to signal to ARM that the measurable transaction
is beginning. start()
causes ARM to capture the current time.
If a correlation token was received when your program was invoked, pass it as
a parameter on the start()
.start()
, and just prior to
executing the transaction, call getCorrelator()
to get a
correlation token that can be sent along with the other transaction
parameters to the receiver. Not all programs use correlators, but their use
is highly recommended, because without them, it is usually impossible to
drill down to understand the components of a transaction, where they
executed, what resources they used, etc.stop()
, passing a status to
indicate whether the transaction succeeded. stop()
causes ARM
to capture the current time. The response time is determined by calculating
the duration between the start()
and stop()
events.int
are returning an error
code that the application may but need not test. Refer to
ArmTransactionFactory
and the ARM 4.0 Java Binding Specification for
more information about handling errors. Note that there are some changes
from ARM 3.0:
ArmTransaction
to ArmApplicationDefinition
and
ArmTransactionDefinition
.getRespTime()
,getStopTime()
, and
getTranHandle()
.stop()
is changed from
long
to int
. The long
returned
in ARM 3.0 was the response time, and the requirement to return it is
considered unacceptable. The int
return value is an error
indicator (if it's negative).ArmTransactionFactory.newArmTransaction(org.opengroup.arm40.transaction.ArmApplication, org.opengroup.arm40.transaction.ArmTransactionDefinition)
.Modifier and Type | Method and Description |
---|---|
int |
bindThread()
indicates current thread executing on behalf of this transaction.
|
long |
blocked()
indicates that the transaction instance is blocked.
|
ArmApplication |
getApplication()
gets the contaning application instance.
|
java.lang.String |
getContextURIValue()
gets the URI context value.
|
java.lang.String |
getContextValue(int index)
gets a context property value.
|
ArmCorrelator |
getCorrelator()
returns a reference to the correlator for the current transaction.
|
ArmTransactionDefinition |
getDefinition()
gets the definition metadata for this transaction.
|
ArmCorrelator |
getParentCorrelator()
returns the parent correlator, if set for this transaction.
|
int |
getStatus()
returns the last status value set on a
stop() method. |
ArmUser |
getUser()
returns the
ArmUser currently asociated with this
transaction instance. |
boolean |
isTraceRequested()
gets the current trace request state.
|
int |
reset()
Resets a transaction if it is currently executing.
|
int |
setArrivalTime()
sets the actual transaction start time for the next
start() . |
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 |
setTraceRequested(boolean traceState)
Toggles request for tracing this transaction.
|
int |
setUser(ArmUser user)
associates a user to the
ArmTransaction instance. |
int |
start()
indicates when a transaction begins.
|
int |
start(ArmCorrelator parentCorr)
indicates when a transaction begins.
|
int |
start(byte[] parentCorr)
indicates when a transaction begins.
|
int |
start(byte[] parentCorr,
int offset)
indicates when a transaction begins.
|
int |
stop(int status)
indicates when a transaction ends and what the status of the transaction
was.
|
int |
stop(int status,
java.lang.String diagnosticDetail)
indicates when a transaction ends and what the status of the transaction
was.
|
int |
unbindThread()
indicates current thread not executing on behalf of this
transaction any more.
|
int |
unblocked(long blockHandle)
indicates that the transaction instance is not blocked any more.
|
int |
update()
provides heartbeat and/or metric value update functionality.
|
getErrorCode, getErrorMessage, setErrorCode
int bindThread()
unbindThread()
is executed in
this thread or stop()
or reset()
is
executed.ArmInterface
).long blocked()
start()
and stop()
.
unblocked(long)
indicates when the blocking
condition has ended.
A transaction may be blocked by multiple conditions
simultaneously. A "block handle" returned by block() is
the input parameter to unblocked()
to indicate which
blocking condition has ended.unblocked()
method call.ArmApplication getApplication()
newArmTransaction()
method of
ArmTransactionFactory
.ArmApplication
.java.lang.String getContextURIValue()
getContextURIValue()
.null
.java.lang.String getContextValue(int index)
setContextValue(int, String)
.index
- index into the context properties array.index
, or
null
.ArmCorrelator getCorrelator()
start()
is executed. Each time it is executed, it
will return the same value until the next stop()
or
reset()
is executed. If it is executed at any other
time, it will return an ArmCorrelator
object, but the
data within the ArmCorrelator object is undefined and should not
be used.ArmCorrelator getParentCorrelator()
start()
method.
If no value was set on the start()
method, or if
start()
has never executed, it returns
null
.null
.int getStatus()
stop()
method.
If stop()
has never executed, it returns
STATUS_INVALID
.ArmConstants
.ArmTransactionDefinition getDefinition()
newArmTransaction()
method of
ArmTransactionFactory
.ArmTransactionDefinition
metadata.ArmUser getUser()
ArmUser
currently asociated with this
transaction instance.
See description of setUser(ArmUser)
.ArmUser
, or null
.boolean isTraceRequested()
false
.
See description of setTraceRequested(boolean)
.int reset()
start()
executed without a matching
stop()
], the current transaction is discarded and
treated as if the start()
never executed. If
no transaction is currently executing, the state of the object is
unchanged. If there is any doubt about the state of an object,
reset()
gets the object into a known state in which a
start()
may be executed.
reset()
clears the arrival time and the current
correlator; it does not change traceRequested
or any
of the context URI, context values, or user.ArmInterface
).int setArrivalTime()
start()
.
This method can be used in situations in which the context of a
transaction is not known when the transaction begins to execute,
and for which there is a non-trivial delay before the context is
known. ARM requires that the full context of a transaction be
known when start()
is executed (because the correlator
is generated at this time). In ARM 2.0 and 3.0 there is no way
to capture any time spent processing the transaction before the
context is known. ARM 4.0 introduces the concept of an
"arrival time". The "arrival time" is when processing of the
transaction commenced. By default it is the moment in time
when start()
executes. If the delay between the start
of processing and the execution of start()
is
significant, the application can capture the arrival time by
invoking setArrivalTime()
. This establishes a timestamp
that will be used at the next start()
, after which
the value will be reset within the ArmTransaction
object. The reset()
and stop()
methods
also clear the value.ArmInterface
).int setContextURIValue(java.lang.String value)
getContextURIValue()
returns the value.
In most scenarios, a URI would be used as a transaction identity
property or a context property, but not both. The only allowed
exception is when the base part of the URI is used as an identity
property, and the full URI (e.g., with the parameters) is used
as a context property. Any other use of URIs as both identity
and context properties is invalid.value
- the URI context value.ArmInterface
).int setContextValue(int index, java.lang.String value)
getContextValue(int)
returns the value. The "name" part is available via
getDefinition().getIdentityProperties().getContextName()
.
The values are position-sensitive - they match the position in the
referenced context name array (see the discussion at
ArmIdentityProperties
for more details). 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
or a zero-length string, both the name
and value are ignored. If the value is null
or a
zero-length string, the meaning is that there is no value for
this instance. The value should not contain trailing blank characters
or consist of only blank characters.index
- index into the context properties array.value
- the new context property value.ArmInterface
).int setTraceRequested(boolean traceState)
isTraceRequested()
is used to query the current trace
request state. The initial state is false
.
Once set, it remains in that state until set to a different state.traceState
- trace request state.ArmInterface
).int setUser(ArmUser user)
ArmTransaction
instance.
This user, represented by an instance of ArmUser
,
is assumed to be the user for all start()
/
stop()
pairs until the association is changed or
cleared.
getUser()
returns the last value that was set.user
- the user to be associated with this transaction
instance. When null
, clears any existing
association to an ArmUser
ArmInterface
).int start()
Because the response time depends on when start()
executes, it should execute as close to the actual start time as
possible. After start()
executes, it should not be
executed again until reset()
or stop()
is
executed. If start()
executes consecutively, the
behavior is undefined.
start()
, depending on
whether a parent correlator is provided, and if one is provided, the
format of the input data. The length of the correlator is in the first
two bytes of the correlator byte array, with the bytes in network byte
order. When the input is a byte array, the length of the array does not
matter, as long as it is at least long enough to hold the correlator,
based on the two-byte length field.ArmInterface
).int start(byte[] parentCorr)
start()
.parentCorr
- a parent correlator for this transaction, represented as an
array of bytes.ArmInterface
).int start(byte[] parentCorr, int offset)
start()
.parentCorr
- a parent correlator for this transaction, represented as an
array of bytes.offset
- the offset into byte array parentCorr
pointing
at the start of the acual correlator data.ArmInterface
).int start(ArmCorrelator parentCorr)
start()
.parentCorr
- a parent correlator object for this transaction.ArmInterface
).int stop(int status)
stop()
executes, it should execute as close to the actual stop time as
possible.
If stop()
is erroneously issued when there is no
transaction active [start()
issued without a matching
stop()
], it is ignored.status
- one of STATUS_ABORT, STATUS_FAILED, STATUS_GOOD, or
STATUS_UNKNOWN (all defined in ArmConstants
).ArmInterface
).int stop(int status, java.lang.String diagnosticDetail)
stop()
as a way for an
application to provide additional diagnostic details when the status is
something other than STATUS_GOOD
. See the desription of
stop(int)
.status
- one of STATUS_ABORT, STATUS_FAILED, STATUS_GOOD, or
STATUS_UNKNOWN (all defined in ArmConstants
).diagnosticDetail
- string with additional diagnostic details provided by the
applicationArmInterface
).int unbindThread()
bindThread()
.ArmInterface
).int unblocked(long blockHandle)
blocked()
.blockHandle
- handle returned from a previous
blocked()
method call.ArmInterface
).int update()
start()
there can be any number of update()
calls until a stop()
. If it is executed at any other
time, it is ignored. The behavior of update()
issued at
any other time is undefined. It is used for two purposes:
ArmTransactionWithMetrics
, a subclass
of ArmTransaction
, any of the metric values can be
provided with an update()
.ArmInterface
).