= 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 [wiki:FDORfcs 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.

[[Image(ExceptionClasses.JPG, 782)]][[BR]]

    - !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.