Butterfly Persistence Combining Object Mapping Methods

Jakob Jenkov
Last update: 2021-06-30

It is possible to combine the mapping methods to ease the mapping process. As already mentioned you can combine automatic mapping with annotation based mapping. It is also possible to combine programmatic mapping with annotation based mapping and automatic mapping. The sequence in which the mapping methods are normally combined are:

  1. Automatic Mapping
  2. Annotation Based Mapping
  3. Programmatic Mapping

By default annotation based mapping is combined with automatic mapping meaning that first automatic mapping will be applied, then the annotations will be read and the mapping modified accordingly. When using programmatic mapping you can also use both annotation based and automatic mapping before the programmatic mapping is applied. The tree methods in the ICustomObjectMapper interface can be used to control the combination of mapping methods applied. The interface is repeated below without JavaDoc and exception declarations:

public interface ICustomObjectMapper {

  public IObjectMapping getObjectMapping(Object objectMappingKey)

  public String getTableName(Object objectMappingKey)

  public void modify(Object objectMappingKey, IObjectMapping mapping)


If your custom mapper implementation returns an object mapping from the getObjectMapping() method then automatic and annotation based mapping are not applied. If null is returned, then first automatic mapping is applied, then annotation based mapping.

If a table name is returned from the getTableName() method, then Butterfly Persistence will not try to guess a table name, nor look at the class annotation for table name. If null is returned Butterfly Persistence will look at the class annotation to see if a table name is set there. If it is, it will be used. If not, Butterfly Persistence will try to guess the table name.

If the getObjectMapping() method returned null Butterfly Persistence will call the modify() method to allow your custom object mapper to modify the automatically generated mapping. Before doing so Butterfly Persistence will have applied the annotations in the class to the mapping.

The mapping rules for combining mapping methods are summarized here:

  1. getObjectMapping() returns mapping - disables automatic and annotation based mapping.
  2. getObjectMapping() returns null - enables automatic and annotation based mapping.
  3. getTableName() returns table name - disables table name guessing and annotation.
  4. getTableName() returns null - first table name annotation is read. If not set, table name guessing is used.
  5. modify() - first automatic mapping is applied, then annotation based mapping, then modify() is called.

Jakob Jenkov

Featured Videos

Java ForkJoinPool

P2P Networks Introduction


Java Persistence
Close TOC
All Tutorial Trails
All Trails
Table of contents (TOC) for this tutorial trail
Trail TOC
Table of contents (TOC) for this tutorial
Page TOC
Previous tutorial in this tutorial trail
Next tutorial in this tutorial trail