---

CdbBdbSCollectionP.ddl

Go to the documentation of this file.

#ifndef CDBBDBSHARED_COLLECTION_P_HH
#define CDBBDBSHARED_COLLECTION_P_HH

// File and Version Information:
//      $Id: CdbBdbSCollectionP.ddl,v 1.9 2004/08/06 05:54:24 bartoldu Exp $

#include "BdbUtil/Bdb.hh"
#include "ooMap.h"

#include "CdbBdbShared/CdbBdbSBtreeP.hh"
#include "CdbBdbShared/CdbBdbSCollectionBte.hh"
#include "CdbBdbShared/CdbBdbSCollectionElementP.hh"

#include <iostream>

//------------------------------------------------------------------
// Explicit template instantiatin for the persistent B-tree class --
//------------------------------------------------------------------

EXPLICIT_INSTANTIATE_CdbBdbSBtreeP_1( CdbBdbSCollectionBte );

/// Persistent collection class
/**
  * This class represents persistent
  * "collection" of objects each having an identifier and/or a name
  * in the scope of the collection.
  *
  * Elements stored in the collection must be of
  * the "CdbBdbSCollectionElementP" class or derive from it.
  *
  * This collection is "unique" in respect to the values of the
  * keys (names and identifiers) of stored elements.
  *
  * The constructor allows to decide of either or both keys (name and
  * identifier) of the stored elements are used. At least one key is expected.
  */
class CdbBdbSCollectionP : public BdbPersObj {

public:

  /// Type definitions for the collection's iterators
  /**
    * These types are being introduced here to facilitate more flexible
    * type parametrisation of the collection's clients (including its
    * direct and indirect subclasses).
    */
    typedef CdbItr< const char* > IteratorOfNames;
    typedef CdbItr< d_UShort >    IteratorOfIdentifiers;

  /// B-tree and its entries types definition
  /**
    * The only reason to have this definition is to avoid DDL compilation problem
    * for the following definitions:
    *
    *     ooRef( template_class< another_template_class< ... > > )
    *
    * NOTE: That each specialization of the B-tree has to be explicitly
    *       instantiated by a user of this class for concrete values of
    *       of the d_UShort.
    */
    typedef CdbBdbSCollectionBte        BTreeEntry;
    typedef CdbBdbSBtreeP< BTreeEntry > BTreeP;

public:

  /// Default & normal constructor
  /**
    * Initializes an empty collection. It's _REQUIRED_ that
    * at least one of the flags passed as parameters must be true.
    */
    CdbBdbSCollectionP( bool useIdFlag   = true,    /**< tells the collection to use elements identifiers */
                        bool useNameFlag = true     /**< tells the collection to use elements names */
                      );

  /// Destructor
  /**
    * Will also destroy all the elements.
    */
    virtual ~CdbBdbSCollectionP( );

  /// Check if elements identifiers are used to sort elements in the collection.

    bool useId( ) const;

  /// Check if elements names are used to sort elements in the collection.

    bool useName( ) const;

  /// get the number of elements

    d_ULong elements( ) const;

  /// Insert an element
  /**
    * Both the element's name and its identifier are obtained from the element.
    * They both must be unique in the collection's scope.
    *
    * The collections taks over the ownership of the stored elements.
    */
    virtual CdbStatus insert( const BdbRef( CdbBdbSCollectionElementP )& theRef     /**< the object to insert */
                            );

  /// Find an object by its name
  /**
    * This method does not return the element's ownership
    *
    * The method will return CdbStatus::NotFound if the object was not
    * found in the folder. Other possible completion statuses are as usual.
    */
    virtual CdbStatus find( const char*                          theName,   /**< the object's name in the collection's scope */
                            BdbRef( CdbBdbSCollectionElementP )& theRef     /**< the reference to be initialized upon successfull completion */
                          ) const;

  /// Find an object by its identifier
  /**
    * The method will return CdbStatus::NotFound if the condition was not
    * found in the folder. Other possible completion statuses are as usual.
    */
    virtual CdbStatus find( d_UShort                             theId,     /**< the object's identifier */
                            BdbRef( CdbBdbSCollectionElementP )& theRef     /**< the reference to be initialized upon successfull completion */
                          ) const;

  /// Remove an element by its name
  /**
    * The found element will be also destroyed.
    *
    * The method will return CdbStatus::NotFound if the object was not
    * found in the folder. Other possible completion statuses are as usual.
    */
    virtual CdbStatus remove( const char* theName   /**< the object's name in the collection's scope */
                            );

  /// Remove an element by its name
  /**
    * The found element will be also destroyed.
    *
    * The method will return CdbStatus::NotFound if the object was not
    * found in the folder. Other possible completion statuses are as usual.
    */
    virtual CdbStatus remove( d_UShort theId        /**< the object's identifier */
                            );

  /// Get an instance of an iterator for names
  /**
    * This kind of iterator provides "non-sorted" access to the keys.
    */
    IteratorOfNames iterator_names( ) const;

  /// Get an instance of an iterator for identifiers
  /**
    * This kind of iterator provides "non-sorted" access to the keys.
    */
    IteratorOfIdentifiers iterator_identifiers( ) const;

  /// Dump the contents of the collection
  /**
    */
    virtual void dump( std::ostream& o ) const;

private:

  /// General verification for the passed element
  /**
    * Every input to the collection element passes this verification.
    */
    bool verifyElement( const BdbRef( CdbBdbSCollectionElementP )& theRef ) const;

private:

  /**
    * NOTE: Don't forget about proper template instantiation for the concrete template
    *       parameters of the B-tree.
    */
    BdbRef( BTreeP ) _treeRef;

  /// The (oo-)Map will store elements by their names

    BdbRef( BdbMap ) _mapRef;

  /// Total number of elements in the collection

    d_ULong _elements;
};

#endif /* CDBBDBSHARED_COLLECTION_P_HH */

---