FDO .NET API Reference Feature Data Objects

mgXmlFeatureReader.h

Go to the documentation of this file.
00001 /*
00002 * Copyright (C) 2004-2006  Autodesk, Inc.
00003 * 
00004 * This library is free software; you can redistribute it and/or
00005 * modify it under the terms of version 2.1 of the GNU Lesser
00006 * General Public License as published by the Free Software Foundation.
00007 * 
00008 * This library is distributed in the hope that it will be useful,
00009 * but WITHOUT ANY WARRANTY; without even the implied warranty of
00010 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00011 * Lesser General Public License for more details.
00012 * 
00013 * You should have received a copy of the GNU Lesser General Public
00014 * License along with this library; if not, write to the Free Software
00015 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
00016 *
00017 */
00018 
00019 #pragma  once
00020 
00021 #include "FDO\Commands\Feature\mgIFeatureReader.h"
00022 #include "FDO\Xml\mgXmlFeatureHandler.h"
00023 
00024 class FdoXmlFeatureReader;
00025 
00026 BEGIN_NAMESPACE_OSGEO_COMMON_XML
00027 public __gc class XmlReader;
00028 END_NAMESPACE_OSGEO_COMMON_XML
00029 
00030 BEGIN_NAMESPACE_OSGEO_FDO_SCHEMA
00031 public __gc class FeatureSchemaCollection;
00032 END_NAMESPACE_OSGEO_FDO_SCHEMA
00033 
00034 BEGIN_NAMESPACE_OSGEO_FDO_XML
00035 public __gc class XmlFeatureFlags;
00036 public __gc class XmlFeaturePropertyReader;
00037 
00038 /// \ingroup (OSGeoFDOXml)
00039 /// \brief
00040 /// XmlFeatureReader reads GML format features from a XML
00041 /// document. The reading is done procedurally, rather than through events.
00042 /// \remarks
00043 /// Each feature can be read in 3 steps:
00044 /// <ol>
00045 ///     <li>call ReadNext() to get the next feature.
00046 ///     <li>call GetClassDefinition() to get the current feature's property list.
00047 ///     <li>call GetProperty() for each feature property to retrieve.
00048 /// </ol>
00049 /// This class allows random access to the properties of the current feature, meaning that 
00050 /// ReadNext() accumulates a list of these properties. This may have slight performance implications.
00051 /// If performance is a concern then XmlFeaturePropertyReader should be used instead.
00052 public __gc class XmlFeatureReader : public NAMESPACE_OSGEO_FDO_XML::XmlFeatureHandler, public NAMESPACE_OSGEO_FDO_COMMANDS_FEATURE::IFeatureReader
00053 {
00054 public:
00055     /// \brief
00056     /// creates a Feature Reader for reading features from XML.
00057     /// 
00058     /// \param reader 
00059     /// Input XML document reader. Please refer to the reader parameter of 
00060     /// XmlFeaturePropertyReader::Create() for a description of how the features are
00061     /// read from the document. An XmlFeaturePropertyReader is automatically wrapped 
00062     /// around this reader. This Feature Property Reader can be retrieved by calling 
00063     /// GetFeaturePropertyReader().
00064     /// 
00065     XmlFeatureReader(NAMESPACE_OSGEO_COMMON_XML::XmlReader* reader);
00066 
00067     /// \brief
00068     /// creates a Feature Reader for reading features from XML.
00069     /// 
00070     /// \param reader 
00071     /// Input XML document reader. Please refer to the reader parameter of 
00072     /// XmlFeaturePropertyReader::Create() for a description of how the features are
00073     /// read from the document. An XmlFeaturePropertyReader is automatically wrapped 
00074     /// around this reader. This Feature Property Reader can be retrieved by calling 
00075     /// GetFeaturePropertyReader().
00076     /// \param flags 
00077     /// Input options for controlling the 
00078     /// deserializing of the features. If NULL then the 
00079     /// default flags are used.
00080     /// 
00081     XmlFeatureReader(NAMESPACE_OSGEO_COMMON_XML::XmlReader* reader, NAMESPACE_OSGEO_FDO_XML::XmlFeatureFlags* flags);
00082 
00083     /// \brief
00084     /// Gets the feature property reader that was passed to this object.
00085     /// 
00086     /// \return
00087     /// Returns XmlFeaturePropertyReader
00088     /// 
00089     NAMESPACE_OSGEO_FDO_XML::XmlFeaturePropertyReader* GetFeaturePropertyReader();
00090 
00091     /// \brief
00092     /// Gets the feature schemas describing the features being read.
00093     /// 
00094     /// \return
00095     /// Returns FeatureSchemaCollection
00096     /// 
00097     __property NAMESPACE_OSGEO_FDO_SCHEMA::FeatureSchemaCollection* get_FeatureSchemas();
00098 
00099     /// \brief
00100     /// Sets the feature schemas describing the features being read. 
00101     /// 
00102     /// \remarks
00103     /// The feature schemas
00104     /// provide directions on how to deserialize the features and convert their property
00105     /// values from the strings in the XML document to their proper types. If any 
00106     /// feature, whose class definition is not present in these schemas, is encountered 
00107     /// then one of the following is done:
00108     /// <ul>
00109     ///     <li> an exception is thrown when flags->errorLevel is Normal or higher. The 
00110     ///       exception reports all such features.
00111     ///     <li> these features are silently skipped When the flags->errorLevel is below 
00112     ///       Normal.
00113     /// </ul>
00114     /// 
00115     /// \param schemas 
00116     /// Input the feature schemas
00117     /// 
00118     __property System::Void set_FeatureSchemas(NAMESPACE_OSGEO_FDO_SCHEMA::FeatureSchemaCollection* schemas);
00119 
00120     /*
00121         IFeatureReader implementation
00122     */
00123 
00124     /// \brief
00125     /// Gets the definition of the object currently being read. If the user
00126     /// has requested only a subset of the class properties, the class 
00127     /// definition reflects what the user has asked, rather than the full class 
00128     /// definition.
00129     /// 
00130     /// \return
00131     /// Returns the class definition object.
00132     /// 
00133     NAMESPACE_OSGEO_FDO_SCHEMA::ClassDefinition* GetClassDefinition();
00134 
00135     /// \brief
00136     /// Gets a value indicating the depth of nesting for the current reader.
00137     /// The depth value increases each time GetFeatureObject is called and a new 
00138     /// reader is returned. The outermost reader has a depth of 0.
00139     /// 
00140     /// \return
00141     /// Returns the depth
00142     /// 
00143     System::Int32 GetDepth();
00144 
00145     /// \brief
00146     /// Gets a reference to an IFeatureReader to read the data contained in
00147     /// the object or object collection property. If the property is not an
00148     /// object property, an exception is thrown.
00149     /// 
00150     /// \param propertyName 
00151     /// Input the property name.
00152     /// 
00153     /// \return
00154     /// Returns the nested feature reader
00155     /// 
00156     NAMESPACE_OSGEO_FDO_COMMANDS_FEATURE::IFeatureReader* GetFeatureObject(System::String* propertyName);
00157 
00158     /*
00159         IReader implementation
00160     */
00161 
00162     /// \brief
00163     /// Gets the Boolean value of the specified property. No conversion is
00164     /// performed, thus the property must be DataType_Boolean or an 
00165     /// exception is thrown.
00166     /// 
00167     /// \param name 
00168     /// Input the property name.
00169     /// 
00170     /// \return
00171     /// Returns the Boolean value.
00172     /// 
00173     System::Boolean GetBoolean(System::String* name);
00174 
00175     /// \brief
00176     /// Gets the byte value of the specified property. No conversion is 
00177     /// performed, thus the property must be DataType_Byte or an 
00178     /// exception is thrown.
00179     /// 
00180     /// \param name 
00181     /// Input the property name.
00182     /// 
00183     /// \return
00184     /// Returns the byte value.
00185     /// 
00186     System::Byte GetByte(System::String* name);
00187 
00188     /// \brief
00189     ///  Gets the date and time value of the specified property. No conversion is 
00190     /// performed, thus the property must be DataType_DateTime or an 
00191     /// exception is thrown.
00192     /// 
00193     /// \param name 
00194     /// Input the property name.
00195     /// 
00196     /// \return
00197     /// Returns the date and time value.
00198     /// 
00199     System::DateTime GetDateTime(System::String* name);
00200 
00201     /// \brief
00202     /// Gets the double-precision floating point value of the specified property. No
00203     /// conversion is performed, thus the property must be DataType_Double
00204     /// or an exception is thrown.
00205     /// 
00206     /// \param name 
00207     /// Input the property name.
00208     /// 
00209     /// \return
00210     /// Returns the double floating point value
00211     /// 
00212     System::Double GetDouble(System::String* name);
00213 
00214     /// \brief
00215     /// Gets the 16-bit integer value of the specified property. No conversion is
00216     /// performed, thus the property must be DataType_Int16 or an exception
00217     /// is thrown.
00218     /// 
00219     /// \param name 
00220     /// Input the property name.
00221     /// 
00222     /// \return
00223     /// Returns the System::Int16 value.
00224     /// 
00225     System::Int16 GetInt16(System::String* name);
00226 
00227     /// \brief
00228     /// Gets the 32-bit integer value of the specified property. No conversion is
00229     /// performed, thus the property must be DataType_Int32 or an exception
00230     /// is thrown.
00231     /// 
00232     /// \param name 
00233     /// Input the property name.
00234     /// 
00235     /// \return
00236     /// Returns the System::Int32 value
00237     /// 
00238     System::Int32 GetInt32(System::String* name);
00239 
00240     /// \brief
00241     /// Gets the 64-bit integer value of the specified property. No conversion is
00242     /// performed, thus the property must be DataType_Int64 or an exception
00243     /// is thrown.
00244     /// 
00245     /// \param name 
00246     /// Input the property name.
00247     /// 
00248     /// \return
00249     /// Returns the System::Int63 value.
00250     /// 
00251     System::Int64 GetInt64(System::String* name);
00252 
00253     /// \brief
00254     /// Gets the Single floating point value of the specified property. No
00255     /// conversion is performed, thus the property must be DataType_Single
00256     /// or an exception is thrown.
00257     /// 
00258     /// \param name 
00259     /// Input the property name.
00260     /// 
00261     /// \return
00262     /// Returns the single value
00263     /// 
00264     System::Single GetSingle(System::String* name);
00265 
00266     /// \brief
00267     /// Gets the string value of the specified property. No conversion is
00268     /// performed, thus the property must be DataType_String or an exception
00269     /// is thrown.
00270     /// 
00271     /// \param name 
00272     /// Input the property name.
00273     /// 
00274     /// \return
00275     /// Returns the string value
00276     /// 
00277     System::String* GetString(System::String* name);
00278 
00279     /// \brief
00280     /// Gets a LOBValue reference. The LOB is fully read in and data available.
00281     /// Because no conversion is performed, the property must be DataType_BLOB or
00282     /// DataType_CLOB etc. (a LOB type)
00283     /// 
00284     /// \param name 
00285     /// Input the property name.
00286     /// 
00287     /// \return
00288     /// Returns the reference to LOBValue
00289     /// 
00290     NAMESPACE_OSGEO_FDO_EXPRESSION::LOBValue* GetLOB(System::String* name);
00291 
00292     /// \brief
00293     /// Gets a reference of the specified LOB property as a BLOBStreamReader or
00294     /// CLOBStreamReader etc. to allow reading in blocks of data.
00295     /// Because no conversion is performed, the property must be DataType_BLOB 
00296     /// or DataType_CLOB etc. (a LOB type)
00297     /// Cast the IStreamReader to the appropiate LOB Stream Reader.
00298     /// 
00299     /// \param name 
00300     /// Input the property name.
00301     /// 
00302     /// \return
00303     /// Returns a reference to a LOB stream reader
00304     /// 
00305     NAMESPACE_OSGEO_COMMON::IStreamReader* GetLOBStreamReader(System::String* name);
00306 
00307     /// \brief
00308     /// Returns true if the value of the specified property is null.
00309     /// 
00310     /// \param name 
00311     /// Input the property name.
00312     /// 
00313     /// \return
00314     /// Returns true if the value is null.
00315     /// 
00316     System::Boolean IsNull(System::String* name);
00317 
00318     /// \brief
00319     /// Gets the geometry value of the specified property as a byte array in 
00320     /// FGF format. Because no conversion is performed, the property must be
00321     /// of Geometric type; otherwise, an exception is thrown.
00322     /// 
00323     /// \param name 
00324     /// Input the property name.
00325     /// 
00326     /// \return
00327     /// Returns the byte array in FGF format.
00328     /// 
00329     System::Byte GetGeometry(System::String* name) [];
00330 
00331     /// \brief
00332     /// Gets the raster object of the specified property.
00333     /// Because no conversion is performed, the property must be
00334     /// of Raster type; otherwise, an exception is thrown.
00335     /// 
00336     /// \param name 
00337     /// Input the property name.
00338     /// 
00339     /// \return
00340     /// Returns the raster object.
00341     /// 
00342     NAMESPACE_OSGEO_FDO_RASTER::IRaster* GetRaster(System::String* name);
00343 
00344     /// \brief
00345     /// Advances the reader to the next item and returns true if there is
00346     /// another object to read or false if reading is complete. The default
00347     /// position of the reader is prior to the first item. Thus you must
00348     /// call ReadNext to begin accessing any data.
00349     /// 
00350     /// \return
00351     /// Returns true if there is a next item.
00352     /// 
00353     System::Boolean ReadNext();
00354 
00355     /// \brief
00356     /// Closes the IFeatureReader object, freeing any resources it may be holding.
00357     /// 
00358     System::Void Close();
00359 
00360 public private:
00361     XmlFeatureReader(System::IntPtr unmanaged, System::Boolean autoDelete) : NAMESPACE_OSGEO_FDO_XML::XmlFeatureHandler(unmanaged, autoDelete)
00362     {
00363         
00364     }
00365 
00366     inline FdoXmlFeatureReader* GetImpObj();
00367 };
00368 
00369 END_NAMESPACE_OSGEO_FDO_XML
00370 
00371 

Comments or suggestions? Send us feedback.