xmldatamanager.h
Go to the documentation of this file.
1 /*
2  * Copyright 2006-2008 The FLWOR Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 #ifndef ZORBA_XMLDATAMANAGER_API_H
17 #define ZORBA_XMLDATAMANAGER_API_H
18 
19 #include <istream>
20 #include <zorba/config.h>
21 #include <zorba/api_shared_types.h>
23 
24 namespace zorba {
25 
26  /** \brief Using the XmlDataManager one can manage documents and collections.
27  *
28  * The XmlDataManager is a singleton instance. The Zorba object is reponsible
29  * for maintaining its lifetime. The instance can be accessed by calling
30  * getXmlDataManager() on the Zorba object. It may not be accessed anymore
31  * after Zorba::shutdown() has been called.
32  *
33  * XmlDataManager is a thread-safe class.
34  */
35  class ZORBA_DLL_PUBLIC XmlDataManager
36  {
37  public:
38  /**
39  * \brief The ParseOptions class stores various properties that affect
40  * how a document is parsed. An instance of this class is passed
41  * as input to the parseXML function.
42  */
44  {
45  private:
46  bool theDtdValidation;
47  bool theExternalEntityProcessing;
48 
49  public:
51  theDtdValidation(false),
52  theExternalEntityProcessing(false)
53  {}
54 
56 
57  /**
58  * Set the property enableDtd, which specifies whether the
59  * document should be validated against its associated DTD (if
60  * any).
61  */
62  void setDtdValidation(bool aEnable)
63  {
64  theDtdValidation = aEnable;
65  }
66 
67  /**
68  * Returns true if dtd validation is enabled, false otherwise.
69  */
71  {
72  return theDtdValidation;
73  }
74 
75  /**
76  * Set the property to enable or disable processing of XML external entities.
77  * If the option is enabled, the input must conform to the syntax
78  * _extParsedEnt_ (production [78] in XML 1.0); and since there is no DTD,
79  * the content must include no entity references. The result of the
80  * function call is a sequence of nodes.
81  */
82  void setExternalEntityProcessing(bool aEnable)
83  {
84  theExternalEntityProcessing = aEnable;
85  }
86 
87  /**
88  * Returns true if external entity processig is enabled,
89  * false otherwise.
90  */
92  {
93  return theExternalEntityProcessing;
94  }
95  };
96 
97  virtual DocumentManager*
98  getDocumentManager() const = 0;
99 
100  /** \brief Returns a CollectionManager responsible for all collections.
101  *
102  * The collection manager provides a set of functions for managing
103  * collections identified by a QName and their contents.
104  *
105  * Please note that the resulting manager is only responsible for
106  * dynamic collections identified by a QName, i.e. those that are
107  * not declared in the prolog of a module or identified by a URI.
108  *
109  * @return The collection manager responsible for managing
110  * collections.
111  *
112  */
113  virtual CollectionManager*
114  getCollectionManager() const = 0;
115 
116  /** \brief Returns a CollectionManager responsible for collections
117  * identified by a URI.
118  *
119  * The collection manager provides a set of functions for managing
120  * collections identified by a URI and their contents.
121  *
122  * Please note that the resulting manager is only responsible for
123  * dynamic collections identified by a URI, i.e. those that are
124  * not declared in the prolog of a module or identified by a QName.
125  *
126  * @return The collection manager responsible for managing
127  * collections.
128  *
129  */
130  virtual CollectionManager*
131  getW3CCollectionManager() const = 0;
132 
133  /** \brief Parse an XML document and return an Item.
134  *
135  */
136  virtual Item
137  parseXML(std::istream& aStream) const = 0;
138 
139  /** \brief Parse an XML document and return an Item.
140  *
141  * @param aStream the input stream whose content should be parsed
142  * @param aBaseURI the base URI which will be used as the base URI
143  * of the document. This serves both as the base URI
144  * used by the XML parser to resolve relative entity
145  * references within the document, and as the base URI
146  * of the document node that is returned.
147  */
148  virtual Item
149  parseXML(std::istream& aStream, const String& aBaseURI) const = 0;
150 
151  /** \brief Parse an XML document and return a sequence of nodes.
152  *
153  * This function parses the given input stream and returns the result
154  * as a sequence of nodes. If external entity processing is disabled
155  * the result will be a singleton sequence consisting of one document
156  * node. Otherwise, the result is the sequence of the external entity
157  * nodes.
158  *
159  * @param aStream the input stream whose content should be parsed
160  * @param aOptions @see ParseOptions
161  * @see ParseOptions
162  */
163  virtual ItemSequence_t
164  parseXML(std::istream& aStream, ParseOptions& aOptions) const = 0;
165 
166  /** \brief Parse an XML document and return a sequence of nodes.
167  *
168  * This function parses the given input stream and returns the result
169  * as a sequence of nodes. If external entity processing is disabled
170  * the result will be a singleton sequence consisting of one document
171  * node. Otherwise, the result is the sequence of the external entity
172  * nodes.
173  *
174  * @param aStream the input stream whose content should be parsed
175  * @param aBaseURI the base URI which will be used as the base URI
176  * of the document. This serves both as the base URI
177  * used by the XML parser to resolve relative entity
178  * references within the document, and as the base URI
179  * of the document node that is returned.
180  * @param aOptions @see ParseOptions
181  * @see ParseOptions
182  */
183  virtual ItemSequence_t
184  parseXML(
185  std::istream& aStream,
186  const String& aBaseURI,
187  ParseOptions& aOptions) const = 0;
188 
189  /** \brief Fetches an resource refered to by the given URI.
190  *
191  * @deprecated this function has been replaced by StaticContext::fetch.
192  */
193  virtual Item
194  fetch(const String& aURI) const = 0;
195 
196  /** \brief Register a DiagnosticHandler to which errors occuring during the
197  * management of documents and collections are reported.
198  *
199  * If no DiagnosticHandler has been set using this function then
200  * subclasses of the ZorbaException class are thrown to report
201  * errors.
202  *
203  * @param aDiagnosticHandler DiagnosticHandler to which errors
204  * are reported. The caller retains ownership over the
205  * DiagnosticHandler passed as parameter.
206  */
207  virtual void
208  registerDiagnosticHandler(DiagnosticHandler* aDiagnosticHandler) = 0;
209 
210 #ifndef ZORBA_NO_FULL_TEXT
211  /**
212  * Registers a StemmerProvider to use for stemming of text content in order
213  * to perform queries involving full-text.
214  *
215  * If no StemmerProvider has been set using this function, then the default
216  * StemmerProvider will be used.
217  *
218  * @param provider If not NULL, sets the StemmerProvider to use; if NULL,
219  * removes any previously registered StemmerProvider.
220  */
221  virtual void
222  registerStemmerProvider(StemmerProvider const *provider) = 0;
223 
224  /**
225  * Registers a TokenizerProvider to use for toknenization of text content
226  * in order to perform queries involving full-text.
227  *
228  * If no TokenizerProvider has been set using this function, then the
229  * default TokenizerProvider will be used.
230  *
231  * @param provider If not NULL, sets the TokenizerProvider to use; if NULL,
232  * removes any previously registered TokenizerProvider.
233  */
234  virtual void
235  registerTokenizerProvider(TokenizerProvider const *provider) = 0;
236 #endif /* ZORBA_NO_FULL_TEXT */
237 
238  protected:
239  /** \brief Destructor
240  */
241  virtual ~XmlDataManager() {}
242 
243  }; /* class XmlDataManager */
244 
245 } // namespace zorba
246 #endif /* ZORBA_XMLDATAMANAGER_API_H */
247 /* vim:set et sw=2 ts=2: */