FDO RFC 37 - Detailed Exception

This page contains an change request (RFC) for the FDO Open Source project. More FDO RFCs can be found on the RFCs page.

Status

RFC Template Version	(1.0)
Submission Date	June 08, 2009
Last Modified	Greg Boone Timestamp
Author	Leaf Li
RFC Status	Adopted
Implementation Status	Under Development
Proposed Milestone	3.5.0.0
Assigned PSC guide(s)	Greg Boone
Voting History	July 14, 2009
+1	Greg Boone, Orest Halustchak, Jackie Ng
+0	Frank Warmerdam, Traian Stanev
-0
-1

Motivation

To handle errors more accurately by providing more detailed exception information

Overview

FdoException is the root class for FDO exception handling. Currently FDO provides less than 10 exception classes derived from FdoException. So it is difficult for users to get the accurate error information so that they can take some actions according to exception type instead of just showing an error message. More exception classes will be provided in this RFC.

However, it is impossible for FDO exception classes to cover all exception type. For some FDO data sources such as Oracle and SQL Server, they already return their native error code to FDO provider when encountering errors. If FDO can return the native error code to users, users may be able to handle it properly. For exmaple,

try
{
    ......
}
catch (FdoException* e)
{
    FdoInt64 errorCode = e->GetNativeErrorCode();
    e->Release();
    // Take some measures according to native error code
    ......
}

Proposed Solution

The following methods will be added to class FdoException to return native error code. Providers will be updated to assign native error code when a FDO exception is created. If there is no native error code assigned, the default value is 0.

class FdoException : public FdoIDisposable
{
public:
    /// \brief
    /// Returns an instance of a FdoException using the specified arguments.
    /// 
    /// \param message 
    /// Input the error message
    /// \param nativeErrorCode 
    /// Input the native error code, which is returned by FDO data source.
    /// 
    /// \return
    /// Returns the FdoException object
    /// 
    FDO_API_COMMON static FdoException* Create(FdoString* message, FdoInt64 nativeErrorCode);

    /// \brief
    /// Returns an instance of a FdoException using the specified arguments.
    /// 
    /// \param message 
    /// Input the error message
    /// \param cause
    /// Input the cause of the error.
    /// \param nativeErrorCode 
    /// Input the native error code, which is returned by FDO data source.
    /// 
    /// \return
    /// Returns the FdoException object
    /// 
    FDO_API_COMMON static FdoException* Create(FdoString* message, FdoException* cause, FdoInt64 nativeErrorCode);

    /// \brief
    /// Gets the native error code returned from FDO data source
    /// 
    /// \return
    /// Returns the native error code
    /// 
    FDO_API_COMMON virtual FdoInt64 GetNativeErrorCode();
}

The following exception classes will be added to FDO API. In the following class diagram, ones with white color are the existing classes and ones with light green color are the new ones. There are no any new methods added to those new exception classes. All of methods are inherited from FdoIException.

The description of new exception classes above are as follows.

• FdoDisconnectedException: The FdoDisconnectedException class is the exception type thrown from classes in the Data package. This exception is thrown whenever executing an operation which requires FDO connection is connected, but FDO connection is disconnected.
• FdoInvalidConnectionParamValueException: The FdoInvalidConnectionParamValueException class is the exception type thrown from classes in the Connections package. This exception is thrown whenever connecting datastore with invalid connection parameters. The message should always mention which parameters were invalid.
• FdoInsufficentPrivilegesException: The FdoInsufficentPrivliegesException class is the exception type thrown from classes in the Connections package. This exception is thrown whenever connecting a FDO data source without sufficient privileges.
• FdoSQLCommandException: The FdoSQLCommandException class is the exception type thrown from class FdoISQLCommand.
• FdoInvalidSQLStatementException: The FdoInvalidSQLStatementException class is the exception type thrown from class FdoISQLCommand. This exception is thrown whenever executing an invalid SQL statement.
• FdoConstraintException: The FdoConstraintException class is the exception type thrown from classes editing property values of datastore.
• FdoNullPropertyValueException: The FdoNullPropertyValueException class is the exception type thrown from classes editing property values of datastore. This exception is thrown whenever setting a non-nullable property value to null.
• FdoOutOfRangePropertyValueException: The FdoOutOfRangePropertyValueException class is the exception type thrown from classes editing property values of datastore. This exception is thrown whenever setting the property value to one which violates constraint FdoPropertyValueConstraintRange.
• FdoNonUniquePropertyValueException: The FdoNonUniquePropertyValueException class is the exception type thrown from classes editing property values of datastore. This exception is thrown whenever setting the property value to one which isn’t unique.
• FdoNotInListPropertyValueException: The FdoNotInListPropertyValueException class is the exception type thrown from classes editing property values of datastore. This exception is thrown whenever setting the property value to one which violates constraint FdoPropertyValueConstraintList.
• FdoSchemaDoesNotExistException: The FdoSchemaDoesNotExistException class is the exception type thrown from classes in the Data and Schema packages. This exception is thrown whenever the specified schema doesn’t exist.
• FdoSchemaAlreadyExistsException: The FdoSchemaDoesNotExistException class is the exception type thrown from classes FdoIApplySchema. This exception is thrown whenever creating a schema which already exists.
• FdoClassDoesNotExistException: The FdoClassDoesNotExistException class is the exception type thrown from classes in the Data and Schema packages. This exception is thrown whenever the specified class doesn’t exist.
• FdoClassAlreadyExistsException: The FdoClassAlreadyExistsException class is the exception type thrown from classes FdoIApplySchema. This exception is thrown whenever creating a class which already exists.
• FdoPropertyDoesNotExistException: The FdoClassDoesNotExistException class is the exception type thrown from classes in the Data and Schema packages. This exception is thrown whenever the specified class doesn’t exist.
• FdoPropertyAlreadyExistsException: The FdoClassAlreadyExistsException class is the exception type thrown from classes FdoIApplySchema. This exception is thrown whenever creating a class which already exists.

Managed FDO API

Currently FDO Managed Interfaces provide OSGeo::FDO::Common::Exception only. So we will create managed classes for all of existing exception classes and new exception classes proposed in this RFC. OSGeo::FDO::Common::Exception will be updated in a similar manner to reflect the proposed changes in this RFC too.

Provider Implementation

SQLite will be enhanced to support it. Update for other providers will be implemented if resourcing and funding can be obtained in the future.

Test Plan

Existing FDO Core and Provider level unit tests will be expanded to test the proposed enhancements defined above.

Funding/Resources

Autodesk to provide resources / funding.