= !MapGuide RFC 79 - Detailed Exception =

This page contains an change request (RFC) for the !MapGuide Open Source project.
More !MapGuide RFCs can be found on the [wiki:MapGuideRfcs RFCs] page.


== Status ==

||RFC Template Version||(1.0)||
||Submission Date||July 16th, 2009||
||Last Modified||Aleck Sun [[Timestamp]]||
||Author||Aleck Sun||
||RFC Status||draft||
||Implementation Status||pending||
||Proposed Milestone||2.2||
||Assigned PSC guide(s)||Tom Fukushima||
||'''Voting History'''||(vote date)||
||+1||||
||+0||||
||-0||||
||-1||||
||no vote|| ||

== Overview ==

This proposal is to provide more specific exceptions and more information for the underlying FDO errors by exposing native error code of FDO provider. 

== Motivation ==

As per [http://trac.osgeo.org/fdo/wiki/FDORfc37 FDO　RFC37] !FdoException is going to provide a !GetNativeErrorCode method, !MgFdoException should also provide such a method, so that users can get the native error code of FDO exception directly, and then do some specific process regarding the native error code .
Also, in Web Tier API, the !MgApplicationException does not have enough subclasses to indicate the actual error. Hence more specific exception classes will be added into Web Tier API.


== Proposed Solution ==

The following methods will be added to class !MgFdoException to return native error code. Code that creates an !MgFdoException should be updated to assign it a native error code if possible. The native error code of a !MgFdoException will only be accessible through API. The exception message will not include this error code.

{{{
class MG_PLATFORMBASE_API MgFdoException : public MgThirdPartyException
{
    DECLARE_CLASSNAME(MgFdoException)
PUBLISHED_API:
    ////////////////////////////////////////////////////////////////////
    /// \brief
    /// Retrieve the native error code of the underlying FDO exception.
    ///
    /// \return
    /// native error code of an fdo exception
    ///
    INT64 GetNativeErrorCode();

EXTERNAL_API:
////////////////////////////////////////////////////////////////////
    /// \brief
    /// Construct a MgFdoException object.
    ///
    /// \param methodName
    /// Name of the method where the exception occurred.
    /// \param lineNumber
    /// Line number where the exception occurred.
    /// \param fileName
    /// File name where the exception occurred.
    /// \param whatArguments
    /// Collection of arguments used to format the message that describes what the exception is.
    /// \param whyMessageId
    /// ID of the message that describes why the exception occurs.
    /// \param whyArguments
    /// Collection of arguments used to format the message that describes why the exception occurs.
    ///
    MgFdoException(CREFSTRING methodName, INT32 lineNumber,
        CREFSTRING fileName, MgStringCollection* whatArguments,
        CREFSTRING whyMessageId, MgStringCollection* whyArguments,
        INT64 nativeErrorCode) throw();
}; 
}}}
 

The following exception classes will be added into Web Tier 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 !MgFdoException. 
The description of new exception classes above are as follows. 

[[Image(Diagram.JPG, 830)]][[BR]]

The description of new exception classes above are as follows.[[BR]]
    - !MgFdoConnectionException: This exception is the base of the following 3 classes.[[BR]]
    - !MgFdoDisconnectedException: This exception is thrown whenever executing an operation which requires FDO connection is connected, but FDO connection is disconnected[[BR]]
    - !MgFdoInvalidConnectionParamValueException: Thrown when connecting datastore with invalid connection parameters. [[BR]]
    - !MgFdoInsufficentPrivilegesException: Thrown when connecting a FDO data source without sufficient privileges.[[BR]]
    - !MgFdoCommandException: This is the base class for !MgFdoSQLCommandException.[[BR]]
    - !MgFdoSQLCommandException: This is the base class for !MgFdoInvalidSQLStatementException.[[BR]]
    - !MgFdoInvalidSQLStatementException: Thrown when executing an invalid SQL statement.[[BR]]
    - !MgFdoConstraintException: This exception is the base of the following 4 classes.[[BR]]
    - !MgFdoNullPropertyValueException: This exception is thrown whenever setting a non-nullable property value to null. [[BR]]
    - !MgFdoOutOfRangePropertyValueException: Thrown when setting the property value to one which violates constraint !FdoPropertyValueConstraintRange.[[BR]]
    - !MgFdoNotUniquePropertyValueException: Thrown when setting the property value to one which isn’t unique.[[BR]]
    - !MgFdoNotInListPropertyValueException: Thrown when setting the property value to one which violates constraint !FdoPropertyValueConstraintList.[[BR]]
    - !MgFdoSchemaException: This exception is the base of the following 6 classes.[[BR]]
    - !MgFdoSchemaDoesNotExistException: Thrown when the specified schema doesn’t exist.[[BR]]
    - !MgFdoSchemaAlreadyExistsException: Thrown when creating a schema that already exists.[[BR]]
    - !MgFdoClassDoesNotExistException: Thrown when the specified class doesn’t exist.[[BR]]
    - !MgFdoClassAlreadyExistsException: Thrown when creating a class that already exists.[[BR]]
    - !MgFdoPropertyDoesNotExistException: Thrown when the specified class doesn’t exist.[[BR]]
    - !MgFdoPropertyAlreadyExistsException: Thrown when creating a class that already exists.[[BR]]


== Implications ==

The server should be updated to throw the newly added detailed exceptions if possible.

== Test Plan ==

Run the existing unit tests.

== Funding/Resources ==

Autodesk to provide resources / funding