You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ibatis.apache.org by ro...@apache.org on 2005/05/23 03:25:06 UTC
svn commit: r177859 - in
/incubator/ibatis/trunk/cs/docs/dataMapperGuide/src/en: architecture.xml
introduction.xml working.xml
Author: roberto
Date: Sun May 22 18:25:05 2005
New Revision: 177859
URL: http://svn.apache.org/viewcvs?rev=177859&view=rev
Log:
~Updated C# DataMapper Dev Guide (minor updates so far)
Modified:
incubator/ibatis/trunk/cs/docs/dataMapperGuide/src/en/architecture.xml
incubator/ibatis/trunk/cs/docs/dataMapperGuide/src/en/introduction.xml
incubator/ibatis/trunk/cs/docs/dataMapperGuide/src/en/working.xml
Modified: incubator/ibatis/trunk/cs/docs/dataMapperGuide/src/en/architecture.xml
URL: http://svn.apache.org/viewcvs/incubator/ibatis/trunk/cs/docs/dataMapperGuide/src/en/architecture.xml?rev=177859&r1=177858&r2=177859&view=diff
==============================================================================
--- incubator/ibatis/trunk/cs/docs/dataMapperGuide/src/en/architecture.xml (original)
+++ incubator/ibatis/trunk/cs/docs/dataMapperGuide/src/en/architecture.xml Sun May 22 18:25:05 2005
@@ -36,25 +36,17 @@
accessing databases, whether through SQL statements or stored procedures.
But developers find several things are still hard to do well when using
"stock" ADO.NET, including:<itemizedlist>
- <listitem>
- Separating SQL code from programming code
- </listitem>
-
- <listitem>
- Passing input parameters to the library classes and extracting the output
- </listitem>
-
- <listitem>
- Separating data access classes from business logic classes
- </listitem>
-
- <listitem>
- Caching often-used data until it changes
- </listitem>
-
- <listitem>
- Managing transactions and threading
- </listitem>
+ <listitem>Separating SQL code from programming code</listitem>
+
+ <listitem>Passing input parameters to the library classes and
+ extracting the output</listitem>
+
+ <listitem>Separating data access classes from business logic
+ classes</listitem>
+
+ <listitem>Caching often-used data until it changes</listitem>
+
+ <listitem>Managing transactions and threading</listitem>
</itemizedlist></para>
@@ -71,7 +63,8 @@
- <para><figure>
+ <para>
+ <figure>
<title>iBATIS Data Mapper workflow</title>
<mediaobject>
@@ -80,7 +73,8 @@
format="GIF" />
</imageobject>
</mediaobject>
- </figure></para>
+ </figure>
+ </para>
Here's a high level description of the workflow diagrammed by Figure 2.1:
@@ -121,7 +115,7 @@
<programlisting>C#
-MyKey = Mapper.Instance().Insert("InsertLineItem",lineItem);</programlisting>
+int myKey = Mapper.Instance().Insert("InsertLineItem",lineItem);</programlisting>
@@ -129,7 +123,8 @@
- <para><example>
+ <para>
+ <example>
<title>The "InsertLineItem" descriptor</title>
<programlisting><insert id="InsertLineItem" parameterClass="LineItem">
@@ -141,7 +136,8 @@
select @@IDENTITY as value
</selectKey>
</insert></programlisting>
- </example></para>
+ </example>
+ </para>
@@ -155,8 +151,10 @@
- <para><programlisting>C#
-IList productList = Mapper.Instance().QueryForList("selectProduct",categoryKey);</programlisting></para>
+ <para>
+ <programlisting>C#
+IList productList = Mapper.Instance().QueryForList("selectProduct",categoryKey);</programlisting>
+ </para>
@@ -186,9 +184,9 @@
business layer is distinct from the user-interface layer.</para>
<para>Under these circumstances, another good choice would be an
- Object/Relational Mapping tool (OR/M tool), like NHibernate. (Other
+ Object/Relational Mapping tool (OR/M tool), like NHibernate. Other
products in this category are Apache ObjectRelationalBridge and
- Gentle.NET.) An OR/M tool generates all or most of the SQL for you, either
+ Gentle.NET. An OR/M tool generates all or most of the SQL for you, either
beforehand or at runtime. These products are called OR/M tools because
they try to map an object graph to a relational schema.</para>
Modified: incubator/ibatis/trunk/cs/docs/dataMapperGuide/src/en/introduction.xml
URL: http://svn.apache.org/viewcvs/incubator/ibatis/trunk/cs/docs/dataMapperGuide/src/en/introduction.xml?rev=177859&r1=177858&r2=177859&view=diff
==============================================================================
--- incubator/ibatis/trunk/cs/docs/dataMapperGuide/src/en/introduction.xml (original)
+++ incubator/ibatis/trunk/cs/docs/dataMapperGuide/src/en/introduction.xml Sun May 22 18:25:05 2005
@@ -30,6 +30,15 @@
<para>A Tutorial is also available. We recommend reviewing the Tutorial
for your platform before reading this Guide.</para>
+
+ <tip>
+ <para>If you would like to get the latest development (unreleased)
+ version of this Guide, please see the <ulink
+ url="http://opensource.atlassian.com/confluence/oss/display/IBATIS/How+do+I+generate+PDF+and+HTML+Help+files+from+the+latest+documentation+XML+source+files+in+the+source+control+repository%3F">iBATIS
+ Wiki FAQ</ulink>. The FAQ entry explains how you can access our SVN
+ source repository and generate CHM and PDF files of the latest
+ development documentation for the Data Mapper.</para>
+ </tip>
</sect1>
<sect1>
Modified: incubator/ibatis/trunk/cs/docs/dataMapperGuide/src/en/working.xml
URL: http://svn.apache.org/viewcvs/incubator/ibatis/trunk/cs/docs/dataMapperGuide/src/en/working.xml?rev=177859&r1=177858&r2=177859&view=diff
==============================================================================
--- incubator/ibatis/trunk/cs/docs/dataMapperGuide/src/en/working.xml (original)
+++ incubator/ibatis/trunk/cs/docs/dataMapperGuide/src/en/working.xml Sun May 22 18:25:05 2005
@@ -180,6 +180,7 @@
[parameterClass="<emphasis role="blue">alias</emphasis>"]
[resultMap="<emphasis role="blue">resultMap.name</emphasis>"]
[resultClass="<emphasis role="blue">class.name|alias</emphasis>"]
+ [listClass="<emphasis role="blue">class.name|alias</emphasis>"]
[cacheModel="<emphasis role="blue">cache.name</emphasis>"]
>
@@ -202,7 +203,7 @@
<para>Example 6 is obviously unlikely, unless you are running a test. But
it does shows that you can use iBATIS to execute arbitrary SQL statements.
More likely, you will use the object mapping features with Parameter Maps
- (Section 3.4) and Result Maps (Section 3.5), where the magic
+ (Section 3.4) and Result Maps (Section 3.5) since that's where the magic
happens.</para>
<sect2>
@@ -241,6 +242,7 @@
resultClass
parameterMap
resultMap
+listClass
cacheModel</programlisting></entry>
<entry><programlisting>All dynamic elements</programlisting></entry>
@@ -272,13 +274,14 @@
<entry><programlisting>id
parameterClass
-parameterMap</programlisting></entry>
+parameterMap
+extends</programlisting></entry>
<entry><programlisting>All dynamic elements
<generate></programlisting></entry>
<entry><programlisting>Insert
-Udate
+Update
Delete</programlisting></entry>
</row>
@@ -287,7 +290,8 @@
<entry><programlisting>id
parameterClass
-parameterMap</programlisting></entry>
+parameterMap
+extends</programlisting></entry>
<entry><programlisting>All dynamic elements
<generate></programlisting></entry>
@@ -305,7 +309,8 @@
resultClass
parameterMap
resultMap
-cacheModel</programlisting></entry>
+cacheModel
+extends</programlisting></entry>
<entry><programlisting>All dynamic elements
<generate></programlisting></entry>
@@ -317,10 +322,10 @@
<entry><procedure></entry>
<entry><programlisting>id
-parameterClass
-resultClass
parameterMap
-resultMap</programlisting></entry>
+resultClass
+resultMap
+cacheModel</programlisting></entry>
<entry><programlisting>All dynamic elements </programlisting></entry>
@@ -353,7 +358,7 @@
<parameter property="email2" column="Second_Email" />
</parameterMap>
-<emphasis role="comment"><!-- Oracle with .NET 1.1 System.Data.OracleClient provider --></emphasis>
+<emphasis role="comment"><!-- Oracle with MS OracleClient provider --></emphasis>
<procedure id="InsertCategory" parameterMap="insert-params">
prc_InsertCategory
</procedure>
@@ -364,9 +369,9 @@
<parameter property="Id" column="p_Category_Id" dbType="Int32" type="Int"/>
</parameterMap>
-<emphasis role="comment"><!-- Oracle with ODP.NET 9i provider --></emphasis>
+<emphasis role="comment"><!-- Oracle with ODP.NET 10g provider --></emphasis>
<statement id="InsertAccount" parameterMap="insert-params">
- call prc_InsertAccount(?, ?, ?, ?)
+ prc_InsertAccount
</statement>
...
<parameterMap id="insert-params">
@@ -385,8 +390,9 @@
Otherwise they are left unchanged. Of course, immutable parameter
objects (e.g. <classname>String</classname>) cannot be modified.<note>
<para>For .NET, the parameterMap attribute is required. The DBType,
- parameter direction, and size are all auto-discovered by the
- framework (via the CommandBuilder).</para>
+ parameter direction, size, precision, and scale are usually
+ auto-discovered by the framework (via the CommandBuilder) depending
+ on your provider.</para>
</note></para>
</sect2>
@@ -440,7 +446,7 @@
<programlisting><emphasis role="comment"><!âOracle SEQUENCE Example using .NET 1.1 System.Data.OracleClient --></emphasis>
<insert id="insertProduct-ORACLE" parameterClass="product">
<selectKey resultClass="int" type="pre" property="Id" >
- <emphasis role="blue">SELECT STOCKIDSEQUENCE.NEXTVAL AS ID FROM DUAL</emphasis>
+ <emphasis role="blue">SELECT STOCKIDSEQUENCE.NEXTVAL AS VALUE FROM DUAL</emphasis>
</selectKey>
insert into PRODUCT (PRD_ID,PRD_DESCRIPTION) values (#id#,#description#)
</insert>
@@ -624,7 +630,7 @@
<parameterMap> and a corresponding <statement>.<example>
<title>A parameterMap and corresponding statement</title>
- <programlisting><parameterMap id="<emphasis role="blue">insert-product-param</emphasis>" class="product">
+ <programlisting><parameterMap id="<emphasis role="blue">insert-product-param</emphasis>" class="Product">
<parameter property="id"/>
<parameter property="description"/>
</parameterMap>
@@ -658,7 +664,7 @@
<title>Ways to specify a parameterClass</title>
<programlisting><emphasis role="comment"><!-- fully qualified classname --></emphasis>
-<statement id="statementName" parameterClass="<emphasis role="blue">Examples.Domain.Product, examples.domain</emphasis>">
+<statement id="statementName" parameterClass="<emphasis role="blue">Examples.Domain.Product, Examples.Domain</emphasis>">
insert into PRODUCT values (#id#, #description#, #price#)
</statement>
@@ -740,18 +746,18 @@
<property>BirthDate</property>,
<property>WeightInKilograms</property>, and
<property>HeightInMeters</property>. Each of these corresponds with
- the column aliases described by the SQL select statement (using the
- "<database>as</database>" keyword âa standard SQL feature). When
+ the column aliases described by the SQL select statement using the
+ "<database>as</database>" keyword âa standard SQL feature. When
executed, a <classname>Person</classname> object is instantiated and
populated by matching the object property names to the (aliased)
column names from the query.</para>
<para>Using SQL aliases to map columns to properties saves defining a
<resultMap> element, but there are limitations. There is no way
- to specify the types of the output columns (if necessary), there is no
- way to automatically load related data (complex properties), and there
- is a slight performance consequence (from accessing the result
- metadata). Architecturally, using aliases this way mixes
+ to specify the types of the output columns (if needed), there is no
+ way to automatically load related data such as complex properties, and
+ there is a slight performance consequence from accessing the result
+ metadata. Architecturally, using aliases this way mixes
<emphasis>database logic</emphasis> with <emphasis>reporting
logic</emphasis>, making the query harder to read and maintain. You
can overcome these limitations with an explicit Result Map (Section
@@ -1469,15 +1475,15 @@
are several developer options for mapping entity classes and subclasses
to database results:<itemizedlist>
<listitem>
- resultMap for each class
+ resultMap for each class
</listitem>
<listitem>
- resultMap with submaps for a class hierarchy
+ resultMap with submaps for a class hierarchy
</listitem>
<listitem>
- resultMap with extended resultMaps for each subclass
+ resultMap with extended resultMaps for each subclass
</listitem>
</itemizedlist>You can use the most efficient mapping strategies from
a SQL and query performance perspective when using the inheritance