Carbonado

Developer(s)	Amazon.com
Stable release	1.2.3 / March 4, 2012 (2012-03-04)
Repository	github.com/carbonado/carbonado
Written in	Java
Operating system	Cross-platform (JVM)
Platform	Java Virtual Machine
Type	Object-Relational mapping
License	Apache License 2.0
Website	github.com/Carbonado/Carbonado

Carbonado is an open source relational database mapping framework, written in Java. Rather than following a typical O/R mapping approach, the relational model is preserved, while still being object-oriented. Not being tied to specific features of SQL or JDBC, Carbonado also supports non-SQL database products such as Berkeley DB. In doing so, relational features such as queries and indexes are supported, without the overhead of SQL.

History[edit]

Carbonado was originally developed for internal use by Amazon.com, as a revision to an earlier framework. It was released as an Apache licensed open-source project in October 2006.^[1]

Entity definitions[edit]

Relational entities are known as Storables in Carbonado, and they are defined by an interface or abstract class. Annotations are required to specify features which cannot be defined by Java interface alone. Every Storable must have an annotation describing the primary key of the entity.

 @PrimaryKey("entityId")

 public interface MyEntity extends Storable {

     long getEntityId();

     void setEntityId(long id);

 

     String getMessage();

     void setMessage(String message);

 }

Carbonado Storables are not pure POJOs, and they must always extend the Storable superclass. By doing so,
they gain access to various methods built into it. A Storable definition may also contain business logic, following the active record pattern.

The actual implementation of the Storable is generated at runtime by Carbonado itself. The standard object methods of toString, equals and hashCode are also generated. This greatly simplifies the process of defining new entities, since no boilerplate code needs to be written.

The process of loading a Storable by key starts by calling a factory method to create an uninitialized instance:

 Repository repo = ...

 Storage<MyEntity> storage = repo.storageFor(MyEntity.class);

 MyEntity entity = storage.prepare();

Next, the key properties are set and load is called:

 entity.setEntityId(id);

 entity.load();

Repository usage[edit]

A Repository is a gateway to the underlying database. A few core implementations are available, which include:

• JDBC access


• Berkeley DB


• Berkeley DB Java Edition


• An in memory database

In addition, composite Repositories exist which support simple replication and logging.

All Repositories are created using a builder pattern. Each type of builder supports options specific to the Repository type. When a Repository instance is built, it only adheres to the standard interface. Access to specific features is provided by a Capability interface.

 BDBRepositoryBuilder builder = new BDBRepositoryBuilder();

 builder.setName(name);

 builder.setEnvironmentHome(envHome);

 builder.setTransactionWriteNoSync(true);

 Repository repo = builder.build();

Query execution[edit]

Carbonado queries are defined by a simple filter expression and an order-by specification. Compared to SQL, the filter closely resembles a "where" clause. Filters can include joined properties and they may also include sub filters. This simple example queries for entities with a given message:

 Storage<MyEntity> storage = repo.storageFor(MyEntity.class);

 Query<MyEntity> query = storage.query("message = ?").with(message);

 List<MyEntity> matches = query.fetch().toList();

Transactions[edit]

Transactions are created from a Repository instance, and they define a thread-local scope. Multiple persist operations are automatically grouped together, and commit must be called to complete the transaction.

 Transaction txn = repo.enterTransaction();

 try {

     MyEntity entity = storage.prepare();

     entity.setEntityId(1);

     entity.setMessage("hello");

     entity.insert();

 

     entity = storage.prepare();

     entity.setEntityId(2);

     entity.setMessage("world");

     entity.insert();

 

     txn.commit();

 } finally {

     txn.exit();

 }

This design approach shows how Carbonado is not like an O/R mapping framework. Such frameworks typically hide the concept of transactions entirely, often by using sessions which track changes. In Carbonado, all actions are direct.

Notes[edit]

External links[edit]

• Carbonado Home Page