Introducing jPersist
Overview
jPersist is an extremely powerful object-relational persistence API that is based on the active-record and data-mapper patterns.
jPersist is as easy as:
public static void main(String[] args)
{
DatabaseManager dbm;
dbm = new DatabaseManager("example", 5, "com.mysql.jdbc.Driver",
"jdbc:mysql://localhost/example",
null, null, "username", "password");
Customer customer = new Customer(“Smith”);
if ((customer = dbm.loadObject(customer)) != null)
{
customer.setLastName(“Smithman”);
dbm.saveObject(customer);
}
dbm.saveObject(new Customer("dbuser1", "passwd", "Dave"));
}
public class Customer [extends PersistentObject or Entity] // optional
{
String lastName;
...
public Customer(String lastName) { this.lastName = lastName; }
...
public getLastName() { return lastName; }
public setLastName(String lastName) { this.lastName = lastName; }
…
}
Just doesn’t get easier. If you’re familiar with ORMs (Hibernate, JPA, etc.), then the first thing you might wonder about is the configuration and/or annotations. With jPersist there is no need for configuration and/or annotations. jPersist is mapless, in that it has no need for XML or annotation-based mapping. In reality jPersist has automatic mapping. jPersist looks at both your class definition and database table definition and automatically figures out what needs to happen when inserting, updating, querying, and deleting.
jPersist wraps and uses JDBC functionality and can work with any relational database, and any type of connection resource, including: java.sql.DriverManager, JNDI, javax.sql.DataSource, and third-party connection pooling libraries (DBCP, C3PO, etc.). jPersist has full support for database transactions and automatically handles transactions with all relationships (inheritance and associations). Transactions can also be handled with the jpersist.TransactionManager class or manually with beginTransaction(), endTransaction(), commit() and rollback() functionality. jPersist automatically handles inheritance via multi-table joins, but also supports single-table and concrete-table inheritance. jPersist easily handles associations with support for arrays, collections, and single-instance objects. With jPersist, all JDBC functionality is supported and available.
jPersist has a database manager class (jpersist.DatabaseManager) that handles pooling of its own resources as well as managing JDBC data sources and connections, as needed (including connection pooling and third party connection pooling libraries). The database manager also provides several object-oriented access methods (by wrapping jpersist.Database and jpersist.Result calls) that allow queries, inserts, updates, deletes, etc., in a single line of code.
While jpersist.DatabaseManager provides several convenience methods for accessing your data, the real power resides in the jpersist.Database and jpersist.Result classes.
An instance of jpersist.Database is retrieved with DatabaseManager’s getDatabase() method. The jpersist.Database and jpersist.Result classes can serve any of the database access needs you may have, from working with stored procedures that return multiple result sets, to automatically loading simple and complex object hierarchies.
An example of using jpersist.Database and jpersist.Result:
Database db = dbm.getDatabase();
Result<Customer> result = db.queryObject(Customer.class);
for (Customer customer : result)
{
System.out.println(customer);
}
db.close();
jpersist.Database has several methods (all JDBC provides) to easily handle transactions, for example:
Database db = dbm.getDatabase();
db.beginTransaction();
try
{
db.saveObject(new YourObject(...));
}
catch (YourException e)
{
db.rollback();
}
finally
{
db.endTransaction(); // also commits transaction
}
You can also use the methods commit(),getSavepoint(), and rollback(). And they can be called at anytime.
jPersist also has a transaction manager class that allows the following:
new TransactionManager(dbm)
{
public void run() throws JPersistException
{
new Contact("alincoln", "Abraham", "Lincoln", ...).save(this);
// or
getDatabase().saveObject(new Contact("alincoln", "Abraham", ...));
// or just
saveObject(new Contact("alincoln", "Abraham", ...));
...
}
}.executeTransaction();
All in all, jPersist’s sole reason for being is to provide simple trouble-free POJO oriented access to your database data. With jPersist and your POJOs, you should rarely have to do anything more than:
- Define a POJO (optionally extending jpersist.PersistentObject), which can be extended by other POJOs (relational hierarchy via joins).
- Call one of jpersist.DatabaseManager’s: loadObject(), saveObject(), and deleteObject(), or one of jpersist.Database’s: saveObject(), deleteObject(), and queryObject() with jpersist.Result’s loadObject().
- Group saves and deletes in a transaction using jpersist.TransactionManager or jpersist.Database’s transaction oriented methods.
- Most likely process a query result with:
while (result.hasNext())
{
MyObject myObj = result.next();
...
}
That’s not to say you won’t have other JDBC needs, like calling stored procedures or executing SQL statements, but with jPersist it’s all easy to handle.
Requirements
jPersist requires Java 1.2 or above and a database with JDBC support.
Java Support
jPersist has two JAR versions available; one for pre 1.5 environments, and one for 1.5+ environments. Both have the same functionality. However, the Java 1.5+ version allows for generics, annotations, variable arguments, dynamic casting, etc. where appropriate.
Supported Databases
Right now our focus is on adding support for as many databases as we can, and jPersist currently has complete, and fully tested, support for:
MySQL
DB2
Oracle
Derby
HSQL
PostgreSQL
H2
You should be able to use jPersist’s complete functionality, without issue, with these databases. Of course, there is varying support from vendor to vendor for JDBC features. If your vendor doesn’t support a certain feature (stored procedures, bi-directional cursors, etc.), you’ll find the same is true with jPersist, as it wraps JDBC.
Logging
jPersist uses Java logging and can be set with:
DatabaseManager.setLogLevel(Level);
With logging set to Level.FINE, you can see the SQL that is generated for your objects. You can also access the root logger with “jpersist”.
