Acquires a lock on the given region of this channel's file.
An invocation of this method will block until the region can be
locked, this channel is closed, or the invoking thread is interrupted,
whichever comes first.
If this channel is closed by another thread during an invocation of
this method then an AsynchronousCloseException
will be thrown.
If the invoking thread is interrupted while waiting to acquire the
lock then its interrupt status will be set and a FileLockInterruptionException
will be thrown. If the invoker's
interrupt status is set when this method is invoked then that exception
will be thrown immediately; the thread's interrupt status will not be
changed.
The region specified by the position and size
parameters need not be contained within, or even overlap, the actual
underlying file. Lock regions are fixed in size; if a locked region
initially contains the end of the file and the file grows beyond the
region then the new portion of the file will not be covered by the lock.
If a file is expected to grow in size and a lock on the entire file is
required then a region starting at zero, and no smaller than the
expected maximum size of the file, should be locked. The zero-argument
FileChannel.lock()
method simply locks a region of size Long.MAX_VALUE
.
Some operating systems do not support shared locks, in which case a
request for a shared lock is automatically converted into a request for
an exclusive lock. Whether the newly-acquired lock is shared or
exclusive may be tested by invoking the resulting lock object's isShared
method.
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.
Returns:
A lock object representing the newly-acquired lock
Parameters:
-
position - The position at which the locked region is to start; must be
non-negative
-
size - The size of the locked region; must be non-negative, and the sum
position +
size must be non-negative
-
shared -
true to request a shared lock, in which case this
channel must be open for reading (and possibly writing);
false to request an exclusive lock, in which case this
channel must be open for writing (and possibly reading)
Throws:
-
IllegalArgumentException - If the preconditions on the parameters do not hold
-
ClosedChannelException - If this channel is closed
-
AsynchronousCloseException - If another thread closes this channel while the invoking
thread is blocked in this method
-
FileLockInterruptionException - If the invoking thread is interrupted while blocked in this
method
-
OverlappingFileLockException - If a lock that overlaps the requested region is already held by
this Java virtual machine, or if another thread is already
blocked in this method and is attempting to lock an overlapping
region
-
NonReadableChannelException - If
shared is
true this channel was not
opened for reading
-
NonWritableChannelException - If
shared is
false but this channel was not
opened for writing
-
IOException - If some other I/O error occurs
See Also:
FileChannel.lock()
,
FileChannel.tryLock()
,
FileChannel.tryLock(long,long,boolean)
,