-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathFileLock.java
More file actions
331 lines (313 loc) · 11.6 KB
/
FileLock.java
File metadata and controls
331 lines (313 loc) · 11.6 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
/*
* Copyright (c) 2001, 2013, Oracle and/or its affiliates. All rights reserved.
* ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*/
package java.nio.channels;
import java.io.IOException;
/**
* A token representing a lock on a region of a file.
*
* <p> A file-lock object is created each time a lock is acquired on a file via
* one of the {@link FileChannel#lock(long,long,boolean) lock} or {@link
* FileChannel#tryLock(long,long,boolean) tryLock} methods of the
* {@link FileChannel} class, or the {@link
* AsynchronousFileChannel#lock(long,long,boolean,Object,CompletionHandler) lock}
* or {@link AsynchronousFileChannel#tryLock(long,long,boolean) tryLock}
* methods of the {@link AsynchronousFileChannel} class.
*
* <p> A file-lock object is initially valid. It remains valid until the lock
* is released by invoking the {@link #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 {@link #isValid isValid} method.
*
* <p> A file lock is either <i>exclusive</i> or <i>shared</i>. 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.
*
* <p> Whether a lock is exclusive or shared may be determined by invoking its
* {@link #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.
*
* <p> The locks held on a particular file by a single Java virtual machine do
* not overlap. The {@link #overlaps overlaps} method may be used to test
* whether a candidate lock range overlaps an existing lock.
*
* <p> 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.
*
* <p> 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.
*
* <p> File-lock objects are safe for use by multiple concurrent threads.
*
*
* <a name="pdep"></a><h2> Platform dependencies </h2>
*
* <p> 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.
*
* <p> 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
* <i>advisory</i>, meaning that programs must cooperatively observe a known
* locking protocol in order to guarantee data integrity. On other systems
* native file locks are <i>mandatory</i>, 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.
*
* <p> On some systems, acquiring a mandatory lock on a region of a file
* prevents that region from being {@link java.nio.channels.FileChannel#map
* <i>mapped into memory</i>}, and vice versa. Programs that combine
* locking and mapping should be prepared for this combination to fail.
*
* <p> 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.
*
* <p> 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 2<sup>30</sup> or 2<sup>31</sup>. In general, great
* care should be taken when locking files that reside on network filesystems.
*
*
* @author Mark Reinhold
* @author JSR-51 Expert Group
* @since 1.4
*/
public abstract class FileLock implements AutoCloseable {
private final Channel channel;
private final long position;
private final long size;
private final boolean shared;
/**
* Initializes a new instance of this class.
*
* @param channel
* The file channel upon whose file this lock is held
*
* @param position
* The position within the file at which the locked region starts;
* must be non-negative
*
* @param size
* The size of the locked region; must be non-negative, and the sum
* <tt>position</tt> + <tt>size</tt> must be non-negative
*
* @param shared
* <tt>true</tt> if this lock is shared,
* <tt>false</tt> if it is exclusive
*
* @throws IllegalArgumentException
* If the preconditions on the parameters do not hold
*/
protected FileLock(FileChannel channel,
long position, long size, boolean shared)
{
if (position < 0)
throw new IllegalArgumentException("Negative position");
if (size < 0)
throw new IllegalArgumentException("Negative size");
if (position + size < 0)
throw new IllegalArgumentException("Negative position + size");
this.channel = channel;
this.position = position;
this.size = size;
this.shared = shared;
}
/**
* Initializes a new instance of this class.
*
* @param channel
* The channel upon whose file this lock is held
*
* @param position
* The position within the file at which the locked region starts;
* must be non-negative
*
* @param size
* The size of the locked region; must be non-negative, and the sum
* <tt>position</tt> + <tt>size</tt> must be non-negative
*
* @param shared
* <tt>true</tt> if this lock is shared,
* <tt>false</tt> if it is exclusive
*
* @throws IllegalArgumentException
* If the preconditions on the parameters do not hold
*
* @since 1.7
*/
protected FileLock(AsynchronousFileChannel channel,
long position, long size, boolean shared)
{
if (position < 0)
throw new IllegalArgumentException("Negative position");
if (size < 0)
throw new IllegalArgumentException("Negative size");
if (position + size < 0)
throw new IllegalArgumentException("Negative position + size");
this.channel = channel;
this.position = position;
this.size = size;
this.shared = shared;
}
/**
* Returns the file channel upon whose file this lock was acquired.
*
* <p> This method has been superseded by the {@link #acquiredBy acquiredBy}
* method.
*
* @return The file channel, or {@code null} if the file lock was not
* acquired by a file channel.
*/
public final FileChannel channel() {
return (channel instanceof FileChannel) ? (FileChannel)channel : null;
}
/**
* Returns the channel upon whose file this lock was acquired.
*
* @return The channel upon whose file this lock was acquired.
*
* @since 1.7
*/
public Channel acquiredBy() {
return channel;
}
/**
* Returns the position within the file of the first byte of the locked
* region.
*
* <p> 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. </p>
*
* @return The position
*/
public final long position() {
return position;
}
/**
* Returns the size of the locked region in bytes.
*
* <p> 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. </p>
*
* @return The size of the locked region
*/
public final long size() {
return size;
}
/**
* Tells whether this lock is shared.
*
* @return <tt>true</tt> if lock is shared,
* <tt>false</tt> if it is exclusive
*/
public final boolean isShared() {
return shared;
}
/**
* Tells whether or not this lock overlaps the given lock range.
*
* @param position
* The starting position of the lock range
* @param size
* The size of the lock range
*
* @return <tt>true</tt> if, and only if, this lock and the given lock
* range overlap by at least one byte
*/
public final boolean overlaps(long position, long size) {
if (position + size <= this.position)
return false; // That is below this
if (this.position + this.size <= position)
return false; // This is below that
return true;
}
/**
* Tells whether or not this lock is valid.
*
* <p> A lock object remains valid until it is released or the associated
* file channel is closed, whichever comes first. </p>
*
* @return <tt>true</tt> if, and only if, this lock is valid
*/
public abstract boolean isValid();
/**
* Releases this lock.
*
* <p> 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. </p>
*
* @throws ClosedChannelException
* If the channel that was used to acquire this lock
* is no longer open
*
* @throws IOException
* If an I/O error occurs
*/
public abstract void release() throws IOException;
/**
* This method invokes the {@link #release} method. It was added
* to the class so that it could be used in conjunction with the
* automatic resource management block construct.
*
* @since 1.7
*/
public final void close() throws IOException {
release();
}
/**
* Returns a string describing the range, type, and validity of this lock.
*
* @return A descriptive string
*/
public final String toString() {
return (this.getClass().getName()
+ "[" + position
+ ":" + size
+ " " + (shared ? "shared" : "exclusive")
+ " " + (isValid() ? "valid" : "invalid")
+ "]");
}
}