---

CdbEnvironment.hh

Go to the documentation of this file.

#ifndef CDB_ENVIRONMENT_HH
#define CDB_ENVIRONMENT_HH

// File and Version Information:
//      $Id: CdbEnvironment.hh,v 1.9 2005/11/03 02:49:26 gapon Exp $

#include "CdbBase/CdbPtrFwd.hh"

#include <string>

class CdbStateId;
class BdbTime;
class CdbEnvironmentImpl;

template< class T > class CdbAnyTypeDict;

/// The configuration options of the Conditions/DB API.
/**
  * This utility class provides global control options in the scope of
  * an application process.
  *
  * NOTE: Most of the operations provided by this class may involve interraction
  *       with a persistent store(s).
  *
  * DESIGN NOTE: The design of this class is based on the 'PIMPL' idiom to introduce
  *              the compilation firewall between clients of this utility class and
  *              its actual "back-end" implementation
  */
class CdbEnvironment {

private:

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

  /// The destructor (NOT IMPLEMENTED)
  /**
    * Is disabled...
    */
    virtual ~CdbEnvironment( );

  /// The copy constructor (NOT IMPLEMENTED)
  /**
    * Is disabled...
    */
    CdbEnvironment( const CdbEnvironment& theEnv );

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

public:

  /// Set the current value of the "DEBUG LEVEL"
  /**
    * If 0 value is passed into the method then it means no debug output.
    * Interpretations for other values are not defined yet. The current behaviour
    * is "print as much as the corresponding component wants to".
    *
    * @return the previous value of the mode
    */
    static int setDebugMode( int newMode = 0 );

  /// Get the current value of the "DEBUG LEVEL"
  /**
    * @see CdbEnvironment::setDebugMode()
    */
    static int getDebugMode( );

  /// Get default value of the state identifier
  /**
    * The method delivers a value of the identifier calculated in the scope of
    * he current default environment. 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.
    *
        * @see CdbStateId
    *
    * @return a value of the identifier.
    */
    static CdbStateId defaultStateId( const BdbTime& theValidityTime );

  /// Get the current value of the "truncate" time
  /**
    * The "truncate" time if set will restrict the end time of stored objects
    * in the validity dimension. This restriction applies to any kinds of conditions
    * stored through CDB API.
    *
    * The default value of this time is "+Infinity", which means there is no restriction.
    * The value of this parameter can be set at any time during an application
    * execution. Should this happen the subsequent storing attempt would be affected.
    *
    * @see CdbEnvironment::setTruncateTime()
    *
    * @return a value of the truncate time.
    */
    static BdbTime getTruncateTime( );

  /// Set the new value of the "truncate" time
  /**
    * @see CdbEnvironment::getTruncateTime()
    *
    * @return a previous value of the truncate time.
    */
    static BdbTime setTruncateTime( const BdbTime& theNewTruncateTime );

  ////////////////////////
  // OBSOLETE INTERFACE //
  ////////////////////////
  //
  // The following interface is currently the obsolete one. It's replaced
  // by the new one (see it rigth after the end of this 'OBSOLETE INTERFACE'
  // section below.

  /// Get default technology name
  /**
    * NOTE: This is an obsolete method to be removed soon.
    */
    static std::string defaultTechnology( );

  /// Get default implementation name
  /**
    * Returns an empty string if there is no information for specified
    * combination of parameters values.
    *
    * NOTE: This is an obsolete method to be removed soon.
    */
    static std::string defaultImplementation( const char* theTechnologyName );

  /// Get default database name
  /**
    * Returns an empty string if there is no information for specified
    * combination of parameters values.
    */
    static std::string defaultDatabase( const char* theTechnologyName,
                                        const char* theImplementationName );

  /// Get default view name
  /**
    * Returns an empty string if there is no information for specified
    * combination of parameters values.
    *
    * NOTE: This is an obsolete method to be removed soon.
    */
    static std::string defaultView( const char* theTechnologyName,
                                    const char* theImplementationName,
                                    const char* theDatabaseName );

  /// Set a combination of default parameters
  /**
    *
    * NOTE: This is an obsolete method to be removed soon.
    */
    static void setDefault( const char* theTechnologyName,
                            const char* theImplementationName,
                            const char* theDatabaseName,
                            const char* theViewName );

  ///////////////////
  // NEW INTERFACE //
  ///////////////////
  //
  // This interface replaces the above defined 'OBSOLETE INTERFACE'.
  //
  // NOTES:
  //
  //   (1) The basic difference of this interface from the old one is in following areas:
  //
  //       o  the order of parameters is reversed. Therefore the inner scope
  //          componentalways comes first.
  //
  //       o  certain _input-only_ parameters may get default 0 pointer to tell:
  //
  //            "...use the default (whatever it is) in my (depending on
  //             the context) upper scope(s)..."
  //
  //       o  passing the "<default>" string as a value of optional parameters
  //          is equivalent to passing teh 0 pointer.
  //
  //       o  all methods now will return status. The reason of this is that
  //          these methods are now the _active_ ones. Which means that (depending
  //          on a context and actual values of parameters passed) they may cause
  //          actual interaction with the corresponding CDB API implementations.
  //
  //   (2) The actual implementation supporting the new interface expects
  //       a "true" tree-like structure of defaults.

  /// Get default technology name
  /**
    * The technology name is the top-level scope of the CDB API. Names returned
    * by this method are associated with particular persistent technologies used
    * in a specific way (which means that the same persistent technology may be
    * used in different ways. If thsi is going to be the case then different "technology"
    * names must be returned for each specific use by the current method).
    *
    * The method will return CdbStatus::NotFound in case if there is no one
    * specific technology known beneath CDB API.
    */
    static CdbStatus getDefaultTechnology( std::string& theTechnologyName );

  /// Get default implementation name
  /**
    * The implementation name corresponds to specific implementation of the full CDB API
    * based on certain technology. Don't mix this "specific implementation" with
    * the various used of the same persistent technology.
    *
    * Omitting the technology name when calling this method whould imply that
    * the current default technology (as defined by the previous method) is going
    * to be used.
    */
    static CdbStatus getDefaultImplementation( std::string& theImplementationName,
                                               const char*  theTechnologyName = 0 );
 
  /// Get default database name
  /**
    * The database is defined as a set of self-consistent (persistent, but not limited to)
    * datasets with CDB metadata and actual user defined payload.
    */
    static CdbStatus getDefaultDatabase( std::string& theDatabaseName,
                                         const char*  theImplementationName = 0,
                                         const char*  theTechnologyName     = 0 );

  /// Get default view name
  /**
    * The view defines which slice of an actual database is available to an application.
    * Views in fact are providing mapping from a virtual namespace available to client
    * applications onto the actual data sets stored in databases.
    */
    static CdbStatus getDefaultView( std::string& theViewName,
                                     const char*  theDatabaseName       = 0,
                                     const char*  theImplementationName = 0,
                                     const char*  theTechnologyName     = 0 );

  /// Get all defaults
  /**
    * This method will return the current path in the tree of defaults.
    */
    static CdbStatus getDefaultPath( std::string& theViewName,
                                     std::string& theDatabaseName,
                                     std::string& theImplementationName,
                                     std::string& theTechnologyName );

  /// Set default technology
  /**
    * The technology must already be instantiated by current application,
    * and it must be known to CDB API.
    *
    * NOTE: Passing 0 pointer as a technology name is _not_ allowed by this method.
    *       The method will return CdbStatus::Error in this case.
    */
    static CdbStatus setDefaultTechnology( const char* theTechnologyName );

  /// Set default implementation
  /**
    * The implementation implementing given (or default) technology must already
    * be instantiated by current application, and it must be known to CDB API.
    *
    * NOTE: Passing 0 pointer as an implementation name is _not_ allowed by this method.
    *       The method will return CdbStatus::Error in this case.
    */
    static CdbStatus setDefaultImplementation( const char* theImplementationName,
                                               const char* theTechnologyName     = 0 );

  /// Set default database
  /**
    * The database must be available to the specified (or default) implementation.
    *
    * NOTE: Passing 0 pointer as a database name is _not_ allowed by this method.
    *       The method will return CdbStatus::Error in this case.
    */
    static CdbStatus setDefaultDatabase( const char* theDatabaseName,
                                         const char* theImplementationName = 0,
                                         const char* theTechnologyName     = 0 );

  /// Set default view
  /**
    * The view must already exist in the scope of the specified (or default) database.
    *
    * NOTE: Passing 0 pointer as a view name is _not_ allowed by this method.
    *       The method will return CdbStatus::Error in this case.
    */
    static CdbStatus setDefaultView( const char* theViewName,
                                     const char* theDatabaseName       = 0,
                                     const char* theImplementationName = 0,
                                     const char* theTechnologyName     = 0 );

  /// Set all defaults to specified path
  /**
    * This method will set new path in the tree of defaults.
    *
    * The method will check the presense and availability of specified
    * components passed to this command.
    *
    * NOTE: Passing 0 pointers for any of the method's parameters is _not_ allowed
    *       by this method. The method will return CdbStatus::Error in this case.
    */
    static CdbStatus setDefaultPath( const char* theViewName,
                                     const char* theDatabaseName,
                                     const char* theImplementationName,
                                     const char* theTechnologyName );

  /// Access a dictionary of extra parameters
  /**
    * The dictionary is meant to be used to pass optional parameters to
    * technology specific implementations of the CDB API. The "environment" makes
    * no separation between the API's implementations.
    *
    * Here is a suggested format for technology-specific parameters:
    *
    *   <technology>/<implementation>/<parameter>
    *
    * For example, if we had a hypothetical implementation of the CDB API storing plain text
    * strings in a relational database then we could control a client size cache by mean of
    * this parameter:
    *
    *   "Text/SQL/max_cache_size"
    *
    * @see class CdbAnyTypeDict
    */
    static CdbAnyTypeDict<std::string>& extra( );

private:


  // The following two methods are only available to the Cdb "frined" class
  // and all its subclasses.

    friend class Cdb;

  /// Add a new entry to the registry.
  /**
    * If the registry already has an entry with given combination of keys
    * then CdbStatus::Error will be returned.
    */
    static CdbStatus set( CdbPtr& thePtr    /**< a pointer to be inserted */
                        );

  /// Find an entry matching specified keys in the registry.
  /**
    * This method will look up specified object in the registry and set up
    * the reference to it if found.
    *
    * @return CdbStatus::NotFound if there is no object matching specified keys.
    */
    static CdbStatus get( CdbPtr&     thePtr,                  /**< the pointer to be set up */
                          const char* theTechnologyName,       /**< the 1-st key of an object to be found */
                          const char* theImplementationName    /**< the 2-d  key of an object to be found */
                        );

private:

  /// Get access to the actual implementation of the "environment"
  /**
    * The actual implementation is defined somewhere else to enforce
    * the compilation dependency firewall.
    *
    * @see CdbEnvironmentImpl
    */
    static CdbEnvironmentImpl* impl( );
};

#endif  // CDB_ENVIRONMENT_HH

---