item.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_ITEM_API_H
00017 #define ZORBA_ITEM_API_H
00018 
00019 #include <iostream>
00020 #include <zorba/config.h>
00021 #include <zorba/api_shared_types.h>
00022 
00023 namespace zorba {
00024 
00025 class Item;
00026 namespace store { class Item; }
00027 
00028 namespace serialization
00029 {
00030   class Archiver;
00031   void operator&(zorba::serialization::Archiver &ar, zorba::Item &obj);
00032 }
00033 
00034 /** \brief The Zorba Item interface.
00035  *
00036  * This class is the Zorba representation of an Item as defined in the
00037  * XQuery 1.0 and XPath 2.0 Data Model (XDM); see http://www.w3.org/TR/xpath-datamodel/. 
00038  * 
00039  * Instances of the XDM are a sequence, i.e. an ordered collection of zero or more items.
00040  * In the Zorba API, a sequence is represented by the ItemSequence class.
00041  *
00042  * The Item class is the union of all XQuery node and atomic types.
00043  * The class provides functions to access the information of an Item. Note that not
00044  * all functions are defined on every Item kind. If a function is called on an Item that
00045  * does not provide the called function, an ZXQP0024_FUNCTION_NOT_IMPLEMENTED_FOR_ITEMTYPE error
00046  * is raised.
00047  *
00048  * Instances of the Item class are always passed by copy. To check whether a given Item is valid
00049  * isNull() can be called which returns true if the given Item is not valid and false otherwise.
00050  * A new atomic Item can be created using the ItemFactory. A new node Item should be created
00051  * by the result of a query.
00052  */
00053 class ZORBA_DLL_PUBLIC Item
00054 {
00055 public:
00056   /** \brief Default constructor
00057    */
00058   Item();
00059 
00060   /** \brief Copy constructor
00061    */
00062   Item(const Item& other);
00063 
00064   /** \brief Constructor that is used to construct Items in the Zorba engine itself.
00065    *
00066    * This constructor is for internal use only.
00067    */
00068   Item(const store::Item* item);
00069 
00070   /** \brief Assingment operator
00071    */
00072   const Item& operator =(const Item& rhs);
00073 
00074   /** \brief Assingment operator that is used in the Zorba engine itself.
00075    *
00076    * This operator is for internal use only.
00077    */
00078   const Item& operator =(const store::Item* rhs);
00079 
00080   /** \brief Destructor
00081    */
00082   ~Item();
00083 
00084   /** \brief Check if the Item is null.
00085    *
00086    * If this function returns true, the Item is not valid.
00087    * Note that this function is available for all types of Items.
00088    *
00089    * @return true if the Item is null, false otherwise.
00090    */
00091   bool
00092   isNull() const;
00093 
00094   /** \brief Free all resources aquired by this Item.
00095    *
00096    * After calling close() on an Item the Item is invalidated, i.e. a subsequent
00097    * call to isNull() will return true. 
00098    *
00099    * Note that calling this function is usually not necessary because close() is
00100    * implicitly called by the destructor. Calling close() is only necessary if
00101    * the resources aquired by an Item should be released before the Item goes out
00102    * of scope, i.e. the destructor is called.
00103    *
00104    * Also note that this function is available for all types of Items.
00105    */
00106   void
00107   close();
00108 
00109   /** \brief Check if the Item is a node Item.
00110    *
00111    * Note that this function is available for all types of Items.
00112    *
00113    * @return true if the Item is of type node, false otherwise.
00114    */
00115   bool
00116   isNode() const;
00117 
00118   /** \brief Check if the Item is an atomic Item.
00119    *
00120    * Note that this function is available for all types of Items.
00121    *
00122    * @return true if the Item is an atomic Item, false otherwise.
00123    */
00124   bool
00125   isAtomic() const;
00126 
00127   /** \brief Get the type of the Item.
00128    *
00129    * See http://www.w3.org/TR/xpath-datamodel/#types.
00130    * Note that this function is available for all types of Items.
00131    *
00132    * @return Item the type of the Item as a QName Item 
00133    * @throw ZorbaException if an error occured.
00134    */
00135   Item
00136   getType() const;
00137 
00138   /** \brief Get the atomization value of the Item.
00139    *
00140    * The atomization value is the value that is returned by atomization 
00141    * (see http://www.w3.org/TR/xquery/#id-atomization).
00142    * Note that this function is available for all types of Items.
00143    *
00144    * @return Item the atomization value of the Item.
00145    * @throw ZorbaException if an error occured.
00146    */
00147   Iterator_t
00148   getAtomizationValue() const;
00149 
00150   /** \brief Get the string value of the Item.
00151    *
00152    * The string value is the string that is extracted by calling the fn:string function
00153    * on the Item (see http://www.w3.org/TR/xpath-functions/#func-string).
00154    * Note that this function is available for all types of Items.
00155    *
00156    * @return Item the string value of the Item.
00157    * @throw ZorbaException if an error occured.
00158    */
00159   String
00160   getStringValue() const;
00161 
00162   /** \brief Get the int value of the Item.
00163    *
00164    * @return Item the int value of the Item.
00165    * @throw ZorbaException if an error occured.
00166    */
00167   int32_t
00168   getIntValue() const;
00169 
00170   /** \brief Get the unsigned int value of the Item.
00171    *
00172    * @return Item the unsigned int value of the Item.
00173    * @throw ZorbaException if an error occured.
00174    */
00175   uint32_t
00176   getUnsignedIntValue() const;
00177 
00178   /** \brief Get the int value of the Item.
00179    *
00180    * @return Item the int value of the Item.
00181    * @throw ZorbaException if an error occured.
00182    */
00183   double
00184   getDoubleValue() const;
00185 
00186   /** \brief Get the long value of the Item.
00187    *
00188    * @return Item the long value of the Item.
00189    * @throw ZorbaException if an error occured.
00190    */
00191   int64_t  
00192   getLongValue() const;
00193 
00194   /** \brief Get the effective boolean value of the Item.
00195    *
00196    * The effective boolean value is the result of applying the fn:boolean function on 
00197    * the Item (see http://www.w3.org/TR/xpath-functions/#func-boolean).
00198    * Note that this function is available for all types of Items.
00199    *
00200    * @return Item the effective boolean value of the Item
00201    * @throw ZorbaException if an error occured.
00202    */
00203   Item
00204   getEBV() const;
00205 
00206   /** \brief Get the (optional) value of a QName's prefix.
00207    *
00208    * Note that this function is only available for Items of type QName.
00209    *
00210    * @return String the prefix of the QName.
00211    * @throw ZorbaException if an error occured, e.g. the Item is not a QName.
00212    */
00213   String
00214   getPrefix() const;
00215 
00216   /** \brief Get the (optional) value of a QName's namespace.
00217    *
00218    * Note that this function is only available for Items of type QName.
00219    *
00220    * @return String the namespace URI of the QName.
00221    * @throw ZorbaException if an error occured, e.g. the Item is not a QName.
00222    */
00223   String
00224   getNamespace() const;
00225 
00226   /** \brief Get the value of a QName's local name.
00227    *
00228    * Note that this function is only available for Items of type QName.
00229    *
00230    * @return String the local name of the QName.
00231    * @throw ZorbaException if an error occured, e.g. the Item is not a QName.
00232    */
00233   String
00234   getLocalName() const;
00235 
00236   /** \brief Check if the value of the Item is not a number (NaN).
00237    *
00238    * Note that this function is only available for numeric Items (e.g. Double or Float).
00239    * 
00240    * @return true if the Item is NaN, false otherwise.
00241    * @throw ZorbaException if an error occured, e.g. the Item is not a numeric type.
00242    */
00243   bool
00244   isNaN() const;
00245 
00246   /** \brief Check if the value of the Item is positive or negative infinity.
00247    *
00248    * Note that this function is only available for numeric Items (e.g. Double or Float).
00249    * 
00250    * @return true if the Item is +/-INF, false otherwise.
00251    * @throw ZorbaException if an error occured, e.g. the Item is not a numeric type.
00252    */
00253   bool
00254   isPosOrNegInf() const;
00255 
00256   /** \brief Get the bool value of the boolean Item.
00257    *
00258    * Note that this function is only available for Items of type boolean.
00259    *
00260    * @return true if the boolean value is true, false otherwise.
00261    * @throw ZorbaException if an error occured, e.g. the Item is not of type boolean.
00262    */
00263   bool
00264   getBooleanValue() const;
00265 
00266   /** \brief Get an iterator for the children of this (node) Item.
00267    *
00268    * Note that this function is only available for node Items.
00269    * The file \link simple.cpp \endlink contains some basic examples the demonstrate
00270    * the use of this function.
00271    *
00272    * @return Iterator over the children of this node.
00273    * @throw ZorbaException if an error occured, e.g. the Item is not of type node.
00274    */
00275   Iterator_t
00276   getChildren() const;
00277 
00278   /** \brief Get an iterator for the attributes of this (node) Item.
00279    *
00280    * Note that this function is only available for node Items.
00281    * The file \link simple.cpp \endlink contains some basic examples the demonstrate
00282    * the use of this function.
00283    *
00284    * @return Iterator over the attributes of this node.
00285    * @throw ZorbaException if an error occured, e.g. the Item is not of type node.
00286    */
00287   Iterator_t
00288   getAttributes() const;
00289 
00290   /** \brief Get parent of this (node) Item.
00291    *
00292    * Note that this function is only available for node Items.
00293    *
00294    * @return element or document parent node of this node.
00295    * @throw ZorbaException if an error occured, e.g. the Item is not of type node.
00296    */
00297   Item
00298   getParent() const;
00299 
00300   /** \brief Get the name of this (node) Item.
00301    *
00302    * Note that this function is only available for node Items.
00303    * The file \link simple.cpp \endlink contains some basic examples the demonstrate
00304    * the use of this function.
00305    *
00306    * @return bool if the name of the node was retrieved successfully
00307    * @return aNodeName the name of the node
00308    * @throw ZorbaException if an error occured (e.g. the Item is not of type node).
00309    */
00310   bool
00311   getNodeName(Item& aNodeName) const;
00312 
00313   /** \brief Get the type of this (node) Item.
00314    *
00315    * Note that this function is only available for node Items.
00316    *
00317    * @return int the kind of this node (the avaialble kinds can be found in the store::StoreConsts class)
00318    * @throw ZorbaException if an error occured (e.g. the Item is not of type node).
00319    */
00320   int
00321   getNodeKind() const;
00322 
00323   /**
00324    * Checks whether the item's content is streamable.
00325    *
00326    * @return true only if it is.
00327    */
00328   bool
00329   isStreamable() const;
00330 
00331   /**
00332    * Gets an istream for the item's content.
00333    *
00334    * @return the stream.
00335    * @throw ZorbaException if the item is not streamable.
00336    */
00337   std::istream&
00338   getStream();
00339 
00340   /** \brief Returns the name of the collection this node is stored in.
00341    *
00342    * @return The name of the collection or 0 if the given item is not
00343    *   a node or not stored in a collection.
00344    */
00345   Item
00346   getCollectionName() const;
00347 
00348 private:
00349   friend class Unmarshaller;
00350 
00351   store::Item * m_item;
00352 private:
00353   //for plan serialization
00354   friend void zorba::serialization::operator&(zorba::serialization::Archiver &ar, Item &obj);
00355 };
00356 
00357 } // namespace zorba
00358 
00359 #endif
00360 /* vim:set et sw=2 ts=2: */
blog comments powered by Disqus