Brief History and Introduction

Abra is a Java library and a set of tools that can be used for storing and retrieving Java object in a relational database. We developed Abra while working at a Wall Street startup from summer of 2000 until spring of 2001. Unfortunately the startup went bust in the summer of 2001 (the investors got cold feet).

Fortunately we were allowed to release Abra as open source package under the BSD style license, as this package had nothing to do with core bussiness of the aforementioned startup.

Abra grew out as a solution to the problem of persisting Java objects in a relational database. Very early on we realized that we needed a simple persistence layer and that we did not want to hand write any SQL.

We looked at several packages (eg. Castor, TopLink, CocoBase), but none seemed to fit our purpose and given immense scheduling pressure we decided to grow the persistence layer ourselves, as we went along building the system.

Major Design Decisions

We were greatly inspired by several excellent articles on persistence layer design by Scott Ambler (see links below). We adapted several of his design suggestions with excellent results. We also wanted to keep things simple and to be able automatically generate all the tedious code (like the SQL/JDBC calls etc).

• Mapping - We picked simple mapping of classes to tables. Only leaf classes of an inheritance hierarchy get mapped to tables and the mapping is canonical. That is each attribute of a class is mapped to one column.
• Object Ids - Every object in the database has a unique (for it's type) object ID. The object ID is used as a database "pointer" to express relationships between objects and has no other bussiness meaning (this is straight out of Ambler).
• Data Classes - A single XML configuration file describes all persistent objects and the actual mapping of attributes to tables (this idea was "stolen" from the Castor project). We wanted to generate the code for all persistent classes based on this file. Therefore we decided to make the persistent classes very simple, they only hold data and have getter and setter methods.
• Factory Classes - Data classes contain no database code. Factory classes (which are partially generated) are used to store and retrieve objects from the database, and all the database specific code goes into the factories.
• Relationships - One to one relationships are represented as plain Java references. One to many relationships are represented as vectors of objects and many to many require usage of special ManyToMany factories that provide the appropriate retrieval methods.
• Views - It is possible to define read-only views of data objects. A view is simply another Java class that includes a subset of attributes of its source class. Sometimes view objects can be returned by queries (in case the full object is to complex and you only need pieces of it for display purposes).

Main Features

• XML configuration files drive generation of Java classes and database schema. The meta-data from XML can also be used to marshall the generated classes to and from XML.
• Uses JDBC to access the database. All SQL code is generated in factory classes. Queries are build up using Java objects (Filter classes) and SQL "where" clauses are created dynamically at run time.
• Works with Oracle and PostgreSql, MySql, DB2/UDB, Sybase (as of 9/02), (DB2/400 interface in the works by Eric Meritt(2/02))
• Simple mapping between database tables and Java objects, that supports one to one, one to many and many to many relationships.
• Simple (but extensible) transaction management. Per transaction caches.
• Can be used in large scale distributed applications - provides for consistent view of database data (latest data becomes available when locks are obtained).

Extra Features

• XMLMarshaller which using the XML map file can go to/from XML to the data classes defined.
• Validation can be described in the XML configuration file and drive generation of Validators within a simple data-validation framework.
• Simple composites (ie Amount(CurrencyCode:String;value:double)) can be inlined in the container object (so as to reduce the number of tables/joins).
• A fast XML Parser using the JavaCup package which can be used instead of Xerces in generation and marshalling.
• Ever Growing set of junit-tests.

In the Works

• Dtd->Mapfile generator :: a Dtd does not contain as much info as our Mapfile, so convert a Dtd into our mapfile, which will proved Java classes for each Dtd node, and the ability to marshal to and from them.

Documentation

Mailing list

Links

• Browse CVS
• Current Download
• Castor Project
• Scott Ambler articles.

Comments

Hosted on SourceForge.

Last updated on: 2002-Mar-05

Visited: