- Butterfly Persistence
- Butterfly Persistence Connection Management
- Butterfly Persistence JDBC DAO
- Butterfly Persistence Map DAO
- Butterfly Persistence Object DAO
- Butterfly Persistence Auto Object Mapping
- Butterfly Persistence Annotation Based Object Mapping
- Butterfly Persistence Programmatic Object Mapping
- Butterfly Persistence Combining Object Mapping Methods
- Butterfly Persistence Partial Object Reading and Writing
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 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 daos = persistenceManager.createDaos();
IDaos instance you have access to a database connection and three
utility daos: 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
Here is an object reading / writing example:
Person person = (Person) daos.getObjectDao().readByPrimaryKey(Person.class, 0); person.setName("Joe Blocks"); daos.getObjectDao().update(person);
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.