---

d_Object.h

Go to the documentation of this file.

#ifndef d_Object_h
#define d_Object_h 1
//------------------------------------------------------------------------------

#include "oObjectId.h"
#include "d_Binary.h"
#include "oStreamable.h"

//------------------------------------------------------------------------------
class _ODLL d_Database;
class _ODLL d_Transaction;

class _ODLL oContext;
class _ODLL oStreamProtocol;
class _ODLL oClass;
class _ODLL oStorage;
class _ODLL oSession;

/**
 * The d_Object class is the base class for each persistent object.
 *
 * Every user objects that want to be persistent had to inherit this class.
 * 
 * It's an abstract class therefore cannot be instantiated.
 * 
 * You had to use the d_Ref template class for referencing persistent objects
 * rather than C++ pointers [see d_Ref].
 *
 * LOCATION:
 * d_Object.h
 *
 * USAGE:
 * class <user-class-name> : public d_Object
 * {
 *   ...
 * }
 * 
 * Where:
 * 
 * <user-class-name>:   is the name of user class
 *
 * EXAMPLES:
 * class Invoice : public d_Object     * Persistent class
 * {
 *   d_ULong                  number;
 *   d_Ref<Customer>          customer;
 *   d_Set< d_Ref<Product> >  products;
 * };
 *
 * SEE ALSO:
 * d_Ref, d_Ref_Any
 *
 * ODMG:
 * Compliant 
 */
class _ODLL d_Object : public oStreamable
{
  public:

    /**
     * Default constructor.
     *
     * ODMG    :  Compliant 
     */
    d_Object ();

    /**
     * Destructor.
     *
     * ODMG    :  Compliant 
     */
    virtual ~d_Object();

    /**
     * Create a transient object.
     *
     * It allocates memory for transient (not persistent) object. This is
     * the redefinition of C++ new operator. 
     *
     * ODMG    :  Compliant 
     */
    void * operator new (size_t iSize);

    /**
     * Create a persistent object.
     *
     * Allocates a persistent object of class <iClassName> into <iDb>
     * database. The database <iDb> must be opened as read_write [see
     * d_Database], a transaction must be opened and the class <iClassName>
     * must be defined as persistent class.
     *
     * ODMG    :  Compliant+ (with optional Extension)
     */
    void* operator new (size_t iSize, d_Database* iDb, const char* iClassName,
                        int iTxMode = TRANSACTIONAL );

    // Internal.
    void* operator new (size_t iSize, oStorage* iStorage, const char* iClassName,
                        int iTxMode = TRANSACTIONAL );
    // Internal.
    void* operator new (size_t iSize, oObjectId& iOid, int iTxMode );

    /**
     * Remove the object permanently in database and memory.
     *
     * ODMG    :  Compliant
     */
    void operator delete (void* iAddress );

#ifdef COMP_MSVC6
    // Internal.
    // NOTE: MSVC6 NEEDS SPECIAL DELETE OPERATORS FOR EACH NEW OPERATORS.
    void operator delete (void* iAddress, d_Database* iDb, const char* iClassName,
                          int iTxMode )
                   {d_Object::operator delete(iAddress);}
    // Internal.
    // NOTE: MSVC6 NEEDS SPECIAL DELETE OPERATORS FOR EACH NEW OPERATORS.
    void operator delete (void* iAddress, oStorage* iStorage, const char* iClassName,
                          int iTxMode )
                   {d_Object::operator delete(iAddress);}
    // Internal.
    // NOTE: MSVC6 NEEDS SPECIAL DELETE OPERATORS FOR EACH NEW OPERATORS.
    void operator delete (void* iAddress, oObjectId& iOid, int iTxMode )
                   {d_Object::operator delete(iAddress);}
#endif

    /**
     * Remove the object permanently in database and memory.
     *
     * This method is needed by collections deletion
     *
     * ODMG    :  Extension
     */
    void delete_object();

    /**
     * Mark the object as modified.
     *
     * When context commits the object will be updated on storage.
     *
     * Enterprise Edition: This operation requires an exclusive lock to
     *                     the server.
     *
     * ODMG    :  Compliant 
     */
    void mark_modified ();

    /**
     * Object activation trigger.
     *
     * It's the trigger called asynchronously by Orient ODBMS when the object
     * is requested by a context. It can be defined as a special "cache
     * constructor".
     *
     * It's useful for reset transient members before the use.
     *
     * If the user class, inherited by d_Object, doesn't define a own
     * d_activate virtual method, by default is called the
     * d_Object::d_activate() that doesn't execute any operation.
     *
     * SEE ALSO:  d_deactivate()
     * ODMG    :  Compliant
     */
    virtual void d_activate ();

    /**
     * Object deactivation trigger.
     *
     * It's the trigger called asynchronously by Orient ODBMS when the object
     * is freed in memory. It can be defined as a special "cache destructor".
     *
     * It's useful when an object had to free some memory (transient members)
     * before to die.
     *
     * If the user class, inherited by d_Object, doesn't define a own
     * d_deactivate virtual method, by default is called the
     * d_Object::d_deactivate() that doesn't execute any operation.
     *
     * SEE ALSO:  d_activate()
     * ODMG    :  Compliant
     */
    virtual void d_deactivate ();

    /**
     * STORE A NON-TRANSACTIONAL OBJECT 
     */
    void store();
    
    // Internal.
    typedef enum{ stStatic, stLoad, stNew, stCreated,
                  stReserved, stUpdated, stDeleted,
                  stCheckpointed } statuses;

    // Internal.
    typedef enum{ TRANSACTIONAL, NO_TRANSACTIONAL } txmode;

    // Internal.
    void static free( d_Object* iObject, bool removeAlsoInContext = true );

    // Internal.
    static d_Object* newObject (const size_t iSize);
    // Internal.
    static bool assignContext( d_Object* iObject, int iTxMode, bool iMandatory );
    // Internal.
    void setStreamProtocol( const char* iProtName );

    // Internal.
    virtual void toStream (oObjectStream& ioBuffer );
    // Internal.
    virtual void fromStream (oObjectStream& iBuffer );

    // Internal.
    oStorage* getStorage() const;
    // Internal.
    oClass* getClass() const;
    // Internal.
    bool is_reserved();
    // Internal.
    bool isInCache();

    /**
     * Get the oid associated with the object.
     *
     * ODMG    :  Extension
     */
    oObjectId& get_oid();

    // Internal
    void setOid( oObjectId& iOid );

    /**
     * Pin the object.
     *
     * Use this method to mark the most used objects. The Orient Object
     * Manager doesn't remove this object when the context is committed.
     *
     * Using this feature avoid loads of the same object from different
     * contexts.
     *
     * SEE ALSO:  unpin()
     * ODMG    :  Extension
     */
    void pin ();

    /**
     * Unpin the object.
     *
     * Unpin the object marked with d_Object::pin() method. Objects are
     * unpinned by default.
     *
     * SEE ALSO:  pin()
     * ODMG    :  Extension
     */
    void unpin ();

    /**
     * Trigger called before to store a new persistent object.
     *
     * It's the trigger called asynchronously by Orient ODBMS on context
     * commit before that new object is stored in database.
     *
     * Inherited class must return a boolean value: true for success, false
     * for error. If error is returned, a d_Error_TriggerBeforeNew exception
     * is thrown.
     *
     * It's useful when it needs to validate objects attributes.
     *
     * If the user class, inherited by d_Object, doesn't define a own
     * d_beforerNew virtual method, by default is called the
     * d_Object::d_beforeNew() that doesn't execute any operation.
     *
     * ODMG    :  Extension 
     */
    virtual bool d_beforeNew ();

    /**
     * Trigger called after when a persistent object is update.
     *
     * It's the trigger called asynchronously by Orient ODBMS immediately
     * after the mark_modified() method is called on the object.
     *
     * Inherited class must return a boolean value: true for success, false
     * for error. If error is returned, a d_Error_TriggerOnUpdate exception
     * is thrown.
     *
     * If the user class, inherited by d_Object, doesn't define a own
     * d_onUpdate virtual method, by default is called
     * the d_Object::d_onUpdate () that doesn't execute any operation.
     *
     * SEE ALSO:  d_beforeUpdate()
     * ODMG    :  Extension 
     */
    virtual bool d_onUpdate ();

    /**
     * Trigger called before to store an updated persistent object.
     *
     * It's the trigger called asynchronously by Orient ODBMS on context
     * commit before that updated object is stored in database.
     *
     * Inherited class must return a boolean value: true for success, false
     * for error. If error is returned, a d_Error_TriggerBeforeUpdate
     * exception is thrown.
     *
     * If the user class, inherited by d_Object, doesn't define a own
     * d_beforeUpdate virtual method, by default is called the
     * d_Object::d_beforeUpdate() that doesn't execute any operation.
     *
     * SEE ALSO:  d_onUpdate()
     * ODMG    :  Extension 
     */
    virtual bool d_beforeUpdate ();

    /**
     * Make the object transactional.
     *
     * SEE ALSO:  makeNoTransactional()
     * ODMG    :  Extension 
     */
    void makeTransactional();

    /**
     * Make the object no transactional.
     *
     * SEE ALSO:  makeTransactional()
     * ODMG    :  Extension 
     */
    void makeNoTransactional();

    // Internal.
    oContext* getContext() const;

    // Internal.
    int                 status;
    // Internal.
    oObjectStream*      origin;
    // Internal.
    oClass*             metaClass;

    //--------------------------------------------------------------------------
    // INNER CLASSES:
    //--------------------------------------------------------------------------
    class DynaFactoryConstructor
    {
    };

  private:
    // Internal.
    void setSessionPendingInfo( oSession* iSess );
    // Internal.
    virtual void toStream (oObjectStream& ioBuffer, oInterface* iInterface );
    // Internal.
    virtual void fromStream (oObjectStream& iBuffer, oInterface* iInterface );

    // Internal.
    oContext*           context;
    // Internal.
    bool                pinned;
    // Internal.
    oObjectId           oid;
    // Internal.
    oStorage*           storage;
    // Internal.
    d_Object*           containerClass;

  // FRIENDSHIPS
  friend class _ODLL d_Transaction;
};

//------------------------------------------------------------------------------
inline d_Object::~d_Object()
{
}
//------------------------------------------------------------------------------
inline void d_Object::pin ()
{
  pinned = true;
}
//------------------------------------------------------------------------------
inline void d_Object::unpin ()
{
  pinned = false;
}
//------------------------------------------------------------------------------
inline oObjectId& d_Object::get_oid()
{
  return oid;
}
//------------------------------------------------------------------------------
inline oClass* d_Object::getClass() const
{
  return metaClass;
}
//------------------------------------------------------------------------------
inline oContext* d_Object::getContext() const
{
  return context;
}
//------------------------------------------------------------------------------
inline bool d_Object::is_reserved()
{
  return status == stReserved;
}
//------------------------------------------------------------------------------
inline void d_Object::d_activate ()
{
}
//------------------------------------------------------------------------------
inline void d_Object::d_deactivate ()
{
}
//------------------------------------------------------------------------------
inline bool d_Object::d_beforeNew ()
{
  // IF NOT DEFINED BY INHERITED CLASSES RETURNS ALWAYS TRUE (OK)
  return true;
}
//------------------------------------------------------------------------------
inline bool d_Object::d_onUpdate ()
{
  // IF NOT DEFINED BY INHERITED CLASSES RETURNS ALWAYS TRUE (OK)
  return true;
}
//------------------------------------------------------------------------------
inline bool d_Object::d_beforeUpdate ()
{
  // IF NOT DEFINED BY INHERITED CLASSES RETURNS ALWAYS TRUE (OK)
  return true;
}
//------------------------------------------------------------------------------

#endif

---