---

CdbDatabase.hh

Go to the documentation of this file.

#ifndef CDB_DATABASE_HH
#define CDB_DATABASE_HH

// File and Version Information:
//      $Id: CdbDatabase.hh,v 1.16 2005/08/16 22:23:53 gapon Exp $

#include "CdbBase/CdbStateControl.hh"
#include "CdbBase/CdbHistoryProvider.hh"
#include "CdbBase/CdbCloneable.hh"

#include "CdbBase/CdbCPtrBase.hh"
#include "CdbBase/CdbPtrFwd.hh"
#include "CdbBase/CdbOriginPtrFwd.hh"
#include "CdbBase/CdbDatabasePtrFwd.hh"
#include "CdbBase/CdbPartitionPtrFwd.hh"
#include "CdbBase/CdbViewPtrFwd.hh"
#include "CdbBase/CdbViewItr.hh"
#include "CdbBase/CdbConditionPtrFwd.hh"

#include "CdbBase/CdbItr.hh"

#include <string>

class CdbId;
class CdbCompositeName;

/// The transient representation for the persistent database and its smart pointer type
/**
  * Notes:
  *
  * - this is an abstract class specifying the interface to the databases.
  *   It also maintains the general status of the database object as it's seen to its
  *   clients through the API.
  *
  * - this class includes the CdbStateControl,
  *   CdbHistoryProvider and CdbCloneable interfaces.
  *
  * - there is a definition for the smart pointer class CdbDatabasePtr which is meant
  *   to be used by the clients of the Database class.
  *
  * - objects of this class will be destructed automatically by the smart pointer.
  *
  * @see CdbtateControl
  * @see CdbHistoryProvider
  * @see CdbCloneable
  */
class CdbDatabase : public    CdbStateControl,
                    public    CdbHistoryProvider,
                    protected CdbCloneable< CdbDatabase > {

friend class CdbCPtrBase< CdbDatabase >;

private:

  /// The default constructor (NOT IMPLEMENTED)
  /**
    * More details...
    */
    CdbDatabase( );

protected:

  /// The normally used constructor will set the internal parameters
  /// of an object.
  /**
    * Initialize the context of the database with specified set of parameters. This
    * will also validate the internal state of the object.
    *
    * The database name must not be a 0 pointer.
    */
    CdbDatabase( const CdbPtr& theCdbPtr,   /**< the back link to the parent object */
                 const char*   theName      /**< the database name */
               );

  /// The copy constructor
  /**
    * Details...
    */
    CdbDatabase( const CdbDatabase& theDatabase );

  /// The destructor.
  /**
    * Is only available for the derived classes and friends to prevent accidental
    * deletion of objects.
    */
    virtual ~CdbDatabase( );

  /// The assignment operator
  /**
    * Details...
    */
    CdbDatabase& operator=( const CdbDatabase& theDatabase );

public:

  /// Static locator for a database object
  /**
    * Locates specified database object and returns a smart pointer to the transient
    * object of the current class. This "shortcut" allows to avoid the complicated
    * multi-staged process of the object location, which is useless when
    * the intermediate objects are not needed.
    *
    * If the database name is omitted then the default one is assumed.
    *
    * The last parameter (a pointer to the top-level Cdb singleton) is optional. If 0 is
    * passed then a default instance is used.
    *
    * Note, that if specified object is not found then a smart pointer is initialized
    * to point to 0.
    *
    * @see Cdb
    * @see CdbatabasePtr
    * @see CdbStatus
    *
    * @return a completion status
    */
    static CdbStatus instance( CdbDatabasePtr& theDatabasePtr,              /**< the smart pointer to be initialized */
                               const char*     theDatabaseName       = 0,   /**< the database name */
                               const char*     theImplementationName = 0,   /**< the implementation name */
                               const char*     theTechnologyName     = 0    /**< the technology name */
                             );

public:

  /// Return a pointer to the parent object.
  /**
    * @see Cdb
    * @see CdbPtr
    */
    const CdbPtr& parent( ) const;

  /// Obtain the current name of the database.
  /**
    * @return a const non 0 pointer onto a database name
    */
    const char* name( ) const;

  /// Obtain the unique identifier of the database.
  /**
    * All databases in a distributed installation should have the same identifier
    * to distinguish them from other installations.
    *
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * @return the value of the identifier
    */
    virtual BdbTime id( ) = 0;

  /// Obtain the creation time of the database
  /**
    * This is the actual creation time of this particular instance of the underlying database.
    * Note, that this value may differ (in fact it's equal or newer) from the database
    * identification timestampt.
    *
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * @return a string with the object's description
    */
    virtual BdbTime created( ) = 0;

  /// Obtain the database description
  /**
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * @return a string with the object's description
    */
    virtual std::string description( ) = 0;

  /// Set up an iterator of partitions at the MASTER
  /**
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * @return CdbStatus::Success if the iterator is set up
    */
    virtual CdbStatus partitionIterator( CdbItr<unsigned short>& theItr     /**< the iterator to set up */
                                       ) = 0;

  /// Set up an iterator of partitions at specified (by ID) origin
  /**
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * @return CdbStatus::Success if the iterator is set up, CdbStatus::NotFound
    *         if the specified origin does not have Partitions Layout.
    */
    virtual CdbStatus partitionIterator( CdbItr<unsigned short>& theItr,        /**< the iterator to set up */
                                         unsigned int            theOriginId    /**< the origin in question */
                                       ) = 0;

  /// Set up an iterator of partitions at specified (by NAME) origin
  /**
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * @return CdbStatus::Success if the iterator is set up, CdbStatus::NotFound
    *         if the specified origin does not have Partitions Layout.
    */
    virtual CdbStatus partitionIterator( CdbItr<unsigned short>& theItr,        /**< the iterator to set up */
                                         const char*             theOriginName  /**< the origin in question */
                                       ) = 0;

  /// Find a partition
  /**
    * IMPORTANT NOTE:
    *
    *   This algorithm will use partition object from the local
    *   P-Layout if it will discover that the partition belongs to the current
    *   origin. This is a typical scenario for the SLAVE type origins.
    *
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * @return CdbStatus::Success if the partition was found
    */
    virtual CdbStatus findPartition( CdbPartitionPtr& thePtr,       /**< the smart pointer to set up */
                                     unsigned short   thePartition  /**< the partition identifier */
                                   ) = 0;

  /// Find a partition at the specified (by ID) origin
  /**
    * Unlike the default algorithm (when no explicit origin specified) this one
    * would use partition directly from the specified origin.
    *
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * @return CdbStatus::Success if the partition was found
    */
    virtual CdbStatus findPartition( CdbPartitionPtr& thePtr,       /**< the smart pointer to set up */
                                     unsigned short   thePartition, /**< the partition identifier */
                                     unsigned int     theOriginId   /**< the origin in question */
                                   ) = 0;

  /// Find a partition at the specified (by NAME) origin
  /**
    * Unlike the default algorithm (when no explicit origin specified) this one
    * would use partition directly from the specified origin.
    *
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * @return CdbStatus::Success if the partition was found
    */
    virtual CdbStatus findPartition( CdbPartitionPtr& thePtr,       /**< the smart pointer to set up */
                                     unsigned short   thePartition, /**< the partition identifier */ 
                                     const char*      theOriginName /**< the origin in question */ 
                                   ) = 0;

  /// Return a pointer to the database's "origin" object.
  /**
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * @see CdbOrigin
    * @see CdbOriginPtr
    */
    virtual CdbOriginPtr localOrigin( ) = 0;

  /// Set up an iterator of origins
  /**
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * @return CdbStatus::Success if the iterator is set up
    */
    virtual CdbStatus originIterator( CdbItr<unsigned short>& theItr    /**< the iterator to set up */
                                    ) = 0;

  /// Find an origin (by name)
  /**
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * @return CdbStatus::Success if the origin was found
    */
    virtual CdbStatus findOrigin( CdbOriginPtr& thePtr,     /**< the smart pointer to set up */
                                  const char*   theName     /**< the name of an origin */
                                ) = 0;

  /// Find an origin (by id)
  /**
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * @return CdbStatus::Success if the origin was found
    */
    virtual CdbStatus findOrigin( CdbOriginPtr&  thePtr,    /**< the smart pointer to set up */
                                  unsigned short theId      /**< the identifier of an origin */
                                ) = 0;

  /// Default view name
  /**
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * This name is delivered when a client is relying on this default.
    */
    virtual std::string defaultView( ) const = 0;

  /// Find the specified view
  /**
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * This method initializes a smart pointer to a transient object
    * of the CdbView class representing the found view. 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 only parameter to be specified when looking for a view is its name. If
    * a 0 pointer is passed instead of the name then a default view will be open.
    *
    * @see CdbView
    * @see CdbViewPtr
    * @see CdbStatus
    *
    * @return a completion status of the operation
    */
    virtual CdbStatus findView( CdbViewPtr& thePtr,         /**< a smart pointer to an object to be initialized */
                                const char* theName = 0     /**< the object specifications */
                              ) = 0;

  /// Find the specified view
  /**
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * Unlike the previous method, this one uses "extended" identifier of a view
    * to find the corresponding object.
    *
    * @see CdbId
    */
    virtual CdbStatus findView( CdbViewPtr&  thePtr,        /**< a smart pointer to an object to be initialized */
                                const CdbId& theId          /**< the object specifications */
                              ) = 0;

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

  /// Initialize an instance of an iterator for the known 'physical' conditions
  /**
    * The iterator will produce a sequence of 'physical address' of found conditions
    * in a scope of all origins of the dataase. Use the "CdbDatabase::findCondition()"
    * method defined below to open actual conditions.
    *
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * The iterator will be set into a "valid" state upon successfull completion.
    *
    * @see CdbIItr::isValid()
    * @see CdbView
    * @see CdbViewItr
    * @see CdbStatus
    *
    * @return completion status
    */
    virtual CdbStatus physicalConditionIterator( CdbItr<CdbId>& theItr ) = 0;

  /// Translate a string with a name of a 'physical' condition into its identifier
  /**
    * The operation will return CdbStatus::Success and set up a valid identifier
    * if the input name has a correct format and if the corresponding condition
    * is known to CDB.
    *
    * If an input name is valid but the condition doesn't exist in the database
    * then CdbStatus::NotFound will be returned.
    *
    * Other status values returned will depend on what exactly is wrong.
    */
    CdbStatus physicalConditionName2Id( CdbId&                  theId,
                                        const CdbCompositeName& theName );

  /// Translate an identifier of a 'physical' condition into its name
  /**
    * The operation will return CdbStatus::Success and set up a valid identifier
    * if the input name has a correct format and if the corresponding condition
    * is known to CDB.
    *
    * If an input name is valid but the condition doesn't exist in the database
    * then CdbStatus::NotFound will be returned.
    *
    * Other status values returned will depend on what exactly is wrong.
    */
    CdbStatus physicalConditionId2Name( CdbCompositeName& theName              ,
                                        const CdbId&      theId );

  /// Find the specified condition by its 'physical address'
  /**
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * This method would locate a condition by its 'physical address'. See the description
    * of the constructor of the CdbCondition class for the implications of this method.
    *
    * @see CdbId
    */
    virtual CdbStatus findCondition( CdbConditionPtr& thePtr,   /**< a smart pointer to an object to be initialized */
                                     const CdbId&     theId     /**< the object specifications */
                                   ) = 0;

  /// Find the specified condition by its 'physical name'
  /**
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * This method would locate a condition by its 'physical name'. See the description
    * of the constructor of the CdbCondition class for the implications of this method.
    *
    * @see CdbCompositeName
    */
    virtual CdbStatus findCondition( CdbConditionPtr&        thePtr,            /**< a smart pointer to an object to be initialized */
                                     const CdbCompositeName& thePhysicalName    /**< the object specifications */
                                   ) = 0;

private:

    CdbPtr      _myParentPtr;
    std::string _myName;
};

#endif  // CDB_DATABASE_HH

---