ibatis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cbe...@apache.org
Subject svn commit: r677174 - in /ibatis/trunk/java/mapper/mapper2/src/com/ibatis/sqlmap/engine/builder/xml: sql-map-2.dtd sql-map-config-2.dtd
Date Wed, 16 Jul 2008 06:49:21 GMT
Author: cbegin
Date: Tue Jul 15 23:49:21 2008
New Revision: 677174

URL: http://svn.apache.org/viewvc?rev=677174&view=rev
Log:
iBATIS 515 -- Commented DTDs!  Thanks Benjamin Bortfeldt

Modified:
    ibatis/trunk/java/mapper/mapper2/src/com/ibatis/sqlmap/engine/builder/xml/sql-map-2.dtd
    ibatis/trunk/java/mapper/mapper2/src/com/ibatis/sqlmap/engine/builder/xml/sql-map-config-2.dtd

Modified: ibatis/trunk/java/mapper/mapper2/src/com/ibatis/sqlmap/engine/builder/xml/sql-map-2.dtd
URL: http://svn.apache.org/viewvc/ibatis/trunk/java/mapper/mapper2/src/com/ibatis/sqlmap/engine/builder/xml/sql-map-2.dtd?rev=677174&r1=677173&r2=677174&view=diff
==============================================================================
--- ibatis/trunk/java/mapper/mapper2/src/com/ibatis/sqlmap/engine/builder/xml/sql-map-2.dtd
(original)
+++ ibatis/trunk/java/mapper/mapper2/src/com/ibatis/sqlmap/engine/builder/xml/sql-map-2.dtd
Tue Jul 15 23:49:21 2008
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8" ?>
-
+ 
 <!--
    Copyright 2004 Clinton Begin
 
@@ -16,17 +16,29 @@
    limitations under the License.
  -->
 
+<!--The root element of an iBATIS SQL Map file.
+A single SQL Map XML file can contain as many cache models, parameter maps, result maps and
+statements as you like. Use discretion and organize the statements and maps appropriately
for your
+application (group them logically).-->
 <!ELEMENT sqlMap (typeAlias* | cacheModel* | resultMap* | parameterMap* | sql* | statement*
| insert* | update* | delete* | select* | procedure*)+>
 <!ATTLIST sqlMap
 xmlns:fo CDATA #IMPLIED
 namespace CDATA #IMPLIED
 >
 
+<!--The parameterMap is responsible for mapping JavaBeans properties to the parameters
of a statement.
+The parameterMap itself only requires a id attribute that is an identifier that statements
will use to refer to it.
+The class attribute is optional but highly recommended. Similar to the parameterClass attribute
of a statement, 
+the class attribute allows the framework to validate the incoming parameter as well as optimize
the engine
+for performance. The parameterMap can contain any number of parameter mappings that map directly
to the
+parameters of a statement.-->
 <!ELEMENT parameterMap (parameter+)>
 <!ATTLIST parameterMap
 id CDATA #REQUIRED
 class CDATA #REQUIRED
 >
+
+<!-- The <parameter> tag is used to describe the parameters of a parameterMap.-->
 <!ELEMENT parameter EMPTY>
 <!ATTLIST parameter
 property CDATA #REQUIRED
@@ -39,6 +51,27 @@
 resultMap CDATA #IMPLIED
 numericScale CDATA #IMPLIED
 >
+<!--Result maps are an extremely important component of Data Mapper. The resultMap is
responsible for
+mapping JavaBeans properties to the columns of a ResultSet produced by executing a query
mapped
+statement.
+The resultMap itself has a id attribute that statements will use to refer to it. The resultMap
also has a 
+class attribute that is the fully qualified (i.e. full package) name of a class or a type
alias. This class will 
+be instantiated and populated based on the result mappings it contains. The extends attribute
can be
+optionally set to the name of another resultMap upon which to base a resultMap. This is similar
to
+extending a class in Java, all properties of the super resultMap will be included as part
of the sub
+resultMap. The properties of the super resultMap are always inserted before the sub resultMap
+properties and the parent resultMap must be defined before the child. The classes for the
super/sub
+resultMaps need not be the same, nor do they need to be related at all (they can each use
any class).
+
+The resultMap element also supports the attribute groupBy. The groupBy attribute is used
to specify a list
+of properties in this resultMap that are used to identify unique rows in the returned result
set. Rows with
+equal values for the specified properties will only generate one result object. Use groupBy
in combination
+with nested resultMaps to solve the N+1 query problem (see following discussion for examples).
+
+The resultMap can contain any number of result mappings that map JavaBean properties to the
columns of a
+ResultSet. These property mappings will be applied in the order that they are defined in
the document. The
+associated class must be a JavaBeans compliant class with appropriate get/set methods for
each of the
+properties, a Map or XML.-->
 <!ELEMENT resultMap (result*, discriminator?)>
 <!ATTLIST resultMap
 id CDATA #REQUIRED
@@ -47,6 +80,9 @@
 xmlName CDATA #IMPLIED
 groupBy CDATA #IMPLIED
 >
+<!--Results map JavaBean properties to the columns of a ResultSet. These property mappings
will be applied
+in the order that they are defined in the document. The associated class must be a JavaBeans
compliant 
+class with appropriate get/set methods for each of the properties, a Map or XML.-->
 <!ELEMENT result EMPTY>
 <!ATTLIST result
 property CDATA #REQUIRED
@@ -59,6 +95,7 @@
 resultMap CDATA #IMPLIED
 typeHandler CDATA #IMPLIED
 >
+<!-- TODO: add documentation. Could not find anything about this element in the official
iabtis doc.-->
 <!ELEMENT discriminator (subMap+)>
 <!ATTLIST discriminator
 javaType CDATA #REQUIRED
@@ -68,11 +105,29 @@
 nullValue CDATA #IMPLIED
 typeHandler CDATA #IMPLIED
 >
+<!-- TODO: add documentation. Could not find anything about this element in the official
iabtis doc. -->
 <!ELEMENT subMap EMPTY>
 <!ATTLIST subMap
 value CDATA #REQUIRED
 resultMap CDATA #REQUIRED
 >
+<!--A cacheModel is used to describe a cache for use with a query mapped statement. Each
query mapped statement 
+can use a different cacheModel, or the same one. The following example will demonstrate how
it looks related to a statement:
+<br><br>
+&lt;cacheModel id="product-cache" type="LRU"&gt;<br>
+	&lt;flushInterval hours="24"/&gt;<br>
+	&lt;flushOnExecute statement="insertProduct"/&gt;<br>
+	&lt;flushOnExecute statement="updateProduct"/&gt;<br>
+	&lt;flushOnExecute statement="deleteProduct"/&gt;<br>
+	&lt;property name=”size” value=”1000” /&gt;<br>
+&lt;/cacheModel&gt;<br>
+<br>
+&lt;select id=”getProductList” parameterClass=”int” cacheModel=”product-cache”&gt;<br>
+	select * from PRODUCT where PRD_CAT_ID = #value#<br>
+&lt;/select&gt;<br>
+
+In the above example, a cache is defined for products that uses a WEAK reference type and
flushes every
+24 hours or whenever associated update statements are executed.-->
 <!ELEMENT cacheModel (flushInterval?, flushOnExecute*, property*)+>
 <!ATTLIST cacheModel
 id CDATA #REQUIRED
@@ -80,6 +135,8 @@
 readOnly (true | false) #IMPLIED
 serialize (true | false) #IMPLIED
 >
+<!--Defines the interval of when the cache will be flushed. There can be only one flush
interval element and it
+can be set using hours, minutes, seconds or milliseconds.-->
 <!ELEMENT flushInterval EMPTY>
 <!ATTLIST flushInterval
 milliseconds CDATA #IMPLIED
@@ -87,33 +144,80 @@
 minutes CDATA #IMPLIED
 hours CDATA #IMPLIED
 >
+<!--Defines that the cache will be flushed when the specified statement is executed. There
can
+be any number of "flush on execute" elements specified for a cache.-->
 <!ELEMENT flushOnExecute EMPTY>
 <!ATTLIST flushOnExecute
 statement CDATA #REQUIRED
 >
 
+<!--Defines a standard Java property. Is used by various elements to define settings.-->
 <!ELEMENT property EMPTY>
 <!ATTLIST property
 name CDATA #REQUIRED
 value CDATA #REQUIRED
 >
 
+<!--The typeAlias element simply allows you to specify a shorter name to refer to what
is usually a long, fully
+qualified classname. For example:
+
+<typeAlias alias="shortname" type="com.long.class.path.Class"/>-->
 <!ELEMENT typeAlias EMPTY>
 <!ATTLIST typeAlias
 alias CDATA #REQUIRED
 type CDATA #REQUIRED
 >
 
+<!--The &lt;sql&gt; tag can be used to eliminate duplication of SQL code. You
can define define a part of SQL code via
+the use of the &lt;sql&gt; tag and use it in a statement by using the <include>
tag. Here is a short example:
+<br><br>
+Example:<br>
+&lt;sql id="selectItem_fragment"&gt;<br>
+	FROM items<br>
+	WHERE parentid = 6<br>
+&lt;/sql&gt;<br>
+<br>
+&lt;select id="selectItemCount" resultClass="int"&gt;<br>
+	SELECT COUNT(*) AS total<br>
+	&lt;include refid="selectItem_fragment"/&gt;<br>
+&lt;/select&gt;<br>
+<br>
+&lt;select id="selectItems" resultClass="Item"&gt;<br>
+	SELECT id, name<br>
+	&lt;include refid="selectItem_fragment"/&gt;<br>
+&lt;/select&gt;-->
 <!ELEMENT sql (#PCDATA | include | dynamic | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST sql
 id CDATA #REQUIRED
 >
 
+<!--The <include> tag can be used to insert SQL code fragments defined by the <sql>
tag into
+a SQL statement. Here is a short example:
+<br>
+Example:<br>
+&lt;sql id="selectItem_fragment"&gt;<br>
+	FROM items<br>
+	WHERE parentid = 6<br>
+&lt;/sql&gt;<br>
+
+&lt;select id="selectItemCount" resultClass="int"&gt;<br>
+	SELECT COUNT(*) AS total<br>
+	<include refid="selectItem_fragment"/><br>
+&lt;/select&gt;<br>
+
+&lt;select id="selectItems" resultClass="Item"&gt;<br>
+	SELECT id, name<br>
+	&lt;include refid="selectItem_fragment"/><br>
+&lt;/select&gt;-->
 <!ELEMENT include EMPTY>
 <!ATTLIST include
 refid CDATA #REQUIRED
 >
 
+<!-- The <statement> element is a general “catch all” statement that can
be used for any type of SQL statement.
+Generally it is a good idea to use one of the more specific statement elements. The more
specific elements
+provide a more intuitive XML DTD and sometimes provides additional features that a normal
<statement>
+element cannot. -->
 <!ELEMENT statement (#PCDATA | include | dynamic | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST statement
 id CDATA #REQUIRED
@@ -129,6 +233,8 @@
 timeout CDATA #IMPLIED
 >
 
+<!--Statement used for select queries.
+Supports all dynamic elements and query methods.-->
 <!ELEMENT select (#PCDATA | include | dynamic | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST select
 id CDATA #REQUIRED
@@ -144,6 +250,8 @@
 timeout CDATA #IMPLIED
 >
 
+<!--Statement used for insert queries.
+Supports all dynamic elements, <selectKey> and the query methods insert, update and
delete.-->
 <!ELEMENT insert (#PCDATA | include | dynamic | selectKey | iterate | isParameterPresent
| isNotParameterPresent | isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual
| isGreaterThan | isGreaterEqual | isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST insert
 id CDATA #REQUIRED
@@ -152,13 +260,29 @@
 timeout CDATA #IMPLIED
 >
 
+<!--Many relational database systems support auto-generation of primary key fields. This
feature of the
+RDBMS is often (if not always) proprietary. Data Mapper supports auto-generated keys via
the
+<selectKey> stanza of the <insert> element. Both pre-generated keys (e.g. Oracle)
and post-generated
+(MS-SQL Server) keys are supported.
+The selectKey statement is executed before the insert statement if it is placed before the
insert SQL,
+otherwise the selectKey statement is executed after the insert statement. In the previous
examples, the
+Oracle example shows that the selectKey will be executed before the insert statement (as
is appropriate for
+a sequence). The SQL Server example shows that the selectKey statement will be executed after
the insert
+statement (as is appropriate for an identity column).
+With iBATIS versions 2.2.0 and later, you can explicitly state the order of execution of
the statements if
+you wish. The selectKey element supports an attribute type that can be used to explicitly
set the execution
+order. The value of the type attribute can be either “pre” or “post”
- meaning that the statement will be
+executed before or after the insert statement. If you specify the type attribute, then the
value you specify
+will be used regardless of the position of the selectKey element.-->
 <!ELEMENT selectKey (#PCDATA | include)*>
 <!ATTLIST selectKey
 resultClass CDATA #IMPLIED
 keyProperty CDATA #IMPLIED
-type CDATA #IMPLIED
+type (pre|post) #IMPLIED
 >
 
+<!--Statement used for update queries.
+Supports all dynamic elements and the query methods insert, update and delete.-->
 <!ELEMENT update (#PCDATA | include | dynamic | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST update
 id CDATA #REQUIRED
@@ -167,6 +291,8 @@
 timeout CDATA #IMPLIED
 >
 
+<!--Statement used for delete queries.
+Supports all dynamic elements and the query methods insert, update and delete.-->
 <!ELEMENT delete (#PCDATA | include | dynamic | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST delete
 id CDATA #REQUIRED
@@ -175,6 +301,22 @@
 timeout CDATA #IMPLIED
 >
 
+<!--The <procedure> statement element is used for Stored Procedures. The following
example shows
+how a stored procedure would be used with output parameters:
+<br><br>
+&lt;parameterMap id="swapParameters" class="map" &gt;<br>
+	&lt;parameter property="email1" jdbcType="VARCHAR" javaType="java.lang.String" mode="INOUT"/&gt;<br>
+	&lt;parameter property="email2" jdbcType="VARCHAR" javaType="java.lang.String" mode="INOUT"/&gt;<br>
+&lt;/parameterMap&gt;<br>
+<br>
+&lt;procedure id="swapEmailAddresses" parameterMap="swapParameters" &gt;<br>
+	{call swap_email_address (?, ?)}<br>
+&lt;/procedure&gt;<br>
+<br>
+Calling the above procedure would swap two email addresses between two columns (database
table) and
+also in the parameter object (Map). The parameter object is only modified if the parameter
mappings mode
+attribute is set to “INOUT” or “OUT”. Otherwise they are left unchanged.
Obviously immutable parameter
+objects (e.g. String) cannot be modified.-->
 <!ELEMENT procedure (#PCDATA | include | dynamic | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST procedure
 id CDATA #REQUIRED
@@ -193,6 +335,7 @@
                  DYNAMIC ELEMENTS
   - - - - - - - - - - - - - - - - - - - - - - - - -->
 
+<!--Wrapper tag that allows for an overall prepend, open and close.-->
 <!ELEMENT dynamic (#PCDATA | include | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST dynamic
 prepend CDATA #IMPLIED
@@ -200,6 +343,7 @@
 close CDATA #IMPLIED
 >
 
+<!--Checks if a property is not null.-->
 <!ELEMENT isNotNull (#PCDATA | include | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST isNotNull
 prepend CDATA #IMPLIED
@@ -209,6 +353,7 @@
 removeFirstPrepend (true|false) #IMPLIED
 >
 
+<!--Checks if a property is null.-->
 <!ELEMENT isNull (#PCDATA | include | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST isNull
 prepend CDATA #IMPLIED
@@ -218,6 +363,7 @@
 removeFirstPrepend (true|false) #IMPLIED
 >
 
+<!--Checks if a property is unavailable (i.e not a property of the parameter bean).-->
 <!ELEMENT isNotPropertyAvailable (#PCDATA | include | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST isNotPropertyAvailable
 prepend CDATA #IMPLIED
@@ -227,6 +373,7 @@
 removeFirstPrepend (true|false) #IMPLIED
 >
 
+<!--Checks if a property is available (i.e is a property of the parameter bean).-->
 <!ELEMENT isPropertyAvailable (#PCDATA | include | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST isPropertyAvailable
 prepend CDATA #IMPLIED
@@ -236,6 +383,7 @@
 removeFirstPrepend (true|false) #IMPLIED
 >
 
+<!--Checks the equality of a property and a value, or another property.-->
 <!ELEMENT isEqual (#PCDATA | include | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST isEqual
 prepend CDATA #IMPLIED
@@ -247,6 +395,7 @@
 compareValue CDATA #IMPLIED
 >
 
+<!--Checks the inequality of a property and a value, or another property.-->
 <!ELEMENT isNotEqual (#PCDATA | include | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST isNotEqual
 prepend CDATA #IMPLIED
@@ -258,6 +407,7 @@
 compareValue CDATA #IMPLIED
 >
 
+<!--Checks if a property is greater than a value or another property.-->
 <!ELEMENT isGreaterThan (#PCDATA | include | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST isGreaterThan
 prepend CDATA #IMPLIED
@@ -269,6 +419,7 @@
 compareValue CDATA #IMPLIED
 >
 
+<!--Checks if a property is greater than or equal to a value or another property.-->
 <!ELEMENT isGreaterEqual (#PCDATA | include | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST isGreaterEqual
 prepend CDATA #IMPLIED
@@ -280,6 +431,7 @@
 compareValue CDATA #IMPLIED
 >
 
+<!--Checks if a property is less than a value or another property.-->
 <!ELEMENT isLessThan (#PCDATA | include | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST isLessThan
 prepend CDATA #IMPLIED
@@ -291,6 +443,12 @@
 compareValue CDATA #IMPLIED
 >
 
+<!--Checks if a property is less than or equal to a value or another property.
+<br>
+Example Usage:<br>
+&lt;isLessEqual prepend=”AND” property=”age” compareValue=”18”&gt;<br>
+	ADOLESCENT = ‘TRUE’<br>
+&lt;/isLessEqual&gt;-->
 <!ELEMENT isLessEqual (#PCDATA | include | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST isLessEqual
 prepend CDATA #IMPLIED
@@ -302,6 +460,8 @@
 compareValue CDATA #IMPLIED
 >
 
+<!--Checks to see if the value of a Collection, String or String.valueOf() property
+is null or empty (“” or size() < 1).-->
 <!ELEMENT isEmpty (#PCDATA | include | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST isEmpty
 prepend CDATA #IMPLIED
@@ -311,6 +471,13 @@
 removeFirstPrepend (true|false) #IMPLIED
 >
 
+<!--Checks to see if the value of a Collection, String or String.valueOf() property
+is not null and not empty (“” or size() < 1).
+<br><br>
+Example Usage:<br>
+&lt;isNotEmpty prepend=”AND” property=”firstName” &gt;<br>
+	FIRST_NAME=#firstName#<br>
+&lt;/isNotEmpty&gt;-->
 <!ELEMENT isNotEmpty (#PCDATA | include | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST isNotEmpty
 prepend CDATA #IMPLIED
@@ -320,6 +487,7 @@
 removeFirstPrepend (true|false) #IMPLIED
 >
 
+<!--Checks to see if the parameter object is present (not null).-->
 <!ELEMENT isParameterPresent (#PCDATA | include | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST isParameterPresent
 prepend CDATA #IMPLIED
@@ -328,6 +496,7 @@
 removeFirstPrepend (true|false) #IMPLIED
 >
 
+<!--Checks to see if the parameter object is not present (null). -->
 <!ELEMENT isNotParameterPresent (#PCDATA | include | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST isNotParameterPresent
 prepend CDATA #IMPLIED
@@ -336,6 +505,26 @@
 removeFirstPrepend (true|false) #IMPLIED
 >
 
+<!--Iterates over a property that is an implementation java.util.Collection, or
+java.util.Iterator, or is an array.
+<br><br>
+Example Usage:<br>
+&lt;iterate prepend=”AND” property=”userNameList” open=”(”
close=”)” conjunction=”OR”&gt;<br>
+	username=#userNameList[]#<br>
+&lt;/iterate&gt;<br>
+<br>
+It is also possible to use the iterate when the collection is passed in as a
+parameter to your mapped statement.
+<br>
+Example Usage:<br>
+&lt;iterate prepend=”AND” open=”(” close=”)” conjunction=”OR”&gt;<br>
+	username=#[]#<br>
+&lt;/iterate&gt;<br>
+
+Note: It is very important to include the square brackets[] at the end of the
+property name when using the Iterate element. These brackets distinguish this
+object as a collection to keep the parser from simply outputting the collection
+as a string.-->
 <!ELEMENT iterate (#PCDATA | include | iterate | isParameterPresent | isNotParameterPresent
| isEmpty | isNotEmpty | isNotNull | isNull | isNotEqual | isEqual | isGreaterThan | isGreaterEqual
| isLessThan | isLessEqual | isPropertyAvailable | isNotPropertyAvailable)*>
 <!ATTLIST iterate
 prepend CDATA #IMPLIED

Modified: ibatis/trunk/java/mapper/mapper2/src/com/ibatis/sqlmap/engine/builder/xml/sql-map-config-2.dtd
URL: http://svn.apache.org/viewvc/ibatis/trunk/java/mapper/mapper2/src/com/ibatis/sqlmap/engine/builder/xml/sql-map-config-2.dtd?rev=677174&r1=677173&r2=677174&view=diff
==============================================================================
--- ibatis/trunk/java/mapper/mapper2/src/com/ibatis/sqlmap/engine/builder/xml/sql-map-config-2.dtd
(original)
+++ ibatis/trunk/java/mapper/mapper2/src/com/ibatis/sqlmap/engine/builder/xml/sql-map-config-2.dtd
Tue Jul 15 23:49:21 2008
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8" ?>
-
+ 
 <!--
    Copyright 2004 Clinton Begin
 
@@ -16,17 +16,37 @@
    limitations under the License.
  -->
 
+<!--The root element of an iBATIS SQL Map configuration file.
+This file provides configuration details for DataSources, Data Mapper and other options like
thread management.-->
 <!ELEMENT sqlMapConfig (properties?, settings?, resultObjectFactory?, typeAlias*, typeHandler*,
transactionManager?, sqlMap+)+>
 <!ATTLIST sqlMapConfig
 xmlns:fo CDATA #IMPLIED
 >
 
+<!--The SQL Map can have a single <properties> element that allows a standard Java
properties file
+(name=value) to be associated with the SQL Map XML configuration document. By doing so, each
named
+value in the properties file can become a variable that can be referred to in the SQL Map
configuration file
+and all Data Mapper referenced within. For example, if the properties file contains the following:
+<br><br>
+driver=org.hsqldb.jdbcDriver
+<br><br>
+Then the SQL Map configuration file or each SQL Map referenced by the configuration document
can use
+the placeholder ${driver} as a value that will be replaced by org.hsqldb.jdbcDriver. For
example:
+<br><br>
+&lt;property name="JDBC.Driver" value="${driver}"/&gt;
+<br><br>
+This comes in handy during building, testing and deployment. It makes it easy to reconfigure
your app for
+multiple environments or use automated tools for configuration (e.g. Ant). The properties
can be loaded
+from the classpath (use the resource attribute) or from any valid URL (use the url attribute).-->
 <!ELEMENT properties EMPTY>
 <!ATTLIST properties
 resource CDATA #IMPLIED
 url CDATA #IMPLIED
 >
 
+<!-- The <settings> element allows you to configure various options and optimizations
for the SqlMapClient
+instance that will be built using this XML file. The settings element and all of its attributes
are completely
+optional. -->
 <!ELEMENT settings EMPTY>
 <!ATTLIST settings
 classInfoCacheEnabled (true | false) #IMPLIED
@@ -44,35 +64,124 @@
 defaultStatementTimeout CDATA #IMPLIED
 >
 
+<!--The <transactionManager> element allows you to configure the transaction management
services for an
+SQL Map. The type attribute indicates which transaction manager to use. The value can either
be a class
+name or a type alias. The three transaction managers included with the framework are: JDBC,
JTA and
+EXTERNAL.
+<br><br>
+JDBC - This allows JDBC to control the transaction via the usual Connection commit() and
+rollback() methods.<br>
+JTA - This transaction manager uses a JTA global transaction such that the SQL Map activities
can
+be included as part of a wider scope transaction that possibly involves other databases or
+transactional resources. This configuration requires a UserTransaction property set to locate
the
+user transaction from a JNDI resource.<br> 
+EXTERNAL – This allows you to manage transactions on your own. You can still configure
a
+data source, but transactions will not be committed or rolled back as part of the framework
+lifecycle. This means that some part of your application external to Data Mapper must manage
the
+transactions. This setting is also useful for non-transactional databases (e.g. Read-only).<br>
+<br>
+The &lt;transactionManager&gt; element also allows an optional attribute commitRequired
that can be true or
+false. Normally iBATIS will not commit transactions unless an insert, update, or delete operation
has been
+performed. This is true even if you explicitly call the commitTransaction() method. This
behavior
+creates problems in some cases. If you want iBATIS to always commit transactions, even if
no insert,
+update, or delete operation has been performed, then set the value of the commitRequired
attribute to true.
+Examples of where this attribute is useful include:
+<br><br>
+1. If you call a stored procedures that updates data as well as returning rows. In that case
you would
+call the procedure with the queryForList() operation – so iBATIS would not normally
commit the
+transaction. But then the updates would be rolled back.<br>
+2. In a WebSphere environment when you are using connection pooling and you use the JNDI
+<dataSource> and the JDBC or JTA transaction manager. WebSphere requires all transactions
on
+pooled connections to be committed or the connection will not be returned to the pool.<br>
+<br>
+Note that the commitRequired attribute has no effect when using the EXTERNAL transaction
manager.
+<br><br>
+Some of the transaction managers allow extra configuration properties.-->
 <!ELEMENT transactionManager (property*,dataSource)>
 <!ATTLIST transactionManager
 type CDATA #REQUIRED
 commitRequired (true | false) #IMPLIED
 >
 
+<!--Included as part of the transaction manager configuration is a dataSource element
and a set of properties to
+configure a DataSource for use with your SQL Map. There are currently three datasource factories
+provided with the framework, but you can also write your own.
+<br><br>
+<b>SimpleDataSourceFactory</b><br>
+The SimpleDataSource factory provides a basic implementation of a pooling DataSource that
is
+ideal for providing connections in cases where there is no container provided DataSource.
It is
+based on the iBATIS SimpleDataSource connection pool implementation.
+<br><br>
+<b>DbcpDataSourceFactory</b><br>
+This implementation uses Jakarta DBCP (Database Connection Pool) to provide connection
+pooling services via the DataSource API. This DataSource is ideal where the application/web
+container cannot provide a DataSource implementation, or you’re running a standalone
+application. IBATIS provides direct access to setting the properties of a DBCP datasource
by
+allowing you to specify any DBCP property name you desire in the configuration.
+<br><br>
+<b>JndiDataSourceFactory</b><br>
+This implementation will retrieve a DataSource implementation from a JNDI context from within
+an application container. This is typically used when an application server is in use and
a
+container managed connection pool and associated DataSource implementation are provided.
The
+standard way to access a JDBC DataSource implementation is via a JNDI context.
+JndiDataSourceFactory provides functionality to access such a DataSource via JNDI. The
+configuration parameters that must be specified in the datasource stanza are as follows:
+<br><br>
+&lt;transactionManager type="JDBC" &gt;<br>
+	&lt;dataSource type="JNDI"&gt;<br>
+		&lt;property name="DataSource" value="java:comp/env/jdbc/jpetstore"/&gt;<br>
+	&lt;/dataSource&gt;<br>
+&lt;/transactionManager&gt;<br>
+<br>
+The above configuration will use normal JDBC transaction management. But with a container
+managed resource, you might also want to configure it for global transactions as follows:
+<br><br>
+&lt;transactionManager type="JTA" &gt;<br>
+	&lt;property name="UserTransaction" value="java:/comp/UserTransaction"/&gt;<br>
+	&lt;dataSource type="JNDI"&gt;<br>
+		&lt;property name="DataSource" value="java:comp/env/jdbc/jpetstore"/&gt;<br>
+	&lt;/dataSource&gt;<br>
+&lt;/transactionManager&gt;<br>
+<br>
+Notice the UserTransaction property that points to the JNDI location where the UserTransaction
+instance can be found. This is required for JTA transaction management so that your SQL Map
+take part in a wider scoped transaction involving other databases and transactional resources.
+JNDI context properties can be added before the lookup by specifying additional properties
with a
+prefix of "context.".-->
 <!ELEMENT dataSource (property*)>
 <!ATTLIST dataSource
 type CDATA #REQUIRED
 >
 
+<!-- Defines a standard Java property. Is used by various elements to define settings.
-->
 <!ELEMENT property EMPTY>
 <!ATTLIST property
 name CDATA #REQUIRED
 value CDATA #REQUIRED
 >
 
+<!-- The sqlMap element is used to explicitly include an SQL Map or another SQL Map Configuration
file.
+Each SQL Map XML file that is going to be used by this SqlMapClient instance, must be declared.
The
+SQL Map XML files will be loaded as a stream resource from the classpath or from a URL. You
must
+specify any and all Data Mapper (as many as there are). -->
 <!ELEMENT sqlMap EMPTY>
 <!ATTLIST sqlMap
 resource CDATA #IMPLIED
 url CDATA #IMPLIED
 >
 
+<!--The typeAlias element simply allows you to specify a shorter name to refer to what
is usually a long, fully
+qualified classname. For example:
+<br><br>
+&lt;typeAlias alias="shortname" type="com.long.class.path.Class"/&gt;-->
 <!ELEMENT typeAlias EMPTY>
 <!ATTLIST typeAlias
 alias CDATA #REQUIRED
 type CDATA #REQUIRED
 >
 
+<!--This element is used to declare a custom TypeHandler in iBATIS. This is necessary
+for iBATIS to know how to handle translations between the stated java type and jdbc type.-->
 <!ELEMENT typeHandler EMPTY>
 <!ATTLIST typeHandler
 javaType CDATA #REQUIRED
@@ -80,6 +189,26 @@
 callback CDATA #REQUIRED
 >
 
+<!--The resultObjectFactory element allows you to specify a factory class for creating
objects resulting from
+the execution of SQL statements. This element is optional – if you don't specify the
element, iBATIS will
+use internal mechanisms to create result objects (class.newInstance()).
+<br><br>
+iBATIS creates result objects in these cases:
+<br>
+1. When mapping rows returned from a ResultSet (the most common case)<br>
+2. When you use a nested select statement on a result element in a resultMap. If the nested
select
+statement declares a parameterClass, then iBATIS will create and populate an instance of
the class
+before executing the nested select<br>
+3. When executing stored procedures – iBATIS will create objects for OUTPUT parameters<br>
+4. When processing nested result maps. If the nested result map is used in conjunction with
the
+groupBy support for avoiding N+1 queries, then the object will typically be an implementation
of
+type Collection, List, or Set. You can provide custom implementations of these interfaces
through
+the result object factory if you wish. In a 1:1 join with a nested result map, then iBATIS
will
+create an instance of the specified domain object through this factory.<br>
+<br>
+If you choose to implement a factory, your factory class must implement the interface
+com.ibatis.sqlmap.engine.mapping.result.ResultObjectFactory, and your class must have a public
+default constructor. The ResultObjectFactory interface has two-->
 <!ELEMENT resultObjectFactory (property*)>
 <!ATTLIST resultObjectFactory
 type CDATA #REQUIRED



Mime
View raw message