indexlist.h

Go to the documentation of this file.

/**************************************************************
 **
 ** @file index/indexlist.h
 **
 ** Copyright (C) 2012  Xpace, LLC.  All rights reserved
 **
 ** www.xpace.net
 **
 **************************************************************/

#if !defined XPACE_INDEXLIST_H
#define XPACE_INDEXLIST_H

#include <vector>
#include <map>

#include "base/config.h"
#include "index/index.h"

namespace Xpace
{
  class indexListImpl;

  class XPACE_EXPORT IndexList : public Configurable
  {
  public :
    /// An empty index list
    IndexList
      ();

    /// open an already-existing index list,
    /// or create one with this Configuration
    /// @param config the Configuration
    /// @param overwrite if true, delete if list already exists
    /// @throw CantOpen
    explicit IndexList
      (const Configuration& config,
       bool overwrite = false);    

    /// open an already-existing index list
    /// @param iiFile the index-index file
    /// @param idFile the actual indexes
    /// &throw CantOpen
    IndexList
      (const String& iiFile,
       const String& idFile);

    /// create a new reference to a list
    /// @param rhs the list
    IndexList
      (const IndexList& rhs);
    /// make this refer to a list
    /// @param rhs the list
    IndexList& operator=
      (const IndexList& rhs);
    
    ~IndexList
      ();

    /// @return the number of indexes in the list
    uint getCount
      ()
      const;

    /// Get the Configuration of an index
    /// @param indexNum the index number
    /// @return the index's Configuration
    const Configuration& getIndexConfig
      (uint indexNum)
      const;

    /// Find indexes that include a field
    /// @param tag the field's tag
    /// @param pos which of the indexes containing the field to return
    /// @return number of the pos'th index that contains the field, ~0 for none
    size_t getIndexByField
      (const String& tag,
       size_t pos = 0)
      const;

    /// open an index by name
    /// @param indexName the index to get
    /// @retval indexNum fill in the index's number
    /// @return the found index, Index() if not found
    Index& openIndex
      (const String& indexName,
       uint* indexNum = 0,
       Configuration config = Configuration());
    const Index& openIndex
      (const String& indexName,
       uint* indexNum = 0,
       Configuration config = Configuration())
      const;

    /// open an index by number
    /// @param indexNum the number of the index to get
    /// @param config if != Configuration(), override index's Configuration with this one
    /// @return the found index, Index() if not found
    Index& openIndex
      (uint indexNum,
       Configuration config = Configuration());   
    const Index& openIndex
      (uint indexNum,
       Configuration config = Configuration())
      const;   

    /// @param index index to add
    /// @return number of added index
    uint addIndex
      (Index& index);

    #ifdef XPACE_REFLIST_H
    /// @param query a query string
    /// @param recCount for NOT searches
    /// @return a RefListCursor into the result
    RefListCursor eval
      (String query,
       uint64 recCount = 0)
      const;
    
    #ifdef QDOM_H
    /// @param query a search tree
    /// @param recCount for NOT searches
    /// @return a RefListCursor into the result
    RefListCursor eval
      (QDomNode query,
       uint64 recCount = 0)
      const;
    #endif
    #endif

    #if defined(XPACE_STORE_H) || defined(XPACE_TABLE_H) || defined DOCUMENTATION

    /// bulk build

    /// status callback 
    struct BuildStatus
    {
      BuildStatus
        () :
        maxMemory(~0),
        memUsed(0)
      {
      }

      virtual ~BuildStatus() 
      { 
      }

      /// @param how many refs indexed
      /// @param term how many terms indexed
      /// @param unique how many unique terms indexed
      /// @return term interval to continue, 0 to stop
      virtual uint operator()
        (uint64 ref,
         uint64 term,
         uint64 unique,
         size_t pageListBytes,
         size_t totalPageBytes,
         size_t sortBytes,
         size_t termPoolBytes)
      = 0;
      size_t maxMemory;   ///< fillin - use no more than this much memory
      size_t memUsed;     ///< how much memory is actually being used by this build
    };
    #endif

    #if defined(XPACE_TABLE_H)
    /// @param table build from this Table
    /// @param bst build status callback
    /// @param wst write status callback (for temp files)
    /// @return true if completed, false if stopped by callback
    bool build
      (Table* table,
       BuildStatus* bst = 0,
       Index::WriteStatus* wst = 0);
    #endif

    /// write in current state
    /// @param wst write status callback
    /// @return true if successful and complete, false if failed or stopped by callback
    bool write
      (Index::WriteStatus* st = 0);

    /// speed up range search for indexes in a list
    /// @param config specifies from/to files, indexes to be oprimized
    /// @return true if successful, false if failed of stopped by callback
    bool range
      (const Configuration& config,
       Index::WriteStatus* st = 0);

    /// merge a list of index lists
    /// @param config merge to a new index list with this configuration
    /// @param list list of lindx lists to merge
    /// @return true if successful and complete, false if failed or stopped by callback
    static
    bool merge
      (const Configuration& config,
       const std::vector<IndexList*>& list,
       Index::WriteStatus* st = 0);

    class CantOpen : public Exception
    {
    public :
      CantOpen
        (const Configuration& conf,
         const Exception& why = Exception()) :
          Exception("Can't open index list from configuration \"%1\".", why)
      {
        addParam(conf.toString());
      }; 
    };

    class CantOpenIndex : public Exception
    {
    public :
      CantOpenIndex
        (const String& name) :
          Exception("Can't open index \"%1\".")
      {
        addParam(name);
      }; 

      CantOpenIndex
        (size_t indexNum,
         const Exception& why = Exception()) :
          Exception("Can't open index# \"%1\".", why)          
      {
        addParam(String::setNum(indexNum));
      }
    };

    DECLARE_CONFIG

    static const char* TAG;
  private :
    static const char* II_TAG;
    static const char* ID_TAG;

    friend class indexListImpl;
    indexListImpl* impl;
  };

  #if (defined TESTING || !defined NDEBUG) && !defined DOCUMENTATION
  //void XPACE_EXPORT testIndexes
  //  (File* configFile,
  //   uint checks);
  #endif

} // namespace

#endif