MapGuide RFC 53 - DescribeSchema, GetSchemas and GetClasses API Enhancements

This page contains a change request (RFC) for the MapGuide Open Source project. More MapGuide RFCs can be found on the RFCs page.

Status

RFC Template Version	(1.0)
Submission Date	July 18, 2008
Last Modified	Steve Dang Timestamp
Author	Steve Dang
RFC Status	proposed
Implementation Status	pending
Proposed Milestone	2.1
Assigned PSC guide(s)	Bruce Dechant
Voting History	(vote date)
+1
+0
-0
-1
no vote

Overview

This 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 .

The mainly affected MapGuide Feature Service APIs include DescribeSchema, GetSchemas, and GetClasses.

Motivation

MapGuide 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.

Although 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).

The 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.

Proposed Solution

1. Adding the following new MapGuide Feature Service APIs:

    ///////////////////////////////////////////////////////////////////////////
    /// \brief
    /// Gets the definitions of one or more schemas contained in the
    /// feature source for particular classes. If the specified schema name or
    /// a class name does not exist, this method will throw an exception.
    /// See \link Feature_Schema_Module Feature Schema \endlink.
    ///
    /// <!-- Syntax in .Net, Java, and PHP -->
    /// \htmlinclude DotNetSyntaxTop.html
    /// virtual MgFeatureSchemaCollection DescribeSchema(MgResourceIdentifier resource, string schemaName, MgStringCollection classNames);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// virtual MgFeatureSchemaCollection DescribeSchema(MgResourceIdentifier resource, String schemaName, MgStringCollection classNames);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// virtual MgFeatureSchemaCollection DescribeSchema(MgResourceIdentifier resource, string schemaName, MgStringCollection classNames);
    /// \htmlinclude SyntaxBottom.html
    ///
    /// \param resource (MgResourceIdentifier)
    /// A resource identifier for the feature source.
    /// \param schemaName (String/string)
    /// The name of the schema definition to retrieve. If this string is empty,
    /// execution of the command will describe requested classes using the
    /// qualified class name. If the class name is not qualified, the requested
    /// class from all schemas will be described.
    /// \param classNames (MgStringCollection)
    /// A collection of strings identifying the feature classes for which to
    /// retrieve schema information. If this collection is null or empty,
    /// execution of the command will describe all classes.
    /// If the class name is not qualified, and the schema name is not specified,
    /// the requested class from all schemas will be described.
    /// The class names specified serve only as a hint. Use of the hint
    /// during command execution is provider dependent. Providers that 
    /// will not use the hint will describe the schema for all classes.
    ///
    /// \return
    /// Returns the schema collection representing the schema containing
    /// the class collection for the specified classes.
    ///
    /// \exception MgFeatureServiceException
    /// \exception MgInvalidArgumentException
    /// \exception MgFdoException
    ///
    /// \note
    /// Please refer to Overview section of this document or FDO
    /// provider documents for details on connection properties,
    /// schema and classes.
    ///
    virtual MgFeatureSchemaCollection* DescribeSchema(MgResourceIdentifier* resource,
        CREFSTRING schemaName, MgStringCollection* classNames);

    ///////////////////////////////////////////////////////////////////////////
    /// \brief
    /// Gets the definitions in XML format of one or more schemas contained in the
    /// feature source for particular classes. If the specified schema name or
    /// a class name does not exist, this method will throw an exception.
    /// See \link Feature_Schema_Module Feature Schema \endlink.
    ///
    /// \remarks
    /// The XML representation of the schema definitions conforms to
    /// FDO XML schema, which are based on OGC GML schema. How to
    /// specify a schema definition in XML is discussed in the
    /// Autodesk FDO API Developer's Guide.
    ///
    /// <!-- Syntax in .Net, Java, and PHP -->
    /// \htmlinclude DotNetSyntaxTop.html
    /// virtual string DescribeSchemaAsXml(MgResourceIdentifier resource, string schemaName, MgStringCollection classNames);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// virtual String DescribeSchemaAsXml(MgResourceIdentifier resource, String schemaName, MgStringCollection classNames);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// virtual string DescribeSchemaAsXml(MgResourceIdentifier resource, string schemaName, MgStringCollection classNames);
    /// \htmlinclude SyntaxBottom.html
    ///
    /// \param resource (MgResourceIdentifier)
    /// A resource identifier for the feature source.
    /// \param schemaName (String/string)
    /// The name of the schema definition to retrieve. If this string is empty,
    /// execution of the command will describe requested classes using the
    /// qualified class name. If the class name is not qualified, the requested
    /// class from all schemas will be described.
    /// \param classNames (MgStringCollection)
    /// A collection of strings identifying the feature classes for which to
    /// retrieve schema information. If this collection is null or empty,
    /// execution of the command will describe all classes.
    /// If the class name is not qualified, and the schema name is not specified,
    /// the requested class from all schemas will be described.
    /// The class names specified serve only as a hint. Use of the hint
    /// during command execution is provider dependent. Providers that 
    /// will not use the hint will describe the schema for all classes.
    ///
    /// \return
    /// Returns a string containing the FDO schema in XML format.
    ///
    /// \exception MgFeatureServiceException
    /// \exception MgInvalidArgumentException
    /// \exception MgFdoException
    ///
    virtual STRING DescribeSchemaAsXml(MgResourceIdentifier* resource,
        CREFSTRING schemaName, MgStringCollection* classNames);

2. Updating the following existing MapGuide Feature Service APIs to utilize the new FDO APIs:

    DescribeSchema
    GetSchemas
    GetClasses

3. Updating the existing HTTP interface "DESCRIBEFEATURESCHEMA" to utilize the new DescribeSchemaAsXml API. Note that the period (.) will be used a delimiter character to separate the class names, e.g.:

    http://localhost/mapguide/mapagent/mapagent.fcgi?OPERATION=DESCRIBEFEATURESCHEMA&VERSION=1.0.0&LOCALE=en&CLIENTAGENT=MapGuide+Developer&
        RESOURCEID=Library%3A%2F%2FTest%2FSdf.FeatureSource&SCHEMA=SDF_Schema&CLASSNAMES=Class1.Class2.Class3&FORMAT=text%2Fxml

Implications

• Other related MapGuide Feature Service APIs (such as DescribeSchemaAsXml, GetClassDefinition, GetIdentityProperties, DescribeWfsFeatureType, GetWfsFeature, etc.) will be updated to utilize the new APIs for improved performance.
• 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.
• 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.
• The old DescribeSchema and DescribeSchemaAsXml APIs will be deprecated in the future:

    virtual MgFeatureSchemaCollection* DescribeSchema(MgResourceIdentifier* resource,
        CREFSTRING schemaName);

    virtual STRING DescribeSchemaAsXml(MgResourceIdentifier* resource,
        CREFSTRING schemaName);

Test Plan

• The old DescribeSchema and DescribeSchemaAsXml APIs should work as before.
• Existing unit tests will be updated to utilize the new APIs and re-tested.

Funding/Resources

Autodesk will provide funding and resources.