Monday, December 12, 2005

iBATIS, DAO, Spring and Middlegen code generation

I've previously written a small del.icio.us clone using Hibernate where some of the code was generated using Middlegen. I like the Hibernate approach but it sometimes feels like a heavyweight approach for a simple application (e.g. sledgehammer to crack a walnut).

I have looked at using Spring and the JDBCTemplate looks like a nice way to handle JDBC access without the need to write all that tedious connection code and exception handling stuff. However, unless I go to great effort I'd probably end up with SQL hard coded in my Java classes and I'd need to do all the resultset to object mapping by hand.

I discovered iBATIS recently almost by accident. iBATIS used to be a commercial product but has now been donated to the Apache Foundation. iBATIS is an O/RM-like approach. Clinton Begin, iBATIS creator, says that "iBATIS is not an O/RM. It does not bind classes to tables, nor does is it limited to OO languages and/or relational databases" and elsewhere iBATIS has been described as a convenience framework for JDBC. iBATIS does not offer some of the benefits that Hibernate does (database independence etc) but on the plus side it is very simple to use and even more so if you choose to use Spring's SqlMapClientTemplate.

I came across iBATIS as it was one of the technologies included as an example Jetspeed2 Portlet. iBATIS distribute JPetstore as an example of using Struts, DAO layer and iBATIS together. The Jetspeed2 version of the application uses the Struts bridge to convert the application into a portlet. The idea behind iBATIS is that all your SQL is kept in an external XML SQLMapping file. iBATIS then maps the returned result into a domain object.

Spring includes support for iBATIS interaction. I spent a little time studying the iBATIS JPetstore example and a version of this which actually uses Spring is further explored in Bruce Tate and Justin Gehtland's book Better, Faster, Lighter Java (excerpts of which can be found on the OnJava web site [Demonstrating Spring's Finesse, Persistence in Spring]).

There is a Perl script which can be used to generate java-beans sources and sql-map config files generator. There is now also some iBATIS support inside Middlegen tool for the generation of iBATIS SQLMapping XML files and associated domain object POJOs. Looking at the DAO approach used in Better, Faster, Lighter Java and similarly using Spring's iBATIS support it seemed very possible to me that I could extend the existing iBATIS Middlegen Plugin so that it would generate the required DAO classes to implement the architecture shown in the diagram below.

The default iBATIS Middlegen plugin generates the CRUD actions needed for the SQL mapping and creates the definition of each domain object. It was relatively straight forward to modify these basic examples to create DAO interfaces, DAO implementation (using Spring SQLMapClientTemplates) and also a Façade interface / implementation.

To do this I had to learn a to use the Velocity Templating Language (VTL) to extend Middlegen code but since I have some shell scripting and XSL experience this is not that daunting a task.

Using the default Middlegen iBATIS plugin you can create an SQL Mapping file and domain object POJO class. For this example I have created a single Table called ITEM with one column containing an ITEM_ID. The generated iBATIS XML SQLMapping file is shown below. Notice how this contains the full range of CRUD operations.


<?xml version='1.0'?>
<!DOCTYPE sqlMap PUBLIC "-//iBATIS.com//DTD SQL Map 2.0//EN"
"http://www.ibatis.com/dtd/sql-map-2.dtd"
>

<!-- WARNING: This is an autogenerated file -->

<sqlMap>
<typeAlias alias="Item" type="mypackage.domain.Item"/>
<!--
<cacheModel id="$table.destinationClassName-cache" type="MEMORY">
<flushInterval hours="24"/>
<flushOnExecute statement="insertItem"/>
<flushOnExecute statement="updateItem"/>
<flushOnExecute statement="deleteItem"/>
<property name="reference-type" value="WEAK" />
</cacheModel>
-->

<resultMap class="Item" id="Item-result" >
<result
property="itemId"
javaType="java.lang.String"
column="ITEM_ID"
/>
</resultMap>

<select id="getItem"
resultClass="Item"
parameterClass="Item"
resultMap="Item-result" >
<![CDATA[
select
ITEM_ID
from
ITEM
where
ITEM_ID = #itemId#

]]>
</select>

<update id="updateItem"
parameterClass="Item" >
<![CDATA[
update
ITEM
set

where
ITEM_ID = #itemId#
]]>
</update>

<insert id="insertItem"
parameterClass="Item" >
<![CDATA[
insert into ITEM
(ITEM_ID )
values
(#itemId# )
]]
>
</insert>

<delete id="deleteItem" parameterClass="Item" >
<![CDATA[
delete from ITEM where ITEM_ID = #itemId#
]]>
</delete>

</sqlMap>

The default Middlegen iBATIS plugin will generate corresponding transparent domain object class (business objects), one per table. The domain should capture the relationships between the various system entities much as an Entity Relationship Diagram does and this is why we can generate this from the database directly. The generated classes are a "bare" platform into which you should expect to add more sophisticated behaviours. These really should contain behaviour as you'll probably recall from object oriented programming first principles a class should contain data and methods. Obviously the precise behaviour cannot be generically generated as it is likely to be domain object specific. If you do not add additional behaviour at this point you may be guilty of using an Anemic Domain Model.


package mypackage.domain;

import java.io.Serializable;
import java.sql.Timestamp;
import java.math.BigDecimal;
import org.apache.commons.lang.builder.HashCodeBuilder;

/**
* @author <a href="http://boss.bekk.no/boss/middlegen/">Middlegen</a>
*
*/

public class Item implements Serializable
{
// fields
/**
* The itemId field
*/

private java.lang.String itemId;

// getters/setters
/**
* Returns the itemId
*
* @return the itemId
*/

public java.lang.String getItemId()
{
return itemId;
}

/**
* Sets the itemId
*
* @param newItemId the new itemId
*/

public void setItemId(java.lang.String newItemId) {
this.itemId = newItemId;
}


/**
* Implementation of equals method.
*/

public boolean equals(Object object)
{
if (this == object)
{
return true;
}
if (!(object instanceof Item))
{
return false;
}
Item other = (Item)object;
return
this.itemId.equals(other.itemId); }

/**
* Implementation of hashCode method that supports the
* equals-hashCode contract.
*/

/*
public int hashCode()
{
return
hashCode(this.itemId); }
*/

/**
* Implementation of hashCode method that supports the
* equals-hashCode contract.
*/

public int hashCode()
{
// TODO generate random number following the contract
HashCodeBuilder builder = new HashCodeBuilder(17,37);
return builder
.append(itemId)
.toHashCode();
}

/**
* Implementation of toString that outputs this object id's
* primary key values.
*/

public String toString()
{
StringBuffer buffer = new StringBuffer();
buffer.append("itemId=");
buffer.append(this.itemId);
return buffer.toString();
/*
return
this.itemId; */

}
}

I created Middlegen iBATIS Plugin extensions to generate the next few classes. This is an example of a generated DAO interface class. There will be one DAO interface class per domain object (i.e. one per table).


package mypackage.iface;

import mypackage.domain.Item;

public interface ItemDao
{
public Item getItem( java.lang.String itemId);
public void insertItem(Item item);
public void updateItem(Item item);
public void deleteItem(Item item);

}

This is DAO implementation of the above interface using Spring's SqlMappingClientTemplate, again there will be one of these per domain object (i.e. one per table):


package mypackage.sqlmapdao;

import mypackage.domain.Item;
import mypackage.iface.ItemDao;
import org.springframework.orm.ibatis.support.SqlMapClientDaoSupport;

public class SqlMapItemDao extends SqlMapClientDaoSupport implements ItemDao
{
public Item getItem(java.lang.String itemId){
Item item = new Item();
item.setItemId(itemId);
return (Item) getSqlMapClientTemplate().queryForObject("getItem",item);
}

public void insertItem(Item item) {
getSqlMapClientTemplate().insert("insertItem",item);
}

public void updateItem(Item item){
getSqlMapClientTemplate().update("updateItem",item);
}

public void deleteItem(Item item){
getSqlMapClientTemplate().delete("deleteItem",item);
}

}

In this most simple example the usage of a façade seems fairly pointless. The idea comes into it's own when you start to have more than one table of data represented in your domain. A façade collects all the publicly accessible DAO methods into a single interface. It also serves as an attachment point for other services, such as transaction support.In writing a Struts Action you would query against the façade rather than trying to obtain a DAO method directly.There will be only one instance of the façade layer interface and implementation it will likely contain references to all the DAO interfaces for every publicly accessible domain object.

See Persistence in Spring for more details about why we might want to generate a façade interface and implementation.

Façade interface:


package mypackage.domain.logic;

import mypackage.domain.Item;

public interface Façade
{

public Item getItem( java.lang.String itemId);
public void insertItem(Item item);
public void updateItem(Item item);
public void deleteItem(Item item);

}

Façade implementation:


package mypackage.domain.logic;

import mypackage.iface.ItemDao;
import mypackage.domain.Item;

public class FaçadeImpl implements Façade
{

private ItemDao itemDao;

//-------------------------------------------------------------------------
// Setter methods for dependency injection
//-------------------------------------------------------------------------


public void setItemDao(ItemDao itemDao) {
this.itemDao = itemDao;
}

//-------------------------------------------------------------------------
// Operation methods, implementing the Façade interface
//-------------------------------------------------------------------------



public Item getItem( java.lang.String itemId){
return this.itemDao.getItem(itemId);
}

public void insertItem(Item item){
this.itemDao.insertItem(item);
}

public void updateItem(Item item){
this.itemDao.updateItem(item);
}

public void deleteItem(Item item){
this.itemDao.deleteItem(item);
}

}

As you can see from the above examples, I have now extended the Middlegen iBATIS Plugin to create a simple version of the entire Spring based DAO layer code. I'm currently looking into generating more complex domain relationship behaviour but this has so far only been slightly hampered by my limited VTL scripting skills but it is certainly possible to do this with Middlegen as the Hibernate and EJB plugins produce something similar. I am hoping to better capture one-to-many relationships in the domain model so that I can detect these and generate appropriate SQLMapping and Java code. For example if we added a new domain object called CATEGORY it might contain many ITEMS and could therefore our Category domain object might contain:


private List items;

public List getItems()
{
return items;
}

public void setItems(List items)
{
this.items = items;
}

The following could be generated inside an appropriate XML SQL Mapping file:


<select
id="getItemsByCategoryCode"
parameterClass="java.lang.String"
resultMap="itemMap">
select
item_id,
item_name,
category_code
from
items
where
category_code = #value#;
</select>

* where itemMap is already defined someplace.

The Spring DAO implementation of this could then look something like:


public List findItems(Category category){
getSqlMapClientTemplate().queryForList("getItemsByCategoryCode",category);
}

public void createCategoryWithItems(Category category){
getSqlMapClientTemplate().execute(new SqlMapClientCallback() {
public Object doInSqlMapClient(SqlMapExecutor executor) throws SQLException {
executor.startBatch();
for (Iterator it=category.getItems().iterator(); it.hasNext(); ) {
Item item = (Item) it.next();
executor.insert("insertItem", item);
}
executor.executeBatch();
return null;
}
});
}

Nothing that I have generated so far is especially complicated but it is still nice to be able to generate basic business objects and a working DAO layer without much effort. I'd be happy to share the Velocity templates that I used to create these classes.

13 comments:

Mark McLaren said...

hello, i think you should take a look at http://ibatis.apache.org/abator.html
Note: Comment imported. Original by Olivier Ziller website: http://olivierziller.blogspot.com at 2005-12-13 08:07

Mark McLaren said...

Abator looks cool but is there anyway it could be run from Ant as I find Eclipse awkward to use. My preference is to use Netbeans.
Note: Comment imported. Original by markmc website: http://content.mark-mclaren.info/ at 2005-12-13 08:30

Mark McLaren said...

"The core code generation functionality of Abator does not require Eclipse, and can be run as a standalone JAR - I'll post some instructions about how to do that if anyone is interested."



i tkink you could ask this question on the ibatis list.
Note: Comment imported. Original by Olivier Ziller at 2005-12-13 21:30

Mark McLaren said...

Hi Olivier,



I downloaded Abator yesterday and had a little look at. I took a look at the source code and very impressive it was too but from what I have seen so far it did not look very extensible.





Compare iBATIS Abator code that generates the domain bean:





JavaModelGeneratorDefaultImpl.java



with the Middlegen velocity template that does the same job:



iBatis-bean.vm



Middlegen is a free general-purpose database-driven code generation engine which uses Velocity templating. It is used in communities other than iBATIS (including Hibernate) and so therefore has the advantage that it is a little more widely used and tested.



Say for example I wanted to add something to all my insertXXX DAO methods, using Abator I would have to modify the Java generation source code and recompile it. If I wanted to make a change to a particular generated method using Middlegen I would only need to modify a Velocity template file, which is very easy to do.



I'm sure the code that Abator produces is probably a little superior to what the iBATIS Middlegen plugin currently produces but this is easily remedied. I will certainly take a look at the source code that Abator produces once I manage to get it working!



For the reason that it is easily configurable, extensible and more widely used, I would expect in the future I would still choose to use Middlegen rather than iBATIS Abator to generate my iBATIS related code.


Note: Comment imported. Original by markmc website: http://content.mark-mclaren.info/ at 2005-12-14 09:28

Mark McLaren said...

First, i have to say thanks for this article.

Second, i'm trying to implement ibatis, spring and JSF. Not so hard until now but i have a special requirement, i need to handle the transaction in a EXTERNAL way, like the documentation of iBatis suggest. My quesyion is, Do you know how can i implement iBatis and Spring handling by my own the transaction??. DO i need to configurate something else in the applicationContext.xml or dataAccessContext-xxx.xml?.

Anyway, thanks fro your help
Note: Comment imported. Original by Othon Sanchez at 2005-12-19 23:05

Mark McLaren said...

Hi Othon,



I started replying to this and it got too large to be a comment, so I've added a new blog entry called Transaction Management with iBATIS and Spring for you.





Hope it helps,



Mark
Note: Comment imported. Original by markmc website: http://content.mark-mclaren.info/ at 2005-12-20 11:04

Mark McLaren said...

Thanks for the article Mark, very informative. I was about to use Abator but after some research agree with your conclusions and am also going to go with middlegen - customisation of the generated code is a crucial factor and easier with middlegen at present as you say. Would be very interested in seeing the velocity templates and any java modifications you made to the middlegen ibatis plugin, as I'm about to embark on the same dao-generating exercise. Thanks, John
Note: Comment imported. Original by John Boyes website: http://www.edinburghwebservices.co.uk at 2006-01-07 10:37

Mark McLaren said...

Hi John,



I have extended Takashi Okamoto's Middlegen/iBATIS plugin modifications. (I'm not actually sure how it differs from the iBATIS plugin currently in the Middlegen CVS).



The following "distribution" contains iBATIS plugin source plus my modifications (I make no claims about production worthiness) and the sample iBATIS/Middlegen application. I have modified the sample application to additionally use Apache Derby and Spring. I've also added one or two extra ant targets so the process would now be:





ant create-tables

ant middlegen

ant compile

ant run



middlegen-2.1.zip [8.2Mb]


Note: Comment imported. Original by markmc website: http://content.mark-mclaren.info/ at 2006-01-09 10:04

Mark McLaren said...

Hi very informative but i want to return the primary key of the table during insertion .How is it possible with this arrangement ?
Note: Comment imported. Original by Krishnendra Nandi at 2006-01-30 12:31

Mark McLaren said...

Hi



I have not covered that here. I had the same query, the precise details depend on what database you are using. I am using Apache Derby.For details of how to do this with Apache Derby see my comment on the following iBATIS wiki page:

How do I use an insert statement? (other DBs are also covered there).


Note: Comment imported. Original by markmc website: http://content.mark-mclaren.info/ at 2006-01-30 13:01

Mark McLaren said...

Nice to meet you, Mark.



I want to read a source code of your Middlegen/iBATIS plugin. But, I was not able to download it because it's a broken link.

Would you revise a broken link?



Please thanking you in advance.


Note: Comment imported. Original by Youhei Nitta at 2006-04-21 10:18

Mark McLaren said...

Sorry about that, somebody moved my file space without telling me. You should now be able to get it here:



middlegen-2.1.zip


Note: Comment imported. Original by markmc website: http://content.mark-mclaren.info/ at 2006-04-21 10:44

Mark McLaren said...

Hi,



The generated ibatis sql map files do not contain selectKey elements for update elements of tables with identify columns. I think I have to modify the plugin to work with identity columns as well or it won't work with tables with identity columns, am I right!?
Note: Comment imported. Original by Behrang website: http://my.opera.com/behrangsa at 2006-11-25 12:16