public class ArmTransaction extends ArmInterface implements ArmTransaction
ArmConstants.STATUS_ABORT - if the transaction was blocked on a thread. ArmConstants.STATUS_FAILED - If the transaction failed. ArmConstants.STATUS_GOOD - If a transaction has successfully started or has been updated. ArmConstants.STATUS_INVALID - When a transaction is instructed to be stopped, the transaction will be marked invlid and it should never execute again. ArmConstants.STATUS_UNKNOWN - When a transaction is first created it will be in an unknown state.
Modifier and Type | Field and Description |
---|---|
static int |
ARM_SUCCESS |
protected ArmApplication |
m_application |
protected long |
m_arrivalTime |
protected java.lang.String |
m_contextUri |
protected java.util.ArrayList |
m_contextValues |
protected ArmCorrelator |
m_currentCorrelator |
protected ArmTransactionDefinition |
m_definition |
protected ArmMetricGroup |
m_metricGroup |
protected ArmCorrelator |
m_parentCorrelator |
protected int |
m_status |
protected boolean |
m_traceRequested |
protected long |
m_transactionHandle |
protected ArmUser |
m_user |
m_errorCode, m_factory
Constructor and Description |
---|
ArmTransaction(ArmApplication app,
ArmTransactionDefinition def,
ArmFactory factory)
Create the ARM Transaction.
|
ArmTransaction(ArmApplication app,
ArmTransactionDefinition def,
ArmMetricGroup group,
ArmFactory factory)
Create the ARM Transaction.
|
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.
|
protected ArmMetricGroup |
getMetricGroup()
Get the metric group.
|
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 |
setCorrelator(ArmCorrelator correlator)
Set the correlator.
|
int |
setParentCorrelator(ArmCorrelator parent)
Set the parent correlator.
|
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, getFactory, setErrorCode, setFactory
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
getErrorCode, getErrorMessage, setErrorCode
public static final int ARM_SUCCESS
protected ArmApplication m_application
protected ArmTransactionDefinition m_definition
protected ArmCorrelator m_parentCorrelator
protected ArmCorrelator m_currentCorrelator
protected ArmUser m_user
protected long m_arrivalTime
protected long m_transactionHandle
protected int m_status
protected boolean m_traceRequested
protected java.lang.String m_contextUri
protected java.util.ArrayList m_contextValues
protected ArmMetricGroup m_metricGroup
public ArmTransaction(ArmApplication app, ArmTransactionDefinition def, ArmFactory factory)
app
- def
- factory
- public ArmTransaction(ArmApplication app, ArmTransactionDefinition def, ArmMetricGroup group, ArmFactory factory)
app
- def
- group
- factory
- public int bindThread()
ArmTransaction
ArmTransaction.unbindThread()
is executed in
this thread or stop()
or reset()
is
executed.bindThread
in interface ArmTransaction
ArmInterface
).public long blocked()
ArmTransaction
start()
and stop()
.
ArmTransaction.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.blocked
in interface ArmTransaction
unblocked()
method call.public ArmApplication getApplication()
ArmTransaction
newArmTransaction()
method of
ArmTransactionFactory
.getApplication
in interface ArmTransaction
ArmApplication
.public java.lang.String getContextURIValue()
ArmTransaction
ArmTransaction.getContextURIValue()
.getContextURIValue
in interface ArmTransaction
null
.public java.lang.String getContextValue(int index)
ArmTransaction
ArmTransaction.setContextValue(int, String)
.getContextValue
in interface ArmTransaction
index
- index into the context properties array.index
, or
null
.public ArmCorrelator getCorrelator()
ArmTransaction
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.getCorrelator
in interface ArmTransaction
public ArmCorrelator getParentCorrelator()
ArmTransaction
start()
method.
If no value was set on the start()
method, or if
start()
has never executed, it returns
null
.getParentCorrelator
in interface ArmTransaction
null
.public int getStatus()
ArmTransaction
stop()
method.
If stop()
has never executed, it returns
STATUS_INVALID
.getStatus
in interface ArmTransaction
ArmConstants
.public ArmTransactionDefinition getDefinition()
ArmTransaction
newArmTransaction()
method of
ArmTransactionFactory
.getDefinition
in interface ArmTransaction
ArmTransactionDefinition
metadata.public ArmUser getUser()
ArmTransaction
ArmUser
currently asociated with this
transaction instance.
See description of ArmTransaction.setUser(ArmUser)
.getUser
in interface ArmTransaction
ArmUser
, or null
.public boolean isTraceRequested()
ArmTransaction
false
.
See description of ArmTransaction.setTraceRequested(boolean)
.isTraceRequested
in interface ArmTransaction
public int reset()
ArmTransaction
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.reset
in interface ArmTransaction
ArmInterface
).public int setArrivalTime()
ArmTransaction
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.setArrivalTime
in interface ArmTransaction
ArmInterface
).public int setContextURIValue(java.lang.String value)
ArmTransaction
ArmTransaction.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.setContextURIValue
in interface ArmTransaction
value
- the URI context value.ArmInterface
).public int setContextValue(int index, java.lang.String value)
ArmTransaction
ArmTransaction.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.setContextValue
in interface ArmTransaction
index
- index into the context properties array.value
- the new context property value.ArmInterface
).public int setTraceRequested(boolean traceState)
ArmTransaction
ArmTransaction.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.setTraceRequested
in interface ArmTransaction
traceState
- trace request state.ArmInterface
).public int setUser(ArmUser user)
ArmTransaction
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.
ArmTransaction.getUser()
returns the last value that was set.setUser
in interface ArmTransaction
user
- the user to be associated with this transaction
instance. When null
, clears any existing
association to an ArmUser
ArmInterface
).public int start()
ArmTransaction
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.start
in interface ArmTransaction
ArmInterface
).public int start(byte[] parentCorr)
ArmTransaction
ArmTransaction.start()
.start
in interface ArmTransaction
parentCorr
- a parent correlator for this transaction, represented as an
array of bytes.ArmInterface
).public int start(byte[] parentCorr, int offset)
ArmTransaction
ArmTransaction.start()
.start
in interface ArmTransaction
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
).public int start(ArmCorrelator parentCorr)
ArmTransaction
ArmTransaction.start()
.start
in interface ArmTransaction
parentCorr
- a parent correlator object for this transaction.ArmInterface
).public int stop(int status)
ArmTransaction
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.stop
in interface ArmTransaction
status
- one of STATUS_ABORT, STATUS_FAILED, STATUS_GOOD, or
STATUS_UNKNOWN (all defined in ArmConstants
).ArmInterface
).public int stop(int status, java.lang.String diagnosticDetail)
ArmTransaction
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.stop(int)
.stop
in interface ArmTransaction
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
).public int unbindThread()
ArmTransaction
ArmTransaction.bindThread()
.unbindThread
in interface ArmTransaction
ArmInterface
).public int unblocked(long blockHandle)
ArmTransaction
ArmTransaction.blocked()
.unblocked
in interface ArmTransaction
blockHandle
- handle returned from a previous
blocked()
method call.ArmInterface
).public int update()
ArmTransaction
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()
.update
in interface ArmTransaction
ArmInterface
).public int setParentCorrelator(ArmCorrelator parent)
parent
- public int setCorrelator(ArmCorrelator correlator)
correlator
- protected ArmMetricGroup getMetricGroup()