1 // ANNA - Anna is Not Nothingness Anymore //
3 // (c) Copyright 2005-2015 Eduardo Ramos Testillano & Francisco Ruiz Rayo //
5 // See project site at http://redmine.teslayout.com/projects/anna-suite //
6 // See accompanying file LICENSE or copy at http://www.teslayout.com/projects/public/anna.LICENSE //
9 #ifndef anna_http_wims20_Abstract_hpp
10 #define anna_http_wims20_Abstract_hpp
14 #include <anna/core/RuntimeException.hpp>
15 #include <anna/core/util/Recycler.hpp>
24 Permite interpretar una URI según las recomendaciones de WIMS 2.0, lo que facilita
25 el desarrollo de aplicaciones integradas en Web 2.0; estas recomendaciones indican
26 cómo debe formarse la petición Abstract (REpresentational State Transfer) para permitir
27 el desarrollo de cualquier servicio.
29 El formato general de una URI según la recomendación de WIMS 2.0 es:
32 http://domain-openapis/path-openapis/serviceID/guid/other_possible_levels?query_parameters
35 Dónde los campos tienen siguen la siguiente especificación:
36 \li http://domain-openapis: Identifica el recurso del Open API. Formará parte de la configuración
37 de nuestro API (servicio) particular.
38 \li path-openapis: Recurso opcional que ajusta la ruta hacia los recursos de éste API. Formará parte
39 de la configuración de nuestro API (servicio) particular.
40 \li serviceID: Identificador de recurso.
41 \li guid: Identificador del usuario que solicita la petición.
42 \li other_possible_level: Opcionalmente se pueden indicar tantos niveles jerárquicos como fuera
43 necesario para el servicio.
44 \li query_parameters: Lista de parámetros. Si hay más de un parámetro se separará con '&'.
48 typedef std::vector <std::string*> other_level_container;
49 typedef other_level_container::iterator other_level_iterator;
50 typedef other_level_container::const_iterator const_other_level_iterator;
53 * Los parámetros se ordenan en el mismo orden en que fueron indicados
54 * por eso no se guardan sobre un std::map, ya que al volcarlos sobre la
55 * cadena que actuará como URI aparecerían ordenados alfabéticamente y
56 * quizás el servidor no lo espera así.
58 typedef std::pair <std::string*, std::string*> parameter_pkv;
59 typedef std::vector <parameter_pkv> parameter_container;
60 typedef parameter_container::iterator parameter_iterator;
61 typedef parameter_container::const_iterator const_parameter_iterator;
69 * Devuelve el campo \em domain-openapis establecido en el contructor.
70 * \return el campo \em domain-openapis establecido en el contructor.
72 const std::string& getDomain() const { return a_domain; }
75 * Devuelve el campo \em path-openapis
76 * \return El campo \em path-openapis, puede ser NULL.
78 const std::string* getPath() const { return a_path; }
81 * Devuelve el servicio de la OpenAPI.
82 * \param Identificador de servicio usado en la OpenAPI.
84 const std::string& getServiceID() const { return a_serviceID; }
87 * Devuelve identificador de usuario que interacciona con el servicio.
88 * \return El identificador de usuario que interacciona con el servicio.
90 const std::string& getGUID() const { return a_guid; }
93 * Establece el servicio de la OpenAPI.
94 * \param serviceID Identificador de servicio usado en la OpenAPI.
96 void setServiceID(const std::string& serviceID) { a_serviceID = serviceID; a_fixedPart.clear(); }
99 * Establece el identificador de usuario que interacciona con el servicio.
100 * \param guid Identificador de usuario. Dónde por usuario se entiende cualquier elemento
101 * que pueda intereccionar con nuestro servicio
103 void setGUID(const std::string& guid) { a_guid = guid; a_fixedPart.clear(); }
106 * Devuelve \em true si la estructura contiene parámetros o \em false en otro caso.
107 * \return \em true si la estructura contiene parámetros o \em false en otro caso.
109 bool hasParameters() const { return a_parameters != NULL && a_parameters->empty() == false; }
112 * Devuelve \em true si la estructura contiene niveles opcionales o \em false en otro caso.
113 * \return \em true si la estructura contiene niveles opcionales o \em false en otro caso.
115 bool hasOtherLevels() const { return a_otherLevels != NULL && a_otherLevels->empty() == false; }
118 * Limpia el contenido asociado al parámetro \em other_possible_level. Sólo debería
119 * invocarse a este método en caso de que el servicio destino de la petición haya cambiado.
121 virtual void clearOtherLevels() ;
124 * Limpia el contenido asociado a los parámetros. Sólo debería invocarse a éste método en caso
125 * de que el número de parámetros a enviar sea distinto al de la petición anterior.
126 * Si son los mismos parámetros con el mismo nombre, deberíamos reutilizar el máximo número
129 virtual void clearParameters() ;
132 * Inicializa los toda la información asociada a esta instancia.
140 * Devuelce una cadena con la información relevante sobre esta clase.
141 * \return una cadena con la información relevante sobre esta clase.
143 std::string asString() const ;
146 * Devuelve un iterator al comienzo de la lista de niveles adicionales.
147 * \return un iterator al comienzo de la lista de niveles adicionales.
148 * \warning Sólo se puede invocar a este método si #hasOtherLevels devuelve \em true.
150 other_level_iterator other_level_begin() { return a_otherLevels->begin(); }
153 * Devuelve un iterator al final de la lista de niveles adicionales.
154 * \return un iterator al final de la lista de niveles adicionales.
155 * \warning Sólo se puede invocar a este método si #hasOtherLevels devuelve \em true.
157 other_level_iterator other_level_end() { return a_otherLevels->end(); }
160 * Devuelve el valor asociado al iterador.
161 * \param ii Iterador sobre los niveles opcionales.
162 * \return el valor asociado al iterador.
164 static std::string* otherLevel(other_level_iterator ii) { return *ii; }
167 * Devuelve un iterator al comienzo de la lista de niveles adicionales.
168 * \return un iterator al comienzo de la lista de niveles adicionales.
169 * \warning Sólo se puede invocar a este método si #hasOtherLevels devuelve \em true.
171 const_other_level_iterator other_level_begin() const { return a_otherLevels->begin(); }
174 * Devuelve un iterator al final de la lista de niveles adicionales.
175 * \return un iterator al final de la lista de niveles adicionales.
176 * \warning Sólo se puede invocar a este método si #hasOtherLevels devuelve \em true.
178 const_other_level_iterator other_level_end() const { return a_otherLevels->end(); }
181 * Devuelve el valor asociado al iterador.
182 * \param ii Iterador sobre los niveles opcionales.
183 * \return el valor asociado al iterador.
185 static const std::string& otherLevel(const_other_level_iterator ii) { return **ii; }
188 * Devuelve un iterator al comienzo de la lista de niveles adicionales.
189 * \return un iterator al comienzo de la lista de niveles adicionales.
190 * \warning Sólo se puede invocar a este método si #hasParameters devuelve \em true.
192 const_parameter_iterator parameter_begin() const { return a_parameters->begin(); }
195 * Devuelve un iterator al final de la lista de niveles adicionales.
196 * \return un iterator al final de la lista de niveles adicionales.
197 * \warning Sólo se puede invocar a este método si #hasParameters devuelve \em true.
199 const_parameter_iterator parameter_end() const { return a_parameters->end(); }
202 * Devuelve el nombre del parámetro asociado al iterador.
203 * \param ii Iterador sobre los niveles opcionales.
204 * \return el nombre del parámetro asociado al iterador.
206 static const std::string& parameter_name(const_parameter_iterator ii) { return *(ii->first); }
209 * Devuelve el valor del parámetro asociado al iterador.
210 * \param ii Iterador sobre los niveles opcionales.
211 * \return el valor del parámetro asociado al iterador.
213 static const std::string& parameter_value(const_parameter_iterator ii) { return *(ii->second); }
216 other_level_container* a_otherLevels;
217 parameter_container* a_parameters;
220 * Contructor indicando el parámetro opcional \em path-openapis. Estos dos parámetros se obtendrá como
221 * parte de la configuración de nuestro sistema.
222 * \param domain: Identifica el recurso del OpenAPI.
223 * \param path: Parámetro opcional que ajusta la ruta hacia los recusos de éste API.
225 Abstract(const char* whatis, const std::string& domain, const std::string& path);
228 * Constructor que no usará el parámetro opcional \em path-openapis. Este parámetro se obtendrá como
229 * parte de la configuración de nuestro sistema.
230 * \param domain: Identifica el recurso del OpenAPI.
232 explicit Abstract(const char* whatis, const std::string& domain);
235 * Calcula la parte fija de la petición en base a #calculeShortFixedPart, el \em serviceID y el \em GUID.
236 * Mientras estos dos últimos campos se mantengan constrantes, el resultado de este método no cambia.
237 * \return Una cadena con la parte fija de la petición.
239 const std::string& calculeFixedPart() noexcept(false);
242 * Calcula la parte fija corta de la petición. Tiene en cuenta el \em domain-openapis y si existe
243 * el path-openapis. Si fuera necesario incluye el identificador de protocolo "http://".
244 * \return Una cadena con la parte fija corta de la petición.
246 const std::string& calculeShortFixedPart() noexcept(false);
249 * Optimiza la creación y liberación de cadenas que usa el proceso de interpretación continuamente.
250 * \warning Exclusivamente uso interno.
252 std::string* createString() noexcept(false) { return a_string_pool.create(); }
255 * Optimiza la creación y liberación de cadenas que usa el proceso de interpretación continuamente.
256 * \warning Exclusivamente uso interno.
258 std::string* createString(const char* value) noexcept(false) {
259 std::string* result = a_string_pool.create();
265 * Optimiza la creación y liberación de cadenas que usa el proceso de interpretación continuamente.
266 * \warning Exclusivamente uso interno.
268 std::string* createString(const std::string& value) noexcept(false) { return createString(value.c_str()); }
271 * Optimiza la creación y liberación de cadenas que usa el proceso de interpretación continuamente.
272 * \warning Exclusivamente uso interno.
274 void destroyString(std::string* str) { a_string_pool.release(str); }
277 * Amplía la lista de niveles.
278 * \param otherLevel Nombre del nivel con el que ampliar las lista.
280 void other_level_add(const std::string& otherLevel) noexcept(false);
283 * Amplía la lista de parámetros con una nueva pareja (Nombre, Valor).
284 * \param name Nombre del parámetro a crear.
285 * \param value Valor asociado al parámetro.
287 void parameter_set(const std::string& name, const std::string& value) noexcept(false);
290 * Devuelve un iterator al comienzo de la lista de niveles adicionales.
291 * \return un iterator al comienzo de la lista de niveles adicionales.
292 * \warning Sólo se puede invocar a este método si #hasParameters devuelve \em true.
294 parameter_iterator parameter_begin() { return a_parameters->begin(); }
297 * Devuelve un iterator al final de la lista de niveles adicionales.
298 * \return un iterator al final de la lista de niveles adicionales.
299 * \warning Sólo se puede invocar a este método si #hasParameters devuelve \em true.
301 parameter_iterator parameter_end() { return a_parameters->end(); }
304 * Devuelve el nombre del parámetro asociado al iterador.
305 * \param ii Iterador sobre los niveles opcionales.
306 * \return el nombre del parámetro asociado al iterador.
308 static std::string* parameter_name(parameter_iterator ii) { return ii->first; }
311 * Devuelve el valor del parámetro asociado al iterador.
312 * \param ii Iterador sobre los niveles opcionales.
313 * \return el valor del parámetro asociado al iterador.
315 static std::string* parameter_value(parameter_iterator ii) { return ii->second; }
318 * Concatena las cadenas recibidas teniendo en entre ambas debe de haber un carácter '/'.
320 static void appendWithSlash(std::string& target, const std::string& other) ;
323 const std::string a_whatis;
324 const std::string a_domain;
326 std::string a_serviceID;
328 Recycler <std::string> a_string_pool;
329 std::string a_fixedPart;