FDO API Reference | Feature Data Objects |
00001 #ifndef FDO_XML_FEATUREFLAGS_H 00002 #define FDO_XML_FEATUREFLAGS_H 00003 00004 // 00005 // Copyright (C) 2004-2006 Autodesk, Inc. 00006 // 00007 // This library is free software; you can redistribute it and/or 00008 // modify it under the terms of version 2.1 of the GNU Lesser 00009 // General Public License as published by the Free Software Foundation. 00010 // 00011 // This library is distributed in the hope that it will be useful, 00012 // but WITHOUT ANY WARRANTY; without even the implied warranty of 00013 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00014 // Lesser General Public License for more details. 00015 // 00016 // You should have received a copy of the GNU Lesser General Public 00017 // License along with this library; if not, write to the Free Software 00018 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 00019 // 00020 00021 #ifdef _WIN32 00022 #pragma once 00023 #endif 00024 00025 #include <FdoStd.h> 00026 #include <Fdo/Xml/Flags.h> 00027 00028 /// \brief 00029 /// FdoXmlFeatureFlags extends FdoXmlFlags to specify flags specific to feature 00030 /// serialization. 00031 /// \remarks 00032 /// The Error Levels inherited from FdoXmlFlags take on the following meaning when 00033 /// applied to features. Suppose we have GML Document A that conforms to GML Schema A. 00034 /// If Document A is read into FDO and then written to Document B then the Error Levels 00035 /// applied to the Document A read have the following meaning: 00036 /// <ul> 00037 /// <li>ErrorLevel_High: Document B will be structurally identical to Document A. 00038 /// Errors are issued if this cannot be guaranteed. Document B will have the 00039 /// exact same elements and attributes as Document A. 00040 /// <li>ErrorLevel_Normal: There is no information loss. Document B contains 00041 /// all of the information from Document A and Document B conforms to Schema A. 00042 /// Errors are issued if this cannot be guaranteed. 00043 /// However, Documents A and B might not look exactly alike; some Document A elements 00044 /// may have an equivalent but different structure in Document B. 00045 /// <li>ErrorLevel_Low: There can be information loss. Document B is a subset 00046 /// of Document A but still conforms to Schema A. Errors are issued if 00047 /// this cannot be guaranteed. Any Document A elements, not recognized by 00048 /// FDO, are discarded on read. 00049 /// <li>ErrorLevel_VeryLow: FDO does a best effort read of Document A and write of 00050 /// Document B. There is no guarantee that Document B will look anything like 00051 /// Document A or that Document B will conform to Schema A. 00052 /// </ul> 00053 /// 00054 /// The above assumes that FDO is not provided the GML form of Schema A when writing 00055 /// Document B. For example, supposed that FDO can write a Schema A conformant 00056 /// Document B only when supplied the GML version of Schema A. FDO will still generate 00057 /// errors and fail to read Document A under ErrorLevel_Low. 00058 class FdoXmlFeatureFlags : public FdoXmlFlags 00059 { 00060 public: 00061 /// \brief 00062 /// The FdoXmlFeatureFlags::ConflictOption specifies how to handle features that 00063 /// are already in the DataStore, when Deserializing: 00064 /// 00065 /// \param ConflictOption_Add 00066 /// just add new features to the FDO DataStore. If a feature already exists, an 00067 /// exception is thrown. 00068 /// \param ConflictOption_Update 00069 /// Update the feature if it already exists, add it if it doesn't exist. This is 00070 /// the slowest option, since the feature must be queried from the DataStore before 00071 /// it is inserted or updated. 00072 /// \param ConflictOption_Skip 00073 /// just add new features. Silently skip features already in the DataStore. 00074 /// 00075 enum ConflictOption { 00076 ConflictOption_Add, 00077 ConflictOption_Update, 00078 ConflictOption_Skip 00079 }; 00080 00081 /// \brief 00082 /// Constructs an FdoXmlFeatureFlags object. 00083 /// 00084 /// \param url 00085 /// See FdoXmlFlags::Create() 00086 /// \param errorLevel 00087 /// See FdoXmlFlags::Create() 00088 /// \param nameAdjust 00089 /// See FdoXmlFlags::Create() 00090 /// \param conflictOption 00091 /// Conflict option to apply to pre-existing features, when deserializing features 00092 /// into an FDO datastore. 00093 /// 00094 /// \return 00095 /// Returns FdoXmlFeatureFlags 00096 /// 00097 FDO_API static FdoXmlFeatureFlags* Create( 00098 FdoString* url = L"fdo.osgeo.org/schemas/feature", 00099 ErrorLevel errorLevel = ErrorLevel_Normal, 00100 FdoBoolean nameAdjust = true, 00101 ConflictOption conflictOption = ConflictOption_Add 00102 ); 00103 00104 /// \brief 00105 /// Sets the current option for handling features already in the connection 00106 /// datastore. 00107 /// 00108 /// \param conflictOption 00109 /// Specifies how feaures, already in the datastore, are handled. 00110 /// 00111 FDO_API virtual void SetConflictOption( ConflictOption conflictOption ); 00112 00113 /// \brief 00114 /// Get the current option for handling feature already in the connection datastore. 00115 /// 00116 /// \return 00117 /// Returns the current conflict option. 00118 /// 00119 FDO_API virtual ConflictOption GetConflictOption() const; 00120 00121 /// \brief 00122 /// Sets the write feature collection flag. This flag is initially set to true. 00123 /// 00124 /// \param writeMember 00125 /// Input 00126 /// true: The serialized features are wrapped in a GML FeatureCollection element. 00127 /// false: features are serialize without a wrapping collection element. 00128 /// 00129 FDO_API virtual void SetWriteCollection( FdoBoolean writeCollection ); 00130 00131 /// \brief 00132 /// Gets the write feature collection flag. 00133 /// 00134 /// \return 00135 /// Returns the write feature collection flag. 00136 /// 00137 FDO_API virtual FdoBoolean GetWriteCollection() const; 00138 00139 /// \brief 00140 /// Sets the write feature member flag. This flag is initially set to true. 00141 /// 00142 /// \param writeMember 00143 /// Input 00144 /// true: Each serialized feature is wrapped in a GML featureMember element. 00145 /// false: features are serialized without a wrapping member element. Normally, 00146 /// writeMember would only be set to false when writing values to a collection 00147 /// object property. 00148 /// 00149 FDO_API virtual void SetWriteMember( FdoBoolean writeMember ); 00150 00151 /// \brief 00152 /// Gets the write feature member flag. 00153 /// 00154 /// \return 00155 /// Returns the write feature member flag. 00156 /// 00157 FDO_API virtual FdoBoolean GetWriteMember() const; 00158 00159 /// \brief 00160 /// Sets the URI for the feature collection element to wrap around serialized 00161 /// features. The initial value is 'http://www.opengis.net/gml' 00162 /// 00163 /// \param uri 00164 /// Input the URI. If NULL or blank, the URI reverts back to the initial value. 00165 /// 00166 FDO_API virtual void SetCollectionUri( FdoString* uri ); 00167 00168 /// \brief 00169 /// Gets the feature collection element URI. 00170 /// 00171 /// \return 00172 /// Returns the URI. 00173 /// 00174 FDO_API virtual FdoString* GetCollectionUri() const; 00175 00176 /// \brief 00177 /// Sets the name for the feature collection element to wrap around serialized 00178 /// features. The initial value is 'FeatureCollection' 00179 /// 00180 /// \param name 00181 /// Input the name. If NULL or blank, the name reverts back to the initial value. 00182 /// 00183 FDO_API virtual void SetCollectionName( FdoString* name ); 00184 00185 /// \brief 00186 /// Gets the feature collection element name. 00187 /// 00188 /// \return 00189 /// Returns FdoString*. 00190 /// 00191 FDO_API virtual FdoString* GetCollectionName() const; 00192 00193 /// \brief 00194 /// Sets the URI for the feature member element to wrap around each serialized 00195 /// feature. The initial value is 'http://www.opengis.net/gml' 00196 /// 00197 /// \param uri 00198 /// Input the URI. If NULL or blank, the URI defaults to the URI of the feature 00199 /// collection element's sub-element. If this sub-element cannot be determined 00200 /// then the URI defaults to the initial value 00201 /// 00202 FDO_API virtual void SetMemberUri( FdoString* uri ); 00203 00204 /// \brief 00205 /// Gets the feature member element URI. 00206 /// 00207 /// \return 00208 /// Returns FdoString* 00209 /// 00210 FDO_API virtual FdoString* GetMemberUri() const; 00211 00212 /// \brief 00213 /// Sets the name for the feature member element to wrap around each serialized 00214 /// feature. The initial value is 'featureMember' 00215 /// 00216 /// \param name 00217 /// Input the name. If NULL or blank, the URI defaults to the name of the feature 00218 /// collection element's sub-element. If this sub-element cannot be determined then 00219 /// the name defaults to the initial value 00220 /// 00221 FDO_API virtual void SetMemberName( FdoString* name ); 00222 00223 /// \brief 00224 /// Gets the feature member element name. 00225 /// 00226 /// \return 00227 /// Returns FdoString*. 00228 /// 00229 FDO_API virtual FdoString* GetMemberName() const; 00230 00231 /// \brief 00232 /// Sets the GML ID prefix for writing features. This prefix is prepended to the 00233 /// gml:id value for each feature. When features from different FDO Datastores are 00234 /// serialized to the same GML document, it is recommended that a different GML ID 00235 /// prefix be used for each Datastore, to ensure that the gml:id values in the GML 00236 /// document are unique. The initial value is L"" (no prefix). 00237 /// 00238 /// \param prefix 00239 /// Input the GML ID Prefix 00240 /// 00241 FDO_API virtual void SetGmlIdPrefix( FdoString* prefix ); 00242 00243 /// \brief 00244 /// Gets the current GML ID prefix. 00245 /// 00246 /// \return 00247 /// Returns FdoString 00248 /// 00249 FDO_API virtual FdoString* GetGmlIdPrefix() const; 00250 00251 /// \brief 00252 /// Sets the schema locations for writing features. The output GML must have schema 00253 /// definition for all its referenced namespaces, e.g, gml namespace, wfs namespace, 00254 /// user defined namespace. There are default values for gml namespace schema location 00255 /// and wfs namespace schema location, so the user doesn't need to set locations for those 00256 /// two namespaces. But the user can still set values to override the default values. The 00257 /// user could call this function multiple times to set schema location for multiple namespace. 00258 /// 00259 /// \param nameSpace 00260 /// Namespace of which the schema location is to be set. Like "http://www.opengis.net/wfs" 00261 /// for wfs namespace. 00262 /// \param schemaLocation 00263 /// Standard URL indicating the schema location, like "http://schemas.opengeospatial.net/wfs/1.0.0/WFS-basic.xsd" 00264 /// for wfs namespace. 00265 /// 00266 FDO_API virtual void SetSchemaLocation(FdoString* nameSpace, FdoString* schemaLocation); 00267 00268 /// \brief 00269 /// Gets the schema location for the specified namespace. 00270 /// 00271 /// \param nameSpace 00272 /// Namespace of which the schema location is to be retrieved. Like "http://www.opengis.net/wfs" 00273 /// 00274 /// \return 00275 /// Returns the URL indicating the schema location. 00276 /// 00277 FDO_API virtual FdoString* GetSchemaLocation(FdoString* nameSpace); 00278 00279 /// \brief 00280 /// Gets all namespaces that have been set for schemaLocation by SetSchemaLocation(). 00281 /// 00282 /// \return 00283 /// Returns all namespaces that have been set for schemaLocation. 00284 /// 00285 FDO_API virtual FdoStringCollection* GetNamespaces(); 00286 00287 /// \brief 00288 /// Sets the default namespace which defines all feature/object types found in the input 00289 /// feature reader which is to be serialized. The user is also supposed to set the schema 00290 /// location for this namespace. 00291 /// 00292 /// \param defaultNamespace 00293 /// Default namespace. 00294 /// 00295 FDO_API virtual void SetDefaultNamespace(FdoString* defaultNamespace); 00296 00297 /// \brief 00298 /// Gets the default namespace. 00299 /// 00300 /// \return 00301 /// Returns the default namespace. 00302 /// 00303 FDO_API virtual FdoString* GetDefaultNamespace(); 00304 00305 protected: 00306 FdoXmlFeatureFlags(); 00307 FdoXmlFeatureFlags(FdoString* url, ErrorLevel errorLevel, FdoBoolean nameAdjust, ConflictOption conflictOption); 00308 virtual ~FdoXmlFeatureFlags(); 00309 00310 private: 00311 ConflictOption mConflictOption; 00312 FdoBoolean mWriteCollection; 00313 FdoBoolean mWriteMember; 00314 FdoStringP mCollectionUri; 00315 FdoStringP mCollectionName; 00316 FdoStringP mMemberUri; 00317 FdoStringP mMemberName; 00318 FdoStringP mGmlIdPrefix; 00319 FdoPtr<FdoStringCollection> mNamespaces; 00320 FdoPtr<FdoStringCollection> mSchemaLocations; 00321 FdoStringP mDefaultNamespace; 00322 00323 }; 00324 00325 /// \brief 00326 /// FdoXmlFeatureFlagsP is a FdoPtr on FdoXmlFeatureFlags, provided for convenience. 00327 typedef FdoPtr<FdoXmlFeatureFlags> FdoXmlFeatureFlagsP; 00328 00329 #endif 00330 00331
Comments or suggestions? Send us feedback. |