= 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 classes, and the set of properties available in each of those 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, class names, or a list of properties for a specific 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 !GetSchemaNames, will be added to the API.  The interface for this command is shown below.

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

public:

    /// \brief
    /// Executes the GetSchemaNames 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 class names without having to incur the cost of a !DescribeSchema, a new command, !GetClassNames, will be added to the API for obtaining a list of class names for a given schema.  If schema is not specified, the list will consist of all classes in the feature source.

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

public:
    /// \brief
    /// Gets the name of the schema for 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 GetClassNames 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 class names for the specified schema.
    FDO_API virtual FdoStringCollection* Execute() = 0;
};
}}}

To retrieve specific class definitions, a new command !DescribeClasses will be added to the API for obtaining a schema containing the class collection for only the requested classes.  If the command has set the schema to retrieve, the classes set by !SetClassNames 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.  An exception will be thrown if the schema name specified in both the schema name and qualified class name parameter do not match.

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

    /// \brief
    /// Sets the name of the classes to retrieve. This is optional, if not
    /// specified execution of the command will describe all classes.
    /// 
    /// \param value 
    /// Input the collection of class names
    /// 
    /// \return
    /// Returns nothing
    /// 
    FDO_API virtual void SetClassNames(FdoStringCollection* value) = 0;

    /// \brief
    /// Executes the DescribeClasses command and returns a 
    /// FdoFeatureSchemaCollection. If the specified schema name does not exist,
    /// the Execute method throws an exception.
    /// 
    /// \return
    /// Returns the schema collection representing the schema containing
    /// the class collection for the specified classes.
    /// 
    FDO_API virtual FdoFeatureSchemaCollection* Execute() = 0;

}}}

The performance gain from using the new !GetSchemaNames, !GetClassNames, and !DescribeClasses 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_GetSchemaNames, !FdoCommandType_GetClassNames, and !FdoCommandType_DescribeClasses in the !GetCommands() response.  Providers that do not support the new commands can fall back on using !DescribeSchema and walk through the results to retrieve the schema, class names, and class definitions.


== 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