Major Enhancement: Java File Merging

The core library now supports Java file merging - this no longer requires Eclipse to run. This is the most requested feature in MyBatis Generator. Thanks to @DanielLiu1123 for the initial contribution!

The Java file merger is based on https://javaparser.org/. This is different from the merger in the Eclipse plugin, which was based on Eclipse JDT. We encourage you to try it and provide any feedback you might have.

This implementation differs from the original Eclipse-based implementation in the following ways:

1. Any merged file will be formatted for output using JavaParser's LexicalPreservingPrinter. This means that the results of a Java merge will be slightly different from the results from the old Eclipse-based merger. The differences should not impact compiling and running the results – they should be limited to import ordering, method ordering, spacing, etc. If you experience any difficulties with this, please let us know by opening an issue at GitHub.
2. This implementation supports merging enums and records
3. This implementation supports merging when the existing file is a class or interface, and the newly generated file is a record.
4. This implementation does not support merging the super class from an existing file to the newly generated file. This was always a little dangerous.
5. This implementation does not attempt to preserve custom annotations added to generated elements. With the generator now generating code with many annotations, it is challenging to distinguish between annotations created by MBG, and custom annotations added after code generation by a user. If you need to add annotations to generated elements, consider implementing a plugin that will create the annotations whenever the genertor runs.

To enable the feature, two things are required:

1. You must explicitely enable this feature with a new flag if you are using the command line runner, or by setting a property in the Ant or Maven runners.
2. You must add JavaParser to the runtime classpath of whatever runner you are using. The Eclipse runner adds JavaParser to the classpath automatically.

See the "running" pages for details on how to enable this in every environment.

Major Enhancement: Record Generation

We now support generating Java records for the models in all Java based runtimes (the generator already generates Kotlin data classes which are similar). Records are a concise way to represent a class that consists only of getters and setters – they can be a good candidate for the model classes generated by the library. One issue is that records are immutable by nature - so they cannot be used to represent tables that have generated keys. This is a limitation in MyBatis' approach to returning generated key values. Another issue is that usage of a record with a large number of fields can be inconvenient. We have added two plugins to help alleviete that difficulty (see below).

Using Java Records as model classes can be inconvenient when a table has a large number of fields. Additionally, since records are immutable by nature, it is impossible to change a field value. To overcome some of these difficulties, we have included two new plugins:

• org.mybatis.generator.plugins.RecordBuilderPlugin will add a "Builder" to a generated record to make construction of records more expressive.
• org.mybatis.generator.plugins.RecordWithMethodsPlugin will add "with" methods to a generated record. A "with" method returns a new instance of the record with just one value changed. This plugin will become obsolete if and when JEP-468 is adopted.

Both plugins add considerable boilerplate to generated records. This, in one sense, defeats the purpose of a record. But if you want to use records for their immutable properties, then these plugins may be useful for you.

Major Enhancement: Adoption of JSpecify

Following the lead of many other projects (including The Spring Framework), we have adopted JSpecify to fully document the null handling properties of this library. JSpecify is now a runtime dependency - as is recommended practice with JSpecify. Proper use of JSpecify pushes a codebase towards immutability - which is a good thing in general. This has caused some potentially breaking changes to the API (detailed below). It has also given us an opportunity to do a general cleanup and modernization of the code base. For many users, these changes should be transparent.

If you want to adopt JSpecify in the generated code, we've added a new plugin org.mybatis.generator.plugins.JSpecifyPlugin that will add JSpecify nullability annotations to generated model classes and records. If you add this plugin to the runtime for MyBatis Dynamic SQL, the plugin will also remove the following methods from a generated mapper:

• updateAllColumns
• updateByPrimaryKeySelective
• updateSelectiveColumns

As with the Kotlin runtime, these methods don't work well when you are strictly observing nullability.

Other Enhancements/Fixes

• Java 17 is now the minimum supported Java version
• Added several missing modifiers to the Kotlin DSL
• Fixed a rendering bug when Java types have wildcard bounds
• Added a missing plugin method for the Dynamic SQL runtime
• Internally the generator now uses commons logging. You can configure commons logging to use any logging framework you desire.
• Support a new property "injectModelIntoRootInterface" on Table and Java Client configurations that supports generation of mappers that extend a generic mapper.
• Inspired by a pull request from @dparo, the annotations related to generated keys now include the column name (this is now the same as the generated XML elements). This might have caused issues if an insert produced more than one generated value.
• Support a new property "useSnakeCaseIdentifiers" on Table and Java Client configurations that supports changes the generation of MyBatis Dynamic SQL support objects. If true, then generated members that model database tables and columns will use snake case names (e.g., ORDER_MASTER) rather than camel case names (e.g., orderMaster). This helps avoid awkward parameter naming for some methods where we appended an underscore to generated parameters in some cases.
• The runtimes that build code for MyBatis Dynamic SQL (MyBatis3DynamicSql and MyBatis3Kotlin) have been updated to use version 2.0.0 of that library, and the generated code will require that version or later.
• The XML configuration element <javaModelGenerator> has been renamed to <modelGenerator>. Since the library is generating Kotlin code in many cases, it makes sense to have the configuration element be more generic. The old element name continues to work. There should be no impact to users except for a warning message that encourages you to use the new name.
• The XML configuration element <javaClientGenerator> has been renamed to <clientGenerator>. Since the library is generating Kotlin code in many cases, it makes sense to have the configuration element be more generic. The old element name continues to work. There should be no impact to users except for a warning message that encourages you to use the new name.
• The Kotlin runtime has the following enhancements:
  • Generated result maps now use constructor argument mappings rather than results mapping. This is more consistent with how data classes are actually built and lessens the reliance on reflection tricks.
  • The generator will now respect the "immutable" property on a <table> or <modelGenerator> configuration.
  • The default model type for Kotlin is now immutable (using "val" instead of "var" in most cases). In addition, the model classes respect the "nullable" setting on database columns. So if a column is defined as "NOT NULL," then the generated data class will use a non-nullable type to represent the column. This change also cascaded into a better implementation of the generated mappers and, therefore, the following generated methods are no longer generated:
    • updateAllColumns
    • updateByPrimaryKeySelective
    • updateSelectiveColumns

    You can revert to the prior version of a generated model by specifying <property name="generateKotlinV1Model" value="true" /> in a <table> or <modelGenerator> configuration element. This setting will no longer be supported and will be removed in a future version of the generator.

• The Java type resolver has changed in the following ways:
  • The property "useJSR310Types" has been removed and will be ignored if you specify it. The default implementation now uses JSR-310 types (LocalDate, LocalDateTime, and LocalTime) in all cases.
  • The default implementation will now properly handle columns of type SQLXML using the type handler built in to MyBatis.
  • If you prefer to use java.util.Date to represent DATE, TIME, and TIMESTAMP fields, you can specify "org.mybatis.generator.internal.types.DateForcingJavaTypeResolver" for "type" in a <JavaTypeResolver> configuration.
  • The interface has changed and has been simplified. If you have created an implementation of org.mybatis.generator.api.JavaTypeResolver, you will need to update your implementation.
• The comment generator has changed in the following ways:
  • The comment generator no longer produces JavaDoc with a non-standard JavaDoc tag. We now exclusively use the "jakarta.annotation.Generated" annotation.
  • Support for the property "dateFormat" has been removed. All timestamps are now formatted in ISO 8601 format.
  • Support for the property "useLegacyGeneratedAnnotation" has been removed. All generated annotations are now "jakarta.annotation.Generated".
  • The behavior of the "suppressAllComments" property has changed – if true, then no comment or annotation will be added to a generated file. This will effectively disable the Java and XML merge functionality.
  • A new property "minimizeComments" can be specified that will cause the comment generator to add the minimum comments and annotations required to support Java and XML merging (no timestamps or other comments will be added)
  • The interface has changed and has been simplified. If you have created an implementation of org.mybatis.generator.api.CommentGenerator, you will need to update your implementation.

Potentially Breaking Changes

The following are potentially breaking changes:

• The GeneratedKey configuration class (and corresponding XML element) no longer support the "type" attribute. This attribute was only used for iBatis2 runtimes which are no longer supported by the library.
• The Table configuration class (and corresponding XML element) no longer support the "selectByPrimaryKeyQueryId" and "selectByExampleQueryId" attributes. I originally added these for a personal project years ago, but they were never very useful anyway.
• Removed "useColumnIndexes" as a documented property on the Table configuration XML element. That property was only used for iBatis2 runtimes which are no longer supported by the library.
• The extension point for creating your own implementation of a Java client generator has been removed. We know of no usages of this poorly documented extension point, so this should not impact anyone.
• The Context class has changed and it now only holds configuration information. This may impact you if you were relying on methods in that class in a Plugin. We have added CommentGenerator to all plugins as this was used in several of the internal plugins. Please let us know if you need access to other classes in a plugin.
• The plugin methods contextGenerateAdditionalFiles() and contextGenerateAdditionalFiles(IntrospectedTable introspectedTable) have changed their return types. They now return List<GenericGeneratedFile>
• If you are generating extra Java, Kotlin, or XML files in a plugin, you no longer need to set the formatter or file encoding. The library will automatically use the values configured in the context
• The Context class no longer has a getConnection() method. If your plugin needs to connect to the database, you can use ConnectionUtility.getConnection(Context)
• The extension point for creating a new target runtime has changed. It is extremely unlikely that this will impact anyone. However, if you have created a fully custom code generator, you must now provide the fully qualified name of class that extends org.mybatis.generator.api.AbstractRuntime.AbstractRuntimeBuilder in the XML configuration for a <context>.
• The IntrospectedTable.getTargetRuntime() method has been removed. It is replaced by IntrospectedTable.getKnownRuntime(). Plugins might use these methods to function differently for different runtimes. The new return value has much more information than the previous value.
• If you run the generator directly from Java code (i.e. not from Maven, Ant, Eclipse, or the command line runner) then you will notice that the interface to the MyBatisGenerator class has changed. The class now uses a Builder to build instances, and the generate methods have changed.
• If you run the generator directly from Java code (i.e. not from Maven, Ant, Eclipse, or the command line runner) then you may notice that the interface to the ConfigurationParser class has changed. The class no longer accepts an outside List to store warnings. Rather, warnings can be retrieved from the object after a configuration file parse.

Enhancements

• The generator now uses annotations from the "jakarta" namespace in favor over the "javax" namespace. This is recommended for JDK 9+. If you prefer to use the "javax" annotations, there is a new property on the <commentGenerator> element that will override this behavior.
• The Maven plugin now includes an integration with Eclipse Maven support. If you import a Maven project with the generator configured into an Eclipse workspace, the code generator will run automatically.
• Added an "info" logging level to the log abstraction. Also removed the broken Maven logging implementation. Logging should now work as expected in Maven - Maven ships with the SLF4J simple logger in the classpath, so configuring logging in Maven will always use the SLF simple logger.
• Added a new plugin method "shouldGenerate" that can be used to provide fine-grained filtering of tables in a context. Also added a new "IgnoreViewsPlugin" that filters out table type VIEW

Updated MyBatis Dynamic SQL Runtimes

The MyBatis3DynamicSQL and MyBatis3Kotlin runtimes have been updated to generate code that requires updated versions of MyBatis Dynamic SQL. Generated Java code requires version 1.3.1 or later, generated Kotlin code requires version 1.4.0 or later. This should be a relatively minor change for most Java users and should simply require updating the MyBatis Dynamic SQL version to 1.3.1 or later.

For both Java and Kotlin users, the new database model classes (a.k.a. the "support" classes) now extend AliasableSqlTable. This allows you to specify a table alias directly within an instance of a table class, rather than specifying the alias in a select statement. This can make the code a bit clearer if you are doing a self join.

Differences for Kotlin users are more extensive. As a result of the changes detailed below, several plugin methods related to the generated Kotlin files have changed or been deprecated. If a method has been deprecated, it is no longer in use by the generator and will be removed in the future.

We have merged the generated mapper extension methods into the same file as the mapper itself - eliminating generated files with the word "Extensions" in their names. If you are regenerating code in an existing project, you should manually delete the old generated extension files (generated Kotlin files with the word "Extensions" in the file name).

The generated Dynamic SQL Support class in the Kotlin runtime has changed and now matches the recommended format published in the MyBatis Dynamic SQL documentation (it more closely matches the style of the support class generated for Java). This has the following benefits:

• Self-joins are now possible with the generated code
• There is no longer a need to append the word "Record" to generated model classes
• Specifying an override to rename the domain object will take effect as desired

This update will require changes in existing code if you regenerate Kotlin code using this updated version.

Generated Kotlin data classes no longer have the word "Record" appended to their names. Otherwise, they are the same. Your use of these classes will need to change. In most cases, you can simply remove the word "Record" from the reference. For example, if you have a table named "Bar", you may see code like this:

    import foo.BarRecord

    val bar = BarRecord(1, 2)

It will need to change to code like this:

    import foo.Bar           // remove "Record"

    val bar = Bar(1, 2)      // remove "Record"

Additionally, generated support classes now declare an instance of the AliasableSqlTable object, and all fields, as values in the top level object. If you wrote custom code that used these generated objects, two changes will be required:

• The declared AliasableSqlTable object is now an instance of an inner Class rather than an inner Object. It should be referenced with the new name (typically the same name as previously, with the first letter now lowercase)
• References to any AliasableSqlColumn should reference the top level value rather than a nested value

For example, previously code might have looked like this:

    import foo.BarDynamicSqlSupport.Bar
    import foo.BarDynamicSqlSupport.Bar.id
    import foo.BarDynamicSqlSupport.Bar.description

    val selectStatement = select(id, description) {
       from(Bar)
    }

New code should look like this:

    import foo.BarDynamicSqlSupport.bar           // use the lower case name
    import foo.BarDynamicSqlSupport.id            // import the top level field
    import foo.BarDynamicSqlSupport.description   // import the top level field

    val selectStatement = select(id, description) {
       from(bar)     // use the lower case name
    }

Lastly, the generated Kotlin code uses upgraded DSL features that should be mostly transparent. But you will notice that any "where" clauses you write will likely have deprecation warnings. This is due to a change in MyBatis Dynamic SQL. You can read about remediation of these warnings in the documentation for that project.

Other Enhancements

• Added capabilities to the SerializablePlugin for Kotlin
• Added the ability to specify a package for MyBatis Dynamic SQL Support Classes
• Added the ability to specify a MyBatis Dynamic SQL Support class name on the table configuration
• Added a plugin to generate @CacheNamespace annotations
• Added the ability to specify a name for the inner class generated in the MyBatis Dynamic SQL support class
• Added plugin methods that allow generation of any arbitrary file type
• Added a property to <columnOverride> that forces the Java type into generated mappings for the MyBatis Dynamic SQL based runtimes. This is useful in certain cases such as when you use MyBatis' EnumOrdinalTypeHandler.

Removed Items

• Removed the deprecated MyBatis3DynamicSqlV1 runtime
• Removed the Java client property "useLegacyBuilder" as it created code that has been deprecated in MyBatis since version 3.2
• Removed support for Log4J version 1.x

New Runtime for Kotlin Using MyBatis Dynamic SQL

MyBatis generator supports Kotlin! There is a new simple DOM for generating Kotlin. There is also a new runtime that will generate Kotlin code that uses the MyBatis Dynamic SQL library. It has functionality that matches the new Java runtime for MyBatis Dynamic SQL (see below) - but it uses a more idiomatic Kotlin style with receiver functions rather than the method chaining style of the Java runtime.

To use the new runtime, set targetRuntime=MyBatis3Kotlin on a <context>.

As in the Java runtime for MyBatis Dynamic SQL, there is no Example class generated and the *ByExample methods are not generated. Rather general count, delete, insert, selectOne, selectMany, and update methods are generated that allow where clauses and other parts of SQL statements to be supplied via lambdas.

See the MyBatis Dynamic SQL with Kotlin Usage Page for further details.

New Runtime for MyBatis Dynamic SQL

There is a new runtime for MyBatis Dynamic SQL. It uses improved functionality in that library and requires version 1.1.3 or later of that library.

To use the new runtime, set targetRuntime=MyBatis3DynamicSql on a <context>.

Important: Setting targetRuntime=MyBatis3DynamicSql will use the new runtime. If you wish to use the original runtime, set targetRuntime=MyBatis3DynamicSqlV1. However, note that the V1 runtime is deprecated and will be removed in a future version - so please switch to the new runtime.

The new runtime has enhanced capabilities:

• The *ByExample methods are removed. There is no example class generated in this runtime and the old method names don't make sense anymore. They are replaced by general count/delete/select/update methods that allow a where clause to be added via a lambda
• There is a new multiple row insert method that leverages recent enhancements in MyBatis and MyBatis Dynamic SQL
• There is a new selectOne method that allows you to specify a where clause via a lambda. This is convenient when you know that there will only be one record returned from a query - you no longer have to receive a list with one element
• selectByPrimaryKey and selectOne return Optional<R> rather than an object that may be null
• The new generated update method is far more flexible than the prior version. It can be used to mimic the old updateByExample and updateByExampleSelective methods, but it can also be used to generate update methods with any combination of update columns. So, for example, you can create an update statement that will insert nulls into some fields and ignore other fields. This has been an ongoing frustration with the prior update methods and is now resolved.

See the MyBatis Dynamic SQL Usage Page for further details.

Breaking API Changes

• Removed Plugin methods that were specific to iBatis2 (these were the clientXXXGenerated methods that accepted a TopLevelClass as a parameter).
• Changed the signature of the Plugin clientGenerated method.
• Removed the toXmlElement methods in the configuration classes. These methods were never properly implemented.
• In the Java DOM, the Method class now requires an explicit call to setAbstract to mark the method as an abstract method. This was done to support private methods in interfaces for Java9+ code.
• In the Java DOM, removed the default constructors for Method and Field
• Removed several methods from CompilationUnit including isJavaInterface, isJavaEnumeration, getSuperClass, and getSuperInterfaceTypes.
• In the XML DOM, element nodes no longer extend the abstract Element class which is removed.
• Changed return types to Optionals in the DOM methods where appropriate.
• Removed the getFormattedContent method from all Java and XML DOM classes. These methods are replaced by a new set of renderer classes. Note that the new renderer classes will produce code that is the same as the prior methods with very few exceptions - and those exceptions are related to bugs in the old methods.
• The attribute "implementationPackage" has been removed from the <clientGenerator> configuration. It was only used for iBatis.

Other Changes

• Support for iBatis2 removed
• Support for parsing old Ibator configuration files removed
• Removed SqlMapConfigPlugin as that was specific to iBatis2
• Added ability to specify a different project and package for generated model objects
• Expanded the capabilities of the Java DOM and fixed a few inconsistencies

Other Fixes/Enhancements

Please reference the GitHub page for milestone 1.3.6 for details on what else has changed in this release. Milestone 1.3.6

Fixes/Enhancements

Please reference the GitHub page for milestone 1.3.5 for details on what has changed in this release. Milestone 1.3.5

Announcements

In this release we have deprecated the popup menu item in the eclipse plugin for running MyBatis generator, and it will be removed in the next release. The replacement is a new MyBatis generator launcher that has far more capabilities than the popup menu item.

Fixes/Enhancements

Please reference the GitHub page for milestone 1.3.4 for details on what has changed in this release. Milestone 1.3.4

Announcements

• MyBatis Generator now requires JRE 1.6 or greater

Fixes/Enhancements

Please reference the GitHub page for milestone 1.3.3 for details on what has changed in this release. Milestone 1.3.3

Bugs Fixed

• Add comments to generated constructors in the model classes so they can be merged.
• Support package names with Uppercase elements.
• Fixed issue #288 - Incorrect annotated countByExample method
• Fixed the Maven plugin so <properties> files can be found in the project classpath.
• Fixed issue #359 - make JdbcTypeInformation public
• Fixed Context.toXmlElement() method to include missing attributes
• Fixed CaseInsensitiveLikePlugin to add new methods to GeneratedCriteria inner class
• Issue #412 - update the documentation to reflect the difference in MyBatis3 regarding generated keys.
• Issue #440 - incorrect code generated for primitives with type handlers
• Issue #439 - use auto boxing for primitives when appropriate
• Issue #438 - keep primary key properties in database sequence
• Issue #507 - RowBounds plugin generates duplicate statements
• Issue #593 - CaseInsensitiveLikePlugin skipped Jdbc4 National Character Types

Enhancements

• Added a new target runtime - MyBatis3Simple - that can be used to generate very simple CRUD operations on tables. This runtime produces far simpler MyBatis code than the normal MyBatis3 runtime. The produced code also has lower functionality that the normal MyBatis3 runtime. If you do not regularly use the "by example" methods, then the code produced by the MyBatis3Siple runtime may be more suitable to your project.
• Added a new plugin - VirtualPrimaryKey plugin - that can be used to specify columns that act as a primary key, even if they are not defined as primary keys in the database.
• Issue #328 - Added a new plugin - RowBounds plugin - that will generate an additional version of selectByExample that supports the MyBatis RowBounds function.
• Created a new reference page for supplied plugins: Supplied Plugins
• Issue #368 - Allowed for generation of Java Model only. If no SQLMapGenerator or ClientGenerator is specified in a context, then only a Java Model is generated. Also, if property "modelOnly" is set to "true" on a <table> element, then only model object and, possibly XML result maps, will be generated.
• Issue #374 - Allow for specification of a file encoding for reading/writing Java files on the file system. There is a new property "javaFileEncoding" on the <context> element that can be used to specify a Java file encoding. (XML files are always read/written in UTF-8 per the spec).
• Added the ability to specify custom code formatters for generated Java and XML files. See new properties on the <context> element for more information.
• Added support for varargs to org.mybatis.generator.api.dom.java.Parameter class
• Added support for synchronized and native to org.mybatis.generator.api.dom.java.Method class
• Added support for transient and volatile to org.mybatis.generator.api.dom.java.Field class
• Issue #375 - Added a new plugin - ToStringPlugin - that will generate a toString() method in the model classes. Thanks, Alexei and Iwao!
• Issue #233 - added GWT capability to the Serializable plugin
• Issue #564 - support subpackages at the table level
• Issue #590 - new plugin for <cache>. Thanks, Jason Bennett!

Bugs Fixed

• Always specify <selectKey> order for MyBatis3 - position within the <insert> is not relevant.
• "rootInterface" was ignored for XMLMAPPER clients
• Fixed bug when a lower case class name is specified as a domain object name
• Fixed issue #174 - incorrect format of order by clause in selectByExampleWithBlobs

Enhancements

• Added a new MyBatis3 generator that generates code based solely on annotations with no generated XML. Configuration settings for this new generator are as follows:
  • The targetRuntime attribute of <context> element is MyBatis3
  • The type attribute of <clientGenerator> element is ANNOTATEDMAPPER
• Added a new MyBatis3 generator that generates code based on a mix of annotations and generated XML. Configuration settings for this new generator are as follows:
  • The targetRuntime attribute of <context> element is MyBatis3
  • The type attribute of <clientGenerator> element is MIXEDMAPPER
• Add support for JDBC types NCHAR, NCLOB, NVARCHAR to match MyBatis3.
• Added support for "useGeneratedKeys" in MyBatis3. See <generatedKey> for details.
• Added support for immutable objects and constructor based result maps in MyBatis3. See <table> and/or <modelGenerator> for details.
• Added support for initialization blocks in the Java DOM
• Issue #214 - Added the ability to supress all comments in generated code. See <commentGenerator> for details.

Announcements

• The org.apache.ibatis.ibator.api.CommentGenerator interface has changed. Classes that implement this interface must be changed. With this change, implementing classes have access to many more data elements from which to generate comments. Additionally, this change makes the comment generator interface more consistent with the other public Ibator interfaces. Details of the change follow:
  • Methods which accepted the parameter FullyQualifiedTable now accept the parameter IntrospectedTable instead. The FullyQualifiedTable instance is available through the method IntrospectedTable.getFullyQualifiedTable().
  • Methods which accepted the String parameter columnName now accept the parameter IntrospectedColumn instead. The column name is available through the method IntrospectedColumn.getActualColumnName().

  Important Note: any implementation that subclasses the Ibator supplied class DefaultCommentGenerator does not need to change immediately with this release. The old methods have been deprecated and will be removed with the next release of Ibator - so subclasses should be reworked as soon as convenient.

• The SQL Map generator has changed in that it no longer prepends the string "ibatorgenerated_" to every generated XML id. If you were relying on these generated names in other code, you can force Ibator to prepend the string with the property useLegacyXMLIds on the <SqlMapGenerator> configuration.
• Ibator is now built with Maven and includes a Maven plugin

Bugs Fixed

• NPE when no DAOs are generated.
• IBATIS-579 - Don't allow column names that contain spaces to break across lines in generated XML.
• Fixed NPE and incorrect calculation in generated equals method (from EqualsHashCodePlugin) when certain fields are null - thanks to Benjamin Klatt for finding this bug.
• IBATIS-601 - improper validation of <generatedKey>
• IBATIS-609 - incorrect parsing of Java generic types
• Fixed spelling error LONCVARCHAR to LONGVARCHAR (thanks Allard)
• Fixed IBATIS-731 - change name of primary key variable to avoid conflicts
• Fixed IBATIS-699 - Overwrite unmergeable XML files if enabled
• Fixed issue where insertSelective failed if there is a sequence generating the primary key (issue only with iBATIS3)

Enhancements

• IBATIS-569 - Modified the IbatorRules implementation to make it easier for plugins to provide custom implementations of IbatorRules. See the Javadoc for the new class org.apache.ibatis.ibator.internal.rules.IbatorRulesDelegate for more information.
• IBATIS-571 - Added support for automatically delimiting SQL keywords if they are used as column names in tables. See the <ibatorContext> page for more information.
• IBATIS-577 - Define SQL fragments for column lists to improve reusability of generated code. Thanks to Iwao AVE! for the idea and the initial patch.
• Added new -verbose command line argument. See the Running Ibator page for more information.
• Added logging statements for use in debug. See the Logging page for more information.
• Added new example plugin to demonstrate adding case-insensitive LIKE support to generated Example classes. See the <ibatorPlugin> page for more information.
• Added "delimitAllColumns" attribute to table configurations. This supports databases like PosgreSQL that are case-sensitive for identifiers. See the <table> page for more information.
• Added a page explaining how to deal with case sensitivity in PostgreSQL. See the PostgreSQL page for more information.
• IBATIS-586 - Added the ability to specify nested property elements on columnOverrides. See the <columnOverride> page for more information. Thanks to Dan Turkenkopf for the idea and a nice initial patch.
• The IntrospectedColumn class now contains any column remarks returned during database introspection. This may be useful for some CommentGenerators.
• IBATIS-592 - Added attributes to IntrospectedTable that contain the calculated SqlMap namespace, and the calculated runtime table names. These can now be overridden in plugins.
• Fixed addCriterionfor JDBC* methods so that they all do a null check.
• Fixed IbatorRunner so that configuration errors are shown (thanks to Karel Rank)
• IBATIS-605 - Added Informix Dialect for <generatedKey>
• Addedd support for "distinct" on select by example methods
• Added new "or" method to example classes
• Added new "useCompoundPropertyNames" property on <table>
• Enabled a far simpler method for extending the example classes
• EqualsHashCodePlugin now generates far superior methods

Bugs Fixed

• Fixed the IbatorObjectFactory so it will find internal classes from the context classloader.
• Fixed IBATIS-565 - ill formed comment in the SqlMapConfigPlugin

Enhancements

• Modified plugin methods for model fields, getters, and setters so that the plugin will know which type of class (Primary Key, Base Record, or Record with BLOBs) is being generated.
• Added methods to IntrospectedTable to get/set attributes. This allows plugin classes to maintain table based state between plugin calls.
• Added initialized method to the plugin API. This allows plugins to alter some of the fundamental code generation items (like the name of a generated class, for example).
• Added an example plugin to show usage of the initialized method.

Announcements

• With version 1.2, Abator is renamed to Apache iBATIS Ibator. Several changes have been made to the XML configuration as well as the Java API. See the Migrating from Abator page for detailed information about changes needed to existing Abator configuration files.

Bugs Fixed

• Fixed the JavaTypeResolver so that columns with unsupported data types may be overridden by configuration.
• Fixed IBATIS-523 - a bug in the pre-release version of the EqualsHashCodePlugin
• Fixed IBATIS-542 - upgrade the build to Ant version 1.7.1

Enhancements

• Ibator now includes a plugin mechanism. This mechanism can be used to add to or modify the code generated by Ibator. If you have previously extended one of Abator's code generators to change their behavior, we strongly suggest that you move to a plugin. See the <ibatorPlugin> page for detailed information.
• Ibator ships with the following plugins:
  • A plugin that will generate an SQL Map Config File (org.apache.ibatis.ibator.plugins.SqlMapConfigPlugin)
  • A plugin that will make generated model classes Serializable (org.apache.ibatis.ibator.plugins.SerializablePlugin)
  • A plugin that will add equals and hashCode methods to generated model classes (org.apache.ibatis.ibator.plugins.EqualsHashCodePlugin)
• Added support for "runtimeCatalog" and "runtimeSchema" properties to the <table> configuration element. Thanks to Dan Turkenkopf for the idea and the patch!
• New generated method - insertSelective. This method will allow you to use column defaults on a table definition on insert
• Added the ability to specify a that DAO implementation classes be in a separate package from the DAO interface classes.

Changes from Abator

There are several breaking changes between Ibator and Abator. This list details the changes, and has methods of resolving the differences.

• JSE 5.0 or higher is required for Ibator
• Ibator does not contain the "legacy" code generators from Abator. You must choose "Ibatis2Java2" or "Ibatis2Java5" as a target runtime - and code generated from Ibator is compatible with iBATIS version 2.2.0 or higher only. If you are using an earlier version of iBATIS - upgrade! If you are not able to upgrade, then you must continue to use Abator.
• The classloading strategy in Ibator is changed from Abator. In all cases, we now recommend specifying the classpath external to Ibator, and we further recommend that you do not use the <classPathEntry> element. You may specify classpath entries if you feel you must, but those entries will only be used when loading JDBC drivers of Java model root classes. If you write a custom extension to Ibator, or a plugin, you must specify that classpath entry external to Ibator.
• The API for extending Ibator is significantly changed from Abator. In most cases, implementations of the old Abator interfaces should be converted to Ibator plugins. See the Extending Ibator for more information.
• The afterXXXGenerationHook methods have been removed from all Ibator supplied implementations of the core interfaces. If you were extending an Ibator supplied implementation to make use of these methods, then you must migrate your code to an Ibator plugin.
• The build has been significantly modified and now includes an Emma based code coverage report.
• Changes to the XML configuration file are required. See the Migrating from Abator page for detailed information

Announcements

• The next release of Abator will require JRE 5.0 or higher.
• Java2 is now the default generator set. This will cause different code to be generated if you have not specified a generator set previously. To remedy this, set the generator set to "Legacy".

New Generated Methods

Abator will generate these new methods:

countByExample

This method will return an integer representing the number of rows in a table that match the given criteria.

updateByExample

This method will update all rows in a table that match a given criteria. This method is available in the Java2 and Java5 generator sets only. There is also a "selective" version of the method that only updates certain columns of a table (the selective version of this method is probably the more useful version to use in most situations).

Bugs Fixed

• Fixed bug for corner case where a criteria class is created, but no criteria are set.
• Fixed a bug that caused the ModelGenerator's "trimStrings" property to fail
• Fixed the XML file merger so that internal entities are preserved
• Fixed the XML configuration parser so that external entities are handled properly
• Fixed bug - incorrect datatype mapping for JDBC BIT datatype
• Fixed bug where Abator generated incorrect properties for certain database columns (for example, if the column name is I_NAME)

Miscellaneous Changes

• Added the ability to specify properties to ignore qualifiers and change runtime table names in the generated SQL for a table. Primary use cases for this support include:
  • Generating objects for a table that has a public synonym or alias
  • Generating objects for a table that exists in many schemas, and the schema will be selected at runtime
  See the <table> reference page for more information, or the Oracle reference page for an example.
• Added support for delimiting SQL identifiers for the use cases where identifiers contain spaces or SQL reserved words. See the <table>, <abatorContext>, and <columnOverride> reference pages for more information.
• Added SYBASE dialect for generated keys. See the <generatedKey> reference page for more information.
• Added DB2_MF (DB2 on Main Frames) dialect for generated keys. See the <generatedKey> reference page for more information.
• Abator will now automatically escape identifiers that contain the $ or # characters as these characters have special meaning in iBATIS configuration files.
• Added a clear method to the generated example classes (in the Java2 and Java5 generator sets only). This allows reuse of these classes.
• Added the ability to specify that result maps should use column indexes rather than column names in the result mappings. Primary use cases for this support include:
  • When tables have columns whose name is only differentiated by case (e.g. "first name" and "First Name")
  • When you want to make the selects as fast as possible (there is a slight performance benefit when using column indexes)
  See the <table> reference page for more information.
• Made the generated Example and Criteria classes extendable. Added some documentation about how to extend these classes. See the Extending the Example Classes reference page for more information.
• Made the legacy DAOs extendable.
• Added the ability to provide a renaming rule for columns. This is for the use case where columns have a common prefix that should be removed before calculating the property name. See the <columnRenamingRule> reference page for more information.
• Added support for persisting a configuration to XML - this to enable a graphical editor in the future.
• Add afterXXXGenerationHook() methods in all generators to enable adding extra Java code or XML elements to any generated object. This will make it easier to create customized generators.
• API change to allow generating with selected contexts rather than the entire config file.
• API change to allow generating with selected tables rather than the entire config file.
• Exposed new support for selecting tables and/or contexts to the command line and the Ant task - this has added an advanced syntax to the command line for Abator. See the Running Abator reference page for more information.
• rootClass and rootInterface may now be specified for each table. See the <table> reference page for more information.
• If a rootClass is specified for any table, Abator will now check in the rootClass to see if a generated property already exists in the root class. If it does, Abator will not generate the property. The <modelGenerator> element now accepts a property to specify the classpath of the rootClass. See the <modelGenerator> reference page for more information. Thanks to Ashok Madhavan for the beginnings of this code.
• Allowed specifying a type (pre or post) for the generated key element. See the <generatedKey> reference page for more information.
• Added a comment generator interface to enable generation of custom comments. See the <commentGenerator> reference page for more information.

Generator Sets

A generator set is a set of code generators (SQL Map Generator, Java Model Generator, DAO Generator, and Java Type Resolver). Abator now ships three different generator sets. The generated code from these three generator sets is slightly different, and the use of the generated objects is slightly different too. The concepts are exactly the same. With the newer generator sets, the "by example" methods have been vastly improved. It is now possible to generate virtually any WHERE clause (including IN and BETWEEN predicates). Lastly, the new generator sets generate much more concise code - the DAOs and SQL Maps are of normal size, and there are no extraneous methods. The example class in the new generator sets encapsulates all the function needed to generate dynamic queries.

The three generator sets shipped with Abator are as follows:

Legacy

This generator set generates code that is the same as previous versions of Abator. There are some limitations with this generator set, and we strongly recommend that you choose one of the other sets. However, this set remains the default for now. This generator set will likely be removed in a future version of Abator.

Java2

This generator set generates code that is compatible with iBATIS versions 2.2.0 and higher. With this generator set the "by example" methods are much more powerful than in the legacy set. It is now possible to generate virtually unlimited SQL WHERE clauses with Abator generated code (including "IN" and "BETWEEN" clauses). This generator set will likely become the default set in a future version of Abator.

Java5

This generator set has the same capabilities as the Java2 generator set with the added feature of generating code that is JSE 5.0 compliant using parameterized types and annotations.

Important: code generated with the Java2 or Java5 generator sets is not 100% compatible with code generated with the Legacy set - especially in the use of the "by example" methods. Also note that the "by example" methods in these generator sets rely on iBATIS dynamic SQL support that is missing in iBATIS versions prior to version 2.2.0.

A generator set is selected with the generatorSet attribute of the <abatorContext> element. See the <abatorContext> reference page for more information.

Use of the example classes is different with the different generator sets. See the Example Class Usage page for more information.

Model Types

A model type is used to give you more control over the types of domain objects generated by Abator. Abator now supports three different types of domain models as follows:

conditional

This model is similar to the hierarchical model except that a separate class will not be generated if that separate class would only contain one field. So if a table has only one primary key field, that field will be merged into the base record class. This model type is the default. Note that this model type may generate classes that are not 100% with classes generated in previous versions of Abator.

flat

This model generates only one domain class for any table. The class will hold all fields in the table.

hierarchical

This model is the same as the model shipped with the initial versions of Abator. This model will generate a primary key class if the table has a primary key, another class that holds any BLOB columns in the table, and another class that holds the remaining fields. There is an appropriate inheritance relationship between the classes.

Model types can be specified as a default for an entire context, and you may override the default for each table in a context. See the <abatorContext> reference page for more information about setting the context default. See the <table> reference page for more information about setting a model type for specific tables.

Important: the default value is conditional - this is a non-backward compatible change from previous versions of Abator.

updateByPrimaryKeySelective

This is a new mapped SQL statement, and new DAO method, that will only update columns whose corresponding properties in the parameter class are non-null. This can be used to update certain columns in a record without needing to update the entire record.

Important: any column that is mapped to a primitive type will always be updated.

Miscellaneous Changes

• Added the ability to specify a table alias. This aids in reuse of generated SQL map elements. See the <table> reference page for more information.
• Fixed the XML file merger so that extraneous blank lines at the end of the file are removed.
• Added the ability to specify a type handler for table columns. See the <columnOverride> reference page for more information.
• Added the ability to specify the visibility of the DAO "by example" methods. This allows you to make the methods private for internal use only. See the <clientGenerator> reference page for more information.
• Added the ability to override the naming convention for DAO method names. See the <clientGenerator> reference page for more information.
• Added the ability to specify wildcards for schema or tableName in a table configuration. This will allow generation of many tables with a simple XML configuration. See the <table> reference page for more information.
• Added the ability to escape wildcard characters in schema or table names if required by the driver. See the <table> reference page for more information.
• Added the ability to suppress JSE 5.0 type warning messages for non-parameterized types if you are using the Legacy or Java2 generator sets in a JSE 5.0 environment. See the <abatorContext> reference page for more information.
• Added the ability to specify an external properties file for passing parameters into an Abator configuration file (like the iBATIS properties file). See the <properties> reference page for more information.
• The Ant task now supports a "verbose" attribute. See the Running Abator page for more information.
• The Ant task now supports a nested property set for passing values into an Abator configuration file. See the Running Abator page for more information.