Changes between Version 9 and Version 10 of MapGuideRfc53


Ignore:
Timestamp:
08/11/08 14:06:01 (16 years ago)
Author:
stevedang
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • MapGuideRfc53

    v9 v10  
    2525== Overview ==
    2626
     27This RFC enhances MapGuide Feature Service to take performance advantage of the new FDO APIs as described in FDO RFC 23, http://trac.osgeo.org/fdo/wiki/FDORfc23 .
     28
     29The mainly affected MapGuide Feature Service APIs include DescribeSchema, GetSchemas, and GetClasses.
     30
    2731== Motivation ==
     32
     33MapGuide Feature Service APIs provide the ability to configure a connection to a supported FDO provider, and to obtain available properties and geometries from a specific feature source. These requested data are retrieved via the FDO DescribeSchema API which returns detailed information about all feature classes available from a provider.
     34
     35Although MapGuide does cache the full schemas for high performance with subsequent requests, the initial DescribeSchema API call can take a very long time when a database contains a large number of feature classes (e.g. real-world Oracle database deployments).
     36
     37The proposal described in this RFC is to update all the relevant MapGuide Feature Service APIs so that they allow only the required subset of the available information to be requested, and avoid making calls to retrieve the full schema unless it is absolutely necessary.
    2838
    2939== Proposed Solution ==
    3040
     41* Update the following existing MapGuide Feature Service APIs to utilize the new FDO APIs:
     42
     43{{{
     44    DescribeSchema
     45    GetSchemas
     46    GetClasses
     47}}}
     48   
     49* Add the following new MapGuide Feature Service APIs:
     50
     51{{{
     52
     53    ///////////////////////////////////////////////////////////////////////////
     54    /// \brief
     55    /// Gets the definitions of one or more schemas contained in the
     56    /// feature source for particular classes. If the specified schema name or
     57    /// a class name does not exist, this method will throw an exception.
     58    /// See \link Feature_Schema_Module Feature Schema \endlink.
     59    ///
     60    /// <!-- Syntax in .Net, Java, and PHP -->
     61    /// \htmlinclude DotNetSyntaxTop.html
     62    /// virtual MgFeatureSchemaCollection DescribeSchema(MgResourceIdentifier resource, string schemaName, MgStringCollection classNames);
     63    /// \htmlinclude SyntaxBottom.html
     64    /// \htmlinclude JavaSyntaxTop.html
     65    /// virtual MgFeatureSchemaCollection DescribeSchema(MgResourceIdentifier resource, String schemaName, MgStringCollection classNames);
     66    /// \htmlinclude SyntaxBottom.html
     67    /// \htmlinclude PHPSyntaxTop.html
     68    /// virtual MgFeatureSchemaCollection DescribeSchema(MgResourceIdentifier resource, string schemaName, MgStringCollection classNames);
     69    /// \htmlinclude SyntaxBottom.html
     70    ///
     71    /// \param resource (MgResourceIdentifier)
     72    /// A resource identifier for the feature source.
     73    /// \param schemaName (String/string)
     74    /// The name of the schema definition to retrieve. If this string is empty,
     75    /// execution of the command will describe requested classes using the
     76    /// qualified class name. If the class name is not qualified, the requested
     77    /// class from all schemas will be described.
     78    /// \param classNames (MgStringCollection)
     79    /// A collection of strings identifying the feature classes for which to
     80    /// retrieve schema information. If this collection is null or empty,
     81    /// execution of the command will describe all classes.
     82    /// If the class name is not qualified, and the schema name is not specified,
     83    /// the requested class from all schemas will be described.
     84    /// The class names specified serve only as a hint. Use of the hint
     85    /// during command execution is provider dependent. Providers that
     86    /// will not use the hint will describe the schema for all classes.
     87    ///
     88    /// \return
     89    /// Returns the schema collection representing the schema containing
     90    /// the class collection for the specified classes.
     91    ///
     92    /// \exception MgFeatureServiceException
     93    /// \exception MgInvalidArgumentException
     94    /// \exception MgFdoException
     95    ///
     96    /// \note
     97    /// Please refer to Overview section of this document or Fdo
     98    /// provider documents for details on connection properties,
     99    /// schema and classes.
     100    ///
     101    virtual MgFeatureSchemaCollection* DescribeSchema(MgResourceIdentifier* resource,
     102        CREFSTRING schemaName, MgStringCollection* classNames);
     103
     104    ///////////////////////////////////////////////////////////////////////////
     105    /// \brief
     106    /// Gets the definitions in XML format of one or more schemas contained in the
     107    /// feature source for particular classes. If the specified schema name or
     108    /// a class name does not exist, this method will throw an exception.
     109    /// See \link Feature_Schema_Module Feature Schema \endlink.
     110    ///
     111    /// \remarks
     112    /// The XML representation of the schema definitions conforms to
     113    /// FDO XML schema, which are based on OGC GML schema. How to
     114    /// specify a schema definition in XML is discussed in the
     115    /// Autodesk FDO API Developer's Guide.
     116    ///
     117    /// <!-- Syntax in .Net, Java, and PHP -->
     118    /// \htmlinclude DotNetSyntaxTop.html
     119    /// virtual string DescribeSchemaAsXml(MgResourceIdentifier resource, string schemaName, MgStringCollection classNames);
     120    /// \htmlinclude SyntaxBottom.html
     121    /// \htmlinclude JavaSyntaxTop.html
     122    /// virtual String DescribeSchemaAsXml(MgResourceIdentifier resource, String schemaName, MgStringCollection classNames);
     123    /// \htmlinclude SyntaxBottom.html
     124    /// \htmlinclude PHPSyntaxTop.html
     125    /// virtual string DescribeSchemaAsXml(MgResourceIdentifier resource, string schemaName, MgStringCollection classNames);
     126    /// \htmlinclude SyntaxBottom.html
     127    ///
     128    /// \param resource (MgResourceIdentifier)
     129    /// A resource identifier for the feature source.
     130    /// \param schemaName (String/string)
     131    /// The name of the schema definition to retrieve. If this string is empty,
     132    /// execution of the command will describe requested classes using the
     133    /// qualified class name. If the class name is not qualified, the requested
     134    /// class from all schemas will be described.
     135    /// \param classNames (MgStringCollection)
     136    /// A collection of strings identifying the feature classes for which to
     137    /// retrieve schema information. If this collection is null or empty,
     138    /// execution of the command will describe all classes.
     139    /// If the class name is not qualified, and the schema name is not specified,
     140    /// the requested class from all schemas will be described.
     141    /// The class names specified serve only as a hint. Use of the hint
     142    /// during command execution is provider dependent. Providers that
     143    /// will not use the hint will describe the schema for all classes.
     144    ///
     145    /// \return
     146    /// Returns a string containing the FDO schema in XML format.
     147    ///
     148    /// \exception MgFeatureServiceException
     149    /// \exception MgInvalidArgumentException
     150    /// \exception MgFdoException
     151    ///
     152    virtual STRING DescribeSchemaAsXml(MgResourceIdentifier* resource,
     153        CREFSTRING schemaName, MgStringCollection* classNames);
     154
     155}}}
     156
    31157== Implications ==
    32158
     159 * Other related MapGuide Feature Service APIs (such as DescribeSchemaAsXml, GetClassDefinition, GetIdentityProperties, etc.) will be updated to utilize the new FDO APIs for improved performance.
     160 * The existing HTTP interface DESCRIBEFEATURESCHEMA will be updated to utilize the new DescribeSchemaAsXml API.
     161 * For providers that do not support the new FDO APIs, MapGuide will fall back on using DescribeSchema and walk through the results to retrieve the schema names, class names, and class definitions.
     162 * The MapGuide Feature Service cache framework will be modified to allow the schema information retrieved from the new APIs to be built up incrementally as required.
     163 * The old DescribeSchema and DescribeSchemaAsXml APIs will be deprecated in the future.
     164 
    33165== Test Plan ==
     166
     167 * The old DescribeSchema and DescribeSchemaAsXml APIs should work as before.
     168 * Existing unit tests will be updated to utilize the new APIs and re-tested.
    34169
    35170== Funding/Resources ==