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 * @updated 1.7
118 */
119
120 public abstract class FileLock {
121
122 private final Channel channel;
123 private final long position;
124 private final long size;
125 private final boolean shared;
126
127 /**
128 * Initializes a new instance of this class. </p>
129 *
130 * @param channel
131 * The file channel upon whose file this lock is held
132 *
133 * @param position
134 * The position within the file at which the locked region starts;
135 * must be non-negative
136 *
137 * @param size
144 *
145 * @throws IllegalArgumentException
146 * If the preconditions on the parameters do not hold
147 */
148 protected FileLock(FileChannel channel,
149 long position, long size, boolean shared)
150 {
151 if (position < 0)
152 throw new IllegalArgumentException("Negative position");
153 if (size < 0)
154 throw new IllegalArgumentException("Negative size");
155 if (position + size < 0)
156 throw new IllegalArgumentException("Negative position + size");
157 this.channel = channel;
158 this.position = position;
159 this.size = size;
160 this.shared = shared;
161 }
162
163 /**
164 * {@note new} Initializes a new instance of this class.
165 *
166 * @param channel
167 * The channel upon whose file this lock is held
168 *
169 * @param position
170 * The position within the file at which the locked region starts;
171 * must be non-negative
172 *
173 * @param size
174 * The size of the locked region; must be non-negative, and the sum
175 * <tt>position</tt> + <tt>size</tt> must be non-negative
176 *
177 * @param shared
178 * <tt>true</tt> if this lock is shared,
179 * <tt>false</tt> if it is exclusive
180 *
181 * @throws IllegalArgumentException
182 * If the preconditions on the parameters do not hold
183 *
184 * @since 1.7
185 */
186 protected FileLock(AsynchronousFileChannel channel,
187 long position, long size, boolean shared)
188 {
189 if (position < 0)
190 throw new IllegalArgumentException("Negative position");
191 if (size < 0)
192 throw new IllegalArgumentException("Negative size");
193 if (position + size < 0)
194 throw new IllegalArgumentException("Negative position + size");
195 this.channel = channel;
196 this.position = position;
197 this.size = size;
198 this.shared = shared;
199 }
200
201 /**
202 * {@note revised}
203 * Returns the file channel upon whose file this lock was acquired.
204 *
205 * <p> This method has been superseded by the {@link #acquiredBy acquiredBy}
206 * method.
207 *
208 * @return The file channel, or {@code null} if the file lock was not
209 * acquired by a file channel.
210 */
211 public final FileChannel channel() {
212 return (channel instanceof FileChannel) ? (FileChannel)channel : null;
213 }
214
215 /**
216 * {@note new}
217 * Returns the channel upon whose file this lock was acquired.
218 *
219 * @return The channel upon whose file this lock was acquired.
220 *
221 * @since 1.7
222 */
223 public Channel acquiredBy() {
224 return channel;
225 }
226
227 /**
228 * Returns the position within the file of the first byte of the locked
229 * region.
230 *
231 * <p> A locked region need not be contained within, or even overlap, the
232 * actual underlying file, so the value returned by this method may exceed
233 * the file's current size. </p>
234 *
235 * @return The position
236 */
|
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
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> + <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 */
|