xapian-core/include/xapian/errorhandler.h

   1 /** @file errorhandler.h
   2  * @brief Decide if a Xapian::Error exception should be ignored.
   3  */
   4 /* Copyright (C) 2003,2006,2007,2012,2013,2014,2016 Olly Betts
   5  *
   6  * This program is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU General Public License as
   8  * published by the Free Software Foundation; either version 2 of the
   9  * License, or (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
  19  */
  20
  21 #ifndef XAPIAN_INCLUDED_ERRORHANDLER_H
  22 #define XAPIAN_INCLUDED_ERRORHANDLER_H
  23
  24 #if !defined XAPIAN_IN_XAPIAN_H && !defined XAPIAN_LIB_BUILD
  25 # error "Never use <xapian/errorhandler.h> directly; include <xapian.h> instead."
  26 #endif
  27
  28 #include <xapian/attributes.h>
  29 #include <xapian/deprecated.h>
  30 #include <xapian/intrusive_ptr.h>
  31 #include <xapian/visibility.h>
  32
  33 namespace Xapian {
  34
  35 class Error;
  36
  37 /** Decide if a Xapian::Error exception should be ignored.
  38  *
  39  *  You can create your own subclass of this class and pass in an instance
  40  *  of it when you construct a Xapian::Enquire object.  Xapian::Error
  41  *  exceptions which happen during the match process are passed to this
  42  *  object and it can decide whether they should propagate or whether
  43  *  Enquire should attempt to continue.
  44  *
  45  *  The motivation is to allow searching over remote databases to handle a
  46  *  remote server which has died (both to allow results to be returned, and
  47  *  also so that such errors can be logged and dead servers temporarily removed
  48  *  from use).
  49  */
  50 class XAPIAN_VISIBILITY_DEFAULT ErrorHandler
  51     : public Xapian::Internal::opt_intrusive_base {
  52     /// Don't allow assignment.
  53     void operator=(const ErrorHandler &);
  54
  55     /// Don't allow copying.
  56     ErrorHandler(const Xapian::ErrorHandler &);
  57
  58     /** Perform user-specified error handling.
  59      *
  60      *  This virtual method must be defined by the API user to specify
  61      *  how a Xapian::Error is to be handled.
  62      *
  63      *  If you want execution to continue (where possible), then return
  64      *  true.  If you want the Error to be rethrown and propagate out
  65      *  of the library, then return false.
  66      *
  67      *  Note that it's not always possible to continue execution, so
  68      *  the error may be rethrown even if you return true.  The ErrorHandler
  69      *  is still called in this situation as you may want to log that a
  70      *  particular remote backend server isn't responding, and perhaps
  71      *  remove it from those being searched temporarily.
  72      *
  73      *  @param error    The Xapian::Error object under consideration.
  74      *
  75      *  @return  true to attempt to continue; false to rethrow the error.
  76      */
  77     XAPIAN_DEPRECATED_EX(virtual bool handle_error(Xapian::Error &error)) = 0;
  78
  79   public:
  80     /// Default constructor.
  81     XAPIAN_NOTHROW(ErrorHandler()) {}
  82
  83     /// We require a virtual destructor because we have virtual methods.
  84     virtual ~ErrorHandler();
  85
  86     /** Handle a Xapian::Error object.
  87      *
  88      *  This method is called when a Xapian::Error object is thrown and
  89      *  caught inside Enquire.  If this is the first ErrorHandler that
  90      *  the Error has been passed to, then the handle_error() virtual
  91      *  method is called, which allows the API user to decide how to
  92      *  handle the error.
  93      *
  94      *  @param error    The Xapian::Error object under consideration.
  95      */
  96     void operator()(Xapian::Error &error);
  97
  98     ErrorHandler * release() {
  99         opt_intrusive_base::release();
 100         return this;
 101     }
 102
 103     const ErrorHandler * release() const {
 104         opt_intrusive_base::release();
 105         return this;
 106     }
 107 };
 108
 109 }
 110
 111 #endif /* XAPIAN_INCLUDED_ERRORHANDLER_H */