org.opengroup.arm40.transaction
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
ArmTransactionFactoryand 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).Method Summary | |
---|---|
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.
returns the value passed to the
newArmTransaction() method of
ArmTransactionFactory . |
String | getContextURIValue()
gets the URI context value.
|
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.
returns the value passed to the
newArmTransaction() method of
ArmTransactionFactory . |
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(String value)
sets the URI context value.
getContextURIValue returns the value.
|
int | setContextValue(int index, 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(byte[] parentCorr)
indicates when a transaction begins. |
int | start(byte[] parentCorr, int offset)
indicates when a transaction begins. |
int | start(ArmCorrelator parentCorr)
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, 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. |
stop()
or reset()
is
executed.Returns: 0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).
start()
and stop()
.
ArmTransaction 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.Returns: handle to be passed to a matching unblocked()
method call.
newArmTransaction()
method of
ArmTransactionFactory
.Returns: the containing ArmApplication
.
Returns: the URI context value, or null
.
Parameters: index index into the context properties array.
Returns: the context value at index index
, or
null
.
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.Returns: a correlator object. Validity of its content depends on the context of execution, see method description.
newArmTransaction()
method of
ArmTransactionFactory
.Returns: the ArmTransactionDefinition
metadata.
start()
method.
If no value was set on the start()
method, or if
start()
has never executed, it returns
null
.Returns: the parent correlator, or null
.
stop()
method.
If stop()
has never executed, it returns
STATUS_INVALID
.Returns: one of the status values defined in ArmConstants.
ArmUser
currently asociated with this
transaction instance.
See description of setUser.Returns: an ArmUser
, or null
.
false
.
See description of ArmTransaction.Returns: the current trace request state.
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.
Returns: 0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).
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.Returns: 0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).
Parameters: value the URI context value.
Returns: 0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).
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.Parameters: index index into the context properties array. value the new context property value.
Returns: 0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).
false
.
Once set, it remains in that state until set to a different state.Parameters: traceState trace request state.
Returns: 0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).
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.Parameters: user the user to be associated with this transaction
instance. When null
, clears any existing
association to an ArmUser
Returns: 0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).
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.
Returns: 0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).
Parameters: parentCorr a parent correlator for this transaction, represented as an array of bytes.
Returns: 0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).
Parameters: 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.
Returns: 0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).
Parameters: parentCorr a parent correlator object for this transaction.
Returns: 0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).
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.
Parameters: status one of STATUS_ABORT, STATUS_FAILED, STATUS_GOOD, or STATUS_UNKNOWN (all defined in ArmConstants).
Returns: 0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).
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
ArmTransaction.
Parameters: 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 application
Returns: 0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).
Returns: 0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).
Parameters: blockHandle handle returned from a previous
blocked()
method call.
Returns: 0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).
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:
ArmTransaction
, any of the metric values can be
provided with an update()
.Returns: 0 on sucess; otherwise, a non-zero error code is returned (as specified in ArmInterface).