= FDO RFC 23 - New !GetSchemaNames, !GetClassNames, and !DescribeClasses commands =

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 commands 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 when interrogating the provider's capabilities.  

=== Discussion of Alternate Approach (but not proposed as part of this RFC) ===

An alternative solution that does not create the new !DesribeClasses command, is to modify !DescribeSchema to allow the results to be filtered by class names, making it a fundamental part of the command.  There would not be any capability exposed to advertise support for the new behaviour, so updating all providers becomes mandatory.  Although this approach makes for a cleaner API experience in terms of !DescribeSchema usage and consistency amongst all providers, there are some issues which makes the feasibility of this approach unsuitable at this time.

1.  Not all providers would benefit from the new behaviour in !DescribeSchema.  The main benefit would be the responsiveness of the command for the RDBMS providers.  Some of the file-based providers may also benefit, but if caching is used there may not be any significant improvement.  As such, it would not be worth the effort to implement in all providers when there is little to no gain.  The solution to this should include optional implementation on an as-needed basis.

2.  Updating the !DescribeSchema command across all providers would need to be scheduled in a timely manner.  Coordinating a mandatory command update with all provider writers (particularly from third parties) may pose significant challenges.

3.  Resources for implementing in all providers is limited for all concerned parties.  Since implementation of the !DescribeSchema changes is not optional, this may create undue strain on available resources for all interested parties.

By favouring optional implementation of the new !DescribeClasses command over mandatory implementation of changes to the existing !DescribeSchema command, the effort can be focused on where it is needed most.  It also allows flexibility for the other providers to determine if and when the new command should be implemented based on their own criteria.

== 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 !DescribeSchema can be replaced, such as when a complete schema is required for a particular operation.  Also, 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.

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 APIs are used to restrict the response to the data of interest.

== Test Plan ==

Test existing and new APIs to validate correct functionality.

== Funding/Resources ==

Autodesk