2011/01/16 - Apache ObJectRelationalBridge has been retired.

The ImplementationExt Interface

The OJB extension of the odmg Implementation interface is called ImplementationExt and provide additional methods missed in the standard class definition.

• get/setOqlCollectionClass
  Use this methods to change the used OQL query result class at runtime. Description can be found in Configuration Properties section and in javadoc of ImplementationExt.
• is/setImpliciteWriteLocks
  Use this methods to global change the associated locking type at runtime when implicit locking is used. Description can be found in Configuration Properties section and in javadoc of ImplementationExt.
• is/setOrdering
  Use this methods to global enable/disable OJB's object ordering algorithm. Description can be found in Configuration Properties section and in javadoc of ImplementationExt.

The TransactionExt Interface

The OJB extension of the odmg Transaction interface is called TransactionExt and provide additional methods missed in the standard class definition.

• markDelete
  Description can be found in javadoc of TransactionExt.
• markDirty
  Description can be found in javadoc of TransactionExt.
• flush
  Description can be found in javadoc of TransactionExt.
• is/setImplicitLocking
  Description can be found in javadoc of TransactionExt.
• is/setOrdering
  Description can be found in javadoc of TransactionExt.
• setCascadingDelete
  Description can be found in javadoc of TransactionExt.
• getBroker()
  Returns the current used broker instance. Usage example is here.

The EnhancedOQLQuery Interface

The OJB extension of the odmg OQLQuery interface is called EnhancedOQLQuery and provide additional methods missed in the standard class definition.

• create(String queryString, int startAtIndex, int endAtIndex)
  Description can be found in javadoc of EnhancedOQLQuery.

Access the PB-api within ODMG

As the PB-api was used by OJB's ODMG-api implementation, thus it is possible to get access of the used PersistenceBroker instance using the extended Transaction interface class TransactionExt:

Implementation odmg = ...;
TransactionExt tx = (TransactionExt) odmg.newTransaction();
tx.begin();
...
PersistenceBroker broker = tx.getBroker();
// do work with broker
...
tx.commit();

It's mandatory that the used PersistenceBroker instance never be closed with a PersistenceBroker.close() call or be committed with PersistenceBroker.commitTransaction(), this will be done internally by the ODMG implementation.

Transactions

The ODMG API uses object-level transactions, compared to the PersistenceBroker database-level transactions. An ODMG Transaction instance contains all of the changes made to the object model within the context of that transaction, and will not commit them to the database until the ODMG Transaction is committed. At that point it will use a database transaction (the underlying PB-api) to ensure atomicity of its changes.

Locks

The ODMG specification includes several levels of locks and isolation. These are explained in much more detail in the Locking documentation.

In the ODMG API, locks obtained on objects are locked within the context of a transaction. Any object modified within the context of a transaction will be stored with the transaction, other changes made to the same object instance by other threads, ignoring the lock state of the object, will also be stored - so take care of locking conventions.
The ODMG locking conventions (obtain a write lock before do any modifications on an object) ensure that an object can only be modified within the transaction.

It's possible to configure OJB's ODMG implementation to support implicit locking with WRITE locks. Then a write lock on an object forces OJB to obtain implicit write locks on all referenced objects. See configuration properties.

Persisting Non-Transactional Objects

Frequently, objects will be modified outside of the context of an ODMG transaction, such as a data access object in a web application. In those cases a persistent object can still be modified, but not directly through the OMG ODMG specification. OJB provides an extension to the ODMG specification for instances such as this. Examine this code:

public static void persistChanges(Product product)
{
    Implementation impl = OJB.getInstance();
    TransactionExt tx = (TransactionExt) impl.newTransaction();

    tx.begin();
    tx.markDirty(product);
    tx.commit();
}

In this function the product is modified outside the context of the transaction, and is then the changes are persisted within a transaction. The TransactionExt.markDirty() method indicates to the Transaction that the passed object has been modified, even if the Transaction itself sees no changes to the object.

Examples

In OJB test-suite is a test case called org.apache.ojb.odmg.NamedRootsTest which shown similar examples as below, but more detailed.

1. Persist a serializable object as named object

We want to persist a name list of all planets:

Transaction tx = odmg.newTransaction();
tx.begin();
List planets = new ArrayList();
example.add("Mercury");
example.add("Venus");
example.add("Earth");
...
database.bind(planets, "planet-list");
tx.commit();

The specified List with all planet names will be serialized and persisted as VARBINARY object.

To lookup the persisted list of the solar system planets:

Transaction tx = odmg.newTransaction();
tx.begin();
List planets = (List) database.lookup("planet-list");
tx.commit();

To remove the persistent list do:

Transaction tx = odmg.newTransaction();
tx.begin();
database.unbind("planet-list");
tx.commit();

2. Persist a persistence capable object as named object

We want to create a named object representing a persistence capable Article object (Article class is declared in OJB metadata mapping):

Transaction tx = odmg.newTransaction();
tx.begin();
// get existing or a new Article object
Article article = ....
database.bind(article, "my-article");
tx.commit();

OJB first checks if the specified Article object is already persisted - if not it will be persisted. Then based on the Article object Identity the named object will be persisted. So the persistent named object is a link to the persistent real Article object.

On lookup of the named object the real Article instance will be returned:

Transaction tx = odmg.newTransaction();
tx.begin();
Article article = (Article) database.lookup("my-article");
tx.commit();

On unbind of the named object only the link to the real Article object will be removed, the Article itself will not be touched.
To remove the named object and the Article instance do:

tx.begin();
// this only remove the named object link, the Article object
// itself will not be touched
database.unbind("my-article");
// thus delete the object itself too
database.deletePersistent(article);
tx.commit();

3. Persist a collection of persistence capable object as named object

We want to persist a list of the last shown Article objects. The Article class is a persistence capable object (declared in OJB metadata mapping). Thus we don't want to persist a serialized List of Article objects (because the real Article object may change), as shown in example 1, rather we want to persist a List that links to the real persistent Article objects.
This is possible when the ODMG DCollections are used:

// get the list with last shown Article objects
List lastArticles = ...
Transaction tx = odmg.newTransaction();
tx.begin();
// obtain new DList instance from Implementation class
DList namedArticles = odmg.newDList();
// push Articles to DList
namedArticles.addAll(lastArticles);
database.bind(namedArticles, "last-shown");
tx.commit();
                

In this case OJB first checks for transient Article objects and make these new objects persistent, then based on the Article object Identity the named object will be persisted. So the persistent named object is in this case a list of links to persistent Article objects.

On database.lookup("last-shown") the DList will be returned and when access the list entries the Article objects will be materialized.

To remove the named object some more attention is needed:

tx.begin();
DList namedArticles = ...
// we want to completely remove the named object
// the persisted DList with all DList entries,
// but the Article objects itself shouldn't be deleted:
// 1. mandatory, clear the list to remove all entries
namedArticles.clear();
// 2. unbind named object
database.unbind("last-shown");
tx.commit();

After this the named object will be completely removed, but all Article object will be untouched.

Disable OJB's object ordering, determine object order "by hand"

By default OJB try to order all persistent objects on transaction commit call to avoid ordering problems. If this is not needed or helpful it can be disabled in two ways.
In most cases it's needed to disable implicite locking too, because it will lock/register dependend objects (e.g. 1:n references) automatically. First in OJB.properties file:

# Enable/Disable OJB's persistent object ordering algorithm on commit
# of a transaction. If enabled OJB try to calculate a valid order for
# all new/modified objects (and referenced objects).
# If the used databases support 'deferred checks' it's recommended to use this
# feature and to disable OJB's object ordering.
# This setting can be changed at runtime using OJB's ODMG extensions.
Ordering=false
                

Second at runtime, using OJB's ODMG extension classes ImplementationExt (global setting) and TransactionExt (per tx setting).

TransactionExt tx = (TransactionExt) odmg.newTransaction();
tx.begin();
...
/*
we want to manually insert new object, so we disable
OJB's ordering and implicit object locking
*/
tx.setOrdering(false);
tx.setImplicitLocking(false);
...
tx.commit();
                

Circular- and Bidirectional References

The good news, OJB can handle bidirectional- and circular- references. When using foreign key constraints for referential integrety in these cases you have to pay attention.

In OJB test-suite a unit test called org.apache.ojb.odmg.CircularTest can be found. The tests show the handling of circular/bidirectional references and the possibilities how to handle object insert/update/delete ordering on transaction commit.

I don't like OQL, can I use the PersistenceBroker Queries within ODMG

Yes you can! The ODMG implementation relies on PB Queries internally! Several users (including myself) are doing this.

If you have a look at the simple example below you will see how OJB Query objects can be used withing ODMG transactions.
The most important thing is to lock all objects returned by a query to the current transaction before starting manipulating these objects.
Further on do not commit or close the obtained PB-instance, this will be done by the ODMG transaction on tx.commit() / tx.rollback().

TransactionExt tx = (TransactionExt) odmg.newTransaction();
tx.begin();
....
// cast to get intern used PB instance
PersistenceBroker broker = tx.getBroker();
...
// build query
QueryByCriteria query = ...
// perform PB-query
Collection result = broker.getCollectionByQuery(query);
// use result
...

tx.commit();
...

Note: Don't close or commit the used broker instance, this will be done by the odmg-api.

How to use multiple Databases

For each database define a jdbc-connection-descriptor same way as described in the FAQ.

Now it is possible to

• access the databases one after another, by closing the current used Database instance and by open a new one.

  // get current used database instance
  Database database = ...;
  // close it
  database.close();
  // open a new one
  database = odmg.newDatabase();
  database.open("jcdAliasName#user#password", Database.OPEN_READ_WRITE);
  ...

  The Database.close() call close the current used Database instance, after this it is possible to open a new database instance.

• use multiple databases in parallel, by creating a separate Implementation and Database instance for each jdbc-connection-descriptor defined in the mapping metadata.

  Implementation odmg_1 = OJB.getInstance();
  Database database_1 = odmg.newDatabase(); 
  database.open("db_1#user#password", Database.OPEN_READ_WRITE);
  
  Implementation odmg_2 = OJB.getInstance();
  Database database_2 = odmg.newDatabase();
  database.open("db_2#user#password", Database.OPEN_READ_WRITE);
                          

  Now it's possible to use both databases in parallel.