Butterfly Persistence Object DAO

The IObjectDao Interface
Simple Read Examples
Simple Read List Examples
Simple Insert Examples
Simple Insert List Examples
Simple Update Examples
Simple Update List Examples
Simple Delete Examples
Simple Delete List Examples
Object DAO Examples

Jakob Jenkov
Last update: 2021-06-30

From the IDaos instance you have access to an IObjectDao instance. This DAO can read/write objects from/to database. It cannot read or write object graphs, but it can assist you while you read or write graphs.

This text will primary give you an introduction to using the IObjectDao. It will not explain every little twist in detail. The IObjectDao is too big to be explained in a single text, so several of the concepts are explained in supplemental texts. Also make sure you check the JavaDoc as great effort has been put into documenting the IObjectDao interface.

The IObjectDao Interface

The most interesting methods of the IObjectDao interface are shown below. Exception declarations has been removed for clarity. As you can see it is much bigger than the IJdbcDao and IMapDao interfaces. But really, the many methods are primarily variations over the operations:

Read Object
Read List of Objects
Insert Object
Insert List of Objects as Batch Update
Update Object
Update Object where Primary Key has Changed
Update List of Objects as Batch Update
Update List of Objects where Primary Key has Changed as Batch Update
Delete Object
Delete List of Objects as Batch Update

package com.jenkov.db.itf;


public interface IObjectDao {

    List getUpdateResults();
    UpdateResult getUpdateResult(int index);


    Object readByPrimaryKey(Object objectMappingKey, Object primaryKey)

    Object read(Object objectMappingKey, String sql)
    Object read(Object objectMappingKey, ResultSet result)
    Object read(Object objectMappingKey, Statement statement,
            String sql)
    Object read(Object objectMappingKey, PreparedStatement statement)
    Object read(Object objectMappingKey, String sql,
            Collection parameters)
    Object read(Object objectMappingKey, String sql,
            Object ...  parameters)

    List readListByPrimaryKeys(Object objectMappingKey,
            Collection primaryKeys)

    List readList(Object objectMappingKey, String sql)
    List readList(Object objectMappingKey, ResultSet result)
    List readList(Object objectMappingKey, Statement statement,
            String sql)
    List readList(Object objectMappingKey, PreparedStatement statement)
    List readList(Object objectMappingKey, String sql,
            Collection parameters)
    List readList(Object objectMappingKey, String sql,
            Object ...  parameters)

    List readList(Object objectMappingKey, String sql,
            IReadFilter filter)
    List readList(Object objectMappingKey, ResultSet result,
        IReadFilter filter)

    List readList(Object objectMappingKey, Statement statement,
            String sql, IReadFilter filter)
    List readList(Object objectMappingKey,
            PreparedStatement statement, IReadFilter filter)
    List readList(Object objectMappingKey, String sql,
            Collection parameters, IReadFilter filter)
    List readList(Object objectMappingKey, String sql,
            IReadFilter filter, Object ...  parameters)

    int insert(Object object)
    int insert(Object objectMappingKey, Object object)

    int[] insertBatch(Collection objects)
    int[] insertBatch(Object objectMappingKey, Collection objects)

    int update(Object object)
    int update(Object objectMappingKey, Object object)

    int updateByPrimaryKey(Object object, Object oldPrimaryKeyValue)
    int updateByPrimaryKey(Object objectMappingKey, Object object,
            Object oldPrimaryKeyValue)

    int[] updateBatch(Collection objects)
    int[] updateBatch(Object objectMappingKey, Collection objects)


    int[] updateBatchByPrimaryKeys(Collection objects,
            Collection oldPrimaryKeys)
    int[] updateBatchByPrimaryKeys(Object objectMappingKey,
            Collection objects, Collection oldPrimaryKeys)

    int delete(Object object)
    int delete(Object objectMappingKey, Object object)

    int[] deleteBatch(Collection objects)
    int[] deleteBatch(Object objectMappingKey, Collection objects)

    int deleteByPrimaryKey(Object objectMappingKey, Object primaryKey)
    int[] deleteBatchByPrimaryKeys(Object objectMappingKey,
            Collection primaryKeys)
}

Simple Read Examples

You can read an object from database like this:

String sql    = "select * from persons where id=22"
Person person = (Person) daos.getObjectDao().read(Person.class, sql);

Automatic Cast of Object Read

From version 5.3.9 you no longer need to cast the returned object, if you use a Class object as object mapping key. This is true for all read() and readList() methods. Here is an example:

String sql    = "select * from persons where id=22"
Person person = daos.getObjectDao().read(Person.class, sql);

You can also read the object using a parameterized SQL statement like this:

String sql = "select * from persons where id=?"
Person person = (Person) daos.getObjectDao().read(Person.class, sql, 22);

If you know the primary key of an object (record) then you can also read it like this:

Person person = (Person) daos.getObjectDao().readByPrimaryKey(Person.class, 666);

Simple Read List Examples

You can read a list of objects like this:

String sql = "select * from persons where birth_year > 1975"
List persons = daos.getObjectDao().readList(Person.class, sql);

You can also parameterize the SQL statement and pass the parameters to the readList() method. Here is an example:

String sql = "select * from persons where birth_year > ?"
List persons = daos.getObjectDao().readList(Person.class, sql, 1975);

List<Person> persons = daos.getObjectDao().readList(Person.class, sql, 1975);

You can also read a list of objects by their primary keys:

List primaryKeys = new ArrayList();
primaryKeys.add(23);
primaryKeys.add(666);
List persons = daos.getObjectDao().readList(Person.class, primaryKeys);

Simple Insert Examples

You can insert an object like this:

Person person = new Person();
person.setName("Joe Blocks");

daos.getObjectDao().insert(person);

Simple Insert List Examples

You can insert a list of object using batch updates like this:

List persons = new ArrayList();
persons.add(person1);
persons.add(person2);
...

daos.getObjectDao().insertBatch(persons);

Simple Update Examples

You can update an object like this:

Person person = (Person)
        daos.getObjectDao().readByPrimaryKey(Person.class, 22);
person.setName("John Doe");

daos.getObjectDao().update(person);

If you also need to change the primary key of the object you need to know the old primary key in order for the update to work. Here is how you do it then:

Person person = (Person)
        daos.getObjectDao().readByPrimaryKey(Person.class, 22);

person.setId(666);
person.setName("John Doe");

daos.getObjectDao().updateByPrimaryKey(person, 22);

Simple Update List Examples

You can update lists of objects using batch updates like this:

String sql = "select * from persons";
List persons = daos.getObjectDao().readList(Person.class, sql);

//change persons in list

daos.getObjectDao().updateBatch(persons);

If you need to change the primary keys of the objects to update, you will need use the updateBatchByPrimaryKeys method. Here is how it looks:

String sql = "select * from persons";
List persons = daos.getObjectDao().readList(Person.class, sql);
List oldPrimaryKeys = getPrimaryKeys(persons);

//change persons and PK's in list

daos.getObjectDao().updateBatchByPrimaryKeys(persons, oldPrimaryKeys);

Simple Delete Examples

You can delete an object (record) in the database like this:

Person person = new Person();
person.setId(666);

daos.getObjectDao().delete(person);

You can also delete an object by its primary key, like this:

daos.getObjectDao().deleteByPrimaryKey(Person.class, 666);

Simple Delete List Examples

You can delete lists of objects using a batch update like this:

String sql = "select * from persons";
List persons = daos.getObjectDao().readList(Person.class, sql);

daos.getObjectDao().deleteBatch(persons);

You can also delete a list of objects (records) by their primary keys, like this:

List primaryKeys = new ArrayList();

primaryKeys.add(22);
primaryKeys.add(666);

daos.getObjectDao().deleteBatchByPrimaryKeys(Person.class, primaryKeys);

Object DAO Examples

This text contains a few examples of how to use the object DAO, IObjectDao, so you can get an idea about how to use the IObjectDao class:

More examples will be added as time is available to write them, and users report they need them.

All the examples will assume a configuration of the PersistenceManager like this one:

protected static final DataSource dataSource = new SimpleDataSource(
    "org.h2.Driver", "jdbc:h2:tcp://localhost/theDb", "sa", "");

public static final PersistenceManager persistenceManager =
    new PersistenceManager(dataSource);

In addition the Person class and persons table are defined like this:

create table persons (
  id    identity  /* auto-incremented integer type*/,
  name  varchar(255)
);

public class Person{
  protected long   id   = -1;
  protected String name = null;

  @AGetterMapping(databaseGenerated = true);
  public long getId()               { return this.id;  }
  public void setId(long id)        { this.id = id; }

  public String getName()           { return this.name; }
  public void   setName(String name){ this.name = name; }
}

Read Object

Here is how to read an object:

IDaos daos = persistenceManager.createDaos();

String sql    = "select * from persons where id = ?";
Person person = (Person) daos.getObjectDao().read(Person.class, sql, 666);

daos.getConnection().close();

Insert Object

Here is how to insert an object into a table:

IDaos daos = persistenceManager.createDaos();

Person person = new Person();
person.setName("Joe Blocks");

daos.getObjectDao().insert(person);

daos.getConnection().close();

Update Object

Here is how to update an object:

IDaos daos = persistenceManager.createDaos();

String sql    = "select * from persons where id = ?";
Person person = (Person) daos.getObjectDao().read(Person.class, sql, 666);

person.setName("Name Changed");

daos.getObjectDao().update(person);


daos.getConnection().close();

Delete Object

Here is how to delete an object:

IDaos daos = persistenceManager.createDaos();

Person person = new Person();
person.setId(666);

daos.getObjectDao().delete(person);

Delete Object by Primary Key

Here is how to delete an object by its primary key:

IDaos daos = persistenceManager.createDaos();

daos.getObjectDao().delete(Person.class, 666);

Next: Butterfly Persistence Auto Object Mapping

Tweet
	Jakob Jenkov