xapian-core/backends/document.h

   1 /** @file document.h
   2  * @brief class with document data
   3  */
   4 /* Copyright 1999,2000,2001 BrightStation PLC
   5  * Copyright 2002 Ananova Ltd
   6  * Copyright 2003,2004,2005,2007,2008,2009,2010,2011 Olly Betts
   7  *
   8  * This program is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU General Public License as
  10  * published by the Free Software Foundation; either version 2 of the
  11  * License, or (at your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
  21  * USA
  22  */
  23
  24 #ifndef OM_HGUARD_DOCUMENT_H
  25 #define OM_HGUARD_DOCUMENT_H
  26
  27 #include "xapian/intrusive_ptr.h"
  28 #include <xapian/types.h>
  29 #include "api/termlist.h"
  30 #include "backends/database.h"
  31 #include "api/documentterm.h"
  32 #include <map>
  33 #include <string>
  34
  35 using namespace std;
  36
  37 class DocumentValueList;
  38 class ValueStreamDocument;
  39
  40 /// A document in the database, possibly plus modifications.
  41 class Xapian::Document::Internal : public Xapian::Internal::intrusive_base {
  42     friend class ::DocumentValueList;
  43     friend class ::ValueStreamDocument;
  44     public:
  45         /// Type to store values in.
  46         typedef map<Xapian::valueno, string> document_values;
  47
  48         /// Type to store terms in.
  49         typedef map<string, OmDocumentTerm> document_terms;
  50
  51     protected:
  52         /// The database this document is in.
  53         Xapian::Internal::intrusive_ptr<const Xapian::Database::Internal> database;
  54
  55     private:
  56         // Prevent copying
  57         Internal(const Internal &);
  58         Internal & operator=(const Internal &);
  59
  60         bool data_here;
  61         mutable bool values_here; // FIXME mutable is a hack
  62         mutable bool terms_here;
  63         mutable bool positions_modified;
  64
  65         /// The (user defined) data associated with this document.
  66         string data;
  67
  68         /// The values associated with this document.
  69         mutable document_values values; // FIXME mutable is a hack
  70
  71         /// The terms (and their frequencies and positions) in this document.
  72         mutable document_terms terms;
  73
  74     protected:
  75         /** The document ID of the document in that database.
  76          *
  77          *  If we're using multiple databases together this may not be the
  78          *  same as the docid in the combined database.
  79          */
  80         Xapian::docid did;
  81
  82     private:
  83         // Functions for backend to implement
  84         virtual string do_get_value(Xapian::valueno /*valueno*/) const { return string(); }
  85         virtual void do_get_all_values(map<Xapian::valueno, string> & values_) const {
  86             values_.clear();
  87         }
  88         virtual string do_get_data() const { return string(); }
  89
  90     public:
  91         /** Get value by value number.
  92          *
  93          *  Values are quickly accessible fields, for use during the match
  94          *  operation.  Each document may have a set of values, each of which
  95          *  having a different value number.  Duplicate values with the same
  96          *  value number are not supported in a single document.
  97          *
  98          *  Value numbers are any integer >= 0, but particular database
  99          *  backends may impose a more restrictive range than that.
 100          *
 101          *  @param slot  The value number requested.
 102          *
 103          *  @return       A string containing the specified value.  If
 104          *  the value is not present in this document, the value's value will
 105          *  be a zero length string
 106          */
 107         string get_value(Xapian::valueno slot) const;
 108
 109         /** Set all the values.
 110          *
 111          *  @param values_      The values to set - passed by non-const reference, and
 112          *                      may be modified by the call.
 113          */
 114         void set_all_values(map<Xapian::valueno, string> & values_) {
 115             // For efficiency we just swap the old and new value maps.
 116             swap(values, values_);
 117             values_here = true;
 118         }
 119
 120         Xapian::valueno values_count() const;
 121         void add_value(Xapian::valueno, const string &);
 122         void remove_value(Xapian::valueno);
 123         void clear_values();
 124         void add_posting(const string &, Xapian::termpos, Xapian::termcount);
 125         void add_term(const string &, Xapian::termcount);
 126         void remove_posting(const string &, Xapian::termpos, Xapian::termcount);
 127         void remove_term(const string &);
 128         void clear_terms();
 129         Xapian::termcount termlist_count() const;
 130
 131         /** Get data stored in document.
 132          *
 133          *  This is a general piece of data associated with a document, and
 134          *  will typically be used to store such information as text to be
 135          *  displayed in the result list, and a pointer in some form
 136          *  (eg, URL) to the full text of the document.
 137          *
 138          *  This operation can be expensive, and shouldn't normally be used
 139          *  during the match operation (such as in a match decider functor):
 140          *  use a value instead, if at all possible.
 141          *
 142          *  @return       A string containing the data for this document.
 143          */
 144         string get_data() const;
 145
 146         void set_data(const string &);
 147
 148         /** Open a term list.
 149          *
 150          *  This is a list of all the terms contained by a given document.
 151          *
 152          *  @return       A pointer to the newly created term list.
 153          *                This object must be deleted by the caller after
 154          *                use.
 155          */
 156         TermList * open_term_list() const;
 157
 158         void need_values() const;
 159         void need_terms() const;
 160
 161         /** Return true if the data in the document may have been modified.
 162          */
 163         bool data_modified() const {
 164             return data_here;
 165         }
 166
 167         /** Return true if the values in the document may have been modified.
 168          */
 169         bool values_modified() const {
 170             return values_here;
 171         }
 172
 173         /** Return true if the terms in the document may have been modified.
 174          */
 175         bool terms_modified() const {
 176             return terms_here;
 177         }
 178
 179         /// Return true if term positions may have been modified.
 180         bool term_positions_modified() const {
 181             return positions_modified;
 182         }
 183
 184         /// Return true if the document may have been modified.
 185         bool modified() const {
 186             return terms_here || values_here || data_here;
 187         }
 188
 189         /** Get the docid which is associated with this document (if any).
 190          *
 191          *  NB If multiple databases are being searched together, then this
 192          *  will be the document id in the individual database, not the merged
 193          *  database!
 194          *
 195          *  @return If this document came from a database, return the document
 196          *          id in that database.  Otherwise, return 0.
 197          */
 198         Xapian::docid get_docid() const { return did; }
 199
 200         /// Return a string describing this object.
 201         string get_description() const;
 202
 203         /** Constructor.
 204          *
 205          *  In derived classes, this will typically be a private method, and
 206          *  only be called by database objects of the corresponding type.
 207          */
 208         Internal(Xapian::Internal::intrusive_ptr<const Xapian::Database::Internal> database_,
 209                  Xapian::docid did_)
 210             : database(database_), data_here(false), values_here(false),
 211               terms_here(false), positions_modified(false), did(did_) { }
 212
 213         Internal()
 214             : database(), data_here(false), values_here(false),
 215               terms_here(false), positions_modified(false), did(0) { }
 216
 217         /** Destructor.
 218          *
 219          *  Note that the database object which created this document must
 220          *  still exist at the time this is called.
 221          */
 222         virtual ~Internal();
 223 };
 224
 225 #endif  // OM_HGUARD_DOCUMENT_H