---

CdbRooRoFileUtils.hh

Go to the documentation of this file.

#ifndef CDBBROOREADONLY_FILE_UTILS_HH
#define CDBBROOREADONLY_FILE_UTILS_HH

// File and Version Information:
//      $Id: CdbRooRoFileUtils.hh,v 1.14 2005/11/11 01:41:26 gapon Exp $

#include "CdbBase/CdbCPtr.hh"

#include <TTree.h>  // must have it here because of the copy contsructor of one of the nested
                    // classes is using it.

#include <string>
#include <list>
#include <map>

#include <iostream>

class CdbRooRoRegistry;
class CdbRooRoMetaDataR;
class CdbRooRoCollectionAddressR;

class TFile;

/// The utility class to help with file system operations
/**
  * This utility class is implemented as a singleton. It provides a simplified interface
  * to an underlying file system.
  */
class CdbRooRoFileUtils {

public:

  /// The singlenton constructor/accessor

    static CdbRooRoFileUtils& instance( );


  /// Build a name for the specified "MetaData" container
  /**
    * Note, that the method will produce a unique fully qualified name of the metadata
    * object in the global scope of CDB. This allows placing these objects into
    * any file of a database installation w/o being worried about namespace
    * conflicts.
    *
    * Here are example of names:
    *
    *   "o0.c0.i1.MetaData.145"
    *   "o257.c0.p18.i0.MetaData.32"
    *
    * The rest of the current CDB API implementation has to be written in terms
    * of names produced by this method.
    */
    static std::string nameOfMetaDataContainer( UShort_t theConditionId,
                                                bool     isPartitionableFlag,
                                                UShort_t thePartitionId,
                                                UShort_t theClusterId,
                                                UShort_t theIncrementNumber,
                                                UShort_t theOriginId );

  /// Build a name for the specified "Objects" container
  /**
    * Also see notes on the naming convention for the similar "MetaData"
    * method:
    *
    * @see CdbRooRoFileUtils::nameOfMetaDataContainer()
    */
    static std::string nameOfObjectsContainer( UShort_t theConditionId,
                                               bool     isPartitionableFlag,
                                               UShort_t thePartitionId,
                                               UShort_t theClusterId,
                                               UShort_t theIncrementNumber,
                                               UShort_t theOriginId );

  /// Build a name for the specified "Objects" container
  /**
    * Note, that the method will produce a unique fully qualified name of the system
    * object in the global scope of CDB. This allows placing these objects into
    * any file of a database installation w/o being worried about namespace
    * conflicts.
    *
    * Here are example of names:
    *
    *   "o0.System.Registry"
    *   "o0.System.ConditionCollection"
    *   "o256.System.ViewCollection"
    *
    * The rest of the current CDB API implementation has to be written in terms
    * of names produced by this method.
    */
    static std::string nameOfSystemContainer( UShort_t           theOriginId,
                                              const std::string& theContainerName );
private:

  /// The default constructor.
  /**
    * Will construct an invalid context to be properly filled up with subsequent
    * calls of the "set" methods.
    */
    CdbRooRoFileUtils( );

  /// The copy constructor (NOT IMPLEMENTED)

    CdbRooRoFileUtils( const CdbRooRoFileUtils& theCdb );

  /// The assignment operator (NOT IMPLEMENTED)

    CdbRooRoFileUtils& operator=( const CdbRooRoFileUtils& theCdb );

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

public:

  /// Reset the context

    void reset( );

  /// Set up the local origin name
  /**
    * The values set by this method would affect results of some operations
    * of this class.
    *
    * A valid string is expected as a parameter of the method.
    */
    void setLocalOrigin( const std::string& theOriginName,
                         UShort_t           theOriginId );

  /// Set up a location of this
  /**
    * A value passed as a parameter will be used to locate database images in a proximity
    * of the bootfile. The location can be represented either by an absolute file system path
    * or a relative one (in the respect to a value of the 'CWD' parameter).
    */
    void setBootFileLocation( const std::string& theFileName );

  /// Set up a mapping between databases and their locations
  /**
    * The mapping will be used to implement a catalog of a persistent store.
    *
    * The locations for database names can be either absolute (begining with the "/" symbol)
    * or relative ones. The absolute locations will be used "as is" w/ no extra interpretations.
    * The relative locations are assumed to be related to a base location of the database
    * installation (where the boot file is found).
    *
    * @see CdbRooRoFileUtils::baseLocation()
    */
    void setDatabase2LocationMap( const std::map<std::string,std::string>& theMap );

  /// Set up a mapping between persistent objects and their databases
  /**
    * This is an optional map allowing persistent objects be found in non-standard
    * locations. The feature is there for an extra flexibility. The key of the map
    * is an object name and the value - is a logical name of the corresponding database.
    *
    * If an object's name is not found in the map then a standard location
    * is assumed.
    *
    * @see CdbRooRoFileUtils::setDatabase2LocationMap()
    */
    void setObject2DatabaseMap( const std::map<std::string,std::string>& theMap );

  /// Set/update a cached pointer to the specified registry

    void setRegistry( const CdbCPtr< CdbRooRoRegistry >& theRegistry );

  /// Get local origin name

    const std::string& localOriginName( ) const { return _localOriginName; }

  /// Get local origin identifier

    UShort_t localOriginId( ) const { return _localOriginId; }

  /// Get the boot file location

    const std::string& bootFileLocation( ) const { return _bootFileLocation; }

  /// Get the base location of database files
  /**
    * This value is derived from the boot file location.
    */
    const std::string& baseLocation( ) const { return _baseLocation; }

  /// Get a cached value of a registry for the specified origin if it exists
  /**
    * Return a 0 pointer of the cache isn't populated.
    */
    CdbCPtr< CdbRooRoRegistry > registry( UShort_t theOriginId ) const;

  /// Get a cached value of a registry for the specified origin if it exists
  /**
    * Return a 0 pointer of the cache isn't populated.
    */
    CdbCPtr< CdbRooRoRegistry > registry( const std::string& theOriginName ) const;

  /// Find a MetaData object with specified parameters
  /**
    * NOTE: The operation may also populate an internal cache of the current facility
    *       to speed up further operations.
    *
    * The operation will return CdbStatus::NotFound if no object matching the specified criteria
    * will be found. Other satus values are returned as usually.
    */
    CdbStatus findMetaData( CdbCPtr< CdbRooRoMetaDataR >& theMetaDataPtr,       /**< the pointer to be initialized */
                            UShort_t                      theConditionId,
                            bool                          isPartitionableFlag,
                            UShort_t                      thePartitionId,
                            UShort_t                      theClusterId,
                            UShort_t                      theIncrementNumber,
                            UShort_t                      theOriginId
                          );

  /// Find the specified database file by its logical name (not a path!)
  /**
    * The common accepts only logical names of database files, not their relative
    * or absolute locations in a database installation. Failure to do so would result
    * at the CdbStatus::IllegalParameters status returned. The operation will return
    * CdbStatus::NotFound if no object matching the specified criteria will be found.
    * Other satus values are returned as usually.
    *
    * @see CdbRooRoFileUtils::baseLocation()
    *
    * NOTE: The operation may also populate an internal cache of the current facility
    *       to speed up further operations.
    */
    CdbStatus findDatabase( CdbCPtr< TFile >&  theDatabasePtr,      /**< the daabase pointer to be initialized */
                            const std::string& theName,             /**< the logical name of a database */
                            const std::string& theOpenMode = "read"
                          );

  /// Find or create a database file for the specified "Collection Address"
  /**
    * NOTE: The operation may also populate an internal cache of the current facility
    *       to speed up further operations.
    *
    * The behavior of the operation will depend on a value of the optional "open mode"
    * parameter. See the documentation on the TFile class to get more idea on this.
    */
    CdbStatus findDatabase( CdbCPtr< TFile >&                 theDatabasePtr,
                            const CdbRooRoCollectionAddressR& theCollectionAddress,
                            const std::string&                theOpenMode = "read"
                          );

  /// Find or create the specified "Registry" database file for the specified origin
  /**
    * NOTE: The operation may also populate an internal cache of the current facility
    *       to speed up further operations.
    *
    * The behavior of the operation will depend on a value of the optional "open mode"
    * parameter. See the documentation on the TFile class to get more idea on this.
    */
    CdbStatus findDatabase( CdbCPtr< TFile >&  theDatabasePtr,
                            UShort_t           theOriginId,
                            const std::string& theOpenMode = "read"
                          );

  /// Find or create the specified database file for "MetaData." containers
  /**
    * NOTE: The operation may also populate an internal cache of the current facility
    *       to speed up further operations.
    *
    * The behavior of the operation will depend on a value of the optional "open mode"
    * parameter. See the documentation on the TFile class to get more idea on this.
    */
    CdbStatus findDatabase( CdbCPtr< TFile >&  theDatabasePtr,
                            bool               isPartitionableFlag,
                            UShort_t           thePartitionId,
                            UShort_t           theClusterId,
                            UShort_t           theIncrementNumber,
                            UShort_t           theOriginId,
                            const std::string& theOpenMode = "read"
                          );

  /// Find or create the specified database file for "Objects." containers
  /**
    * NOTE: The operation may also populate an internal cache of the current facility
    *       to speed up further operations.
    *
    * The behavior of the operation will depend on a value of the optional "open mode"
    * parameter. See the documentation on the TFile class to get more idea on this.
    */
    CdbStatus findObjectsDatabase( CdbCPtr< TFile >&  theDatabasePtr,
                                   bool               isPartitionableFlag,
                                   UShort_t           thePartitionId,
                                   UShort_t           theClusterId,
                                   UShort_t           theIncrementNumber,
                                   UShort_t           theOriginId,
                                   const std::string& theOpenMode = "read"
                                 );

  /// Find a ROOT "tree"
  /**
    * @see CdbRooRoFileUtils::doFindTree()
    */
    CdbStatus findTree( CdbCPtr< TTree >&  theTreePtr,
                        const std::string& theFileName,
                        const std::string& theTreeName,
                        const std::string& theOpenMode = "read"
                      );

  /// Find a ROOT "tree"
  /**
    * @see CdbRooRoFileUtils::doFindTree()
    */
    CdbStatus findTree( CdbCPtr< TTree >&                 theTreePtr,
                        const CdbRooRoCollectionAddressR& theCollectionAddress,
                        const std::string&                theTreeName,
                        const std::string&                theOpenMode = "read"
                      );

  /// Dumnp the statistics

    void dump( std::ostream& theStream ) const;

private:

  /// Actual finding of the tree from the specified database
  /**
    * IMPORTANT:
    *
    *   It's not recommended to cache smart pointers obtained through this interaface
    *   within a client's code to avoid potential virtual memory runout. To avoid that problem
    *   the current facility may maintain a special cache of open TTree-s and put certain
    *   limitations onto a number of open trees. In addition, TTree-s are also objects associated
    *   with open TFile-s, so if the corresponding file gets closed all its trees sould disappear
    *   from the cache.
    *
    *     NOTE: The current implementation of the cache of trees implies that database files open
    *           by the application never get closed. If this will change then the cache will get
    *           reimplemented to get rid of trees loaded from the closed files.
    *
    *   The cache size is maintaind through the following optional (case sensitive) parameter of
    *   the CDB API:
    *
    *     "Roo/Readonly/max_num_ttrees"
    *
    *   The parameter's value is of the "unsigned" type. Here is how it should be set:
    *
    *     CdbEnvironment::extra( ).insert<unsigned>( "Roo/Readonly/max_num_ttrees", 128 );
    *
    *   The default number of TTree-s is implementation specific and is not to be revealed
    *   in the current interface. However, when setting a non-default value of the parameter,
    *   keep in mind that each TTree costs about 0.5-1.0 MB of the virtual memory.
    */
    CdbStatus doFindTree( CdbCPtr< TTree >&       theTreePtr,
                          const CdbCPtr< TFile >& theDatabasePtr,
                          const std::string&      theTreeName
                        );

  // The current context of the object

    std::string _localOriginName;
    UShort_t    _localOriginId;

    std::string _bootFileLocation;
    std::string _baseLocation;

    std::map<std::string,std::string> _database2LocationMap;
    std::map<std::string,std::string> _object2DatabaseMap;

  // A cache of registries

    std::map< UShort_t,    CdbCPtr< CdbRooRoRegistry > > _origin2RegistryMapById;
    std::map< std::string, CdbCPtr< CdbRooRoRegistry > > _origin2RegistryMapByName;

  // A cache of MetaData-s
  //
  // IMPLEMENTATION NOTE:
  //
  //   The keys to the cache are strings combined from a database name and a metadata
  //   object name:
  //
  //     <database_name>::<object_name>

    std::map< std::string, CdbCPtr< CdbRooRoMetaDataR > > _cacheOfMetaData;

  // A cache of files

    std::map< std::string, CdbCPtr< TFile > > _cacheOfFiles;

  // A cache of TTree-s. The keys are built from file and tree names in the following
  // way:
  //
  //   <file_name>::<tree_name>

    struct TreeCacheElement {
        TreeCacheElement( const std::string&    theName = "",
                          const CdbCPtr<TTree>& thePtr  = 0 ) :
            name(theName),
            ptr (thePtr),
            used(1)
        {}
        std::string    name;
        CdbCPtr<TTree> ptr;
        unsigned used;
    };
    typedef std::list<TreeCacheElement> MyListOfTrees;
    typedef std::map<std::string,MyListOfTrees::iterator> MyMapOfTrees;

    unsigned _cacheOfTreesMaxSize;
    unsigned _cacheOfTreesSize;

    MyListOfTrees _cacheOfTreesByUseTime;
    MyMapOfTrees  _cacheOfTreesByName;

    unsigned _cacheOfTreesStatTotal;
    unsigned _cacheOfTreesStatCached;
    unsigned _cacheOfTreesStatRemoved;

    std::map< std::string, unsigned > _cacheOfTreesStatTrees;
};

#endif  // CDBBROOREADONLY_FILE_UTILS_HH

---