The best way to determine if you should upgrade is to try it. There are a few upgrade paths.

The 2.0 framework includes an XML document converter that runs via the Ant build system. Converting your XML documents is completely optional as 1.x code will automatically transform old XML files on the fly. Still, it’s a good idea to convert your files once you’re comfortable with the idea of upgrading. You will experience fewer compatibility issues and you’ll be able to take advantage of some of the new features (even if you’re still using the 1.x Java API).

The Ant task looks like this in your build.xml file:

<target>
  <taskdef name="convertSqlMaps"
    classname="com.ibatis.db.sqlmap.upgrade.ConvertTask"
    classpathref="classpath"/> <target name="convert">
  <convertSqlMaps todir="D:/targetDirectory/" overwrite="true">
    <fileset dir="D/sourceDirectory/"> <include
      name="**/maps/*.xml"/> 
    </fileset> 
  </convertSqlMaps>
</target>

As you can see, it works exactly like the Ant copy task, and in fact it extends the Ant copy task, so you can really do anything with this task that Copy can do (see the Ant Copy task documentation for details).

When upgrading, it's a good idea to remove all existing (old) iBATIS SQL Map files and dependencies, and replace them with the new files. Be sure not to remove any that your other components or frameworks might still need. Note that most of the JAR files are optional depending on your circumstances. Please see the discussion above for more information about JAR files and dependencies

The following table summarizes the old files and the new ones.

ibatis-db.jar After
    release 1.2.9b, this file was split into the following 3 files:
    batis-common.jar ibatis-dao.jar
    ibatis-sqlmap.jar

ibatis-common.jar (required)
    ibatis-sqlmap.jar (required) ibatis-dao-1-2-9-b.jar (optional 1.x DAO)
    ibatis-compat (optional 1.x compatibility)

commons-logging.jar
    commons-logging-api.jar commons-collections.jar commons-dbcp.jar
    commons-pool.jar oscache.jar jta.jar dbc2_0-stdext.jar xercesImpl.jar
    xmlParserAPIs.jar jjdom.jar

commons-logging-1-0-3.jar (required)
    commons-collections-2-1.jar (optional) commons-dbcp-1-1.jar (optional)
    commons-pool-1-1.jar (optional) oscache-2-0-1.jar (optional)
    jta-1-0-1a.jar (optional) jdbc2_0-stdext.jar (optional)
    xercesImpl-2-4-0.jar (optional) xmlParserAPIs-2-4-0.jar (optional)
    xalan-2-5-2.jar (optional) log4j-1.2.8.jar (optional)
    cglib-full-2-0-rc2.jar (optional)

Sometimes the values we use in an XML configuration file occur in more than one element. Often, there are values that change when we move the application from one server to another. To help you manage configuration values, you can specify a standard properties file (name=value) as part of a Data Mapper configuration. Each named value in the properties file becomes a "shell" variable that can be used throughout the Data Mapper configuration, including the Data Map definition files (see Section 3). For example, if the properties file contains

username=iBATIS

then any element in the Data Mapper configuration, including the data maps, can use the variable ${username} to insert the value "iBATIS". For example:

<dataSource connectionString="user id=${username}; 

Properties are handy during building, testing, and deployment. Properties make it easy to reconfigure your application 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). For example, to load a fixed path file, use:

<properties url=”file:///c:/config/my.properties” />

There are a number of minimums, maximums, and other settings used by the framework. The settings appropriate for one application may not be appropriate for another. The <settings> element lets you configure these options and optimizations for the SqlMapClient instance that is created from the XML document. All of the settings have defaults, and you can omit the setting element or any of its attributes. The setting attributes and their behavior they control are described in Table 9.

Example: cacheModelsEnabled=”true”
Default: true (enabled)

queryForObject(“sqlMapName.statementName”);
(See the Developers Guide for your platform (Section 4 or 5) for more about creating Data Map clients.)
Example: useStatementNamespaces=”false”
Default: false (disabled)

Example: maxRequests=”256”
Default: 512

Example: maxSessions=”64”
Default: 128

Example: maxTransactions=”16”
Default: 32

Example: lazyLoadingEnabled=”true”
Default: true (enabled)

Example: enhancementEnabled=”true”
Default: false (disabled)

The typeAlias element lets you specify a shorter name in lieu of fully-qualified classname. For example:

<typeAlias name="Account" assembly="NPetshop.Domain.dll" class="NPetshop.Domain.Accounts.Account" />

You can then refer to "account" or "Account" where you would normally have to spell-out the fully qualified class name.

The <typeAlias> element has two required properties:

JDBC = com.ibatis.sqlmap.engine.transaction.jdbc.JdbcTransactionConfig JTA = com.ibatis.sqlmap.engine.transaction.jta.JtaTransactionConfig EXTERNALcom.ibatis.sqlmap.engine.transaction.external.ExternalTransactionConfig

SIMPLE = com.ibatis.sqlmap.engine.datasource.SimpleDataSourceFactory DBCP = com.ibatis.sqlmap.engine.datasource.DbcpDataSourceFactory JNDI = com.ibatis.sqlmap.engine.datasource.JndiDataSourceFactory

The .NET implementation only supports ADO-controlled transaction.

Three DataSource factories are provided with the Java implementation, and you can also write your own. The bundled DataSourceFactory implementations are discussed in Sections 4.2.3.5.1 through Section 4.2.3.5.3.

<transactionManager type="JDBC">
            <dataSource type="SIMPLE"> <property name="JDBC.Driver"
            value="org.postgresql.Driver"/> <property
            name="JDBC.ConnectionURL"
            value="jdbc:postgresql://server:5432/dbname"/> <property
            name="JDBC.Username" value="user"/> <property
            name="JDBC.Password" value="password"/> <!-- OPTIONAL
            PROPERTIES BELOW --> <property
            name="Pool.MaximumActiveConnections" value="10"/> <property
            name="Pool.MaximumIdleConnections" value="5"/> <property
            name="Pool.MaximumCheckoutTime" value="120000"/> <property
            name="Pool.TimeToWait" value="10000"/> <property
            name="Pool.PingQuery" value="select * from dual"/> <property
            name="Pool.PingEnabled" value="false"/> <property
            name="Pool.PingConnectionsOlderThan" value="0"/> <property
            name="Pool.PingConnectionsNotUsedFor" value="0"/>
            </dataSource> </transactionManager>

<transactionManager
            type="JDBC"> <dataSource type="DBCP"> <property
            name="JDBC.Driver" value="${driver}"/> <property
            name="JDBC.ConnectionURL" value="${url}"/> <property
            name="JDBC.Username" value="${username}"/> <property
            name="JDBC.Password" value="${password}"/> <!-- OPTIONAL
            PROPERTIES BELOW --> <property
            name="Pool.MaximumActiveConnections" value="10"/> <property
            name="Pool.MaximumIdleConnections" value="5"/> <property
            name="Pool.MaximumWait" value="60000"/> <!-- Use of the
            validation query can be problematic. If you have difficulty, try
            without it. --> <property name="Pool.ValidationQuery"
            value="select * from ACCOUNT"/> <property
            name="Pool.LogAbandoned" value="false"/> <property
            name="Pool.RemoveAbandoned" value="false"/> <property
            name="Pool.RemoveAbandonedTimeout" value="50000"/>
            </datasource>
            </transactionManager>

<transactionManager
            type="JDBC" > <dataSource type="JNDI"> <property
            name="DataSource" value="java:comp/env/jdbc/jpetstore"/>
            </dataSource> </transactionManager>

<transactionManager type="JTA" >
            <property name="UserTransaction"
            value="java:/ctx/con/UserTransaction"/> <dataSource
            type="JNDI"> <property name="DataSource"
            value="java:comp/env/jdbc/jpetstore"/> </dataSource>
            </transactionManager>

On a daily basis, most of your work will be with the Data Maps. The Data Maps define the actual SQL statements or stored procedures used by your application. The parameter and result objects are also defined as part of the Data Map. As your application grows, you may have several varieties of Data Map. To help you keep your Data Maps organized, you can create any number of Data Map definition files and incorporate them by reference into the Data Mapper configuration. All of the definition files used by a Data Mapper instance must be listed in the configuration file.

Example 32 shows <sqlMap> elements for loading a set of Data Map definitions, either from the classpath or an URL.

<!-- CLASSPATH RESOURCES (Java) -->
<sqlMap resource="com/ibatis/jpetstore/persistence/sqlmapdao/sql/Category.xml"/>
<sqlMap resource="com/ibatis/jpetstore/persistence/sqlmapdao/sql/Product.xml"/>

<!-- URL RESOURCES (Java)(absolute) -->
<sqlMap url="file:///c:/config/Category.xml" />
<sqlMap url="file:///c:/config/Product.xml" />

<!-- Application path (.NET) -->
<sqlMap resource="sql/Category.xml"/>
<sqlMap resource="://sql/Product.xml"/>

<!-- URL RESOURCES (.NET)(absolute) -->
<sqlMap url="c:/config/maps/Category.xml"/>
<sqlMap url="c:/config/Maps/Product.xml"/>

Section 3 describes the Data Map definition files.

Although using explicit transactions is very highly recommended, there is a simplified semantic that can be used for simple requirements (generally read-only). If you do not explicitly demarcate transactions using the startTransaction(), commitTransaction() and endTransaction() methods, they will all be called automatically for you whenever you execute a statement outside of a transactional block as demonstrated in the above. For example:

private Reader reader = new Resources.getResourceAsReader ("com/ibatis/example/sqlMapconfig.xml");

private SqlMapClient sqlMap = XmlSqlMapBuilder.buildSqlMap(reader);

public updateItemDescription (String itemId, String newDescription) throws SQLException {
  try {
    Item item = (Item) sqlMap.queryForObject ("getItem", itemId);
    item.setDescription (“TX1”);
    // No transaction demarcated, so transaction will be automatic (implied)
    sqlMap.update ("updateItem", item);
    item.setDescription (newDescription);
    item.setDescription (“TX2”);
    // No transaction demarcated, so transaction will be automatic (implied)
    sqlMap.update("updateItem", item);
  } 
  catch (SQLException e) {
    throw (SQLException) e.fillInStackTrace();
  }
}

You can choose to manage global transactions externally, either programmatically (coded by hand), or by implementing another framework such as the very common EJB. Using EJBs you can declaratively demarcate (set the boundaries of) a transaction in an EJB deployment descriptor. Further discussion of how this is done is beyond the scope of this document. To enable support external or programmatic global transactions, you must set the <transactionManager> type attribute to “EXTERNAL” in your Data Mapper configuration file (see above). When using externally controlled global transactions, the SQL Map transaction control methods are somewhat redundant, because the begin, commit and rollback of transactions will be controlled by the external transaction manager. However, there can be a performance benefit to still demarcating your transactions using the SqlMapClient methods startTransaction(), commitTransaction() and endTransaction() (vs. allowing an automatic transaction to started and committed or rolled back). By continuing to use these methods, you will maintain a consistent programming paradigm, as well as you will be able to reduce the number of requests for connections from the connection pool. Further benefit is that in some cases you may need to change the order in which resources are closed (commitTransaction() or endTransaction()) versus when the global transaction is committed. Different app servers and transaction managers have different rules (unfortunately). Other than these simple considerations, there are really no changes required to your Data Mapper code to make use of a global transaction.

The iBATIS Data Mapper framework can also manage global transactions for you. To enable support for managed global transactions, you must set the <transactionManager> type attribute to “JTA” in your SQL Map configuration file and set the “UserTransaction” property to the full JNDI name of where the SqlMapClient instance will find the UserTransaction instance. See the <transactionManager> discussion above for full configuration details.

Programming for global transactions is not much different, however there are some small considerations. Here is an example:

try {
  orderSqlMap.startTransaction();
  storeSqlMap.startTransaction();
  orderSqlMap.insertOrder(…);
  orderSqlMap.updateQuantity(…);
  storeSqlMap.commitTransaction();
  orderSqlMap.commitTransaction();
  } 
  finally {
    try {
      storeSqlMap.endTransaction()
    } 
    finally {
      orderSqlMap.endTransaction()
    }
}

In this example, there are two SqlMapClient instances that we will assume are using two different databases. The first SqlMapClient (orderSqlMap) that we use to start a transaction will also start the global transaction. After that, all other activity is considered part of the global transaction until that same SqlMapClient (orderSqlMap) calls commitTransaction() and endTransaction(), at which point the global transaction is committed and all other work is considered done.

These methods are specifically meant for update statements (a.k.a. non-query). That said, it’s not impossible to execute an update statement using one of the query methods below, however this is an odd semantic and obviously driver dependent. In the case of executeUpdate(), the statement is simply executed and the number of rows effected is returned.

There are two versions of executeQueryForObject(), one that returns a newly allocated object, and another that uses a pre-allocated object that is passed in as a parameter. The latter is useful for objects that are populated by more than one statement.

There are three versions of queryForList(). The first executes a query and returns all of the results from that query. The second allows for specifying a particular number of results to be skipped (i.e. a starting point) and also the maximum number of records to return. This is valuable when dealing with extremely large data sets that you do not want to return in their entirety.

Finally there is a queryForList() method that takes a row handler. This method allows you to process result sets row by row but using the result object rather than the usual columns and rows. The method is passed the typical name and parameter object, but it also takes a RowHandler. The row handler is an instance of a class that implements the RowHandler interface. The RowHandler interface has only one method as follows:

public void handleRow (Object object, List list);

This very useful method returns a list that can manage a subset of data that can be navigated forward and back. This is commonly used in implementing user interfaces that only display a subset of all of the available records returned from a query. An example familiar to most would be a web search engine that finds 10,000 hits, but only displays 100 at a time. The PaginatedList interface includes methods for navigating through pages (nextPage(), previousPage(), gotoPage()) and also checking the status of the page (isFirstPage(), isMiddlePage(), isLastPage(), isNextPageAvailable(), isPreviousPageAvailable(), getPageIndex(), getPageSize()). Although the total number of records available is not accessible from the PaginatedList interface, this should be easily accomplished by simply executing a second statement that counts the expected results. Too much overhead would be associated with the PaginatedList otherwise.

This method provides an alternative to loading a collection of results into a list. Instead it loads the results into a map keyed by the parameter passed in as the keyProperty. For example, if loading a collection of Employee objects, you might load them into a map keyed by the employeeNumber property. The value of the map can either be the entire employee object, or another property from the employee object as specified in the optional second parameter called valueProperty. For example, you might simply want a map of employee names keyed by the employee number. Do not confuse this method with the concept of using a Map type as a result object. This method can be used whether the result object is a JavaBean or a Map (or a primitive wrapper, but that would likely be useless).

Because we’re using Log4J, we’ll need to ensure its JAR file is available to our application. Remember, Commons Logging is an abstraction API. It is not meant to provide its implementations. So to use Log4J, you need to add the JAR file to your application classpath. You can download Log4J from the URL above or use the JAR included with the iBATIS Data Mapper framework. For web or enterprise applications you can add the "log4j.jar" to your WEB-INF/lib directory, or for a standalone application you can simply add it to the JVM - classpath startup parameter.

Configuring Log4J is simple. Like Commons Logging, you’ll again be adding a properties file to your classpath root (i.e. not in a package). This time the file is called log4j.properties and it looks like the following:

1  # Global logging configuration
2  log4j.rootLogger=ERROR, stdout
3  # SqlMap logging configuration...
4  #log4j.logger.com.ibatis=DEBUG
5  #log4j.logger.com.ibatis.common.jdbc.SimpleDataSource=DEBUG
6  #log4j.logger.com.ibatis.common.jdbc.ScriptRunner=DEBUG
7  #log4j.logger.com.ibatis.sqlmap.engine.impl.SqlMapClientDelegate=DEBUG
8  #log4j.logger.java.sql.Connection=DEBUG
9  #log4j.logger.java.sql.Statement=DEBUG
10 #log4j.logger.java.sql.PreparedStatement=DEBUG
11 #log4j.logger.java.sql.ResultSet=DEBUG
12 # Console output...
13 log4j.appender.stdout=org.apache.log4j.ConsoleAppender
14 log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
15 log4j.appender.stdout.layout.ConversionPattern=%5p [%t] - %m%n

The above file is the minimal configuration that will cause logging to only report on errors. Line 2 of the file is what is shown to be configuring Log4J to only report errors to the stdout appender. An appender is a component that collects output (e.g. console, file, database etc.). To maximize the level of reporting, we could change line 2 as follows:

log4j.rootLogger=DEBUG, stdout

By changing line 2 as above, Log4J will now report on all logged events to the ‘stdout’ appender (console). If you want to tune the logging at a finer level, you can configure each class that logs to the system using the ‘Data Mapper logging configuration’ section of the file above (commented out in lines 5 through 12 above). So if we wanted to log PreparedStatement activity (SQL statements) to the console at the DEBUG level, we would simply change line 11 to the following (notice it’s not #commented out anymore):

log4j.logger.java.sql.PreparedStatement=DEBUG

The remaining configuration in the log4j.properties file is used to configure the appenders, which is beyond the scope of this document. However, you can find more information at the Log4J website (URL above). Or, you could simply play around with it to see what effects the different configuration options have.