springnet-commits

[Mark P. <mar...@us...>]

Update of /cvsroot/springnet/Spring.Net/doc/reference/src
In directory sc8-pr-cvs8.sourceforge.net:/tmp/cvs-serv13106

Modified Files:
	dao.xml 
Log Message:
additional details on how to customize error code to dao exception translation.

Index: dao.xml
===================================================================
RCS file: /cvsroot/springnet/Spring.Net/doc/reference/src/dao.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -d -r1.4 -r1.5
*** dao.xml	16 Jan 2008 17:21:44 -0000	1.4
--- dao.xml	23 Jan 2008 03:35:10 -0000	1.5
***************
*** 104,132 ****
      <literal>ErrorCodeExceptionTranslator</literal>, is provided that uses the
      error codes defined for each data provider in the file dbproviders.xml.
!     Refer to this file for the exact mappings of error codes to Spring
!     DataAccessExceptions. <classname>ErrorCodeExceptionTranslator</classname>
!     allows you to customize the mapping behavior without having customize the
!     <classname>IDbProvider</classname> metadata (typically in dbproviders.xml
!     but can also be defined in an external location). .You can subclass
!     <classname>ErrorCodeExceptionTranslator</classname> and override the
!     method, <literal>DataAccessException TranslateException(string task,
!     string sql, string errorCode, Exception exception)</literal>. This will be
!     called before referencing the metadata to perform exception translation.
!     The property <literal>ExceptionTranslator</literal> on
!     <literal>AdoTemplate</literal> and <literal>HibernateTemplate</literal>
!     lets you use your own custom implementation.</para>
  
!     <para>You can use this API directly in your own Spring independent data
!     layer. If you are using Spring's ADO.NET abstraction class,
!     <literal>AdoTemplate</literal>, or <literal>HibernateTemplate</literal>,
!     the converted exceptions will be thrown automatically. Somewhere in
!     between these two cases is using Spring's declarative transaction
!     management features in .NET 2.0 with the raw ADO.NET APIs and using
!     <literal>IAdoExceptionTranslator</literal> in your exception handling
!     layer (which might be implemented in AOP using Spring's exception
!     translation aspect).</para>
  
!     <para>Some of the more common exceptions are described here. Please refer
!     to the API documentation for more details.</para>
  
      <table>
--- 104,195 ----
      <literal>ErrorCodeExceptionTranslator</literal>, is provided that uses the
      error codes defined for each data provider in the file dbproviders.xml.
!     Refer to this file, an embedded resource in the Spring.Data assembly, for
!     the exact mappings of error codes to Spring DataAccessExceptions. </para>
  
!     <para>A common need is to modify the error codes that are map onto the
!     exception hierarchy. There are several ways to accomplish this task.
!     </para>
  
!     <para>One approach is to override the error codes that are defined in
!     <code>assembly://Spring.Data/Spring.Data.Common/dbproviders.xml</code>. By
!     default, the <link
!     linkend="dbprovider-dbprovider">DbProviderFactory</link> will look for
!     additional metadata for the IoC container it uses internally to define and
!     manage the DbProviders in a file named <literal>dbProviders.xml</literal>
!     located in the root runtime directory. (You can change this location, see
!     the documentation on <link lang=""
!     linkend="dbprovider-dbprovider">DbProvider</link> for more information.)
!     This is a standard Spring application context so all features, such as
!     <link
!     linkend="objects-factory-customizing-factory-postprocessors">ObjectFactoryPostProcessors</link>
!     are available and will be automatically applied. Defining a <link
!     linkend="objects-factory-overrideconfigurer">PropertyOverrideConfigurer</link>
!     in this additional configuration file will allow for you to override
!     specific property values defined in the embedded resource file. As an
!     example, the additional <literal>dbProviders.xml</literal> file shown
!     below will add the error code <literal>2601</literal> to the list of error
!     codes that map to a
!     <literal>DataIntegrityViolationException</literal>.</para>
! 
!     <para><programlisting>&lt;objects xmlns='http://www.springframework.net'&gt;
!  
!   &lt;alias name='SqlServer-2.0' alias='SqlServer2005'/&gt;
!  
!   &lt;object name="appConfigPropertyOverride" type="Spring.Objects.Factory.Config.PropertyOverrideConfigurer, Spring.Core"&gt;
!     &lt;property name="Properties"&gt;
!       &lt;name-values&gt;
!         &lt;add key="SqlServer2005.DbMetadata.ErrorCodes.DataIntegrityViolationCodes"
!              value="544,2601,2627,8114,8115"/&gt;
!       &lt;/name-values&gt;
!     &lt;/property&gt;
!   &lt;/object&gt;
! 
! &lt;/objects&gt;</programlisting>The reason to define the alias is that <link
!     linkend="objects-factory-overrideconfigurer">PropertyOverrideConfigurer</link>
!     assumes a period <literal>(.)</literal> as the separator to pick out the
!     object name but the names of the objects in
!     <literal>dbProviders.xml</literal> have periods in them (i.e.
!     SqlServer-2.0 or System.Data.SqlClient). Creating an alias that has no
!     periods in the name is a workaround. </para>
! 
!     <para>Another way to customize the mappings of error codes to exceptions
!     is to subclass <classname>ErrorCodeExceptionTranslator</classname> and
!     override the method, <literal>DataAccessException
!     TranslateException(string task, string sql, string errorCode, Exception
!     exception)</literal>. This will be called before referencing the metadata
!     to perform exception translation. The vendor specific error code provided
!     as a method argument has already been parsed out of the raw ADO.NET
!     exception. If you create your own specific subclass, then you should set
!     the property <literal>ExceptionTranslator</literal> on
!     <literal>AdoTemplate</literal> and
!     <literal>HibernateTemplate/HibernateTransactionManager</literal> to refer
!     to your custom implementation (unless you are using autowiring).</para>
! 
!     <para>The third way is to write an implementation of
!     <literal>IAdoExceptionTranslator</literal> and set the property
!     <literal>FallbackTranslator</literal>'on
!     <literal>ErrorCodeExceptionTranslator</literal>. In this case you are
!     responsible for parsing our the vendor specific error code from the raw
!     ADO.NET exception. As with the case of subclassing
!     ErrorCodeExceptionTranslator, you will need to refer to this custom
!     exception translator when using <literal>AdoTemplate</literal> or
!     <literal>HibernateTemplate/HibernateTransactionManager</literal>.</para>
! 
!     <para>The ordering of the exception translation processing is as follows.
!     The method TranslateException is called first, then the standard exception
!     translation logic, then the FallbackTranslator. </para>
! 
!     <para>Note that you can use this API directly in your own Spring
!     independent data layer. If you are using Spring's ADO.NET abstraction
!     class, <literal>AdoTemplate</literal>, or
!     <literal>HibernateTemplate</literal>, the converted exceptions will be
!     thrown automatically. Somewhere in between these two cases is using
!     Spring's declarative transaction management features in .NET 2.0 with the
!     raw ADO.NET APIs and using <literal>IAdoExceptionTranslator</literal> in
!     your exception handling layer (which might be implemented in AOP using
!     Spring's exception translation aspect).</para>
! 
!     <para>Some of the more common data access exceptions are described here.
!     Please refer to the API documentation for more details.</para>
  
      <table>