Tutorials     About     RSS
Tech and Media Labs

Butterfly Persistence

Jakob Jenkov
Last update: 2021-06-30

Butterfly Persistence is an open source light-weight Java persistence API for reading and writing data from and to relational databases. Butterfly Persistence is a thin layer on top of JDBC which takes care of most of the boring boilerplate code needed to perform the most common JDBC actions, such as CRUD and simple select statements with simple filtering. Butterfly Persistence has functionality for:

  • Connection Management
  • Simple JDBC operations
  • Reading data into Java Map instances
  • Reading data into Java objects
  • Automatic mapping of objects to database table columns
  • Annotation based mapping of objects to database table columns
  • Programmatic mapping of objects to database table columns
  • Combinations of the mapping methods

Butterfly Persistence History

Butterfly Persistence was originally created around 2003-2005 under the name Mr. Persister. Later, Mr. Persister was added to a small suite of lightweight Java toolkits I was developing, which I called Butterfly Components. Mr. Persister was renamed to Butterfly Persistence at that time.

Keep in mind that Butterfly Persistence was started around 2005 or so and was maintained for around 5 years or so. However, Butterfly Persistence never really gained that much traction - because at the time everyone wanted JPA and Hibernate. That also explains why the code is not (yet) up-to-date with Maven and the latest Java features.

Today, more than 10 years later, more people appreciate lightweight toolkits, so Butterfly Persistence has gained a "second life" with these enthusiasts.

Butterfly Persistence GitHub Repository

Butterfly Persistence is available in a GitHub repository here:


Installation and Setup

The only thing required to use Butterfly Persistence is that you add the JAR file to the classpath of your application. That is all. All configuration etc. is done from inside your code, so you don't have to mess around with configuration files and JVM parameters.

There is, unfortunately, no Maven distribution of Butterfly Persistence at this point in time, but I might add that in the future.

Creating a PersistenceManager

All actions you need to perform with Butterfly Persistence start from the PersistenceManager. Therefore you will have to create a PersistenceManager instance. Here is how it could look:

public static final PersistenceManager persistenceManager =
    new PersistenceManager();

Notice that the PersistenceManager instance is declared public static final. A lot of things are cached internally in the PersistenceManager instance, like object mappings, sql etc., so you should not create a new instance everytime you need it. Rather you should create a single instance and reuse that throughout the life time of your application. If your application uses more than one database, create one instance per database.

Creating an IDaos

In order to use any of Butterfly Persistence's functions you must create an IDaos instance. An IDaos instance is a collection of utility DAO's you can use to ease the interaction with JDBC and the database. Here is how creating an IDaos instance looks:

IDaos daos = persistenceManager.createDaos();

From the IDaos instance you have access to a database connection and three utility daos: A IJdbcDao, a IMapDao and an IObjectDao. Using these three dao utilities you can interact easily with the database. Here is a simple example:

String insertSql = "insert into persons(name) values(?)";
daos.getJdbcDao().update(insertSql, "John Doe");

This code will run the insert sql statement and replace the ? with the value "John Doe" using a standard PreparedStatement.

Here is an object reading / writing example:

Person person = (Person) daos.getObjectDao().readByPrimaryKey(Person.class, 0);
person.setName("Joe Blocks");

This code will first read the person having primary key 0. Then it will change the name of the read object. Finally the record matching the object in the database is updated to reflect the changed name.

What is Next?

If you like what you have seen so far, you should familiarize yourself with the more advanced features of Butterfly Persistence. It is recommendable to start out reading about connection management, then the JDBC utilities, and finally the object reading and writing utilities. You can get a long way with just connection management and the JDBC utilities, so that's a good place to start.

Jakob Jenkov

Featured Videos

Sponsored Ads

Maildroppa - Smart Email Marketing Solution
Close TOC

All Trails

Trail TOC

Page TOC