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