Implementing Ibator Plugins

Ibator plugins can be used to modify or add to the objects that are generated by Ibator. Plugins must implement the interface org.apache.ibatis.ibator.api.IbatorPlugin. The plugin interface contains many methods that Ibator calls in different phases of the code generation process. Implementing the entire interface is generally not needed for any particular plugin. Therefore, most plugins should extend the adapter class org.apache.ibatis.ibator.api.IbatorPluginAdapter. The adapter class provides basic plugin support, and implements no-operation methods for most of the interface methods (similar to Swing adapter classes).

Ibator supplies several plugins (all are in the package org.apache.ibatis.ibator.plugins). The supplied plugins demonstrate different types of tasks that can be accomplished with Ibator plugins. Source code for the plugins is available with the Ibator downloads, or can be viewed online here.

Plugin Lifecycle

Plugins have a lifecycle. Plugins are created during the initialization of the code generation process and are called, in order, in different phases of the process. The following list shows the basic lifecycle of a plugin:

1. Plugin created through the default constructor
2. setIbatorContext method called
3. setProperties method called
4. validate method called. If this method returns false, then no further methods in the plugin will be called
5. For each table in the configuration:
   1. initialized method called
   2. DAO Methods:^1,2
      1. daoXXXMethodGenerated(Method, TopLevelClass, IntrospectedTable) - these methods are called as each method of the DAO implementation is generated.
      2. daoImplementationGenerated(TopLevelClass, IntrospectedTable) method called
      3. daoXXXMethodGenerated(Method, Interface, IntrospectedTable) - these methods are called as each method of the DAO interface is generated.
      4. daoImplementationGenerated(Interface, IntrospectedTable) method called
   3. Model Methods:¹
      1. modelFieldGenerated, modelGetterMethodGenerated, modelSetterMethodGenerated for each field in the class
      2. modelExampleClassGenerated(TopLevelClass, IntrospectedTable)
      3. modelPrimaryKeyClassGenerated(TopLevelClass, IntrospectedTable)
      4. modelBaseRecordClassGenerated(TopLevelClass, IntrospectedTable)
      5. modelRecordWithBLOBsClassGenerated(TopLevelClass, IntrospectedTable)
   4. SQL Map Methods:¹
      1. sqlMapXXXElementGenerated(XmlElement, IntrospectedTable) - these methods are called as each element of the SQL map is generated
      2. sqlMapDocumentGenerated(Document, IntrospectedTable)
      3. sqlMapDocument(GeneratedXmlFile, IntrospectedTable)
   5. contextGenerateAdditionalJavaFiles(IntrospectedTable) method called
   6. contextGenerateAdditionalXmlFiles(IntrospectedTable) method called
6. contextGenerateAdditionalJavaFiles() method called
7. contextGenerateAdditionalXmlFiles() method called

Notes:
¹ - These methods will be called by the Ibator supplied code generators. If you supply a custom code generator, then these methods will only be called if the custom code generator calls them.
² - The DAO methods will only be called is a DAO generator is configured.

Coding Plugins

The best way to implement a plugin is to extend the org.apache.ibatis.ibator.api.IbatorPluginAdapter class and override only the specific methods you need in your plugin.

Methods in the plugin interface can be used to modify code generated by Ibator, or to add addtional generated code. Examples of things that can be accomplished with plugins are:

• Add custom annotations to generated methods
• Add additional methods to a generated class
• Add additional elements to a generated XML file
• Generate additional Java files
• Generate additional XML files

The contextXXX methods will always be called. Other methods are called by the Ibator supplied code generators - and only if the rules for a table would cause the generation of a particular element. For example, the modelPrimaryKeyClassGenerated(TopLevelClass, IntrospectedTable) method will not be called if the table does not have a primary key.

Methods that return a boolean can be used to bypass code generation. If any of these methods return false, then the related item will not be added to the generated code. If there is more than one plugin configured, then the first plugin to return false from a method will cause Ibator to stop calling that method in all other plugins.

If you have an idea for a plugin, feel free to ask a question about it on the iBATIS Java user list. We're here to help!