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 enum ConflictOption { 00065 /// Add new features to the FDO DataStore and if a feature already exists, 00066 /// throw an exception. 00067 ConflictOption_Add, 00068 /// Update the feature if it already exists, add it if it doesn't exist. 00069 /// This is the slowest option, since the feature must be queried from the DataStore 00070 /// before it is inserted or updated. 00071 ConflictOption_Update, 00072 /// Add new features and silently skip features already in the DataStore. 00073 ConflictOption_Skip 00074 }; 00075 00076 /// \brief 00077 /// Constructs an FdoXmlFeatureFlags object. 00078 /// 00079 /// \param url 00080 /// See FdoXmlFlags::Create() 00081 /// \param errorLevel 00082 /// See FdoXmlFlags::Create() 00083 /// \param nameAdjust 00084 /// See FdoXmlFlags::Create() 00085 /// \param conflictOption 00086 /// Conflict option to apply to pre-existing features, when deserializing features 00087 /// into an FDO datastore. 00088 /// 00089 /// \return 00090 /// Returns FdoXmlFeatureFlags 00091 /// 00092 FDO_API static FdoXmlFeatureFlags* Create( 00093 FdoString* url = L"fdo.osgeo.org/schemas/feature", 00094 ErrorLevel errorLevel = ErrorLevel_Normal, 00095 FdoBoolean nameAdjust = true, 00096 ConflictOption conflictOption = ConflictOption_Add 00097 ); 00098 00099 /// \brief 00100 /// Sets the current option for handling features already in the connection 00101 /// datastore. 00102 /// 00103 /// \param conflictOption 00104 /// Specifies how feaures, already in the datastore, are handled. 00105 /// 00106 FDO_API virtual void SetConflictOption( ConflictOption conflictOption ); 00107 00108 /// \brief 00109 /// Get the current option for handling feature already in the connection datastore. 00110 /// 00111 /// \return 00112 /// Returns the current conflict option. 00113 /// 00114 FDO_API virtual ConflictOption GetConflictOption() const; 00115 00116 /// \brief 00117 /// Sets the write feature collection flag. This flag is initially set to true. 00118 /// 00119 /// \param writeCollection 00120 /// Input 00121 /// true: The serialized features are wrapped in a GML FeatureCollection element. 00122 /// false: features are serialize without a wrapping collection element. 00123 /// 00124 FDO_API virtual void SetWriteCollection( FdoBoolean writeCollection ); 00125 00126 /// \brief 00127 /// Gets the write feature collection flag. 00128 /// 00129 /// \return 00130 /// Returns the write feature collection flag. 00131 /// 00132 FDO_API virtual FdoBoolean GetWriteCollection() const; 00133 00134 /// \brief 00135 /// Sets the write feature member flag. This flag is initially set to true. 00136 /// 00137 /// \param writeMember 00138 /// Input 00139 /// true: Each serialized feature is wrapped in a GML featureMember element. 00140 /// false: features are serialized without a wrapping member element. Normally, 00141 /// writeMember would only be set to false when writing values to a collection 00142 /// object property. 00143 /// 00144 FDO_API virtual void SetWriteMember( FdoBoolean writeMember ); 00145 00146 /// \brief 00147 /// Gets the write feature member flag. 00148 /// 00149 /// \return 00150 /// Returns the write feature member flag. 00151 /// 00152 FDO_API virtual FdoBoolean GetWriteMember() const; 00153 00154 /// \brief 00155 /// Sets the URI for the feature collection element to wrap around serialized 00156 /// features. The initial value is 'http://www.opengis.net/gml' 00157 /// 00158 /// \param uri 00159 /// Input the URI. If NULL or blank, the URI reverts back to the initial value. 00160 /// 00161 FDO_API virtual void SetCollectionUri( FdoString* uri ); 00162 00163 /// \brief 00164 /// Gets the feature collection element URI. 00165 /// 00166 /// \return 00167 /// Returns the URI. 00168 /// 00169 FDO_API virtual FdoString* GetCollectionUri() const; 00170 00171 /// \brief 00172 /// Sets the name for the feature collection element to wrap around serialized 00173 /// features. The initial value is 'FeatureCollection' 00174 /// 00175 /// \param name 00176 /// Input the name. If NULL or blank, the name reverts back to the initial value. 00177 /// 00178 FDO_API virtual void SetCollectionName( FdoString* name ); 00179 00180 /// \brief 00181 /// Gets the feature collection element name. 00182 /// 00183 /// \return 00184 /// Returns FdoString*. 00185 /// 00186 FDO_API virtual FdoString* GetCollectionName() const; 00187 00188 /// \brief 00189 /// Sets the URI for the feature member element to wrap around each serialized 00190 /// feature. The initial value is 'http://www.opengis.net/gml' 00191 /// 00192 /// \param uri 00193 /// Input the URI. If NULL or blank, the URI defaults to the URI of the feature 00194 /// collection element's sub-element. If this sub-element cannot be determined 00195 /// then the URI defaults to the initial value 00196 /// 00197 FDO_API virtual void SetMemberUri( FdoString* uri ); 00198 00199 /// \brief 00200 /// Gets the feature member element URI. 00201 /// 00202 /// \return 00203 /// Returns FdoString* 00204 /// 00205 FDO_API virtual FdoString* GetMemberUri() const; 00206 00207 /// \brief 00208 /// Sets the name for the feature member element to wrap around each serialized 00209 /// feature. The initial value is 'featureMember' 00210 /// 00211 /// \param name 00212 /// Input the name. If NULL or blank, the URI defaults to the name of the feature 00213 /// collection element's sub-element. If this sub-element cannot be determined then 00214 /// the name defaults to the initial value 00215 /// 00216 FDO_API virtual void SetMemberName( FdoString* name ); 00217 00218 /// \brief 00219 /// Gets the feature member element name. 00220 /// 00221 /// \return 00222 /// Returns FdoString*. 00223 /// 00224 FDO_API virtual FdoString* GetMemberName() const; 00225 00226 /// \brief 00227 /// Sets the GML ID prefix for writing features. This prefix is prepended to the 00228 /// gml:id value for each feature. When features from different FDO Datastores are 00229 /// serialized to the same GML document, it is recommended that a different GML ID 00230 /// prefix be used for each Datastore, to ensure that the gml:id values in the GML 00231 /// document are unique. The initial value is L"" (no prefix). 00232 /// 00233 /// \param prefix 00234 /// Input the GML ID Prefix 00235 /// 00236 FDO_API virtual void SetGmlIdPrefix( FdoString* prefix ); 00237 00238 /// \brief 00239 /// Gets the current GML ID prefix. 00240 /// 00241 /// \return 00242 /// Returns FdoString 00243 /// 00244 FDO_API virtual FdoString* GetGmlIdPrefix() const; 00245 00246 /// \brief 00247 /// Sets the schema locations for writing features. The output GML must have schema 00248 /// definition for all its referenced namespaces, e.g, gml namespace, wfs namespace, 00249 /// user defined namespace. There are default values for gml namespace schema location 00250 /// and wfs namespace schema location, so the user doesn't need to set locations for those 00251 /// two namespaces. But the user can still set values to override the default values. The 00252 /// user could call this function multiple times to set schema location for multiple namespace. 00253 /// 00254 /// \param nameSpace 00255 /// Namespace of which the schema location is to be set. Like "http://www.opengis.net/wfs" 00256 /// for wfs namespace. 00257 /// \param schemaLocation 00258 /// Standard URL indicating the schema location, like "http://schemas.opengeospatial.net/wfs/1.0.0/WFS-basic.xsd" 00259 /// for wfs namespace. 00260 /// 00261 FDO_API virtual void SetSchemaLocation(FdoString* nameSpace, FdoString* schemaLocation); 00262 00263 /// \brief 00264 /// Gets the schema location for the specified namespace. 00265 /// 00266 /// \param nameSpace 00267 /// Namespace of which the schema location is to be retrieved. Like "http://www.opengis.net/wfs" 00268 /// 00269 /// \return 00270 /// Returns the URL indicating the schema location. 00271 /// 00272 FDO_API virtual FdoString* GetSchemaLocation(FdoString* nameSpace); 00273 00274 /// \brief 00275 /// Gets all namespaces that have been set for schemaLocation by SetSchemaLocation(). 00276 /// 00277 /// \return 00278 /// Returns all namespaces that have been set for schemaLocation. 00279 /// 00280 FDO_API virtual FdoStringCollection* GetNamespaces(); 00281 00282 /// \brief 00283 /// Sets the default namespace which defines all feature/object types found in the input 00284 /// feature reader which is to be serialized. The user is also supposed to set the schema 00285 /// location for this namespace. 00286 /// 00287 /// \param defaultNamespace 00288 /// Default namespace. 00289 /// 00290 FDO_API virtual void SetDefaultNamespace(FdoString* defaultNamespace); 00291 00292 /// \brief 00293 /// Gets the default namespace. 00294 /// 00295 /// \return 00296 /// Returns the default namespace. 00297 /// 00298 FDO_API virtual FdoString* GetDefaultNamespace(); 00299 00300 protected: 00301 FdoXmlFeatureFlags(); 00302 FdoXmlFeatureFlags(FdoString* url, ErrorLevel errorLevel, FdoBoolean nameAdjust, ConflictOption conflictOption); 00303 virtual ~FdoXmlFeatureFlags(); 00304 00305 private: 00306 ConflictOption mConflictOption; 00307 FdoBoolean mWriteCollection; 00308 FdoBoolean mWriteMember; 00309 FdoStringP mCollectionUri; 00310 FdoStringP mCollectionName; 00311 FdoStringP mMemberUri; 00312 FdoStringP mMemberName; 00313 FdoStringP mGmlIdPrefix; 00314 FdoPtr<FdoStringCollection> mNamespaces; 00315 FdoPtr<FdoStringCollection> mSchemaLocations; 00316 FdoStringP mDefaultNamespace; 00317 00318 }; 00319 00320 /// \ingroup (typedefs) 00321 /// \brief 00322 /// FdoXmlFeatureFlagsP is a FdoPtr on FdoXmlFeatureFlags, provided for convenience. 00323 typedef FdoPtr<FdoXmlFeatureFlags> FdoXmlFeatureFlagsP; 00324 00325 #endif 00326 00327
Comments or suggestions? Send us feedback. |