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 
17 #ifndef API_ITEM_H
18 #define API_ITEM_H
19 
20 /** \brief The Zorba Item interface.
21  *
22  * This class is the Zorba representation of an Item as defined in the
23  * XQuery 1.0 and XPath 2.0 Data Model (XDM); see http://www.w3.org/TR/xpath-datamodel/.
24  *
25  * Instances of the XDM are a sequence, i.e. an ordered collection of zero or more items.
26  * In the Zorba API, a sequence is represented by the ItemSequence class.
27  *
28  * The Item class is the union of all XQuery node and atomic types.
29  * The class provides functions to access the information of an Item. Note that not
30  * all functions are defined on every Item kind. If a function is called on an Item that
31  * does not provide the called function, an ZXQP0024_FUNCTION_NOT_IMPLEMENTED_FOR_ITEMTYPE error
32  * is raised.
33  *
34  * Instances of the Item class are always passed by copy. To check whether a given Item is valid
35  * isNull() can be called which returns true if the given Item is not valid and false otherwise.
36  * A new atomic Item can be created using the ItemFactory. A new node Item should be created
37  * by the result of a query.
38  */
39 class Item
40 {
41  friend class Iterator;
42  friend class StaticContext;
43  friend class DocumentManager;
44  friend class SingletonIterator;
45  friend class DynamicContext;
46  friend class ItemFactory;
47  friend class Collection;
48  friend class CollectionManager;
50  friend class ItemSequence;
51 private:
52  zorba::Item theItem;
53 
54 public:
55  /** \brief Default constructor
56  */
57  Item() {}
58  /** \brief Copy constructor
59  */
60  Item(const Item& aItem) : theItem(aItem.theItem) {}
61  /** \brief Constructor that is used to construct Items in the Zorba engine itself.
62  *
63  * This constructor is for internal use only.
64  */
65  Item(const zorba::Item& aZItem) : theItem(aZItem) {}
66 
67  /** \brief Static constructor
68  */
69  static Item createEmptyItem();
70 
71  /** \brief Get the string value of the Item.
72  *
73  * The string value is the string that is extracted by calling the fn:string function
74  * on the Item (see http://www.w3.org/TR/xpath-functions/#func-string).
75  * Note that this function is available for all types of Items.
76  *
77  * @return Item the string value of the Item.
78  * @throw ZorbaException if an error occured.
79  */
80  std::string getStringValue() const;
81 
82  /** \brief Serializes the object
83  *
84  * Returns a string with the value of the object serialized
85  *
86  * @return The string value of the Item.
87  * @throw ZorbaException if an error occured.
88  */
89  std::string serialize() const;
90 
91  /** \brief Serializes the object
92  *
93  * Returns a string with the value of the object serialized
94  *
95  * @param serOptions The serialization options for this Item
96  * @return The string value of the Item.
97  * @throw ZorbaException if an error occured.
98  */
99  std::string serialize(SerializationOptions serOptions) const;
100 
101  /** \brief Get the atomization value of the Item.
102  *
103  * The atomization value is the value that is returned by atomization
104  * (see http://www.w3.org/TR/xquery/#id-atomization).
105  * Note that this function is available for all types of Items.
106  *
107  * @return Item the atomization value of the Item.
108  * @throw ZorbaException if an error occured.
109  */
110  Iterator getAtomizationValue () const;
111 
112  /** \brief Get an iterator for the attributes of this (node) Item.
113  *
114  * Note that this function is only available for node Items.
115  *
116  * @return Iterator over the attributes of this node.
117  * @throw ZorbaException if an error occured, e.g. the Item is not of type node.
118  */
119  Iterator getAttributes () const;
120 
121  /** \brief Get the bool value of the boolean Item.
122  *
123  * Note that this function is only available for Items of type boolean.
124  *
125  * @return true if the boolean value is true, false otherwise.
126  * @throw ZorbaException if an error occured, e.g. the Item is not of type boolean.
127  */
128  bool getBooleanValue () const;
129 
130  /** \brief Get an iterator for the children of this (node) Item.
131  *
132  * Note that this function is only available for node Items.
133  *
134  * @return Iterator over the children of this node.
135  * @throw ZorbaException if an error occured, e.g. the Item is not of type node.
136  */
137  Iterator getChildren () const;
138 
139  /** \brief Get the effective boolean value of the Item.
140  *
141  * The effective boolean value is the result of applying the fn:boolean function on
142  * the Item (see http://www.w3.org/TR/xpath-functions/#func-boolean).
143  * Note that this function is available for all types of Items.
144  *
145  * @return Item the effective boolean value of the Item
146  * @throw ZorbaException if an error occured.
147  */
148  Item getEBV () const;
149 
150  /** \brief Get the int value of the Item.
151  *
152  * @return Item the int value of the Item.
153  * @throw ZorbaException if an error occured.
154  */
155  int getIntValue () const;
156 
157  /** \brief Get the int value of the Item.
158  *
159  * @return Item the int value of the Item.
160  * @throw ZorbaException if an error occured.
161  */
162  double getDoubleValue () const;
163 
164  /** \brief Get the long value of the Item.
165  *
166  * @return Item the long value of the Item.
167  * @throw ZorbaException if an error occured.
168  */
169  long long getLongValue () const;
170 
171  /** \brief Get the value of a QName's local name.
172  *
173  * Note that this function is only available for Items of type QName.
174  *
175  * @return String the local name of the QName.
176  * @throw ZorbaException if an error occured, e.g. the Item is not a QName.
177  */
178  std::string getLocalName () const;
179 
180  /** \brief Get the (optional) value of a QName's namespace.
181  *
182  * Note that this function is only available for Items of type QName.
183  *
184  * @return String the namespace URI of the QName.
185  * @throw ZorbaException if an error occured, e.g. the Item is not a QName.
186  */
187  std::string getNamespace () const;
188 
189  /** \brief Get a vector for the namespace bindings of this (element) Item.
190  *
191  * Note that this function is only available for element Items.
192  *
193  * @throw ZorbaException if an error occured, e.g. the Item is not of type element.
194  */
195  std::vector< std::pair< std::string, std::string > > getNamespaceBindings ();
196 
197  /** \brief Get the name of this (node) Item.
198  *
199  * Note that this function is only available for node Items.
200  *
201  * @return bool if the name of the node was retrieved successfully
202  * @param aNodeName the name of the node
203  * @throw ZorbaException if an error occured (e.g. the Item is not of type node).
204  */
205  bool getNodeName (Item &aNodeName) const;
206 
207  /** \brief Get parent of this (node) Item.
208  *
209  * Note that this function is only available for node Items.
210  *
211  * @return element or document parent node of this node.
212  * @throw ZorbaException if an error occured, e.g. the Item is not of type node.
213  */
214  Item getParent () const;
215 
216  /** \brief Get the (optional) value of a QName's prefix.
217  *
218  * Note that this function is only available for Items of type QName.
219  *
220  * @return String the prefix of the QName.
221  * @throw ZorbaException if an error occured, e.g. the Item is not a QName.
222  */
223  std::string getPrefix () const;
224 
225  /** \brief Get the type of the Item.
226  *
227  * See http://www.w3.org/TR/xpath-datamodel/#types.
228  * Note that this function is available for all types of Items.
229  *
230  * @return Item the type of the Item as a QName Item
231  * @throw ZorbaException if an error occured.
232  */
233  Item getType () const;
234  unsigned int getUnsignedIntValue () const;
235 
236  /** \brief Get the type of this (node) Item.
237  *
238  * Note that this function is only available for node Items.
239  *
240  * @return int the kind of this node (the avaialble kinds can be found in the store::StoreConsts class)
241  * @throw ZorbaException if an error occured (e.g. the Item is not of type node).
242  */
243  int getNodeKind() const;
244 
245  /** \brief Check if the Item is an atomic Item.
246  *
247  * Note that this function is available for all types of Items.
248  *
249  * @return true if the Item is an atomic Item, false otherwise.
250  */
251  bool isAtomic () const;
252 
253  /** \brief Check if the value of the Item is not a number (NaN).
254  *
255  * Note that this function is only available for numeric Items (e.g. Double or Float).
256  *
257  * @return true if the Item is NaN, false otherwise.
258  * @throw ZorbaException if an error occured, e.g. the Item is not a numeric type.
259  */
260  bool isNaN () const;
261 
262  /** \brief Check if the Item is a node Item.
263  *
264  * Note that this function is available for all types of Items.
265  *
266  * @return true if the Item is of type node, false otherwise.
267  */
268  bool isNode () const;
269 
270  /** \brief Check if the Item is null.
271  *
272  * If this function returns true, the Item is not valid.
273  * Note that this function is available for all types of Items.
274  *
275  * @return true if the Item is null, false otherwise.
276  */
277  bool isNull () const;
278 
279  /** \brief Check if the value of the Item is positive or negative infinity.
280  *
281  * Note that this function is only available for numeric Items (e.g. Double or Float).
282  *
283  * @return true if the Item is +/-INF, false otherwise.
284  * @throw ZorbaException if an error occured, e.g. the Item is not a numeric type.
285  */
286  bool isPosOrNegInf () const;
287 
288  /** \brief Free all resources aquired by this Item.
289  *
290  * After calling close() on an Item the Item is invalidated, i.e. a subsequent
291  * call to isNull() will return true.
292  *
293  * Note that calling this function is usually not necessary because close() is
294  * implicitly called by the destructor. Calling close() is only necessary if
295  * the resources aquired by an Item should be released before the Item goes out
296  * of scope, i.e. the destructor is called.
297  *
298  * Also note that this function is available for all types of Items.
299  */
300  void close();
301 
302  /** \brief Serializes the object
303  *
304  * Put the serialized object into the specified stream.
305  *
306  * @param aStream The stream to write the value of the Item.
307  * @throw ZorbaException if an error occured.
308  */
309  void serializeToStream(ZorbaIOStream & aStream) const;
310 
311  /** \brief Serializes the object
312  *
313  * Put the serialized object into the specified stream.
314  *
315  * @param aStream The stream to write the value of the Item.
316  * @param serOptions The serialization options for this Item
317  * @throw ZorbaException if an error occured.
318  */
319  void serializeToStream(ZorbaIOStream & aStream, SerializationOptions serOptions) const;
320 
321 }; // class Item
322 
323 #endif
double getDoubleValue() const
Get the int value of the Item.
void close()
Free all resources aquired by this Item.
Iterator getAttributes() const
Get an iterator for the attributes of this (node) Item.
Item getType() const
Get the type of the Item.
int getIntValue() const
Get the int value of the Item.
bool isNull() const
Check if the Item is null.
std::vector< std::pair< std::string, std::string > > getNamespaceBindings()
Get a vector for the namespace bindings of this (element) Item.
This interface represents an instance of the XQuery 1.0 and XPath 2.0 Data Model (XDM).
Definition: ItemSequence.h:25
Using the StaticCollectionManager one can retrieve information about statically declared collections ...
bool getBooleanValue() const
Get the bool value of the boolean Item.
Item()
Default constructor.
Definition: Item.h:57
void serializeToStream(ZorbaIOStream &aStream) const
Serializes the object.
A Collection is a persistent sequence of node items.
Definition: Collection.h:29
Instances of the class StaticContext contain the information that is available at the time the query ...
Definition: StaticContext.h:79
Item getParent() const
Get parent of this (node) Item.
This class defines a set of functions for managing persistent collections.
bool getNodeName(Item &aNodeName) const
Get the name of this (node) Item.
Iterator getChildren() const
Get an iterator for the children of this (node) Item.
bool isNaN() const
Check if the value of the Item is not a number (NaN).
The Zorba Item interface.
Definition: Item.h:39
Item(const Item &aItem)
Copy constructor.
Definition: Item.h:60
unsigned int getUnsignedIntValue() const
int getNodeKind() const
Get the type of this (node) Item.
Interface for an Iterator over an instance of the XML Data Model (i.e., a sequence of items)...
Definition: Iterator.h:32
Instances of the class DynamicContext contain the information that is available at the time the query...
Item getEBV() const
Get the effective boolean value of the Item.
Item(const zorba::Item &aZItem)
Constructor that is used to construct Items in the Zorba engine itself.
Definition: Item.h:65
bool isNode() const
Check if the Item is a node Item.
bool isAtomic() const
Check if the Item is an atomic Item.
Iterator getAtomizationValue() const
Get the atomization value of the Item.
This class defines a set of values used to define the way a serialization can be made over Items or C...
long long getLongValue() const
Get the long value of the Item.
friend class SingletonIterator
Definition: Item.h:44
std::string getLocalName() const
Get the value of a QName's local name.
ItemFactory to create Items.
Definition: ItemFactory.h:28
std::string serialize() const
Serializes the object.
std::string getStringValue() const
Get the string value of the Item.
static Item createEmptyItem()
Static constructor.
bool isPosOrNegInf() const
Check if the value of the Item is positive or negative infinity.
std::string getPrefix() const
Get the (optional) value of a QName's prefix.
std::string getNamespace() const
Get the (optional) value of a QName's namespace.