Markos Zaharioudakis has proposed merging lp:~zorba-coders/zorba/markos-scratch 
into lp:zorba.

Commit message:
added/clened-up comments

Requested reviews:
  Markos Zaharioudakis (markos-za)

For more details, see:
https://code.launchpad.net/~zorba-coders/zorba/markos-scratch/+merge/178030

added/clened-up comments
-- 
https://code.launchpad.net/~zorba-coders/zorba/markos-scratch/+merge/178030
Your team Zorba Coders is subscribed to branch lp:zorba.
=== modified file 'include/zorba/document_manager.h'
--- include/zorba/document_manager.h	2013-02-07 17:24:36 +0000
+++ include/zorba/document_manager.h	2013-08-01 09:54:32 +0000
@@ -21,30 +21,62 @@
 
 namespace zorba {
 
-  /** \brief 
-   *
-   */
-  class ZORBA_DLL_PUBLIC DocumentManager
-  {
-  public:
-    virtual void
-    put(const String& aURI, const Item& aDoc) = 0;
-
-    virtual void
-    remove(const String& aURI) = 0;
-
-    virtual Item
-    document(const String& aURI) const = 0;
-
-    virtual ItemSequence_t
-    availableDocuments() const = 0;
-
-    virtual bool
-    isAvailableDocument(const String& aURI) const = 0;
-
-    virtual ~DocumentManager() {}
-
-  }; /* class DocumentManager */
+/**
+ * \brief There is a single instance of DocumentManager, which provides methods
+ * for adding, removing, or accessing XML documents in the Zorba store. This single
+ * instance is accessible via the XmlDataManger::getDocumentManager() method.
+ */
+class ZORBA_DLL_PUBLIC DocumentManager
+{
+public:
+  virtual ~DocumentManager() {}
+
+  /**
+   * Add a document to the store, associating it with the given URI.
+   *
+   * This method adds the document to the "available documents" component of
+   * the dynamic context. This means that the document will remain in the
+   * store and be accessible to queries via the associated URI (e.g., by using
+   * the fn:doc() function) until it is explicitly removed via the
+   * DocumentManager::remove() method.
+   */
+  virtual void
+  put(const String& aURI, const Item& aDoc) = 0;
+
+  /**
+   * Remove the document with the given URI from the store.
+   *
+   * This method removes the document from the "available documents" component
+   * of the dynamic context. This means that the document will no longer be
+   * accessible to queries via the associated URI. However, the document is not
+   * necessarily destroyed by this method. It will be destroyed if/when no more
+   * references to it exist.
+   */
+  virtual void
+  remove(const String& aURI) = 0;
+
+  /**
+   * Return a reference to the root node of the document with the given URI.
+   */
+  virtual Item
+  document(const String& aURI) const = 0;
+
+  /**
+   * Returns an iterator over the root nodes of all the available documents
+   * (i.e., all the documents that have been added to the store via the
+   * DocumentManager::put() method).
+   */
+  virtual Iterator_t
+  availableDocuments() const = 0;
+  
+  /**
+   * Check if a document with a given URI is among the available documents
+   * (i.e., the documents that have been added to the store via the
+   * DocumentManager::put() method).
+   */
+  virtual bool
+  isAvailableDocument(const String& aURI) const = 0;
+};
 
 } /* namespace zorba */
 #endif

=== modified file 'include/zorba/empty_sequence.h'
--- include/zorba/empty_sequence.h	2013-02-07 17:24:36 +0000
+++ include/zorba/empty_sequence.h	2013-08-01 09:54:32 +0000
@@ -13,8 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-#ifndef ZORBA_EMPTY_SEQUENCE_API_H
-#define ZORBA_EMPTY_SEQUENCE_API_H
+#ifndef ZORBA_EMPTY_ITEM_SEQUENCE_API_H
+#define ZORBA_EMPTY_ITEM_SEQUENCE_API_H
 
 #include <zorba/config.h>
 #include <zorba/item_sequence.h>
@@ -23,62 +23,47 @@
 
 namespace zorba { 
 
-  /** \brief This class is an implementation of the ItemSequence.
-   *         Objects of this class return, on the first next call,
-   *         an empty sequence.
+/**
+ * \brief This class is an implementation of the ItemSequence.
+ *        Objects of this class represent the empty sequence.
+ *
+ * See ItemSequence
+ */
+class ZORBA_DLL_PUBLIC EmptySequence : public ItemSequence
+{
+  /**
+   * \brief Implements an iterator over the empty sequence.
+   * Assuming that the iterator is in the open state, its next() method will
+   * always return false.
    *
-   * See ItemSequence
+   * See Iterator.
    */
-  class ZORBA_DLL_PUBLIC EmptySequence : public ItemSequence
+  class InternalIterator : public Iterator
   {
-    class InternalIterator : public Iterator
-    {
-    private:
-      ItemSequence    *theItemSequence;
-      bool is_open;
-    public:
-      InternalIterator(ItemSequence *item_sequence);
-
-      /** \brief Start iterating.
-       *
-       * This function needs to be called before calling next().
-       *
-       */
-      virtual void open();
-      /** \brief Get the next Item of the sequence.
-       *
-       * This function returns false with no item.
-       * @param aItem not used
-       * @return false always
-       * @throw ZorbaException if iterator is not open.
-       *
-       */
-      virtual bool next(Item& aItem);
-      /** \brief Stop iterating.
-       *
-       *  Not mandatory.
-       */
-      virtual void close();
-      /**
-       * brief Check whether the iterator is open or not
-       */
-      virtual bool isOpen() const;
-    };
-    public:
-      /** \brief Constructor
-       */
-      EmptySequence() { }
-
-      /** \brief Destructor
-       */
-      virtual ~EmptySequence() { }
-
-      /** \brief get the void Iterator
-       * @return a void iterator
-      */
-      virtual Iterator_t  getIterator();
-
-  }; /* class EmptySequence */
+  private:
+    ItemSequence  * theItemSequence;
+    bool            theIsOpen;
+
+  public:
+    InternalIterator(ItemSequence* seq);
+
+    virtual void open();
+
+    virtual bool next(Item& aItem);
+
+    virtual void close();
+
+    virtual bool isOpen() const;
+  };
+
+ public:
+  EmptySequence() { }
+
+  virtual ~EmptySequence() { }
+  
+  virtual Iterator_t getIterator();
+  
+}; /* class EmptySequence */
 
 } // namespace zorba
 

=== modified file 'include/zorba/item_sequence.h'
--- include/zorba/item_sequence.h	2013-02-07 17:24:36 +0000
+++ include/zorba/item_sequence.h	2013-08-01 09:54:32 +0000
@@ -19,32 +19,33 @@
 #include <zorba/config.h>
 #include <zorba/api_shared_types.h>
 
-namespace zorba { 
-
-  /** 
-   * \brief This interface represents an instance of the XQuery 1.0 and XPath 2.0
-   * Data Model (XDM).
+namespace zorba
+{ 
+
+/** 
+ * \brief ItemSequence represents an ordered sequence of items. The sequence
+ * may contain any mix of atomic items, function items, nodes, JSON objects,
+ * or JSON arrays.
+ */
+class ZORBA_DLL_PUBLIC ItemSequence : virtual public SmartObject
+{
+ public:
+  /**
+   * \brief Destructor
+   */
+  virtual ~ItemSequence() { }
+
+  /**
+   * \brief Create an iterator over the items of this sequence. The life time
+   * of the iterator shouldnot exceed the life time of this item sequence.
    *
-   * See http://www.w3.org/TR/xpath-datamodel/.
+   * @return an iterator over the items
+   * @throw Throws zerr::ZAPI0039 if the implementation of the associated
+   *        ItemSequence does not allow more than one iterator to be created. 
    */
-  class ZORBA_DLL_PUBLIC ItemSequence : virtual public SmartObject
-  {
-    public:
-      /**
-       * \brief Destructor
-       */
-      virtual ~ItemSequence() { }
-
-      /**
-       * \brief get the Iterator over the items
-       *
-       * @return an iterator over the items
-       * @throw Throws zerr::ZAPI0039 if the implementation of the associated
-       *        ItemSequence does not allow more than one iterator to be created. 
-      */
-      virtual Iterator_t  getIterator() = 0;
-
-  }; /* class ItemSequence */
+  virtual Iterator_t getIterator() = 0;
+
+}; /* class ItemSequence */
 
 } // namespace zorba
 #endif

=== modified file 'include/zorba/iterator.h'
--- include/zorba/iterator.h	2013-02-07 17:24:36 +0000
+++ include/zorba/iterator.h	2013-08-01 09:54:32 +0000
@@ -22,21 +22,14 @@
 
 namespace zorba {
 
-/** \brief Interface for an Iterator over an instance of the XML Data Model
- *  (i.e., a sequence of items).
+/**
+ * \brief Interface for an Iterator over a sequence of items.
  *
  * An iterator can be in one of the following two states: open or not-open.
  * When in open state, only methods isOpen(), next() and close() may be called.
- * When in not-open state, only isOpen and open() may be called. The open()
+ * When in not-open state, only isOpen() and open() may be called. The open()
  * method changes the state from non-open to open, and the close() method
  * changes the state from open to not-open.
- *
- * Iterator is not a thread-safe class, i.e., none of its methods should ever
- * be called by two or more threads in parallel.
- *
- * Note: This class is reference counted. When writing multi-threaded clients,
- * it is the responibility of the client code to synchronize assignments to the
- * SmartPtr holding this object.
  */
 class ZORBA_DLL_PUBLIC Iterator : virtual public SmartObject
 {
@@ -59,8 +52,8 @@
 
   /** \brief Get the next Item of the sequence.
    *
-   * @param  aItem the next Item of the result sequence, if true is returned
-   *         by the function.
+   * @param  aItem the next Item of the sequence, unless all the items of the
+   *         sequence have been returned already by previous invocations of next().
    * @return false if all the items of the sequence have been returned already
    *         by previous invocations of next(); true otherwise.
    * @throw  ZorbaException if an error occurs, or the Iterator has not been opened.

=== modified file 'include/zorba/singleton_item_sequence.h'
--- include/zorba/singleton_item_sequence.h	2013-02-07 17:24:36 +0000
+++ include/zorba/singleton_item_sequence.h	2013-08-01 09:54:32 +0000
@@ -23,70 +23,52 @@
 
 namespace zorba { 
 
-  /** \brief A sequence that contains only one item.
-   *
-   * This class is an implementation of the ItemSequence. Objects of this class
-   * are backed by an iterator that returns on the first next call, the Item
-   * that is passed to this class' constructor.
-   *
-   * See ItemSequence
+/**
+ * \brief This class is an implementation of ItemSequence. Objects of this
+ * class represent a sequence with exactly one item.
+ *
+ * See ItemSequence
+ */
+class ZORBA_DLL_PUBLIC SingletonItemSequence : public ItemSequence
+{
+  /**
+   * \brief Implements an iterator over the sequence.
+   *
+   * See Iterator.
    */
-  class ZORBA_DLL_PUBLIC SingletonItemSequence : public ItemSequence
+  class InternalIterator : public Iterator
   {
-    class InternalIterator : public Iterator
-    {
-    private:
-      SingletonItemSequence   *theItemSequence;
-      bool is_open;
-      bool theDone;
-    public:
-      InternalIterator(SingletonItemSequence *item_sequence);
-
-      /** \brief Start iterating.
-       *
-       * This function needs to be called before calling next().
-       *
-       */
-      virtual void open();
-      /** \brief Get the one Item.
-       *
-       * @param aItem the Item if true is returned by the function.
-       * @return true if the sequence is not exhausted, false otherwise.
-       * @throw ZorbaException if iterator is not open or an error occured.
-       */
-      virtual bool next(Item& aItem);
-      /** \brief Close the iterator.
-       *
-       * You can call close and open to reset the iterator.
-       *
-       */
-      virtual void close();
-      /**
-       * brief Check whether the iterator is open or not
-       */
-      virtual bool isOpen() const;
-    };
-    public:
-      /** \brief Constructor
-       * 
-       * @param aItem the single item in this sequence
-       */
-      SingletonItemSequence(const Item& aItem);
-
-      /** \brief Destructor
-       */
-      virtual ~SingletonItemSequence() { }
-
-      /** \brief get the Iterator over the single item
-       * @return an iterator over the one item
-      */
-      virtual Iterator_t    getIterator();
-
-    protected:
-
-      Item theItem;
-
-  }; /* class SingletonItemSequence */
+  private:
+    SingletonItemSequence  * theItemSequence;
+    bool                     theIsOpen;
+    bool                     theIsDone;
+
+  public:
+    InternalIterator(SingletonItemSequence* seq);
+    
+    virtual void open();
+ 
+    virtual bool next(Item& aItem);
+
+    virtual void close();
+
+    virtual bool isOpen() const;
+  };
+
+ protected:
+  Item theItem;
+
+ public:
+  /**
+   * @param aItem the single item of the sequence
+   */
+  SingletonItemSequence(const Item& aItem);
+
+  virtual ~SingletonItemSequence() { }
+
+  virtual Iterator_t getIterator();
+
+}; /* class SingletonItemSequence */
 
 } // namespace zorba
 

=== modified file 'include/zorba/vector_item_sequence.h'
--- include/zorba/vector_item_sequence.h	2013-02-07 17:24:36 +0000
+++ include/zorba/vector_item_sequence.h	2013-08-01 09:54:32 +0000
@@ -25,70 +25,54 @@
 
 namespace zorba { 
 
-  /** \brief This class is an implementation of the ItemSequence.
-   *         Objects of this class return, on each next call, an
-   *         Item of the vector that is passed to this object.
+/**
+ * \brief This class is an implementation of ItemSequence. Objects of this
+ * class store the items of the sequence in a vector.
+ *
+ * See ItemSequence
+ */
+class ZORBA_DLL_PUBLIC VectorItemSequence : public ItemSequence
+{
+  /**
+   * \brief Implements an iterator over the sequence.
    *
-   * See ItemSequence
+   * See Iterator.
    */
-  class ZORBA_DLL_PUBLIC VectorItemSequence : public ItemSequence
+  class InternalIterator : public Iterator
   {
-    class InternalIterator : public Iterator
-    {
-    private:
-      VectorItemSequence   *theItemSequence;
-      std::vector<Item>::iterator theIterator;
-      std::vector<Item>::iterator theEnd;
-      bool is_open;
-    public:
-      InternalIterator(VectorItemSequence *item_sequence);
-
-      /** \brief Start iterating.
-       *
-       * This function needs to be called before calling next().
-       * Initializes the iterator over the items vector.
-       *
-       */
-      virtual void open();
-      /** \brief Get the next Item of the vector of items from ItemSequence.
-       *
-       * @param aItem the next Item of the sequence if true is returned by the function.
-       * @return true if the vector is not exhausted, false otherwise.
-       * @throw ZorbaException if iterator is not open or an error occured.
-       */
-      virtual bool next(Item& aItem);
-      /** \brief Close the iterator.
-       *
-       * You can call close and open to reset the iterator.
-       *
-       */
-      virtual void close();
-      /**
-       * brief Check whether the iterator is open or not
-       */
-      virtual bool isOpen() const;
-    };
-    public:
-      /** \brief Constructor
-       * 
-       * @param aSequence the vector containing the sequence of Items
-       */
-      VectorItemSequence(const std::vector<Item>& aSequence);
-
-      /** \brief Destructor
-       */
-      virtual ~VectorItemSequence() { }
-
-      /** \brief get the Iterator over the items vector
-       * @return an iterator over the items
-      */
-      virtual Iterator_t  getIterator();
-
-    protected:
-      std::vector<Item> theSequence;
-
-  }; /* class VectorItemSequence */
-
+  private:
+    VectorItemSequence          * theItemSequence;
+    std::vector<Item>::iterator   theIterator;
+    std::vector<Item>::iterator   theEnd;
+    bool                          theIsOpen;
+
+  public:
+    InternalIterator(VectorItemSequence* seq);
+    
+    virtual void open();
+
+    virtual bool next(Item& aItem);
+
+    virtual void close();
+
+    virtual bool isOpen() const;
+  };
+
+ protected:
+  std::vector<Item> theSequence;
+
+ public:
+  /**
+   * @param aSequence the vector containing the items of the sequence
+   */
+  VectorItemSequence(const std::vector<Item>& aSequence);
+  
+  virtual ~VectorItemSequence() { }
+  
+  virtual Iterator_t getIterator();
+  
+}; /* class VectorItemSequence */
+  
 } // namespace zorba
 #endif
 

=== modified file 'include/zorba/xmldatamanager.h'
--- include/zorba/xmldatamanager.h	2013-02-07 17:24:36 +0000
+++ include/zorba/xmldatamanager.h	2013-08-01 09:54:32 +0000
@@ -23,224 +23,224 @@
 
 namespace zorba {
 
-  /** \brief Using the XmlDataManager one can manage documents and collections.
-   *
-   * The XmlDataManager is a singleton instance. The Zorba object is reponsible
-   * for maintaining its lifetime. The instance can be accessed by calling
-   * getXmlDataManager() on the Zorba object. It may not be accessed anymore
-   * after Zorba::shutdown() has been called.
-   *
-   * XmlDataManager is a thread-safe class.
+/**
+ * \brief Using the XmlDataManager one can manage documents and collections.
+ *
+ * The XmlDataManager is a singleton instance. The Zorba object is reponsible
+ * for maintaining its lifetime. The instance can be accessed by calling
+ * getXmlDataManager() on the Zorba object. It may not be accessed anymore
+ * after Zorba::shutdown() has been called.
+ */
+class ZORBA_DLL_PUBLIC XmlDataManager
+{
+ public:
+  /**
+   * \brief The ParseOptions class stores various properties that affect
+   *        how a document is parsed. An instance of this class is passed
+   *        as input to the parseXML function.
    */
-  class ZORBA_DLL_PUBLIC XmlDataManager
+  class ParseOptions
   {
+  private:
+    bool              theDtdValidation;
+    bool              theExternalEntityProcessing;
+
   public:
-    /**
-     * \brief The ParseOptions class stores various properties that affect
-     *        how a document is parsed. An instance of this class is passed
-     *        as input to the parseXML function.
-     */
-    class ParseOptions
-    {
-    private:
-      bool              theDtdValidation;
-      bool              theExternalEntityProcessing;
-
-    public:
-      ParseOptions() :
-        theDtdValidation(false),
-        theExternalEntityProcessing(false)
-      {}
-
-      ~ParseOptions() {}
-
-      /**
-       * Set the property enableDtd, which specifies whether the
-       * document should be validated against its associated DTD (if
-       * any).
-       */
-      void setDtdValidation(bool aEnable)
-      {
-        theDtdValidation = aEnable;
-      }
-
-      /**
-       * Returns true if dtd validation is enabled, false otherwise.
-       */
-      bool isDtdValidationEnabled() const
-      {
-        return theDtdValidation;
-      }
-
-      /**
-       * Set the property to enable or disable processing of XML external entities. 
-       * If the option is enabled, the input must conform to the syntax
-       * _extParsedEnt_ (production [78] in XML 1.0); and since there is no DTD,
-       * the content must include no entity references. The result of the
-       * function call is a sequence of nodes.
-       */
-      void setExternalEntityProcessing(bool aEnable)
-      {
-        theExternalEntityProcessing = aEnable;
-      }
-
-      /**
-       * Returns true if external entity processig is enabled,
-       * false otherwise.
-       */
-      bool isExternalEntityProcessingEnabled() const
-      {
-        return theExternalEntityProcessing;
-      }
-    };
-
-    virtual DocumentManager*
-    getDocumentManager() const = 0;
-
-    /** \brief Returns a CollectionManager responsible for all collections.
-     * 
-     * The collection manager provides a set of functions for managing
-     * collections identified by a QName and their contents.
-     *
-     * Please note that the resulting manager is only responsible for
-     * dynamic collections identified by a QName, i.e. those that are
-     * not declared in the prolog of a module or identified by a URI.
-     *
-     * @return The collection manager responsible for managing
-     *   collections.
-     *
-     */
-    virtual CollectionManager*
-    getCollectionManager() const = 0;
-
-    /** \brief Returns a CollectionManager responsible for collections
-     * identified by a URI.
-     * 
-     * The collection manager provides a set of functions for managing
-     * collections identified by a URI and their contents.
-     *
-     * Please note that the resulting manager is only responsible for
-     * dynamic collections identified by a URI, i.e. those that are
-     * not declared in the prolog of a module or identified by a QName.
-     *
-     * @return The collection manager responsible for managing
-     *   collections.
-     *
-     */
-    virtual CollectionManager*
-    getW3CCollectionManager() const = 0;
-
-    /** \brief Parse an XML document and return an Item.
-     *
-     */
-    virtual Item
-    parseXML(std::istream& aStream) const = 0;
-
-    /** \brief Parse an XML document and return an Item.
-     *
-     * @param aStream the input stream whose content should be parsed
-     * @param aBaseURI the base URI which will be used as the base URI
-     *                 of the document. This serves both as the base URI
-     *                 used by the XML parser to resolve relative entity
-     *                 references within the document, and as the base URI
-     *                 of the document node that is returned.
-     */
-    virtual Item
-    parseXML(std::istream& aStream, const String& aBaseURI) const = 0;
-
-    /** \brief Parse an XML document and return a sequence of nodes.
-     *
-     * This function parses the given input stream and returns the result
-     * as a sequence of nodes. If external entity processing is disabled
-     * the result will be a singleton sequence consisting of one document
-     * node. Otherwise, the result is the sequence of the external entity
-     * nodes.
-     *
-     * @param aStream the input stream whose content should be parsed
-     * @param aOptions @see ParseOptions
-     * @see ParseOptions
-     */
-    virtual ItemSequence_t
-    parseXML(std::istream& aStream, ParseOptions& aOptions) const = 0;
-
-    /** \brief Parse an XML document and return a sequence of nodes.
-     *
-     * This function parses the given input stream and returns the result
-     * as a sequence of nodes. If external entity processing is disabled
-     * the result will be a singleton sequence consisting of one document
-     * node. Otherwise, the result is the sequence of the external entity
-     * nodes.
-     *
-     * @param aStream the input stream whose content should be parsed
-     * @param aBaseURI the base URI which will be used as the base URI
-     *                 of the document. This serves both as the base URI
-     *                 used by the XML parser to resolve relative entity
-     *                 references within the document, and as the base URI
-     *                 of the document node that is returned.
-     * @param aOptions @see ParseOptions
-     * @see ParseOptions
-     */
-    virtual ItemSequence_t
-    parseXML(
-        std::istream& aStream,
-        const String& aBaseURI,
-        ParseOptions& aOptions) const = 0;
-
-    /** \brief Fetches an resource refered to by the given URI.
-     *
-     * @deprecated this function has been replaced by StaticContext::fetch.
-     */
-    virtual Item
-    fetch(const String& aURI) const = 0;
-
-    /** \brief Register a DiagnosticHandler to which errors occuring during the
-     * management of documents and collections are reported.
-     *
-     * If no DiagnosticHandler has been set using this function then
-     * subclasses of the ZorbaException class are thrown to report
-     * errors.
-     *
-     *  @param aDiagnosticHandler DiagnosticHandler to which errors
-     *         are reported. The caller retains ownership over the
-     *         DiagnosticHandler passed as parameter.
-     */
-    virtual void
-    registerDiagnosticHandler(DiagnosticHandler* aDiagnosticHandler) = 0;
+    ParseOptions() :
+      theDtdValidation(false),
+      theExternalEntityProcessing(false)
+    {}
+
+    ~ParseOptions() {}
+
+    /**
+     * Set the property enableDtd, which specifies whether the
+     * document should be validated against its associated DTD (if
+     * any).
+     */
+    void setDtdValidation(bool aEnable)
+    {
+      theDtdValidation = aEnable;
+    }
+    
+    /**
+     * Returns true if dtd validation is enabled, false otherwise.
+     */
+    bool isDtdValidationEnabled() const
+    {
+      return theDtdValidation;
+    }
+    
+    /**
+     * Set the property to enable or disable processing of XML external entities. 
+     * If the option is enabled, the input must conform to the syntax
+     * _extParsedEnt_ (production [78] in XML 1.0); and since there is no DTD,
+     * the content must include no entity references. The result of the
+     * function call is a sequence of nodes.
+     */
+    void setExternalEntityProcessing(bool aEnable)
+    {
+      theExternalEntityProcessing = aEnable;
+    }
+    
+    /**
+     * Returns true if external entity processig is enabled,
+     * false otherwise.
+     */
+    bool isExternalEntityProcessingEnabled() const
+    {
+      return theExternalEntityProcessing;
+    }
+  };
+
+  /**
+   * \brief Returns a DocumentManager responsible for managing XML documents
+   */
+  virtual DocumentManager*
+  getDocumentManager() const = 0;
+
+  /**
+   * \brief Returns a CollectionManager responsible for all collections.
+   * 
+   * The collection manager provides a set of functions for managing
+   * collections identified by a QName and their contents.
+   *
+   * Please note that the resulting manager is only responsible for
+   * dynamic collections identified by a QName, i.e. those that are
+   * not declared in the prolog of a module or identified by a URI.
+   *
+   * @return The collection manager responsible for managing collections.
+   */
+  virtual CollectionManager*
+  getCollectionManager() const = 0;
+
+  /**
+   * \brief Returns a CollectionManager responsible for collections
+   * identified by a URI.
+   * 
+   * The collection manager provides a set of functions for managing
+   * collections identified by a URI and their contents.
+   *
+   * Please note that the resulting manager is only responsible for
+   * dynamic collections identified by a URI, i.e. those that are
+   * not declared in the prolog of a module or identified by a QName.
+   *
+   * @return The collection manager responsible for managing collections.
+   */
+  virtual CollectionManager*
+  getW3CCollectionManager() const = 0;
+  
+  /**
+   * \brief Parse an XML document and return an Item.
+   */
+  virtual Item
+  parseXML(std::istream& aStream) const = 0;
+
+  /** \brief Parse an XML document and return an Item.
+   *
+   * @param aStream the input stream whose content should be parsed
+   * @param aBaseURI the base URI which will be used as the base URI
+   *                 of the document. This serves both as the base URI
+   *                 used by the XML parser to resolve relative entity
+   *                 references within the document, and as the base URI
+   *                 of the document node that is returned.
+   */
+  virtual Item
+  parseXML(std::istream& aStream, const String& aBaseURI) const = 0;
+  
+  /** \brief Parse an XML document and return a sequence of nodes.
+   *
+   * This function parses the given input stream and returns the result
+   * as a sequence of nodes. If external entity processing is disabled
+   * the result will be a singleton sequence consisting of one document
+   * node. Otherwise, the result is the sequence of the external entity
+   * nodes.
+   *
+   * @param aStream the input stream whose content should be parsed
+   * @param aOptions @see ParseOptions
+   * @see ParseOptions
+   */
+  virtual ItemSequence_t
+  parseXML(std::istream& aStream, ParseOptions& aOptions) const = 0;
+
+  /** \brief Parse an XML document and return a sequence of nodes.
+   *
+   * This function parses the given input stream and returns the result
+   * as a sequence of nodes. If external entity processing is disabled
+   * the result will be a singleton sequence consisting of one document
+   * node. Otherwise, the result is the sequence of the external entity
+   * nodes.
+   *
+   * @param aStream the input stream whose content should be parsed
+   * @param aBaseURI the base URI which will be used as the base URI
+   *                 of the document. This serves both as the base URI
+   *                 used by the XML parser to resolve relative entity
+   *                 references within the document, and as the base URI
+   *                 of the document node that is returned.
+   * @param aOptions @see ParseOptions
+   * @see ParseOptions
+   */
+  virtual ItemSequence_t
+  parseXML(
+      std::istream& aStream,
+      const String& aBaseURI,
+      ParseOptions& aOptions) const = 0;
+
+  /** \brief Fetches an resource refered to by the given URI.
+   *
+   * @deprecated this function has been replaced by StaticContext::fetch.
+   */
+  virtual Item
+  fetch(const String& aURI) const = 0;
+
+  /** \brief Register a DiagnosticHandler to which errors occuring during the
+   * management of documents and collections are reported.
+   *
+   * If no DiagnosticHandler has been set using this function then
+   * subclasses of the ZorbaException class are thrown to report
+   * errors.
+   *
+   *  @param aDiagnosticHandler DiagnosticHandler to which errors
+   *         are reported. The caller retains ownership over the
+   *         DiagnosticHandler passed as parameter.
+   */
+  virtual void
+  registerDiagnosticHandler(DiagnosticHandler* aDiagnosticHandler) = 0;
 
 #ifndef ZORBA_NO_FULL_TEXT
-    /**
-     * Registers a StemmerProvider to use for stemming of text content in order
-     * to perform queries involving full-text.
-     *
-     * If no StemmerProvider has been set using this function, then the default
-     * StemmerProvider will be used.
-     *
-     * @param provider If not NULL, sets the StemmerProvider to use; if NULL,
-     * removes any previously registered StemmerProvider.
-     */
-    virtual void
-    registerStemmerProvider(StemmerProvider const *provider) = 0;
-
-    /**
-     * Registers a TokenizerProvider to use for toknenization of text content
-     * in order to perform queries involving full-text.
-     *
-     * If no TokenizerProvider has been set using this function, then the
-     * default TokenizerProvider will be used.
-     *
-     * @param provider If not NULL, sets the TokenizerProvider to use; if NULL,
-     * removes any previously registered TokenizerProvider.
-     */
-    virtual void
-    registerTokenizerProvider(TokenizerProvider const *provider) = 0;
+  /**
+   * Registers a StemmerProvider to use for stemming of text content in order
+   * to perform queries involving full-text.
+   *
+   * If no StemmerProvider has been set using this function, then the default
+   * StemmerProvider will be used.
+   *
+   * @param provider If not NULL, sets the StemmerProvider to use; if NULL,
+   * removes any previously registered StemmerProvider.
+   */
+  virtual void
+  registerStemmerProvider(StemmerProvider const *provider) = 0;
+  
+  /**
+   * Registers a TokenizerProvider to use for toknenization of text content
+   * in order to perform queries involving full-text.
+   *
+   * If no TokenizerProvider has been set using this function, then the
+   * default TokenizerProvider will be used.
+   *
+   * @param provider If not NULL, sets the TokenizerProvider to use; if NULL,
+   * removes any previously registered TokenizerProvider.
+   */
+  virtual void
+  registerTokenizerProvider(TokenizerProvider const *provider) = 0;
 #endif /* ZORBA_NO_FULL_TEXT */
 
-    protected:
-    /** \brief Destructor
-     */
-    virtual ~XmlDataManager() {}
-
-  }; /* class XmlDataManager */
+ protected:
+  /** \brief Destructor
+   */
+  virtual ~XmlDataManager() {}
+  
+}; /* class XmlDataManager */
 
 } // namespace zorba
 #endif /* ZORBA_XMLDATAMANAGER_API_H */

=== modified file 'include/zorba/zorba.h'
--- include/zorba/zorba.h	2013-02-07 17:24:36 +0000
+++ include/zorba/zorba.h	2013-08-01 09:54:32 +0000
@@ -285,22 +285,13 @@
 
   /** \brief Creates a new StaticContext.
    *
-   * The method returns a StaticContext object that can be used
-   * for compiling a query. Instances of the StaticContext class are
-   * returned as a smart pointer.
-   * That is, objects of type StaticContext_t are reference counted object
-   * to an dynamically allocated StaticContext object. Hence, each object can h
-   * have multiple owners. The object is deleted if nobody holds on to an StaticContext_t
-   * object anymore.
-   *
-   * Optionally, this method takes an DiagnosticHandler as parameter. In the case
-   * an DiagnosticHandler is passed as parameter, each error that occurs during
-   * setting or getting information out of the StaticContext, is reported to the passed
-   * DiagnosticHandler.
-   * If not DiagnosticHandler is given, exceptions are thrown for each of these errors.
-   *
-   * @param aDiagnosticHandler the DiagnosticHandler to which errors should be reported.
-   * @return StaticContext_t a new StaticContext object.
+   * The method returns a smart pointer to a new StaticContext object that can
+   * be used for compiling a query.
+   *
+   * @param aDiagnosticHandler the DiagnosticHandler to which errors should be
+   *        reported. If not DiagnosticHandler is given, exceptions are thrown
+   *        for each of these errors.
+   * @return StaticContext_t a smart pointer to a new StaticContext object.
    */
   virtual StaticContext_t
   createStaticContext(DiagnosticHandler* aDiagnosticHandler = 0) = 0;

-- 
Mailing list: https://launchpad.net/~zorba-coders
Post to     : zorba-coders@lists.launchpad.net
Unsubscribe : https://launchpad.net/~zorba-coders
More help   : https://help.launchpad.net/ListHelp

Reply via email to