collection.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_COLLECTION_API_H
17 #define ZORBA_COLLECTION_API_H
18 
19 #include <zorba/config.h>
20 #include <zorba/api_shared_types.h>
21 #include <zorba/item.h>
22 #include <vector>
23 
24 namespace zorba {
25 
26 /** \brief A Collection is a persistent sequence of node items.
27  *
28  * Instances of this class can be used to modify or retrieve the contents
29  * of a collection.
30  *
31  * The variable aNodes passed to any of the insert functions is evaluated
32  * as though it were an enclosed expression in an element constructor.
33  * The result of this step is a sequence of nodes to be inserted into the collection.
34  *
35  * Note: This class is reference counted. When writing multi-threaded clients,
36  * it is the responibility of the client code to synchronize assignments to the
37  * SmartPtr holding this object.
38  */
39 class ZORBA_DLL_PUBLIC Collection : public SmartObject
40 {
41  public:
42  /**
43  * \brief Get the name of the collection.
44  *
45  * @return The name of the collection.
46  */
47  virtual const Item
48  getName() const = 0;
49 
50  /**
51  * This function inserts copies of the
52  * given nodes at the beginning of the collection.
53  *
54  * @param aNodes The sequences of nodes whose copies
55  * should be added to the collection.
56  *
57  */
58  virtual void
59  insertNodesFirst(const ItemSequence_t& aNodes) = 0;
60 
61  /**
62  * This function inserts copies of the
63  * given nodes at the end of the collection.
64  *
65  * @param aNodes The sequences of nodes whose copies
66  * should be added to the collection.
67  *
68  */
69  virtual void
70  insertNodesLast(const ItemSequence_t& aNodes) = 0;
71 
72  /**
73  * This function inserts copies of the given
74  * nodes into a collection at the position directly preceding the
75  * given target node.
76  *
77  * @param aTarget the node in the collection before which the
78  * sequence should be inserted.
79  * @param aNodes The sequences of nodes whose copies should
80  * be added to the collection.
81  *
82  * @throw XDDY0011 if any nodes in the sequence is not a member of a collection
83  * or not all nodes of the sequence belong to the same collection.
84  *
85  */
86  virtual void
87  insertNodesBefore(
88  const Item& aTarget,
89  const ItemSequence_t& aNodes) = 0;
90 
91  /**
92  * This function inserts copies of the given
93  * nodes into a collection at the position directly following the
94  * given target node.
95  *
96  * @param aTarget the node in the collection after which the
97  * sequence should be inserted.
98  * @param aNodes The sequences of nodes whose copies should
99  * be added to the collection.
100  *
101  * @throw XDDY0011 if any nodes in the sequence is not a member of a collection
102  * or not all nodes of the sequence belong to the same collection.
103  *
104  */
105  virtual void
106  insertNodesAfter(
107  const Item& aTarget,
108  const ItemSequence_t& aNodes) = 0;
109 
110  /**
111  * This function deletes zero of more nodes from a collection.
112  *
113  * @param aNodes the nodes in the collection that should be deleted.
114  *
115  * @throw XDDY0011 if any nodes in the given sequence is not a member of a collection
116  * or not all nodes of the sequence belong to the same collection.
117  *
118  */
119  virtual void
120  deleteNodes(const ItemSequence_t& aNodes) = 0;
121 
122  /**
123  * This function deletes the first node from a collection.
124  *
125  * @throw XDDY0011 if the collection doesn't contain any node.
126  *
127  */
128  virtual void
129  deleteNodeFirst() = 0;
130 
131  /**
132  * This function deletes the n first nodes from a collection.
133  *
134  * @throw XDDY0011 if the collection doesn't contain any node.
135  *
136  */
137  virtual void
138  deleteNodesFirst(unsigned long aNumNodes) = 0;
139 
140  /**
141  * This function deletes the last node from a collection.
142  *
143  * @throw XDDY0011 if the collection doesn't contain any node.
144  *
145  */
146  virtual void
147  deleteNodeLast() = 0;
148 
149  /**
150  * This function deletes the n last nodes from a collection.
151  *
152  * @throw XDDY0011 if the collection doesn't contain any node.
153  *
154  */
155  virtual void
156  deleteNodesLast(unsigned long aNumNodes) = 0;
157 
158  /**
159  * This function returns the index of the given node in the collection.
160  *
161  * @param aNode The node to retrieve the index from.
162  *
163  * @return Returns the position of the given node in the collection.
164  *
165  * @throw XDDY0011 if node is not contained in any collection.
166  *
167  */
168  virtual long long
169  indexOf(const Item& aNode) = 0;
170 
171  /**
172  * This function returns the sequence of nodes of the collection.
173  *
174  * @return The sequence contained in the given collection.
175  *
176  */
177  virtual ItemSequence_t
178  contents() = 0;
179 
180  /**
181  * \brief Destructor.
182  */
183  virtual ~Collection() {}
184 
185  /**
186  * Retrieves all annotations for the given collection.
187  * If the collection is a statically declared collection, the annotations
188  * are the ones that haven been given in the declaration of the collection
189  * (or the defaults). If the collection is a dynamic collection, the
190  * annotations are the default ones for dynamic collections.
191  *
192  * @return a list of all annotations for the given collection (if found)
193  */
194  virtual void
195  getAnnotations(std::vector<Annotation_t>& aAnnotations) const = 0;
196 
197  /**
198  * The function checks if this collection has been statically declared.
199  *
200  * @return true if the collection is a static collection, false otherwise.
201  */
202  virtual bool
203  isStatic() const = 0;
204 
205  /**
206  * Retrieves the sequence type for this (static declared) collection.
207  *
208  * @return the sequence type for the said collection, or 0
209  * if this collection is not statically declared.
210  *
211  * @see isStatic()
212  */
213  virtual TypeIdentifier_t
214  getType() const = 0;
215 
216  /** \brief Register a DiagnosticHandler to which errors
217  * occuring during the management or manipulation of this collection
218  * are reported.
219  *
220  * If no DiagnosticHandler has been set using
221  * (1) this function,
222  * (2) the corresponding function of the XmlDataManager, or
223  * (3) the corresponding function of the CollectionManager
224  * then subclasses of the ZorbaException class are thrown to report
225  * errors.
226  *
227  * @param aDiagnosticHandler DiagnosticHandler to which errors
228  * are reported. The caller retains ownership over the
229  * DiagnosticHandler passed as parameter.
230  */
231  virtual void
232  registerDiagnosticHandler(DiagnosticHandler* aDiagnosticHandler) = 0;
233 
234 };
235 
236 } /* namespace zorba */
237 
238 #endif
239 /*
240  * Local variables:
241  * mode: c++
242  * End:
243  */
244 /* vim:set et sw=2 ts=2: */
blog comments powered by Disqus