669f2713484a3e089533f9877dc339053fb51a7b
[anna.git] / include / anna / xml / Document.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_xml_Document_hpp
38 #define anna_xml_Document_hpp
39
40 struct _xmlDoc;
41 struct _xmlValidCtxt;
42 struct _xmlDoc;
43
44 #include <anna/core/DataBlock.hpp>
45 #include <anna/core/RuntimeException.hpp>
46
47 namespace anna {
48
49 namespace xml {
50
51 class Parser;
52 class XPath;
53 class DTD;
54 class Node;
55
56 /**
57    Clase base para manejar los documentos XML.
58
59    Ejemplo de documento XML:
60
61    \code
62
63    <xvc HeartBeat="20000">
64       <broadcast>
65          <INetAddress Address="204.152.65.15" Port="2000"/>
66          <INetAddress Address="204.152.65.47" Port="2002"/>
67       </broadcast>
68
69       <ethernet Mode="raw" VirtualAddress="1.1.1.100">
70          <Input Device="/dev/qfe" PhysicalAccessPoint="2" MAC="8:0:20:9e:ee:21"/>
71          <Output Device="/dev/qfe" PhysicalAccessPoint="2" MAC="8:0:20:9e:ee:c9"/>
72       </ethernet>
73    </xvc>
74
75    \endcode
76 */
77 class Document : anna::DataBlock {
78 public:
79   /**
80      Destructor.
81   */
82   virtual ~Document();
83
84   /**
85      Inicializa el contenido del documento XML.
86      \param content Contenido de la Documento, depedendiendo del tipo de Documento hara referencia
87      a un nombre de archivo, una URI o a una cadena.
88   */
89   void initialize(const char* content) throw(RuntimeException);
90
91   /**
92      Inicializa el contenido del documento XML.
93      \param content Contenido del Documento XML.
94   */
95   void initialize(const DataBlock& content) throw(RuntimeException);
96
97   /**
98    * Obtiene el conjunto de caracteres usado en el documento XML. Puede ser NULL.
99    * \return El conjunto de caracteres usado en el documento XML.
100    */
101   const char* getEncoding() const throw();
102
103   /**
104    * Obtiene la versión indicada en el documento XML.Puede ser NULL.
105    * \return La versión indicada en el documento XML.
106    */
107   const char* getVersion() const throw();
108
109   /**
110      Devuelve el contenido asociado al documento XML.
111      \return El contenido asociado al documento XML.
112   */
113   virtual const DataBlock& getContent() const throw(RuntimeException) { return *this; }
114
115   /**
116      Devuelve el contenido asociado al documento XML expresado como una cadena C.
117      \return El contenido asociado al documento XML expresado como una cadena C.
118   */
119   const char* getContentAsCString() const throw(RuntimeException);
120
121   /**
122    * Establece el conjunto de caracteres usado en el documento XML.
123    * \param encoding Literal que indica el conjunto de caracteres. Puede ser NULL.
124    */
125   void setEncoding(const char* encoding) throw();
126
127   /**
128    * Establece la versión usada en el documento XML.
129    * \param encoding Literal que indica la versión. Puede ser NULL.
130    */
131   void setVersion(const char* version) throw();
132
133   /**
134    * Analiza el contenido del documento XML y devuelve el nodo raíz.
135    * \return El nodo raiz del arbol XML correspondiente al resultado del analisis.
136    * \warning Este documento debe estar correctamente inicializado.
137    */
138   const xml::Node* parse() throw(RuntimeException);
139
140   /**
141    * Analiza el documento XML recibido como parametro, y verifica que cumpla las reglas
142    * establecidas por la DTD.
143    * \param dtd DTD que debe cumplir el documento XML.
144    * \return El nodo raiz del arbol XML correspondiente al resultado del analisis.
145    * \warning Este documento debe estar correctamente inicializado.
146    */
147   const xml::Node* parse(const DTD& dtd) throw(RuntimeException);
148
149 protected:
150   /**
151      Constructor.
152   */
153   Document();
154
155   /**
156    * Libera la memoria asociada a los componentes de este documento.
157    */
158   void clear() throw();
159
160   /*
161    * Establece el contenido de este documento XML.
162    * \param content Buffer que contiene una C-String con la que inciar este documento XML.
163    */
164   void setContent(const char* content) throw() {
165     DataBlock::clear();
166     DataBlock::append(content, anna_strlen(content) + 1);
167     a_contentIsCString = true;
168   }
169
170   /*
171    * Establece el contenido de este documento XML.
172    * \param content Buffer que apunta al contenido con la que inciar este documento XML.
173    * \param size Longitud del buffer.
174    * \warning Sólo uso interno
175    */
176   void setContent(const char* content, const int size) throw() {
177     DataBlock::clear();
178     DataBlock::append(content, size);
179     a_contentIsCString = false;
180   }
181
182   /*
183    * Establece el contenido de este documento XML.
184    * \param content Bloque de datos del que copiar el valor para iniciar este documento XML.
185    */
186   void setContent(const DataBlock& content) throw() {
187     DataBlock::operator= (content);
188     a_contentIsCString = false;
189   }
190
191 private:
192   _xmlDoc* a_handle;
193   std::string* a_encoding;
194   std::string* a_version;
195   bool a_contentIsCString;
196   DataBlock* a_asCString;
197   Parser* a_parser;
198
199   Document(const Document&);
200
201   virtual _xmlDoc* do_initialize(const char* content) throw(RuntimeException) = 0;
202   virtual _xmlDoc* do_initialize(const DataBlock& content) throw(RuntimeException) = 0;
203
204   friend class Parser;
205   friend class XPath;
206 };
207
208 }
209 }
210
211 #endif