---

Cdb.hh

Go to the documentation of this file.

#ifndef CDB_HH
#define CDB_HH

// File and Version Information:
//      $Id: Cdb.hh,v 1.8 2005/05/03 20:59:50 gapon Exp $

#include "CdbBase/CdbCPtrBase.hh"
#include "CdbBase/CdbPtrFwd.hh"
#include "CdbBase/CdbDatabasePtrFwd.hh"
#include "CdbBase/CdbDatabaseItr.hh"
#include "CdbBase/CdbTransaction.hh"
#include "CdbBase/CdbObjectTranslator.hh"

#include <string>

class CdbTranslatorsDictBase;

/// The starting point for the public API of the Conditions/DB.
/**
  * This is an abstract class also providing a factory interface. Its main function
  * is to locate the right instance of the Conditions/DB API.
  *
  * The second group of functionality is location of persistent databases in the store.
  */
class Cdb {

friend class CdbCPtrBase< Cdb >;    // Who destroys me.

public:

  /// The API locator.
  /**
    * Its only parameter is meant to specify which concrete instance
    * is to be returned. If it's ommited then the default value will be used
    * This default is a subject of the job's run-time configuration.
    *
    * @see Cdb::technologyName()
    * @see Cdb::implementationName()
    * @see Cdb::defaultTechnologyName()
    * @see Cdb::defaultImplementationName()
    *
    * @return a smart pointer to the interface. The 0 is returned in case of errors.
    */
    static CdbPtr instance( const char* theTechnologyName     = 0,  /**< a value of the 1-st key */
                            const char* theImplementationName = 0   /**< a value of the 2-d  key */
                          );

private:

  /// The copy constructor (NOT IMPLEMENTED)
  /**
    * Is disabled...
    */
    Cdb( const Cdb& theCdb );

  /// The assignment operator (NOT IMPLEMENTED)
  /**
    * Is disabled...
    */
    Cdb& operator=( const Cdb& theCdb );

protected:

  /// The default constructor.
  /**
    * More details...
    */
    Cdb( );

  /// The destructor
  /**
    * The destructor is protected to prevent clients from deleting
    * objects which may be shared with others.
    */
    virtual ~Cdb( );

  /// Add a new entry to the registry.
  /**
    * This _proxy_ method is meant to be used by subclasses to register themselves
    * in the dictionary through the dictionary's protected interface.
    * 
    * @see CdbEnvironment::set()
    */
    CdbStatus set( CdbPtr& thePtr );

  /// Find an entry matching specified keys in the registry.
  /**
    * This _proxy_ method is meant to be used by subclasses to find themselves
    * in the dictionary through the dictionary's protected interface.
    * 
    * @see CdbEnvironment::get()
    */
    CdbStatus get( CdbPtr&     thePtr,
                   const char* theTechnologyName,
                   const char* theImplementationName );

public:

  /// Return the technology name
  /**
    * This method has to be implemented by subclasses.
    */
    virtual const char* technologyName( ) const = 0;

  /// Return the implementation name
  /**
    * This method has to be implemented by subclasses.
    */
    virtual const char* implementationName( ) const = 0;

  /// Initialize the API
  /**
    * This method needs to be called at least once during the lifetime
    * of the API's implementation to have it properly functioning. The main reason
    * to do this initialization explicitly is to avoid "initialization upon construction",
    * which is not welcome by certain clients of CDB API.
    *
    * @see Cdb::isInitialized()
    *
    * This method has to be implemented by subclasses.
    */
    virtual void initialize( ) = 0;

  /// Check if the API is initialized
  /**
    * This method can be used to check the current status of an API implementation.
    *
    * @see Cdb::initialize()
    *
    * This method has to be implemented by subclasses.
    */
    virtual bool isInitialized( ) = 0;

  /// Get default database name
  /**
    * This method is supposed to be implemented by subclasses.
    */
    virtual CdbStatus getDefaultDatabase( std::string& theDatabaseName  /**< the database name to be returned */
                                        ) = 0;

  /// Get default view name
  /**
    * This method is supposed to be implemented by subclasses.
    *
    * NOTE: 0 pointer is NOT allowed where the database name is expected.
    */
    virtual CdbStatus getDefaultView( std::string& theViewName,     /**< the view name to be returned */
                                      const char*  theDatabaseName  /**< the scope of the operation */
                                    ) = 0;

  /// Set default database name
  /**
    * NOTE: 0 pointers or empty strings ("") are NOT allowed as values of parameters.
    *
    * This method is supposed to be implemented by subclasses.
    */
    virtual CdbStatus setDefaultDatabase( const char* theDatabaseName   /**< the database name to be set */
                                        ) = 0;

  /// Set default view name
  /**
    * NOTE: 0 pointers or empty strings ("") are NOT allowed as values of parameters.
    *
    * This method is supposed to be implemented by subclasses.
    */
    virtual CdbStatus setDefaultView( const char* theViewName,      /**< the view name to be returned */
                                      const char* theDatabaseName   /**< the scope of the operation */
                                    ) = 0;

  /// Find the specified Database
  /**
    * This method is supposed to be implemented by subclasses.
    *
    * This method initializes a smart pointer to a transient object of
    * the CdbDatabase class representing the found database. It will initialize the smart
    * pointer to point onto 0 and return the corresponding error status
    * when specified object is not found or is not awailable for some
    * other reason.
    *
    * The database is specified through its name. If the name is not specified then
    * the default database will be found and open.
    *
    * @see CdbDatabase
    * @see CdbDatabasePtr
    * @see CdbStatus
    *
    * @return a completion status of the operation
    */
    virtual CdbStatus findDatabase( CdbDatabasePtr& thePtr,             /**< a smart pointer to set up */
                                    const char*     theDatabaseName = 0 /**< the database name */
                                  ) = 0;

  /// Initialize an instance of an iterator for the known databases names
  /**
    * This method is supposed to be implemented by subclasses.
    *
    * The iterator will be set into a "valid" state upon successfull completion.
    *
    * @see CdbIItr::isValid()
    * @see CdbDatabase
    * @see CdbDatabaseItr
    * @see CdbStatus
    *
    * @return completion status
    */
    virtual CdbStatus databaseIterator( CdbDatabaseItr& theItr ) = 0;

  /// Register a user defined "persistent-to-transient" translator
  /**
    * A non-zero pointer is expected as a value of the method's parameter.
    * Also, note that the method will take an ownership of the passed object.
    *
    * @see class CdbObjectTranslator
    */
    virtual CdbStatus registerTranslator( CdbObjectTranslator* theTranslatorPtr );

  /// Find a user defined "persistent-to-transient" translator
  /**
    * The method will look for the translator matching the specified transient
    * type identifier and the persistent type. The translator is supposed to be
    * registered for the current technology/implementation of the CDB API using
    * the Cdb::registerTranslator() method.
    *
    * @see class CdbType2Id
    * @see Cdb::registerTranslator()
    */
    virtual CdbStatus findTranslator( CdbCPtr<CdbObjectTranslator>& theTranslatorPtr,
                                      unsigned int                  theTransientTypeId,
                                      const std::string&            thePersistentTypeName ) const;

protected:

    friend class CdbTransaction;  // the one who's allowed to use the method defined below.

  /// Get the transaction manager and start new transaction if needed
  /**
    * This method is used by the CdbTransaction class in implementing the technology-neutral
    * transaction management. Calling this method and returning a non-zero object will ensure
    * an existince of transaction of the specified more. The object's ownership is also returned
    * along with the object. When the object gets destroyed then the transaction should return
    * to its previous state (the one before calling this method).
    *
    * The method is supposed to be implemented by technology-specific implementations of
    * the current class. Any errors during the method's execution should be reported
    * in a form of the 0 pointer.
    *
    * @see class CdbTransactionBase
    * @see class CdbTransaction
    */
    virtual CdbTransactionBase* transaction( CdbTransaction::Mode theMode ) const = 0;

private:

  // A dictionary of translators

    CdbCPtr< CdbTranslatorsDictBase > _myTranslatorsDict;
};

#endif  // CDB_HH

---