View source for Software:Carbonado (Java)

{{Infobox software
| logo                   =
| name                   = Carbonado
| developer              = Amazon.com
| latest_release_version = 1.2.3
| latest_release_date    = {{release date|2012|03|04}}
| operating_system       = Cross-platform (JVM)
| platform               = Java Virtual Machine
| programming_language   = [[Java (programming language)|Java]]
| genre                  = Object-Relational mapping
| license                = [[Software:Apache License|Apache License]] 2.0
| website                = [https://github.com/Carbonado/Carbonado github.com/Carbonado/Carbonado]
}}

'''Carbonado''' is an [[Open source|open source]] relational database mapping framework, written in [[Java (programming language)|Java]]. Rather than following a typical [[Object-relational mapping|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 [[Software:Berkeley DB|Berkeley DB]]. In doing so, relational features such as queries and indexes are supported, without the overhead of SQL.

== History ==

Carbonado was originally developed for internal use by Amazon.com, as a revision to an earlier framework. It was released as an [[Software:Apache License|Apache licensed]] open-source project in October 2006.<ref>{{cite web |url=http://www.allthingsdistributed.com/2006/10/carbonado.html |title=Carbonado |last=Vogels |first=Werner |date=26 October 2006 |work=All Things Distributed |accessdate=25 December 2010}}</ref>

== Entity definitions ==

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.
<source lang="java">
 @PrimaryKey("entityId")
 public interface MyEntity extends Storable {
     long getEntityId();
     void setEntityId(long id);
 
     String getMessage();
     void setMessage(String message);
 }
</source>
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|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|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:
<source lang="java">
 Repository repo = ...
 Storage<MyEntity> storage = repo.storageFor(MyEntity.class);
 MyEntity entity = storage.prepare();
</source>
Next, the key properties are set and load is called:
<source lang="java">
 entity.setEntityId(id);
 entity.load();
</source>

== Repository usage ==

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|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.
<source lang="java">
 BDBRepositoryBuilder builder = new BDBRepositoryBuilder();
 builder.setName(name);
 builder.setEnvironmentHome(envHome);
 builder.setTransactionWriteNoSync(true);
 Repository repo = builder.build();
</source>

== Query execution ==
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:
<source lang="java">
 Storage<MyEntity> storage = repo.storageFor(MyEntity.class);
 Query<MyEntity> query = storage.query("message = ?").with(message);
 List<MyEntity> matches = query.fetch().toList();
</source>

== Transactions ==
[[Database transaction|Transactions]] are created from a Repository instance, and they define a [[Thread-local storage|thread-local]] scope. Multiple persist operations are automatically grouped together, and commit must be called to complete the transaction.
<source lang="java">
 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();
 }
</source>
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 ==
<references/>

== External links ==
*[https://github.com/Carbonado/Carbonado Carbonado Home Page]



[[Category:Java platform software]]
[[Category:Persistence]]

{{Sourceattribution|Carbonado (Java)|1}}