Java Doc for LockFile.java in  » Database-DBMS » hsql » org » hsqldb » persist » Java Source Code / Java DocumentationJava Source Code and Java Documentation

1. A file with a well-known path relative to each database instance is used to implement cooperative locking of database files across process boundaries (database instances running in different JVM host processes) and class loader contexts (databases whose classes have been loaded by distinct class loaders such that their open database repositories are distinct and are inaccessible across the class loader context boundaries).

2. A background thread periodically writes a timestamp to this object's lock file at LockFile.HEARTBEAT_INTERVAL millisecond intervals, acting as a heartbeat to indicate that a lock is still held.

3. The generic lock attempt rules are:
   • If a lock condition is already held by this object, do nothing and signify that the lock attempt was successful, else...

   • If no lock file exists, go ahead and create one, silently issue the java.io.File.deleteOnExit File.deleteOnExit() directive via refelective method invocation (in order to stay JDK 1.1 compliant), schedule a periodic heartbeat task and signify that the lock attempt was successful, else...

   • The lock file must already exist, so try to read its heartbeat timestamp. If the read fails, assume that a lock condition is held by another process or a database in an inaccessible class loader context and signify that the attempt failed, else if the read value is less than HEARTBEAT_INTERVAL milliseconds into the past or futuer, assume that a lock condition is held by another process or a database in an inaccessible class loader context and signify that the lock attempt failed, else assume that the file is not in use, schedule a periodic heartbeat task and signify that the lock attempt was successful.

4. The generic release attempt rules are:
   • If a lock condition is not currently held, do nothing and signify that the release attempt was successful, else...

   • A lock condition is currently held, so try to release it. By default, releasing the lock condition consists of closing and nullifying any objects that have a file descriptor open on the lock file. If the release is successful, cancel the periodic heartbeat task and signify that the release succeeded, else signify that the release attempt failed.

In addition to the generic lock and release rules, the protected methods LockFile.lockImpl() lockImpl() and LockFile.releaseImpl() releaseImpl() are called during lock and release attempts, respectively. This allows transparent, JDK 1.1 compliant integration of extended strategies for locking and releasing, based on subclassing and reflective construction of such specializations in the factory method LockFile.newLockFile newLockFile() , determined by information gathered at run-time.

In particular, if it is available at runtime, then newLockFile() retrieves instances of org.hsqldb.NIOLockFile NIOLockFile to capitalize, when possible, on the existence of the java.nio.channels.FileLockFileLock class. If the NIOLockFile class does not exist at run-time or the java.nio classes it uses are not supported under the run-time JVM, then newLockFile() produces vanilla LockFile instances, meaning that only purely cooperative locking takes place, as opposed to possibly O/S-enforced file locking which, at least in theory, is made available through the java.nio.channels package). However, it must be noted that even if a JVM implementation provides the full java.nio.channels package, it is not absolutely required to guarantee that the underlying platform (the current operating system) provides true process-wide file locking.

Note:

The NIOLockFile descendent exists because it has been determined though experimenatation that java.nio.channels.FileLock does not always exhibit the correct/desired behaviour under reflective method invocation. That is, it has been discovered that under some operating system/JVM combinations, after calling FileLock.release() via a reflective method invocation, the lock is not released properly, deletion of the lock file is not possible even from the owning object (this) and it is impossible for other LockFile instances or any other objects or processes to successfully obtain a lock condition on the lock file, despite the fact that the FileLock object reports that its lock is invalid (was released successfully). Frustratingly, this condition appears to persist until full exit of the JVM process in which the FileLock.tryLock() method was reflectively invoked.

To solve this, the original LockFile class was split in two and instead of reflective method invocation, reflection-based class instantiation is now performed at the level of the newLockFile() factory method. Similarly, the HSQLDB ANT build script detects the presence or abscence of JDK 1.4 features such as java.nio and only attempts to build and deploy NIOLockFile to the hsqldb.jar if such features are reported present.

This RandomAccessFile is used to periodically write out the heartbeat timestamp to this object's lock file.

 this == other ||
 this.f == null ? other.f == null : this.f.equals(other.f);
 

Parameters:
  obj - the reference object with which to compare. true if this object is equal tothe obj argument;false otherwise.
See Also:   LockFile.hashCode

throws:
  Throwable - if this object encounters an unhandled exceptiontrying to release the lock condition,if any, that it has on its lock file.

a hash code value for this object.
See Also:   LockFile.equals(java.lang.Object)

Note: Due to the retrictions placed on the JVM by platform-independence, it is very possible to successfully obtain and hold a cooperative lock on a lock file and yet for the lock to become invalid while held.

For instance, under JVMs with no java.nio package or operating systems that cannot live up to the contracts set forth for java.nio.channels.FileLock FileLock , it is quite possible for another process or even an uncooperative bit of code running in the same JVM to delete or overwrite the lock file while this object holds a lock on it.

Because of this, the isValid() method is provided in the public interface in order to allow clients to detect such situations.

true iff this object has successfully obtainedand is currently holding (has not yet released)a lock on its lock file
See Also:   LockFile.isValid

More formally, this method retrieves true iff:

 isLocked() &&
 f != null &&
 f.exists() &&
 raf != null
 

Descendents are free to provide additional functionality here, using the following rules:

 PRE:
 This method is only called if tryLock() thinks it needs to get a lock
 condition, so it can be assumed the locked == false upon entry, raf is
 a non-null instance that can be used to get a FileChannel if desired,
 and the lock file is, at the very least, readable.  Further, this
 object's heatbeat task is definitely cancelled and/or has not yet been
 scheduled, so whatever timestamp is recorded in the lock file, if it
 exists, is what was written by a previous locker, if any.  A timestamp
 value in a preexisting file is only considered valid if the file is
 of the correct length and its first eight bytes are
 the value 
LockFile.MAGIC MAGIC .
 POST:
 This method must return false if any additional locking work fails,
 else true.
 

throws:
  Exception - if a situation is encountered that absolutelyprevents the status of the lock condtionto be determined. (e.g. an IO exceptionoccurs here) true if no extended lockingactions are taken or the actions succeed,else false.

a LockFile instance initialized with aFile object whose path is the one specifiedby the path argument.
Parameters:
  path - the path of the File object withwhich the retrieved LockFileobject is to be initialized

true if there are no specialized releaseactions performed or they succeed,else false
throws:
  Exception - if a situation is encountered that absolutelyprevents the status of the lock condtionto be determined. (e.g. an IO exceptionoccurs here).

The String is of the form:

 super.toString() +
 "[file=" + getAbsolutePath() +
 ", exists=" + f.exists() +
 ", locked=" + isLocked() +
 ", valid=" + isValid() +
 ", " + toStringImpl() +
 "]";
 

The default implementation returns the empty string. an implementation-specific tail value for the toString() method
See Also:   LockFile.toString

throws:
  Exception - if an error occurs that absolutely prevents the lockstatus of the lock condition from being determined(e.g. an unhandled file I/O error). true if this object already holds a lock orthe lock was obtained successfully, elsefalse

throws:
  Exception - if an error occurs that absolutely preventsthe status of the lock condition frombeing determined (e.g. an unhandled fileI/O exception). true if this object does not hold alock or the lock is released successfully,else false.