World Library  
Flag as Inappropriate
Email this Article

Carbonado (Java)

Article Id: WHEBN0017722081
Reproduction Date:

Title: Carbonado (Java)  
Author: World Heritage Encyclopedia
Language: English
Subject:, Amazon Standard Identification Number, Tom Szkutak, Amazon Cloud Drive, Amazon CloudFront
Collection: Amazon.Com, Java Platform Software, Persistence
Publisher: World Heritage Encyclopedia

Carbonado (Java)

Stable release 1.2.3 / March 4, 2012 (2012-03-04)
Written in Java
Operating system Cross-platform (JVM)
Platform Java Virtual Machine
Type Object-Relational mapping
License Apache License 2.0

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 1
  • Entity definitions 2
  • Repository usage 3
  • Query execution 4
  • Transactions 5
  • Notes 6
  • External links 7


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

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 defined by Java interface alone. Every Storable must have an annotation describing the primary key of the entity.

 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 storage = repo.storageFor(MyEntity.class);
 MyEntity entity = storage.prepare();

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


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. 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();
 Repository repo =;

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:

 Storage storage = repo.storageFor(MyEntity.class);
 Query query = storage.query("message = ?").with(message);
 List matches = query.fetch().toList();


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 = storage.prepare();
 } finally {

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.


  1. ^

External links

  • Carbonado Home Page

This article was sourced from Creative Commons Attribution-ShareAlike License; additional terms may apply. World Heritage Encyclopedia content is assembled from numerous content providers, Open Access Publishing, and in compliance with The Fair Access to Science and Technology Research Act (FASTR), Wikimedia Foundation, Inc., Public Library of Science, The Encyclopedia of Life, Open Book Publishers (OBP), PubMed, U.S. National Library of Medicine, National Center for Biotechnology Information, U.S. National Library of Medicine, National Institutes of Health (NIH), U.S. Department of Health & Human Services, and, which sources content from all federal, state, local, tribal, and territorial government publication portals (.gov, .mil, .edu). Funding for and content contributors is made possible from the U.S. Congress, E-Government Act of 2002.
Crowd sourced content that is contributed to World Heritage Encyclopedia is peer reviewed and edited by our editorial staff to ensure quality scholarly research articles.
By using this site, you agree to the Terms of Use and Privacy Policy. World Heritage Encyclopedia™ is a registered trademark of the World Public Library Association, a non-profit organization.

Copyright © World Library Foundation. All rights reserved. eBooks from World eBook Fair are sponsored by the World Library Foundation,
a 501c(4) Member's Support Non-Profit Organization, and is NOT affiliated with any governmental agency or department.