Amber aims at relational database persistence with an application-oriented data model.

Goals

• Use Java beans for the application model.
• Leverage JDBC APIs.
• Make persistence connections and transactions explicit
• Simplify configuration files

Java beans as the application model

The application's data model should drive the Java classes and architecture. As much as possible, Amber stays out of the way and defers to the application's needs. At the same time, it must be clear how the objects map to the database.

Persistent objects for Amber have bean-style properties (getXXX and setXXX) which correspond to columns in the database. No additional classes or interfaces are required for Amber. In this respect, Amber is identical to Hibernate's persistence model. Classes designed for Hibernate can be used for Amber without modification.

Amber contrasts with J2EE CMP by eliminating the home and local interfaces and eliminating the special J2EE methods like ejbCreate and ejbPostCreate. Applications using J2EE must twist their data model to fit the J2EE CMP rules, and must deal with the extra interfaces and methods. By eliminating the J2EE complexity, can simplify application code, making it easier and cheaper to design and maintain.

In contrast with JDO, Amber requires bean-style properties and commits to a relational database. For Amber, the database design is primary and the Java model is just a view of the database. JDO aims at making persistence invisible, hiding the existence of the database from the application and bytecode enhancing all field references. By hiding the database, JDO makes the persistence opaque, making the mental model of JDO more complicated. By committing to a relational model, Amber gains the power of the relational queries and keeps the persistence model concrete.

Explicit Persistence

Developers are familiar with obtaining a JDBC Connection from a DataSource, doing some work, and closing the Connection when work is done. Amber's model maps directly to the JDBC model, avoiding a complicated mental model.

The AmberConnection is based on an underlying JDBC Connection. Beans used with the AmberConnection are enlisted with that connection. The connection's close delists the beans. Unregistered beans act like any normal Java object. Only when the application explicitly enlists them with the AmberConnection will they become persistent.

By making the persistence explicit, Amber works at making persistence transparent, not opaque or invisible. Persistence should be a clear box, not a black box. It should be clear to a code reviewer how the application code is persisted without referring to external design documents. With invisible or hidden persistence, it's not always clear how objects are reflected in the database.

In contrast to Amber's explicit persistence connection, J2EE's CMP uses a hidden connection, invisible to the J2EE developer. J2EE beans are enlisted and delisted automatically: magic occuring behind the J2EE stub. By hiding its connection and bean instance, J2EE requires a more complicated mental model for even the most simple beans.

Amber's explicit model not only makes it easier to learn, but makes application code easier to debug and maintain. Because the connection is explicit, it's visible in the code. With an explicit connection a code review can follow the persistence just by inspecting the code.

JDBC APIs

Amber uses JDBC classes like ResultSet both to simplify the interfaces and to take advantage of database driver capability. Since the ResultSet can already flexibly scan through results and return columns in their proper types, there's no need to invent a new API.

To handle objects, Amber implements the ResultSet.getObject method to return the loaded object.

AmberConnection conn = ...;

ResultSet rs = conn.query("SELECT o FROM qa.Test o WHERE o.data='test-data'");

while (rs.next()) {
  ...
}

Configuration Files

Amber follows the JPA specification and supports persistence.xml and orm.xml configuration files.