corina.site
Class Lock

java.lang.Object
  |
  +--corina.site.Lock

public class Lock
extends Object

A file locking mechanism, requiring nothing beyond what is provided by Java 1.1. This uses the atomicity guaranteed by File.createNewFile(). (The lockfile it creates for a file called "Data" would be called "Data - locked". If Corina gets wedged, you can delete it by hand.)

It's appropriate for a relatively low-utilization fileserver where one filesystem is shared by multiple users. For lock a single file in one JVM, use class methods and members, not the filesystem; for heavy-duty locking, use a real database (which is more robust, and probably higher performance).

Please do not write a native version of this. Java's createNewFile() method guarantees atomicity, and it will work on any platform, so (for example) Mac and Windows workstations using a shared folder will all be able to do locking together correctly. And creating a zero-length file will almost certainly be cached, so performance isn't really an issue.

TODO: use this author string for everything! (the old one can't be printed)

Version:
$Id$
Author:
Ken Harris <kbh7@cornell.edu>

Method Summary
static boolean acquire(String filename)
          Try to acquire a lock on a file.
static boolean acquire(String filename, int keepTrying)
          Try to acquire a lock on a file.
static void release(String filename)
          Release the lock on a file.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

acquire

public static boolean acquire(String filename)
Try to acquire a lock on a file.

There's nothing forcing anybody to respect this lock, especially other programs; you have to trust that they'll use this Lock class, as well.

Parameters:
filename - the name of the file to lock
Returns:
true if the lock was acquired, else false

acquire

public static boolean acquire(String filename,
                              int keepTrying)
Try to acquire a lock on a file. If it's not available, keep trying every half second until it's available, up to a certain number of tries. If it's still unavailable after that time, it returns false as normal.

There's nothing forcing anybody to respect this lock, especially other programs; you have to trust that they'll use this Lock class, as well.

Parameters:
filename - the name of the file to lock
keepTrying - if locked, try again this many times, 0.5 seconds apart
Returns:
true if the lock was acquired, else false

release

public static void release(String filename)
Release the lock on a file. If that file wasn't locked, does nothing.

There's no explicit steal() method, because Lock doesn't provide any assurance that this file is truly locked, aside from trusting that you will call acquire() to check first. If you really need to steal a lock, just do whatever you were going to do - but bad things will happen.

Parameters:
filename - the name of the file to release the lock on