1 /*
   2  * Copyright (c) 2001, 2009, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.nio.channels;
  27 
  28 import java.io.IOException;
  29 
  30 /**
  31  * A token representing a lock on a region of a file.
  32  *
  33  * <p> A file-lock object is created each time a lock is acquired on a file via
  34  * one of the {@link FileChannel#lock(long,long,boolean) lock} or {@link
  35  * FileChannel#tryLock(long,long,boolean) tryLock} methods of the
  36  * {@link FileChannel} class, or the {@link
  37  * AsynchronousFileChannel#lock(long,long,boolean,Object,CompletionHandler) lock}
  38  * or {@link AsynchronousFileChannel#tryLock(long,long,boolean) tryLock}
  39  * methods of the {@link AsynchronousFileChannel} class.
  40  *
  41  * <p> A file-lock object is initially valid.  It remains valid until the lock
  42  * is released by invoking the {@link #release release} method, by closing the
  43  * channel that was used to acquire it, or by the termination of the Java
  44  * virtual machine, whichever comes first.  The validity of a lock may be
  45  * tested by invoking its {@link #isValid isValid} method.
  46  *
  47  * <p> A file lock is either <i>exclusive</i> or <i>shared</i>.  A shared lock
  48  * prevents other concurrently-running programs from acquiring an overlapping
  49  * exclusive lock, but does allow them to acquire overlapping shared locks.  An
  50  * exclusive lock prevents other programs from acquiring an overlapping lock of
  51  * either type.  Once it is released, a lock has no further effect on the locks
  52  * that may be acquired by other programs.
  53  *
  54  * <p> Whether a lock is exclusive or shared may be determined by invoking its
  55  * {@link #isShared isShared} method.  Some platforms do not support shared
  56  * locks, in which case a request for a shared lock is automatically converted
  57  * into a request for an exclusive lock.
  58  *
  59  * <p> The locks held on a particular file by a single Java virtual machine do
  60  * not overlap.  The {@link #overlaps overlaps} method may be used to test
  61  * whether a candidate lock range overlaps an existing lock.
  62  *
  63  * <p> A file-lock object records the file channel upon whose file the lock is
  64  * held, the type and validity of the lock, and the position and size of the
  65  * locked region.  Only the validity of a lock is subject to change over time;
  66  * all other aspects of a lock's state are immutable.
  67  *
  68  * <p> File locks are held on behalf of the entire Java virtual machine.
  69  * They are not suitable for controlling access to a file by multiple
  70  * threads within the same virtual machine.
  71  *
  72  * <p> File-lock objects are safe for use by multiple concurrent threads.
  73  *
  74  *
  75  * <a name="pdep"><h4> Platform dependencies </h4></a>
  76  *
  77  * <p> This file-locking API is intended to map directly to the native locking
  78  * facility of the underlying operating system.  Thus the locks held on a file
  79  * should be visible to all programs that have access to the file, regardless
  80  * of the language in which those programs are written.
  81  *
  82  * <p> Whether or not a lock actually prevents another program from accessing
  83  * the content of the locked region is system-dependent and therefore
  84  * unspecified.  The native file-locking facilities of some systems are merely
  85  * <i>advisory</i>, meaning that programs must cooperatively observe a known
  86  * locking protocol in order to guarantee data integrity.  On other systems
  87  * native file locks are <i>mandatory</i>, meaning that if one program locks a
  88  * region of a file then other programs are actually prevented from accessing
  89  * that region in a way that would violate the lock.  On yet other systems,
  90  * whether native file locks are advisory or mandatory is configurable on a
  91  * per-file basis.  To ensure consistent and correct behavior across platforms,
  92  * it is strongly recommended that the locks provided by this API be used as if
  93  * they were advisory locks.
  94  *
  95  * <p> On some systems, acquiring a mandatory lock on a region of a file
  96  * prevents that region from being {@link java.nio.channels.FileChannel#map
  97  * <i>mapped into memory</i>}, and vice versa.  Programs that combine
  98  * locking and mapping should be prepared for this combination to fail.
  99  *
 100  * <p> On some systems, closing a channel releases all locks held by the Java
 101  * virtual machine on the underlying file regardless of whether the locks were
 102  * acquired via that channel or via another channel open on the same file.  It
 103  * is strongly recommended that, within a program, a unique channel be used to
 104  * acquire all locks on any given file.
 105  *
 106  * <p> Some network filesystems permit file locking to be used with
 107  * memory-mapped files only when the locked regions are page-aligned and a
 108  * whole multiple of the underlying hardware's page size.  Some network
 109  * filesystems do not implement file locks on regions that extend past a
 110  * certain position, often 2<sup>30</sup> or 2<sup>31</sup>.  In general, great
 111  * care should be taken when locking files that reside on network filesystems.
 112  *
 113  *
 114  * @author Mark Reinhold
 115  * @author JSR-51 Expert Group
 116  * @since 1.4
 117  */
 118 
 119 public abstract class FileLock {
 120 
 121     private final Channel channel;
 122     private final long position;
 123     private final long size;
 124     private final boolean shared;
 125 
 126     /**
 127      * Initializes a new instance of this class.  </p>
 128      *
 129      * @param  channel
 130      *         The file channel upon whose file this lock is held
 131      *
 132      * @param  position
 133      *         The position within the file at which the locked region starts;
 134      *         must be non-negative
 135      *
 136      * @param  size
 137      *         The size of the locked region; must be non-negative, and the sum
 138      *         <tt>position</tt>&nbsp;+&nbsp;<tt>size</tt> must be non-negative
 139      *
 140      * @param  shared
 141      *         <tt>true</tt> if this lock is shared,
 142      *         <tt>false</tt> if it is exclusive
 143      *
 144      * @throws IllegalArgumentException
 145      *         If the preconditions on the parameters do not hold
 146      */
 147     protected FileLock(FileChannel channel,
 148                        long position, long size, boolean shared)
 149     {
 150         if (position < 0)
 151             throw new IllegalArgumentException("Negative position");
 152         if (size < 0)
 153             throw new IllegalArgumentException("Negative size");
 154         if (position + size < 0)
 155             throw new IllegalArgumentException("Negative position + size");
 156         this.channel = channel;
 157         this.position = position;
 158         this.size = size;
 159         this.shared = shared;
 160     }
 161 
 162     /**
 163      * Initializes a new instance of this class.
 164      *
 165      * @param  channel
 166      *         The channel upon whose file this lock is held
 167      *
 168      * @param  position
 169      *         The position within the file at which the locked region starts;
 170      *         must be non-negative
 171      *
 172      * @param  size
 173      *         The size of the locked region; must be non-negative, and the sum
 174      *         <tt>position</tt>&nbsp;+&nbsp;<tt>size</tt> must be non-negative
 175      *
 176      * @param  shared
 177      *         <tt>true</tt> if this lock is shared,
 178      *         <tt>false</tt> if it is exclusive
 179      *
 180      * @throws IllegalArgumentException
 181      *         If the preconditions on the parameters do not hold
 182      *
 183      * @since 1.7
 184      */
 185     protected FileLock(AsynchronousFileChannel channel,
 186                        long position, long size, boolean shared)
 187     {
 188         if (position < 0)
 189             throw new IllegalArgumentException("Negative position");
 190         if (size < 0)
 191             throw new IllegalArgumentException("Negative size");
 192         if (position + size < 0)
 193             throw new IllegalArgumentException("Negative position + size");
 194         this.channel = channel;
 195         this.position = position;
 196         this.size = size;
 197         this.shared = shared;
 198     }
 199 
 200     /**
 201      * Returns the file channel upon whose file this lock was acquired.
 202      *
 203      * <p> This method has been superseded by the {@link #acquiredBy acquiredBy}
 204      * method.
 205      *
 206      * @return  The file channel, or {@code null} if the file lock was not
 207      *          acquired by a file channel.
 208      */
 209     public final FileChannel channel() {
 210         return (channel instanceof FileChannel) ? (FileChannel)channel : null;
 211     }
 212 
 213     /**
 214      * Returns the channel upon whose file this lock was acquired.
 215      *
 216      * @return  The channel upon whose file this lock was acquired.
 217      *
 218      * @since 1.7
 219      */
 220     public Channel acquiredBy() {
 221         return channel;
 222     }
 223 
 224     /**
 225      * Returns the position within the file of the first byte of the locked
 226      * region.
 227      *
 228      * <p> A locked region need not be contained within, or even overlap, the
 229      * actual underlying file, so the value returned by this method may exceed
 230      * the file's current size.  </p>
 231      *
 232      * @return  The position
 233      */
 234     public final long position() {
 235         return position;
 236     }
 237 
 238     /**
 239      * Returns the size of the locked region in bytes.
 240      *
 241      * <p> A locked region need not be contained within, or even overlap, the
 242      * actual underlying file, so the value returned by this method may exceed
 243      * the file's current size.  </p>
 244      *
 245      * @return  The size of the locked region
 246      */
 247     public final long size() {
 248         return size;
 249     }
 250 
 251     /**
 252      * Tells whether this lock is shared.  </p>
 253      *
 254      * @return <tt>true</tt> if lock is shared,
 255      *         <tt>false</tt> if it is exclusive
 256      */
 257     public final boolean isShared() {
 258         return shared;
 259     }
 260 
 261     /**
 262      * Tells whether or not this lock overlaps the given lock range.  </p>
 263      *
 264      * @return  <tt>true</tt> if, and only if, this lock and the given lock
 265      *          range overlap by at least one byte
 266      */
 267     public final boolean overlaps(long position, long size) {
 268         if (position + size <= this.position)
 269             return false;               // That is below this
 270         if (this.position + this.size <= position)
 271             return false;               // This is below that
 272         return true;
 273     }
 274 
 275     /**
 276      * Tells whether or not this lock is valid.
 277      *
 278      * <p> A lock object remains valid until it is released or the associated
 279      * file channel is closed, whichever comes first.  </p>
 280      *
 281      * @return  <tt>true</tt> if, and only if, this lock is valid
 282      */
 283     public abstract boolean isValid();
 284 
 285     /**
 286      * Releases this lock.
 287      *
 288      * <p> If this lock object is valid then invoking this method releases the
 289      * lock and renders the object invalid.  If this lock object is invalid
 290      * then invoking this method has no effect.  </p>
 291      *
 292      * @throws  ClosedChannelException
 293      *          If the channel that was used to acquire this lock
 294      *          is no longer open
 295      *
 296      * @throws  IOException
 297      *          If an I/O error occurs
 298      */
 299     public abstract void release() throws IOException;
 300 
 301     /**
 302      * Returns a string describing the range, type, and validity of this lock.
 303      *
 304      * @return  A descriptive string
 305      */
 306     public final String toString() {
 307         return (this.getClass().getName()
 308                 + "[" + position
 309                 + ":" + size
 310                 + " " + (shared ? "shared" : "exclusive")
 311                 + " " + (isValid() ? "valid" : "invalid")
 312                 + "]");
 313     }
 314 
 315 }