---

CdbView.hh

Go to the documentation of this file.

#ifndef CDB_VIEW_HH
#define CDB_VIEW_HH

// File and Version Information:
//      $Id: CdbView.hh,v 1.14 2003/08/13 23:34:13 gapon Exp $

#include "CdbBase/CdbId.hh"

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

#include "CdbBase/CdbCPtrBase.hh"
#include "CdbBase/CdbViewPtrFwd.hh"
#include "CdbBase/CdbDatabasePtrFwd.hh"

#include "CdbBase/CdbRevisionPolicy.hh"
#include "CdbBase/CdbConfigElement.hh"
#include "CdbBase/CdbItr.hh"

#include <string>

class CdbStateId;

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

friend class CdbCPtrBase< CdbView >;

private:

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

protected:

  /// The normally used constructor will set the internal parameters
  /// of an object.
  /**
    * Initialize the context of the view with specified set of parameters. This
    * will also validate the internal state of the object.
    *
    * Both pointers should not point to 0 objects.
    *
    * @see CdbDatabase
    * @see CdbDatabasePtr
    */
    CdbView( const CdbDatabasePtr& theDatabasePtr,  /**< the smart pointer providing a back link to the parent object */
             const char*           theName,         /**< the name of the view */
             const CdbId&          theId            /**< the extended identifier of this view */
           );

  /// The copy constructor
  /**
    * Details...
    */
    CdbView( const CdbView& theView );

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

  /// The assignment operator
  /**
    * Details...
    */
    CdbView& operator=( const CdbView& theView );

public:

  /// Static locator for a view object
  /**
    * Locates specified view 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 CdbViewPtr
    * @see CdbStatus
    *
    * @return a completion status
    */
    static CdbStatus instance( CdbViewPtr& theViewPtr,                  /**< the smart pointer to be initialized */
                               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 view object
  /**
    * Unlike the previous method, this one uses extended identifier of a view
    * to find the corresponding object.
    *
    * @see CdbId
    */
    static CdbStatus instance( CdbViewPtr&  theViewPtr,                 /**< the smart pointer to be initialized */
                               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 */
                             );

public:

  /// Return a smart pointer to the parent object.
  /**
    * @see CdbDatabase
    */
    const CdbDatabasePtr& parent( ) const;

  /// Obtain the current name of the view.
  /**
    * This name is garanteed to be non 0 pointer.
    *
    * @return a const pointer to the name of the object
    */
    const char* name( ) const;

  /// Obtain the current identifier of the view.
  /**
    * It's an extended identifier of the view in the (potentially) distributed
    * installation.
    *
    * @return a const reference to the identifier
    */
    const CdbId& id( ) const;

  /// Obtain the begin time allowed by the view
  /**
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * @return a string with the object's description
    */
    virtual BdbTime minValidity( ) const = 0;

  /// Obtain the end time allowed by the view
  /**
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * @return a string with the object's description
    */
    virtual BdbTime maxValidity( ) const = 0;

  /// Obtain the creation time of the view
  /**
    * This method is supposed to be implemented by the corresponding subclass.
    *
    * @return a string with the object's description
    */
    virtual BdbTime created( ) const = 0;

  /// Obtain the view 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;

  /// Check if the view has "default" configuration
  /**
    * A view may have an optional "default" configuration to be used for conditions not
    * having their private configurations.
    *
    * @return TRUE if there is such configuration
    */
    virtual bool hasDefaultConfig( ) const = 0;

  /// Get the current status of the view
  /**
    * The maijor difference of "local" views from others is that their configuration
    * can be modified locally (if it's not in "frozen" state and the corresponding
    * authorization permits modifications.)
    */
    virtual bool isLocal( ) const = 0;

  /// Get the current status of the view
  /**
    * A non-"frozen" view is not stable since its configuration is allowed to be changed
    * by the database administration tools. This kind (non-"frozen") views are used
    * where the views is being in a transition state. Once it's done the view can be
    * turned into the "frozen" state.
    */
    virtual bool isFrozen( ) const = 0;

  /// Get a "config element" at specified point of validity time from the "default" configuration
  /**
    * This method is similar to the regular get() method except it will use (if any)
    * the so called "default" configuration of the view.
    *
    * Since "default" configuration is an optional feature of the view then it may
    * not exist at a particular view. If this is going to be the case then the method
    * will return CdbStatus::NotFound cimpletiuon status.
    *
    * @see CdbView::hasDefaultConfig()
    * @see CdbView::get()
    */
    virtual CdbStatus getDefault( const BdbTime&    theValidityTime,
                                  CdbConfigElement& theConfigElement
                                ) const = 0;

  /// Set up an iterator of "default config elements"
  /**
    * @see CdbView::hasDefaultConfig()
    * @see CdbView::getDefault()
    * @see CdbView::configIterator()
    */
    virtual CdbStatus defaultConfigIterator( CdbItr<CdbConfigElement>& theItr
                                           ) const = 0;

  /// Get a "config element" for a condition at specified point of validity time
  /**
    * A full path name (inluding a condition itself) is used to specify
    * the corresponding condition.
    *
    * The method delivers its results through the "config element"
    * comprising the found revision policy and its interval of the validity.
    *
    * Note, that returned policy may prohibit accessing the database for
    * specified period of time.
    *
    * @see CdbConfigElement
    * @see CdbRevisionPolicy
    *
    * @return completion status
    */
    virtual CdbStatus get( const char*       theName,
                           const BdbTime&    theValidityTime,
                           CdbConfigElement& theConfigElement
                         ) const = 0;

  /// Set up an iterator of "config elements" for a condition
  /**
    * The iterator will retirn valid elements for the interval of validity
    * covered by the view.
    *
    * @return completion status
    */
    virtual CdbStatus configIterator( const char*               theName,
                                      CdbItr<CdbConfigElement>& theItr
                                    ) const = 0;

  /// Get current value of the state identifier
  /**
    * The method delivers a value of the identifier calculated in the scope of
    * he view. The only explicit parameter of the method is a point of time in
    * the validity dimension, in which the identifier is requested.
    *
    * The returned identifier will be "invalid" should any problem occures to construct
    * (calculate) the identifier.
    *
    * The method is supposed to be implemented by subclasses.
    *
        * @see CdbStateId
    *
    * @return a value of the identifier.
    */
    virtual CdbStateId currentStateId( const BdbTime& theValidityTime ) const = 0;

private:

    CdbDatabasePtr _myParentPtr;
    std::string    _myName;
    CdbId          _myId;
};

#endif  // CDB_VIEW_HH

---