---

CdbBdbSMetaDataP.cc

Go to the documentation of this file.

// File and Version Information:
//      $Id: CdbBdbSMetaDataP.cc,v 1.15 2004/08/06 05:54:24 bartoldu Exp $

/// The implementation file for the CdbBdbSMetaDataP class
/**
  * @see CdbBdbSMetaDataP
  */

#include "BaBar/BaBar.hh"

#include "CdbBdbShared/CdbBdbSMetaDataP.hh"
#include "CdbBdbShared/CdbBdbSRebuildAction.hh"

#include "CdbBdb/CdbBdbObjectClone.hh"

#include <iostream>
#include <assert.h>
#include <string.h>
using std::cout;
using std::endl;

namespace {

    ///////////////////////////////
    // Class: RevisionIdIterator //
    ///////////////////////////////

    class RevisionIdIterator : public CdbItr<BdbTime>::InterfaceType {

    private:

      /// The default constructor (NOT IMPLEMENTED)

        RevisionIdIterator( );

      /// The assignment operator (NOT IMPLEMENTED)

        RevisionIdIterator& operator=( const RevisionIdIterator& theItr );

    protected:

      /// The copy constructor
      /**
        * The only reason why we have it implemented is because it's needed
        * to implement the clone method.
        *
        * @see RevisionIdIterator::clone()
        */
        RevisionIdIterator( const RevisionIdIterator& theItr ) :
            _revCollectionRef      (theItr._revCollectionRef),
            _appendTopmostFlag     (theItr._appendTopmostFlag),
            _isValid               (theItr._isValid),
            _hasEverBeenAdvanced   (theItr._hasEverBeenAdvanced),
            _value                 (theItr._value),
            _revItr                (theItr._revItr),
            _thereIsTopmostToAppend(theItr._thereIsTopmostToAppend)
        { }

    public:

      /// The normal constructor

        RevisionIdIterator( const BdbRef(CdbBdbSRevCollectionP)& theRef,
                            bool                                 appendTopmostFlag ) :
            _revCollectionRef      (theRef),
            _appendTopmostFlag     (appendTopmostFlag),
            _isValid               (false),
            _hasEverBeenAdvanced   (false),
            _thereIsTopmostToAppend(appendTopmostFlag)
        {
            assert( !BdbIsNull(theRef));
        }

      /// The destructor

        virtual ~RevisionIdIterator( )
        { }

      /// Reset an iterator to its initial state.
      /**
        * This implements the corresponding method of the base class.
        *
        * @see CdbIItr::reset
        * @see CdbStatus
        */
        virtual CdbStatus reset( )
        {
            _isValid             = false;
            _hasEverBeenAdvanced = false;

            _thereIsTopmostToAppend = _appendTopmostFlag;

            return CdbStatus::Success;
        }

      /// Advance an iterator to the next position.
      /**
        * This implements the corresponding method of the base class.
        *
        * @see CdbIItr::next()
        */
        virtual bool next( )
        {
            if( !_isValid ) {

                if( !_hasEverBeenAdvanced ) {
                    _hasEverBeenAdvanced = true;

                    _revItr = _revCollectionRef->iterator_identifiers( );

                } else {

                  // This iterator should remain at "PAST_LAST_ELEMENT" state. The only way
                  // to get out of this state is to to call ::reset() method.

                    return false;
                }
            }
            if( _isValid && _revItr.isValid( ) && _revItr.next( )) {

              // We keep iterating in the valid state

                _value = _revItr.value( );

            } else if( !_isValid && _revItr.next( )) {

              // The first attemp to advance an iterator since it was initialized

                _value   = _revItr.value( );
                _isValid = true;

            } else {

              // It does not matter what was the previous state of the iterator
              // before since the only source of information would be the topmost revision
              // if any.

                if( _thereIsTopmostToAppend ) {
                    _thereIsTopmostToAppend = false;

                    _value   = BdbTime::plusInfinity;
                    _isValid = true;

                } else {

                  // Now we've got into the "PAST_LAST_ELEMENT" state.

                    _isValid = false;
                }
            }
            return _isValid;
        }

      /// Obtain the currently reffered value.
      /**
        * This implements the corresponding method of the base class.
        *
        * @see CdbIItr::value()
        * @see CdbIItr::ValueType
        *
        * @return the current value the iterator is set on
        */
        virtual ValueType value( )
        {
            if( _isValid ) {
                return _value;
            }

          // Invalid revision identifier.

            return BdbTime::minusInfinity;
        }

      /// Check if an iterator is valid.
      /**
        * This implements the corresponding method of the base class.
        *
        * @see CdbIItr::isValid()
        */
        virtual bool isValid( )
        {
            return _isValid;
        }

      /// Make a clone of itself
      /**
        * @see CdbIItr::clone()
        */
        virtual InterfaceType* clone( ) const
        {
            return new RevisionIdIterator( *this );
        }

    private:

        BdbRef(CdbBdbSRevCollectionP) _revCollectionRef;
        bool                          _appendTopmostFlag;

        bool _isValid;
        bool _hasEverBeenAdvanced;

        BdbTime _value;

        CdbItr<BdbTime> _revItr;

      // This flag is used to trigger appending the topmost revision (if required
      // by the corresponding iterator parameter) by the end of the sequence when
      // the original collection of revisions is exausted.

        bool _thereIsTopmostToAppend;
    };

    /////////////////////////////////
    // Class: RevisionNameIterator //
    /////////////////////////////////

    class RevisionNameIterator : public CdbItr<const char*>::InterfaceType {

    private:

      /// The default constructor (NOT IMPLEMENTED)

        RevisionNameIterator( );

      /// The assignment operator (NOT IMPLEMENTED)

        RevisionNameIterator& operator=( const RevisionNameIterator& theItr );

    protected:

      /// The copy constructor
      /**
        * The only reason why we have it implemented is because it's needed
        * to implement the clone method.
        *
        * @see RevisionNameIterator::clone()
        */
        RevisionNameIterator( const RevisionNameIterator& theItr ) :
            _revCollectionRef      (theItr._revCollectionRef),
            _appendTopmostFlag     (theItr._appendTopmostFlag),
            _isValid               (theItr._isValid),
            _hasEverBeenAdvanced   (theItr._hasEverBeenAdvanced),
            _value                 (theItr._value),
            _revItr                (theItr._revItr),
            _thereIsTopmostToAppend(theItr._thereIsTopmostToAppend)
        { }

    public:

      /// The normal constructor

        RevisionNameIterator( const BdbRef(CdbBdbSRevCollectionP)& theRef,
                              bool                                 appendTopmostFlag ) :
            _revCollectionRef      (theRef),
            _appendTopmostFlag     (appendTopmostFlag),
            _isValid               (false),
            _hasEverBeenAdvanced   (false),
            _value                 (""),
            _revItr                (0),
            _thereIsTopmostToAppend(appendTopmostFlag)
        {
            assert( !BdbIsNull(theRef));
        }

      /// The destructor

        virtual ~RevisionNameIterator( )
        { }

      /// Reset an iterator to its initial state.
      /**
        * This implements the corresponding method of the base class.
        *
        * @see CdbIItr::reset
        * @see CdbStatus
        */
        virtual CdbStatus reset( )
        {
            _isValid             = false;
            _hasEverBeenAdvanced = false;

            _thereIsTopmostToAppend = _appendTopmostFlag;

            return CdbStatus::Success;
        }

      /// Advance an iterator to the next position.
      /**
        * This implements the corresponding method of the base class.
        *
        * @see CdbIItr::next()
        */
        virtual bool next( )
        {
            if( !_isValid ) {

                if( !_hasEverBeenAdvanced ) {
                    _hasEverBeenAdvanced = true;

                    _revItr = _revCollectionRef->iterator_names( );

                } else {

                  // This iterator should remain at "PAST_LAST_ELEMENT" state. The only way
                  // to get out of this state is to to call ::reset() method.

                    return false;
                }
            }
            if( _isValid && _revItr.isValid( ) && _revItr.next( )) {

              // We keep iterating in the valid state

                _value = _revItr.value( );

            } else if( !_isValid && _revItr.next( )) {

              // The first attemp to advance an iterator since it was initialized

                _value   = _revItr.value( );
                _isValid = true;

            } else {

              // It does not matter what was the previous state of the iterator
              // before since the only source of information would be the topmost revision
              // if any.

                if( _thereIsTopmostToAppend ) {
                    _thereIsTopmostToAppend = false;

                    _value   = "<topmost>";
                    _isValid = true;

                } else {

                  // Now we've got into the "PAST_LAST_ELEMENT" state.

                    _isValid = false;
                }
            }
            return _isValid;
        }

      /// Obtain the currently reffered value.
      /**
        * This implements the corresponding method of the base class.
        *
        * @see CdbIItr::value()
        * @see CdbIItr::ValueType
        *
        * @return the current value the iterator is set on
        */
        virtual ValueType value( )
        {
            if( _isValid ) {
                return _value.c_str( );
            }

          // Invalid revision name.

            return 0;
        }

      /// Check if an iterator is valid.
      /**
        * This implements the corresponding method of the base class.
        *
        * @see CdbIItr::isValid()
        */
        virtual bool isValid( )
        {
            return _isValid;
        }

      /// Make a clone of itself
      /**
        * @see CdbIItr::clone()
        */
        virtual InterfaceType* clone( ) const
        {
            return new RevisionNameIterator( *this );
        }

    private:

        BdbRef(CdbBdbSRevCollectionP) _revCollectionRef;
        bool                          _appendTopmostFlag;

        bool _isValid;
        bool _hasEverBeenAdvanced;

        std::string _value;

        CdbItr<const char*> _revItr;

      // This flag is used to trigger appending the topmost revision (if required
      // by the corresponding iterator parameter) by the end of the sequence when
      // the original collection of revisions is exausted.

        bool _thereIsTopmostToAppend;
    };

    /////////////////////////////////////
    // Class: CombinedIntervalIterator //
    /////////////////////////////////////

    class CombinedIntervalIterator : public CdbItr<CdbBdbSCi>::InterfaceType {

    private:

      /// The default constructor (NOT IMPLEMENTED)

        CombinedIntervalIterator( );

      /// The assignment operator (NOT IMPLEMENTED)

        CombinedIntervalIterator& operator=( const CombinedIntervalIterator& theItr );

    protected:

      /// The copy constructor
      /**
        * The only reason why we have it implemented is because it's needed
        * to implement the clone method.
        *
        * @see CombinedIntervalIterator::clone()
        */
        CombinedIntervalIterator( const CombinedIntervalIterator& theItr ) :
            _viCollectionH      (theItr._viCollectionH),
            _oiCollectionH      (theItr._oiCollectionH),
            _beginTime          (theItr._beginTime),
            _endTime            (theItr._endTime),
            _isValid            (theItr._isValid),
            _hasEverBeenAdvanced(theItr._hasEverBeenAdvanced),
            _value              (theItr._value),
            _viItr              (theItr._viItr)
        { }

    public:

      /// The normal constructor

        CombinedIntervalIterator( const BdbRef(CdbBdbSViCollectionP)& theViCollectionRef,
                                  const BdbRef(CdbBdbSOiCollectionP)& theOiCollectionRef,
                                  const BdbTime&                      theBeginTime,
                                  const BdbTime&                      theEndTime ) :
            _viCollectionH      (theViCollectionRef),
            _oiCollectionH      (theOiCollectionRef),
            _beginTime          (theBeginTime),
            _endTime            (theEndTime),
            _isValid            (false),
            _hasEverBeenAdvanced(false)
        {
            assert( !BdbIsNull(theViCollectionRef));
            assert( !BdbIsNull(theOiCollectionRef));
        }

      /// The destructor

        virtual ~CombinedIntervalIterator( )
        { }

      /// Reset an iterator to its initial state.
      /**
        * This implements the corresponding method of the base class.
        *
        * @see CdbIItr::reset
        * @see CdbStatus
        */
        virtual CdbStatus reset( )
        {
            _isValid             = false;
            _hasEverBeenAdvanced = false;

            return CdbStatus::Success;
        }

      /// Try advancing the input iterator

        bool tryNext( )
        {
            bool result = false;
            do {

              // Advance the VI iterator to the next interval

                if( !_viItr.next( )) break;

                CdbBdbSVi vi = _viItr.value( );

              // Check for the end condition requering that the begin time
              // of found visible interval fall into the iterator's validity limits.
              //
              // Either of two scenarious:
              //
              // - begin time of the interval #1 falls into Interval #2
              // - begin time of the interval #2 falls into Interval #1
              //
              // In other "words":
              //
              //   #1    [.....)
              //   #2   [....)
              //
              // or:
              //
              //   #1  [.....)
              //   #2    [.....)
/*
 * DEBUG
                cout << "_beginTime = " << _beginTime.getGmtSec( ) << "." << _beginTime.getGmtNsec( ) << endl
                     << "vi.begin   = " << vi.begin.getGmtSec  ( ) << "." << vi.begin.getGmtNsec  ( ) << endl
                     << "vi.end     = " << vi.end.getGmtSec    ( ) << "." << vi.end.getGmtNsec    ( ) << endl
                     << "_endTime   = " << _endTime.getGmtSec  ( ) << "." << _endTime.getGmtNsec  ( ) << endl;
*/
                if( ! ((( _beginTime <= vi.begin   ) && ( vi.begin   < _endTime )) ||
                       (( vi.begin   <= _beginTime ) && ( _beginTime < vi.end   )))) break;

              // Construct the current value
              //
              // NOTE: We're not changing the "visibility" of found interval
              //       even if it partially falls beyond the limits of the current
              //       iterator. It's up to the application's logic to catch this
              //       problem. See the corresponding desciption in the client
              //       class's method.

                if( 0 == vi.value ) {

                  // This is a "hole" in the visible timeline because there is
                  // no any object for the duration of foudn visible interval.

                    _value = CdbBdbSCi( vi.begin,
                                        vi.end );
                } else {

                  // Ther emust be a valid object. Get the "original" interval
                  // describing it.

                    CdbBdbSOi oi;
                    BdbTime   beginOfDuration;  // not used
                    BdbTime   endOfDuration;    // not used

                    if( CdbStatus::Success != _oiCollectionH->find( vi.value,
                                                                    oi,
                                                                    beginOfDuration,
                                                                    endOfDuration )) {

                        assert( 0 );    // FATAL ERROR: inconsistent "visible"
                                        //              and "original" collections.
                        break;
                    }
                    _value = CdbBdbSCi( vi.begin,
                                        vi.end,
                                        oi );
                }

              // Done.

                result = true;

            } while( false );

            return result;
        }

      /// Advance an iterator to the next position.
      /**
        * This implements the corresponding method of the base class.
        *
        * @see CdbIItr::next()
        */
        virtual bool next( )
        {
            if( !_isValid ) {

                if( !_hasEverBeenAdvanced ) {
                    _hasEverBeenAdvanced = true;

                    _viItr = _viCollectionH->iterator( _beginTime );

                } else {

                  // This iterator should remain at "PAST_LAST_ELEMENT" state. The only way
                  // to get out of this state is to to call ::reset() method.

                    return false;
                }
            }
            if( !_isValid ) {

              // The first attemp to advance an iterator since it was initialized

                _isValid = tryNext( );

            } else if( _isValid && _viItr.isValid( )) {

              // We keep iterating in the valid state of the input iterator

                _isValid = tryNext( );

            } else {

              // Now we've got into the "PAST_LAST_ELEMENT" state.

               _isValid = false;
            }
            return _isValid;
        }

      /// Obtain the currently reffered value.
      /**
        * This implements the corresponding method of the base class.
        *
        * @see CdbIItr::value()
        * @see CdbIItr::ValueType
        *
        * @return the current value the iterator is set on
        */
        virtual ValueType value( )
        {
            if( ! _isValid ) assert( 0 );
            return _value;
        }

      /// Check if an iterator is valid.
      /**
        * This implements the corresponding method of the base class.
        *
        * @see CdbIItr::isValid()
        */
        virtual bool isValid( )
        {
            return _isValid;
        }

      /// Make a clone of itself
      /**
        * @see CdbIItr::clone()
        */
        virtual InterfaceType* clone( ) const
        {
            return new CombinedIntervalIterator( *this );
        }

    private:

      // Parameters of the iterator

        BdbHandle(CdbBdbSViCollectionP) _viCollectionH;
        BdbHandle(CdbBdbSOiCollectionP) _oiCollectionH;

        BdbTime _beginTime;
        BdbTime _endTime;

      // The state of the iterator

        bool _isValid;
        bool _hasEverBeenAdvanced;

        CdbBdbSCi _value;

        CdbBdbSViCollectionP::IteratorOfIntervals _viItr;
    };
};

/////////////////////////////
// Class: CdbBdbSMetaDataP //
/////////////////////////////

CdbBdbSMetaDataP::CdbBdbSMetaDataP( const BdbTime& theMinValidityTime,
                                    const BdbTime& theMaxValidityTime,
                                    const BdbTime& theMinInsertionTime ) :
    _minValidityTime(theMinValidityTime),
    _maxValidityTime(theMaxValidityTime),
    _minInsertionTime(theMinInsertionTime),
    _maxInsertionTime(BdbTime::plusInfinity),
    _modified(theMinInsertionTime)
{
    _originalCollectionRef = new( ooThis( )) CdbBdbSOiCollectionP( );
    _topmostRevisionRef    = new( ooThis( )) CdbBdbSRevisionP( );
    _revCollectionRef      = new( ooThis( )) CdbBdbSRevCollectionP( );
}

CdbBdbSMetaDataP::~CdbBdbSMetaDataP( ) 
{
    BdbDelete( _originalCollectionRef );
    BdbDelete( _topmostRevisionRef );
    BdbDelete( _revCollectionRef );
}

BdbTime
CdbBdbSMetaDataP::minValidity ( ) const
{
    return _minValidityTime;
}

BdbTime
CdbBdbSMetaDataP::maxValidity ( ) const
{
    return _maxValidityTime;
}

BdbTime
CdbBdbSMetaDataP::minInsertion( ) const
{
    return _minInsertionTime;
}

BdbTime
CdbBdbSMetaDataP::maxInsertion( ) const
{
    return _maxInsertionTime;
}

BdbRef( CdbBdbSOiCollectionP )
CdbBdbSMetaDataP::originaIntervalsCollection( ) const
{
    return _originalCollectionRef;
}

BdbTime
CdbBdbSMetaDataP::modified( ) const
{
    return _modified;
}

CdbStatus
CdbBdbSMetaDataP::close( const BdbTime& theMaxInsertionTime,
                         const char*    theNewRevisionName,
                         const BdbTime& theNewRevisionCreationTime,
                         const char*    theNewRevisionDescription )
{
    ooUpdate( );

    const char* errorStr = "CdbBdbSMetaDataP::close() -- ERROR";

    CdbStatus result = CdbStatus::Error;
    do {

      // Verify parameters

        if( CdbStatus::Success != verifyInsertionTime( theMaxInsertionTime )) {
            cout << errorStr << endl
                 << "    Specified insertion time is not correct." << endl
                 << "    See details above." << endl;
            break;
        }
        if( theMaxInsertionTime <= _modified ) {
            cout << errorStr << endl
                 << "    Specified insertion time is not correct." << endl
                 << "    Current operation requires this time to be strictly greater than" << endl
                 << "    the most recent modification time of the MetaData object." << endl
                 << "        PASSED MAX.INSERTION TIME: " << theMaxInsertionTime << endl
                 << "        CURRENT MODIFICATION TIME: " << _modified << endl;
            break;
        }

      // Check if there is a revision with the current value of the modification
      // time.

        BdbRef(CdbBdbSRevisionP) rRef;
        if( CdbStatus::Success != _revCollectionRef->find( _modified,
                                                           rRef )) {

          // Then we also require that revision parameters were passed.

            if(( 0 == theNewRevisionName ) ||
               ( BdbTime::minusInfinity == theNewRevisionCreationTime ) ||
               ( 0 == theNewRevisionDescription )) {
                cout << errorStr << endl
                     << "    Invalid revision parameters passed to the procedure when" << endl
                     << "    a final revision is about to be created. This revision has" << endl
                     << "    be created before closing the MetaData object." << endl;
                break;
            }

          // Create the one.

            if( CdbStatus::Success != createRevision( _modified,
                                                      theNewRevisionName,
                                                      theNewRevisionCreationTime,
                                                      theNewRevisionDescription )) {
                cout << errorStr << endl
                     << "    Failed to create new revision before closing the MetaData object." << endl;
                break;
            }
        }

      // Destroy the topmost revision.

        BdbDelete(_topmostRevisionRef);
        _topmostRevisionRef = 0;

      // Set up the time.

        _maxInsertionTime = theMaxInsertionTime;

      // Done.

        result = CdbStatus::Success;

    } while( false );

    return result;
}

CdbStatus
CdbBdbSMetaDataP::insert( const CdbBdbSOi& theInterval )
{
    ooUpdate( );

    const char* errorStr = "CdbBdbSMetaDataP::insert() -- ERROR";
    const char* fatalStr = "CdbBdbSMetaDataP::insert() -- FATAL INTERNAL ERROR!!!";

    CdbStatus result = CdbStatus::Error;
    do {

      // Verify parameters.

        if( CdbStatus::Success != verifyInsertionTime( theInterval.inserted )) {
            cout << errorStr << endl
                 << "    The insertion time of the passed interval is not correct." << endl
                 << "    See details above." << endl;
            break;
        }
        if( BdbIsNull( theInterval.object )) {
            cout << errorStr << endl
                 << "    The passed interval points to 0-0-0-0 condition object." << endl
                 << "    This interval can't be inserted." << endl;
            break;
        }
        if( theInterval.inserted < _modified ) {
            cout << errorStr << endl
                 << "    The insertion time of the passed interval is not correct." << endl
                 << "    Current operation requires this time to be greater or equal to" << endl
                 << "    the most recent modification time of the MetaData object." << endl
                 << "        PASSED INSERTION TIME:     " << theInterval.inserted << endl
                 << "        CURRENT MODIFICATION TIME: " << _modified << endl;
            break;
        }

      // Calculate the crossection of the passed interval with the "validity"
      // window of the current metadata object. The resulting interval should
      // not have 0 length.

        CdbBdbSOi oiInterval = theInterval;

        if( oiInterval.begin < _minValidityTime ) oiInterval.begin = _minValidityTime;
        if( oiInterval.end   > _maxValidityTime ) oiInterval.end   = _maxValidityTime;

        if( oiInterval.begin >= oiInterval.end ) {
            cout << errorStr << endl
                 << "    The passed interval does not have any cross-section" << endl
                 << "    with the validity window of the metadata object." << endl
                 << "    This interval can't be inserted." << endl;
            break;
        }

      // Insert into the "original" collection"

        d_ULong oiIdx;      // The subsequent operation will set up this value
                            // so it can be used to register new interval in
                            // the "visible" intervals collection.

        if( CdbStatus::Success != _originalCollectionRef->insert( oiInterval, oiIdx )) {
            cout << errorStr << endl
                 << "    Failed to register the interval in the 'original' intervals collection." << endl;
            break;
        }

      // Insert into the "visible" intervals collection of the "TOPMOST" revision.

        if( CdbStatus::Success != _topmostRevisionRef->collection( )->insert( oiInterval.begin,
                                                                              oiInterval.end,
                                                                              oiIdx )) {
            cout << fatalStr << endl
                 << "    Failed to register the interval in the 'visible' intervals collection" << endl
                 << "    of the 'TOPMOST' revision. This puts the metadata object into" << endl
                 << "    an inconsistent state." << endl;

            assert( 0 );    // FATAL INTERNAL ERROR!!!!

            break;
        }

      // Update modification time

        _modified = theInterval.inserted;

      // Done.

        result = CdbStatus::Success;

    } while( false );

    return result;
}

CdbStatus
CdbBdbSMetaDataP:: rebuild( CdbBdbSRebuildAction* theRebuildAction,
                            const BdbTime&        theBeginTime,
                            const BdbTime&        theEndTime )
{
    ooUpdate( );

    const char* errorStr = "CdbBdbSMetaDataP::rebuild() -- ERROR";
    const char* fatalStr = "CdbBdbSMetaDataP::rebuild() -- FATAL INTERNAL ERROR!!!";

    CdbStatus result = CdbStatus::Error;
    do {

      // Verify the parameters

        if( theBeginTime >= theEndTime ) {
            cout << errorStr << endl
                 << "    Incorrect validity time range passed to the procedure." << endl;
            break;
        }

      // Verify if there is non no-topmost revision in the metadata object.
      //
      // NOTES:
      //
      //   (1) We'll _NOT_ allow the current operation if there is at least one revision
      //       (except the 'TOPMOST' one) created at or after the specified "begin insertion"
      //       time.
      //
      //   (2) Revisions created strictly _before_ must be okay since "visible intervals"
      //       of the revisions are relying on numbers (indexes) of "original intervals"
      //       in the "original intervals collections", which itself has a fixed (continous)
      //       sequence of numbers starting from 1 (o is reserved for special purposes).
      //       It means that original intervals created before the specified "begin time"
      //       will get the same numbers in the recretead collection as they have it in
      //       the older one.

        {
            CdbItr<BdbTime> rItr;
            if( CdbStatus::Success != revisionIdIterator( rItr )) {
                cout << errorStr << endl
                     << "    Failed to get an iterator of revisions for the current metadata object." << endl;
                break;
            }

            bool failed = false;

            while( rItr.next( )) {
                if( BdbTime::plusInfinity != rItr.value( )) {
                    if( rItr.value( ) >= theBeginTime ) {
                        cout << errorStr << endl
                             << "    A non-topmost revision created at or after the specifid begin time" << endl
                             << "    passed to the procedure has been detected:" << endl
                             << "        REVISION ID : " << rItr.value( ).getGmtSec( ) << "." << rItr.value( ).getGmtNsec( ) << " " << rItr.value( ) << endl
                             << "        BEGIN TIME  : " <<  theBeginTime.getGmtSec( ) << "." <<  theBeginTime.getGmtNsec( ) << " " << theBeginTime  << endl
                             << "    The operation is not allowed for this metadata." << endl;
                        failed = true;
                        break;
                    }
                }
            }
            if( failed ) break;
        }

      // Verify if the current metadata object is still open

        if( BdbTime::plusInfinity != _maxInsertionTime ) {
            cout << errorStr << endl
                 << "    The current metadata object is in the 'closed' state." << endl
                 << "    The operation is not allowed for this metadata." << endl;
            break;
        }


      // Reset the current state of the metadata object and keep an old collection
      // of original intervals aside for the duratiuon of copying. The current state of
      // the metadata object will be updated when we'll be evaluating and copying
      // intervals from the input collection of original intervals.

      // 1: Reset the modification time back to the begin time of the "insertion"
      //    timeline window of the metadata. This modification time will be updated later on
      //    when copying original interval from the current collection into the output one.

        _modified = _minInsertionTime;

      // 2: Remember the old (input) collection of original intervals and create its
      //    replacement (the output one). The old collection will be destroyed when we'll
      //    finish rebuilding.

        BdbHandle( CdbBdbSOiCollectionP ) inputOriginalCollectionH = _originalCollectionRef;
        _originalCollectionRef = new( ooThis( )) CdbBdbSOiCollectionP( );

      // 3: Reset topmost revision which are going to be populated in a course of rebuilding.

        BdbDelete(_topmostRevisionRef);
        _topmostRevisionRef = new( ooThis( )) CdbBdbSRevisionP( );

      // 4: Keep a collection of non-topmost revisions since it's not going to be affected
      //    by the current operation (see the "Verify" section above for details).
      //
      //    IMPORTANT: As a temporary measure, to avoid confusing the ::insert()
      //               method we will create an empty temporary collection and preserve
      //               the current one. Then, when we'll finish updating intervals
      //               then we'll put the current collection back.

        BdbRef( CdbBdbSRevCollectionP ) savedRevCollectionRef = _revCollectionRef;
        _revCollectionRef = new( ooThis( )) CdbBdbSRevCollectionP( );

      // Scan input collections and fill the output ones using user supplied action object.
      //
      // NOTE: We're scanning the input collection begining from an interval
      //       with 1 index rather than with 0, which has a special meaning.

        bool failed = false;

        d_ULong num = inputOriginalCollectionH->size( );
        for( d_ULong i = 1; i < num; ++i ) {

          // Get next input interval

            CdbBdbSOi oi;

            BdbTime beginOfDuration;  // not used, but required by the API
            BdbTime endOfDuration;    // ditto

            if( CdbStatus::Success != inputOriginalCollectionH->find( i,
                                                                      oi,
                                                                      beginOfDuration,
                                                                      endOfDuration )) {
                cout << fatalStr << endl
                     << "    Failed to obtain an original interval with index " << i << " from the current collection." << endl
                     << "    The collection may be corrupted." << endl;

                assert( 0 );    // FATAL INTERNAL ERROR!!!!

                failed = true;
                break;
            }

          // If this interval is in the specified insertion time window then let a user
          // do decide on what to do with this interval. Otherwise simply copy it into the output
          // collections.

            CdbBdbSRebuildAction::ActionType action = CdbBdbSRebuildAction::ACTION_COPY;

            if(( theBeginTime <= oi.inserted ) && ( oi.inserted < theEndTime )) {

                action = theRebuildAction->userAction( oi );
                if( CdbBdbSRebuildAction::ACTION_ERROR == action ) {

                    cout << errorStr << endl
                         << "    User action has failed when processing an original interval." << endl;

                    failed = true;
                    break;
                }
            }

          // Copy the interval into the output collections and register it in
          // the topmost revision.
          //
          // NOTE: We're using a local copy of the original interval, which
          //       may have been modified by a user action.

            if( CdbBdbSRebuildAction::ACTION_COPY == action ) {
                if( CdbStatus::Success != insert( oi )) {
                    cout << errorStr << endl
                         << "    Failed to store an original interval in the rebuilt collection." << endl;
                    failed = true;
                    break;
                }
            }
        }
        if( failed ) break;

      // Replace the temporary collection of revisions with the saved one.
      //
      // Then update the modification time to the most recent one, which would go either from
      // the collection of original intervals or from the latest revision.

        BdbDelete(_revCollectionRef);
        _revCollectionRef = savedRevCollectionRef;

        BdbTime recentlyModifiedTime = recentlyModified( );
        if( recentlyModifiedTime > _modified ) _modified = recentlyModifiedTime;

      // Got rid of the input original collection. We don't need it any more since
      // we've moved all relevant data into a right places.

        BdbDelete( inputOriginalCollectionH );

      // Done

        result = CdbStatus::Success;

    } while( false );
    
    return result;
}

CdbStatus
CdbBdbSMetaDataP::repoint( CdbBdbObjectClone&         theObjectCloningTool,
                           CdbBdbCache<ooRef(ooObj)>& theTranslationDictionary )
{
    const char* fatalStr = "CdbBdbSMetaDataP::repoint() -- FATAL INTERNAL ERROR!!!";
    const char* errorStr = "CdbBdbSMetaDataP::repoint() -- ERROR";

    CdbStatus result = CdbStatus::Error;
    do {

      // Scan the original collection and modify its elements

        bool failed = false;

        d_ULong num = _originalCollectionRef->size( );
        for( d_ULong i = 1; i < num; ++i ) {

          // Get next input interval

            CdbBdbSOi oi;

            BdbTime beginOfDuration;  // not used, but required by the API
            BdbTime endOfDuration;    // ditto

            if( CdbStatus::Success != _originalCollectionRef->find( i,
                                                                    oi,
                                                                    beginOfDuration,
                                                                    endOfDuration )) {
                cout << fatalStr << endl
                     << "    Failed to obtain an original interval with index " << i << " from the current collection." << endl
                     << "    The collection may be corrupted." << endl;

                assert( 0 );    // FATAL INTERNAL ERROR!!!!

                failed = true;
                break;
            }

          // Skip this intervak if the object is 0-0-0-0

            if( BdbIsNull( oi.object )) continue;

          // Clone the object.

            ooHandle(ooObj) oldH = oi.object;
            ooHandle(ooObj) newH = 0;

            if( !theObjectCloningTool.clone( oldH,
                                             newH )) {

                cout << errorStr << endl
                     << "    Failed to clone an old object from the original interval with index " << i << " from the current collection." << endl
                     << "    The collection may be corrupted. Or there may be some other problem with the federation." << endl;

                failed = true;
                break;
            }

          // Repoint the oid object in the 'original' interval with the new objects
          // then update the original collection at the current index.

            ooRef(ooObj) newObjectRef = newH;               // Convert to the reference first
            oi.object = (BdbRef(BdbObject)) newObjectRef;   // Then cust and repoint

            if( CdbStatus::Success != _originalCollectionRef->replace( oi,
                                                                       i )) {
                cout << errorStr << endl
                     << "    Failed to replace the original interval with updated one at index " << i << " of the current collection." << endl;

                failed = true;
                break;
            }

          // Update the dictionary
          //
          // NOTE: The logic of the update also includes a consistency check to make sure
          //       that the cloning algorithm is not broken (at least) in the scope of
          //       of the current metadata object. So, for example, we want to assure
          //       that there is a unique new OID for each old one.

            ooRef(ooObj) oldObjectRef = oldH;   // Convert to the reference first

            ooRef(ooObj) valueRef = theTranslationDictionary.findObject( oldObjectRef );
            if( 0 == valueRef ) {
                theTranslationDictionary.addObject( oldObjectRef,
                                                    newObjectRef );
            } else {
                if( valueRef != newObjectRef ) {

                    cout << fatalStr << endl
                         << "    Dangerous inconsistency found in the data structures used by" << endl
                         << "    the repointing operation. The resulting metadata object may be useless." << endl
                         << "    This may be an indication of a serious bug in the caller's code." << endl;

                    assert( 0 );    // FATAL INTERNAL ERROR!!!!

                    failed = true;
                    break;
                }
            }
        }
        if( failed ) break;

      // Done

        result = CdbStatus::Success;

    } while( false );
    
    return result;
}


CdbStatus
CdbBdbSMetaDataP::findByRevision( const BdbTime& theRevisionId,
                                  const BdbTime& theValidityTime,
                                  CdbBdbSOi&     theOriginalInterval,
                                  BdbTime&       theBeginOfVisiblePeriod,
                                  BdbTime&       theEndOfVisiblePeriod ) const
{
    const char* errorStr = "CdbBdbSMetaDataP::findByRevision() -- ERROR";
    const char* fatalStr = "CdbBdbSMetaDataP::findByRevision() -- FATAL INTERNAL ERROR!!!";

    CdbStatus result = CdbStatus::Error;
    do {

      // This is required by the public contract of the method.

        theBeginOfVisiblePeriod = _minValidityTime;
        theEndOfVisiblePeriod   = _maxValidityTime;

      // Verify the parameters

        if(( theValidityTime <  _minValidityTime ) ||
           ( theValidityTime >= _maxValidityTime)) {
            cout << errorStr << endl
                 << "    The passed validity time is out of the validity window" << endl
                 << "    of the current metadata object." << endl;
            break;
        }

      // Get to the specified revision, and then to the collection
      // of "visible" intervals.

        BdbRef( CdbBdbSRevisionP ) revisionRef;
        if( BdbTime::plusInfinity == theRevisionId ) {
            if( BdbIsNull(_topmostRevisionRef)) {
                cout << errorStr << endl
                     << "    The topmost revision is not available in this Meta Data collection" << endl
                     << "    because the collection is closed." << endl;
                break;
            }
            revisionRef = _topmostRevisionRef;
        } else {
            if( CdbStatus::Success != _revCollectionRef->find( theRevisionId, revisionRef )) {
                cout << errorStr << endl
                     << "    Specified revision was not found in the collection." << endl
                     << "        PASSED REVISION ID: " << theRevisionId << endl;
                break;
            }
        }
        BdbRef( CdbBdbSViCollectionP ) collectionRef = revisionRef->collection( );

      // Find a "visible" interval through the "visible" collection.
      //
      // IMPORTANT NOTE:
      //
      //     This operation if successfull will return us a short description
      //     of visible interval. The "successful" may also mean 0 index. No matter what
      //     is the value of the original interval's index carried by the visible interval
      //     still we have very important information about the visible validity range of
      //     the found index. If this ois 0 index the we have the visible validity interval
      //     of a 'hole', and if it's not then its the interval of an actual object.
      //
      //     Assigning the correct value to the visible validity interval is required
      //     by the contract of the current method.

        CdbBdbSVi viInterval;

        if( ! collectionRef->find( viInterval, theValidityTime )) {

            assert( 0 );    // Inconsistent TimeLine. All range of the insertion time
                            // must be covered.
            break;
        }

        theBeginOfVisiblePeriod = viInterval.begin;
        theEndOfVisiblePeriod   = viInterval.end;

        d_ULong oiIdx = viInterval.value;       // Get to the index of the 'original' interval
        if( 0 == oiIdx ) {
            result = CdbStatus::NotFound;
            break;
        }

      // Extract the "original" interval information and setup the values
      // of parameters to be returned.

        BdbTime beginOfDurationPeriod( 0 );     // Don't need this information
        BdbTime endOfDurationPeriod  ( 0 );     // Don't need this information

        if( CdbStatus::Success != _originalCollectionRef->find( oiIdx,
                                                                theOriginalInterval,
                                                                beginOfDurationPeriod,
                                                                endOfDurationPeriod )) {
            cout << fatalStr << endl
                 << "    The collection of 'visible' intervals does not match" << endl
                 << "    the collection of 'original' intervals." << endl;

            assert( 0 );    // FATAL INTERNAL ERROR!!!!

            break;
        }

      // Done

        result = CdbStatus::Success;

    } while( false );
    
    return result;
}

CdbStatus
CdbBdbSMetaDataP::findByRevision( const char*    theRevisionName,
                                  const BdbTime& theValidityTime,
                                  CdbBdbSOi&     theOriginalInterval,
                                  BdbTime&       theBeginOfVisiblePeriod,
                                  BdbTime&       theEndOfVisiblePeriod ) const
{
    const char* errorStr = "CdbBdbSMetaDataP::findByRevision() -- ERROR";

    CdbStatus result = CdbStatus::Error;
    do {

      // This is required by the public contract of the method.

        theBeginOfVisiblePeriod = _minValidityTime;
        theEndOfVisiblePeriod   = _maxValidityTime;

      // Do not verify anything - just find a revision by name
      // and do the rest through the similar procedure.

        BdbTime revisionId( 0 );

        if( 0 == theRevisionName ) {
            revisionId = BdbTime::plusInfinity;     // TOPMOST revision
        } else {
            BdbRef( CdbBdbSRevisionP ) revisionRef;
            if( CdbStatus::Success != _revCollectionRef->find( theRevisionName, revisionRef )) {
                cout << errorStr << endl
                     << "    Specified revision was not found in the collection." << endl
                     << "        PASSED REVISION NAME: " << theRevisionName << endl;
                break;
            }
            revisionId = revisionRef->id( );
        }

      // Proceed to the actual finder...

        result = findByRevision( revisionId,
                                 theValidityTime,
                                 theOriginalInterval,
                                 theBeginOfVisiblePeriod,
                                 theEndOfVisiblePeriod );

    } while( false );
    
    return result;
}

CdbStatus
CdbBdbSMetaDataP::findByInsertion( const BdbTime& theInsertionTime,
                                   const BdbTime& theValidityTime,
                                   CdbBdbSOi&     theOriginalInterval,
                                   BdbTime&       theBeginOfDurationPeriod,
                                   BdbTime&       theEndOfDurationPeriod ) const
{
    const char* errorStr = "CdbBdbSMetaDataP::findByInsertion() -- ERROR";

    CdbStatus result = CdbStatus::Error;
    do {

      // Verify the parameters

        if(( theValidityTime <  _minValidityTime ) ||
           ( theValidityTime >= _maxValidityTime)) {
            cout << errorStr << endl
                 << "    The passed validity time is out of the validity window" << endl
                 << "    of the current metadata object." << endl;
            break;
        }
        if(( theInsertionTime <  _minInsertionTime ) ||
           ( theInsertionTime >= _maxInsertionTime)) {
            cout << errorStr << endl
                 << "    The passed insertion time is out of the insertion window" << endl
                 << "    of the current metadata object." << endl;
            break;
        }

      // Find the "original" interval and its "duration" interval through
      // the "original" collection.
      //
      // NOTE: We preserve the returned status since it may also be equal
      //       to CdbStatus::NotFound if the 0-0-0-0 reference found instead
      //       of an actual object.

        CdbStatus status = _originalCollectionRef->find( theInsertionTime,
                                                         theOriginalInterval,
                                                         theBeginOfDurationPeriod,
                                                         theEndOfDurationPeriod );
        if( CdbStatus::Success != status ) {
            result = status;
            break;
        }

      // Check if the specified "validity" time falls into the "original"
      // "validity" of this interval.

        if(( theValidityTime <  theOriginalInterval.begin ) ||
           ( theValidityTime >= theOriginalInterval.end   )) {
            cout << errorStr << endl
                 << "    This is inappropriate use of this finding method since" << endl
                 << "    the passed validity time does not fall into the 'validity' period" << endl
                 << "    of found 'original' interval." << endl;
            break;
        }

      // Done

        result = CdbStatus::Success;

    } while( false );
    
    return result;
}
CdbStatus
CdbBdbSMetaDataP::findRevision( const BdbTime&            theId,
                                BdbRef(CdbBdbSRevisionP)& theRef ) const
{
    CdbStatus result = CdbStatus::NotFound;
    do {

      // Check if the specified revision identifier time falls into
      // the "window" of current metadata object.
      //
      // NOTE: Passing +Infinity is allowed.

        if( theId < _minInsertionTime ) break;
        if(( BdbTime::plusInfinity != _maxInsertionTime ) && ( theId >= _maxInsertionTime )) break;

      // Check if the topmost revision was requested

        if( BdbTime::plusInfinity == theId ) {

            if( !BdbIsNull(_topmostRevisionRef)) {
                theRef = _topmostRevisionRef;
                result = CdbStatus::Success;
            }

        } else {

          // Delegate revision lookup down to the revisions collection

            result = _revCollectionRef->find( theId,
                                              theRef );
        }

    } while( false );

    return result;
}

CdbStatus
CdbBdbSMetaDataP::findRevision( const char*               theName,
                                BdbRef(CdbBdbSRevisionP)& theRef ) const
{
    const char* errorStr = "CdbBdbSMetaDataP::findRevision(name) -- ERROR";

    CdbStatus result = CdbStatus::NotFound;
    do {

      // Verify parameters

        if( 0 == theName ) {
            cout << errorStr << endl
                 << "    Null pointer passed instead of a valid revision name." << endl;
            break;
        }

      // Check if the topmost revision was requested

        if( 0 == strcmp( "<topmost>", theName )) {

            if( !BdbIsNull(_topmostRevisionRef)) {
                theRef = _topmostRevisionRef;
                result = CdbStatus::Success;
            }

        } else {

          // Delegate revision lookup down to the revisions collection

            result = _revCollectionRef->find( theName,
                                              theRef );
        }

    } while( false );

    return result;
}

CdbStatus
CdbBdbSMetaDataP::createRevision( const BdbTime& theId,
                                  const char*    theName,
                                  const BdbTime& theCreationTime,
                                  const char*    theDescription )
{
    ooUpdate( );

    const char* errorStr = "CdbBdbSMetaDataP::createRevision -- ERROR";

    CdbStatus result = CdbStatus::Error;
    do {

      // Verify the parameters

        if( CdbStatus::Success != verifyInsertionTime( theId )) {
            cout << errorStr << endl
                 << "    Specified revision identifier is not correct." << endl
                 << "    See details above." << endl;
            break;
        }
        if( 0 == strcmp( "<topmost>", theName )) {
            cout << errorStr << endl
                 << "    The special name '<topmost>' passed as a new revision name." << endl
                 << "    This name is reserved for the automatically created topmost revision" << endl
                 << "    and can't be used to create user-defined revisions." << endl;
            break;
        }
        if( theCreationTime < theId ) {
            cout << errorStr << endl
                 << "    Invalid revision creation time passsed to the procedure. This name should not" << endl
                 << "    be less than the revision identifiedr time." << endl
                 << "        PASSED REVISION ID:            " << theId << endl
                 << "        PASSED REVISION CREATION TIME: " << theCreationTime << endl;
            break;
        }
        if( theId < _modified ) {
            cout << errorStr << endl
                 << "    The identifier time of the passed revision is not correct." << endl
                 << "    Current operation requires this time to be greater or equal to" << endl
                 << "    the most recent modification time of the MetaData object." << endl
                 << "        PASSED INSERTION TIME:     " << theId << endl
                 << "        CURRENT MODIFICATION TIME: " << _modified << endl;
            break;
        }
        if( 0 == theDescription ) {
            cout << errorStr << endl
                 << "    Null pointer passed instead a valid revision description." << endl;
            break;
        }

      // Create new revision object by taking a snapshot of the "visible"
      // intervals collection of the current topmost revision.

        BdbRef(CdbBdbSRevisionP) revisionRef;
        revisionRef = new ( ooThis( )) CdbBdbSRevisionP( theId,
                                                         theName,
                                                         _topmostRevisionRef->collection( ),
                                                         theCreationTime,
                                                         theDescription );

      // Register new revision in the collection.
      //
      // NOTE: This operation will also verify the parameters of the new revision
      //       in the collection's context.

        if( CdbStatus::Success != _revCollectionRef->insert( revisionRef )) {
            cout << errorStr << endl
                 << "    Failed to insert new revision into the collection." << endl;
            BdbDelete( revisionRef );
            break;
        }

      // Update modification time if the new revision identifier is greater
      // than the current value of the modification time.

        if( theId > _modified ) _modified = theId;

      // Done

        result = CdbStatus::Success;

    } while( false );
    
    return result;
}

CdbStatus
CdbBdbSMetaDataP::revisionIdIterator( CdbItr<BdbTime>& theItr ) const
{
  // ATTENTION: This is not a memory leak - the created object
  //            will be destroyed by the iterator.

    theItr = CdbItr<BdbTime>( new RevisionIdIterator( _revCollectionRef,
                                                      !BdbIsNull(_topmostRevisionRef)));
    return CdbStatus::Success;
}

CdbStatus
CdbBdbSMetaDataP::revisionNameIterator( CdbItr<const char*>& theItr ) const
{
  // ATTENTION: This is not a memory leak - the created object
  //            will be destroyed by the iterator.

    theItr = CdbItr<const char*>( new RevisionNameIterator( _revCollectionRef,
                                                            !BdbIsNull(_topmostRevisionRef)));
    return CdbStatus::Success;
}

bool
CdbBdbSMetaDataP::verifyObjectIteratorParameters( const BdbTime& theBeginTime,
                                                  const BdbTime& theEndTime ) const
{
    const char* errorStr = "CdbBdbSMetaDataP::verifyObjectIteratorParameters() -- ERROR";

    bool result = false;
    do {

      // See formal requirements at the class's description

        if( ! (( _minValidityTime <= theBeginTime ) && ( theBeginTime < _maxValidityTime ))) {
            cout << errorStr << endl
                 << "    Incorrect begin time passed to the method. It's out of the validity" << endl
                 << "    time window of the current meta-data object." << endl
                 << "        PASSED BEGIN TIME : " << theBeginTime << endl
                 << "        WINDOW BEGIN TIME : " << _minValidityTime << endl
                 << "        WINDOW END   TIME : " << _maxValidityTime << endl;
            break;
        }
        if( ! (( _minValidityTime < theEndTime ) && ( theEndTime <= _maxValidityTime ))) {
            cout << errorStr << endl
                 << "    Incorrect end time passed to the method. It's out of the validity" << endl
                 << "    time window of the current meta-data object." << endl
                 << "        PASSED END   TIME : " << theEndTime << endl
                 << "        WINDOW BEGIN TIME : " << _minValidityTime << endl
                 << "        WINDOW END   TIME : " << _maxValidityTime << endl;
            break;
        }
        if(  ! ( theBeginTime < theEndTime )) {
            cout << errorStr << endl
                 << "    Incorrect begin and end times passed to the method." << endl
                 << "    The begin time must be strictly less (older) than the end one. " << endl
                 << "        PASSED BEGIN TIME : " << theBeginTime << endl
                 << "        PASSED END   TIME : " << theEndTime << endl;
            break;
        }

      // Done

        result = true;

    } while( false );

    return result;
}

CdbStatus
CdbBdbSMetaDataP::objectIterator( CdbItr<CdbBdbSCi>& theItr,
                                  const BdbTime&     theRevisionId,
                                  const BdbTime&     theBeginTime,
                                  const BdbTime&     theEndTime ) const
{
    const char* errorStr = "CdbBdbSMetaDataP::objectIterator(id) -- ERROR";

    CdbStatus result = CdbStatus::Error;
    do {

        if( ! verifyObjectIteratorParameters( theBeginTime,
                                              theEndTime )) break;
      // Find revision

        BdbRef(CdbBdbSRevisionP) revisionRef;
        if( CdbStatus::Success != findRevision( theRevisionId,
                                                revisionRef )) {
            cout << errorStr << endl
                 << "    Failed to find a revision for specified identifier." << endl
                 << "        REVISION IDENTIFIER : " << theRevisionId << endl;
        }

      // ATTENTION: This is not a memory leak - the created object
      //            will be destroyed by the iterator.

        theItr = CdbItr<CdbBdbSCi>( new CombinedIntervalIterator( revisionRef->collection( ),
                                                                  _originalCollectionRef,
                                                                  theBeginTime,
                                                                  theEndTime ));

      // Done

        result = CdbStatus::Success;

    } while( false );

    return result;
}

CdbStatus
CdbBdbSMetaDataP::objectIterator( CdbItr<CdbBdbSCi>& theItr,
                                  const char*        theName,
                                  const BdbTime&     theBeginTime,
                                  const BdbTime&     theEndTime ) const
{
    const char* errorStr = "CdbBdbSMetaDataP::objectIterator(name) -- ERROR";

    CdbStatus result = CdbStatus::Error;
    do {

        if( ! verifyObjectIteratorParameters( theBeginTime,
                                              theEndTime )) break;

      // Find revision

        BdbRef(CdbBdbSRevisionP) revisionRef;
        if( CdbStatus::Success != findRevision( theName,
                                                revisionRef )) {
            cout << errorStr << endl
                 << "    Failed to find a revision for specified name." << endl
                 << "        REVISION NAME : " << theName << endl;
            break;
        }

      // ATTENTION: This is not a memory leak - the created object
      //            will be destroyed by the iterator.

        theItr = CdbItr<CdbBdbSCi>( new CombinedIntervalIterator( revisionRef->collection( ),
                                                                  _originalCollectionRef,
                                                                  theBeginTime,
                                                                  theEndTime ));

      // Done

        result = CdbStatus::Success;

    } while( false );

    return result;
}

bool
CdbBdbSMetaDataP::isClosed( ) const
{
    return BdbTime::plusInfinity != _maxInsertionTime;
}

BdbTime
CdbBdbSMetaDataP::recentlyModified( ) const
{
    BdbTime result = BdbTime::minusInfinity;
    {
      // Check the "original" intervals collection

        CdbBdbSOi lastOiInterval;
        if( CdbStatus::Success == _originalCollectionRef->last( lastOiInterval )) {
            if( lastOiInterval.inserted > result ) result = lastOiInterval.inserted;
        }

      // Check the collection of revisions (revisions may get created
      // at any after the "original" intervals insertions.
      //
      // We're only asking for the ID of this revision.

        BdbTime revId( 0 );
        if( CdbStatus::Success == _revCollectionRef->last( revId )) {
            if( revId > result ) result = revId;
        }
    }
    return result;
}

CdbStatus
CdbBdbSMetaDataP::verifyInsertionTime( const BdbTime& theTime ) const
{
    const char* errorStr = "CdbBdbSMetaDataP::verifyInsertionTime -- ERROR";

    CdbStatus result = CdbStatus::Error;
    do {

      // Verify the current context of the metadata object.

        if( isClosed( )) {
            cout << errorStr << endl
                 << "    The metadata object is already closed for further modifications." << endl;
            break;
        }

      // Verify the parameters

        if(( BdbTime::minusInfinity == theTime ) ||
           ( BdbTime::plusInfinity  == theTime )) {
            cout << errorStr << endl
                 << "    Invalid value of the insertion time. It should not be" << endl
                 << "    equal neither '-Infinity' nor the '+Infinity'." << endl;
            break;
        }

      // Check if specified insertion time is not older than the most recent
      // modification time.

        BdbTime recentModificationTime = recentlyModified( );
        if( theTime < recentModificationTime ) {
            cout << errorStr << endl
                 << "    The passed time must be greater or equal than the most recent" << endl
                 << "    modification time of the metadata window." << endl
                 << "        MODIFICATION TIME:     " << recentModificationTime << endl
                 << "        PASSED INSERTION TIME: " << theTime << endl;
            break;
        }

      // Done

        result = CdbStatus::Success;

    } while( false );
    
    return result;
}

/////////////////
// End Of File //
/////////////////

---