- Main Page
- Related Pages
- Modules
- Classes
- Files

# FeatureFlags.h

Go to the documentation of this file.

    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

Please send us your comment about this page