= FDO RFC 23 - !DescribeSchema Enhancement and new !EnumerateSchemas, !EnumerateFeatureClasses command =

This page contains a request for change document (RFC) for the FDO Open Source project.  
More FDO RFCs can be found on the [wiki:FDORfcs RFCs] page.

== Status == 
 
||RFC Template Version||1.0|| 
||Submission Date||July 8, 2008||
||Last Modified||Ronnie Louie [[Timestamp]]||
||Author||Ronnie Louie||
||RFC Status||Proposed||
||Implementation Status||pending||
||Proposed Milestone||3.4.0.0||
||Assigned PSC guide(s)||Greg Boone||
||'''Voting History'''||(vote date)||
||+1||||
||+0||||
||-0||||
||-1||||
 
== Overview ==

This RFC is for adding new APIs for retrieving a specific subset of available information that would otherwise be obtained from executing a full !DescribeSchema command.

== Motivation ==

Applications using FDO to interact with underlying datastores are often interested in retrieving a list of the available feature classes, and the set of properties available in each of those feature classes from the available FDO provider.  This information is used to configure a connection to a provider, and to obtain supported geometries and properties from the requested datastore.

Currently this information is retrieved from executing a !DescribeSchema command, which returns a full database schema, containing detailed information about every feature class available from that provider.  For a typical real-world database deployment, containing hundreds of feature classes, it can take a very long time to retrieve all the data for a full schema.

For commonly required tasks such as requesting a list of schema names, feature class names, or a list of properties for a specific class or classes, it could be accomplished more efficiently by retrieving only the requested information.

== Proposed Solution ==

To retrieve the names of the available schemas in a feature source without having to incur the cost of a !DescribeSchema, a new command !EnumerateSchemas, will be added to the API.  The interface for this command is shown below.

{{{
/// \brief
/// The FdoIEnumerateSchemas interface defines the EnumerateSchemas command, which
/// retrieves the list of available schemas. 
/// The Execute operation returns an FdoStringCollection
/// object.
class FdoIEnumerateSchemas : public FdoICommand
{
    friend class FdoIConnection;

public:

    /// \brief
    /// Executes the EnumerateSchemas command and returns a 
    /// FdoStringCollection. 
    /// 
    /// \return
    /// Returns the string collection of the names of the available schemas.
    FDO_API virtual FdoStringCollection* Execute() = 0;
};
}}}

To retrieve the feature class names without having to incur the cost of a !DescribeSchema, a new command, !EnumerateFeatureClasses, will be added to the API for obtaining a list of feature class names for a given schema.  If schema is not specified, the list will consist of all feature classes in the feature source.

{{{
/// \brief
/// The FdoIEnumerateFeatureClasses interface defines the EnumerateFeatureClasses command,
/// which retrieves the list of available feature class names. 
/// The Execute operation returns an FdoStringCollection object.
class FdoIEnumerateFeatureClasses : public FdoICommand
{
    friend class FdoIConnection;

public:
    /// \brief
    /// Gets the name of the schema for the enumeration. This function is optional;
    /// if not specified, execution of the command will enumerate the classes in all schemas.
    /// 
    /// \return
    /// Returns the schema name
    /// 
    FDO_API virtual FdoString* GetSchemaName() = 0;

    /// \brief
    /// Sets the name of the schema for the enumeration. This function is optional; if not
    /// specified execution of the command will enumerate the classes in all schemas.
    /// 
    /// \param value 
    /// Input the schema name
    /// 
    /// \return
    /// Returns nothing
    /// 
    FDO_API virtual void SetSchemaName(FdoString* value) = 0;

    /// \brief
    /// Executes the EnumerateFeatureClasses command and returns a 
    /// FdoStringCollection. If the specified schema name does not exist,
    /// the Execute method throws an exception.
    /// 
    /// \return
    /// Returns the string collection of the fully qualified feature class names for the specified schema.
    FDO_API virtual FdoStringCollection* Execute() = 0;
};
}}}

To retrieve specific feature class definitions, the existing !DescribeSchema API will be modified to add the following methods to instruct the !DescibeSchema command to return a schema that contains only the requested classes.  If the command has set the schema to retrieve, the classes set by !SetFeatureClassNames will be restricted to that schema.  If no schema has been set, fully qualified class names should be passed to the !SetFeatureClassNames method.  Finally, if the schema has not been set, and class names are not fully qualified, then the result will contain all matching class names.

{{{
    /// \brief
    /// Gets the names of the feature classes to retrieve. This is optional,
    /// if not specified execution of the command will describe all feature classes.
    /// 
    /// \return
    /// Returns the collection of feature class names
    /// 
    FDO_API virtual FdoStringCollection* GetFeatureClassNames() = 0;

    /// \brief
    /// Sets the name of the feature classes to retrieve. This is optional, if not
    /// specified execution of the command will describe all feature classes.
    /// 
    /// \param value 
    /// Input the collection of feature class names
    /// 
    /// \return
    /// Returns boolean value to indicate if the provider supports specifying class names for this command.
    /// 
    FDO_API virtual bool SetFeatureClassNames(FdoStringCollection* value) = 0;

}}}

The performance gain from using the new !EnumerateSchemas and !EnumerateFeatureClasses command will be most notable for the RDBMS-based FDO providers. Support for the commands will be indicated by the provider's command capabilities object.  Hence, only the RDBMS-based FDO providers will include  !FdoCommandType_EnumerateSchemas and !FdoCommandType_EnumerateFeatureClasses in the !GetCommands() response.  Providers that do not support this command will have to fall back on using !DescribeSchema and walk through the results to retrieve the schema and class names.

The !DescribeSchema command for non-RDBMS FDO providers will return the schema(s) for all the feature classes regardless of the set of classes specified by the !SetFeatureClassNames method.  !SetFeatureClassNames will return a boolean to provide feedback to the caller for indicating whether the command supports specifying classes as a criteria when executed against a particular provider.

== Implications ==

Application code that currently uses !DescribeSchema to enumerate schema/class names or retrieve class definitions should be updated to utilize the new APIs for improved performance.  The application developer should be aware that not all occurrences of the original !DescribeSchema can be replaced, such as when a complete schema is required for a particular operation.

The existing !DescribeSchema API, which retrieves the full schema for all the available feature classes, will continue to perform as before.  Performance gains will only be realized when the new API is used to restrict the response to the feature class or classes of interest.

== Test Plan ==

Test existing and new APIs to validate correct functionality.

== Funding/Resources ==

Autodesk