The Core components

The com.google.code.ibaguice.core package prodives a set of reusable simple Guice Provider and Module that alleviate users the task to create iBatis objects

To use the core iBaGuice module add the following dependency to your pom.xml:

<dependencies>
    ...
    <dependency>
        <groupId>com.google.code.ibaguice</groupId>
        <artifactId>ibaguice-core</artifactId>
        <version>XX.XX</version>
    </dependency>
    ...
</dependencies>

Building SqlSessionFactory from XML

The class XMLSqlSessionFactoryProvider builds for you the iBatis org.apache.ibatis.session.SqlSessionFactory simply by reading the configuration classpath resource. Users can use that provider in two ways:

  • specifying in the com.google.inject.name.Named property called ibatis.classpathResource, then in your module the provider mapping looks like:
    binder.bindConstant()
      .annotatedWith(com.google.inject.name.Names.named("ibatis.classpathResource"))
      .to("com/acme/ibatis-config.xml"); // feel free to get this value with the way you prefeer
...
binder.bind(org.apache.ibatis.session.SqlSessionFactory.class)
      .toProvider(XMLSqlSessionFactoryProvider.class)
      .asEagerSingleton();
  • or invoking directly the provider instantiation: looks like:
    binder.bind(SqlSessionFactory.class)
      .toProvider(new XMLSqlSessionFactoryProvider("com/acme/ibatis-config.xml"));

Building SqlSessionFactory from Java

Confronting to the previous approach, this is the way we prefer to configure the org.apache.ibatis.session.SqlSessionFactory since we can play a little with iBatis settings and easily integrate 3rd part technologies we need.

The core component of this aproach is the com.google.code.ibaguice.core.core.SqlSessionFactoryModule that's able to create, through a serie of required and optional com.google.inject.Provider, the org.apache.ibatis.session.SqlSessionFactory.

The best way to start is just adding the module into the com.google.inject.Injector as shown below and explain details step by step:

import com.google.code.ibaguice.core.SqlSessionFactoryModule;
import com.google.inject.Guice;
import com.google.inject.Injector;
import com.google.inject.Provider;
import javax.sql.DataSource;
import org.apache.ibatis.session.SqlSessionFactory;
import org.apache.ibatis.transaction.TransactionFactory;

...

Class<? extends Provider<DataSource>> dataSourceProviderClass = [...];
Class<? extends Provider<TransactionFactory>> txFactoryProviderClass = [...];

Injector injector = Guice.createInjector(
    new SqlSessionFactoryModule(dataSourceProviderClass, txFactoryProviderClass),
    ...
);

SqlSessionFactory sessionFactory = injector.getInstance(SqlSessionFactory.class);

Let's have a look now at required and optional providers.

Required properties

The org.apache.ibatis.mapping.Environment needs to know the environment id, so users have to take care of setting the ibatis.environment.id property as a Guice constant, for example:

binder.bindConstant()
    .annotatedWith(com.google.inject.name.Names.named("ibatis.environment.id"))
    .to("production");

Feel free to read and set it in any way you prefeer, we suggest to put it in a properties file (maybe filtered and set depending on for wich environment you're building the application), but don't forget it otherwise the injection won't work.

Optional properties

If you need to enable the lazy loading in the iBatis org.apache.ibatis.session.Configuration, then bind the named property ibatis.configuration.lazyLoadingEnabled with the required boolean value. By default, if ibatis.configuration.lazyLoadingEnabled is not specified, the property will be ignored and iBatis will take care about proper default lazy loading initialization.

binder.bindConstant()
    .annotatedWith(com.google.inject.name.Names.named("ibatis.configuration.lazyLoadingEnabled"))
    .to(true);

The Data Source provider

This is one of two required providers that has the task to create and provide the javax.sql.DataSource managed by iBatis.

This library comes with some providers that support the iBatis-native Data Sources and two other well known Data Sources, C3P0 and Apache commons-dbcp, but users are free to write their own DataSourceProvider and reference it in the com.google.code.ibaguice.core.SqlSessionFactoryModule.

Please read the Data Source reference to obtain more informations about natively supported providers.

The Transaction Factory Provider

This provider has to serve the iBatis Transaction Manager Factory; the library comes with the native iBatis implementation providers: com.google.code.ibaguice.core.transactionfactory.JdbcTransactionFactoryProvider that provides the iBatis JDBC Transaction Manager Factory, and the com.google.code.ibaguice.core.transactionfactory.ManagedTransactionFactoryProvider, that provides the iBatis user managed Transaction Manager Factory.

Users are free to write their own TransactionFactoryProvider and reference it in the com.google.code.ibaguice.core.SqlSessionFactoryModule.

Configuring aliases

Once users create the com.google.code.ibaguice.core.SqlSessionFactoryModule, it's quite easy plugging optional iBatis components, like aliases: here users can define simple aliases, for example Foo that stands for com.acme.Foo, or custom aliases, for example MyFoo that stands for com.acme.Foo.

We found very useful adding simple aliases because helped us a lot to reduce the errors during our development time; just call:

com.google.code.ibaguice.core.SqlSessionFactoryModule module = [...]
module.addSimpleAliases(com.acme.Foo.class, com.acme.Bar.class, ...);

If you prefeer instead using you own custom aliases, just invoke

com.google.code.ibaguice.core.SqlSessionFactoryModule module = [...]
module.addAlias("MyFoo", com.acme.Foo.class)
module.addAlias("MyBar", com.acme.Bar.class);
...

Configuring Type Handlers

Like users can configure aliases, the can do it the same for type aliases: given my com.acme.Foo type, that has to be hanlded by the type handler com.acme.dao.FooHandler, just invoke

com.google.code.ibaguice.core.SqlSessionFactoryModule module = [...]
module.addTypeHandler(com.acme.Foo.class, com.acme.dao.FooHandler.class);
module.addTypeHandler(com.acme.Bar.class, com.acme.dao.BarHandler.class);
...

and let google-guice creating the handler and bind it to iBatis.

Configuring Interceptor Plugins

Users can easily add their preferred org.apache.ibatis.plugin.Interceptor simply invoking:

com.google.code.ibaguice.core.SqlSessionFactoryModule module = [...]
module.setInterceptorsClasses(com.acme.dao.FooInterceptor.class, com.acme.dao.BarInterceptor.class, ...);

Configuring Mappers

Users can add the mapper classes adding them to the module, iBaGuice will take care to inject them accurately:

com.google.code.ibaguice.core.SqlSessionFactoryModule module = [...]
module.setMapperClasses(com.acme.dao.FooMapper.class, com.acme.dao.BarMapper.class, ...);

Configuring the Object Factory

Just simply define the com.google.inject.Provider for your own org.apache.ibatis.reflection.factory.ObjectFactory and communicate it to the module and let google-guice create it:

com.google.code.ibaguice.core.SqlSessionFactoryModule module = [...]
module.setObjectFactoryProviderClass(com.acme.MyObjectFactoryProvider.class);