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 RFCs page.

Status

RFC Template Version	(1.0)
Submission Date	July 16th, 2009
Last Modified	Aleck Sun Timestamp
Author	Aleck Sun
RFC Status	adopted
Implementation Status	implemented
Proposed Milestone	2.2
Assigned PSC guide(s)	Tom Fukushima
Voting History	August 17, 2009
+1	Tom, Jason, Trevor, Andy, Bruce, Kenneth
+0
-0
-1
no vote	Bob, Harris, Paul

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 Web Tier API, there aren't enough exception classes 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.

The description of new exception classes above are as follows.

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

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