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: */