Repository Locking

Overview

The repository lock mechanism ensures that only one Jackrabbit instance can open the same repository at one time. By default, when a repository is started, Jackrabbit tries to create a file named .lock in the repository home directory and protects it using using a native file lock. If the repository is already in use, this will fail, usually with one of the following exceptions / entries in the log file:

Existing lock file at  ../.lock detected. Repository was not shut down properly.
javax.jcr.RepositoryException: 
The repository home ... appears to be in use since the file named .lock is locked by another process.
or
The repository home ... appears to be in use since the file named .lock is already locked by the current process.
or
OverlappingFileLockException

In the first case, the repository is already open in another process. Please stop the other process first.

In the second and third case, the repository is already open in the same process but within another class loader (for example, in another web application). In this case you need to ensure that the repository is closed when the web-application is stopped.

Why Is the Repository Locked

Jackrabbit works like a file system or database: to improve performance, Jackrabbit caches frequently used data, and keeps transient changes in memory until they are saved explicitly. Therefore, to avoid inconsistencies and corruption, it must be ensured that the same repository is only accessed by one process at a time.

How to Access the Repository from Multiple Processes

Jackrabbit supports multiple Deployment Models. To access the same repository from multiple computers or processes, use a Repository Server.

An alternative is to use Clustering.

When to Manually Delete the Lock File

Deleting the lock file manually is normally not necessary, even if the repository was not closed before.

The only case where it may be required to manually delete the repository lock file is when using an NFS share (for some NFS implementations), and the NFS server died and was re-started. Some NFS servers will not release the file lock in this case.

Using the Cooperative File Lock Mechanism

Since Jackrabbit 1.6 an alternative repository locking mechanism is available.

Some NFS implementations do not release native locks after a hard reboot. In this case the workaround is to manually delete all .lock files. Older NFS implementation throw the exception "No locks available", which means the NFS does not support native file locks.

To solve this problem, Jackrabbit also supports cooperative file locking. This mechanism is not based on native file locks, but instead uses background threads that periodically update a sentinel file (lock.properties). The algorithm of cooperative file locking is described below. To use cooperative file locking, add this to your repository.xml before the </Repository> tag:

<RepositoryLockMechanism class="org.apache.jackrabbit.core.util.CooperativeFileLock" />

Cooperative File Locking Algorithm

The cooperative file locking works as follows:

RepositoryLock (last edited 2010-01-04 11:18:08 by ThomasMueller)