---

CdbCondition.hh

Go to the documentation of this file.

#ifndef CDB_CONDITION_HH
#define CDB_CONDITION_HH

// File and Version Information:
//      $Id: CdbCondition.hh,v 1.25 2005/09/15 05:04:11 gapon Exp $

#include "BdbTime/BdbTime.hh"

#include "CdbBase/CdbCommon.hh"

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

#include "CdbBase/CdbCPtrBase.hh"
#include "CdbBase/CdbObjectPtrFwd.hh"
#include "CdbBase/CdbRevisionPtrFwd.hh"
#include "CdbBase/CdbConditionPtrFwd.hh"
#include "CdbBase/CdbFolderPtrFwd.hh"
#include "CdbBase/CdbDatabasePtrFwd.hh"

#include "CdbBase/CdbItr.hh"
#include "CdbBase/CdbObjectItr.hh"

#include "CdbBase/CdbPathName.hh"

#include <string>

class CdbObjectFactoryBase;
class CdbRevisionPolicy;
class CdbId;
class CdbCompositeName;

/// The transient representation for the persistent Condition.
/**
  * Note, that this is an abstract class specifying the interface to the condition.
  * It also maintains the general status of the Condition object as it's seen to its
  * clients through the API.
  *
  * This class also includes the CdbStateControl, CdbHistoryProvider
  * and CdbCloneable interfaces.
  *
  * @see CdbStateControl
  * @see CdbHistoryProvider
  */
class CdbCondition : public    CdbStateControl,
                     public    CdbHistoryProvider,
                     protected CdbCloneable< CdbCondition > {

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

public:

  /// Static locator for a condition
  /**
    * Locates specified condition 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.
    *
    * 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 CdbConditionPtr
    * @see CdbStatus
    *
    * @return a completion status
    */
    static CdbStatus instance( CdbConditionPtr& theConditionPtr,            /**< the smart pointer to be initialized */
                               const char*      theFullPathName,            /**< the full path name of the condition */
                               const char*      theViewName           = 0,  /**< the view name */
                               const char*      theDatabaseName       = 0,  /**< the database name */
                               const char*      theImplementationName = 0,  /**< the implementation name */
                               const char*      theTechnologyName     = 0   /**< the technology name */
                             );

  /// Static locator for a condition
  /**
    * Unlike the previous method, this one uses "extended" identifier of a view
    * instead of its name.
    *
    * @see CdbId
    */
    static CdbStatus instance( CdbConditionPtr& theConditionPtr,            /**< the smart pointer to be initialized */
                               const char*      theFullPathName,            /**< the full path name of the condition */
                               const CdbId&     theViewId,                  /**< the view identifier */
                               const char*      theDatabaseName       = 0,  /**< the database name */
                               const char*      theImplementationName = 0,  /**< the implementation name */
                               const char*      theTechnologyName     = 0   /**< the technology name */
                             );

  /// Static locator for a condition
  /**
    * Unlike the previous methods, this one uses "physical address" of a condition.
    *
    * @see CdbId
    */
    static CdbStatus instance( CdbConditionPtr& theConditionPtr,            /**< the smart pointer to be initialized */
                               const CdbId&     thePhysicalAddress,         /**< the 'physical address' of a condition */
                               const char*      theDatabaseName       = 0,  /**< the database name */
                               const char*      theImplementationName = 0,  /**< the implementation name */
                               const char*      theTechnologyName     = 0   /**< the technology name */
                             );

  /// Static locator for a condition
  /**
    * Unlike the previous methods, this one uses "physical name" of a condition.
    *
    * @see CdbCompositeName
    */
    static CdbStatus instance( CdbConditionPtr&        theConditionPtr,             /**< the smart pointer to be initialized */
                               const CdbCompositeName& thePhysicalName,             /**< the 'physical name' of a condition */
                               const char*             theDatabaseName       = 0,   /**< the database name */
                               const char*             theImplementationName = 0,   /**< the implementation name */
                               const char*             theTechnologyName     = 0    /**< the technology name */
                             );

  /// Static locator for a condition
  /**
    * The method is able to deal with multiple formats of the condition name, including
    * the above mentioned:
    *
    *   <path>             - a full path to the condition in a view:                       "/emc/EmcFooClassP"
    *   <physical address> - a 'physical' address of the condition in the Distributed CDB: "0::112"
    *   <physical name>    - a 'physical' name of the condition in the Distributed CDB:    "MASTER::EmcFooClassP"
    *
    * @see CdbCompositeName
    */
    static CdbStatus instanceFromAny( CdbConditionPtr& theConditionPtr,             /**< the smart pointer to be initialized */
                                      const char*      theConditionName,            /**< the 'any' name of a condition */
                                      const char*      theDatabaseName       = 0,   /**< the database name */
                                      const char*      theImplementationName = 0,   /**< the implementation name */
                                      const char*      theTechnologyName     = 0    /**< the technology name */
                                    );

  /// Calculate the full path for the condition
  /**
    * The path would include all preceeding folders and the specified condition
    * itself.
    *
    * The method will return an empty path containing "" in case of any problem met
    * while calculating the path.
    *
    * NOTE: For conditions found via their 'physical' names or addresses the nethod
    *       will return that empty path since their (CdbCondition) API objects
    *       do not have any parent folders or views.
    *
    * @see class CdbCondition
    */
    static std::string fullPathName( const CdbConditionPtr& theConditionPtr );

private:

  /// The default constructor (IS NOT IMPLEMENTED)
  /**
    * Is disabled...
    */
    CdbCondition( );

protected:

  /// The normally used constructor will set the internal parameters of an object.
  /**
    * Initialize the context of the CdbCondition with specified set of fixed parameters.
    * This will also validate the internal state of the object.
    *
    * The condition name must be non 0 pointer.
    *
    * This API component has two parameters to specify its "parent" API objects. Their values
    * would vary depending on how the Condition API object was created:
    *
    *   - for conditions found through views the parent folder must be a non zero
    *     pointer. The database pointer must always have a non zero value.
    *
    *   - for conditions located by their 'physical address' or 'physical name' the only valid
    *     connection to a hierarchy of API components is through the non zero database pointer.
    *     The folder pointer must be zero in this case.
    *
    * The value of the folder pointer can also be used as flags to determine
    * how the condition was created.
    *
    * @see CdbFolder
    * @see CdbFolderPtr
    * @see CdbDatabase
    * @see CdbDatabasePtr
    * @see CdbCompositeName
    * @see CdbId
    */
    CdbCondition( const CdbFolderPtr&   theFolderPtr,       /**< the parent folder object (view conditions only) */
                  const CdbDatabasePtr& theDatabasePtr,     /**< the parent database object */
                  const char*           theName             /**< the name in its folder's namespace */
                );

  /// The copy constructor
  /**
    * Details...
    */
    CdbCondition( const CdbCondition& theCondition );

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

  /// The assignment operator
  /**
    * Details...
    */
    CdbCondition& operator=( const CdbCondition& theCondition );

public:

  /// Return a smart pointer to the parent CdbFolder object.
  /**
    * This is a folder where this condition is directly connected to. Note, that for conditions
    * found through their 'physical' names or addresses the returned pointer would always
    * be equal to 0.
    *
    * @see CdbFolder
    * @see CdbFolderPtr
    *
    * @return a smart pointer to the parent object
    */
    const CdbFolderPtr& parent( ) const;

  /// Return a smart pointer to the parent CdbDatabase object.
  /**
    * This is a database where this condition is directly connected to.
    *
    * @see CdbDatabase
    * @see CdbDatabasePtr
    *
    * @return a smart pointer to the parent object
    */
    const CdbDatabasePtr& parentDatabase( ) const;

  /// Obtain the name of the condition in its folder.
  /**
    * It's guaranteed that a non 0 pointer will be returned.
    *
    * @return a const pointer onto to the object's name
    */
    const char* name( ) const;

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

  /// Obtain the condition type.
  /**
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * @return TRUE for 'partitionable conditions and FALSE for 'regular' ones.
    */
    virtual bool isPartitionable( ) const = 0;

  /// Obtain the full condition name in the 'physical' namespace.
  /**
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * @return a value of the composite 'physical' name.
    */
    virtual CdbCompositeName physicalName( ) const = 0;

  /// Obtain the full condition identifier in the 'physical' namespace.
  /**
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * @return a value of the 'physical' identifier.
    */
    virtual CdbId physicalId( ) const = 0;

  /// Get the condition creation time.
  /**
    * This is the time when the corresponding 'physical' condition was created.
    * Note the difference of this time between the condition registration time.
    *
    * @see CdbCondition::registered()
    *
    * @return a value of the creation time.
    */
    virtual BdbTime created( ) const = 0;

  /// Get the condition registration time.
  /**
    * This is a time when the condition entry was put into the folder (view).
    * Note the difference of this time from the corresponding 'physical' condition
    * creation time.
    *
    * @see CdbCondition::created()
    *
    * @return a value of the registration time.
    */
    virtual BdbTime registered( ) const = 0;

  /// Get the last time when the condition was modified.
  /**
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * @return a value of the modification time.
    */
    virtual BdbTime modified( ) const = 0;

  /// Find a condition object
  /**
    * This method will initialize a smart pointer to point onto a transient object
    * representing an object of the CdbObject class. It may also initialize the smart pointer to point
    * onto 0 object in case of failure. The corresponding error status will be
    * returned in this case.
    *
    * The resulting object will be valid at given validity time point
    * and optional insertion time point, assuming that other parameters
    * of this operation are taken from a view the current condition belongs to.
    *
    * NOTE: The use or not use of the optional insertion time depends on two factors:
    *       (a) the kind of the condition and (b) the current revision policy
    *       for thsi condition.
    *
    * @see BdbTime
    * @see CdbObject
    * @see CdbObjectPtr
    * @see CdbRevisionPolicy
    * @see CdbStatus
    *
    * @return the completion status
    */
    virtual CdbStatus findObject( CdbObjectPtr&  theObjectPtr,                              /**< the smart pointer to an object to be initialized */
                                  const BdbTime& theValidityTime,                           /**< the point in the validity dimension */
                                  const BdbTime& theInsertionTime = BdbTime::plusInfinity   /**< the point in the insertion time dimension */
                                ) = 0;

  /// Find a condition object
  /**
    * Unlike the previous method, this one expects an explicit value
    * of the "revision policy" to be used when looking for a condition object.
    */
    virtual CdbStatus findObject( CdbObjectPtr&            theObjectPtr,
                                  const CdbRevisionPolicy& thePolicy,
                                  const BdbTime&           theValidityTime,
                                  const BdbTime&           theInsertionTime = BdbTime::plusInfinity
                                ) = 0;

  /// An iterator for the objects
  /**
    * Initializes an iterator to find all Objects at a given scope of a condition.
    * The iterator when advanced will return an CdbObjectPtr smart pointer. It may also
    * initialize the iterator to be in the non-valid state in case of failure.
    * he corresponding error status will be returned in this case.
    *
    * The scope is defined by an interval at the validity dimension and the current
    * configuration of a view.
    *
    * @see BdbTime
    * @see CdbObject
    * @see CdbObjectPtr
    * @see CdbStatus
    *
    * @return the completion status
    */
    virtual CdbStatus objectIterator( CdbObjectItr&  theItr,                                    /**< the iterator to be initialized */
                                      const BdbTime& theBeginValidity = BdbTime::minusInfinity, /**< the begin point for iteration */
                                      const BdbTime& theEndValidity   = BdbTime::plusInfinity   /**< the end   point for iteration */
                                    ) = 0;

  /// An iterator for the objects
  /**
    * Unlike the previous method, this one expects an explicit value
    * of the "revision policy" to be used when looking for condition objects.
    *
    * Note, that for partitionable conditions the specified validity interval
    * would be reduced to the width of the specified (by the policy) partition.
    * No error status would be reported if these intervals won't intersect.
    */
    virtual CdbStatus objectIterator( CdbObjectItr&            theItr,                                      /**< the iterator to be initialized */
                                      const CdbRevisionPolicy& thePolicy,                                   /**< the policy to be used to iterate for objects */
                                      const BdbTime&           theBeginValidity = BdbTime::minusInfinity,   /**< the begin point for iteration */
                                      const BdbTime&           theEndValidity   = BdbTime::plusInfinity     /**< the end   point for iteration */
                                    ) = 0;

  /// An iterator for the 'original' objects
  /**
    * Initializes an iterator to find all Objects at a given scope of a condition.
    * The iterator when advanced will return an CdbObjectPtr smart pointer. It may also
    * initialize the iterator to be in the non-valid state in case of failure.
    * he corresponding error status will be returned in this case.
    *
    * The scope is defined by an interval at the insertion dimension, a partition identifier
    * and the corresponding 'physical' condition as it's defined by the current configuration
    * of a view.
    *
    * @see BdbTime
    * @see CdbObject
    * @see CdbObjectPtr
    * @see CdbStatus
    *
    * @return the completion status
    */
    virtual CdbStatus originalObjectIterator( CdbObjectItr&        theItr,                                      /**< the iterator to be initialized */
                                              const BdbTime&       theBeginInsertion = BdbTime::minusInfinity,  /**< the begin point for iteration */
                                              const BdbTime&       theEndInsertion   = BdbTime::plusInfinity,   /**< the end   point for iteration */
                                              const unsigned short thePartitionId = 0                           /**< the partition identifier */
                                            ) = 0;

  /// Create and store a new condition object in the database.
  /**
    * The new object is created via a special factory passed by a reference onto
    * its (factory's) base class. It's expected that a client of this API is responsible
    * for preparing these factories creating concrete persistent objects on the base
    * of a particular technology. If the creation and verification of this objects succeeds
    * then a new object is registered in the database with specified interval of validity.
    *
    * @see BdbTime
    * @see CdbObject
    * @see CdbObjectFactoryBase
    * @see CdbStatus
    *
    * @return the completion status
    */
    CdbStatus storeObject( CdbObjectFactoryBase& theObjectFactory,  /**< a factory implementing an object creation */
                           const BdbTime&        theBegin,          /**< the begin point for a stored object */
                           const BdbTime&        theEnd             /**< the end   point for a stored object */
                         );

  /// Create and store a new condition object in the database.
  /**
    * This is an extended form of the previous method returning a smart pointer
    * corresponding to the newely created object.
    *
    * IMPORTANT: The validity interval of the returned object could be shorter
    *            than the original intention if the corresponding restrictions
    *            are imposed by the current view.
    */
    virtual CdbStatus storeObject( CdbObjectFactoryBase& theObjectFactory,  /**< a factory implementing an object creation */
                                   const BdbTime&        theBegin,          /**< the begin point for a stored object */
                                   const BdbTime&        theEnd,            /**< the end   point for a stored object */
                                   CdbObjectPtr&         theObjectPtr       /**< the object pointer to be filled out */
                                 ) = 0;

  /// Create and store a new condition object in the database.
  /**
    * This method is here for backward compatibility with the corresponding feature
    * of the old Condition/DB.
    */
    CdbStatus storeAndTruncateObject( CdbObjectFactoryBase& theObjectFactory,   /**< a factory implementing an object creation */
                                      const BdbTime&        theStoreTime,       /**< the begin point for a stored object */
                                      const BdbTime&        theTruncateTime     /**< the end   point for a stored object */
                                    );

  /// Create and store a new condition object in the database.
  /**
    * This is an extended form of the previous method returning a smart pointer
    * corresponding to the newely created object.
    *
    * IMPORTANT: The validity interval of the returned object could be shorter
    *            than the original intention if the corresponding restrictions
    *            are imposed by the current view.
    */
    virtual CdbStatus storeAndTruncateObject( CdbObjectFactoryBase& theObjectFactory,   /**< a factory implementing an object creation */
                                              const BdbTime&        theStoreTime,       /**< the begin point for a stored object */
                                              const BdbTime&        theTruncateTime,    /**< the end   point for a stored object */
                                              CdbObjectPtr&         theObjectPtr        /**< the object pointer to be filled out */
                                            ) = 0;

  /// Split the validity timeline at specified point.
  /**
    * ATTENTION: This is a temporary method for backward compatibility
    *            with the old API introduced on a period of migration.
    */
    virtual CdbStatus split( const BdbTime& theTime     /**< a point of split */
                           ) = 0;
                       
  /// Find a revision by its identifier
  /**
    * This command if succeeded will initialize specified smart pointer
    * to point onto a revision description object with required characteristics.
    *
    * NOTE: The "partition identifier" parameter is only required for so called
    *       "partitionable" conditions.
    *
    * @see CdbRevision
    * @see CdbRevisionPtr
    * @see CdbStatus
    *
    * @return a completion status
    */
    virtual CdbStatus findRevision( CdbRevisionPtr& thePtr,             /**< the smart pointer to be initialized */
                                    const BdbTime&  theId,              /**< the revision identifier */
                                    unsigned short  thePartitionId = 0  /**< the partition identifier */
                                  ) = 0;

  /// Find a revision by its name
  /**
    * This command if succeeded will initialize specified smart pointer
    * to point onto a revision description object with required characteristics.
    *
    * NOTE: The "partition identifier" parameter is only required for so called
    *       "partitionable" conditions.
    *
    * @see CdbRevision
    * @see CdbRevisionPtr
    * @see CdbStatus
    *
    * @return a completion status
    */
    virtual CdbStatus findRevision( CdbRevisionPtr& thePtr,             /**< the smart pointer to be initialized */
                                    const char*     theName,            /**< the revision name */
                                    unsigned short  thePartitionId = 0  /**< the partition identifier */
                                  ) = 0;

  /// An iterator for the known revision identifiers
  /**
    * Initializes an iterator to find all revision identifiers at a scope of
    * the current condition/partition. The iterator when advanced will return an object
    * of BdbTime class. These objects can be turned into revision description
    * objects by calling CdbConditionMgr::findRevision() method described above.
    *
    * The iterator will be set into a "valid" state upon successfull completion.
    *
    * NOTE: The "partition identifier" parameter is only required for so called
    *       "partitionable" conditions.
    *
    * @see CdbIItr::isValid()
    * @see CdbStatus
    *
    * @return completion status
    */
    virtual CdbStatus revisionIdIterator( CdbItr<BdbTime>& theItr,              /**< an iterator to be initialized */
                                          unsigned short   thePartitionId = 0   /**< the partition identifier */
                                        ) = 0;

  /// An iterator for the known revision names
  /**
    * Initializes an iterator to find all revision names at a scope of
    * the current condition/partition. The iterator when advanced will return
    * (pointers to) strings. These objects can be turned into revision description
    * objects by calling CdbConditionMgr::findRevision() method described above.
    *
    * The iterator will be set into a "valid" state upon successfull completion.
    *
    * NOTE: The "partition identifier" parameter is only required for so called
    *       "partitionable" conditions.
    *
    * @see CdbIItr::isValid()
    * @see CdbStatus
    *
    * @return completion status
    */
    virtual CdbStatus revisionNameIterator( CdbItr<const char*>& theItr,            /**< an iterator to be initialized */
                                            unsigned short       thePartitionId = 0 /**< the partition identifier */
                                          ) = 0;

  /// Create a new revision
  /**
    * This command if succeeded will create a new revision with specified parameters
    * in a s cope of a condition (and partition for 'PARTTIONABLE' conditions).
    * It will also initialize a smart pointer onto a transient API object
    * representing a newely created revision.
    *
    * The operation would check if the revision can be created for a condition
    * it (the operation) is being used at.
    *
    * @see CdbRevision
    * @see CdbStatus
    *
    * @return a completion status
    */
    virtual CdbStatus createRevision( CdbRevisionPtr& thePtr,               /**< the smart pointer to be initialized */
                                      const BdbTime&  theId,                /**< the revision identifier */
                                      const char*     theName,              /**< the revision name */
                                      const char*     theDescription,       /**< the revision description */
                                      unsigned short  thePartitionId = 0    /**< the partition identifier */
                                     ) = 0;
private:

  // Fixed parameters of the condition

    CdbFolderPtr   _myParent;
    CdbDatabasePtr _myParentDatabase;
    std::string    _myName;
};

#endif  // CDB_CONDITION_HH

---