MyBatis (formerly called iBatis) – Examples and Hints using SELECT, INSERT and UPDATE Annotations

MyBatis (http://www.mybatis.org/) is a lightweight persistence framework for Java and .NET. This blog entry addresses the Java side. MyBatis is an alternative positioned somewhere between plain JDBC and ORM frameworks (e.g. EclipseLink or Hibernate). MyBatis usually uses XML, but it also supports annotations since version 3.

The documentation (http://mybatis.googlecode.com/svn/trunk/doc/en/MyBatis-3-User-Guide.pdf) is very detailed for XML, but lacks of annotation examples. Just the Annotations itself are described, but no examples how to use them. I could not find any good and easy examples anywhere, so I will describe some very basic examples for SELECT, INSERT and UPDATE statements by implementing a Data Access Object (DAO) using MyBatis.
These examples are a good starting point to create more complex MyBatis queries using a DAO. You can find the full source code  at the end of this blog.

SQL – Create Tables

I use a very simple table with two attributes. The name of the table is “simple_information”. The primary key is a Integer and may not be null (info_id). The only real data is  a character and may also not be null (info_content). That is enough “complexity” to learn the usage of MyBatis annotations.

The Java class “SimpleInformationEntity” is a POJO which contains these two attributes.

@SELECT-Statement

The @Select annotation is very easy to use, if you want to use exactly one paramter. If you need more than one paramter, use the @Param annotation (which is described below at the update example).
You do not have to map the found information to a SimpleInformationEntity object, as you would have to do with a JDBC ResultSet. The magic of the framework does this for you.

final String GET_INFO =
“SELECT * FROM simple_information WHERE info_id = #{info_id}”;

@Select(GET_INFO)
public SimpleInformationEntity getSimpleInformationById(int info_id) throws Exception;

@INSERT-Statement

You can use the object (which you want to be persist) as parameter. You do not have to use several parameters for each attribute of the object. The magic of the framework does this for you.

final String PERSIST_INFO =
“INSERT INTO simple_information(info_id, info_content) VALUES (#{infoId}, #{infoContent})”;

@Insert(PERSIST_INFO)
public int persistInformation(SimpleInformationEntity simpleInfo) throws Exception;

@UPDATE-Statement

You cannot use more than one parameter within a method. If you want to understand why, look at some MyBatis XML examples in the documenation: There you use the attribute “parameterType”, which must be exactly one “parameter”! So you will get a (strange) exception, if you use two or more parameters. Instead you have to use the @Param annotation, if you need more than one parameter.

final String UPDATE_INFO =
“UPDATE simple_information SET info_content = #{newInfo} WHERE info_id = #{infoId}”;

@Update(UPDATE_INFO)
public int updateInformation(@Param(“infoId”) int info_id, @Param(“newInfo”) String new_content) throws Exception;

Configuration

You have to add your MyBatis-Interface for the Mapper to the SQLSessionFactory:

sqlSessionFactory.getConfiguration().addMapper(InfoMapper.class);

Some Hints for developing with MyBatis

The following means helped me a lot to use MyBatis annotations despite the lack of documentation about using annotations:
– MyBatis is open source! So add the sources to your build path and use the debugging function of your IDE to enter the MyBatis source code while executing some queries. You will see what MyBatis expects as input and how it is processed.
– Read the documentation about using MyBatis XML. This does not really make any sense you think? It does! The processing deep inside MyBatis does not change if you use annotations instead of XML. It is just another way to develop persistence queries.
E.g. if you know that a XML select query may just use exactly one parameterType-attribute, then you know that you may just use one parameter in an annotation-based method too! If you need more parameters, you have to use the @Param annotation.
– If you get any strange exception that does not make any sense, then clean and re-compile your project. This often helps, because as with other persistence frameworks such as Hibernate, the bytecode enhancement sometimes confuses your IDE.

Conclusion: @MyBatis-Team: Improve and extend the documentation instead of improving the framework itself!

MyBatis is a nice lightweigt persistence framework. But the documentation is not enough detailed. Some important information is completely missing. Especially, if you are a newbie to MyBatis / iBatis, it is very tough to develop with MyBatis using annotations instead of XML.
Besides the usage of annotations, another good example for missing documentation is how to configure transactions in MyBatis by using JNDI and a J2EE / JEE Application server. You have to use google to find out, and if you are lucky you will find a mailing list or blog entry describing your problem. If not, you have to try it out.
The missing documentation makes MyBatis much more tough than it actually is. So in the next months, the MyBatis team should improve and extend the documentation instead of improving the framework itself…

Best regards,

Kai Wähner (Twitter: @KaiWaehner)

Appendix: Source Code

Here you see all the necessary source code, also including a MyBatis Connection Factory, which reads the configuration data from a XML file.

############################################################################

Connection Factory (using a static initializer)

############################################################################

import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.Reader;

import org.apache.ibatis.session.SqlSessionFactory;
import org.apache.ibatis.session.SqlSessionFactoryBuilder;

import de.waehner.kai.persistence.InfoDAO.InfoMapper;

public class MyBatisConnectionFactory {

private static SqlSessionFactory sqlSessionFactory;

static {

Reader reader = null;

try {

InputStream in = MyBatisConnectionFactory.class.getResourceAsStream(“myBatisConfiguration.xml”);

reader = new InputStreamReader(in);

if (sqlSessionFactory == null) {
sqlSessionFactory = new SqlSessionFactoryBuilder().build(reader);

sqlSessionFactory.getConfiguration().addMapper(InfoMapper.class);

}

in.close();

}

catch (FileNotFoundException fileNotFoundException) {
fileNotFoundException.printStackTrace();
}

catch (IOException iOException) {
iOException.printStackTrace();
}
}

public static SqlSessionFactory getSqlSessionFactory() {

return sqlSessionFactory;
}

}

############################################################################

Data Acces Object (including the MyBatis-Mapper as inner Class)

############################################################################

import org.apache.ibatis.annotations.Insert;
import org.apache.ibatis.annotations.Param;
import org.apache.ibatis.annotations.Select;
import org.apache.ibatis.annotations.Update;
import org.apache.ibatis.session.SqlSession;
import org.apache.ibatis.session.SqlSessionFactory;

public class InfoDAO {

public interface InfoMapper {

final String GET_INFO =
“SELECT * FROM simple_information WHERE info_id = #{info_id}”;

@Select(GET_INFO)
public SimpleInformationEntity getSimpleInformationById(int info_id) throws Exception;

final String PERSIST_INFO =
“INSERT INTO simple_information(info_id, info_content) VALUES (#{infoId}, #{infoContent})”;

@Insert(PERSIST_INFO)
public int persistInformation(SimpleInformationEntity simpleInfo) throws Exception;

final String UPDATE_INFO =
“UPDATE simple_information SET info_content = #{newInfo} WHERE info_id = #{infoId}”;

@Update(UPDATE_INFO)
public int updateInformation(@Param(“infoId”) int info_id, @Param(“newInfo”) String new_content) throws Exception;

}

public SimpleInformationEntity getSingleAlarm(int info_id) throws Exception {

SqlSessionFactory sqlSessionFactory = MyBatisConnectionFactory.getSqlSessionFactory();
SqlSession session = sqlSessionFactory.openSession();

try {

InfoMapper mapper = session.getMapper(InfoMapper.class);
SimpleInformationEntity simpleInfo = mapper.getSimpleInformationById(info_id);

return simpleInfo;

} finally {
session.close();
}
}

public int persistInformation(SimpleInformationEntity simpleInfo) throws Exception {

SqlSessionFactory sqlSessionFactory = MyBatisConnectionFactory.getSqlSessionFactory();
SqlSession session = sqlSessionFactory.openSession();

try {

InfoMapper mapper = session.getMapper(InfoMapper.class);
int answer = mapper.persistInformation(simpleInfo);

return answer;

} finally {
session.close();
}
}

public int updateInformation(int info_id, String new_content) throws Exception {

SqlSessionFactory sqlSessionFactory = MyBatisConnectionFactory.getSqlSessionFactory();
SqlSession session = sqlSessionFactory.openSession();

try {

InfoMapper mapper = session.getMapper(InfoMapper.class);
int answer = mapper.updateInformation(info_id, new_content);

return answer;

} finally {
session.close();
}
}
}

############################################################################

SimpleInformation Entity (a simple POJO)

############################################################################

import java.io.Serializable;

public class SimpleInformationEntity implements Serializable{

private static final long serialVersionUID = -821826330941829539L;

private int infoId;

private String infoContent;

public int getInfoId() {
return infoId;
}

public void setInfoId(int infoId) {
this.infoId = infoId;
}

public String getInfoContent() {
return infoContent;
}

public void setInfoContent(String infoContent) {
this.infoContent = infoContent;
}
}