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> + <tt>size</tt> must be non-negative
139 *
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 }
|
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 implements AutoCloseable {
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> + <tt>size</tt> must be non-negative
139 *
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 * This method invokes the {@link #release} method. It was added
303 * to the class so that it could be used in conjunction with the
304 * automatic resource management block construct.
305 *
306 * @since 1.7
307 */
308 public final void close() throws IOException {
309 release();
310 }
311
312 /**
313 * Returns a string describing the range, type, and validity of this lock.
314 *
315 * @return A descriptive string
316 */
317 public final String toString() {
318 return (this.getClass().getName()
319 + "[" + position
320 + ":" + size
321 + " " + (shared ? "shared" : "exclusive")
322 + " " + (isValid() ? "valid" : "invalid")
323 + "]");
324 }
325
326 }
|