Context Navigation

Changes between Version 20 and Version 21 of FDORfc23

Timestamp:: 07/18/08 10:04:03 (16 years ago)
Author:: ronnielouie
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

FDORfc23

-              v20
+              v21
 = FDO RFC 23 - New !GetSchemaNames, !GetClassNames, and !DescribeClasses commands =
+= FDO RFC 23 - New !GetSchemaNames, !GetClassNames commands, and !DescribeSchema hint =
 This page contains a request for change document (RFC) for the FDO Open Source project.
 …
 == Proposed Solution ==
 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.
+The performance gain from using the new !GetSchemaNames and !GetClassNames commands, and the modified !DescribeSchema command will be most notable for the RDBMS-based FDO providers. Support for the new commands will be indicated by the provider's command capabilities object.  Hence, only the RDBMS-based FDO providers will include  !FdoCommandType_GetSchemaNames, and !FdoCommandType_GetClassNames in the !GetCommands() response when interrogating the provider's capabilities.  Likewise, the new behaviour in !DescribeSchema will be supported in the RDBMS-based providers.  For all the non-RDBMS based providers, there will not be any change in the execution of the !DescribeSchema command.
 === !GetSchemaNames ===
 …
 }}}
+=== !DescribeClasses ===
+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 !SetClassNames 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.
+=== !DescribeSchema ===
+To retrieve specific class definitions, the existing !DescribeSchema command will be modified to allow specifying the classes contained in the class collection of the resulting schema.  In particular, a new method !SetClassNames will be added to the command to facilitate the request for a collection of certain 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 !SetClassNames 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.
+Since this change involves an update to the !DescribeSchema command interface, implementation of the !SetClassNames method will be mandatory for all providers.  However, due to resource constraints and the cost versus benefit of restricting the results to certain classes for each provider, it is proposed that the class names passed to this method serve as a hint for the !DescribeSchema command during execution.  Providers will not necessarily take advantage of the hint, depending on each provider's criteria and implementation schedule, and simply return the full schema.  There would not be any capability exposed to advertise support for the new behaviour, and no error or exception thrown if the provider does not intend to use the hint.  Initially the RDBMS-based providers will use the hint and restrict the returned schema to the specific classes, since those providers should exhibit performance improvements when the full schema does not need to be returned.
 {{{
 /// \brief
+/// The FdoIDescribeClasses interface defines the DescribeClasses command, which
+/// describes specific classes available for a particular schema. The DescribeClasses
+/// command can describe multiple classes that are available from  the connection.
+/// The Execute operation returns an FdoFeatureSchemaCollection object.
+class FdoIDescribeClasses : public FdoICommand
+/// The FdoIDescribeSchema interface defines the DescribeSchema command, which
+/// describes the feature schemas available from the connection. The DescribeSchema
+/// command can describe a single schema or all schemas available from
+/// the connection. The Execute operation returns an FdoFeatureSchemaCollection
+/// object.
+class FdoIDescribeSchema : public FdoICommand
+{
     friend class FdoIConnection;
 …
 public:
     /// \brief
+    /// Gets the name of the schema that the command will be restricted to.
+    /// This function is optional; if not specified, execution of the command will
+    /// describe requested classes using the qualified class name.  If the class name
+    /// is not qualified, the requested class from all schemas will be described.
+    /// Gets the name of the schema to describe. This function is optional;
+    /// if not specified, execution of the command will describe all schemas.
     ///
     /// \return
 …
     /// \brief
+    /// Sets the name of the schema that the command will be restricted to.
+    /// This function is optional; if not specified, execution of the command will
+    /// describe requested classes using the qualified class name.  If the class name
+    /// is not qualified, the requested class from all schemas will be described.
+    /// Sets the name of the schema to describe. This function is optional; if not
+    /// specified execution of the command will describe all schemas.
     ///
     /// \param value
 …
     /// Gets the names of the classes to retrieve. This is optional,
     /// if not specified execution of the command will describe all classes.
+    /// If the class name is not qualified, and the schema name is not specified,
+    /// the requested class from all schemas will be described.
+    /// The class names specified serve only as a hint.  Use of the hint
+    /// during command execution is provider dependent.  Providers that
+    /// will not use the hint will describe the schema for all classes.
     ///
     /// \return
 …
     /// Sets the name of the classes to retrieve. This is optional, if not
     /// specified execution of the command will describe all classes.
+    /// If the class name is not qualified, and the schema name is not specified,
+    /// the requested class from all schemas will be described.
+    /// The class names specified serve only as a hint.  Use of the hint
+    /// during command execution is provider dependent.  Providers that
+    /// will not use the hint will describe the schema for all classes.
     ///
     /// \param value
 …
     /// \brief
+    /// Executes the DescribeClasses command and returns a
+    /// FdoFeatureSchemaCollection. If the specified schema name or a class name does not exist,
+    /// Executes the DescribeSchema command and returns a
+    /// FdoFeatureSchemaCollection. If a schema name is given that has
+    /// references to another schema, the dependent schemas will
+    /// be returned as well. 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.
+    /// Returns the schema collection representing the schema created.
+    /// The element states for all elements will be set to FdoSchemaElementState_Unchanged.
+    /// Each provider-specific implementation of Execute() can ensure
+    /// that this is the case by
+    /// calling FdoFeatureSchema::AcceptChanges() for each feature schema
+    /// in the returned collection.
     ///
     FDO_API virtual FdoFeatureSchemaCollection* Execute() = 0;
 …
 === 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.
+An alternative solution is to modify !DescribeSchema to make filtering of the schema by class names a fundamental part of the command, requiring all providers to have full implementation for the new behviour.  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.
 .  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.
 …
 .  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.
+By favouring optional use a hint to restrict classes in !DescribeSchema over mandatory implementation of support for class filtering, the effort can be focused on where it is needed most.  It also allows flexibility for the other providers to determine if and when use of the hint 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.
+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 when executed against supported providers.
 == Test Plan ==