Context Navigation

Changes between Version 2 and Version 3 of MapGuideRfc143

Timestamp:: 07/04/14 03:28:05 (11 years ago)
Author:: jng
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

MapGuideRfc143

-              v2
+              v3
 As you can see, this type of code is a lot of boilerplate for just inserting features.
 For this RFC, we will add convenience APIs to MgFeatureService and MgLayerBase to do individual insert/update/delete operations instead of a one-size-fits-all API that we currently have:
+For this RFC, we will add convenience APIs to MgFeatureService to allow individual insert/update/delete operations instead of a one-size-fits-all API that we currently have
 {{{
 …
 };
 }}}
-{{{
-class MG_PLATFORMBASE_API MgLayerBase : public MgNamedSerializable
+{
-PUBLISHED_API:
-    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-    /// \brief
-    /// Inserts a new feature into the specified feature class of the specified Feature Source
-    ///
-    /// <!-- Syntax in .Net, Java, and PHP -->
-    /// \htmlinclude DotNetSyntaxTop.html
-    /// virtual MgFeatureReader InsertFeatures(MgPropertyCollection properties);
-    /// \htmlinclude SyntaxBottom.html
-    /// \htmlinclude JavaSyntaxTop.html
-    /// virtual MgFeatureReader InsertFeatures(MgPropertyCollection properties);
-    /// \htmlinclude SyntaxBottom.html
-    /// \htmlinclude PHPSyntaxTop.html
-    /// virtual MgFeatureReader InsertFeatures(MgPropertyCollection properties);
-    /// \htmlinclude SyntaxBottom.html
-    ///
-    /// \param properties (MgPropertyCollection)
-    /// The collection of property values to insert
-    ///
-    /// \return
-    /// Returns a feature reader object that contains the set of properties
-    /// inserted into the datastore by the insert command.
-    ///
-    /// \remarks
-    /// Transactions will be used internally if the provider supports them.
-    /// Remember to close any feature readers returned by this method, even if you don't intend
-    /// to do anything with them
-    ///
-    /// \exception MgFeatureServiceException
-    /// \exception MgInvalidArgumentException
-    /// \exception MgInvalidOperationException
-    /// \exception MgFdoException
-    ///
-    /// \since 3.0
-    virtual MgFeatureReader* InsertFeatures(MgPropertyCollection* properties);
-    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-    /// \brief
-    /// Inserts a set of new features into the specified feature class of the specified Feature Source
-    ///
-    /// <!-- Syntax in .Net, Java, and PHP -->
-    /// \htmlinclude DotNetSyntaxTop.html
-    /// virtual MgFeatureReader InsertFeatures(MgBatchPropertyCollection properties);
-    /// \htmlinclude SyntaxBottom.html
-    /// \htmlinclude JavaSyntaxTop.html
-    /// virtual MgFeatureReader InsertFeatures(MgBatchPropertyCollection properties);
-    /// \htmlinclude SyntaxBottom.html
-    /// \htmlinclude PHPSyntaxTop.html
-    /// virtual MgFeatureReader InsertFeatures(MgBatchPropertyCollection properties);
-    /// \htmlinclude SyntaxBottom.html
-    ///
-    /// \param properties (MgBatchPropertyCollection)
-    /// The collection of property values to insert. Each MgPropertyCollection within
-    /// this collection represents property values for a single feature to insert
-    ///
-    /// \return
-    /// Returns a feature reader object that contains the set of properties
-    /// inserted into the datastore by the insert command.
-    ///
-    /// \remarks
-    /// Transactions will be used internally if the provider supports them.
-    /// Remember to close any feature readers returned by this method, even if you don't intend
-    /// to do anything with them
-    ///
-    /// \exception MgFeatureServiceException
-    /// \exception MgInvalidArgumentException
-    /// \exception MgInvalidOperationException
-    /// \exception MgFdoException
-    ///
-    /// \since 3.0
-    virtual MgFeatureReader* InsertFeatures(MgBatchPropertyCollection* properties);
-    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-    /// \brief
-    /// Updates all features that match the given filter with the specified property values
-    ///
-    /// \remarks
-    /// Transactions will be used internally if the provider supports them
-    ///
-    /// <!-- Syntax in .Net, Java, and PHP -->
-    /// \htmlinclude DotNetSyntaxTop.html
-    /// virtual int UpdateMatchingFeatures(MgPropertyCollection properties, string filter);
-    /// \htmlinclude SyntaxBottom.html
-    /// \htmlinclude JavaSyntaxTop.html
-    /// virtual int UpdateMatchingFeatures(MgPropertyCollection properties, String filter);
-    /// \htmlinclude SyntaxBottom.html
-    /// \htmlinclude PHPSyntaxTop.html
-    /// virtual int UpdateMatchingFeatures(MgPropertyCollection properties, String filter);
-    /// \htmlinclude SyntaxBottom.html
-    ///
-    /// \param properties (MgBatchPropertyCollection)
-    /// The property values to update matching features with
-    /// \param filter (String/string)
-    /// The FDO filter string that detemines what features will be updated
-    ///
-    /// \return
-    /// Returns the number of features updated by this operation
-    ///
-    /// \exception MgFeatureServiceException
-    /// \exception MgInvalidArgumentException
-    /// \exception MgInvalidOperationException
-    /// \exception MgFdoException
-    ///
-    /// \since 3.0
-    virtual INT32 UpdateMatchingFeatures(MgPropertyCollection* properties, CREFSTRING filter);
-    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-    /// \brief
-    /// Deletes all features that match the given filter
-    ///
-    /// \remarks
-    /// Transactions will be used internally if the provider supports them
-    ///
-    /// <!-- Syntax in .Net, Java, and PHP -->
-    /// \htmlinclude DotNetSyntaxTop.html
-    /// virtual int DeleteFeatures(string filter);
-    /// \htmlinclude SyntaxBottom.html
-    /// \htmlinclude JavaSyntaxTop.html
-    /// virtual int DeleteFeatures(String filter);
-    /// \htmlinclude SyntaxBottom.html
-    /// \htmlinclude PHPSyntaxTop.html
-    /// virtual int DeleteFeatures(String filter);
-    /// \htmlinclude SyntaxBottom.html
-    ///
-    /// \param filter (String/string)
-    /// The FDO filter string that detemines what features will be deleted
-    ///
-    /// \return
-    /// Returns the number of features deleted by this operation
-    ///
-    /// \exception MgFeatureServiceException
-    /// \exception MgInvalidArgumentException
-    /// \exception MgInvalidOperationException
-    /// \exception MgFdoException
-    ///
-    /// \since 3.0
-    virtual INT32 DeleteFeatures(CREFSTRING filter);
-};
-}}}
 With these convenience APIs, the above example for inserting features now becomes:
 …
 }}}
+For updating/deleting features, you will see similar reductions in code using these convenience APIs
+For updating/deleting features you will see similar reductions in code using these convenience APIs
+For MgLayerBase, we'll add convenience APIs to shortcut boilerplate that would normally require MgFeatureService and extracting additional information from the layer:
+ - Individual insert/update/delete operations instead of a one-size-fits-all API that we currently have
+ - The ability to start transactions on the layer's feature source
+ - The ability to interrogate spatial contexts for the layer's feature source
+ - The ability to call UpdateFeatures() transactionally or non-transactionally instead of having the method internally decide (ie. UpdateFeatures() that can take a MgTransaction parameter)
+{{{
+class MG_PLATFORMBASE_API MgLayerBase : public MgNamedSerializable
+{
+PUBLISHED_API:
+    ////////////////////////////////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Starts a transaction on the this layer. The FDO provider indicated by the layer's
+    /// Feature Source must support transactions.
+    ///
+    /// \remarks
+    /// The XML returned by MgFeatureService::GetCapabilities says
+    /// whether a provider supports transactions. See \link ProviderCapabilities Provider Capabilities \endlink.
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual MgTransaction BeginTransaction();
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual MgTransaction BeginTransaction();
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual MgTransaction BeginTransaction();
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \return
+    /// Returns an MgTransaction instance (or NULL).
+    ///
+    /// \exception MgFeatureServiceException
+    /// \exception MgInvalidArgumentException
+    /// \exception MgInvalidOperationException
+    /// \exception MgFdoException
+    ///
+    /// \since 3.0
+    virtual MgTransaction* BeginTransaction();
+    //////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Executes the MgDeleteFeatures, MgInsertFeatures,
+    /// MgUpdateFeatures, MgLockFeatures or MgUnlockFeatures commands
+    /// contained in the given MgFeatureCommandCollection object.
+    ///
+    /// \remarks
+    /// The XML returned by MgFeatureService::GetCapabilities says
+    /// whether a provider supports SQL commands. See \link ProviderCapabilities Provider Capabilities \endlink.
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual MgPropertyCollection UpdateFeatures(MgFeatureCommandCollection commands);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual MgPropertyCollection UpdateFeatures(MgFeatureCommandCollection commands);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual MgPropertyCollection UpdateFeatures(MgFeatureCommandCollection commands);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param commands (MgFeatureCommandCollection)
+    /// A collection of feature commands to be
+    /// executed.
+    /// \param transaction (MgTransaction)
+    /// An optional transaction to execute this operation under
+    ///
+    /// \return
+    /// Returns an MgPropertyCollection object. Each property in the
+    /// collection corresponds to a command in the
+    /// MgFeatureCommandCollection argument. The property name is the
+    /// index of the command in the feature command collection.
+    /// <ul>
+    ///   <li>If the command is of type MgDeleteFeatures, the property
+    ///     type is an MgPropertyType::Int32, and its value is the number
+    ///     of features deleted.</li>
+    ///   <li>If the command is of type MgInsertFeatures, the property
+    ///     type is an MgPropertyType::Feature, and its value is a
+    ///     MgFeatureReader object. The feature reader object contains
+    ///     the set of properties inserted into the datastore by the
+    ///     insert command.</li>
+    ///   <li>If the command is of type MgUpdateFeatures, the property
+    ///     type is MgPropertyType::Int32, and its value is the number of
+    ///     features updated.</li>
+    ///   <li>If the command is of type MgLockFeatures, the property
+    ///     type is MgPropertyType::Feature, and its value is the number
+    ///     of features locked.</li>
+    ///   <li>If the command is of type MgUnLockFeatures, the property
+    ///     type is MgPropertyType::Int32, and its value is the number of
+    ///     features unlocked.</li>
+    /// </ul>
+    ///
+    /// \exception MgFeatureServiceException
+    /// \exception MgInvalidArgumentException
+    /// \exception MgInvalidOperationException
+    /// \exception MgFdoException
+    ///
+    /// \since 3.0
+    virtual MgPropertyCollection* UpdateFeatures(MgFeatureCommandCollection* commands, MgTransaction* transaction);
+    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Inserts a new feature into the specified feature class of the specified Feature Source
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual MgFeatureReader InsertFeatures(MgPropertyCollection properties);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual MgFeatureReader InsertFeatures(MgPropertyCollection properties);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual MgFeatureReader InsertFeatures(MgPropertyCollection properties);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param properties (MgPropertyCollection)
+    /// The collection of property values to insert
+    /// \param transaction (MgTransaction)
+    /// An optional transaction to execute this operation under
+    ///
+    /// \return
+    /// Returns a feature reader object that contains the set of properties
+    /// inserted into the datastore by the insert command.
+    ///
+    /// \remarks
+    /// Transactions will be used internally if the provider supports them.
+    /// Remember to close any feature readers returned by this method, even if you don't intend
+    /// to do anything with them
+    ///
+    /// \exception MgFeatureServiceException
+    /// \exception MgInvalidArgumentException
+    /// \exception MgInvalidOperationException
+    /// \exception MgFdoException
+    ///
+    /// \since 3.0
+    virtual MgFeatureReader* InsertFeatures(MgPropertyCollection* properties, MgTransaction* transaction);
+    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Inserts a set of new features into the specified feature class of the specified Feature Source
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual MgFeatureReader InsertFeatures(MgBatchPropertyCollection properties);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual MgFeatureReader InsertFeatures(MgBatchPropertyCollection properties);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual MgFeatureReader InsertFeatures(MgBatchPropertyCollection properties);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param properties (MgBatchPropertyCollection)
+    /// The collection of property values to insert. Each MgPropertyCollection within
+    /// this collection represents property values for a single feature to insert
+    /// \param transaction (MgTransaction)
+    /// An optional transaction to execute this operation under
+    ///
+    /// \return
+    /// Returns a feature reader object that contains the set of properties
+    /// inserted into the datastore by the insert command.
+    ///
+    /// \remarks
+    /// Transactions will be used internally if the provider supports them.
+    /// Remember to close any feature readers returned by this method, even if you don't intend
+    /// to do anything with them
+    ///
+    /// \exception MgFeatureServiceException
+    /// \exception MgInvalidArgumentException
+    /// \exception MgInvalidOperationException
+    /// \exception MgFdoException
+    ///
+    /// \since 3.0
+    virtual MgFeatureReader* InsertFeatures(MgBatchPropertyCollection* properties, MgTransaction* transaction);
+    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Updates all features that match the given filter with the specified property values
+    ///
+    /// \remarks
+    /// Transactions will be used internally if the provider supports them
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual int UpdateMatchingFeatures(MgPropertyCollection properties, string filter);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual int UpdateMatchingFeatures(MgPropertyCollection properties, String filter);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual int UpdateMatchingFeatures(MgPropertyCollection properties, String filter);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param properties (MgBatchPropertyCollection)
+    /// The property values to update matching features with
+    /// \param filter (String/string)
+    /// The FDO filter string that detemines what features will be updated
+    /// \param transaction (MgTransaction)
+    /// An optional transaction to execute this operation under
+    ///
+    /// \return
+    /// Returns the number of features updated by this operation
+    ///
+    /// \exception MgFeatureServiceException
+    /// \exception MgInvalidArgumentException
+    /// \exception MgInvalidOperationException
+    /// \exception MgFdoException
+    ///
+    /// \since 3.0
+    virtual INT32 UpdateMatchingFeatures(MgPropertyCollection* properties, CREFSTRING filter, MgTransaction* transaction);
+    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Deletes all features that match the given filter
+    ///
+    /// \remarks
+    /// Transactions will be used internally if the provider supports them
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual int DeleteFeatures(string filter);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual int DeleteFeatures(String filter);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual int DeleteFeatures(String filter);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param filter (String/string)
+    /// The FDO filter string that detemines what features will be deleted
+    /// \param transaction (MgTransaction)
+    /// An optional transaction to execute this operation under
+    ///
+    /// \return
+    /// Returns the number of features deleted by this operation
+    ///
+    /// \exception MgFeatureServiceException
+    /// \exception MgInvalidArgumentException
+    /// \exception MgInvalidOperationException
+    /// \exception MgFdoException
+    ///
+    /// \since 3.0
+    virtual INT32 DeleteFeatures(CREFSTRING filter, MgTransaction* transaction);
+    //////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Gets all of the spatial contexts available in the layer or just the active one
+    ///
+    /// \remarks
+    /// The \link FdoSpatialContextList_schema FdoSpatialContextList \endlink XML schema contains
+    /// a specification of the content of the spatial context
+    /// information returned in the MgSpatialContextReader object.
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual MgSpatialContextReader GetSpatialContexts(bool bActiveOnly);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual MgSpatialContextReader GetSpatialContexts(boolean bActiveOnly);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual MgSpatialContextReader GetSpatialContexts(bool bActiveOnly);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param bActiveOnly (boolean/bool)
+    /// This flag is obsolete and no longer used.
+    ///
+    /// \return
+    /// Returns an MgSpatialContextReader object.
+    ///
+    /// \exception MgFeatureServiceException
+    /// \exception MgInvalidArgumentException
+    /// \exception MgInvalidOperationException
+    /// \exception MgFdoException
+    ///
+    /// \since 3.0
+    virtual MgSpatialContextReader* GetSpatialContexts(bool bActiveOnly);
+};
+}}}
 === Rendering layer style icons ===
 …
 As with [wiki:MapGuideRfc9 MapGuide RFC 9], the new convenience APIs in MgLayer/MgLayerBase will only work if the parent MgMap was initialized with an MgSiteConnection instance. If [wiki:MapGuideRfc139 MapGuide RFC 139] is adopted, the deprecated MgMap() constructor will be removed, eliminating the possibility of these APIs not working under certain conditions.
+It's up to Autodesk whether they choose to implement these convenience APIs for their AutoCAD Map implementation of MgLayerBase and MgFeatureService. These methods will throw MgNotImplementedException if not overridden.
 == Test Plan ==