---

oOrient.h

Go to the documentation of this file.

#ifndef oOrient_h
#define oOrient_h 1
//------------------------------------------------------------------------------

#include "cTypes.h"
#include "oSessionManager.h"
#include "oObjectStreamCache.h"
#include "oThread.h"
#include "oLicense.h"

#include "oCurrMutex.h"
//------------------------------------------------------------------------------

/**
 * oOrient is the main class of the Orient ODBMS environment.
 * 
 * ORIENT ENVIRONMENT:
 * Before to use Orient ODBMS the client application must initialize the Orient
 * ODBMS engine.
 * 
 * In Windows® systems this operation is executed automatically at startup of
 * the application before the main() function, when the user client application
 * links the Orient ODBMS library. On application ending the library is
 * detached and the shutdown procedure of the Orient ODBMS environment is
 * called automatically. 
 * 
 * In other platforms the client application must explicitly initialize and
 * deinitialize the Orient environment before to use any Orient ODBMS APIs.
 * To initialize the Orient ODBMS environment the user application had to call
 * the oOrient::init() static method. When the application ends to use Orient
 * ODBMS can call the oOrient::deinit() static method to free Orient resources.
 * 
 * The simpler method is defining a variable of type oOrient as first thing
 * inside the main() function. The oOrient constructor calls init() and the
 * destructor calls deinit(). In this way the Orient environment will be
 * initialized when the variable will be out-of-scope.
 * 
 * For more information see the example below.
 *
 * CLIENT CACHE:
 * Each client application that use Orient has a local object cache. The
 * default size of the cache is of 512 objects. Is possible to modify the
 * client cache size calling oOrient::setCacheSize(). This permits a major
 * reuse of objects already loaded.
 *
 * MULTI-SESSION MANAGEMENT:
 * In the multi-thread version of Orient ODBMS client libraries are available
 * sessions to handle parallel multi-threads access to Orient ODBMS engine.
 * 
 * oOrient is entry-point the class for Session management.
 * 
 * USAGE:
 * oOrient      orient_env;
 * 
 * Where:
 * 
 * <orient_env>:        Is the name of variable of type oOrient.
 *
 * EXAMPLES:
 * int main( int argc, char* argv[] )
 * {
 *    * START THE ORIENT ENVIRONMENT (OPTIONAL IN WIN32 SYSTEMS)
 *    * WHEN THE VARIABLE WILL BE OUT OF SCOPE THE ENVIRONMENT 
 *    * WILL BE DEINITIALIZED.
 *   oOrient    orient_env;
 * 
 *   ...
 * }
 *
 * ODMG:
 * Extension
 */

class _ODLL oOrient
{
 public:
    /**
     * Default constructor.
     *
     * Initializes the Orient ODBMS environment calling the init() method.
     */
    oOrient ();

    /**
     * Destructor.
     *
     * Deinitializes the Orient ODBMS environment calling the deinit() method.
     */
    ~oOrient();

    /**
     * Initializes the Orient ODBMS environment.
     *
     * Must be called before to use any Orient ODBMS APIs.
     *
     * SEE ALSO:  oOrient(), deinit()
     */
    static void init ();

    /**
     * Shutdowns Orient ODBMS environment.
     *
     * Must be called after the use of Orient ODBMS. It's useful to free
     * Orient ODBMS resources (local object cache, etc).
     *
     * SEE ALSO:  ~oOrient(), init()
     */
    static void deinit ();

    /**
     * Check the status of Orient ODBMS engine.
     *
     * It returns true if the Orient ODBMS environment is initialized,
     * otherwise false.
     *
     * SEE ALSO: check_ready()
     */
    static bool is_ready();

    /**
     * Check the status of Orient ODBMS engine.
     *
     * It throws a d_Error_OrientNotInit exception if the Orient ODBMS
     * environment is not yet initialized.
     *
     * SEE ALSO: is_ready()
     */
    static void check_ready();

    /**
     * Sets the Local Client Cache size.
     *
     * Sets the Local Client Cache size to <iSize> objects. By default is 512.
     * This permits a major reuse of objects already loaded.
     *
     * The user application can change at run-time the cache size.
     *
     * SEE ALSO:  getCacheSize(), d_Object::pin(), d_Object::unpin()
     */
    static void setCacheSize (oUInt4 iSize);

    /**
     * Returns the Local Client Cache size in objects.
     *
     * By default is equals to 512.
     *
     * SEE ALSO:  setCacheSize(), d_Object::pin(), d_Object::unpin()
     */
    static oUInt4 getCacheSize ();

    /**
     * Set the cache policy for new objects created. By default is unpinned
     * that means that all objects will be created as unpinned.
     *
     * The user application can change at run-time the cache policy.
     *
     * SEE ALSO:        getCachePolicy()
     */
    static void setCachePolicy (const oObjectStreamCache::cachePolicies iPolicy);

    /**
     * Get the current cache policy. By default is unpinned
     *
     * SEE ALSO:        setCachePolicy()
     */
    static oObjectStreamCache::cachePolicies getCachePolicy ();

    /**
     * Creates a new session.
     *
     * Creates a new session called <iName>. This method creates a new thread
     * associated to the session. The thread starts at <iEntryPoint> function
     * passing <iArg> as argument.
     *
     * Optional flags can be specified for the new thread. Now are supported
     * these flags:
     *
     * flagDetached: create the thread as detached. In this the thread (and
     *               therefore the session) cannot be waited. The benefits
     *               of detached threads are that can be instanced much more
     *               rather than "joinable" threads.
     *
     * This method returns the new session created.
     *
     * This method returns immediately after that the new session is created,
     * because the new session is executed asynchronously in a new thread.
     *
     * SEE ALSO:        waitSessions ()
     */
    static oSession* createSession( d_String iName, oThread::tEntry iEntryPoint, oThread::tArgument iArg, oUInt2 iFlag = 0 );

    /**
     * Wait for one or more session to finish.
     *
     * Wait for one or more session called <iSessionName> to finish.
     *
     * If <iSessionName> is empty, then are waited all the session registered.
     *
     * If not specified any name, are waited all the sessions registered.
     *
     * SEE ALSO:        createSession ()
     */
    static bool waitSessions( d_String iSessionName = "" );

    // Internal.
    static void setTransMaxObjs (oUInt4 iSize);
    // Internal.
    static oUInt4 getTransMaxObjs ();

    static char getType( void );

  private:
    // Internal.
    static void registerSysTypes();
    // Internal.
    static void registerSysClasses ();
    // Internal.
    //static void registerSysFactory();

    // INSTALL THE APPLICATION SIGNALS TO MAKE A "SOFT" SHUTDOWN AVOIDING LOSS
    // OF DATA
    static void installSignal( void );

    // CATCH AN APPLICATION SIGNAL TO MAKE A "SOFT" SHUTDOWN AVOIDING LOSS OF DATA
    static void catchSignal( int iSignal );

    // INTERNAL.
    static void checkLicense( void );

    // INTERNAL
    static oLicense::information license;

    // Internal.
    static bool         ready;

    // Internal.
    static OCURRMUTEX   _lock;

  // FRIENDSHIPS
  friend class oSegment;
  friend class oSessionManager;
};
//------------------------------------------------------------------------------
inline bool oOrient::is_ready()
{
  return ready;
}
//------------------------------------------------------------------------------
inline void oOrient::check_ready()
{
  if( !ready )
    // ERROR: ORIENT ENVIRONMENT IS NOT YET INITIALIZED
    OERROR( d_Error_OrientNotInit, "" )
}
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

#endif

---