---

d_Transaction.h

Go to the documentation of this file.

#ifndef d_Transaction_h
#define d_Transaction_h 1

//------------------------------------------------------------------------------
#include <map>
//------------------------------------------------------------------------------
#include "oContext.h"
#include "oTxObjStreamManager.h"
//------------------------------------------------------------------------------
class _ODLL d_Object;
//------------------------------------------------------------------------------
/**
 * The transaction is a logical operation that executes more operations
 * together.
 *
 * All database operations must be executed inside an open transaction.
 * 
 * Orient ODBMS's transactions have ACID properties:
 * 
 * Atomicity:   a transaction is treated as a unit of operation. Therefore,
 *              either all or none of the transaction's actions are completed.
 * Consistency: a transaction must guaranty the consistency of the database. If
 *              a failure happens while a transaction is open or is committing
 *              the database must be consistent after the failure.
 * Isolation:   an executing transaction cannot reveal its results to other
 *              concurrent transactions before it commits.
 * Durability:  referes to the property of transactions that ensures that once
 *              a transaction commits, its results are permanent and cannot be
 *              erased from the database.
 *
 * NESTED TRANSACTIONS:
 * Orient supports nested transactions. A nested transaction is a transaction
 * open inside another transaction. All operations executed being associated
 * to the last open transaction.
 * 
 * Nested transactions are totally separate. Thus an abort to a transaction at
 * a lower level doesn't abort the higher level transaction. An abort to a
 * transaction at a higher level doesn't abort the lower level transaction.
 * 
 * There is no limit to the number of transactions nested.
 *
 * JUST EDITION:
 * The most of operations are executed only in memory without involving the
 * disk storage optimizing performance with no I/O cost until commit operation.
 *
 * ENTERPRISE EDITION:
 * The most of operations are executed only on the client side without involving
 * the Dynamic Server optimizing performance with no network traffic and leaving
 * the Dynamic Server free.
 *
 * LOCATION:
 * d_Transaction.h
 *
 * USAGE:
 * d_Transaction        <variable-name>;
 * 
 * Where:
 * 
 * <variable-name>:     Name of variable
 *
 * EXAMPLES:
 * d_Transaction                        tx;
 * 
 * tx.begin();
 * 
 * .. ..
 * 
 * tx.commit();
 *
 * ODMG:
 * Compliant 
 */
class _ODLL d_Transaction : public oContext
{
  public:

    /**
     * Default constructor.
     *
     * The constructor doesn't begin the transaction.
     *
     * Optional parameter <iDb> makes the transaction persistent for crash
     * recovery.
     *
     * ODMG    :  Compliant + Extension
     */
    d_Transaction ( d_Database* iDb = 0 );

    // Internal constructor.
    d_Transaction ( oStorage* iStg );

    /**
     * Destructor.
     *
     * If the transaction is open (begin()), then an abort will occurs.
     *
     * ODMG    :  Compliant 
     */
    ~d_Transaction();

    /**
     * Starts the transaction.
     *
     * All database operations must be executed inside an open transaction,
     * otherwise an exception d_Error_TransactionNotOpen is raised.
     *
     * If the transaction is already open, than an exception
     * d_Error_TransactionOpen is raised.
     *
     * SEE ALSO:  commit(), abort()
     * ODMG    :  Compliant + Extension
     */
    void begin( d_Database* iDb = 0 );

    /**
     * Commits the transaction.
     *
     * All database operations executed inside the transaction are committed
     * to the database permanently.
     *
     * If the transaction is not open, an exception d_Error_TransactionNotOpen
     * is raised.
     *
     * If an error occurs while the transaction commits, the transaction will
     * rollback (calling abort()) leaving the database consistent.
     *
     * After a commit, the persistent objects created in the transaction are
     * freed and the locks acquired are released. All objects loaded in the
     * transaction could be removed by local cache (see d_Object::pin(),
     * d_Object::unpin()).
     *
     * After this operation, all d_Ref and d_Ref_Any objects used in the
     * transaction will be invalid.
     *
     * SEE ALSO:  checkpoint(), abort()
     * ODMG    :  Compliant 
     */
    void commit();

    /**
     * Aborts the transaction.
     *
     * All database operations executed inside the transaction are aborted,
     * thus none of that operations take effect. If the transaction is not
     * open, an exception d_Error_TransactionNotOpen is raised.
     *
     * After an abort the persistent objects created in the transaction are
     * freed and the locks acquired are released. All objects loaded in the
     * transaction could be removed by local cache (see d_Object::pin(),
     * d_Object::unpin()).
     *
     * After this operation, all d_Ref and d_Ref_Any objects used in the
     * transaction will be invalid.
     *
     * SEE ALSO:  commit(), ~d_Transaction()
     * ODMG    :  Compliant 
     */
    void abort();

    /**
     * Commits the persistent objects in the transaction.
     *
     * All database operations executed inside the transaction are committed
     * to the database permanently.
     *
     * If the transaction is not open, an exception d_Error_TransactionNotOpen
     * is raised.
     *
     * If an error occurs while the transaction commits, the transaction will
     * rollback (calling abort()) leaving the database consistent.
     *
     * After a checkpoint, the persistent objects created in the transaction
     * are usable and the locks acquired are maintained.
     *
     * After this operation, all d_Ref and d_Ref_Any objects used in the
     * transaction remain valid.
     *
     * SEE ALSO:  commit(), abort()
     * ODMG    :  Compliant 
     */
    void checkpoint();


    /**
     * Returns true if the transaction is currently active (open by begin()
     * method), otherwise false.
     *
     * ODMG    :  Compliant 
     */
    d_Boolean is_active () const;


    /**
     * Returns the current active transaction for the current thread.
     *
     * If the transactions are nested, returns the most nested transaction.
     *
     * ODMG    :  Compliant
     */
    static d_Transaction* current();


    /**
     * Return status of transaction (see d_Transaction::statuses)
     */
    int getStatus() const;

    // Internal.
    void flushLocalObjects();

    // Internal.
    void createObject( d_Object* iObject );
    // Internal.
    void loadObject (d_Object* iObj, oObjectId& iOid);
    // Internal.
    void updateObject( d_Object* iObj );
    // Internal.
    void reserveObject( d_Object* iObject );
    // Internal.
    void deleteObject( d_Object* iObj, oObjectId& iOid );
    // Internal.
    void releaseObject( oObjectId& iOid );

    // Internal.
    virtual bool isTxAble() const;

    //--------------------------------------------------------------------------
    // CONSTANTS:
    //--------------------------------------------------------------------------
    typedef enum{ AVAIL, BEGUN, COMMITTING, ABORTING, CHECKPOINTING } statuses;

  private:
    void close();
    //--------------------------------------------------------------------------
    // ATTRIBUTES:
    //--------------------------------------------------------------------------
    oTxObjStreamManager     streamMgr;
    statuses                status;

    oVector<oObjectStream*>::iterator itObjectToRemove;
    oVector<oObjectStream*>           objectToRemove;
};
//------------------------------------------------------------------------------
/**
 * Returns always true since d_Transaction class can handle transaction.
 */
inline bool d_Transaction::isTxAble() const
{
  return true;
}
//------------------------------------------------------------------------------
inline d_Boolean d_Transaction::is_active () const
{
  return status == BEGUN ? true : false;
}
//------------------------------------------------------------------------------
inline int d_Transaction::getStatus() const
{
  return status;
}

#endif

---