org.arm4.arm40.transaction.ArmInterface
org.arm4.arm40.transaction.ArmTransaction
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
public class ArmTransaction
For most applications, ArmTransaction is the most important of all the ARM classes, and the most frequently used. 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 VM. ArmTransaction is created with the newArmTransaction() method of ArmTransactionFactory.
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.
| Field Summary | |
|---|---|
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
|
| Fields inherited from class org.arm4.arm40.transaction.ArmInterface |
|---|
m_errorCode, m_factory |
| Constructor Summary | |
|---|---|
ArmTransaction(ArmApplication app,
ArmTransactionDefinition def,
ArmFactory factory)
Create the ARM Transaction. |
|
ArmTransaction(ArmApplication app,
ArmTransactionDefinition def,
ArmMetricGroup group,
ArmFactory factory)
Create the ARM Transaction. |
|
| 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. |
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. |
| Methods inherited from class org.arm4.arm40.transaction.ArmInterface |
|---|
getErrorCode, getErrorMessage, getFactory, setErrorCode, setFactory |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Methods inherited from interface org.opengroup.arm40.transaction.ArmInterface |
|---|
getErrorCode, getErrorMessage, setErrorCode |
| Field Detail |
|---|
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
| Constructor Detail |
|---|
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 - | Method Detail |
|---|
public int bindThread()
ArmTransactionArmTransaction.unbindThread() is executed in
this thread or stop() or reset() is
executed.
bindThread in interface ArmTransactionArmInterface).public long blocked()
ArmTransactionstart() 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 ArmTransactionunblocked()
method call.public ArmApplication getApplication()
ArmTransactionnewArmTransaction() method of
ArmTransactionFactory.
getApplication in interface ArmTransactionArmApplication.public java.lang.String getContextURIValue()
ArmTransactionArmTransaction.getContextURIValue().
getContextURIValue in interface ArmTransactionnull.public java.lang.String getContextValue(int index)
ArmTransactionArmTransaction.setContextValue(int, String).
getContextValue in interface ArmTransactionindex - index into the context properties array.
index, or
null.public ArmCorrelator getCorrelator()
ArmTransactionstart() 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 ArmTransactionpublic ArmCorrelator getParentCorrelator()
ArmTransactionstart() method.
If no value was set on the start() method, or if
start() has never executed, it returns
null.
getParentCorrelator in interface ArmTransactionnull.public int getStatus()
ArmTransactionstop() method.
If stop() has never executed, it returns
STATUS_INVALID.
getStatus in interface ArmTransactionArmConstants.public ArmTransactionDefinition getDefinition()
ArmTransactionnewArmTransaction() method of
ArmTransactionFactory.
getDefinition in interface ArmTransactionArmTransactionDefinition metadata.public ArmUser getUser()
ArmTransactionArmUser currently asociated with this
transaction instance.
See description of ArmTransaction.setUser(ArmUser).
getUser in interface ArmTransactionArmUser, or null.public boolean isTraceRequested()
ArmTransactionfalse.
See description of ArmTransaction.setTraceRequested(boolean).
isTraceRequested in interface ArmTransactionpublic int reset()
ArmTransactionstart() 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 ArmTransactionArmInterface).public int setArrivalTime()
ArmTransactionstart().
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 ArmTransactionArmInterface).public int setContextURIValue(java.lang.String value)
ArmTransactionArmTransaction.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 ArmTransactionvalue - the URI context value.
ArmInterface).
public int setContextValue(int index,
java.lang.String value)
ArmTransactionArmTransaction.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 ArmTransactionindex - index into the context properties array.value - the new context property value.
ArmInterface).public int setTraceRequested(boolean traceState)
ArmTransactionArmTransaction.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 ArmTransactiontraceState - trace request state.
ArmInterface).public int setUser(ArmUser user)
ArmTransactionArmTransaction 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 ArmTransactionuser - 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 ArmTransactionArmInterface).public int start(byte[] parentCorr)
ArmTransactionArmTransaction.start().
start in interface ArmTransactionparentCorr - a parent correlator for this transaction, represented as an
array of bytes.
ArmInterface).
public int start(byte[] parentCorr,
int offset)
ArmTransactionArmTransaction.start().
start in interface ArmTransactionparentCorr - 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)
ArmTransactionArmTransaction.start().
start in interface ArmTransactionparentCorr - a parent correlator object for this transaction.
ArmInterface).public int stop(int status)
ArmTransactionstop()
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 ArmTransactionstatus - 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)
ArmTransactionstop() 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 ArmTransactionstatus - 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
ArmInterface).public int unbindThread()
ArmTransactionArmTransaction.bindThread().
unbindThread in interface ArmTransactionArmInterface).public int unblocked(long blockHandle)
ArmTransactionArmTransaction.blocked().
unblocked in interface ArmTransactionblockHandle - handle returned from a previous
blocked() method call.
ArmInterface).public int update()
ArmTransactionstart() 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 ArmTransactionArmInterface).public int setParentCorrelator(ArmCorrelator parent)
parent -
public int setCorrelator(ArmCorrelator correlator)
correlator -
protected ArmMetricGroup getMetricGroup()
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||