src/dbus/server/pim/locale-factory.h

   1 /*
   2  * Copyright (C) 2012 Intel Corporation
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2.1 of the License, or (at your option) version 3.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the Free Software
  16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  17  * 02110-1301  USA
  18  */
  19
  20 /**
  21  * Abstract definition of sorting and searching plugin. Used
  22  * by folks.cpp, must be provided by exactly one implementation
  23  * which is chosen at compile time.
  24  */
  25
  26 #ifndef INCL_SYNCEVO_DBUS_SERVER_PIM_LOCALE_FACTORY
  27 #define INCL_SYNCEVO_DBUS_SERVER_PIM_LOCALE_FACTORY
  28
  29 #include <boost/shared_ptr.hpp>
  30 #include <boost/variant.hpp>
  31
  32 #include <folks/folks.h>
  33
  34 #include <syncevo/util.h>
  35
  36 #include <syncevo/declarations.h>
  37 SE_BEGIN_CXX
  38
  39 class IndividualCompare;
  40 class IndividualFilter;
  41
  42
  43 /**
  44  * Factory for everything related to the current locale: sorting and
  45  * searching.
  46  */
  47 class LocaleFactory
  48 {
  49  public:
  50     /**
  51      * Exactly one factory can be created, chosen at compile time.
  52      */
  53     static boost::shared_ptr<LocaleFactory> createFactory();
  54
  55     /**
  56      * Creates a compare instance or throws an error when that is not
  57      * possible.
  58      *
  59      * @param order     factory-specific string which chooses one of
  60      *                  the orderings supported by the factory
  61      * @return a valid instance, must not be NULL
  62      */
  63     virtual boost::shared_ptr<IndividualCompare> createCompare(const std::string &order) = 0;
  64
  65     /**
  66      * A recursive definition of a search expression.
  67      * All operand names, field names and values are strings.
  68      */
  69     typedef boost::make_recursive_variant<
  70         std::string,
  71         std::vector< boost::recursive_variant_ >
  72         >::type Filter_t;
  73
  74     /**
  75      * Simplified JSON representation (= no escaping of special characters),
  76      * for debugging and error reporting.
  77      */
  78     static std::string Filter2String(const Filter_t &filter);
  79
  80     /**
  81      * Throws "expected <item>, got instead: <filter as string>" when
  82      * conversion to V fails.
  83      */
  84     static const std::string &getFilterString(const Filter_t &filter, const char *expected);
  85     static const std::vector<Filter_t> &getFilterArray(const Filter_t &filter, const char *expected);
  86
  87     /**
  88      * Creates a filter instance or throws an error when that is not
  89      * possible.
  90      *
  91      * @param  represents a (sub-)filter
  92      * @level  0 at the root of the filter, incremented by one for each
  93      *         non-trivial indirection; i.e., [ [ <filter> ] ] still
  94      *         treats <filter> as if it was the root search
  95      *
  96      * @return a valid instance, must not be NULL
  97      */
  98     virtual boost::shared_ptr<IndividualFilter> createFilter(const Filter_t &filter, int level) = 0;
  99
 100     /**
 101      * To be called when parsing a Filter_t caused an exception.
 102      * Will add information about the filter and a preamble, if
 103      * called at the top level.
 104      */
 105     static void handleFilterException(const Filter_t &filter, int level, const std::string *file, int line);
 106
 107     /**
 108      * Pre-computed data for a single FolksIndividual which will be needed
 109      * for searching. Strictly speaking, this should be an opaque pointer
 110      * whose content is entirely owned by the implementation of LocaleFactory.
 111      * For the sake of performance and simplicity, we define a struct instead
 112      * which can be embedded inside IndividualData. Leads to better memory
 113      * locality and reduces overall memory consumption/usage.
 114      */
 115     struct Precomputed
 116     {
 117         /**
 118          * Normalized phone numbers (E164). Contains only + and digits.
 119          * TODO (?): store in more compact format.
 120          */
 121         std::vector<std::string> m_phoneNumbers;
 122     };
 123
 124     /**
 125      * (Re)set pre-computed data for an individual.
 126      */
 127     virtual void precompute(FolksIndividual *individual, Precomputed &precomputed) const = 0;
 128 };
 129
 130 SE_END_CXX
 131
 132 #endif // INCL_SYNCEVO_DBUS_SERVER_PIM_LOCALE_FACTORY