00001 /* 00002 * Copyright 2006-2008 The FLWOR Foundation. 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 #ifndef ZORBA_XMLDATAMANAGER_API_H 00017 #define ZORBA_XMLDATAMANAGER_API_H 00018 00019 #include <istream> 00020 #include <zorba/config.h> 00021 #include <zorba/api_shared_types.h> 00022 #include <zorba/static_context_consts.h> 00023 00024 namespace zorba { 00025 00026 /** \brief Using the XmlDataManager one can manage documents and collections. 00027 * 00028 * The XmlDataManager is a singleton instance. The Zorba object is reponsible 00029 * for maintaining its lifetime. The instance can be accessed by calling 00030 * getXmlDataManager() on the Zorba object. It may not be accessed anymore 00031 * after Zorba::shutdown() has been called. 00032 * 00033 * XmlDataManager is a thread-safe class. 00034 */ 00035 class ZORBA_DLL_PUBLIC XmlDataManager 00036 { 00037 public: 00038 /** 00039 * \brief The ParseOptions class stores various properties that affect 00040 * how a document is parsed. An instance of this class is passed 00041 * as input to the parseXML function. 00042 */ 00043 class ParseOptions 00044 { 00045 private: 00046 bool theDtdValidation; 00047 bool theExternalEntityProcessing; 00048 00049 public: 00050 ParseOptions() : 00051 theDtdValidation(false), 00052 theExternalEntityProcessing(false) 00053 {} 00054 00055 ~ParseOptions() {} 00056 00057 /** 00058 * Set the property enableDtd, which specifies whether the 00059 * document should be validated against its associated DTD (if 00060 * any). 00061 */ 00062 void setDtdValidation(bool aEnable) 00063 { 00064 theDtdValidation = aEnable; 00065 } 00066 00067 /** 00068 * Returns true if dtd validation is enabled, false otherwise. 00069 */ 00070 bool isDtdValidationEnabled() const 00071 { 00072 return theDtdValidation; 00073 } 00074 00075 /** 00076 * Set the property to enable or disable processing of XML external entities. 00077 * If the option is enabled, the input must conform to the syntax 00078 * _extParsedEnt_ (production [78] in XML 1.0); and since there is no DTD, 00079 * the content must include no entity references. The result of the 00080 * function call is a sequence of nodes. 00081 */ 00082 void setExternalEntityProcessing(bool aEnable) 00083 { 00084 theExternalEntityProcessing = aEnable; 00085 } 00086 00087 /** 00088 * Returns true if external entity processig is enabled, 00089 * false otherwise. 00090 */ 00091 bool isExternalEntityProcessingEnabled() const 00092 { 00093 return theExternalEntityProcessing; 00094 } 00095 }; 00096 00097 virtual DocumentManager* 00098 getDocumentManager() const = 0; 00099 00100 /** \brief Returns a CollectionManager responsible for all collections. 00101 * 00102 * The collection manager provides a set of functions for managing 00103 * collections identified by a QName and their contents. 00104 * 00105 * Please note that the resulting manager is only responsible for 00106 * dynamic collections identified by a QName, i.e. those that are 00107 * not declared in the prolog of a module or identified by a URI. 00108 * 00109 * @return The collection manager responsible for managing 00110 * collections. 00111 * 00112 */ 00113 virtual CollectionManager* 00114 getCollectionManager() const = 0; 00115 00116 /** \brief Returns a CollectionManager responsible for collections 00117 * identified by a URI. 00118 * 00119 * The collection manager provides a set of functions for managing 00120 * collections identified by a URI and their contents. 00121 * 00122 * Please note that the resulting manager is only responsible for 00123 * dynamic collections identified by a URI, i.e. those that are 00124 * not declared in the prolog of a module or identified by a QName. 00125 * 00126 * @return The collection manager responsible for managing 00127 * collections. 00128 * 00129 */ 00130 virtual CollectionManager* 00131 getW3CCollectionManager() const = 0; 00132 00133 /** \brief Parse an XML document and return an Item. 00134 * 00135 */ 00136 virtual Item 00137 parseXML(std::istream& aStream) const = 0; 00138 00139 /** \brief Parse an XML document and return an Item. 00140 * 00141 * @param aStream the input stream whose content should be parsed 00142 * @param aBaseURI the base URI which will be used as the base URI 00143 * of the document. This serves both as the base URI 00144 * used by the XML parser to resolve relative entity 00145 * references within the document, and as the base URI 00146 * of the document node that is returned. 00147 */ 00148 virtual Item 00149 parseXML(std::istream& aStream, const String& aBaseURI) const = 0; 00150 00151 /** \brief Parse an XML document and return a sequence of nodes. 00152 * 00153 * This function parses the given input stream and returns the result 00154 * as a sequence of nodes. If external entity processing is disabled 00155 * the result will be a singleton sequence consisting of one document 00156 * node. Otherwise, the result is the sequence of the external entity 00157 * nodes. 00158 * 00159 * @param aStream the input stream whose content should be parsed 00160 * @param aOptions @see ParseOptions 00161 * @see ParseOptions 00162 */ 00163 virtual ItemSequence_t 00164 parseXML(std::istream& aStream, ParseOptions& aOptions) const = 0; 00165 00166 /** \brief Parse an XML document and return a sequence of nodes. 00167 * 00168 * This function parses the given input stream and returns the result 00169 * as a sequence of nodes. If external entity processing is disabled 00170 * the result will be a singleton sequence consisting of one document 00171 * node. Otherwise, the result is the sequence of the external entity 00172 * nodes. 00173 * 00174 * @param aStream the input stream whose content should be parsed 00175 * @param aBaseURI the base URI which will be used as the base URI 00176 * of the document. This serves both as the base URI 00177 * used by the XML parser to resolve relative entity 00178 * references within the document, and as the base URI 00179 * of the document node that is returned. 00180 * @param aOptions @see ParseOptions 00181 * @see ParseOptions 00182 */ 00183 virtual ItemSequence_t 00184 parseXML( 00185 std::istream& aStream, 00186 const String& aBaseURI, 00187 ParseOptions& aOptions) const = 0; 00188 00189 /** \brief Fetches an resource refered to by the given URI. 00190 */ 00191 virtual Item 00192 fetch(const String& aURI) const = 0; 00193 00194 /** \brief Register a DiagnosticHandler to which errors occuring during the 00195 * management of documents and collections are reported. 00196 * 00197 * If no DiagnosticHandler has been set using this function then 00198 * subclasses of the ZorbaException class are thrown to report 00199 * errors. 00200 * 00201 * @param aDiagnosticHandler DiagnosticHandler to which errors 00202 * are reported. The caller retains ownership over the 00203 * DiagnosticHandler passed as parameter. 00204 */ 00205 virtual void 00206 registerDiagnosticHandler(DiagnosticHandler* aDiagnosticHandler) = 0; 00207 00208 #ifndef ZORBA_NO_FULL_TEXT 00209 /** 00210 * Registers a StemmerProvider to use for stemming of text content in order 00211 * to perform queries involving full-text. 00212 * 00213 * If no StemmerProvider has been set using this function, then the default 00214 * StemmerProvider will be used. 00215 * 00216 * @param provider If not NULL, sets the StemmerProvider to use; if NULL, 00217 * removes any previously registered StemmerProvider. 00218 */ 00219 virtual void 00220 registerStemmerProvider(StemmerProvider const *provider) = 0; 00221 00222 /** 00223 * Registers a TokenizerProvider to use for toknenization of text content 00224 * in order to perform queries involving full-text. 00225 * 00226 * If no TokenizerProvider has been set using this function, then the 00227 * default TokenizerProvider will be used. 00228 * 00229 * @param provider If not NULL, sets the TokenizerProvider to use; if NULL, 00230 * removes any previously registered TokenizerProvider. 00231 */ 00232 virtual void 00233 registerTokenizerProvider(TokenizerProvider const *provider) = 0; 00234 #endif /* ZORBA_NO_FULL_TEXT */ 00235 00236 protected: 00237 /** \brief Destructor 00238 */ 00239 virtual ~XmlDataManager() {} 00240 00241 }; /* class XmlDataManager */ 00242 00243 } // namespace zorba 00244 #endif /* ZORBA_XMLDATAMANAGER_API_H */ 00245 /* vim:set et sw=2 ts=2: */