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 #ifdef ZORBA_WITH_JSON
151 
152  /**
153  * \brief Check if the Item is a JSON Item, that is, part of the JSONiq
154  * data model.
155  *
156  * Note that this function is available for all types of Items.
157  *
158  * @return true if the Item is a JSON Item, false otherwise.
159  */
160  bool
161  isJSONItem() const;
162 
163 #endif /* ZORBA_WITH_JSON */
164 
165  /** \brief Get the atomization value of the Item.
166  *
167  * The atomization value is the value that is returned by atomization
168  * (see http://www.w3.org/TR/xquery/#id-atomization).
169  * Note that this function is available for all types of Items.
170  *
171  * @return Item the atomization value of the Item.
172  * @throw ZorbaException if an error occured.
173  */
174  Iterator_t
175  getAtomizationValue() const;
176 
177  /** \brief Get the string value of the Item.
178  *
179  * The string value is the string that is extracted by calling the fn:string function
180  * on the Item (see http://www.w3.org/TR/xpath-functions/#func-string).
181  * Note that this function is available for all types of Items.
182  *
183  * @return Item the string value of the Item.
184  * @throw ZorbaException if an error occured.
185  */
186  String
187  getStringValue() const;
188 
189  /** \brief Get the int value of the Item.
190  *
191  * @return Item the int value of the Item.
192  * @throw ZorbaException if an error occured.
193  */
194  int32_t
195  getIntValue() const;
196 
197  /** \brief Get the unsigned int value of the Item.
198  *
199  * @return Item the unsigned int value of the Item.
200  * @throw ZorbaException if an error occured.
201  */
202  uint32_t
203  getUnsignedIntValue() const;
204 
205  /** \brief Get the int value of the Item.
206  *
207  * @return Item the int value of the Item.
208  * @throw ZorbaException if an error occured.
209  */
210  double
211  getDoubleValue() const;
212 
213  /** \brief Get the long value of the Item.
214  *
215  * @return Item the long value of the Item.
216  * @throw ZorbaException if an error occured.
217  */
218  int64_t
219  getLongValue() const;
220 
221  /** \brief Get the effective boolean value of the Item.
222  *
223  * The effective boolean value is the result of applying the fn:boolean function on
224  * the Item (see http://www.w3.org/TR/xpath-functions/#func-boolean).
225  * Note that this function is available for all types of Items.
226  *
227  * @return Item the effective boolean value of the Item
228  * @throw ZorbaException if an error occured.
229  */
230  Item
231  getEBV() const;
232 
233  /** \brief Get the (optional) value of a QName's prefix.
234  *
235  * Note that this function is only available for Items of type QName.
236  *
237  * @return String the prefix of the QName.
238  * @throw ZorbaException if an error occured, e.g. the Item is not a QName.
239  */
240  String
241  getPrefix() const;
242 
243  /** \brief Get the (optional) value of a QName's namespace.
244  *
245  * Note that this function is only available for Items of type QName.
246  *
247  * @return String the namespace URI of the QName.
248  * @throw ZorbaException if an error occured, e.g. the Item is not a QName.
249  */
250  String
251  getNamespace() const;
252 
253  /** \brief Get the value of a QName's local name.
254  *
255  * Note that this function is only available for Items of type QName.
256  *
257  * @return String the local name of the QName.
258  * @throw ZorbaException if an error occured, e.g. the Item is not a QName.
259  */
260  String
261  getLocalName() const;
262 
263  /** \brief Check if the value of the Item is not a number (NaN).
264  *
265  * Note that this function is only available for numeric Items (e.g. Double or Float).
266  *
267  * @return true if the Item is NaN, false otherwise.
268  * @throw ZorbaException if an error occured, e.g. the Item is not a numeric type.
269  */
270  bool
271  isNaN() const;
272 
273  /** \brief Check if the value of the Item is positive or negative infinity.
274  *
275  * Note that this function is only available for numeric Items (e.g. Double or Float).
276  *
277  * @return true if the Item is +/-INF, false otherwise.
278  * @throw ZorbaException if an error occured, e.g. the Item is not a numeric type.
279  */
280  bool
281  isPosOrNegInf() const;
282 
283  /** \brief Get the bool value of the boolean Item.
284  *
285  * Note that this function is only available for Items of type boolean.
286  *
287  * @return true if the boolean value is true, false otherwise.
288  * @throw ZorbaException if an error occured, e.g. the Item is not of type boolean.
289  */
290  bool
291  getBooleanValue() const;
292 
293  /** \brief Get an iterator for the children of this (node) Item.
294  *
295  * Note that this function is only available for node Items.
296  * The file \link simple.cpp \endlink contains some basic examples that demonstrate
297  * the use of this function.
298  *
299  * @return Iterator over the children of this node.
300  * @throw ZorbaException if an error occured, e.g. the Item is not of type node.
301  */
302  Iterator_t
303  getChildren() const;
304 
305  /** \brief Get an iterator for the attributes of this (node) Item.
306  *
307  * Note that this function is only available for node Items.
308  * The file \link simple.cpp \endlink contains some basic examples that demonstrate
309  * the use of this function.
310  *
311  * @return Iterator over the attributes of this node.
312  * @throw ZorbaException if an error occured, e.g. the Item is not of type node.
313  */
314  Iterator_t
315  getAttributes() const;
316 
317  /** \brief Get an iterator for the namespace bindings of this (element) Item.
318  *
319  * Note that this function is only available for element Items.
320  * The file \link simple.cpp \endlink contains some basic examples that demonstrate
321  * the use of this function.
322  *
323  * @param aBindings An STL list to receive the namespace bindings of this node (each
324  * represented as a std::pair<zorba::String,zorba::String> where the
325  * first string is the namespace prefix and the second is the namespace URI).
326  * @param aNsScoping An instance of NsScoping to declare which bindings to return:
327  * those local to the element; those local to all parent elements; or all bindings
328  * (the default).
329  * @throw ZorbaException if an error occured, e.g. the Item is not of type element.
330  */
331  void
332  getNamespaceBindings(NsBindings& aBindings,
334  const;
335 
336  /** \brief Get parent of this (node) Item.
337  *
338  * Note that this function is only available for node Items.
339  *
340  * @return element or document parent node of this node.
341  * @throw ZorbaException if an error occured, e.g. the Item is not of type node.
342  */
343  Item
344  getParent() const;
345 
346  /** \brief Get the name of this (node) Item.
347  *
348  * Note that this function is only available for node Items.
349  * The file \link simple.cpp \endlink contains some basic examples that demonstrate
350  * the use of this function.
351  *
352  * @return bool if the name of the node was retrieved successfully
353  * @return aNodeName the name of the node
354  * @throw ZorbaException if an error occured (e.g. the Item is not of type node).
355  */
356  bool
357  getNodeName(Item& aNodeName) const;
358 
359  /** \brief Get the type of this (node) Item.
360  *
361  * Note that this function is only available for node Items.
362  *
363  * @return int the kind of this node (the avaialble kinds can be found in the store::StoreConsts class)
364  * @throw ZorbaException if an error occured (e.g. the Item is not of type node).
365  */
366  int
367  getNodeKind() const;
368 
369 #ifdef ZORBA_WITH_JSON
370 
371  /** \brief Get the kind of this (JSON) Item.
372  *
373  * Note that this function is only available for JSON Items, that is, Items
374  * which return true from isJSONItem().
375  *
376  * @return the kind of this JSON item
377  * @throw ZorbaException if an error occured (e.g. the Item is not of type JSON).
378  */
380  getJSONItemKind() const;
381 
382  /** \brief Get the size of a JSON Array.
383  *
384  * Note that this function is only available for JSON Arrays.
385  *
386  * @return Item the size of the array.
387  * @throw ZorbaException if an error occured (e.g. the Item is not of type JSON Array).
388  */
389  uint64_t
390  getArraySize() const;
391 
392  /** \brief Returns the item in the JSON array at the specified index.
393  *
394  * Note that this function is only available for JSON Arrays.
395  *
396  * @param aIndex the index in the array.
397  * @return Item the indexed Item.
398  * @throw ZorbaException if an error occured (e.g. the Item is not of type JSON Array).
399  */
400  Item
401  getArrayValue(uint32_t aIndex) const;
402 
403  /** \brief Get the keys of a JSON Object.
404  *
405  * Note that this function is only available for JSON Objects.
406  *
407  * @return Iterator_t an iterator on the keys of the object.
408  * @throw ZorbaException if an error occured (e.g. the Item is not of type JSON Object).
409  */
410  Iterator_t
411  getObjectKeys() const;
412 
413  /** \brief Returns the value with the given name from a JSON Object.
414  *
415  * Note that this function is only available for JSON Objects.
416  *
417  * @param aName the name of the value in the Object to return.
418  * @return Item the named value from the Object.
419  * @throw ZorbaException if an error occured (e.g. the Item is not of type JSON Object).
420  */
421  Item
422  getObjectValue(String aName) const;
423 
424 #endif /* ZORBA_WITH_JSON */
425 
426  /**
427  * Checks whether the item's content is streamable.
428  *
429  * @return true only if it is.
430  */
431  bool
432  isStreamable() const;
433 
434  /**
435  * Checks whether the item's streamable content is arbitrarily
436  * (forward anb backward) seekable.
437  *
438  * @return true only if it is.
439  */
440  bool
441  isSeekable() const;
442 
443  /**
444  * Gets an istream for the item's content.
445  *
446  * @return the stream.
447  * @throw ZorbaException if the item is not streamable.
448  */
449  std::istream&
450  getStream();
451 
452  /**
453  * Returns true if the contents of a binary item is already encoded
454  *
455  * @return true if the content is already encoded, false otherwise
456  */
457  bool
458  isEncoded() const;
459 
460  /**
461  * Returns the value and size of the given base64Binary item
462  *
463  * The value is a string which is base64 encoded if isEncoded()
464  * returns true. Otherwise, it is the original unencoded binary
465  * data.
466  *
467  * If the given item is streamable (i.e. isStreamable() returns true),
468  * the stream returned by getStream() should to be used to retrieve
469  * the value. Otherwise, the contents of the stream will be materialized
470  * in main memory.
471  */
472  const char*
473  getBase64BinaryValue(size_t& s) const;
474 
475  /** \brief Returns the name of the collection this node is stored in.
476  *
477  * @return The name of the collection or 0 if the given item is not
478  * a node or not stored in a collection.
479  */
480  Item
481  getCollectionName() const;
482 
483  /**
484  * Gets the total amount of memory this Item and all its child Items are
485  * using.
486  *
487  * @return said total amount of memory.
488  */
489  size_t
490  mem_size() const;
491 
492 private:
493  friend class Unmarshaller;
494 
495  store::Item * m_item;
496 private:
497  //for plan serialization
498  friend void zorba::serialization::operator&(zorba::serialization::Archiver &ar, Item &obj);
499 };
500 
501 } // namespace zorba
502 
503 #endif
504 /* vim:set et sw=2 ts=2: */