Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

## Package com.sun.mfwk.trans

Provides the classes of the Java Transaction API.

See:
Description

Interface Summary
MfConstants | MfConstants defines constants that are widely used in the monitoring interfaces.
MfGenericTransaction |
MfTranInterface | Manages errors for transaction classes.
MfTranReport | MfTranReport defines a transaction instance (report mode).
MfTransaction | MfTransaction defines a transaction instance (start/stop mode).
MfTransactionDefinition | MfTransactionDefinition defines a transaction type.
MfTransactionFactory | MfTransactionFactory provides methods to create the transaction API objects.
MfTransactionMetricsMBean | MfTransactionMetricsMBean contains the computed metrics related to transactions exposed for monitoring purpose.

Class Summary
MfGenericTransactionImpl | Generic class for transaction classes.
MfTranInterfaceImpl | Manages errors for transaction classes.
MfTransactionFactoryImpl | Implementation of the MfTransactionFactory interface
MfTransactionMetrics | MfTransactionMetrics contains the computed metrics related to a transaction type

## Package com.sun.mfwk.trans Description

Provides the classes of the Java Transaction API.

Overview

The purpose of this package is to define the transaction API included in Java ES MF.

This API is based on the Open Group standard: Application Response Measurement (ARM) 4.0 - Java binding.

The goal is to implement the semantic of this standard API, although the syntax will be simplified to fit with the Java ES MF SDK needs. The main functionalities of the API are the following:

- Measuring transactions using primitives to start and stop a transaction, and optionally block/unblock a transaction (described as option 1)
- Reporting transaction measurements using a primitive to report transaction (described as option 2)

Transaction Model

The application has two options for providing measurement data:

In Option 1, the preferred, and more widely used option, the application uses the Transaction object start() and stop() methods just before and after a transaction executes. Based on the time when these calls are made, the Transaction object memorizes the start and stop times.

In Option 2, the application makes all the measurements itself and uses the TranReport object report() method to report the data some time later. Option 2 should only be used in situations that preclude using Option 1.

Option 1 (Transaction start/stop)

Option 1 is the preferred, and most widely used option. Immediately prior to starting a transaction, the component product invokes start(). The Transaction object captures and saves the timestamp. Immediately after the transaction ends, the application calls stop(), passing the completion status of the transaction. The Transaction object captures the stop time. The difference between the stop time and the start time will be the response time of the transaction. In the same manner, the service time will be computed at stop time. Moreover, a transaction can also invoke block() and unblock() to indicate that the transaction is blocked waiting on an external request. Finally, a transaction can be linked to a parent transaction: in this case it is called a sub-transaction.

Option 2 (TranReport report)

The application itself measures the response time and service time of the transaction. After the transaction completes (the delay could be short or long), it calls report() (TranReport object) to provide the status, response time, service time, and stop time.

Selecting which Option to Use

In many situations the application can use either programming option. In general, the recommendation is to use Option 1 (separate start and stop calls), unless that is not practical.

There are two situations for which applications must use Option 2 [report()]: Option 1 requires that inline synchronous start() and stop() calls are used. The calls must be made at the moment the real transaction starts and stops. If they are not, the timings will not be accurate. If the application finds this inconvenient or impractical, it must perform the measurements itself with report().

TransactionMetrics MBean

The TransactionDefinition object contains the computed metrics related to a transaction type.

Sub-transactions

Transactions can have hierarchical relations between them. This can help to correlate transactions, to determine the cause of a transaction failure, to determine the cause of a response time problem, etc... So a sub-transaction is a transaction that have a parent transaction.

Note : Only one level of sub-transactions is supported (that is, a sub-transaction of sub-transaction is not allowed)

Sub-transactions of a transaction can run either sequencially, or in parallel (that is in multiple threads).

If a transaction is dispatched on multiple threads, the best way to handle this is to use sub-transactions: the main thread (if any) being the parent transaction, the spawned threads being the sub-transactions.
Doing this, one can get several level of metrics: the first one at the service level (that is parent transaction), the second one at the sub-task (that is sub-transation) level.

A sub-transaction is a transaction, that is has all the functionalities of any transaction (e.g. has its own related TransactionMetrics).

The TransactionMetrics of a parent transaction contains the correlation of the metrics of its sub-transactions. It means that when a parent transaction is done, it gets all the related metrics of its sub-transactions and correlate them.

Note: the sub-transaction mechanism applies to both Option 1 (Transaction start/stop) and Option 2 (TranReport report).

A parent transaction can either be associated to a thread, with its own metrics (Case 1), or be only an aggregation of a set of sub-transactions (Case 2). The following diagram describes this:

For Case 1, a parent transaction have additional metrics in its related TransactionMetrics, representing its own metrics (that is not taking into account the sub-transactions). For details, refer to TransactionMetrics object, getSingleXXX methods.

For Case 2, a parent transaction follows the same state diagram as Case 1. Start() and stop() methods can be run from any thread. At stop() time, the response time is the difference between the last sub-transaction stopped and the first sub-transaction started; the service time is the sum of all the sub-transactions service times. Block() and unblock() calls have no effect.
To specify the Case 2 is to be used, a boolean has been added in the newTransactionDefinition() method of the MfTransactionFactory (hasComputingInfo). The default is false (that is Case 1).
Case 2 is not supported for Option 2 (TranReport report).

Note:
For Option 1 (Start/Stop), if only one thread at a time is dealing with the transaction, it is possible to deal with only one transaction (no sub-transactions) by calling the transaction methods from different threads with the following condition:
- The block() and stop() methods must be called from the same thread than start() or unblock().
For example, the following scenario:
- A 1st thread picks up an incoming request, puts it in a queue, and returns.
- A 2nd thread picks it up, processes it, replies to the client, and returns.
.. should be instrumented as follows:
- The 1st thread calls start(), picks up an incoming request, puts it in a queue with a reference on the Transaction object, calls block(), and returns.
- A 2nd thread picks it up, gets the Transaction reference, calls unblock(), processes it, replies to the client, calls stop(), and returns.

Transactions state diagrams without sub-transactions

Option 1 (Start/Stop)

Option 2 (Report)

Transactions state diagrams with sub-transactions

Option 1 (Start/Stop)

Option 2 (Report)

Note: For option 2, all the sub-transaction must have called the report method before the parent transaction can call its report method. In option 1, the sub-transactions not started (that is in POOL state) are not taken into account when the parent transaction stop.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES