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

Supported Isolation Levels

The OJB locking package supports four different isolation level.

• read-uncommitted
• read-committed
• repeatable-read
• serializable
• (none)
• (optimistic)

The object locking isolation levels can be simply characterized as follows:

Uncommitted Reads
Obtaining two concurrent write locks on a given object is not allowed (case 14). Obtaining read locks is allowed even if another transaction is writing to that object (case 13). (Thats why this level is also called dirty reads, because you can read lock objects with an existing write lock).

Committed Reads
Obtaining two concurrent write locks on a given object is not allowed. Obtaining read locks is allowed only if there is no write lock on the given object (case 13).

Repeatable Reads
Same as commited reads, but obtaining a write lock on an object that has been locked for reading by another transaction is not allowed (case 7).

Serializable transactions
As Repeatable Reads, but it is even not allowed to have multiple read locks on a given object (case 6).

The isolation level none and optimistic are self-explanatory:
none - don't lock objects associated with this isolation level
optimistic - don't lock objects associated with this isolation level, because optimistic locking was used instead.
Thus the lock manager will ignore all objects associated with these isolation level.

The proper behaviour of the different locking isolation level is checked by JUnit TestCases that implement test methods for each of the 17 cases specified in the above table. (See code for classes in package org.apache.ojb.broker.locking in OJB test suite).

The semantics of the strategies are defined by the following table:

The table is to be read as follows. The acquisition of a single read lock on a given object (case 1) is allowed (returns True) for all isolationlevels. To upgrade a single read lock (case 2) is also allowed for all isolationlevels. If there is already a write lock on a given object for tx1, it is not allowed (returns False) to obtain a write lock from tx2 for all isolationlevels (case 14).

How to specify locking isolation level

The locking isolation level can be specified global or per class.

The global setting is done in the descriptor-repository element:

<descriptor-repository version="1.0" isolation-level="read-uncommitted"
        proxy-prefetching-limit="50">
...
</descriptor-repository>

The isolation level of a class can be configured with the following attribute to a class-descriptor:

<ClassDescriptor isolation-level="read-uncomitted" ...>
    ...
</ClassDescriptor>

If no isolation-level was specified a default isolation level was used - see interface IsolationLevels. The semantics of isolation levels are described in isolation level section.

Specify the LockManager Implementation

To specify the used lock manager implementation set the LockManagerClass property in OJB.properties file. By default an in memory lock manager is enabled.

LockManagerClass=org.apache.ojb.broker.locking.LockManagerInMemoryImpl
 ...

The LockManager Implementations

Below all LockManager implementations shipped with OJB are listed.

The LockManager implementation can optionally support

• lock timeout: The locked objects of an owner will be released after a specified time
• block timeout: The maximal time to wait for acquire a lock (e.g. when an object was locked by another thread). Implementations which do not support this feature are called non-blocking

LockManagerInMemoryImpl

A non-blocking, single JVM, in-memory LockManager implementation. All LockManager.upgradeLock(...) calls are delegated to write locks. It's a simple and fast implementation.

The timeout of locks is supported. The block timeout is ignored, because it's non-blocking.

LockManagerCommonsImpl

This implementation use the locking part of apache's commons-transaction api. The timeout of locks is currently (OJB 1.0.2) not supported, maybe in further versions. This implementation supports blocking (with deadlock detection) and non-blocking of acquired locks.

LockManagerRemoteImpl

Supports locking in distributed environments based on a servlet. The LockManagerRemoteImpl class delegates all locking calls to a remote servlet (LockManagerServlet). The URL to contact the servlet have to be set in OJB.properties file using the LockServletUrl property, e.g.

LockServletUrl=http://127.0.0.1:8080/ojb-lockserver

To make deployment of the LockManagerServlet on a servlet container easier an Ant target lockservlet-war exist, which will build an example .war file containing all needed files (maybe some useless files) for deployment.
The generated web.xml file look like:

<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>

    <display-name>OJB ODMG Lock Server</display-name>
    <description>
     OJB ODMG Lock Server
    </description>

    <servlet>
        <servlet-name>lockserver</servlet-name>
        <servlet-class>org.apache.ojb.broker.locking.LockManagerServlet</servlet-class>
        <init-param>
            <param-name>lockManager</param-name>
            <param-value>org.apache.ojb.broker.locking.LockManagerInMemoryImpl</param-value>
        </init-param>
        <init-param>
            <param-name>lockTimeout</param-name>
            <param-value>80000</param-value>
        </init-param>
        <init-param>
            <param-name>blockTimeout</param-name>
            <param-value>1000</param-value>
        </init-param>

        <!--load-on-startup>1</load-on-startup-->
    </servlet>

    <!-- The mapping for the webdav servlet -->
    <servlet-mapping>
        <servlet-name>lockserver</servlet-name>
        <url-pattern>/</url-pattern>
    </servlet-mapping>

    <!-- Establish the default list of welcome files -->
    <welcome-file-list>
        <welcome-file>index.jsp</welcome-file>
        <welcome-file>index.html</welcome-file>
        <welcome-file>index.htm</welcome-file>
    </welcome-file-list>
</web-app>

It's possible to use each LockManager implementation as backend of the lock manager servlet - only adapt the lockManager init-param entry in the web.xml file.

What it does

The ODMG-Api allows transactions to lock an object obj as follows:

org.odmg.Transaction.lock(Object obj, int lockMode)

where lockMode defines the locking modes:

org.odmg.Transaction.READ
org.odmg.Transaction.UPGRADE
org.odmg.Transaction.WRITE

A sample session could look as follows:

// get odmg facade instance
Implementation odmg = ...

//get open database
Database db = ...

// start a transaction
Transaction tx = odmg.newTransaction();
tx.begin();

MyClass myObject = ... ;

// lock object for write access
tx.lock(myObject, Transaction.WRITE);

// now perform write access on myObject ...

// finally commit transaction to make changes to myObject persistent
tx.commit();

The ODMG specification does not say if locks must be acquired explicitely by client applications or may be acquired implicitely. OJB provides implicit locking for the application programmers convenience: On commit of a transaction all read-locked objects are checked for modifications. If a modification is detected, a write lock is acquired for the respective object. If automatic acquisition of read- or write-lock failes, the transaction is aborted.

On locking an object to a transaction, OJB automatically locks all associated objects (as part of the persistence by reachability feature) with the same locking level. If application use large object nets which are shared among several transactions acquisition of write-locks may be very difficult. Thus OJB can be configured to aquire only read-locks for associated objects.
You can change this behaviour by modifying the file OJB.properties and changing the entry LockAssociations=WRITE to LockAssociations=READ.

The ODMG specification does not prescribe transaction isolation levels or locking strategies to be used. Thus there are no API calls for setting isolation levels. OJB provides four different isolation levels that can be configured global or for each persistent class in the configuration files.