collection.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_COLLECTION_API_H
00017 #define ZORBA_COLLECTION_API_H
00018 
00019 #include <zorba/config.h>
00020 #include <zorba/api_shared_types.h>
00021 #include <zorba/item.h>
00022 #include <vector>
00023 
00024 namespace zorba {
00025 
00026 /** \brief A Collection is a persistent sequence of node items.
00027  *
00028  * Instances of this class can be used to modify or retrieve the contents
00029  * of a collection.
00030  *
00031  * The variable aNodes passed to any of the insert functions is evaluated
00032  * as though it were an enclosed expression in an element constructor.
00033  * The result of this step is a sequence of nodes to be inserted into the collection.
00034  *
00035  * Note: This class is reference counted. When writing multi-threaded clients,
00036  * it is the responibility of the client code to synchronize assignments to the
00037  * SmartPtr holding this object.
00038  */
00039 class ZORBA_DLL_PUBLIC Collection : public SmartObject
00040 {
00041  public:
00042   /**
00043    * \brief Get the name of the collection.
00044    *
00045    * @return The name of the collection.
00046    */
00047   virtual const Item
00048   getName() const = 0;
00049 
00050   /**
00051    * This function inserts copies of the
00052    * given nodes at the beginning of the collection.
00053    *
00054    * @param aNodes The sequences of nodes whose copies
00055    *        should be added to the collection.
00056    *
00057    */
00058   virtual void
00059   insertNodesFirst(const ItemSequence_t& aNodes) = 0;
00060   
00061   /**
00062    * This function inserts copies of the
00063    * given nodes at the end of the collection.
00064    *
00065    * @param aNodes The sequences of nodes whose copies
00066    *        should be added to the collection.
00067    *
00068    */
00069   virtual void
00070   insertNodesLast(const ItemSequence_t& aNodes) = 0;
00071   
00072   /**
00073    * This function inserts copies of the given
00074    * nodes into a collection at the position directly preceding the
00075    * given target node.
00076    *
00077    * @param aTarget the node in the collection before which the
00078    *        sequence should be inserted.
00079    * @param aNodes The sequences of nodes whose copies should
00080    *        be added to the collection.
00081    *
00082    * @throw XDDY0011 if any nodes in the sequence is not a member of a collection
00083    *        or not all nodes of the sequence belong to the same collection.
00084    *
00085    */
00086   virtual void
00087   insertNodesBefore(
00088       const Item& aTarget,
00089       const ItemSequence_t& aNodes) = 0;
00090 
00091   /**
00092    * This function inserts copies of the given
00093    * nodes into a collection at the position directly following the
00094    * given target node.
00095    *
00096    * @param aTarget the node in the collection after which the
00097    *        sequence should be inserted.
00098    * @param aNodes The sequences of nodes whose copies should
00099    *        be added to the collection.
00100    *
00101    * @throw XDDY0011 if any nodes in the sequence is not a member of a collection
00102    *        or not all nodes of the sequence belong to the same collection.
00103    *
00104    */
00105   virtual void
00106   insertNodesAfter(
00107       const Item& aTarget,
00108       const ItemSequence_t& aNodes) = 0;
00109   
00110   /**
00111    * This function deletes zero of more nodes from a collection. 
00112    *
00113    * @param aNodes the nodes in the collection that should be deleted.
00114    *
00115    * @throw XDDY0011 if any nodes in the given sequence is not a member of a collection
00116    *        or not all nodes of the sequence belong to the same collection.
00117    *
00118    */
00119   virtual void
00120   deleteNodes(const ItemSequence_t& aNodes) = 0;
00121   
00122   /**
00123    * This function deletes the first node from a collection.
00124    *
00125    * @throw XDDY0011 if the collection doesn't contain any node.
00126    *
00127    */
00128   virtual void
00129   deleteNodeFirst() = 0;
00130   
00131   /**
00132    * This function deletes the n first nodes from a collection.
00133    *
00134    * @throw XDDY0011 if the collection doesn't contain any node.
00135    *
00136    */
00137   virtual void
00138   deleteNodesFirst(unsigned long aNumNodes) = 0;
00139   
00140   /**
00141    * This function deletes the last node from a collection.
00142    *
00143    * @throw XDDY0011 if the collection doesn't contain any node.
00144    *
00145    */
00146   virtual void
00147   deleteNodeLast() = 0;
00148   
00149   /**
00150    * This function deletes the n last nodes from a collection.
00151    *
00152    * @throw XDDY0011 if the collection doesn't contain any node.
00153    *
00154    */
00155   virtual void
00156   deleteNodesLast(unsigned long aNumNodes) = 0;
00157   
00158   /**
00159    * This function returns the index of the given node in the collection.
00160    *
00161    * @param aNode The node to retrieve the index from.
00162    *
00163    * @return Returns the position of the given node in the collection.
00164    *
00165    * @throw XDDY0011 if node is not contained in any collection.
00166    *
00167    */
00168   virtual long long
00169   indexOf(const Item& aNode) = 0;
00170   
00171   /**
00172    * This function returns the sequence of nodes of the collection.
00173    *
00174    * @return The sequence contained in the given collection.
00175    *
00176    */
00177   virtual ItemSequence_t
00178   contents() = 0;
00179 
00180   /**
00181    * \brief Destructor.
00182    */
00183   virtual ~Collection() {}
00184 
00185   /**
00186    * Retrieves all annotations for the given collection.
00187    * If the collection is a statically declared collection, the annotations
00188    * are the ones that haven been given in the declaration of the collection
00189    * (or the defaults). If the collection is a dynamic collection, the
00190    * annotations are the default ones for dynamic collections.
00191    *
00192    * @return a list of all annotations for the given collection (if found)
00193    */
00194   virtual void
00195   getAnnotations(std::vector<Annotation_t>& aAnnotations) const = 0;
00196 
00197   /**
00198    * The function checks if this collection has been statically declared.
00199    *
00200    * @return true if the collection is a static collection, false otherwise.
00201    */
00202   virtual bool
00203   isStatic() const = 0;
00204 
00205   /**
00206    * Retrieves the sequence type for this (static declared) collection.
00207    *
00208    * @return the sequence type for the said collection, or 0
00209    *  if this collection is not statically declared.
00210    *
00211    * @see isStatic()
00212    */
00213   virtual TypeIdentifier_t
00214   getType() const = 0;
00215 
00216   /** \brief Register a DiagnosticHandler to which errors
00217    * occuring during the management or manipulation of this collection
00218    * are reported.
00219    *
00220    * If no DiagnosticHandler has been set using
00221    * (1) this function,
00222    * (2) the corresponding function of the XmlDataManager, or
00223    * (3) the corresponding function of the CollectionManager 
00224    * then subclasses of the ZorbaException class are thrown to report
00225    * errors.
00226    *
00227    * @param aDiagnosticHandler DiagnosticHandler to which errors
00228    *        are reported. The caller retains ownership over the
00229    *        DiagnosticHandler passed as parameter.
00230    */
00231   virtual void
00232   registerDiagnosticHandler(DiagnosticHandler* aDiagnosticHandler) = 0;
00233 
00234 };
00235   
00236 } /* namespace zorba */
00237 
00238 #endif
00239 /*
00240  * Local variables:
00241  * mode: c++
00242  * End:
00243  */
00244 /* vim:set et sw=2 ts=2: */
blog comments powered by Disqus