---

CdbBdbObjectVisitorUserAction.hh

Go to the documentation of this file.

#ifndef CDBBDB_OBJECT_VISITOR_USER_ACTION_HH
#define CDBBDB_OBJECT_VISITOR_USER_ACTION_HH

// File and Version Information:
//      $Id: CdbBdbObjectVisitorUserAction.hh,v 1.3 2004/10/21 20:35:51 gapon Exp $

#include "CdbBase/CdbCommon.hh"

#include <oo.h>     // ooRef(ooObj), ooHandle(ooObj)

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

class CdbBdbObjectVisitorContext;

/// The base class for user defined actions
/**
  * This base class has to implemented by users willing to control
  * the "visitor" navigation in complex graphs.
  * 
  * IMPLEMENTATION NOTES:
  *
  *   (1) This class violates CDB API convention on the inclusion
  *       of "CdbBase/CdbCommon.hh" header file to avoid STD namespace
  *       conflicts of the kind described above.
  */
class CdbBdbObjectVisitorUserAction {

public:

  /// These values will be used to indicate the user's response

    typedef enum { ACTION_PROCEED,
                   ACTION_STOP,
                   ACTION_ERROR } ActionType;

  /// Total number of databases in a federation
  /**
    * This value defined the limits [0..MAX_DATABASE] for certain
    * operations involving database iderntifiers.
    */
    enum { MAX_DATABASE = 0xFFFF };

public:

  /// The constructor
  /**
    * An optional file with a list of "known" patterns to be ignored/suppressed
    * may be passed to the constructor. The file (if present) would be analysed
    * and loaded into intyernal data structures. If something wrong happends during
    * the file's translation then a run time assertion would happen.
    *
    * It's also possible to specify a list of DBID-s to be avoided. These databases
    * (if any) would not be checked for validity.
    */
    CdbBdbObjectVisitorUserAction(                const char* theSupressFile = 0,
                                   const std::list<d_UShort>* theDatabasesToIgnore = 0,
                                             bool verboseMode = false,
                                               bool debugMode = false );

  /// The destructor
  /**
    * Moe details...
    */
    virtual ~CdbBdbObjectVisitorUserAction( );

  /// Let a user to make a decision on what has to be done next
  /**
    * This wrapper method takes the "about-to-be-visited" link on the input. Ths link
    * is evaluated by the method to report what's the next action should be.
    *
    * The second parameter passed town to the operation is the current context
    * description in which the link has to be evaluated.
    *
    * Here is the explanation of possible responses:
    *
    *   ACTION_PROCEED : a caller has to proceed and visit this node.
    *
    *   ACTION_STOP    : a caller should stop and not to propagate along this link.
    *
    *   ACTION_ERROR   : an error has happened inside the method. Normally the caller
    *                    should stop visiting any further links.
    *
    * HOW IT WORKS:
    *
    *   - first of all this method will verify if the passed object is valid and take
    *     the following actions if it's not:
    *
    *     -- check if the object's context matches one of the known patterns (if any).
    *        and if not then print diagnostic message (in verbose/debug modes)
    *        and update internal statistics for missing/corrupted databases.
    *        The action returned in this case would be ACTION_ERROR.
    *
    *     -- otherwise the internal statistics would not be updated (although
    *        an informational message in verbose mode saying that the problem
    *        of the missing objects has been ignored due to known pattern would be
    *        still printed.) and the method would return ACTION_STOP.
    *
    *   - in the end if the passed object is valid then a user defined "userAction"
    *     application's object will be called to let a user to proceed with his/her
    *     decision in a specific context.
    *
    * @see CdbBdbObjectVisitorUserAction::userAction()
    * @see class CdbBdbObjectVisitorContext
    */
    ActionType action(            const ooHandle(ooObj)& theInputH,
                       const CdbBdbObjectVisitorContext* theContext );


  /// Print the internal counters and table onto the Standard Output
  /**
    * This method will print all statistics information accumulated by
    * the current user object onto the Standard Output. This includes a list
    * of missing databases and their clients.
    *
    * This method can be overriden by a subclass to add up extra information
    * accumulated by the subclass.
    */
    virtual void print_statistics( ) const;

  /// Get the total number of objects visited

    unsigned long totalObjects( ) const { return _totalObjects; }

  /// Get the number of invalid objects found

    unsigned long invalidObjects( ) const { return _invalidObjects; }


  /// Get the number of times the specified database was found missing
  /**
    * The number returned by this method would be either 0 or a positive number.
    * Returning 0 does not mean that specified databases exsists, it just means
    * that the databases has not been found missing (noone attempted to use it).
    *
    * The database identifier must be a in the valid range [0..64k]. Otherwise
    * a run time assertion would occure.
    */
    unsigned int missedCounters( d_UShort theDatabaseId ) const;

  /// Get clients of specified missing database
  /**
    * The result of this procedure would be either a 0 pointer or a const pointer
    * onto a map with DBID-s and system names of clients. The map object itself
    * would be located at a a user action object.
    *
    * WARNING: This method does not return the ownership of teh map object.
    *
    * The database identifier must be a in the valid range [0..64k]. Otherwise
    * a run time assertion would occure.
    */
    const std::map<d_UShort,std::string>* missedDatabaseClients( d_UShort theDatabaseId ) const;

protected:

  /// Let a user to make a decision on what has to be done next (ACTUAL USER ACTION)
  /**
    * This method gets called only for valid objects.
    *
    * IMPLEMENTATION NOTE: In its default implementation this method would always
    *                      return ACTION_PROCEED. This behaviour can be overriten
    *                      by specific subclasses.
    *
    * @see CdbBdbObjectVisitorUserAction::action()
    * @see class CdbBdbObjectVisitorContext
    */
    virtual ActionType userAction(            const ooHandle(ooObj)& theInputH,
                                   const CdbBdbObjectVisitorContext* theContext );

private:

  /// Update a list of clients (databases) reffering a missing one
  /**
    * Each client is represented as pair of <DBID> <DATBASE SYSTEM NAME>.
    *
    * The algorithm also uses an object-scope dictionary to avoid
    * multiple translations of the DBID.
    */
    bool update_missing_database_clients_list(  std::map<d_UShort,std::string>*& theClients,
                                               const CdbBdbObjectVisitorContext* theContext );

private:

  // Parameters

    bool _verboseMode;
    bool _debugMode;

    std::vector<CdbBdbObjectVisitorContext*> _patternsToIgnore;
    bool                                     _databasesToIgnore[MAX_DATABASE + 1];

  // Statisticts

    unsigned long _totalObjects;
    unsigned long _invalidObjects;

    unsigned int                    _missingDatabase         [MAX_DATABASE + 1];
    std::map<d_UShort,std::string>* _clientsOfMissingDatabase[MAX_DATABASE + 1];

  // A dictionary meant to translate DBID-s of existing databases into
  // their name.

    std::string _dbidToName[MAX_DATABASE + 1];
};

#endif  // CDBBDB_OBJECT_VISITOR_USER_ACTION_HH

---