item_factory.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 
00017 #ifndef ZORBA_ITEM_FACTORY_API_H
00018 #define ZORBA_ITEM_FACTORY_API_H
00019 
00020 #include <iostream>
00021 #include <vector>
00022 
00023 #include <zorba/config.h>
00024 #include <zorba/api_shared_types.h>
00025 #include <zorba/streams.h>
00026 
00027 namespace zorba {
00028 
00029   /** \brief ItemFactory to create Items.
00030    *
00031    * An instance of this class can be obtained by calling getItemFactory on the Zorba object.
00032    *
00033    * Each createXXX function of this class creates an Item of an XML Schema item.
00034    * If an isNull() call on an Item created by one of these functions returns true the
00035    * Item could not be created.
00036    */
00037   class ZORBA_DLL_PUBLIC ItemFactory
00038   {
00039     public:
00040       /** \brief Destructor
00041        */
00042       virtual ~ItemFactory() {}
00043 
00044       /** \brief Creates a String Item
00045        *         see [http://www.w3.org/TR/xmlschema-2/#string]
00046        *
00047        * @param aString String representation of the String Item.
00048        * @return The String Item
00049        */
00050       virtual Item
00051       createString(const String& aString) = 0;
00052 
00053       /** \brief Creates a streamable String Item
00054        *         see [http://www.w3.org/TR/xmlschema-2/#string]
00055        *
00056        * @param stream An istream whence to read the string's content.
00057        * @param streamReleaser A function pointer which is invoked once
00058        *        the StreamableStringItem is destroyed. Normally this function
00059        *        will delete the std::istream object passed to it.
00060        * @param seekable
00061        * @return The streamable String Item
00062        */
00063       virtual Item
00064       createStreamableString( std::istream &stream,
00065                               StreamReleaser streamReleaser,
00066                               bool seekable = false ) = 0;
00067 
00068       /** \brief Creates an AnyURI Item
00069        *         see [http://www.w3.org/TR/xmlschema-2/#anyURI]
00070        *
00071        * @param aURI String representation of the AnyURI.
00072        * @return The AnyURI Item.
00073        */
00074       virtual Item
00075       createAnyURI(const String& aURI) = 0;
00076 
00077       /** \brief Creates a QName Item
00078        *         see [http://www.w3.org/TR/xmlschema-2/#QName]
00079        *
00080        * @param aNamespace String representation of the namespace.
00081        * @param aPrefix String representation of the prefix.
00082        * @param aLocalname String representation of the localname.
00083        *
00084        * @return The QName Item.
00085        */
00086       virtual Item
00087       createQName(const String& aNamespace, const String& aPrefix,
00088                   const String& aLocalname) = 0;
00089 
00090       /** \brief Creates a QName Item
00091        *         see [http://www.w3.org/TR/xmlschema-2/#QName]
00092        *
00093        * @param aNamespace String representation of the namespace.
00094        * @param aLocalname String representation of the localname.       *
00095        * @return The QName Item.
00096        */
00097       virtual Item
00098       createQName(const String& aNamespace, const String& aLocalname) = 0;
00099 
00100       /** \brief Creates a QName Item
00101        *         see [http://www.w3.org/TR/xmlschema-2/#QName]
00102        *
00103        * The QName is constructed by parsing the string using the notation
00104        * invented by James Clark (i.e. {namespace}localname).
00105        *
00106        * @param aQNameString String in the QName notation by James Clark.
00107        * @return The QName Item.
00108        */
00109       virtual Item
00110       createQName(const String& aQNameString) = 0;
00111 
00112       /** \brief Creates a NCName Item
00113        *         see [http://www.w3.org/TR/xmlschema-2/#NCName]
00114        *
00115        * @param aValue String representation of the NCName.
00116        * @return The NCName Item.
00117        */
00118       virtual Item
00119       createNCName(const String& aValue) = 0;
00120 
00121 
00122       /** \brief Creates a Base64Binary Item
00123        *         see [http://www.w3.org/TR/xmlschema-2/#base64Binary]
00124        *
00125        * @param aBinData a pointer to the base64 binary data.
00126        * @param aLength the length of the base64 binary data.
00127        * @return The Base64Binary Item.
00128        */
00129       virtual Item
00130       createBase64Binary(const char* aBinData, size_t aLength) = 0;
00131 
00132       /** \brief Creates a Base64Binary Item
00133        *         see [http://www.w3.org/TR/xmlschema-2/#base64Binary]
00134        *
00135        * @param aStream A stream containing the Base64 encoded data.
00136        * @return the Base64Binary Item.
00137        */
00138       virtual Item
00139       createBase64Binary(std::istream& aStream) = 0;
00140 
00141       /** \brief Creates a Base64Binary Item
00142        *         see [http://www.w3.org/TR/xmlschema-2/#base64Binary]
00143        *
00144        * @param aBinData the data in binary form. The data is copied from aBinData.
00145        * @param aLength the length of the data
00146        * @return the Base64Binary Item.
00147        */
00148       virtual Item 
00149       createBase64Binary(const unsigned char* aBinData, size_t aLength) = 0;
00150 
00151       /** \brief Creates a Boolean Item
00152        *         see [http://www.w3.org/TR/xmlschema-2/#bool]
00153        *
00154        * @param aValue bool representation of the Boolean.
00155        * @return The Boolean Item.
00156        */
00157       virtual Item
00158       createBoolean(bool aValue) = 0;
00159 
00160       /** \brief Creates a Decimal Item
00161        *         see [http://www.w3.org/TR/xmlschema-2/#decimal]
00162        *
00163        * @param aValue unsigned long representation of the Decimal.
00164        * @return The Decimal Item.
00165        */
00166       virtual Item
00167       createDecimalFromLong (unsigned long aValue) = 0;
00168 
00169       /** \brief Creates a Decimal Item
00170        *         see [http://www.w3.org/TR/xmlschema-2/#decimal]
00171        *
00172        * @param aValue double representation of the Decimal.
00173        * @return The Decimal Item.
00174        */
00175       virtual Item
00176       createDecimalFromDouble (double aValue) = 0;
00177 
00178       /** \brief Creates a Decimal Item
00179        *         see [http://www.w3.org/TR/xmlschema-2/#decimal]
00180        *
00181        * @param aValue String representation of the Decimal (e.g. 12678967.543233).
00182        * @return The Decimal Item.
00183        */
00184       virtual Item
00185       createDecimal (const String& aValue) = 0;
00186 
00187       /** \brief Creates an Integer Item
00188        *         see [http://www.w3.org/TR/xmlschema-2/#integer]
00189        *
00190        * @param aInteger unsigned long representation of the Integer.
00191        * @return The Integer Item.
00192        */
00193       virtual Item
00194       createInteger(long long aInteger) = 0;
00195 
00196       /** \brief Creates an Integer Item
00197        *         see [http://www.w3.org/TR/xmlschema-2/#integer]
00198        *
00199        * @param aInteger String representation of the Integer.
00200        * @return The Integer Item.
00201        */
00202       virtual Item
00203       createInteger(const String& aInteger) = 0;
00204 
00205       /** \brief Creates a Long Item
00206        *         see [http://www.w3.org/TR/xmlschema-2/#long]
00207        *
00208        * @param aLong long long representation of the Long.
00209        * @return The Long Item.
00210        */
00211       virtual Item
00212       createLong ( long long aLong ) = 0;
00213 
00214       /** \brief Creates a Int Item
00215        *         see [http://www.w3.org/TR/xmlschema-2/#int]
00216        *
00217        * @param aInt int representation of the Int.
00218        * @return The NCName Item.
00219        */
00220       virtual Item
00221       createInt ( int aInt ) = 0;
00222 
00223       /** \brief Creates a Short Item
00224        *         see [http://www.w3.org/TR/xmlschema-2/#short]
00225        *
00226        * @param aShort short representation of the Short.
00227        * @return The Short Item.
00228        */
00229       virtual Item
00230       createShort ( short aShort ) = 0;
00231 
00232       /** \brief Creates a Byte Item
00233        *         see [http://www.w3.org/TR/xmlschema-2/#byte]
00234        *
00235        * @param aByte char representation of the Byte.
00236        * @return The Byte Item.
00237        */
00238       virtual Item
00239       createByte ( char aByte ) = 0;
00240 
00241       /** \brief Creates a Date Item
00242        *         see [http://www.w3.org/TR/xmlschema-2/#date]
00243        *
00244        * @param aDate String representation of the Date (e.g. 2002-10-10).
00245        * @return The Date Item.
00246        */
00247       virtual Item
00248       createDate ( const String& aDate ) = 0;
00249 
00250       /** \brief Creates a Date Item
00251        *         see [http://www.w3.org/TR/xmlschema-2/#date]
00252        *
00253        * @param aYear short-valued representation of the year.
00254        * @param aMonth short-valued representation of the month.
00255        * @param aDay short-valued representation of the day.
00256        * @return The Date Item.
00257        */
00258       virtual Item
00259       createDate ( short aYear, short aMonth, short aDay ) = 0;
00260 
00261       /** \brief Creates a DateTime Item
00262        *         see [http://www.w3.org/TR/xmlschema-2/#dateTime]
00263        *
00264        * @param aYear short-valued representation of the year.
00265        * @param aMonth short-valued representation of the month.
00266        * @param aDay short-valued representation of the day.
00267        * @param aHour short-valued representation of the hour.
00268        * @param aMinute short-valued representation of the minute.
00269        * @param aSecond double-valued representation of the seconds and fractional seconds.
00270        * @param aTimeZone_hours short-valued representation of the difference in hours to UTC.
00271        * @return The DateTime Item.
00272        */
00273       virtual Item
00274       createDateTime(short aYear, short aMonth, short aDay,
00275                      short aHour, short aMinute, double aSecond,
00276                      short aTimeZone_hours) = 0;
00277 
00278       /** \brief Creates a DateTime Item
00279        *         see [http://www.w3.org/TR/xmlschema-2/#dateTime]
00280        *
00281        * @param aDateTimeValue String representation of the datetime value
00282        *        (for example, 2002-10-10T12:00:00-05:00).
00283        * @return The DateTime Item.
00284        */
00285       virtual Item
00286       createDateTime( const String& aDateTimeValue ) = 0;
00287 
00288       /** \brief Creates a Double Item
00289        *         see [http://www.w3.org/TR/xmlschema-2/#double]
00290        *
00291        * @param aValue double representation of the Double.
00292        * @return The Double Item.
00293        */
00294       virtual Item
00295       createDouble ( double aValue ) = 0;
00296 
00297       /** \brief Creates a Double Item
00298        *         see [http://www.w3.org/TR/xmlschema-2/#double]
00299        *
00300        * @param aValue String representation of the Double.
00301        * @return The Double Item.
00302        */
00303       virtual Item
00304       createDouble ( const String& aValue ) = 0;
00305 
00306       /** \brief Creates a Duration Item
00307        *         see [http://www.w3.org/TR/xmlschema-2/#duration]
00308        *
00309        * @param aValue String representation of the NCName.
00310        * @return The Duration Item.
00311        */
00312       virtual Item
00313       createDuration( const String& aValue ) = 0;
00314 
00315       /** \brief Creates a Duration Item
00316        *         see [http://www.w3.org/TR/xmlschema-2/#duration]
00317        *
00318        * @param aYear short-valued representation of the years.
00319        * @param aMonths short-valued representation of the months.
00320        * @param aDays short-valued representation of the days.
00321        * @param aHours short-valued representation of the hours.
00322        * @param aMinutes short-valued representation of the minutes.
00323        * @param aSeconds double-valued representation of the seconds and fractional seconds.
00324        * @return The Duration Item.
00325        */
00326       virtual Item
00327       createDuration ( short aYear, short aMonths, short aDays,
00328                        short aHours, short aMinutes, double aSeconds ) = 0;
00329 
00330       /** \brief creates a float item
00331        *         see [http://www.w3.org/tr/xmlschema-2/#float]
00332        *
00333        * @param aValue string representation of the float.
00334        * @return the float item.
00335        */
00336       virtual Item
00337       createFloat ( const String& aValue ) = 0;
00338 
00339       /** \brief creates a float item
00340        *         see [http://www.w3.org/tr/xmlschema-2/#float]
00341        *
00342        * @param aValue float representation of the float.
00343        * @return the float item.
00344        */
00345       virtual Item
00346       createFloat ( float aValue ) = 0;
00347 
00348       /** \brief Creates a gDay Item
00349        *         see [http://www.w3.org/TR/xmlschema-2/#gDay]
00350        *
00351        * @param aValue String representation of the gDay.
00352        * @return The gDay Item.
00353        */
00354       virtual Item
00355       createGDay ( const String& aValue ) = 0;
00356 
00357       /** \brief Creates a gDay Item
00358        *         see [http://www.w3.org/TR/xmlschema-2/#gDay]
00359        *
00360        * @param aDay short representation of the gDay.
00361        * @return The gDay Item.
00362        */
00363       virtual Item
00364       createGDay ( short aDay ) = 0;
00365 
00366       /** \brief Creates a gMonth Item
00367        *         see [http://www.w3.org/TR/xmlschema-2/#gMonth]
00368        *
00369        * @param aValue String representation of the gMonth.
00370        * @return The gMonth Item.
00371        */
00372       virtual Item
00373       createGMonth ( const String& aValue ) = 0;
00374 
00375       /** \brief Creates a gMonth Item
00376        *         see [http://www.w3.org/TR/xmlschema-2/#gMonth]
00377        *
00378        * @param aMonth short representation of the gMonth.
00379        * @return The gMonth Item.
00380        */
00381       virtual Item
00382       createGMonth ( short aMonth ) = 0;
00383 
00384       /** \brief Creates a gMonthDay Item
00385        *         see [http://www.w3.org/TR/xmlschema-2/#gMonthDay]
00386        *
00387        * @param aValue String representation of the gMonthDay.
00388        * @return The gMonthDay Item.
00389        */
00390       virtual Item
00391       createGMonthDay ( const String& aValue ) = 0;
00392 
00393       /** \brief Creates a gMonthDay Item
00394        *         see [http://www.w3.org/TR/xmlschema-2/#gMonthDay]
00395        *
00396        * @param aMonth short representation of the month.
00397        * @param aDay short representation of the day.
00398        * @return The gMonthDay Item.
00399        */
00400       virtual Item
00401       createGMonthDay ( short aMonth, short aDay ) = 0;
00402 
00403       /** \brief Creates a gYear Item
00404        *         see [http://www.w3.org/TR/xmlschema-2/#gYear]
00405        *
00406        * @param aValue String representation of the gYear.
00407        * @return The gYear Item.
00408        */
00409       virtual Item
00410       createGYear ( const String& aValue ) = 0;
00411 
00412       /** \brief Creates a gYear Item
00413        *         see [http://www.w3.org/TR/xmlschema-2/#gYear]
00414        *
00415        * @param aYear short representation of the gYear.
00416        * @return The gYear Item.
00417        */
00418       virtual Item
00419       createGYear ( short aYear ) = 0;
00420 
00421       /** \brief Creates a gYearMonth Item
00422        *         see [http://www.w3.org/TR/xmlschema-2/#gYearMonth]
00423        *
00424        * @param aValue String representation of the gYearMonth.
00425        * @return The gYearMonth Item.
00426        */
00427       virtual Item
00428       createGYearMonth ( const String& aValue ) = 0;
00429 
00430       /** \brief Creates a gYearMonth Item
00431        *         see [http://www.w3.org/TR/xmlschema-2/#gYearMonth]
00432        *
00433        * @param aYear short representation of the year.
00434        * @param aMonth short representation of the month.
00435        * @return The gYearMonth Item.
00436        */
00437       virtual Item
00438       createGYearMonth ( short aYear, short aMonth ) = 0;
00439 
00440       /** \brief Creates a HexBinary Item
00441        *         see [http://www.w3.org/TR/xmlschema-2/#hexBinary]
00442        *
00443        * @param aHexData pointer to the hexdata.
00444        * @param aSize size of the hexdata.
00445        * @return The HexBinary Item.
00446        */
00447       virtual Item
00448       createHexBinary ( const char* aHexData, size_t aSize ) = 0;
00449 
00450       /** \brief Creates a negativeInteger Item
00451        *         see [http://www.w3.org/TR/xmlschema-2/#negativeInteger]
00452        *
00453        * @param aValue long long representation of the negativeInteger.
00454        * @return The negativeInteger Item.
00455        */
00456       virtual Item
00457       createNegativeInteger ( long long aValue ) = 0;
00458 
00459       /** \brief Creates a nonNegativeInteger Item
00460        *         see [http://www.w3.org/TR/xmlschema-2/#nonNegativeInteger]
00461        *
00462        * @param aValue unsigned long representation of the nonNegativeInteger.
00463        * @return The nonNegativeInteger Item.
00464        */
00465       virtual Item
00466       createNonNegativeInteger ( unsigned long long aValue ) = 0;
00467 
00468       /** \brief Creates a nonPositiveInteger Item
00469        *         see [http://www.w3.org/TR/xmlschema-2/#nonPositiveInteger]
00470        *
00471        * @param aValue long long representation of the NCName.
00472        * @return The nonPositiveInteger Item.
00473        */
00474       virtual Item
00475       createNonPositiveInteger ( long long aValue ) = 0;
00476 
00477       /** \brief Creates a positiveInteger\ Item
00478        *         see [http://www.w3.org/TR/xmlschema-2/#positiveInteger]
00479        *
00480        * @param aValue unsigned long representation of the positiveInteger.
00481        * @return The positiveInteger Item.
00482        */
00483       virtual Item
00484       createPositiveInteger ( unsigned long long aValue ) = 0;
00485 
00486       /** \brief Creates a Time Item
00487        *         see [http://www.w3.org/TR/xmlschema-2/#time]
00488        *
00489        * @param aValue String representation of the Time.
00490        * @return The Time Item
00491        */
00492       virtual Item
00493       createTime ( const String& aValue ) = 0;
00494 
00495       /** \brief Creates a Time Item
00496        *         see [http://www.w3.org/TR/xmlschema-2/#time]
00497        *
00498        * @param aHour short representation of the hour.
00499        * @param aMinute short representation of the minute.
00500        * @param aSecond double representation of the seconds and fractional seconds.
00501        * @return The Time Item.
00502        */
00503       virtual Item
00504       createTime ( short aHour, short aMinute, double aSecond ) = 0;
00505 
00506       /** \brief Creates a Time Item
00507        *         see [http://www.w3.org/TR/xmlschema-2/#time]
00508        *
00509        * @param aHour short representation of the hour.
00510        * @param aMinute short representation of the minute.
00511        * @param aSecond double representation of the seconds and fractional seconds.
00512        * @param aTimeZone_hours short representation of the timezone difference in hours to UTC.
00513        * @return The Time Item.
00514        */
00515       virtual Item
00516       createTime ( short aHour, short aMinute, double aSecond, short aTimeZone_hours ) = 0;
00517 
00518       /** \brief Creates an Unsigned Byte Item
00519        *         see [http://www.w3.org/TR/xmlschema-2/#unsignedByte]
00520        *
00521        * @param aValue unsignedByte unsigned char representation of the unsigned byte.
00522        * @return The Unsigned Byte Item.
00523        */
00524       virtual Item
00525       createUnsignedByte(const unsigned char aValue) = 0;
00526 
00527       /** \brief Creates an unsigned int Item
00528        *         see [http://www.w3.org/TR/xmlschema-2/#unsignedInt]
00529        *
00530        * @param aValue unsigned int representation of the unsignedInt.
00531        * @return The unsignedInt Item.
00532        */
00533       virtual Item
00534       createUnsignedInt(unsigned int aValue) = 0;
00535 
00536       /** \brief Creates an unsignedLong Item
00537        *         see [http://www.w3.org/TR/xmlschema-2/#unsignedLong]
00538        *
00539        * @param aValue unsignedLong long long representation of the unsignedLong.
00540        * @return The unsignedLong Item.
00541        */
00542       virtual Item
00543       createUnsignedLong(unsigned long long aValue) = 0;
00544 
00545       /** \brief Creates a unsignedShort Item
00546        *         see [http://www.w3.org/TR/xmlschema-2/#unsignedShort]
00547        *
00548        * @param aValue unsigned short representation of the unsignedShort.
00549        * @return The unsignedShort Item.
00550        */
00551       virtual Item
00552       createUnsignedShort(unsigned short aValue) = 0;
00553 
00554       /**
00555       * @brief Creates a new element node.
00556       *
00557       * Create a new element node N and place it at the  end among the
00558       * children of a given parent node. If no parent is given, N becomes the
00559       * root (and single node) of a new XML tree.
00560       *
00561       * @param aParent        The parent P of the new node; may be NULL.
00562       * @param aNodeName      The fully qualified name of the new node.
00563       * @param aTypeName      The fully qualified name of the new node's type.
00564       *                       Not allowed to be NULL, use xsd:untyped instead.
00565       * @param aHasTypedValue Whether the node has a typed value or not (element
00566       *                       nodes with complex type and element-only content do
00567       *                       not have typed value).
00568       * @param aHasEmptyValue True if the typed value of the node is the empty
00569       *                       sequence. This is the case if the element has a
00570       *                       complex type with empty content.
00571       * @param aNsBindings    A set of namespace bindings. The namespaces property
00572       *                       of N will be the union of this set and the namespaces
00573       *                       property of P.
00574       * @return               The new node N created by this method
00575       */
00576       virtual Item
00577       createElementNode(Item& aParent,
00578                         Item aNodeName,
00579                         Item aTypeName,
00580                         bool aHasTypedValue,
00581                         bool aHasEmptyValue,
00582                         std::vector<std::pair<String, String> > aNsBindings) = 0;
00583 
00584       /**
00585       * Create a new attribute node N and place it among the
00586       * attributes of a given parent node. If no parent is given, N becomes the
00587       * root (and single node) of a new XML tree.
00588       *
00589       * @param aParent     The parent P of the new node; may be NULL.
00590       * @param aNodeName   The fully qualified name of the new node. The nemaspace
00591       *                    binding implied by this name will be added to the namespaces
00592       *                    of P. If the name prefix is "xml" and the local name is
00593       *                    "base", then the base-uri property of P will be set or
00594       *                    updated accordingly.
00595       * @param aTypeName   The fully qualified name of the new node's type.
00596       * @param aTypedValue The typed value of the new node.
00597       * @return            The new node N created by this method
00598       */
00599       virtual Item
00600       createAttributeNode(Item aParent,
00601                           Item aNodeName,
00602                           Item aTypeName,
00603                           Item aTypedValue) = 0;
00604 
00605       virtual Item
00606         createAttributeNode(Item aParent,
00607         Item aNodeName,
00608         Item aTypeName,
00609         std::vector<Item> aTypedValue) = 0;
00610 
00611       /**
00612       * Create a new text node N and place it among the
00613       * children of a given parent node. If no parent is given, N becomes the
00614       * root (and single node) of a new XML tree.
00615       *
00616       * @param parent  The parent P of the new node; may be NULL.
00617       * @param content The content of the new node.
00618       * @return        The new node N created by this method
00619       */
00620       virtual Item createTextNode(
00621         Item   parent,
00622         String content) = 0;
00623 }; // class ItemFactory
00624 
00625 } // namespace zorba
00626 #endif
00627 /* vim:set et sw=2 ts=2: */
blog comments powered by Disqus