Mybatis

MyBatis configuration is made of 3 beans 

• org.mybatis.spring.SqlSessionFactoryBean

  FactoryBean that creates a 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 Objects

  MyBatis environment has several object types namely

  1. Entities/Models
     They are in the package org.opensrp.domain.postgres. These are Java classes representation of the database tables. A model maps to one database table and has 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/logic 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. MyBatis Example classes
     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 one concentrates on writing custom logic. They can be used to construct complex queries in the dao. They cannot be used to query the database directly without a mapper, thus they are used in the context of a mapper
  5. TypeHandler
     They are in the package org.opensrp.repository.postgres.handler. They handle the two way translation/conversion between database datatypes and java datatypes during the execution of database queries .
  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 by 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 invokes the sql statement in the mapper xml in the database configured 
4. MyBatis returns a model or list of models to the interfaces which returns the reponse to calling dao/repository

Note:

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 model object is defined as the return type a single object will be returned or null if the underlying database table returns 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 the rows returned after fetching and then returns the filtered list . OpenSRP uses customMappers to define a seachMany method that passes a row limit parameter to control the number of rows fetched on the database and and offset parameter that controls the offset/starting position to query the data. 

You can use example classes 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

Refer to the documentation at  http://www.mybatis.org/mybatis-3.