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.

@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.

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.