it.list.jft
Interface Transaction

All Superinterfaces:
ActivityLifeCycle, CommunicationLifeCycle, LifeCycle

public interface Transaction
extends ActivityLifeCycle

A client's request to the server to add, remove or modify an entity in its own Data Base.

Transaction Usage

A new transaction (i.e. a new client's request to the server) is defined by: Once the transaction is properly sent to the server:

The TransactionID of a sent transaction may be saved, i.e. the 5 int values that represents the TransactionID may be properly saved (see TransactionID for details). From these saved values it's possibile to recreate the original TransactionID and then create a Transaction object, that represents this past transaction, using the following two values:

In this manner this created Transaction object may be used to query the status of this past Transaction to the server.
In brief:
Transactions are locally created by Context.makeTransaction() in which the transaction parameters are described by TransactionParam and the event listeners are described by TransactionListener.

Once locally created a transaction may be sent to the server, and/or its status may be queried to the server.
It is also possibile to query the status of a past pending transaction if the programmer created a new Transaction with a saved TransactionID of a sent transaction.

Transaction Lifecycle

See Also:
Context.makeTransaction(), TransactionParam, TransactionListener

Field Summary
static int STATUS_ABORTED
          Lifecycle and Transaction status: Transaction completed unsuccessfully and ready to be released.
static int STATUS_COMMITTED
          Lifecycle and Transaction status: Transaction completed successfully and ready to be released.
static int STATUS_FLYING
          Lifecycle and Transaction status: Transaction is flying waiting to become STATUS_COMMITTED or STATUS_ABORTED.
 
Fields inherited from interface ActivityLifeCycle
RESULT_INVALID_CONNECTION_STATUS
 
Fields inherited from interface LifeCycle
RESULT_GENERIC_ERROR, RESULT_INVALID_STATUS, RESULT_OK, STATUS_INIT, STATUS_RELEASED
 
Method Summary
 TransactionID getTransactionID()
          Returns the TransactionID of this (new or past) transaction.
 int query()
          Try to query the server for the status of this (new or past) transaction.
 int send()
          Try to send this new transaction to the server.
 
Methods inherited from interface ActivityLifeCycle
getConnection
 
Methods inherited from interface CommunicationLifeCycle
getContext, getListener, getParam
 
Methods inherited from interface LifeCycle
enumChilds, getStatus, release
 

Field Detail

STATUS_FLYING

static final int STATUS_FLYING
Lifecycle and Transaction status: Transaction is flying waiting to become STATUS_COMMITTED or STATUS_ABORTED.
This value may be returned by LifeCycle.getStatus().

Status Entry:
STATUS_INITsend() ok → STATUS_FLYING.
STATUS_INITquery() ok → STATUS_FLYING.
Status Activities:
query(),
or waiting an automatic onTransactionSend() call,
or waiting an automatic onTransactionQuery() call.
Status Exit:
STATUS_FLYINGonTransactionSend() bad → STATUS_ABORTED.
STATUS_FLYINGonTransactionQuery() RESULT_COMMITTEDSTATUS_COMMITTED.
STATUS_FLYINGonTransactionQuery() RESULT_INVALID_TRANSACTION_IDSTATUS_ABORTED.
STATUS_FLYINGonTransactionQuery() RESULT_GENERIC_ERRORSTATUS_ABORTED.
STATUS_FLYINGonTransactionQuery() RESULT_ABORTEDSTATUS_ABORTED.

See Also:
Transaction lifecycle, Constant Field Values

STATUS_COMMITTED

static final int STATUS_COMMITTED
Lifecycle and Transaction status: Transaction completed successfully and ready to be released.
This value may be returned by LifeCycle.getStatus().

It's always a good practice to release a Transaction in this status.

Status Entry:
STATUS_FLYINGonTransactionQuery() RESULT_COMMITTEDSTATUS_COMMITTED.
Status Activities:
LifeCycle.release().
Status Exit:
STATUS_COMMITTEDLifeCycle.release()STATUS_RELEASED.

See Also:
Transaction lifecycle, Constant Field Values

STATUS_ABORTED

static final int STATUS_ABORTED
Lifecycle and Transaction status: Transaction completed unsuccessfully and ready to be released.
This value may be returned by LifeCycle.getStatus().

It's always a good practice to release a Transaction in this status.

Status Entry:
STATUS_FLYINGonTransactionSend() bad → STATUS_ABORTED.
STATUS_FLYINGonTransactionQuery() RESULT_INVALID_TRANSACTION_IDSTATUS_ABORTED.
STATUS_FLYINGonTransactionQuery() RESULT_GENERIC_ERRORSTATUS_ABORTED.
STATUS_FLYINGonTransactionQuery() RESULT_ABORTEDSTATUS_ABORTED.
Status Activities:
LifeCycle.release().
Status Exit:
STATUS_ABORTEDLifeCycle.release()STATUS_RELEASED.

See Also:
Transaction lifecycle, Constant Field Values
Method Detail

send

int send()
Try to send this new transaction to the server.

This method must be called only when

If this method invocation completed successfully,
then

otherwise

In the latter case it is a good practice to release this Transaction.

Returns:

query

int query()
Try to query the server for the status of this (new or past) transaction.

This method must be called only when

If this method invocation completed successfully,
then

otherwise

In the latter case it is a good practice to release this Transaction.

Returns:

getTransactionID

TransactionID getTransactionID()
Returns the TransactionID of this (new or past) transaction.

If there is a valid past TransactionID then this method returns it, otherwise it returns the new TransactionID that will be used by the send() method.

Returns:
the TransactionID of this (new or past) transaction.
null is returned when the past TransactionID exists but it does not belongs to the associated connection.


Submit a bug or feature to FT\API Programming Support<\font>