Butterfly Persistence Partial Object Reading and Writing

Jakob Jenkov
Last update: 2021-06-30

Sometimes it is overkill to read or write a full object from database. You may only need to display, say 5 fields, and edit 2 of them. If the full object contains 30-40 fields, it can be a waste to read all 30-40 fields out of the database, only to display 5 of them. Likewise it is a waste to write all 30-40 fields back to the database when only 2 of them have been changed. In a situation like this you need partial object reading and writing.

Butterfly Persistence supports both partial object reading and writing. Both are explained in this text. Here is a list of the topics covered:

  1. Partial Object Reading
  2. Partial Object Writing
  3. Different Mappings for Reading and Writing

Partial Object Reading

Partial object reading is very easy to do with Butterfly Persistence. Butterfly Persistence only copies the values available in the ResultSet into the object. Therefore, if you just limit the columns available in the ResultSet, by limiting the selected columns in the "select" statement, only the selected columns will be read into the object. In the SQL statement below, only the two columns "name" and "type" are selected.

select name, type from items

Thus, it doesn't matter how many fields in a class are mapped to columns in the "items" table. Only the columns "name" and "type" are read into the corresponding object fields. The rest of the fields are left untouched. No values are inserted into them. Whatever values they have at object instantiation they will retain after the reading of columns into the object.

Partial Object Writing

Partial object writing requires a bit more work, but is still not too difficult. Butterfly Persistence cannot guess which columns you want to write. Therefore you need to create a special object mapping for the given class, that only maps the fields you want to write to columns in the database. You will have to do so programmatically. You can find more information about how to create programmatic object mappings in the text on Programmatic Mapping. Here is an example:

public static final ObjectMappingKey partialMappingKey =
        Employee.class,  new CustomMapper());

public class CustomMapper implements ICustomObjectMapper {
  public IObjectMapping getObjectMapping(Object objectMappingKey)
  throws PersistenceException {
    try {
      IObjectMappingFactory factory = new ObjectMappingFactory();
      IObjectMapping mapping = factory.createObjectMapping();
      factory.addGetterMapping(mapping, "getName" , "name", true);
      factory.addGetterMapping(mapping, "getJobTitle", "job_title", true);
      return mapping;
    } catch (NoSuchMethodException e) {
      throw new PersistenceException(
         "Error creating custom mapping for Employee", e);

  public String getTableName(Object objectMappingKey)
  throws PersistenceException {
    return null;

  public void modify(Object objectMappingKey,
    IObjectMapping mapping)
  throws PersistenceException {
    //do nothing.

To use this partial object mapping for writing, pass the partialMappingKey object mapping key as object mapping key parameter to the IGenericDao's write methods.

Note: Getter-mappings are used when writing objects, and setter-mappings are used when reading objects. Since the above custom object mapping is only used for writing, it is only necessary to add getter-mappings to it.

Different Mappings for Reading and Writing

An object read using mapping A does not have to be written again using mapping A. It can be written using a different mapping B if desired. Hence it is possible to read a full object using the standard object mapping (auto-generated, annotation based etc.), but to write only parts of it by using a special object mapping that only maps part of the object to database.

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