| java.lang.Object
 java.nio.channels.FileLock
| FileLock | | abstract public class FileLock (Code) | | A token representing a lock on a region of a file.
A file-lock object is created each time a lock is acquired on a file via
one of the
FileChannel.lock(longlongboolean) lock or
FileChannel.tryLock(longlongboolean) tryLock methods of the
FileChannel class.
A file-lock object is initially valid. It remains valid until the lock
is released by invoking the
FileLock.release release method, by closing the
channel that was used to acquire it, or by the termination of the Java
virtual machine, whichever comes first. The validity of a lock may be
tested by invoking its
FileLock.isValid isValid method.
A file lock is either exclusive or shared. A shared lock
prevents other concurrently-running programs from acquiring an overlapping
exclusive lock, but does allow them to acquire overlapping shared locks. An
exclusive lock prevents other programs from acquiring an overlapping lock of
either type. Once it is released, a lock has no further effect on the locks
that may be acquired by other programs.
Whether a lock is exclusive or shared may be determined by invoking its
FileLock.isShared isShared method. Some platforms do not support shared
locks, in which case a request for a shared lock is automatically converted
into a request for an exclusive lock.
The locks held on a particular file by a single Java virtual machine do
not overlap. The
FileLock.overlaps overlaps method may be used to test
whether a candidate lock range overlaps an existing lock.
A file-lock object records the file channel upon whose file the lock is
held, the type and validity of the lock, and the position and size of the
locked region. Only the validity of a lock is subject to change over time;
all other aspects of a lock's state are immutable.
File locks are held on behalf of the entire Java virtual machine.
They are not suitable for controlling access to a file by multiple
threads within the same virtual machine.
File-lock objects are safe for use by multiple concurrent threads.
Platform dependencies
This file-locking API is intended to map directly to the native locking
facility of the underlying operating system. Thus the locks held on a file
should be visible to all programs that have access to the file, regardless
of the language in which those programs are written.
Whether or not a lock actually prevents another program from accessing
the content of the locked region is system-dependent and therefore
unspecified. The native file-locking facilities of some systems are merely
advisory, meaning that programs must cooperatively observe a known
locking protocol in order to guarantee data integrity. On other systems
native file locks are mandatory, meaning that if one program locks a
region of a file then other programs are actually prevented from accessing
that region in a way that would violate the lock. On yet other systems,
whether native file locks are advisory or mandatory is configurable on a
per-file basis. To ensure consistent and correct behavior across platforms,
it is strongly recommended that the locks provided by this API be used as if
they were advisory locks.
On some systems, acquiring a mandatory lock on a region of a file
prevents that region from being
java.nio.channels.FileChannel.mapmapped into memory , and vice versa. Programs that combine
locking and mapping should be prepared for this combination to fail.
On some systems, closing a channel releases all locks held by the Java
virtual machine on the underlying file regardless of whether the locks were
acquired via that channel or via another channel open on the same file. It
is strongly recommended that, within a program, a unique channel be used to
acquire all locks on any given file.
Some network filesystems permit file locking to be used with
memory-mapped files only when the locked regions are page-aligned and a
whole multiple of the underlying hardware's page size. Some network
filesystems do not implement file locks on regions that extend past a
certain position, often 230 or 231. In general, great
care should be taken when locking files that reside on network filesystems.
author:
Mark Reinhold
author:
JSR-51 Expert Group
version:
1.15, 07/05/05
since:
1.4 |
| Constructor Summary | |
| protected | FileLock(FileChannel channel, long position, long size, boolean shared)
Initializes a new instance of this class. |
| Method Summary | |
| final public FileChannel | channel()
Returns the file channel upon whose file this lock is held. | | final public boolean | isShared()
Tells whether this lock is shared. | | abstract public boolean | isValid()
Tells whether or not this lock is valid.
A lock object remains valid until it is released or the associated
file channel is closed, whichever comes first. | | final public boolean | overlaps(long position, long size)
Tells whether or not this lock overlaps the given lock range. | | final public long | position()
Returns the position within the file of the first byte of the locked
region.
A locked region need not be contained within, or even overlap, the
actual underlying file, so the value returned by this method may exceed
the file's current size. | | abstract public void | release()
Releases this lock.
If this lock object is valid then invoking this method releases the
lock and renders the object invalid. | | final public long | size()
Returns the size of the locked region in bytes.
A locked region need not be contained within, or even overlap, the
actual underlying file, so the value returned by this method may exceed
the file's current size. | | final public String | toString()
Returns a string describing the range, type, and validity of this lock. |
| FileLock | | protected FileLock(FileChannel channel, long position, long size, boolean shared)(Code) | | Initializes a new instance of this class.
Parameters:
channel - The file channel upon whose file this lock is held
Parameters:
position - The position within the file at which the locked region starts;must be non-negative
Parameters:
size - The size of the locked region; must be non-negative, and the sumposition + size must be non-negative
Parameters:
shared - true if this lock is shared,false if it is exclusive
throws:
IllegalArgumentException - If the preconditions on the parameters do not hold |
| channel | | final public FileChannel channel()(Code) | | Returns the file channel upon whose file this lock is held.
The file channel |
| isShared | | final public boolean isShared()(Code) | | Tells whether this lock is shared.
true if lock is shared,false if it is exclusive |
| isValid | | abstract public boolean isValid()(Code) | | Tells whether or not this lock is valid.
A lock object remains valid until it is released or the associated
file channel is closed, whichever comes first.
true if, and only if, this lock is valid |
| overlaps | | final public boolean overlaps(long position, long size)(Code) | | Tells whether or not this lock overlaps the given lock range.
true if, and only if, this lock and the given lockrange overlap by at least one byte |
| position | | final public long position()(Code) | | Returns the position within the file of the first byte of the locked
region.
A locked region need not be contained within, or even overlap, the
actual underlying file, so the value returned by this method may exceed
the file's current size.
The position |
| release | | abstract public void release() throws IOException(Code) | | Releases this lock.
If this lock object is valid then invoking this method releases the
lock and renders the object invalid. If this lock object is invalid
then invoking this method has no effect.
throws:
ClosedChannelException - If the channel that was used to acquire this lockis no longer open
throws:
IOException - If an I/O error occurs |
| size | | final public long size()(Code) | | Returns the size of the locked region in bytes.
A locked region need not be contained within, or even overlap, the
actual underlying file, so the value returned by this method may exceed
the file's current size.
The size of the locked region |
| toString | | final public String toString()(Code) | | Returns a string describing the range, type, and validity of this lock.
A descriptive string |
|
|