History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/java/nio/channels/FileLock.java (1 of 18352 files). Show all

Unified · Split

java/pkg/java/nio/channels/FileLock.java+326−0
@@ -0,0 +1,326 @@
1+/*
2+ * Copyright (c) 2001, 2010, 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 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>&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+ * 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+}

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t