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