= !MapGuide RFC 77 - Create Feature Source =

This page contains an change request (RFC) for the !MapGuide Open Source project.
More !MapGuide RFCs can be found on the [wiki:MapGuideRfcs RFCs] page.


== Status ==

||RFC Template Version||(1.0)||
||Submission Date||July 09, 2009||
||Last Modified||Leaf Li [[Timestamp]]||
||Author||Leaf Li||
||RFC Status||adopted||
||Implementation Status||implemented||
||Proposed Milestone||2.2||
||Assigned PSC guide(s)||Bruce Dechant||
||'''Voting History'''||July 27, 2009||
||+1||Tom, Jason, Kenneth, Trevor, Paul, Andy||
||+0||||
||-0||||
||-1||
||no vote||Bruce, Harris, Bob ||

== Overview ==

This proposal is to extend MapGuide Feature Service to support creating more types of feature source.

== Motivation ==

Currently method MgFeatureService::!CreateFeatureSource(...) supports creating a SDF feature source only. It is really a limitation of Feature Service. This RFC will extend this method to support all file based feature sources. 

== Proposed Solution ==

==== !MgFileFeatureSourceParams ====

A new class !MgFileFeatureSourceParams is added to represent parameters which are used to create a file-based feature source. The existing class !MgCreateSdfParams inherits from it. Previously !MgCreateSdfParams inherits from virtual base class !MgFeatureSourceParams directly as shown in the following picture.

[[Image(ClassDiagram.JPG, 391)]][[BR]]

The class definition of !MgFileFeatureSourceParams is as follows.

{{{
///////////////////////////////////////////////
/// \brief
/// Contains the parameters used to create an file-based
/// feature source.
///
class MgFileFeatureSourceParams : public MgFeatureSourceParams
{
PUBLISHED_API:
    ///////////////////////////////////////////////
    /// \brief
    /// Constructs an empty MgFileFeatureSourceParams object.
    ///
    /// \return
    /// Returns nothing.
    ///
    MgFileFeatureSourceParams ();

    ///////////////////////////////////////////////
    /// \brief
    /// Constructs an empty MgFileFeatureSourceParams object.
    ///
    /// \param providerName (String/string)
    /// The FDO provider name of the feature source.
    ///
    /// \return
    /// Returns nothing.
    ///
    MgFileFeatureSourceParams (CREFSTRING providerName);
    
    ///////////////////////////////////////////////
    /// \brief
    /// Constructs an MgFileFeatureSourceParams object with the supplied
    /// parameters.
    ///
    /// \param providerName (String/string)
    /// FDO provider name of the feature source to be created.
    /// \param spatialContextName (String/string)
    /// The name of the spatial context. This is a user defined spatial
    /// context for the file feature source.
    /// \param srsWkt (String/string)
    /// An OGC WKT string representing the coordinate system for the file
    /// feature source.
    /// \param featureSchema (MgFeatureSchema)
    /// The schema definition for the file feature source.
    ///
    /// \return
    /// Returns nothing.
    ///
    MgFileFeatureSourceParams (
        CREFSTRING providerName, 
        CREFSTRING spatialContextName, 
        CREFSTRING srsWkt, 
        MgFeatureSchema* featureSchema);

    ///////////////////////////////////////////////
    /// \brief
    /// Gets the FDO provider name of the feature source.
    ///
    /// \return
    /// Returns the FDO provider name of the feature source.
    ///
    virtual STRING GetProviderName();  /// __get, __set

    ///////////////////////////////////////////////
    /// \brief
    /// Sets the FDO provider name of the feature source.
    ///
    /// \param name (String/string)
    /// FDO provider name of the feature source to be created.
    ///
    /// \return
    /// Returns nothing.
    ///
    virtual void SetProviderName(CREFSTRING name);

    ///////////////////////////////////////////////
    /// \brief
    /// Gets the file name to be created.
    ///
    /// \return
    /// Returns the file name to be created.
    ///
    STRING GetFileName();  /// __get, __set

    ////////////////////////////////////////////////////////////////////////////
    /// \brief
    /// Sets the file name to be created.
    ///
    /// \param name (String/string)
    /// The file name to be created.
    ///
    /// \return
    /// Returns nothing.
    ///
    void SetFileName (CREFSTRING name);

    ///////////////////////////////////////////////
    /// \brief
    /// Gets the user-defined spatial context name.
    ///
    /// \return
    /// Returns the name of the spatial context.
    ///
    STRING GetSpatialContextName();  /// __get, __set

    ////////////////////////////////////////////////////////////////////////////
    /// \brief
    /// Sets the user-defined spatial context name.
    ///
    /// \param name (String/string)
    /// The name of the spatial context
    ///
    /// \return
    /// Returns nothing.
    ///
    void SetSpatialContextName(CREFSTRING name);

    /////////////////////////////////////////////
    /// \brief
    /// Gets the spatial context description.
    ///
    /// \return
    /// Returns the spatial context description.
    ///
    STRING GetSpatialContextDescription();  /// __get, __set

    //////////////////////////////////////////////////////////////////////////
    /// \brief
    /// Sets the spatial context description.
    /// \param description (String/string)
    /// The description of the spatial context.
    ///
    /// \return
    /// Returns nothing.
    ///
    void SetSpatialContextDescription(CREFSTRING description);

    ///////////////////////////////////////////////////////////////
    /// \brief
    /// Gets the well-known text description of the coordinate system.
    ///
    /// \return
    /// Returns the OGC WKT description of the coordinate system.
    ///
    STRING GetCoordinateSystemWkt();  /// __get, __set

    //////////////////////////////////////////////////////////////////////////
    /// \brief
    /// Sets the well-know text string representing the coordinate system.
    ///
    /// \param srsWkt (String/string)
    /// The OGC WKT string representing the coordinate system.
    ///
    /// \return
    /// Returns nothing.
    ///
    void SetCoordinateSystemWkt(CREFSTRING srsWkt);

    //////////////////////////////////////////////////////////
    /// \brief
    /// Gets the tolerance tolerance used for the X and Y
    /// ordinates.
    ///
    /// \return
    /// Returns the tolerance used for the X and Y ordinates.
    ///
    double GetXYTolerance();  /// __get, __set

    ////////////////////////////////////////////////////////////////
    /// \brief
    /// Sets the tolerance tolerance for the X and Y ordinates.
    ///
    /// \param tolerance (double)
    /// The tolerance for the X and Y ordinates.
    ///
    /// \return
    /// Returns nothing.
    ///
    void SetXYTolerance(double tolerance);

    ////////////////////////////////////////////////////////
    /// \brief
    /// Gets the tolerance tolerance for the Z ordinate.
    ///
    /// \return
    /// Returns the tolerance for the Z ordinate.
    ///
    double GetZTolerance();  /// __get, __set

    ////////////////////////////////////////////////////////////////////////////
    /// \brief
    /// Sets the tolerance for the Z ordinate.
    ///
    /// \param tolerance (double)
    /// The tolerance for the Z ordinate.
    ///
    /// \return
    /// Returns nothing.
    ///
    void SetZTolerance(double tolerance);

    ////////////////////////////////////////////////
    /// \brief
    /// Gets the feature schema definition.
    ///
    /// \return
    /// Returns a feature schema definition object.
    ///
    MgFeatureSchema* GetFeatureSchema();  /// __get, __set

    ///////////////////////////////////////////////////////////////////
    /// \brief
    /// Sets the feature schema definition.
    ///
    /// \param featureSchema (MgFeatureSchema)
    /// The feature schema definition.
    ///
    /// \return
    /// Returns nothing.
    ///
    void SetFeatureSchema(MgFeatureSchema* featureSchema);
};
}}}

==== Changes to !MgCreateSdfParams ====

There are only some minor changes to class !MgCreateSdfParams. !MgCreateSdfParams overrides constructor and method !SetProviderName(). Other methods are inherited from its parent.

{{{
/// \brief
/// Contains the parameters used to create an SDF feature source.
///
class MgCreateSdfParams : public MgFileFeatureSourceParams
{
PUBLISHED_API:
    //////////////////////////////////////////////////
    /// \brief
    /// Constructs an empty MgCreateSdfParams object.
    ///
    /// \return
    /// Returns nothing.
    ///
    MgCreateSdfParams();

    ////////////////////////////////////////////////////
    /// \brief
    /// Constructs an MgCreateSdfParams object with the supplied
    /// parameters.
    ///
    /// \param spatialContextName (String/string)
    /// The name of the spatial context. This is a user defined
    /// spatial context for the SDF file. Only one spatial context is
    /// supported.
    /// \param srsWkt (String/string)
    /// An OGC WKT string representing the
    /// coordinate system for the SDF file.
    /// \param featureSchema (MgFeatureSchema)
    /// The schema definition for the SDF file.
    ///
    /// \return
    /// Returns nothing.
    ///
    MgCreateSdfParams(
        CREFSTRING spatialContextName, 
        CREFSTRING srsWkt, 
        MgFeatureSchema* featureSchema);

    ///////////////////////////////////////////////
    /// \brief
    /// Throw an MgInvalidOperationException because we
    /// can't change FDO provider for MgCreateSdfParams.
    ///
    /// \param name (String/string)
    /// FDO provider name of the feature source to be created.
    ///
    /// \return
    /// Returns nothing.
    ///
    virtual void SetProviderName(CREFSTRING name);
};
}}}

There are no change to method MgFeatureService::!CreateFeatureSource(...), whose usage is as before.

== Implications ==

This is new API only. There will be no effect on existing applications. However, API documentation need to be updated.

Because this API is based on FdoICreateDataStore, so it will not bee supported if FDO provider doesn't support FdoICreateDataStore command. For exmaple, ORG&GDAL FDO provider will not support it even if it is a file-based provider because it doesn't support FdoICreateDataStore command. So SQLite, SHP and SDF support this API only.

Currently, there are no enough resources and funding to support creating non-file based feature sources. They may be implemented if resources and funding can be obtained in the future.

== Test Plan ==

Add unit tests for method MgFeatureService::!CreateFeatureSource(...) into the existing Feature Service unit tests.

== Funding/Resources ==

Supplied by Autodesk.

== Addendum, Sept. 15, 2009 ==

Previously, MgFeatureService::!CreateFeatureSource(...) will throw an !MgInvalidArgumentException no feature classes or spatial context are specified in the !MgFileFeatureSourceParams instance. If the spatial context and feature class are not known at the time of creation then a "dummy" feature class and spatial context would need to be specified; and then deleted later. 

This change will allow MgFeatureService::!CreateFeatureSource(...) to execute without the spatial context and feature class specified.