LCOV - code coverage report
Current view: top level - backends - databaseinternal.h (source / functions) Hit Total Coverage
Test: Test Coverage for xapian-core 954b5873a738 Lines: 10 10 100.0 %
Date: 2019-06-30 05:20:33 Functions: 5 5 100.0 %
Branches: 3 4 75.0 %

           Branch data     Line data    Source code
       1                 :            : /** @file databaseinternal.h
       2                 :            :  * @brief Virtual base class for Database internals
       3                 :            :  */
       4                 :            : /* Copyright 2004,2006,2007,2008,2009,2011,2014,2015,2016,2017 Olly Betts
       5                 :            :  * Copyright 2007,2008 Lemur Consulting Ltd
       6                 :            :  *
       7                 :            :  * This program is free software; you can redistribute it and/or
       8                 :            :  * modify it under the terms of the GNU General Public License as
       9                 :            :  * published by the Free Software Foundation; either version 2 of the
      10                 :            :  * License, or (at your option) any later version.
      11                 :            :  *
      12                 :            :  * This program is distributed in the hope that it will be useful,
      13                 :            :  * but WITHOUT ANY WARRANTY; without even the implied warranty of
      14                 :            :  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
      15                 :            :  * GNU General Public License for more details.
      16                 :            :  *
      17                 :            :  * You should have received a copy of the GNU General Public License
      18                 :            :  * along with this program; if not, write to the Free Software
      19                 :            :  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
      20                 :            :  */
      21                 :            : 
      22                 :            : #ifndef XAPIAN_INCLUDED_DATABASEINTERNAL_H
      23                 :            : #define XAPIAN_INCLUDED_DATABASEINTERNAL_H
      24                 :            : 
      25                 :            : #include "internaltypes.h"
      26                 :            : 
      27                 :            : #include <xapian/database.h>
      28                 :            : #include <xapian/document.h>
      29                 :            : #include <xapian/intrusive_ptr.h>
      30                 :            : #include <xapian/positioniterator.h>
      31                 :            : #include <xapian/postingiterator.h>
      32                 :            : #include <xapian/termiterator.h>
      33                 :            : #include <xapian/types.h>
      34                 :            : #include <xapian/valueiterator.h>
      35                 :            : 
      36                 :            : #include <string>
      37                 :            : 
      38                 :            : typedef Xapian::TermIterator::Internal TermList;
      39                 :            : typedef Xapian::PositionIterator::Internal PositionList;
      40                 :            : typedef Xapian::ValueIterator::Internal ValueList;
      41                 :            : 
      42                 :            : class LeafPostList;
      43                 :            : 
      44                 :            : namespace Xapian {
      45                 :            : namespace Internal {
      46                 :            : class PostList;
      47                 :            : }
      48                 :            : }
      49                 :            : using Xapian::Internal::PostList;
      50                 :            : 
      51                 :            : namespace Xapian {
      52                 :            : 
      53                 :            : class Query;
      54                 :            : struct ReplicationInfo;
      55                 :            : 
      56                 :            : /// Virtual base class for Database internals
      57                 :            : class Database::Internal : public Xapian::Internal::intrusive_base {
      58                 :            :     friend class Database;
      59                 :            : 
      60                 :            :     /// Don't allow assignment.
      61                 :            :     Internal& operator=(const Internal&) = delete;
      62                 :            : 
      63                 :            :     /// Don't allow copying.
      64                 :            :     Internal(const Internal&) = delete;
      65                 :            : 
      66                 :            :     /// The "action required" helper for the dtor_called() helper.
      67                 :            :     void dtor_called_();
      68                 :            : 
      69                 :            :   protected:
      70                 :            :     /// Transaction state enum.
      71                 :            :     enum transaction_state {
      72                 :            :         TRANSACTION_READONLY = -2, // Not a writable database shard.
      73                 :            :         TRANSACTION_UNIMPLEMENTED = -1, // Used by InMemory.
      74                 :            :         TRANSACTION_NONE = 0,
      75                 :            :         TRANSACTION_UNFLUSHED = 1,
      76                 :            :         TRANSACTION_FLUSHED = 2
      77                 :            :     };
      78                 :            : 
      79                 :            :     /** Only constructable as a base class for derived classes.
      80                 :            :      *
      81                 :            :      *  @param transaction_support  One of:
      82                 :            :      *  * TRANSACTION_READONLY - read-only shard
      83                 :            :      *  * TRANSACTION_UNIMPLEMENTED - writable but no transaction support
      84                 :            :      *  * TRANSACTION_NONE - writable with transaction support
      85                 :            :      */
      86                 :     212789 :     Internal(transaction_state transaction_support)
      87                 :     212789 :         : state(transaction_support) {}
      88                 :            : 
      89                 :            :     /// Current transaction state.
      90                 :            :     transaction_state state;
      91                 :            : 
      92                 :            :     /// Test if this shard is read-only.
      93                 :       1009 :     bool is_read_only() const {
      94                 :       1009 :         return state == TRANSACTION_READONLY;
      95                 :            :     }
      96                 :            : 
      97                 :            :     /// Test if a transaction is currently active.
      98                 :      31436 :     bool transaction_active() const { return state > 0; }
      99                 :            : 
     100                 :            :     /** Helper to process uncommitted changes when a writable db is destroyed.
     101                 :            :      *
     102                 :            :      *  The destructor of a derived writable database class needs to call this
     103                 :            :      *  method - we can't call it from our own destructor because we need to
     104                 :            :      *  be able to call methods in the derived class, but that's no longer
     105                 :            :      *  valid by the time our destructor runs, as that happens after the
     106                 :            :      *  destructor of the derived class has run.
     107                 :            :      *
     108                 :            :      *  If a transaction is active, it is cancelled.  Otherwise we attempt to
     109                 :            :      *  commit uncommitted changes, but because it is not safe to throw
     110                 :            :      *  exceptions from destructors, this method will catch and discard any
     111                 :            :      *  exceptions.
     112                 :            :      */
     113                 :       2708 :     void dtor_called() {
     114                 :            :         // Inline the check to exclude no-op cases (read-only and unimplemented).
     115         [ +  + ]:       2708 :         if (state >= 0)
     116                 :       1724 :             dtor_called_();
     117                 :       2708 :     }
     118                 :            : 
     119                 :            :   public:
     120                 :            :     /** We have virtual methods and want to be able to delete derived classes
     121                 :            :      *  using a pointer to the base class, so we need a virtual destructor.
     122                 :            :      */
     123         [ -  + ]:     425578 :     virtual ~Internal() {}
     124                 :            : 
     125                 :            :     typedef size_t size_type;
     126                 :            : 
     127                 :            :     virtual size_type size() const;
     128                 :            : 
     129                 :            :     virtual void keep_alive();
     130                 :            : 
     131                 :            :     virtual void readahead_for_query(const Query& query) const;
     132                 :            : 
     133                 :            :     virtual doccount get_doccount() const = 0;
     134                 :            : 
     135                 :            :     /** Return the last used document id of this (sub) database. */
     136                 :            :     virtual docid get_lastdocid() const = 0;
     137                 :            : 
     138                 :            :     /** Return the total length of all documents in this database. */
     139                 :            :     virtual totallength get_total_length() const = 0;
     140                 :            : 
     141                 :            :     virtual termcount get_doclength(docid did) const = 0;
     142                 :            : 
     143                 :            :     /** Get the number of unique terms in document.
     144                 :            :      *
     145                 :            :      *  @param did  The document id of the document to return this value for.
     146                 :            :      */
     147                 :            :     virtual termcount get_unique_terms(docid did) const = 0;
     148                 :            : 
     149                 :            :     /** Returns frequencies for a term.
     150                 :            :      *
     151                 :            :      *  @param term             The term to get frequencies for
     152                 :            :      *  @param termfreq_ptr     Point to return number of docs indexed by @a
     153                 :            :      *                          term (or NULL not to return)
     154                 :            :      *  @param collfreq_ptr     Point to return number of occurrences of @a
     155                 :            :      *                          term in the database (or NULL not to return)
     156                 :            :      */
     157                 :            :     virtual void get_freqs(const std::string& term,
     158                 :            :                            doccount* termfreq_ptr,
     159                 :            :                            termcount* collfreq_ptr) const = 0;
     160                 :            : 
     161                 :            :     /** Return the frequency of a given value slot.
     162                 :            :      *
     163                 :            :      *  This is the number of documents which have a (non-empty) value
     164                 :            :      *  stored in the slot.
     165                 :            :      *
     166                 :            :      *  @param slot The value slot to examine.
     167                 :            :      */
     168                 :            :     virtual doccount get_value_freq(valueno slot) const = 0;
     169                 :            : 
     170                 :            :     /** Get a lower bound on the values stored in the given value slot.
     171                 :            :      *
     172                 :            :      *  If the lower bound isn't available for the given database type,
     173                 :            :      *  this will return the lowest possible bound - the empty string.
     174                 :            :      *
     175                 :            :      *  @param slot The value slot to examine.
     176                 :            :      */
     177                 :            :     virtual std::string get_value_lower_bound(valueno slot) const = 0;
     178                 :            : 
     179                 :            :     /** Get an upper bound on the values stored in the given value slot.
     180                 :            :      *
     181                 :            :      *  @param slot The value slot to examine.
     182                 :            :      */
     183                 :            :     virtual std::string get_value_upper_bound(valueno slot) const = 0;
     184                 :            : 
     185                 :            :     /// Get a lower bound on the length of a document in this DB.
     186                 :            :     virtual termcount get_doclength_lower_bound() const = 0;
     187                 :            : 
     188                 :            :     /// Get an upper bound on the length of a document in this DB.
     189                 :            :     virtual termcount get_doclength_upper_bound() const = 0;
     190                 :            : 
     191                 :            :     /// Get an upper bound on the wdf of term @a term.
     192                 :            :     virtual termcount get_wdf_upper_bound(const std::string& term) const = 0;
     193                 :            : 
     194                 :            :     /// Get a lower bound on the unique terms size of a document in this DB.
     195                 :            :     virtual termcount get_unique_terms_lower_bound() const;
     196                 :            : 
     197                 :            :     /// Get an upper bound on the unique terms size of a document in this DB.
     198                 :            :     virtual termcount get_unique_terms_upper_bound() const;
     199                 :            : 
     200                 :            :     virtual bool term_exists(const std::string& term) const = 0;
     201                 :            : 
     202                 :            :     /** Check whether this database contains any positional information. */
     203                 :            :     virtual bool has_positions() const = 0;
     204                 :            : 
     205                 :            :     /** Return a PostList suitable for use in a PostingIterator. */
     206                 :            :     virtual PostList* open_post_list(const std::string& term) const = 0;
     207                 :            : 
     208                 :            :     /** Create a LeafPostList for use during a match.
     209                 :            :      *
     210                 :            :      *  @param term             The term to open a postlist for, or the empty
     211                 :            :      *                          string to create an all-docs postlist.
     212                 :            :      *
     213                 :            :      *  @param need_read_pos    Does the postlist need to support
     214                 :            :      *                          read_position_list()?  Note that
     215                 :            :      *                          open_position_list() may still be called even
     216                 :            :      *                          if need_read_pos is false.
     217                 :            :      */
     218                 :            :     virtual LeafPostList* open_leaf_post_list(const std::string& term,
     219                 :            :                                               bool need_read_pos) const = 0;
     220                 :            : 
     221                 :            :     /** Open a value stream.
     222                 :            :      *
     223                 :            :      *  This returns the value in a particular slot for each document.
     224                 :            :      *
     225                 :            :      *  @param slot     The value slot.
     226                 :            :      *
     227                 :            :      *  @return Pointer to a new ValueList object which should be deleted by
     228                 :            :      *          the caller once it is no longer needed.
     229                 :            :      */
     230                 :            :     virtual ValueList* open_value_list(valueno slot) const;
     231                 :            : 
     232                 :            :     virtual TermList* open_term_list(docid did) const = 0;
     233                 :            : 
     234                 :            :     /** Like open_term_list() but without MultiTermList wrapper.
     235                 :            :      *
     236                 :            :      *  MultiDatabase::open_term_list() wraps the returns TermList in a
     237                 :            :      *  MultiTermList, but we don't want that for query expansion.
     238                 :            :      */
     239                 :            :     virtual TermList* open_term_list_direct(docid did) const = 0;
     240                 :            : 
     241                 :            :     virtual TermList* open_allterms(const std::string& prefix) const = 0;
     242                 :            : 
     243                 :            :     virtual PositionList* open_position_list(docid did,
     244                 :            :                                              const std::string& term) const = 0;
     245                 :            : 
     246                 :            :     /** Open a handle on a document.
     247                 :            :      *
     248                 :            :      *  The returned handle provides access to document data and document
     249                 :            :      *  values.
     250                 :            :      *
     251                 :            :      *  @param did      The document id to open.
     252                 :            :      *
     253                 :            :      *  @param lazy     If true, there's no need to check that this document
     254                 :            :      *                  actually exists (only a hint - the backend may still
     255                 :            :      *                  check).  Used to avoid unnecessary work when we already
     256                 :            :      *                  know that the requested document exists.
     257                 :            :      *
     258                 :            :      *  @return         A new document object, owned by the caller.
     259                 :            :      */
     260                 :            :     virtual Document::Internal* open_document(docid did, bool lazy) const = 0;
     261                 :            : 
     262                 :            :     /** Create a termlist tree from trigrams of @a word.
     263                 :            :      *
     264                 :            :      *  You can assume word.size() > 1.
     265                 :            :      *
     266                 :            :      *  If there are no trigrams, returns NULL.
     267                 :            :      */
     268                 :            :     virtual TermList* open_spelling_termlist(const std::string& word) const;
     269                 :            : 
     270                 :            :     /** Return a termlist which returns the words which are spelling
     271                 :            :      *  correction targets.
     272                 :            :      *
     273                 :            :      *  If there are no spelling correction targets, returns NULL.
     274                 :            :      */
     275                 :            :     virtual TermList* open_spelling_wordlist() const;
     276                 :            : 
     277                 :            :     /** Return the number of times @a word was added as a spelling. */
     278                 :            :     virtual doccount get_spelling_frequency(const std::string& word) const;
     279                 :            : 
     280                 :            :     /** Add a word to the spelling dictionary.
     281                 :            :      *
     282                 :            :      *  If the word is already present, its frequency is increased.
     283                 :            :      *
     284                 :            :      *  @param word     The word to add.
     285                 :            :      *  @param freqinc  How much to increase its frequency by.
     286                 :            :      */
     287                 :            :     virtual void add_spelling(const std::string& word,
     288                 :            :                               termcount freqinc) const;
     289                 :            : 
     290                 :            :     /** Remove a word from the spelling dictionary.
     291                 :            :      *
     292                 :            :      *  The word's frequency is decreased, and if would become zero or less
     293                 :            :      *  then the word is removed completely.
     294                 :            :      *
     295                 :            :      *  @param word     The word to remove.
     296                 :            :      *  @param freqdec  How much to decrease its frequency by.
     297                 :            :      *
     298                 :            :      *  @return Any freqdec not "used up".
     299                 :            :      */
     300                 :            :     virtual termcount remove_spelling(const std::string& word,
     301                 :            :                                       termcount freqdec) const;
     302                 :            : 
     303                 :            :     /** Open a termlist returning synonyms for a term.
     304                 :            :      *
     305                 :            :      *  If @a term has no synonyms, returns NULL.
     306                 :            :      */
     307                 :            :     virtual TermList* open_synonym_termlist(const std::string& term) const;
     308                 :            : 
     309                 :            :     /** Open a termlist returning each term which has synonyms.
     310                 :            :      *
     311                 :            :      *  @param prefix   If non-empty, only terms with this prefix are
     312                 :            :      *              returned.
     313                 :            :      */
     314                 :            :     virtual TermList* open_synonym_keylist(const std::string& prefix) const;
     315                 :            : 
     316                 :            :     /** Add a synonym for a term.
     317                 :            :      *
     318                 :            :      *  If @a synonym is already a synonym for @a term, then no action is
     319                 :            :      *  taken.
     320                 :            :      */
     321                 :            :     virtual void add_synonym(const std::string& term,
     322                 :            :                              const std::string& synonym) const;
     323                 :            : 
     324                 :            :     /** Remove a synonym for a term.
     325                 :            :      *
     326                 :            :      *  If @a synonym isn't a synonym for @a term, then no action is taken.
     327                 :            :      */
     328                 :            :     virtual void remove_synonym(const std::string& term,
     329                 :            :                                 const std::string& synonym) const;
     330                 :            : 
     331                 :            :     /** Clear all synonyms for a term.
     332                 :            :      *
     333                 :            :      *  If @a term has no synonyms, no action is taken.
     334                 :            :      */
     335                 :            :     virtual void clear_synonyms(const std::string& term) const;
     336                 :            : 
     337                 :            :     /** Get the metadata associated with a given key.
     338                 :            :      *
     339                 :            :      *  See Database::get_metadata() for more information.
     340                 :            :      */
     341                 :            :     virtual std::string get_metadata(const std::string& key) const;
     342                 :            : 
     343                 :            :     /** Open a termlist returning each metadata key.
     344                 :            :      *
     345                 :            :      *  Only metadata keys which are associated with a non-empty value will
     346                 :            :      *  be returned.
     347                 :            :      *
     348                 :            :      *  @param prefix   If non-empty, only keys with this prefix are returned.
     349                 :            :      */
     350                 :            :     virtual TermList* open_metadata_keylist(const std::string& prefix) const;
     351                 :            : 
     352                 :            :     /** Set the metadata associated with a given key.
     353                 :            :      *
     354                 :            :      *  See WritableDatabase::set_metadata() for more information.
     355                 :            :      */
     356                 :            :     virtual void set_metadata(const std::string& key, const std::string& value);
     357                 :            : 
     358                 :            :     /** Reopen the database to the latest available revision.
     359                 :            :      *
     360                 :            :      *  Database backends which don't support simultaneous update and
     361                 :            :      *  reading probably don't need to do anything here.
     362                 :            :      */
     363                 :            :     virtual bool reopen();
     364                 :            : 
     365                 :            :     /** Close the database */
     366                 :            :     virtual void close() = 0;
     367                 :            : 
     368                 :            :     /** Commit pending modifications to the database. */
     369                 :            :     virtual void commit();
     370                 :            : 
     371                 :            :     /** Cancel pending modifications to the database. */
     372                 :            :     virtual void cancel();
     373                 :            : 
     374                 :            :     /** Begin transaction. */
     375                 :            :     virtual void begin_transaction(bool flushed);
     376                 :            : 
     377                 :            :     /** End transaction.
     378                 :            :      *
     379                 :            :      *  @param do_commit        If true, commits the transaction; if false,
     380                 :            :      *                          cancels the transaction.
     381                 :            :      */
     382                 :            :     virtual void end_transaction(bool do_commit);
     383                 :            : 
     384                 :            :     virtual docid add_document(const Document& document);
     385                 :            : 
     386                 :            :     virtual void delete_document(docid did);
     387                 :            : 
     388                 :            :     /** Delete any documents indexed by a term from the database. */
     389                 :            :     virtual void delete_document(const std::string& unique_term);
     390                 :            : 
     391                 :            :     virtual void replace_document(docid did,
     392                 :            :                                   const Document& document);
     393                 :            : 
     394                 :            :     /** Replace any documents matching a term. */
     395                 :            :     virtual docid replace_document(const std::string& unique_term,
     396                 :            :                                    const Document& document);
     397                 :            : 
     398                 :            :     /** Request a document.
     399                 :            :      *
     400                 :            :      *  This tells the database that we're going to want a particular
     401                 :            :      *  document soon.  It's just a hint which the backend may ignore,
     402                 :            :      *  but for glass it issues a preread hint on the file with the
     403                 :            :      *  document data in, and for the remote backend it might cause
     404                 :            :      *  the document to be fetched asynchronously (this isn't currently
     405                 :            :      *  implemented though).
     406                 :            :      *
     407                 :            :      *  It can be called for multiple documents in turn, and a common usage
     408                 :            :      *  pattern would be to iterate over an MSet and request the documents,
     409                 :            :      *  then iterate over it again to actually get and display them.
     410                 :            :      *
     411                 :            :      *  The default implementation is a no-op.
     412                 :            :      */
     413                 :            :     virtual void request_document(docid did) const;
     414                 :            : 
     415                 :            :     /** Write a set of changesets to a file descriptor.
     416                 :            :      *
     417                 :            :      *  This call may reopen the database, leaving it pointing to a more
     418                 :            :      *  recent version of the database.
     419                 :            :      */
     420                 :            :     virtual void write_changesets_to_fd(int fd,
     421                 :            :                                         const std::string& start_revision,
     422                 :            :                                         bool need_whole_db,
     423                 :            :                                         ReplicationInfo* info);
     424                 :            : 
     425                 :            :     /// Get revision number of database (if meaningful).
     426                 :            :     virtual Xapian::rev get_revision() const;
     427                 :            : 
     428                 :            :     /** Get a UUID for the database.
     429                 :            :      *
     430                 :            :      *  The UUID will persist for the lifetime of the database.
     431                 :            :      *
     432                 :            :      *  Replicas (eg, made with the replication protocol, or by copying all
     433                 :            :      *  the database files) will have the same UUID.  However, copies (made
     434                 :            :      *  with copydatabase, or xapian-compact) will have different UUIDs.
     435                 :            :      *
     436                 :            :      *  If the backend does not support UUIDs the empty string is returned.
     437                 :            :      */
     438                 :            :     virtual std::string get_uuid() const;
     439                 :            : 
     440                 :            :     /** Notify the database that document is no longer valid.
     441                 :            :      *
     442                 :            :      *  This is used to invalidate references to a document kept by a
     443                 :            :      *  database for doing lazy updates.  If we moved to using a weak_ptr
     444                 :            :      *  instead we wouldn't need a special method for this, but it would
     445                 :            :      *  involve a fair bit of reorganising of other parts of the code.
     446                 :            :      */
     447                 :            :     virtual void invalidate_doc_object(Document::Internal* obj) const;
     448                 :            : 
     449                 :            :     /** Get backend information about this database.
     450                 :            :      *
     451                 :            :      *  @param path     If non-NULL, and set the pointed to string to the file
     452                 :            :      *                  path of this database (or if to some string describing
     453                 :            :      *                  the database in a backend-specified format if "path"
     454                 :            :      *                  isn't a concept which  make sense).
     455                 :            :      *
     456                 :            :      *  @return A constant indicating the backend type.
     457                 :            :      */
     458                 :            :     virtual int get_backend_info(std::string* path) const = 0;
     459                 :            : 
     460                 :            :     /** Find lowest and highest docids actually in use.
     461                 :            :      *
     462                 :            :      *  Only used by compaction, so only needs to be implemented by
     463                 :            :      *  backends which support compaction.
     464                 :            :      */
     465                 :            :     virtual void get_used_docid_range(docid& first,
     466                 :            :                                       docid& last) const;
     467                 :            : 
     468                 :            :     /** Return true if the database is open for writing.
     469                 :            :      *
     470                 :            :      *  If this is a WritableDatabase, always returns true.
     471                 :            :      *
     472                 :            :      *  For a Database, test if there's a writer holding the lock (or if
     473                 :            :      *  we can't test for a lock without taking it on the current platform,
     474                 :            :      *  throw Xapian::UnimplementedError).
     475                 :            :      */
     476                 :            :     virtual bool locked() const;
     477                 :            : 
     478                 :            :     /// Return a string describing this object.
     479                 :            :     virtual std::string get_description() const = 0;
     480                 :            : };
     481                 :            : 
     482                 :            : }
     483                 :            : 
     484                 :            : #endif // XAPIAN_INCLUDED_DATABASEINTERNAL_H

Generated by: LCOV version 1.11