You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ibatis.apache.org by cb...@apache.org on 2008/07/16 08:49:21 UTC
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
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>
+<cacheModel id="product-cache" type="LRU"><br>
+ <flushInterval hours="24"/><br>
+ <flushOnExecute statement="insertProduct"/><br>
+ <flushOnExecute statement="updateProduct"/><br>
+ <flushOnExecute statement="deleteProduct"/><br>
+ <property name=âsizeâ value=â1000â /><br>
+</cacheModel><br>
+<br>
+<select id=âgetProductListâ parameterClass=âintâ cacheModel=âproduct-cacheâ><br>
+ select * from PRODUCT where PRD_CAT_ID = #value#<br>
+</select><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 <sql> tag can be used to eliminate duplication of SQL code. You can define define a part of SQL code via
+the use of the <sql> tag and use it in a statement by using the <include> tag. Here is a short example:
+<br><br>
+Example:<br>
+<sql id="selectItem_fragment"><br>
+ FROM items<br>
+ WHERE parentid = 6<br>
+</sql><br>
+<br>
+<select id="selectItemCount" resultClass="int"><br>
+ SELECT COUNT(*) AS total<br>
+ <include refid="selectItem_fragment"/><br>
+</select><br>
+<br>
+<select id="selectItems" resultClass="Item"><br>
+ SELECT id, name<br>
+ <include refid="selectItem_fragment"/><br>
+</select>-->
<!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>
+<sql id="selectItem_fragment"><br>
+ FROM items<br>
+ WHERE parentid = 6<br>
+</sql><br>
+
+<select id="selectItemCount" resultClass="int"><br>
+ SELECT COUNT(*) AS total<br>
+ <include refid="selectItem_fragment"/><br>
+</select><br>
+
+<select id="selectItems" resultClass="Item"><br>
+ SELECT id, name<br>
+ <include refid="selectItem_fragment"/><br>
+</select>-->
<!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>
+<parameterMap id="swapParameters" class="map" ><br>
+ <parameter property="email1" jdbcType="VARCHAR" javaType="java.lang.String" mode="INOUT"/><br>
+ <parameter property="email2" jdbcType="VARCHAR" javaType="java.lang.String" mode="INOUT"/><br>
+</parameterMap><br>
+<br>
+<procedure id="swapEmailAddresses" parameterMap="swapParameters" ><br>
+ {call swap_email_address (?, ?)}<br>
+</procedure><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>
+<isLessEqual prepend=âANDâ property=âageâ compareValue=â18â><br>
+ ADOLESCENT = âTRUEâ<br>
+</isLessEqual>-->
<!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>
+<isNotEmpty prepend=âANDâ property=âfirstNameâ ><br>
+ FIRST_NAME=#firstName#<br>
+</isNotEmpty>-->
<!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>
+<iterate prepend=âANDâ property=âuserNameListâ open=â(â close=â)â conjunction=âORâ><br>
+ username=#userNameList[]#<br>
+</iterate><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>
+<iterate prepend=âANDâ open=â(â close=â)â conjunction=âORâ><br>
+ username=#[]#<br>
+</iterate><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>
+<property name="JDBC.Driver" value="${driver}"/>
+<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 <transactionManager> 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>
+<transactionManager type="JDBC" ><br>
+ <dataSource type="JNDI"><br>
+ <property name="DataSource" value="java:comp/env/jdbc/jpetstore"/><br>
+ </dataSource><br>
+</transactionManager><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>
+<transactionManager type="JTA" ><br>
+ <property name="UserTransaction" value="java:/comp/UserTransaction"/><br>
+ <dataSource type="JNDI"><br>
+ <property name="DataSource" value="java:comp/env/jdbc/jpetstore"/><br>
+ </dataSource><br>
+</transactionManager><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>
+<typeAlias alias="shortname" type="com.long.class.path.Class"/>-->
<!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