You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ibatis.apache.org by gb...@apache.org on 2008/08/04 20:43:44 UTC
svn commit: r682456 [1/7] - in /ibatis/trunk/cs/V3/docs: ./ dataAccessGuide/
dataAccessGuide/resources/ dataAccessGuide/src/ dataAccessGuide/src/en/
dataAccessGuide/src/en/images/ dataAccessGuide/styles/ dataMapperGuide/
dataMapperGuide/resources/ data...
Author: gbayon
Date: Mon Aug 4 11:43:42 2008
New Revision: 682456
URL: http://svn.apache.org/viewvc?rev=682456&view=rev
Log:
Add doc directory for V3
Added:
ibatis/trunk/cs/V3/docs/
ibatis/trunk/cs/V3/docs/dataAccessGuide/
ibatis/trunk/cs/V3/docs/dataAccessGuide/resources/
ibatis/trunk/cs/V3/docs/dataAccessGuide/resources/IBatisNet.vsd (with props)
ibatis/trunk/cs/V3/docs/dataAccessGuide/src/
ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/
ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/configuration.xml
ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/dao.xml
ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/example.xml
ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/handler.xml
ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/images/
ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/images/DAODesign.gif (with props)
ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/images/DAODiagram.gif (with props)
ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/images/ibatisnet.gif (with props)
ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/index.xml
ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/interface.xml
ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/introduction.xml
ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/programming.xml
ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/xsd-template.xml
ibatis/trunk/cs/V3/docs/dataAccessGuide/styles/
ibatis/trunk/cs/V3/docs/dataAccessGuide/styles/fopdf.xsl
ibatis/trunk/cs/V3/docs/dataAccessGuide/styles/html.css
ibatis/trunk/cs/V3/docs/dataAccessGuide/styles/html.xsl
ibatis/trunk/cs/V3/docs/dataMapperGuide/
ibatis/trunk/cs/V3/docs/dataMapperGuide/resources/
ibatis/trunk/cs/V3/docs/dataMapperGuide/resources/DataMapper.ppt (with props)
ibatis/trunk/cs/V3/docs/dataMapperGuide/src/
ibatis/trunk/cs/V3/docs/dataMapperGuide/src/en/
ibatis/trunk/cs/V3/docs/dataMapperGuide/src/en/architecture.xml
ibatis/trunk/cs/V3/docs/dataMapperGuide/src/en/dotnet.xml
ibatis/trunk/cs/V3/docs/dataMapperGuide/src/en/images/
ibatis/trunk/cs/V3/docs/dataMapperGuide/src/en/images/DevGuide-1.gif (with props)
ibatis/trunk/cs/V3/docs/dataMapperGuide/src/en/images/ibatisnet.gif (with props)
ibatis/trunk/cs/V3/docs/dataMapperGuide/src/en/images/intellisense.GIF (with props)
ibatis/trunk/cs/V3/docs/dataMapperGuide/src/en/images/new.gif (with props)
ibatis/trunk/cs/V3/docs/dataMapperGuide/src/en/index.xml
ibatis/trunk/cs/V3/docs/dataMapperGuide/src/en/introduction.xml
ibatis/trunk/cs/V3/docs/dataMapperGuide/src/en/working.xml
ibatis/trunk/cs/V3/docs/dataMapperGuide/src/en/xsd-config-template.xml
ibatis/trunk/cs/V3/docs/dataMapperGuide/src/en/xsd-sqlMap-template.xml
ibatis/trunk/cs/V3/docs/dataMapperGuide/styles/
ibatis/trunk/cs/V3/docs/dataMapperGuide/styles/fopdf.xsl
ibatis/trunk/cs/V3/docs/dataMapperGuide/styles/html.css
ibatis/trunk/cs/V3/docs/dataMapperGuide/styles/html.xsl
ibatis/trunk/cs/V3/docs/doc.build
ibatis/trunk/cs/V3/docs/docbook/
ibatis/trunk/cs/V3/docs/docbook/readme.txt
ibatis/trunk/cs/V3/docs/favicon.ico (with props)
ibatis/trunk/cs/V3/docs/fop/
ibatis/trunk/cs/V3/docs/fop/readme.txt
ibatis/trunk/cs/V3/docs/skin/
ibatis/trunk/cs/V3/docs/skin/breadcrumbs-optimized.js
ibatis/trunk/cs/V3/docs/skin/breadcrumbs.js
ibatis/trunk/cs/V3/docs/skin/css/
ibatis/trunk/cs/V3/docs/skin/images/
ibatis/trunk/cs/V3/docs/skin/images/chapter.gif (with props)
ibatis/trunk/cs/V3/docs/skin/images/chapter_open.gif (with props)
ibatis/trunk/cs/V3/docs/skin/images/current.gif (with props)
ibatis/trunk/cs/V3/docs/skin/images/doc.gif (with props)
ibatis/trunk/cs/V3/docs/skin/images/favicon.ico (with props)
ibatis/trunk/cs/V3/docs/skin/images/label.gif (with props)
ibatis/trunk/cs/V3/docs/skin/images/menu-left.gif (with props)
ibatis/trunk/cs/V3/docs/skin/images/menu-right.gif (with props)
ibatis/trunk/cs/V3/docs/skin/images/page.gif (with props)
ibatis/trunk/cs/V3/docs/skin/images/pdfdoc.gif (with props)
ibatis/trunk/cs/V3/docs/skin/images/printer.gif (with props)
ibatis/trunk/cs/V3/docs/skin/images/search-left.gif (with props)
ibatis/trunk/cs/V3/docs/skin/images/search-right.gif (with props)
ibatis/trunk/cs/V3/docs/skin/images/singlepage.gif (with props)
ibatis/trunk/cs/V3/docs/skin/images/spacer.gif (with props)
ibatis/trunk/cs/V3/docs/skin/images/tab-left.gif (with props)
ibatis/trunk/cs/V3/docs/skin/images/tab-right.gif (with props)
ibatis/trunk/cs/V3/docs/skin/images/tabSel-left.gif (with props)
ibatis/trunk/cs/V3/docs/skin/images/tabSel-right.gif (with props)
ibatis/trunk/cs/V3/docs/skin/images/valid-html401.png (with props)
ibatis/trunk/cs/V3/docs/skin/images/vcss.png (with props)
ibatis/trunk/cs/V3/docs/skin/images/xmldoc.gif (with props)
ibatis/trunk/cs/V3/docs/skin/page.css
ibatis/trunk/cs/V3/docs/skin/scripts/
ibatis/trunk/cs/V3/docs/tutorial/
ibatis/trunk/cs/V3/docs/tutorial/src/
ibatis/trunk/cs/V3/docs/tutorial/src/en/
ibatis/trunk/cs/V3/docs/tutorial/src/en/images/
ibatis/trunk/cs/V3/docs/tutorial/src/en/images/figure01.gif (with props)
ibatis/trunk/cs/V3/docs/tutorial/src/en/images/figure02.gif (with props)
ibatis/trunk/cs/V3/docs/tutorial/src/en/images/figure03.gif (with props)
ibatis/trunk/cs/V3/docs/tutorial/src/en/index.xml
ibatis/trunk/cs/V3/docs/tutorial/src/en/tutorial.xml
ibatis/trunk/cs/V3/docs/tutorial/styles/
ibatis/trunk/cs/V3/docs/tutorial/styles/fopdf.xsl
ibatis/trunk/cs/V3/docs/tutorial/styles/html.css
ibatis/trunk/cs/V3/docs/tutorial/styles/html.xsl
ibatis/trunk/cs/V3/docs/xsltproc/
ibatis/trunk/cs/V3/docs/xsltproc/readme.txt
Added: ibatis/trunk/cs/V3/docs/dataAccessGuide/resources/IBatisNet.vsd
URL: http://svn.apache.org/viewvc/ibatis/trunk/cs/V3/docs/dataAccessGuide/resources/IBatisNet.vsd?rev=682456&view=auto
==============================================================================
Binary file - no diff available.
Propchange: ibatis/trunk/cs/V3/docs/dataAccessGuide/resources/IBatisNet.vsd
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/configuration.xml
URL: http://svn.apache.org/viewvc/ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/configuration.xml?rev=682456&view=auto
==============================================================================
--- ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/configuration.xml (added)
+++ ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/configuration.xml Mon Aug 4 11:43:42 2008
@@ -0,0 +1,1275 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="configuration">
+ <title>Configuration</title>
+
+ <sect1>
+ <title>Installation</title>
+
+ <para>There are three steps to using the iBATIS Data Access Objects (DAO)
+ framework with your application for the first time. <orderedlist>
+ <listitem>
+ Setup the distribution
+ </listitem>
+
+ <listitem>
+ Add assembly references
+ </listitem>
+
+ <listitem>
+ Setup XML configuration documents
+ </listitem>
+ </orderedlist></para>
+
+ <sect2>
+ <title>Setup the Distribution</title>
+
+ <para>The official site for iBATIS for .NET is our Apache site
+ <http://ibatis.apache.org/>. The DataAccess framework is availabe
+ in 2 types of distributions: a binary distribution that includes the
+ required DataAccess assemblies and a source distribution that includes a
+ VSN solution. To download either of the distributions, follow the link
+ to the Downloads area on our web site, and select the either the binary
+ or source distribution for the iBATIS .NET DataAccess V1.6.1 or later
+ release (if you download the binary distribution, extract the files
+ using a utility like WinZip or the extractor built into newer versions
+ of Windows and skip ahead to the Add Assembly References
+ section).</para>
+
+ <para>The source distribution includes a VSN solution and a number of C#
+ projects. The distribution is in the form of a ZIP archive. You can
+ extract the distribution using a utility like WinZip or the extractor
+ built into newer versions of Windows. We suggest that you create an
+ <filename>ibatisnet</filename> folder in your VSN project directory and
+ extract the distribution there.</para>
+
+ <para>Under the distribution's <filename>source</filename> folder are
+ eight folders that make up the iBATIS.NET distribution, as shown in the
+ following table:</para>
+
+ <table>
+ <title>Folders found in the iBATIS.NET source distribution</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Folder name</entry>
+
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>External-Bin</entry>
+
+ <entry>Dependency assemblies provided for your
+ convenience.</entry>
+ </row>
+
+ <row>
+ <entry>IBatisNet.Common</entry>
+
+ <entry>Assembly of classes shared by DataAccess and
+ DataMapper</entry>
+ </row>
+
+ <row>
+ <entry>IBatisNet.Common.Test</entry>
+
+ <entry>Test project for IBatisNet.Common that can be used with
+ NUnit</entry>
+ </row>
+
+ <row>
+ <entry>IBatisNet.DataAccess</entry>
+
+ <entry>The Data Access Objects framework</entry>
+ </row>
+
+ <row>
+ <entry>IBatisNet.DataAccess.Extensions</entry>
+
+ <entry>Contains a C# project for extensions to the DataAccess
+ framework such as NHibernate support</entry>
+ </row>
+
+ <row>
+ <entry>IBatisNet.DataAccess.Test</entry>
+
+ <entry>Test project for the DataAccess framework that can be
+ used with NUnit</entry>
+ </row>
+
+ <row>
+ <entry>iBatisNet.DataMapper</entry>
+
+ <entry>The DataMapper framework (see seperate DataMapper
+ Guide)</entry>
+ </row>
+
+ <row>
+ <entry>IBatisNet.DataMapper.Test</entry>
+
+ <entry>Test project for the DataMapper that can be used with
+ NUnit</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>You can load the <filename>IBatisNet.sln</filename> solution file
+ into VSN and build the solution to generate the needed assemblies. There
+ are seven projects in the solution, and all should succeed. The
+ assemblies we need will be created under
+ <filename>\source\IBatisNet.DataAccess\bin\Debug</filename>. The created
+ assemblies are :
+ <orderedlist>
+ <listitem>
+ <filename>IBatisNet.Common.dll</filename>
+ </listitem>
+
+ <listitem>
+ <filename>iBatisNet.DataAccess.dll</filename>
+ </listitem>
+ </orderedlist>
+
+ The core DataAccess
+ framework has external dependencies on
+ <orderedlist>
+ <listitem>
+ <filename>Castle.DynamicProxy.dll</filename> (creating proxies)
+ </listitem>
+
+ </orderedlist>
+ The dependency is found in the <filename>External-Bin</filename> folder and can also
+ be found in the <filename>bin\Debug</filename> folder after building the
+ solution. In addition, the framework's
+ <filename>IBatisNet.DataAccess.Extensions</filename> and
+ <filename>IBatisNet.DataAccess.Test</filename> projects have
+ dependencies on NHibernate.</para>
+
+ <tip>
+ <para>If you will not be using NHibernate and have a problem building
+ the solution due to that dependency, simply remove the
+ IBatisNet.DataAccess.Extensions and IBatisNet.DataAccess.Test projects
+ from the solution before building.</para>
+ </tip>
+ </sect2>
+
+ <sect2>
+ <title>Add Assembly References</title>
+
+ <para>Switching to your own solution, open the project that will be
+ using the iBATIS.NET DAO Framework. Depending on how your organize your
+ solutions, this might not be the project for your Windows or Web
+ application. It may be a library project that your application project
+ references. You need to add two references to your project: <orderedlist>
+ <listitem>
+ IBatisNet.DataAccess.dll
+ </listitem>
+
+ <listitem>
+ <para>IBatisNet.Common.dll</para>
+ </listitem>
+ </orderedlist></para>
+
+ <para>Additionally, the DAO framework has the following external
+ dependencies:<table>
+ <title>Dependencies</title>
+
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Name</entry>
+
+ <entry>Description</entry>
+
+ <entry>Assembly DLLs</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>Castle dynamic proxy 1.1.5.0</entry>
+
+ <entry>Dynamic proxy generator</entry>
+
+ <entry>Castle.DynamicProxy.dll</entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table></para>
+ </sect2>
+
+ <sect2>
+ <title>Setup XML configuration documents</title>
+
+ <para>You will need to add two or more XML file items to your Windows or
+ Web application project (and Test project if you have one). These files
+ are:</para>
+
+ <para><itemizedlist>
+ <listitem>
+ dao.config - The Data Access configuration file that is used to specify your DAOs, providers.config file location, and data source information.
+ </listitem>
+
+ <listitem>
+ providers.config - A file used by the framework to look up the definition of your selected database provider.
+ </listitem>
+
+ <listitem>
+ SqlMap.config and Data Map definition XML files - Required when using the iBATIS DataAccess framework in conjunction with the iBATIS DataMapper framework
+ </listitem>
+ </itemizedlist></para>
+
+ <para>The <filename>dao.config</filename> and
+ <filename>providers.config</filename> files must be placed in a location
+ where the framework can find them at runtime. Depending on the type of
+ project you have, the default expected location of these 2 files will be
+ different, as shown in Table 3.3. However, your project is not limited
+ to using just these locations. The DataAccess framework provides other
+ options for placing these files in locations that are more suitable for
+ your project instead of using the default locations. These options are
+ covered later in this guide.</para>
+
+ <table>
+ <title>Where to place the dao.config file</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>Windows, Library, or Test projects (using NUnit or
+ equivalent)</entry>
+
+ <entry>Place with the assembly (.dll) files and the
+ <filename>app.config</filename> file</entry>
+ </row>
+
+ <row>
+ <entry>Web projects</entry>
+
+ <entry>Place in the project root, with the
+ <filename>web.config</filename> file</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect2>
+
+<sect2>
+ <title>Visual Studio.NET Integration</title>
+
+ <para>The configuration file (dao.config) is associated to a schema. The benefits of associating
+ an XML document with a schema are to validate the document (which is
+ done at runtime) and to use editing features such as
+ IntelliSense/content completion assistance.</para>
+
+ <para>To allow association of the schemas in VS.NET XML editor to your
+ configuration file, you should add the schema file
+ (<filename>DaoConfig.xsd</filename> to either your VS.NET project or in
+ your VS.NET installation directory. The VS.NET directory will be
+ either</para>
+
+ <para><filename>C:\Program Files\Microsoft Visual Studio 8\Xml\Schemas for VS.NET 2005</filename></para>
+
+ <para>or</para>
+
+ <para><filename>C:\Program Files\Microsoft Visual Studio .NET
+ 2003\Common7\Packages\schemas\xml for VS.NET 2003</filename></para>
+
+ <para>or</para>
+
+ <para><filename>C:\Program Files\Microsoft Visual Studio
+ .NET\Common7\Packages\schemas\xml for VS.NET 2002</filename></para>
+
+ <para>depending on your version of VS.NET. It is typically easier to
+ place the file in the well known location under the VS.NET installation
+ directory than to copy the XSD file for each project you create.</para>
+
+ <para>Once you have registered the schema with VS.NET you will be enough
+ to get IntelliSense and validation of the configuration file from within
+ VS.NET.</para>
+
+ <figure>
+ <title>IntelliSense example</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/intellisense.gif"
+ format="GIF" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Logging Activity</title>
+
+ <para>The iBATIS DataAccess framework records its interaction with the
+ database through an internal logging mechanism patterned after Apache
+ Log4Net. The internal logging mechanism can use one of the three built-in
+ loggers (NoOpLogger, ConsoleOutLogger, TraceLogger) or external logging
+ packages such as Apache Log4Net. In order for iBATIS to generate log
+ messages, the application's config file (App.Config or Web.Config) must
+ contain an appropriate configSection node:</para>
+
+ <example>
+ <title>iBATIS Configuration Section Handler for logging</title>
+
+ <programlisting><configSections>
+ <sectionGroup name="iBATIS">
+ <section name="logging" type="IBatisNet.Common.Logging.ConfigurationSectionHandler, IBatisNet.Common" />
+ </sectionGroup>
+</configSections></programlisting>
+ </example>
+
+ <para>The application's config file must declare one logger
+ implementation. See the examples below on how to configure one of the
+ three built-in loggers.</para>
+
+ <para><programlisting><iBATIS>
+ <logging>
+ <logFactoryAdapter type="IBatisNet.Common.Logging.Impl.ConsoleOutLoggerFA, IBatisNet.Common">
+ <arg key="showLogName" value="true" />
+ <arg key="showDataTime" value="true" />
+ <arg key="level" value="ALL" />
+ <arg key="dateTimeFormat" value="yyyy/MM/dd HH:mm:ss:SSS" />
+ </logFactoryAdapter>
+ </logging>
+</iBATIS>
+</programlisting><programlisting><iBATIS>
+ <logging>
+ <logFactoryAdapter type="IBatisNet.Common.Logging.Impl.NoOpLoggerFA, IBatisNet.Common" />
+ </logging>
+</iBATIS>
+</programlisting><programlisting><iBATIS>
+ <logging>
+ <logFactoryAdapter type="IBatisNet.Common.Logging.Impl.TraceLoggerFA, IBatisNet.Common" />
+ </logging>
+</iBATIS></programlisting></para>
+
+ <para>To configure iBATIS to use another logger implementation, simple
+ specify the appropriate logFactoryAdapter type. To use Apache Log4Net with
+ the iBATIS framework, use the following configuration
+ setting:</para>
+
+ <para><programlisting><iBATIS>
+ <logging>
+ <logFactoryAdapter type="IBatisNet.Common.Logging.Impl.Log4NetLoggerFA, IBatisNet.Common.Logging.Log4Net">
+ <arg key="configType" value="inline" />
+ </logFactoryAdapter>
+ </logging>
+</iBATIS></programlisting></para>
+
+ <para><programlisting><iBATIS>
+ <logging>
+ <logFactoryAdapter type="IBatisNet.Common.Logging.Impl.Log4NetLoggerFA, IBatisNet.Common.Logging.Log4Net">
+ <arg key="configType" value="file" />
+ <arg key="configFile" value="log4Net.config" />
+ </logFactoryAdapter>
+ </logging>
+</iBATIS></programlisting></para>
+
+ <para>The Log4NetLoggerFA supports the following values for the
+ configTypes argument:<table>
+ <title>Valid configType values</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>configType</entry>
+
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>inline</entry>
+
+ <entry>log4net node will use the log4net node in the
+ App.Config/Web.Config file when it is configured</entry>
+ </row>
+
+ <row>
+ <entry>file</entry>
+
+ <entry>(also requires configFile argument) - log4net will use an
+ external file for its configuration</entry>
+ </row>
+
+ <row>
+ <entry>file-watch</entry>
+
+ <entry> (also requires configFile argument) - log4net will use
+ an external file for its configuration and will re-configure
+ itself if this file changes</entry>
+ </row>
+
+ <row>
+ <entry>external</entry>
+
+ <entry>iBATIS will not attempt to configure log4net.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></para>
+
+ <sect2>
+ <title>Sample Logging Configurations</title>
+
+ <para>The simplest logging configuration is to output log messages to
+ Console.Out:</para>
+
+ <para><programlisting><configuration>
+ <configSections>
+ <sectionGroup name="iBATIS">
+ <section name="logging" type="IBatisNet.Common.Logging.ConfigurationSectionHandler, IBatisNet.Common" />
+ </sectionGroup>
+ </configSections>
+ <iBATIS>
+ <logging>
+ <logFactoryAdapter type="IBatisNet.Common.Logging.Impl.ConsoleLoggerFA, IBatisNet.Common.Logging" />
+ </logging>
+ </iBATIS>
+</configuration></programlisting></para>
+
+ <para>A common logging configuration is to use Apache Log4Net. To use
+ Log4Net with your own application, you need to provide your own Log4Net
+ configuration. You can do this by adding a configuration file for your
+ assembly that includes a <log4Net> element. The configuration file
+ is named after your assembly but adds a <filename>.config</filename>
+ extension, and is stored in the same folder as your assembly. This is an
+ example of a basic Log4Net configuration block
+ (IBatisNet.DataMapper.Test.dll.Config) that also creates a log4net.txt
+ which contains debug information from log4net. If log4net is not
+ producing output, check the log4net.txt file.</para>
+
+ <para><programlisting><configuration>
+ <configSections>
+ <sectionGroup name="iBATIS">
+ <section name="logging" type="IBatisNet.Common.Logging.ConfigurationSectionHandler, IBatisNet.Common" />
+ </sectionGroup>
+ <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler, log4net" />
+ </configSections>
+ <appSettings>
+ <add key="log4net.Internal.Debug" value="true"/>
+ </appSettings>
+ <system.diagnostics>
+ <trace autoflush="true">
+ <listeners>
+ <add name="textWriterTraceListener"
+ type="System.Diagnostics.TextWriterTraceListener"
+ initializeData="C:\\inetpub\\wwwroot\\log4net.txt" />
+ </listeners>
+ </trace>
+ </system.diagnostics>
+ <iBATIS>
+ <logging>
+ <logFactoryAdapter type="IBatisNet.Common.Logging.Impl.Log4NetLoggerFA, IBatisNet.Common.Logging.Log4Net">
+ <arg key="configType" value="inline" />
+ </logFactoryAdapter>
+ </logging>
+ </iBATIS>
+ <log4net>
+ <appender name="FileAppender" type="log4net.Appender.FileAppender">
+ <file value="log.txt" />
+ <appendToFile value="true" />
+ <layout type="log4net.Layout.SimpleLayout" />
+ </appender>
+ <root>
+ <level value="ALL" />
+ <appender-ref ref="FileAppender" />
+ </root>
+ </log4net>
+</configuration></programlisting></para>
+ </sect2>
+ </sect1>
+ <sect1>
+ <title>The Configuration File (dao.config)</title>
+
+ <para>The DaoManager class is responsible for the configuration of the DAO
+ Framework by parsing a special configuration XML file. The configuration
+ XML file specifies the following items:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>DAO contexts</para>
+ </listitem>
+
+ <listitem>
+ <para>properties for configuration</para>
+ </listitem>
+
+ <listitem>
+ <para>data source information</para>
+ </listitem>
+
+ <listitem>
+ <para>DAO implementations for each associated DAO interface</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>A DAO context is a grouping of related configuration information and
+ DAO implementations. Usually a context is associated with a single data
+ source such as a relational database or a flat file. By configuring
+ multiple contexts, you can easily centralize the data access configuration
+ for multiple databases. The structure of the DAO configuration file
+ (commonly called <filename>dao.config</filename> but not required) is as
+ follows. Values that you will likely change for your application are
+ highlighted.</para>
+
+ <example>
+ Example dao.config file
+
+ <programlisting><?xml version="1.0" encoding="utf-8"?>
+<daoConfig xmlns="http://ibatis.apache.org/dataAccess"
+xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+
+<providers resource="providers.config">
+
+<emphasis role="comment"><!-- Example ADO.NET DAO Configuration --></emphasis>
+<context id="<emphasis role="blue">SimpleDao</emphasis>" default="<emphasis
+ role="blue">true</emphasis>">
+ <properties resource="<emphasis role="blue">properties.config</emphasis>"/>
+
+ <database>
+ <!-- Optional ( default ) -->
+ <provider name="<emphasis role="blue">sqlServer1.1</emphasis>"/>
+ <dataSource name="<emphasis role="blue">iBatisNet</emphasis>"
+ connectionString="<emphasis role="blue">data source=${datasource};database=${database};
+ user id=${userid};password=${password};</emphasis>"/>
+ </database>
+
+ <daoFactory>
+ <dao interface="<emphasis role="blue">IBatisNet.Test.Dao.Interfaces.IAccountDao, IBatisNet.Test</emphasis>"
+ implementation="<emphasis role="blue">IBatisNet.Test.Dao.Implementations.Ado.AccountDao, IBatisNet.Test</emphasis>"/>
+ </daoFactory>
+</context>
+
+<emphasis role="comment"><!-- Example SQL Maps DAO Configuration --></emphasis>
+<context id="<emphasis role="blue">SqlMapDao</emphasis>">
+ <properties resource="<emphasis role="blue">properties2.config</emphasis>"/>
+
+ <database>
+ <provider name="<emphasis role="blue">OleDb1.1</emphasis>"/>
+ <dataSource name="<emphasis role="blue">iBatisNet</emphasis>"
+ connectionString="<emphasis role="blue">Provider=SQLOLEDB;Server=${database};database=IBatisNet;
+ user id=${userid};password=${password};</emphasis>"/>
+ </database>
+
+ <daoSessionHandler id="SqlMap">
+ <property name="resource" value="<emphasis role="blue">SqlMap.config</emphasis>"/>
+<emphasis role="comment"> <!--
+ url and embedded options are also available
+ <property name="url" value="C:\iBATIS\IBatisNet.DataAccess.Test\bin\Debug\SqlMap.config"/>
+ <property name="embedded" value="bin.Debug.SqlMap.config, IBatisNet.DataAccess.Test"/>
+ -->
+</emphasis> </daoSessionHandler>
+
+ <daoFactory>
+ <dao interface="<emphasis role="blue">IBatisNet.Test.Dao.Interfaces.IAccountDao, IBatisNet.Test</emphasis>"
+ implementation="<emphasis role="blue">IBatisNet.Test.Dao.Implementations.DataMapper.AccountDao, IBatisNet.Test</emphasis>"/>
+ </daoFactory>
+</context>
+
+</daoConfig> </programlisting>
+
+
+ </example>
+
+ <para>In the example above, what we end up with is two DAO contexts. DAOs
+ are automatically aware of which context they belong to and therefore
+ which session handler to use. Again, there can be any number of DAO
+ contexts specified in a <filename>dao.config</filename> file, and
+ generally, a context will refer to a single specific data source.</para>
+
+ <para>In order to manage multiple configurations for different
+ environments (DEVT, Q/A, PROD), you can also make use of the optional
+ <literal><properties></literal> element as shown above. This allows
+ you to use placeholders in the place of literal value elements. If you
+ have a "properties" file with the following values:</para>
+
+ <example>
+ <title>Example properties file</title>
+
+ <programlisting><add key="<emphasis role="blue">userid</emphasis>" value="<emphasis
+ role="blue">IBatisNet</emphasis>" />
+<add key="<emphasis role="blue">password</emphasis>" value="<emphasis
+ role="blue">test</emphasis>" />
+<add key="<emphasis role="blue">database</emphasis>" value="<emphasis
+ role="blue">iBatisNet</emphasis>" />
+<add key="<emphasis role="blue">datasource</emphasis>" value="<emphasis
+ role="blue">(local)\NetSDK</emphasis>" /></programlisting>
+ </example>
+
+ <para>You can use placeholders defined in that properties file instead of
+ explicit values in the <filename>dao.config</filename> file. For
+ example:</para>
+
+ <programlisting><dataSource name="<emphasis role="blue">iBatisNet</emphasis>"
+ connectionString="<emphasis role="blue">data source=${datasource};database=${database};
+ user id=${userid};password=${password};</emphasis>"/></programlisting>
+
+ <para>This allows for easier management of different environment
+ configurations. Only one properties resource file may be specified per
+ context.</para>
+
+ <para>Continuing with the example above, the provider and the datasource
+ values are given within the <literal>database</literal> element. Following
+ that, an optional <literal>daoSessionHandler</literal> may be specified.
+ If none is specified, the default iBATIS.NET DAO SessionHandler called
+ <classname>SimpleDaoSessionHandler</classname> will be used. In the
+ example, the second context identifies the SessionHandler as
+ <literal>SqlMap</literal>, meaning that the DAO implementations will be
+ using iBATIS.NET Data Mapper SqlMaps instead of basic ADO calls.</para>
+
+ <para>Next in the context under <literal>daoFactory</literal>, is the
+ specification of all DAO interfaces and their associated implementations.
+ These mappings link a generic DAO interface to a concrete (specific)
+ implementation. This is where we can see the pluggable nature of Data
+ Access Objects. By simply replacing the implementation class for a given
+ DAO mapping, the persistence approach taken can be completely changed
+ (e.g. from ADO to iBATIS DataMapper SqlMaps to NHibernate).</para>
+ </sect1>
+
+ <sect1>
+ <title>Configuration Elements</title>
+
+ <para>The sections below describe the elements of the Data Access
+ configuration document for .NET. The <filename>dao.config</filename> file
+ can be validated by the <filename>DaoConfig.xsd</filename> schema provided
+ with the distribution.</para>
+
+ <sect2>
+
+
+ <title>type Attributes</title>
+
+ In general, when specifying a type attribute within a configuration file, a type attribute value must be a fully qualified type name following the format:
+
+ <programlisting> type="[namespace.class], [assembly name],
+ Version=[version], Culture=[culture],
+ PublicKeyToken=[public token]"</programlisting>
+
+ For example:
+
+ <programlisting> type="MyProject.Domain.LineItem, MyProject.Domain,
+ Version=1.2.3300.0, Culture=neutral,
+ PublicKeyToken=b03f455f11d50a3a" </programlisting>
+
+ The strongly typed name is desired, however, it is also legitimate to use the shorter style assembly type name:
+
+ <programlisting> type="MyProject.Domain.LineItem, MyProject.Domain"
+</programlisting>
+
+
+ </sect2>
+
+ <sect2>
+ <title>The <providers> Element</title>
+
+ <para>Under ADO.NET, a database system is accessed through a provider. A
+ database system can use a custom provider or a generic ODBC provider.
+ iBATIS.NET uses a pluggable approach to installing providers. Each
+ provider is represented by an XML descriptor element. The list of
+ providers you might want to use can be kept in a separate XML descriptor
+ file. The iBATIS.NET distribution includes the standard
+ <filename>providers.config</filename> file with a set of thirteen
+ prewritten provider elements:</para>
+
+ <para><itemizedlist>
+ <listitem>
+ sqlServer1.0 - Microsoft SQL Server 7.0/2000 provider available with .NET Framework 1.0
+ </listitem>
+
+ <listitem>
+ sqlServer1.1 -Microsoft SQL Server 7.0/2000 provider available with .NET Framework 1.1
+ </listitem>
+
+ <listitem>
+ OleDb1.1 - OleDb provider available with .NET Framework 1.1
+ </listitem>
+
+ <listitem>
+ Odbc1.1 - Odbc provider available with .NET Framework 1.1
+ </listitem>
+
+ <listitem>
+ oracle9.2 - Oracle provider V9.2.0.401
+ </listitem>
+
+ <listitem>
+ oracle10.1 - Oracle provider V10.1.0.301
+ </listitem>
+
+ <listitem>
+ oracleClient1.0 - MS Oracle provider V1.0.5 available with .NET Framework 1.1
+ </listitem>
+
+ <listitem>
+ ByteFx - ByteFx MySQL provider V0.7.6.15073
+ </listitem>
+
+ <listitem>
+ MySql - MySQL provider V1.0.4.20163
+ </listitem>
+
+ <listitem>
+ SQLite3 - SQLite.NET provider V0.21.1869.3794
+ </listitem>
+
+ <listitem>
+ Firebird1.7 - Firebird SQL .NET provider V1.7.0.33200
+ </listitem>
+
+ <listitem>
+ PostgreSql0.7 - Npgsql provider V0.7.0.0
+ </listitem>
+
+ <listitem>
+ iDb2.10 - IBM DB2 iSeries provider V10.0.0.0
+ </listitem>
+ </itemizedlist></para>
+
+ <para>The <filename>providers.config</filename> file can be found under
+ <filename>\source\IBatisNet.DataAccess.Test\bin\Debug</filename> in the
+ iBATIS.NET source distribution or in the root folder of the .NET
+ DataAccess binary distribution.</para>
+
+ <para>A provider may require libraries that you do not have installed,.
+ Therefore, the provider element has an "enabled" attribute that allows
+ you to disable unused providers. One provider can also be marked as the
+ "default" and will be used if another is not specified by your
+ configuration.</para>
+
+ <para>The standard <filename>providers.config</filename> file has
+ sqlServer1.1 set as the default and the sqlServer1.0 provider disabled.
+ Aside from sqlServer1.1, OleDb1.1, and Odbc1.1, all other providers are
+ disabled by default. Remember to set the "enabled" attribute to "true"
+ for the provider that you will be using.</para>
+
+ <important>
+ <para>ByteFx is the recommended provider if you are using MySQL. You
+ may download ByteFx from the MySQLNet SourceForge site
+ (http://sf.net/projects/mysqlnet/). If the ByteFx license is
+ acceptable to you, you may install it as a reference within your
+ application and enable the ByteFx provider.</para>
+ </important>
+
+ <para><tip>
+ <para>Be sure to review the <filename>providers.config</filename>
+ file and confirm that the provider you intend to use is enabled!
+ (Set the enabled attribute to true.)</para>
+ </tip></para>
+
+ <table>
+ <title>Expected default locations of the providers.config file</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>Windows, Library, or Test projects (using NUnit or
+ equivalent)</entry>
+
+ <entry>With the assembly (.dll) files with the
+ <filename>app.config</filename> file</entry>
+ </row>
+
+ <row>
+ <entry>Web projects</entry>
+
+ <entry>In the project base directory, with the
+ <filename>web.config</filename> file</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>To use the file, you can copy it into your project at the expected
+ default location, give a path to the file relative to the project root
+ directory, specify a url (absolute path) to its location, or make it an
+ embedded resource of your project. If you copy the file into the
+ expected default location, the <providers> element is not required
+ in your dao.config file.</para>
+
+ <sect3>
+ <title><providers> attributes</title>
+
+ <para>The <providers> element can accept one of the following
+ attributes to specify the location of the providers.config
+ file.</para>
+
+ <table>
+ <title>Attributes of the <providers> element</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Attribute</entry>
+
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><emphasis>resource</emphasis></entry>
+
+ <entry>Specify the file to be loaded from a relative path from
+ the project root directory. Since the root directory is
+ different depending on the project type, it is best to use a
+ properties variable to indicate the relative path. Having that
+ variable defined in a properties file makes it easy to change
+ the path to all your DataAccess configuration resources in one
+ location.<programlisting>resource="${root}providers.config"</programlisting></entry>
+ </row>
+
+ <row>
+ <entry><emphasis>url</emphasis></entry>
+
+ <entry>Specify the providers.config to be loaded through an
+ absolute path.<programlisting>url="<filename>c:\Web\MyApp\</filename>Resources\providers.config"
+or
+url="file://<filename>c:\</filename><filename><filename>Web\MyApp\</filename>Resources\</filename>providers.config"</programlisting></entry>
+ </row>
+
+ <row>
+ <entry><emphasis>embedded</emphasis></entry>
+
+ <entry>Specify the providers.config file to be loaded as an
+ embedded resource in an assembly. Syntax for the embedded
+ attribute is '<emphasis>[extendednamespace.]filename, the name
+ of the assembly which contains the embedded
+ resource</emphasis>'<programlisting>embedded="Resources.providers.config, MyApp.Data"</programlisting></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>The <context> Element</title>
+
+ <para>A DAO context is a grouping of related configuration information
+ and DAO implementations for a specific database and provider.</para>
+
+ <table>
+ <title>Attributes of the <context> element</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Attribute</entry>
+
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><emphasis>id</emphasis></entry>
+
+ <entry>Context id</entry>
+ </row>
+
+ <row>
+ <entry><emphasis>default</emphasis></entry>
+
+ <entry>Global setting to indicate if this is the default
+ context</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <sect3>
+ <title>The <properties> Element</title>
+
+ <para>Sometimes the values we use in an XML configuration file occur
+ in more than one element. Often, there are values that change when we
+ move the application from one server to another. To help you manage
+ configuration values, you can specify a standard properties file (with
+ name=value entries) as part of a Data Access configuration. Each named
+ value in the properties file becomes a <emphasis>shell</emphasis>
+ variable that can be used throughout the Data Access
+ configuration.</para>
+
+ <para>Properties are handy during building, testing, and deployment.
+ Additionally, properties make it easy to reconfigure your application
+ for multiple environments or to use automated tools for configuration
+ such as NAnt.</para>
+
+ <para>The <properties> element can only accept one of the
+ following attributes to specify the location of the properties
+ file.</para>
+
+ <table>
+ <title>Attributes of the <properties> element</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Attribute</entry>
+
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><emphasis>resource</emphasis></entry>
+
+ <entry>Specify the properties file name files to be loaded
+ from the root directory of the application (relative
+ path)<programlisting>resource="properties.config"</programlisting></entry>
+ </row>
+
+ <row>
+ <entry><emphasis>url</emphasis></entry>
+
+ <entry>Specify the properties file to be loaded through an
+ absolute path<programlisting>url="<filename>c:\Web\MyApp\Resources\properties</filename>.config"
+or
+url="file://<filename>c:\Web\MyApp\Resources\properties</filename>.config"</programlisting></entry>
+ </row>
+
+ <row>
+ <entry><emphasis>embedded</emphasis></entry>
+
+ <entry>Specify the properties file to be loaded as an embedded
+ resource in an assembly. Syntax for the embedded attribute is
+ '<emphasis>[extendednamespace.]filename, the name of the
+ assembly which contains the embedded
+ resource</emphasis>'<programlisting>embedded="Resources.properties.config, MyApp.Data"</programlisting></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <sect4>
+ <title><property> element and attributes</title>
+
+ <para>You can also specify more than one properties file or add
+ property keys and values directly into your
+ <filename>dao.config</filename> file by using <property>
+ elements. For example:</para>
+
+ <informalexample>
+ <programlisting><properties>
+ <property resource="myProperties.config"/>
+ <property resource="anotherProperties.config"/>
+ <property key="host" value="ibatis.com" />
+</properties></programlisting>
+ </informalexample>
+
+ <table>
+ <title>Attributes of the <property> element</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Attribute</entry>
+
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><emphasis>resource</emphasis></entry>
+
+ <entry>Specify the properties file to be loaded from the
+ root directory of the application<programlisting>resource="properties.config"</programlisting></entry>
+ </row>
+
+ <row>
+ <entry><emphasis>url</emphasis></entry>
+
+ <entry>Specify the properties file to be loaded through an
+ absolute path.<programlisting>url="<filename>c:\Web\MyApp\Resources\properties</filename>.config"
+or
+url="file://<filename>c:\Web\MyApp\Resources\properties</filename>.config"</programlisting></entry>
+ </row>
+
+ <row>
+ <entry><emphasis>embedded</emphasis></entry>
+
+ <entry>Specify the properties file to be loaded as an
+ embedded resource in an assembly. Syntax for the embedded
+ attribute is '<emphasis>[extendednamespace.]filename, the
+ name of the assembly which contains the embedded
+ resource</emphasis>'<programlisting>embedded="Resources.properties.config, MyApp.Data"</programlisting></entry>
+ </row>
+
+ <row>
+ <entry><emphasis>key</emphasis></entry>
+
+ <entry>Defines a property key (variable)
+ name<programlisting>key="username"</programlisting></entry>
+ </row>
+
+ <row>
+ <entry><emphasis>value</emphasis></entry>
+
+ <entry>Defines a value that will be used by the framework in
+ place of the the specified property
+ key/variable<programlisting>value="mydbuser"</programlisting></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect4>
+ </sect3>
+
+ <sect3>
+ <title>The <database> Element</title>
+
+ <para>The <database> element encloses elements that configure
+ the database system for use by the framework. These are the
+ <provider> and <datasource> elements.</para>
+
+ <sect4>
+ <title>The <provider> Element</title>
+
+ <para>The <provider> element specifies a database provider
+ from the <filename>providers.config</filename> file.</para>
+
+ <para>If the default provider is being used, the <provider>
+ element is optional. Or, if several providers are available, one may
+ be selected using the provider element without modifying the
+ <filename>providers.config</filename> file. <programlisting><provider name="OleDb1.1" /></programlisting></para>
+
+ <table>
+ <title>Attributes of the <provider> element</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Attribute</entry>
+
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><emphasis>name</emphasis></entry>
+
+ <entry>Name used to uniquely identify the provider</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect4>
+
+ <sect4>
+ <title>The <dataSource> Element</title>
+
+ <para>The <datasource> element specifies the connection string
+ for a specific database and provider.</para>
+
+ <table>
+ <title>Attributes of the <dataSource> element</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Attribute</entry>
+
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><emphasis>name</emphasis></entry>
+
+ <entry>Name used to identify the data source</entry>
+ </row>
+
+ <row>
+ <entry><emphasis>connectionString</emphasis></entry>
+
+ <entry>The connection string to the database</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect4>
+ </sect3>
+
+ <sect3>
+ <title>The <daoSessionHandler> Element</title>
+
+ <para>The <daoSessionHandler> element specifies the component
+ that manages transaction and connections for a session.</para>
+
+ <table>
+ <title>Attributes of the <daoSessionHandler> element</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Attribute</entry>
+
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><emphasis>id</emphasis></entry>
+
+ <entry>Id used to uniquely identify the handler</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <sect4>
+ <title>The <property> Element</title>
+
+ <para>Some <daoSessionHandler> implementations such as iBATIS
+ DataMapper SqlMaps and NHibernate need additional information for
+ configuration. The <property> element is used to specify this
+ information.</para>
+
+ <para>For iBATIS DataMapper SqlMaps, the method for locating and
+ loading the <filename>SqlMap.config</filename> file is used in the
+ "name" attribute. Depending on the chosen method, the corresponding
+ filepath or fully-qualified resource and assembly name is used for
+ the "value" attribute.</para>
+
+ <table>
+ <title>Attributes of the <property> element for use with
+ iBATIS DataMapper SqlMaps</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Attribute</entry>
+
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><emphasis>name</emphasis></entry>
+
+ <entry>Indicates the method used to locate and load the
+ <filename>SqlMap.config</filename> file. The available
+ options are "resource", "url", and "embedded" (as previously
+ described for loading the providers and properties
+ configuration files).<programlisting>name="resource"</programlisting></entry>
+ </row>
+
+ <row>
+ <entry><emphasis>value</emphasis></entry>
+
+ <entry>Used to specify the filename, fullpath, or fully
+ qualified resource and assembly name for the
+ <filename>SqlMap.config</filename> file.<programlisting>value="MySqlMap.config"</programlisting></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>For NHibernate, the "name" and "value" attributes are used to
+ specify various NHibernate configuration details such as
+ "hibernate.dialect", "hibernate.connection.provider", and
+ "mapping".</para>
+
+ <table>
+ <title>Attributes of the <property> element for use with
+ NHibernate</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Attribute</entry>
+
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><emphasis>name</emphasis></entry>
+
+ <entry>The name of the property to configure.
+ Example:<programlisting>name="hibernate.dialect"</programlisting></entry>
+ </row>
+
+ <row>
+ <entry><emphasis>value</emphasis></entry>
+
+ <entry>The value of the property configuration.
+ Example:<programlisting>value="NHibernate.Dialect.MsSql2000Dialect"</programlisting></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect4>
+ </sect3>
+
+ <sect3>
+ <title>The <daoFactory> Element</title>
+
+ <para>The <daoFactory> element is a grouping of Dao interfaces
+ and implementations.</para>
+
+ <sect4>
+ <title>The <dao> Element</title>
+
+ <para>The <dao> element specifies a Dao interface and one
+ implementation of that interface.</para>
+
+ <table>
+ <title>Attributes of the <dao> element</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Attribute</entry>
+
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><emphasis>interface</emphasis></entry>
+
+ <entry>The interface that the Dao must implement. Structure
+ value must be : namespace-qualified name of the class,
+ followed by a comma, followed by (at a bare minimum) the
+ name of the assembly that contains the class. Example:
+ <programlisting>interface=
+"IBatisNet.Test.Dao.Interfaces.IAccountDao,
+IBatisNet.Test"</programlisting></entry>
+ </row>
+
+ <row>
+ <entry><emphasis>implementation</emphasis></entry>
+
+ <entry>An implementation of the Dao interface. Structure
+ value must be : namespace-qualified name of the class,
+ followed by a comma, followed by (at a bare minimum) the
+ name of the assembly that contains the class. Example:
+ <programlisting>implementation=
+"IBatisNet.Test.Dao.Implementations.Ado.AccountDao,
+IBatisNet.Test"</programlisting></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect4>
+ </sect3>
+ </sect2>
+ </sect1>
+</chapter>
\ No newline at end of file
Added: ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/dao.xml
URL: http://svn.apache.org/viewvc/ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/dao.xml?rev=682456&view=auto
==============================================================================
--- ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/dao.xml (added)
+++ ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/dao.xml Mon Aug 4 11:43:42 2008
@@ -0,0 +1,151 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="dao">
+ <title>Data Access Objects</title>
+
+ <sect1>
+ <title>Data Access Objects</title>
+
+ <para>The iBATIS.NET Data Access Objects API can be used to help hide
+ persistence layer implementation details from the rest of your application
+ by allowing dynamic and pluggable DAO components to be easily swapped in
+ and out. For example, you could have two implementations of a particular
+ DAO, one that uses the iBATIS.NET DataMapper framework and another that
+ uses the NHibernate framework, to persist objects to the database. Another
+ example would be a DAO that provides caching services for another DAO.
+ Depending on the situation (e.g. limited database performance vs. limited
+ memory), either the cache DAO could be plugged in or the standard
+ un-cached DAO could be used. These examples show the convenience, and more
+ importantly, the safety that the DAO pattern provides. The DAO pattern
+ protects your application from possibly being tied to a particular
+ persistence approach. In the event that your current solution becomes
+ unsuitable (or even unavailable), you can simply create new DAO
+ implementations to support a new solution without having to modify any
+ code in the other layers of your application.</para>
+
+ <note>
+ <para>The iBATIS.NET DAO Framework and DataMapper Framework are
+ completely separate and are not dependent on each other in any way.
+ Please feel free to use either one separately, or both together.</para>
+ </note>
+ </sect1>
+
+ <sect1>
+ <title>The Components of the Data Access Objects API</title>
+
+ <para>There are a number of classes that make up the IBatisNet.DataAccess
+ API. Each has a very specific and important role. The following table
+ lists the classes and a brief description. The next sections will provide
+ more detail on how to use these classes.</para>
+
+ <table>
+ <title>IBatisNet.DataAccess API Classes</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Class/Interface (Patterns)</entry>
+
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+
+ <row>
+
+ <entry>DomDaoManagerBuilder</entry>
+
+ <entry>Responsible for configuration of the DAO framework (via
+ dao.config), instantiating DAO implementations and IDaoManager instances.</entry>
+ </row>
+
+ <row>
+ <entry>IDaoManager (Facade)</entry>
+
+ <entry>Acting as a façade to the rest of the API.</entry>
+ </row>
+
+ <row>
+ <entry>IDalSession (Marker Interface)</entry>
+
+ <entry>A generic marker interface for a database session. A common
+ implementation would wrap an ADO.NET connection/transaction
+ object.</entry>
+ </row>
+
+ <row>
+ <entry>DataAccessException (Runtime Exception)</entry>
+
+ <entry>All methods and classes in the DAO API throw this exception
+ exclusively. DAO implementations should also throw this exception
+ exclusively and avoid throwing any other exception type by nesting
+ them within the DataAccessException.</entry>
+ </row>
+
+ <row>
+ <entry>IDao (Marker Interface)</entry>
+
+ <entry>A marker interface for all DAO implementations. This
+ interface must be implemented by all DAO classes. This interface
+ does not declare any methods to be implemented and only acts as a
+ marker (i.e. something for the XML-based DaoFactory to identify
+ the class by).</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect1>
+
+ <sect1>
+ <title>Session Handler</title>
+
+ <table>
+ <title>Session Handler Implementations</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Session Handler</entry>
+
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>SqlMap</entry>
+
+ <entry>Manages connection and transactions via the DataMapper
+ framework.</entry>
+ </row>
+
+ <row>
+ <entry>NHibernate</entry>
+
+ <entry>Provides easy integration for NHibernate and its associated
+ transaction facilities (SessionFactory, Session,
+ Transaction).</entry>
+ </row>
+
+ <row>
+ <entry>ADONET</entry>
+
+ <entry>Manages connection and transactions via ADO.NET using the
+ basic iBATIS.NET DataSource, IDbConnection, and IDbTransaction
+ interfaces.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/DAODiagram.gif" format="GIF" />
+ </imageobject>
+
+ <caption>
+ <para>iBATIS.NET Data Access Objects</para>
+ </caption>
+ </mediaobject>
+ </sect1>
+</chapter>
\ No newline at end of file
Added: ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/example.xml
URL: http://svn.apache.org/viewvc/ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/example.xml?rev=682456&view=auto
==============================================================================
--- ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/example.xml (added)
+++ ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/example.xml Mon Aug 4 11:43:42 2008
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="example">
+ <title>Examples</title>
+
+ <sect1>
+ <title>NPetshop Application</title>
+
+ <para>For a complete example of using the DAO Framework, please visit
+ <ulink url="http://ibatis.apache.org/">http://ibatis.apache.org/</ulink>
+ and download the NPetshop demo application. Have fun!</para>
+ </sect1>
+</chapter>
\ No newline at end of file
Added: ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/handler.xml
URL: http://svn.apache.org/viewvc/ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/handler.xml?rev=682456&view=auto
==============================================================================
--- ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/handler.xml (added)
+++ ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/handler.xml Mon Aug 4 11:43:42 2008
@@ -0,0 +1,123 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="handler">
+ <title>Session Handler Implementations and Configuration</title>
+
+ <sect1>
+ <title>Overview</title>
+
+ <para>A Session Handler implementation is a component that manages
+ transaction and connections for a session. There are currently three
+ implementations of session handlers that come with the framework: Simple,
+ SqlMap, and NHibernate.</para>
+ </sect1>
+
+ <sect1>
+ <title>Simple DAO Session Handler (Default) Example Configuration</title>
+
+ <para>This implementation uses ADO.NET to provide a connection and
+ transaction via the ADO.NET API.</para>
+
+ <example>
+ <title>Example Simple DAO Session Handler configuration</title>
+
+ <programlisting><context id="<emphasis role="blue">SimpleDao</emphasis>" default="<emphasis
+ role="blue">true</emphasis>">
+ <properties resource="<emphasis role="blue">database.config</emphasis>"/>
+
+ <database>
+ <emphasis role="comment"><!-- Optional ( default ) --></emphasis>
+ <provider name="<emphasis role="blue">sqlServer1.1</emphasis>"/>
+ <dataSource name="<emphasis role="blue">iBatisNet</emphasis>"
+ connectionString="<emphasis role="blue">data source=${datasource};database=${database};
+ user id=${userid};password=${password}</emphasis>"/>
+ </database>
+
+ <emphasis role="comment"><!-- Element daoSessionHandler (ADONET) is Optional ( default ) --></emphasis>
+
+ <daoFactory>
+ <dao interface="<emphasis role="blue">IBatisNet.Test.Dao.Interfaces.IAccountDao, IBatisNet.Test</emphasis>"
+ implementation="<emphasis role="blue">IBatisNet.Test.Dao.Implementations.Ado.AccountDao, IBatisNet.Test</emphasis>"/>
+ </daoFactory>
+</context></programlisting>
+ </example>
+
+ <para></para>
+ </sect1>
+
+ <sect1>
+ <title>SqlMap DAO Session Handler Example Configuration</title>
+
+ <para>The SqlMap session handler implementation wraps iBATIS Data Mapper
+ SqlMapper session management services for simple use via the DAO
+ framework. All you need to specify is the SqlMap configuration
+ file.</para>
+
+ <example>
+ <title>Example SqlMap DAO Session Handler configuration</title>
+
+ <programlisting><context id="<emphasis role="blue">SqlMapDao</emphasis>">
+ <properties resource="<emphasis role="blue">database.config</emphasis>"/>
+
+ <database>
+ <provider name="<emphasis role="blue">OleDb1.1</emphasis>"/>
+ <dataSource name="<emphasis role="blue">iBatisNet</emphasis>"
+ connectionString="<emphasis role="blue">Provider=SQLOLEDB;Server=${database};database=IBatisNet;
+ user id=${userid};password=${password};</emphasis>"/>
+ </database>
+
+ <daoSessionHandler id="SqlMap">
+ <property name="resource" value="<emphasis role="blue">SqlMap.config</emphasis>"/>
+ </daoSessionHandler>
+
+ <daoFactory>
+ <dao interface="<emphasis role="blue">IBatisNet.Test.Dao.Interfaces.IAccountDao, IBatisNet.Test</emphasis>"
+ implementation="<emphasis role="blue">IBatisNet.Test.Dao.Implementations.DataMapper.AccountDao, IBatisNet.Test"</emphasis>/>
+ </daoFactory>
+</context></programlisting>
+ </example>
+
+ <para></para>
+ </sect1>
+
+ <sect1>
+ <title>NHibernate DAO Session Handler Example Configuration</title>
+
+ <para>Similar to the SqlMap implementation, the NHibernate session handler
+ implementation wraps the NHibernate session management services for simple
+ use via the DAO framework. Basically, the properties specified in the
+ configuration are the same as those that would normally be specified in an
+ NHibernate configuration section. Here is an example configuration:</para>
+
+ <example>
+ <title>Example NHibernate DAO Session Handler configuration</title>
+
+ <programlisting><context id="<emphasis role="blue">NHibernateDao</emphasis>">
+ <properties resource="<emphasis role="blue">database.config</emphasis>"/>
+
+ <database>
+ <provider name="<emphasis role="blue">OleDb1.1</emphasis>"/>
+ <dataSource name="<emphasis role="blue">iBatisNet</emphasis>"
+ connectionString="<emphasis role="blue">Provider=SQLOLEDB;Server=${database};database=IBatisNet;
+ user id=${userid};password=${password};</emphasis>"/>
+ </database>
+
+ <daoSessionHandler id="NHibernate">
+ <property name="hibernate.dialect"
+ value="<emphasis role="blue">NHibernate.Dialect.MsSql2000Dialect</emphasis>"/>
+ <property name="hibernate.connection.provider"
+ value="<emphasis role="blue">NHibernate.Connection.DriverConnectionProvider</emphasis>"/>
+ <property name="hibernate.connection.driver_class"
+ value="<emphasis role="blue">NHibernate.Driver.SqlClientDrive</emphasis>r"/>
+ <property name="mapping" value="<emphasis role="blue">IBatisNet.Test</emphasis>"/>
+ <property name="show_sql" value="<emphasis role="blue">false</emphasis>"/>
+ <property name="use_outer_join" value="<emphasis role="blue">true</emphasis>"/>
+ </daoSessionHandler>
+
+ <daoFactory>
+ <dao interface="<emphasis role="blue">IBatisNet.Test.Dao.Interfaces.IAccountDao, IBatisNet.Test</emphasis>"
+ implementation="<emphasis role="blue">IBatisNet.Test.Dao.Implementations.DataMapper.AccountDao, IBatisNet.Test</emphasis>"/>
+ </daoFactory>
+</context></programlisting>
+ </example>
+ </sect1>
+</chapter>
\ No newline at end of file
Added: ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/images/DAODesign.gif
URL: http://svn.apache.org/viewvc/ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/images/DAODesign.gif?rev=682456&view=auto
==============================================================================
Binary file - no diff available.
Propchange: ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/images/DAODesign.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/images/DAODiagram.gif
URL: http://svn.apache.org/viewvc/ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/images/DAODiagram.gif?rev=682456&view=auto
==============================================================================
Binary file - no diff available.
Propchange: ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/images/DAODiagram.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/images/ibatisnet.gif
URL: http://svn.apache.org/viewvc/ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/images/ibatisnet.gif?rev=682456&view=auto
==============================================================================
Binary file - no diff available.
Propchange: ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/images/ibatisnet.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/index.xml
URL: http://svn.apache.org/viewvc/ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/index.xml?rev=682456&view=auto
==============================================================================
--- ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/index.xml (added)
+++ ibatis/trunk/cs/V3/docs/dataAccessGuide/src/en/index.xml Mon Aug 4 11:43:42 2008
@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "../../../docbook/docbook-dtd/docbookx.dtd" [
+<!ENTITY introduction SYSTEM "introduction.xml">
+<!ENTITY dao SYSTEM "dao.xml">
+<!ENTITY configuration SYSTEM "configuration.xml">
+<!ENTITY handler SYSTEM "handler.xml">
+<!ENTITY programming SYSTEM "programming.xml">
+<!ENTITY interface SYSTEM "interface.xml">
+<!ENTITY example SYSTEM "example.xml">
+<!ENTITY xsd SYSTEM "xsd.xml">
+]>
+<book>
+ <bookinfo>
+ <title>iBATIS.NET - Data Access Objects Application Framework</title>
+ <subtitle>Data Access Objects Developer Guide</subtitle>
+ <releaseinfo>Version 1.9.1</releaseinfo>
+ <pubdate>March 2007</pubdate>
+ <authorgroup>
+ <author>
+ <firstname>Gilles</firstname>
+ <surname>Bayon</surname>
+ </author>
+ <author>
+ <firstname>Clinton</firstname>
+ <surname>Begin</surname>
+ </author>
+ <author>
+ <firstname>Roberto</firstname>
+ <surname>Rabe</surname>
+ </author>
+ </authorgroup>
+
+ <legalnotice>
+ <para>Copies of this document may be made for your own use and for
+ distribution to others, provided that you do not charge any fee for such
+ copies and further provided that each copy contains this Copyright
+ Notice, whether distributed in print or electronically.</para>
+ </legalnotice>
+ </bookinfo>
+
+ <toc></toc>
+
+ &introduction;
+ &dao;
+ &configuration;
+ &handler;
+ &programming;
+ &interface;
+ &example;
+ &xsd;
+
+</book>
\ No newline at end of file