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: */
The ParseOptions class stores various properties that affect how a document is parsed.
Using the XmlDataManager one can manage documents and collections.
The Zorba Item interface.
Definition: item.h:60
virtual ~XmlDataManager()
Destructor.
Definition: options.h:40
A StemmerProvider, given a language, provides a Stemmer for it.
Definition: stemmer.h:88
void setDtdValidation(bool aEnable)
Set the property enableDtd, which specifies whether the document should be validated against its asso...
The Zorba string class.
Definition: zorba_string.h:33
bool isExternalEntityProcessingEnabled() const
Returns true if external entity processig is enabled, false otherwise.
When registered with an XQuery object, a DiagnosticHandler handles all exceptions and warnings that o...
A TokenizerProvider provides a Tokenizer for a given language.
Definition: tokenizer.h:284
This class defines a set of functions for managing persistent collections.
bool isDtdValidationEnabled() const
Returns true if dtd validation is enabled, false otherwise.
void setExternalEntityProcessing(bool aEnable)
Set the property to enable or disable processing of XML external entities.