Changes between Version 1 and Version 2 of FDORfc23


Ignore:
Timestamp:
07/07/08 16:24:55 (16 years ago)
Author:
ronnielouie
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • FDORfc23

    v1 v2  
    1 = FDO RFC 23 - DescribeSchema Enhancement and add new EnumerateFeatureClasses command =
     1= FDO RFC 23 - !DescribeSchema Enhancement and add new !EnumerateFeatureClasses command =
    22
    3 This page contains a request for comments document (RFC) for the FDO Open Source project. 
     3This page contains a request for change document (RFC) for the FDO Open Source project. 
    44More FDO RFCs can be found on the [wiki:FDORfcs RFCs] page.
    55
    … …  
    77 
    88||RFC Template Version||(1.0)||
    9 ||Submission Date||(Date/Time submitted)||
    10 ||Last Modified||(your name here) [[Timestamp]]||
    11 ||Author||(your name here)||
    12 ||RFC Status||(draft, proposed, frozen for vote, adopted, retracted, or rejected)||
    13 ||Implementation Status||(pending, under development, completed)||
    14 ||Proposed Milestone||(e.g. 1.1, 1.3)||
     9||Submission Date||July 7, 2008||
     10||Last Modified||(Ronnie Louie) [[Timestamp]]||
     11||Author||(Ronnie Louie)||
     12||RFC Status||draft||
     13||Implementation Status||pending||
     14||Proposed Milestone||3.4.0.0||
    1515||Assigned PSC guide(s)||(when determined)||
    1616||'''Voting History'''||(vote date)||
    17 ||+1||Bob, Mateusz||
    18 ||+0||Frank||
    19 ||-0||Orest||
    20 ||-1||Greg (troublemaker)||
     17||+1||||
     18||+0||||
     19||-0||||
     20||-1||||
    2121 
    2222== Overview ==
    2323
    24 This section briefly describes the problem set, and the proposed solution in general terms.  It should be deliberately short, a couple of sentences or so.
     24This 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.
    2525
    2626== Motivation ==
    2727
    28 This is the most important part of the RFC.  It describes the problem domain in detail.  Focusing on this will allow reviewers to fully understand why the proposed change is being made, and potentially suggest different/better ways of accomplishing the desired results.  The more time we spend on understanding the problem, the better our solution will be.
     28Applications 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.
     29
     30Currently 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.
     31
     32For commonly required tasks such as requesting a list of 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.
    2933
    3034== Proposed Solution ==
    3135
    32 This is a more detailed description of the actual changes desired.  The contents of this section will vary based on the target of the RFC, be it a technical change, website change, or process change.  For example, for a technical change, items such as files, XML schema changes, and API chances would be identified.  For a process change, the new process would be laid out in detail.  For a website change, the files affected would be listed.
     36To retrieve the feature class names without having 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.
     37
     38{{{
     39/// \brief
     40/// The FdoIEnumerateFeatureClasses interface defines the EnumerateFeatureClasses command,
     41/// which retrieves the list of available feature class names.
     42/// The Execute operation returns an FdoStringCollection object.
     43class FdoIEnumerateFeatureClasses : public FdoICommand
     44{
     45    friend class FdoIConnection;
     46
     47public:
     48    /// \brief
     49    /// Gets the name of the schema for the enumeration. This function is optional;
     50    /// if not specified, execution of the command will enumerate the classes in all schemas.
     51    ///
     52    /// \return
     53    /// Returns the schema name
     54    ///
     55    FDO_API virtual FdoString* GetSchemaName() = 0;
     56
     57    /// \brief
     58    /// Sets the name of the schema for the enumeration. This function is optional; if not
     59    /// specified execution of the command will enumerate the classes in all schemas.
     60    ///
     61    /// \param value
     62    /// Input the schema name
     63    ///
     64    /// \return
     65    /// Returns nothing
     66    ///
     67    FDO_API virtual void SetSchemaName(FdoString* value) = 0;
     68
     69    /// \brief
     70    /// Executes the EnumerateFeatureClasses command and returns a
     71    /// FdoStringCollection. If the specified schema name does not exist,
     72    /// the Execute method throws an exception.
     73    ///
     74    /// \return
     75    /// Returns the string collection of the feature classes for the specified schema.
     76    FDO_API virtual FdoStringCollection* Execute() = 0;
     77};
     78}}}
     79
     80To retrieve specific feature classes, 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.
     81
     82{{{
     83    /// \brief
     84    /// Gets the names of the feature classes to retrieve. This is optional,
     85    /// if not specified execution of the command will describe all feature classes.
     86    ///
     87    /// \return
     88    /// Returns the collection of feature class names
     89    ///
     90    FDO_API virtual FdoStringCollection* GetFeatureClassNames() = 0;
     91
     92    /// \brief
     93    /// Sets the name of the feature classes to retrieve. This is optional, if not
     94    /// specified execution of the command will describe all feature classes.
     95    ///
     96    /// \param value
     97    /// Input the collection of feature class names
     98    ///
     99    /// \return
     100    /// Returns nothing
     101    ///
     102    FDO_API virtual void SetFeatureClassNames(FdoStringCollection* value) = 0;
     103
     104}}}
     105
     106The proposed changes will need to be completed for all FDO providers.  Generally speaking, response time for a full !DescribeSchema command is not much of an issue for the file-based FDO providers when compared to the response time for the RDBMS-based FDO providers. 
     107
     108The performance gain from using the new EnumerateFeatureClasses command will be most notable for the RDBMS-based FDO providers. The !EnumerateFeatureClasses command will throw a "Not Implemented" exception when executed against non-RDBMS FDO providers.
     109
     110Additional information will be added to the !GetCapabilities response to allow the providers to indicate its support for the new command.  These will default to “false” for all non-RDBMS FDO providers.
     111
     112The 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. 
    33113
    34114== Implications ==
    35115
    36 This section allows discussion of the repercussions of the change, such as whether there will be any breakage in backwards compatibility, if documentation will need to be updated, etc.
     116Application code that currently uses !DescribeSchema to retrieve only class names or 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.
    37117
    38118== Test Plan ==
    39119
    40 How the proposed change will be tested, if applicable.  New unit tests should be detailed here???
     120Test existing and new APIs to validate correct functionality.
    41121
    42122== Funding/Resources ==
    43123
    44 This section will confirm that the proposed feature has enough support to proceed.  This would typically mean that the entity making the changes would put forward the RFC, but a non-developer could act as an RFC author if they are sure they have the funding to cover the change.
     124Autodesk