include/anna/ldap/Search.hpp

   1 // ANNA - Anna is Not 'N' Anymore
   2 //
   3 // (c) Copyright 2005-2014 Eduardo Ramos Testillano & Francisco Ruiz Rayo
   4 //
   5 // https://bitbucket.org/testillano/anna
   6 //
   7 // Redistribution and use in source and binary forms, with or without
   8 // modification, are permitted provided that the following conditions
   9 // are met:
  10 //
  11 //     * Redistributions of source code must retain the above copyright
  12 // notice, this list of conditions and the following disclaimer.
  13 //     * Redistributions in binary form must reproduce the above
  14 // copyright notice, this list of conditions and the following disclaimer
  15 // in the documentation and/or other materials provided with the
  16 // distribution.
  17 //     * Neither the name of Google Inc. nor the names of its
  18 // contributors may be used to endorse or promote products derived from
  19 // this software without specific prior written permission.
  20 //
  21 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32 //
  33 // Authors: eduardo.ramos.testillano@gmail.com
  34 //          cisco.tierra@gmail.com
  35
  36
  37 #ifndef anna_ldap_Search_hpp
  38 #define anna_ldap_Search_hpp
  39
  40 #include <vector>
  41
  42 #include <anna/core/util/Recycler.hpp>
  43
  44 #include <anna/ldap/defines.hpp>
  45 #include <anna/ldap/Request.hpp>
  46 #include <anna/ldap/Scope.hpp>
  47
  48 namespace anna {
  49
  50 namespace ldap {
  51
  52 class Session;
  53
  54 /**
  55    Modela las peticiones de busqueda realizadas contra un servidor LDAP.
  56 */
  57 class Search : public Request {
  58   typedef Recycler<std::string> attribute_pool;
  59   typedef std::vector<std::string*> attribute_container;
  60   typedef attribute_container::iterator attribute_iterator;
  61
  62 public:
  63   typedef attribute_container::const_iterator const_attribute_iterator;
  64
  65   /**
  66      Constructor.
  67      \param onExpiry Indica la acción a realizar si el temporizador de esta transación expira.
  68   */
  69   Search(const Request::OnExpiry::_v onExpiry = Request::OnExpiry::Abandon) : Request(ClassCode::Search, onExpiry) { clear(); }
  70
  71   /**
  72      Devuelve el DN de la entrada en la que se comienza la busqueda.
  73      \return El DN de la entrada en la que se comienza la busqueda.
  74   */
  75   const std::string& getBase() const throw() { return a_base; }
  76
  77   /**
  78      Devuelve el ambito de la busqueda.
  79      \return El ambito de la busqueda.
  80   */
  81   Scope::_v getScope() const throw() { return a_scope; }
  82
  83   /**
  84      Devuelve el filtro aplicado a la busqueda.
  85      \return El filtro aplicado a la busqueda.
  86   */
  87   const std::string& getFilter() const throw() { return a_filter; }
  88
  89   /**
  90      Devuelve el indicador de tratamiento de busquedas.
  91      \return El indicador de tratamiento de busquedas.
  92   */
  93   bool getOnlyType() const throw() { return a_onlyType; }
  94
  95   /**
  96      Devuelve el numero maximo de elementos devueltos como resultado de la consulta.
  97      \return El numero maximo de elementos devueltos como resultado de la consulta.
  98      \see clearSizeLimit.
  99   */
 100   int getSizeLimit() const throw() { return a_sizeLimit; }
 101
 102   /**
 103      Establece el DN de la entrada en la que comenzar la busqueda.
 104      \param base DN de la entrada en la que comenzar la busqueda.
 105   */
 106   void setBase(const std::string& base) throw() { a_base = base; }
 107
 108   /**
 109      Establece el ambito de la busqueda.
 110      \param scope Ambito de la busqueda.
 111   */
 112   void setScope(const Scope::_v scope) throw() { a_scope = scope; }
 113
 114   /**
 115      Establece el ambito de la busqueda.
 116      \param scope Texto que identifica el ambito de la busqueda. Si no se trata de un texto
 117      reconocido se devolvera una excepcion.
 118   */
 119   void setScope(const char* scope) throw(RuntimeException) { a_scope = Scope::asEnumEx(scope); }
 120
 121   /**
 122      Establece el filtro aplicado a la busqueda.
 123      \param filter Filtro aplicado a la busqueda.
 124      \see clearFilter
 125   */
 126   void setFilter(const std::string& filter) throw() { a_filter = filter; }
 127
 128   /**
 129      Determina como se van a tratar los atributos.
 130      \param onlyType Un valor \em true indica que solo se requieren los tipos de atributos, un valor
 131      \em false indica que se requieren tipos y valores asociados a los atributos.
 132   */
 133   void setOnlyType(const bool onlyType) throw() { a_onlyType = onlyType; }
 134
 135   /**
 136      Establece el numero maximo de elementos devueltos como resultado de la consulta.
 137      \param sizeLimit Numero de entradas retornadas por la busqueda.
 138      \see clearSizeLimit.
 139   */
 140   void setSizeLimit(const int sizeLimit) throw() { a_sizeLimit = sizeLimit; }
 141
 142   /**
 143      Elimina el filtro asociado a esta consulta.
 144   */
 145   void clearFilter() throw() { a_filter.clear(); }
 146
 147   /**
 148      Elimina el limite en cuanto al numero de elementos indicados en la consulta.
 149   */
 150   void clearSizeLimit() throw() { a_sizeLimit = 0; }
 151
 152   /**
 153    * Elimina los atributos asociados a esta consulta.
 154    */
 155   void clearAttributes() throw();
 156
 157   /**
 158      Incorpora un elemento a la lista de atributos que deseamos obtener de cada una de las entradas
 159      que cumplen el filtro establecido.
 160      Si esta lista esta vacia se devolvera la informacion de todos los atributos implicados.
 161   */
 162   void addAttribute(const std::string& attribute) throw() {
 163     std::string* newString = st_attributes.create();
 164     *newString = attribute;
 165     a_attributes.push_back(newString);
 166   }
 167
 168   /**
 169      Inicializa el contenido de esta clase.
 170   */
 171   void clear() throw();
 172
 173   /**
 174      Devuelve un iterador que apunta el primer atributo contenido en la consulta.
 175      \return un iterador que apunta el primer atributo contenido en la consulta.
 176   */
 177   const_attribute_iterator attribute_begin() const throw() { return a_attributes.begin(); }
 178
 179   /**
 180      Devuelve un iterador que apunta el ultimo atributo contenido en la consulta.
 181      \return un iterador que apunta el ultimo atributo contenido en la consulta.
 182   */
 183   const_attribute_iterator attribute_end() const throw() { return a_attributes.end(); }
 184
 185   /**
 186      Devuelve el numero de atributos contenidos en la consulta.
 187      \return El numero de atributos contenidos en la consulta.
 188   */
 189   int attribute_size() const throw() { return a_attributes.size(); }
 190
 191   /**
 192      Devuelve el atributo apuntado por el iterador recibido.
 193      \param ii Iterador con el que estamos recorriendo los atributos.
 194      \return El atributo apuntado por el iterador recibido.
 195   */
 196   static const std::string& attribute(const_attribute_iterator ii) throw() { return **ii; }
 197
 198   /**
 199      Devuelve una cadena con la informacion referente a este objeto.
 200      \return Una cadena con la informacion referente a este objeto.
 201   */
 202   virtual std::string asString() const throw();
 203
 204   /**
 205      Devuelve un nodo XML con la informacion referente a este objeto.
 206      \param parent Nodo XML a partir del cual introducir la informacion.
 207      \return Un nodo XML con la informacion referente a este objeto.
 208   */
 209   virtual xml::Node* asXML(xml::Node* parent) const throw();
 210
 211 private:
 212   std::string a_base;
 213   Scope::_v a_scope;
 214   std::string a_filter;
 215   bool a_onlyType;
 216   int a_sizeLimit;
 217   attribute_container a_attributes;
 218
 219   static attribute_pool st_attributes;
 220
 221   attribute_iterator attribute_begin() throw() { return a_attributes.begin(); }
 222   attribute_iterator attribute_end() throw() { return a_attributes.end(); }
 223   int attribute_size() throw() { return a_attributes.size(); }
 224   static std::string& attribute(attribute_iterator ii) throw() { return **ii; }
 225
 226   IdMessage send(Session&) const throw();
 227 };
 228
 229 }
 230 }
 231
 232 #endif
 233