remote.h

Go to the documentation of this file.

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

#ifndef XPACE_REMOTE_H
#define XPACE_REMOTE_H

#include <vector>

#include "base/types.h"

namespace Xpace
{
  namespace Remote
  {
    /// String does NOT own its buffer
    struct XPACE_EXPORT String
    {
      /// @param len the number of chars in the buffer
      /// @param b the buffer
      String
        (size_t len = 0,
         uint16* b = 0) :
          bufferLength(len),
          buffer(b)
      {
      }

      /// @param s a 0-terminated string
      String
        (uint16* s) :
          bufferLength(str16len(s)),
          buffer(s)
      {
      }
    
      const size_t bufferLength;
      uint16 *const buffer;

      static
      size_t str16len
        (uint16* s)
      {
        size_t ret(0);
        while (*s++)
          ++ret;
        return ret;
      }
    };

    /// Does NOT own its buffer
    struct XPACE_EXPORT intArray
    {
      /// @param s the number of char in the buffer
      /// @param b the buffer
      intArray
        (size_t len,
         int64 *const b) :
          bufferLength(len),
          buffer(b)
      {
      }
         
      const size_t bufferLength;
      int64 *const buffer;
    };

    /// ============================= REFERENCE LIST ==========

    // A reference list - a search result
    class XPACE_EXPORT RefList
    {
    public:
      void destroy
        ();

      /// @return true iff the list is empty
      virtual bool operator!
        ()
        const
      = 0;

      /// @return number of refs in the list
      virtual uint64 getCount
        ()
        const
      = 0;

      /// return numbers of siblings at levels in the list
      /// N.B could be quite slow
      /// @param atLevel if (atLevel[n] != 0), count siblings at level n
      /// @retval atLevel fill in the number of siblings at level n
      /// @return number of distinct siblings in the list
      virtual void getSiblingCount
        (intArray* atLevel)
      = 0;

      /// get a range of references
      /// @retval ret array of references
      /// @param start start of range
      /// @param size number of values (e.g., document num, paragraph, sentence) to return for each ref
      /// @return number of references (not values) in retval
      virtual size_t getRefs    
        (intArray* ret,
         uint64 start,
         uint size = 1)
      = 0;

      /// this list AND another list
      /// @param rhs the other list
      virtual void opAnd
        (RefList* rhs)
      = 0;

      /// this list OR another list
      /// @param rhs the other list
      virtual void opOr
        (RefList* rhs)
      = 0;

      /// invert this list
      virtual void opNot
        ()
      = 0;

      /// does the list contain this ref?
      /// N.B. Could be quite slow
      /// @param ref the reference, e.g. [56789, 2, 1]
      /// @return true iff list contains the ref
      virtual bool hasRef
        (const intArray& ref)
      = 0;

    protected:
      RefList
        ()
      {
      }

      virtual ~RefList
        ()
      {
      }

    private:
      RefList
        (const RefList&);
      RefList& operator=
        (const RefList&);
    };

    // ============================== INDEX ===================

    /// An index
    class XPACE_EXPORT Index
    {
    public:
      /// destroy an index
      /// @param the index to destroy
      void destroy
        ();

      /// @return true iff this index is empty
      virtual bool operator!
        ()
        const
      = 0;

      /// @retval this index's configuration
      virtual void getConfig
        (String*)
        const
      = 0;

      /// @return the number of terms in this index
      virtual uint64 getTermCount
        ()
        const
      = 0;

      /// get a range of terms in the index
      /// @retval the range of terms, e.g., "<term val="AK" count="4321"/><term val="AL" count="5432">"
      /// @param start start of range
      /// @count number of terms to get
      /// @return number of terms gotten
      virtual size_t getTerms   
        (String*,
         uint64 start,
         size_t count)
        const
      = 0;

      /// do a search
      /// @param query 
      /// @throw XML_Error
      /// @return a pointer to the search result
      virtual RefList* search
        (const String& query)
        const
      = 0;

    protected:
      Index
        ()
      {
      }

      virtual ~Index
        ()
      {
      }

    private:
      Index
        (const Index&);
      Index& operator=
        (const Index&);
    };
    
    // ============================== INDEX_LIST ==============

    /// A list of indexes
    class XPACE_EXPORT IndexList
    {
    public:
      /// Create an index list
      /// @param config - must have a "index_list" tag
      static
      IndexList* create
        (const String& config);  

      /// Destroy an index list
      /// @param the list to destroy
      void destroy
        ();

      /// @return the number of indexes in the list
      virtual size_t getCount
        ()
        const
      = 0;

      /// open an index by number
      /// @param indexNum the index to get
      /// @param config - use this config where possible
      /// @return a pointer to the Index; 0 if there is no index
      virtual Index* openIndex
        (uint indexNum,
         const String& config = String())
      = 0;

      /// open an index by name
      /// @retval indexNum fillin the index's number
      /// @param name the index to get
      /// @param config - use this config where possible
      /// @return a pointer to the Index; 0 if there is no index
      virtual Index* openIndex
        (uint* indexNum,
         const String& name,
         const String& config = String())
      = 0;

      /// do a search
      /// @param query; includes index names TODO - define syntax
      /// @return a pointer to the search result
      virtual RefList* search   
        (const String& query)
      = 0;     

    protected:
      IndexList
        ()
      {
      }

      virtual ~IndexList
        ()
      {
      }

    private:
      IndexList
        (const IndexList&);
      IndexList& operator=
        (const IndexList&);
    };

    // ============================== DATA STORE ==============

    /// A data store
    class XPACE_EXPORT Store
    {
    public:
      /// @param config - must have a "store" tag
      static
      Store* create 
        (const String& config);      

      void destroy
        ();

      /// get the Store's Class Tree
      /// @retval an XML representation of the Class Tree
      /// @param siblingPos list of sibling numbers: start here
      /// @retval siblingPos fillin with next
      /// @param showMore leave stubs for unreturned subtrees
      /// @param maxNodes no more nodes than this
      /// @param maxDepth no deeper than this
      /// @return true iff tree continues
      virtual bool getClassTree
        (String*,
         intArray* siblingPos,      
         bool showMore = true,
         uint maxNodes = 0, 
         uint maxDepth = 0)
       = 0;  

      /// convert an XML stub to a sibling pos and a byte pos
      /// @retval siblingPos the siblings
      /// @param the XML stub
      /// @return true iff the stub was valid
      static bool convertStub
        (intArray* siblingPos,
         const String& stub);

      virtual ~Store
        ()
      {
      }

    protected:
      Store
        ()
      {
      }

    private:
      Store
        (const Store&);
      Store& operator=
        (const Store&);
    };

    // ============================== CONTENT =================

    /// Data from a Store, possibly filtered with a RefList
    class XPACE_EXPORT Content
    {
    public:
      /// @param store content comes from here
      /// @param refList get only content from these refs
      static
      Content* create
        (const Store* store,
         const RefList* refList = 0);

      void destroy
        ();

      /// get a range of content
      /// @retval something like “<count>2<><Symbol>DWTI<><Date>20000505<><end>0,2<>\0”  
      /// @param siblingPos list of sibling numbers: start here, go no deeper than siblingPos.bufferSize
      /// @retval siblingPos list of sibling numbers: fillin with next
      /// @param charPos start here (within a node)
      /// @retval charPos fillin next (within a node)
      /// @param fullNodes don't break a node due to size.bufferSize (if possible)
      /// @param showMore leave stubs for unreturned subtrees
      /// @param maxNodes retrieve no more than this many nodes
      /// @return the number of chars filled in
      virtual size_t get
        (String* ret,
         intArray* siblingPos,
         size_t* bytePos,
         bool fullNodes = true,
         bool showMore = true,
         uint maxNodes = 0)
       = 0;

      /// convert an XML stub to a sibling pos and a byte pos
      /// @retval siblingPos the siblings
      /// @retval bytePos the bytes
      /// @param the XML stub
      /// @return true iff the stub was valid
      static bool convertStub
        (intArray* siblingPos,
         size_t* bytePos,
         const String& stub);

    protected:
      Content
        ()
      {
      }

      virtual ~Content
        ()
      {
      }
 
    private:
      Content
        (const Content&);
      Content& operator=
        (const Content&);
    };

  #if (defined TESTING || !defined NDEBUG) && !defined DOCUMENTATION
  void XPACE_EXPORT testRemoteIndexes
    (const String& config,
     uint checks);

  void XPACE_EXPORT testRemoteStore
    (const String& config);
  #endif

  } // namespace Remote
} // namespace Xpace

#endif