1. Butterfly Persistence
2. Butterfly Persistence Connection Management
3. Butterfly Persistence JDBC DAO
4. Butterfly Persistence Map DAO
5. Butterfly Persistence Object DAO
6. Butterfly Persistence Auto Object Mapping
7. Butterfly Persistence Annotation Based Object Mapping
8. Butterfly Persistence Programmatic Object Mapping
9. Butterfly Persistence Combining Object Mapping Methods
10. Butterfly Persistence Partial Object Reading and Writing

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.