item.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_ITEM_API_H
17 #define ZORBA_ITEM_API_H
18 
19 #include <iostream>
20 #include <zorba/config.h>
21 #include <zorba/api_shared_types.h>
22 #include <zorba/store_consts.h>
23 #include <vector>
24 
25 namespace zorba {
26 
27 class Item;
28 namespace store { class Item; }
29 
30 namespace serialization
31 {
32  class Archiver;
33  void operator&(zorba::serialization::Archiver &ar, zorba::Item &obj);
34 }
35 
36 /**
37  * Used for Item::getNamespaceBindings() and ItemFactory::createElementNode().
38  */
39 typedef std::vector<std::pair<String, String> > NsBindings;
40 
41 /** \brief The Zorba Item interface.
42  *
43  * This class is the Zorba representation of an Item as defined in the
44  * XQuery 1.0 and XPath 2.0 Data Model (XDM); see http://www.w3.org/TR/xpath-datamodel/.
45  *
46  * Instances of the XDM are a sequence, i.e. an ordered collection of zero or more items.
47  * In the Zorba API, a sequence is represented by the ItemSequence class.
48  *
49  * The Item class is the union of all XQuery node and atomic types.
50  * The class provides functions to access the information of an Item. Note that not
51  * all functions are defined on every Item kind. If a function is called on an Item that
52  * does not provide the called function, an ZXQP0024_FUNCTION_NOT_IMPLEMENTED_FOR_ITEMTYPE error
53  * is raised.
54  *
55  * Instances of the Item class are always passed by copy. To check whether a given Item is valid
56  * isNull() can be called which returns true if the given Item is not valid and false otherwise.
57  * A new atomic Item can be created using the ItemFactory. A new node Item should be created
58  * by the result of a query.
59  */
60 class ZORBA_DLL_PUBLIC Item
61 {
62 public:
63  /** \brief Default constructor
64  */
65  Item();
66 
67  /** \brief Copy constructor
68  */
69  Item(const Item& other);
70 
71  /** \brief Constructor that is used to construct Items in the Zorba engine itself.
72  *
73  * This constructor is for internal use only.
74  */
75  Item(const store::Item* item);
76 
77  /** \brief Assingment operator
78  */
79  const Item& operator =(const Item& rhs);
80 
81  /** \brief Assingment operator that is used in the Zorba engine itself.
82  *
83  * This operator is for internal use only.
84  */
85  const Item& operator =(const store::Item* rhs);
86 
87  /** \brief Destructor
88  */
89  ~Item();
90 
91  /** \brief Check if the Item is null.
92  *
93  * If this function returns true, the Item is not valid.
94  * Note that this function is available for all types of Items.
95  *
96  * @return true if the Item is null, false otherwise.
97  */
98  bool
99  isNull() const;
100 
101  /** \brief Free all resources aquired by this Item.
102  *
103  * After calling close() on an Item the Item is invalidated, i.e. a subsequent
104  * call to isNull() will return true.
105  *
106  * Note that calling this function is usually not necessary because close() is
107  * implicitly called by the destructor. Calling close() is only necessary if
108  * the resources aquired by an Item should be released before the Item goes out
109  * of scope, i.e. the destructor is called.
110  *
111  * Also note that this function is available for all types of Items.
112  */
113  void
114  close();
115 
116  /** \brief Check if the Item is a node Item.
117  *
118  * Note that this function is available for all types of Items.
119  *
120  * @return true if the Item is of type node, false otherwise.
121  */
122  bool
123  isNode() const;
124 
125  /** \brief Check if the Item is an atomic Item.
126  *
127  * Note that this function is available for all types of Items.
128  *
129  * @return true if the Item is an atomic Item, false otherwise.
130  */
131  bool
132  isAtomic() const;
133 
134  /**
135  * @return the type of this item based on the enum values in store_const.h
136  */
137  store::SchemaTypeCode getTypeCode() const;
138 
139  /** \brief Get the type of the Item.
140  *
141  * See http://www.w3.org/TR/xpath-datamodel/#types.
142  * Note that this function is available for all types of Items.
143  *
144  * @return Item the type of the Item as a QName Item
145  * @throw ZorbaException if an error occured.
146  */
147  Item
148  getType() const;
149 
150  /** \brief Get the atomization value of the Item.
151  *
152  * The atomization value is the value that is returned by atomization
153  * (see http://www.w3.org/TR/xquery/#id-atomization).
154  * Note that this function is available for all types of Items.
155  *
156  * @return Item the atomization value of the Item.
157  * @throw ZorbaException if an error occured.
158  */
159  Iterator_t
160  getAtomizationValue() const;
161 
162  /** \brief Get the string value of the Item.
163  *
164  * The string value is the string that is extracted by calling the fn:string function
165  * on the Item (see http://www.w3.org/TR/xpath-functions/#func-string).
166  * Note that this function is available for all types of Items.
167  *
168  * @return Item the string value of the Item.
169  * @throw ZorbaException if an error occured.
170  */
171  String
172  getStringValue() const;
173 
174  /** \brief Get the int value of the Item.
175  *
176  * @return Item the int value of the Item.
177  * @throw ZorbaException if an error occured.
178  */
179  int32_t
180  getIntValue() const;
181 
182  /** \brief Get the unsigned int value of the Item.
183  *
184  * @return Item the unsigned int value of the Item.
185  * @throw ZorbaException if an error occured.
186  */
187  uint32_t
188  getUnsignedIntValue() const;
189 
190  /** \brief Get the int value of the Item.
191  *
192  * @return Item the int value of the Item.
193  * @throw ZorbaException if an error occured.
194  */
195  double
196  getDoubleValue() const;
197 
198  /** \brief Get the long value of the Item.
199  *
200  * @return Item the long value of the Item.
201  * @throw ZorbaException if an error occured.
202  */
203  int64_t
204  getLongValue() const;
205 
206  /** \brief Get the effective boolean value of the Item.
207  *
208  * The effective boolean value is the result of applying the fn:boolean function on
209  * the Item (see http://www.w3.org/TR/xpath-functions/#func-boolean).
210  * Note that this function is available for all types of Items.
211  *
212  * @return Item the effective boolean value of the Item
213  * @throw ZorbaException if an error occured.
214  */
215  Item
216  getEBV() const;
217 
218  /** \brief Get the (optional) value of a QName's prefix.
219  *
220  * Note that this function is only available for Items of type QName.
221  *
222  * @return String the prefix of the QName.
223  * @throw ZorbaException if an error occured, e.g. the Item is not a QName.
224  */
225  String
226  getPrefix() const;
227 
228  /** \brief Get the (optional) value of a QName's namespace.
229  *
230  * Note that this function is only available for Items of type QName.
231  *
232  * @return String the namespace URI of the QName.
233  * @throw ZorbaException if an error occured, e.g. the Item is not a QName.
234  */
235  String
236  getNamespace() const;
237 
238  /** \brief Get the value of a QName's local name.
239  *
240  * Note that this function is only available for Items of type QName.
241  *
242  * @return String the local name of the QName.
243  * @throw ZorbaException if an error occured, e.g. the Item is not a QName.
244  */
245  String
246  getLocalName() const;
247 
248  /** \brief Check if the value of the Item is not a number (NaN).
249  *
250  * Note that this function is only available for numeric Items (e.g. Double or Float).
251  *
252  * @return true if the Item is NaN, false otherwise.
253  * @throw ZorbaException if an error occured, e.g. the Item is not a numeric type.
254  */
255  bool
256  isNaN() const;
257 
258  /** \brief Check if the value of the Item is positive or negative infinity.
259  *
260  * Note that this function is only available for numeric Items (e.g. Double or Float).
261  *
262  * @return true if the Item is +/-INF, false otherwise.
263  * @throw ZorbaException if an error occured, e.g. the Item is not a numeric type.
264  */
265  bool
266  isPosOrNegInf() const;
267 
268  /** \brief Get the bool value of the boolean Item.
269  *
270  * Note that this function is only available for Items of type boolean.
271  *
272  * @return true if the boolean value is true, false otherwise.
273  * @throw ZorbaException if an error occured, e.g. the Item is not of type boolean.
274  */
275  bool
276  getBooleanValue() const;
277 
278  /** \brief Get an iterator for the children of this (node) Item.
279  *
280  * Note that this function is only available for node Items.
281  * The file \link simple.cpp \endlink contains some basic examples that demonstrate
282  * the use of this function.
283  *
284  * @return Iterator over the children of this node.
285  * @throw ZorbaException if an error occured, e.g. the Item is not of type node.
286  */
287  Iterator_t
288  getChildren() const;
289 
290  /** \brief Get an iterator for the attributes of this (node) Item.
291  *
292  * Note that this function is only available for node Items.
293  * The file \link simple.cpp \endlink contains some basic examples that demonstrate
294  * the use of this function.
295  *
296  * @return Iterator over the attributes of this node.
297  * @throw ZorbaException if an error occured, e.g. the Item is not of type node.
298  */
299  Iterator_t
300  getAttributes() const;
301 
302  /** \brief Get an iterator for the namespace bindings of this (element) Item.
303  *
304  * Note that this function is only available for element Items.
305  * The file \link simple.cpp \endlink contains some basic examples that demonstrate
306  * the use of this function.
307  *
308  * @param aBindings An STL list to receive the namespace bindings of this node (each
309  * represented as a std::pair<zorba::String,zorba::String> where the
310  * first string is the namespace prefix and the second is the namespace URI).
311  * @param aNsScoping An instance of NsScoping to declare which bindings to return:
312  * those local to the element; those local to all parent elements; or all bindings
313  * (the default).
314  * @throw ZorbaException if an error occured, e.g. the Item is not of type element.
315  */
316  void
317  getNamespaceBindings(NsBindings& aBindings,
319  const;
320 
321  /** \brief Get parent of this (node) Item.
322  *
323  * Note that this function is only available for node Items.
324  *
325  * @return element or document parent node of this node.
326  * @throw ZorbaException if an error occured, e.g. the Item is not of type node.
327  */
328  Item
329  getParent() const;
330 
331  /** \brief Get the name of this (node) Item.
332  *
333  * Note that this function is only available for node Items.
334  * The file \link simple.cpp \endlink contains some basic examples that demonstrate
335  * the use of this function.
336  *
337  * @return bool if the name of the node was retrieved successfully
338  * @return aNodeName the name of the node
339  * @throw ZorbaException if an error occured (e.g. the Item is not of type node).
340  */
341  bool
342  getNodeName(Item& aNodeName) const;
343 
344  /** \brief Get the type of this (node) Item.
345  *
346  * Note that this function is only available for node Items.
347  *
348  * @return int the kind of this node (the avaialble kinds can be found in the store::StoreConsts class)
349  * @throw ZorbaException if an error occured (e.g. the Item is not of type node).
350  */
351  int
352  getNodeKind() const;
353 
354  /**
355  * Checks whether the item's content is streamable.
356  *
357  * @return true only if it is.
358  */
359  bool
360  isStreamable() const;
361 
362  /**
363  * Gets an istream for the item's content.
364  *
365  * @return the stream.
366  * @throw ZorbaException if the item is not streamable.
367  */
368  std::istream&
369  getStream();
370 
371  /**
372  * Returns true if the contents of a binary item is already encoded
373  *
374  * @return true if the content is already encoded, false otherwise
375  */
376  bool
377  isEncoded() const;
378 
379  /**
380  * Returns the value and size of the given base64Binary item
381  *
382  * The value is a string which is base64 encoded if isEncoded()
383  * returns true. Otherwise, it is the original unencoded binary
384  * data.
385  *
386  * If the given item is streamable (i.e. isStreamable() returns true),
387  * the stream returned by getStream() should to be used to retrieve
388  * the value. Otherwise, the contents of the stream will be materialized
389  * in main memory.
390  */
391  const char*
392  getBase64BinaryValue(size_t& s) const;
393 
394  /** \brief Returns the name of the collection this node is stored in.
395  *
396  * @return The name of the collection or 0 if the given item is not
397  * a node or not stored in a collection.
398  */
399  Item
400  getCollectionName() const;
401 
402 private:
403  friend class Unmarshaller;
404 
405  store::Item * m_item;
406 private:
407  //for plan serialization
408  friend void zorba::serialization::operator&(zorba::serialization::Archiver &ar, Item &obj);
409 };
410 
411 } // namespace zorba
412 
413 #endif
414 /* vim:set et sw=2 ts=2: */
blog comments powered by Disqus