Changes between Version 10 and Version 11 of FDORfc23


Ignore:
Timestamp:
Jul 16, 2008, 9:46:39 AM (16 years ago)
Author:
ronnielouie
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • FDORfc23

    v10 v11  
    2626== Motivation ==
    2727
    28 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.
     28Applications 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.
    2929
    3030Currently 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.
    3131
    32 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.
     32For 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.
    3333
    3434== Proposed Solution ==
    3535
    36 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.
     36To 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.
    3737
    3838{{{
    3939/// \brief
    40 /// The FdoIEnumerateSchemas interface defines the EnumerateSchemas command, which
    41 /// retrieves the list of available schemas.
    42 /// The Execute operation returns an FdoStringCollection
    43 /// object.
    44 class FdoIEnumerateSchemas : public FdoICommand
     40/// The FdoIGetSchemaNames interface defines the GetSchemaNames command, which
     41/// retrieves the list names for the available schemas.
     42/// The Execute operation returns an FdoStringCollection object.
     43class FdoIGetSchemaNames : public FdoICommand
    4544{
    4645    friend class FdoIConnection;
    … …  
    4948
    5049    /// \brief
    51     /// Executes the EnumerateSchemas command and returns a
     50    /// Executes the GetSchemaNames command and returns a
    5251    /// FdoStringCollection.
    5352    ///
    … …  
    5857}}}
    5958
    60 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.
     59To 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.
    6160
    6261{{{
    6362/// \brief
    64 /// The FdoIEnumerateFeatureClasses interface defines the EnumerateFeatureClasses command,
    65 /// which retrieves the list of available feature class names.
     63/// The FdoIGetClassNames interface defines the GetClassNames command,
     64/// which retrieves the list of available class names.
    6665/// The Execute operation returns an FdoStringCollection object.
    67 class FdoIEnumerateFeatureClasses : public FdoICommand
     66class FdoIGetClassNames : public FdoICommand
    6867{
    6968    friend class FdoIConnection;
    … …  
    7170public:
    7271    /// \brief
    73     /// Gets the name of the schema for the enumeration. This function is optional;
     72    /// Gets the name of the schema for enumeration. This function is optional;
    7473    /// if not specified, execution of the command will enumerate the classes in all schemas.
    7574    ///
    … …  
    9291
    9392    /// \brief
    94     /// Executes the EnumerateFeatureClasses command and returns a
     93    /// Executes the GetClassNames command and returns a
    9594    /// FdoStringCollection. If the specified schema name does not exist,
    9695    /// the Execute method throws an exception.
    9796    ///
    9897    /// \return
    99     /// Returns the string collection of the fully qualified feature class names for the specified schema.
     98    /// Returns the string collection of the fully qualified class names for the specified schema.
    10099    FDO_API virtual FdoStringCollection* Execute() = 0;
    101100};
    102101}}}
    103102
    104 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.
     103To 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.
    105104
    106105{{{
    107106    /// \brief
    108     /// Gets the names of the feature classes to retrieve. This is optional,
    109     /// if not specified execution of the command will describe all feature classes.
     107    /// Gets the names of the classes to retrieve. This is optional,
     108    /// if not specified execution of the command will describe all classes.
    110109    ///
    111110    /// \return
    112     /// Returns the collection of feature class names
     111    /// Returns the collection of class names
    113112    ///
    114     FDO_API virtual FdoStringCollection* GetFeatureClassNames() = 0;
     113    FDO_API virtual FdoStringCollection* GetClassNames() = 0;
    115114
    116115    /// \brief
    117     /// Sets the name of the feature classes to retrieve. This is optional, if not
    118     /// specified execution of the command will describe all feature classes.
     116    /// Sets the name of the classes to retrieve. This is optional, if not
     117    /// specified execution of the command will describe all classes.
    119118    ///
    120119    /// \param value
    121     /// Input the collection of feature class names
     120    /// Input the collection of class names
    122121    ///
    123122    /// \return
    124     /// Returns boolean value to indicate if the provider supports specifying class names for this command.
     123    /// Returns nothing
    125124    ///
    126     FDO_API virtual bool SetFeatureClassNames(FdoStringCollection* value) = 0;
     125    FDO_API virtual void SetClassNames(FdoStringCollection* value) = 0;
     126
     127    /// \brief
     128    /// Executes the DescribeClasses command and returns a
     129    /// FdoFeatureSchemaCollection. If the specified schema name does not exist,
     130    /// the Execute method throws an exception.
     131    ///
     132    /// \return
     133    /// Returns the schema collection representing the schema containing
     134    /// the class collection for the specified classes.
     135    ///
     136    FDO_API virtual FdoFeatureSchemaCollection* Execute() = 0;
    127137
    128138}}}
    129139
    130 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.
     140The 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.
    131141
    132 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.
    133142
    134143== Implications ==