xapian-core/include/xapian/registry.h

   1 /** @file
   2  * @brief Class for looking up user subclasses during unserialisation.
   3  */
   4 /* Copyright 2009 Lemur Consulting Ltd
   5  * Copyright 2009,2011,2013,2014,2019,2024 Olly Betts
   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
  20  * USA
  21  */
  22
  23 #ifndef XAPIAN_INCLUDED_REGISTRY_H
  24 #define XAPIAN_INCLUDED_REGISTRY_H
  25
  26 #if !defined XAPIAN_IN_XAPIAN_H && !defined XAPIAN_LIB_BUILD
  27 # error Never use <xapian/registry.h> directly; include <xapian.h> instead.
  28 #endif
  29
  30 #include <xapian/intrusive_ptr.h>
  31 #include <xapian/visibility.h>
  32 #include <string>
  33
  34 namespace Xapian {
  35
  36 // Forward declarations.
  37 class KeyMaker;
  38 class LatLongMetric;
  39 class MatchSpy;
  40 class PostingSource;
  41 class Weight;
  42
  43 /** Registry for user subclasses.
  44  *
  45  *  This class provides a way for the remote server to look up user subclasses
  46  *  when unserialising.
  47  */
  48 class XAPIAN_VISIBILITY_DEFAULT Registry {
  49   public:
  50     /// Class holding details of the registry.
  51     class Internal;
  52
  53   private:
  54     /// @internal Reference counted internals.
  55     Xapian::Internal::intrusive_ptr_nonnull<Internal> internal;
  56
  57   public:
  58     /** Copy constructor.
  59      *
  60      *  The internals are reference counted, so copying is cheap.
  61      *
  62      *  @param other    The object to copy.
  63      */
  64     Registry(const Registry & other);
  65
  66     /** Assignment operator.
  67      *
  68      *  The internals are reference counted, so assignment is cheap.
  69      *
  70      *  @param other    The object to copy.
  71      */
  72     Registry & operator=(const Registry & other);
  73
  74     /** Move constructor.
  75      *
  76      * @param other     The object to move.
  77      */
  78     Registry(Registry && other);
  79
  80     /** Move assignment operator.
  81      *
  82      * @param other     The object to move.
  83      */
  84     Registry & operator=(Registry && other);
  85
  86     /** Default constructor.
  87      *
  88      *  The registry will contain all standard subclasses of user-subclassable
  89      *  classes.
  90      */
  91     Registry();
  92
  93     ~Registry();
  94
  95     /** Register a weighting scheme.
  96      *
  97      *  @param wt       The weighting scheme to register.
  98      */
  99     void register_weighting_scheme(const Xapian::Weight &wt);
 100
 101     /** Get the weighting scheme given a name.
 102      *
 103      *  @param name     The name of the weighting scheme to find.
 104      *  @return         An object with the requested name, or NULL if the
 105      *                  weighting scheme could not be found.  The returned
 106      *                  object is owned by the registry and so must not be
 107      *                  deleted by the caller.
 108      */
 109     const Xapian::Weight* get_weighting_scheme(std::string_view name) const;
 110
 111     /** Register a user-defined posting source class.
 112      *
 113      *  @param source   The posting source to register.
 114      */
 115     void register_posting_source(const Xapian::PostingSource &source);
 116
 117     /** Get a posting source given a name.
 118      *
 119      *  @param name     The name of the posting source to find.
 120      *  @return         An object with the requested name, or NULL if the
 121      *                  posting source could not be found.  The returned
 122      *                  object is owned by the registry and so must not be
 123      *                  deleted by the caller.
 124      */
 125     const Xapian::PostingSource*
 126             get_posting_source(std::string_view name) const;
 127
 128     /** Register a user-defined match spy class.
 129      *
 130      *  @param spy      The match spy to register.
 131      */
 132     void register_match_spy(const Xapian::MatchSpy &spy);
 133
 134     /** Get a match spy given a name.
 135      *
 136      *  @param name     The name of the match spy to find.
 137      *  @return         An object with the requested name, or NULL if the
 138      *                  match spy could not be found.  The returned
 139      *                  object is owned by the registry and so must not be
 140      *                  deleted by the caller.
 141      */
 142     const Xapian::MatchSpy* get_match_spy(std::string_view name) const;
 143
 144     /// Register a user-defined lat-long metric class.
 145     void register_lat_long_metric(const Xapian::LatLongMetric &metric);
 146
 147     /** Get a lat-long metric given a name.
 148      *
 149      *  The returned metric is owned by the registry object.
 150      *
 151      *  Returns NULL if the metric could not be found.
 152      */
 153     const Xapian::LatLongMetric*
 154             get_lat_long_metric(std::string_view name) const;
 155
 156     /** Register a user-defined KeyMaker subclass.
 157      *
 158      *  @param keymaker The KeyMaker subclass to register.  The clean up of
 159      *                  this object is handled via Xapian's optional reference
 160      *                  counting.  The simplest way to do so is to allocate it
 161      *                  with <code>new</code> and call <code>release()</code>
 162      *                  on it before passing it to this method to tell Xapian
 163      *                  to manage its lifetime.  The alternative approach is
 164      *                  for the caller to ensure the KeyMaker object remains
 165      *                  valid for the lifetime of the Registry object.
 166      */
 167     void register_key_maker(Xapian::KeyMaker* keymaker);
 168
 169     /** Get a KeyMaker given a name.
 170      *
 171      *  @param name     The name of the KeyMaker to find.
 172      *  @return         An object with the requested name, or NULL if the
 173      *                  KeyMaker could not be found.  The returned
 174      *                  object must <b>not</b> be deleted by the caller.
 175      */
 176     const Xapian::KeyMaker* get_key_maker(std::string_view name) const;
 177 };
 178
 179 }
 180
 181 #endif /* XAPIAN_INCLUDED_REGISTRY_H */