Mybatis

MyBatis configuration is made of 3 beans 

• org.mybatis.spring.SqlSessionFactoryBean

  FactoryBean that creates an MyBatis SqlSessionFactory. This sets up a shared MyBatis SqlSessionFactory in a Spring application context; the SqlSessionFactory can then be passed to MyBatis-based DAOs via dependency injection.

  This bean registers the data source to be managed, the package for the entity(models), and location for mybatis mapper xml files(we use a wild card in "classpath*:org/opensrp/repository/postgres/mapper/**/*.xml" to load all the MyBatis mapper XML files in the  org.opensrp.repository.postgres.mapper package and its sub-packages from the classpath)
              

• org.mybatis.spring.SqlSessionTemplate 

  Thread safe, Spring managed, SqlSession that works with Spring transaction management to ensure that the actual SqlSession used is the one associated with the current Spring transaction. In addition, it manages the session life-cycle, including closing, committing or rolling back the session as necessary based on the Spring transaction configuration.

  The template needs a SqlSessionFactory to create SqlSessions, passed as a constructor argument. 

  
  We register the SqlSessionFactoryBean above to this bean as the first argument

• org.mybatis.spring.mapper.MapperScannerConfigurer

  BeanDefinitionRegistryPostProcessor that searches recursively starting from a base package for interfaces and registers them as MapperFactoryBean. Note that only interfaces with at least one method will be registered; concrete classes will be ignored.

  The basePackage property can contain more than one package name, separated by either commas or semicolons. We pass the two packages of the mapper interfaces; auto-generated interfaces and the custom interfaces.

  MyBatis Artifacts

  MyBatis has several artifacts namely

  1. Entities/Models
     They are in the package org.opensrp.domain.postgres. These are Java classes representation of the database tables. They have a property for each column in the equivalent database table .
  2. Mapper xml
     They are in the package org.opensrp.repository.postgres.mapper.custom for the generated Mappers and in org.opensrp.repository.postgres.mapper.custom.xml for the custom mappers. They contain the actual statements that are needed for each database operation. The custom interfaces extend the generated interfaces to define custom logic. They are not overwitten by MyBatis generator and thus any custom queries should be written in the custom mappers. 
  3. Mapper Interfaces
     They are in the package org.opensrp.repository.postgres.mapper for the generated Mappers and in org.opensrp.repository.postgres.mapper.custom for the custom mappers. They are java interfaces. The main function is to define a contracts/bridge that binds the Mapper xml and Java runtime. One uses these interfaces to invoke the sql statmemnts in mapper xml. The custom interfaces extend the generated interfaces to define custom logic. They are not overwitten by MyBatis generator and thus any custom queries should be written in the custom mappers. Its advisable to autowire the custom interfaces in the repositories(dao) so that one is able to access both generated and custom code
  4. Example
     They are in the package org.opensrp.domain.postgres. They are generated by MyBatis Generator. They are used to define simple CRUD operations so that concentates on writing custom logic. 
  5. TypeHandler
     They are in the package org.opensrp.repository.postgres.handler. They handle the transalation between database datatypes and java datatypes.
  6. Migration scripts
     These are in the folder opensrp/assets/migrations/scripts. The scripts in the folder are used my MyBatis Migrations to create and manage versioning of database objects
  7. Generator Configuration File
     This is a single file in the path opensrp/assets/migrations/genarator/generatorConfig.xml. Its used to define the configurations used  MyBatis Generator when generating various MyBatis arifacts e.g Models, Mapper interfaces and xml and examples. When you want to change only one domain(database table) only uncomment only that table so that only the objects for that domain are generated.

Execution sequence at runtime :

1. The Repositories/Dao objects autowire the custom or generated Mapper Interface. 
2. They repositories invoke a method on the mapper interface. This is a synchronous and waits for a response before returning from method call.
3. MyBatis invoke the sql statement in the mapper xml in the database configured
4. MyBatis returns the model or list of models to the interfaces which returns the reponse to calling class

Important Notes:

The return type is the determined by the Mapper interface. If you define a mapper to return a list. MyBatis will return a list of the models or an empty list if the underlying query return no records. If a single object is defined a single object will be returned or null if the underlying database table return no record.

Mybatis has a rowbounds plugin for controlling the number of records returned. OpenSRP does not use the plugin as if fetches all records and then limits in memory before returning the list of models. OpenSRP uses the CustomMapper to define a seachMany method that passes the row limit to fetch and the offset/starting position to query the data. 

You can use example to construct complex queries or you can implement custom methods using the mapper interfaces and the mapper xml where you can define the actual sql statements

You use the documentation at  http://www.mybatis.org/mybatis-3 for further configuration if need be