This page describes the format to be used when developing [wiki:MapGuideRfcs RFCs] for proposal to the mapguide-internals mail list and subsequent presentation to the !MapGuide PSC. New RFCs should be created following the instructions at the top of the [wiki:MapGuideRfcs RFCs] page.

The  original version of this document was based on the RFCs from http://mapserver.gis.umn.edu/development/rfc.

RFC Template Version:  1.0
Last Modified:  04:50, 3 November 2006 (CET)  (Jason Birch)

----
= !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 17th, 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 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 GIS Platform API, the MgApplicationException does not have enough subclasses to indicate the actual error. Hence more specific exception classes will be added into GIS Platform.


== 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 it possible

{{{
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 GIS Platform 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 !MgException. 
The description of new exception classes above are as follows. 



The description of new exception classes above are as follows.[[BR]]
!MgNotConnectedException: Thrown when executing an operation that require feature source connection is connected.[[BR]]
!MgWrongConnectionParamValueException: Thrown when connecting datastore with invalid connection parameters. [[BR]]
!MgInsufficentPrivilegesException: Thrown when connecting a FDO data source without sufficient privileges.[[BR]]
!MgInvalidSQLStatementException: Thrown when executing an invalid SQL statement.[[BR]]
!MgOutOfRangePropertyValueException: Thrown when setting the property value to one which violates constraint !FdoPropertyValueConstraintRange.[[BR]]
!MgNotUniquePropertyValueException: Thrown when setting the property value to one which isn’t unique.[[BR]]
!MgNotInListPropertyValueException: Thrown when setting the property value to one which violates constraint !FdoPropertyValueConstraintList.[[BR]]
!MgSchemaDoesNotExistException: Thrown when the specified schema doesn’t exist.[[BR]]
!MgSchemaAlreadyExistsException: Thrown when creating a schema that already exists.[[BR]]
!MgClassDoesNotExistException: Thrown when the specified class doesn’t exist.[[BR]]
!MgClassAlreadyExistsException: Thrown when creating a class that already exists.[[BR]]
!MgPropertyDoesNotExistException: Thrown when the specified class doesn’t exist.[[BR]]
!MgPropertyAlreadyExistsException: 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