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