xmldatamanager.h
Go to the documentation of this file.
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: */
blog comments powered by Disqus