001 /*
002 * Copyright 2000-2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.nio.channels;
027
028 import java.io.*;
029 import java.nio.ByteBuffer;
030 import java.nio.MappedByteBuffer;
031 import java.nio.channels.spi.AbstractInterruptibleChannel;
032
033 /**
034 * A channel for reading, writing, mapping, and manipulating a file.
035 *
036 * <p> A file channel has a current <i>position</i> within its file which can
037 * be both {@link #position() </code>queried<code>} and {@link #position(long)
038 * </code>modified<code>}. The file itself contains a variable-length sequence
039 * of bytes that can be read and written and whose current {@link #size
040 * </code><i>size</i><code>} can be queried. The size of the file increases
041 * when bytes are written beyond its current size; the size of the file
042 * decreases when it is {@link #truncate </code><i>truncated</i><code>}. The
043 * file may also have some associated <i>metadata</i> such as access
044 * permissions, content type, and last-modification time; this class does not
045 * define methods for metadata access.
046 *
047 * <p> In addition to the familiar read, write, and close operations of byte
048 * channels, this class defines the following file-specific operations: </p>
049 *
050 * <ul>
051 *
052 * <li><p> Bytes may be {@link #read(ByteBuffer, long) </code>read<code>} or
053 * {@link #write(ByteBuffer, long) </code>written<code>} at an absolute
054 * position in a file in a way that does not affect the channel's current
055 * position. </p></li>
056 *
057 * <li><p> A region of a file may be {@link #map </code>mapped<code>}
058 * directly into memory; for large files this is often much more efficient
059 * than invoking the usual <tt>read</tt> or <tt>write</tt> methods.
060 * </p></li>
061 *
062 * <li><p> Updates made to a file may be {@link #force </code>forced
063 * out<code>} to the underlying storage device, ensuring that data are not
064 * lost in the event of a system crash. </p></li>
065 *
066 * <li><p> Bytes can be transferred from a file {@link #transferTo </code>to
067 * some other channel<code>}, and {@link #transferFrom </code>vice
068 * versa<code>}, in a way that can be optimized by many operating systems
069 * into a very fast transfer directly to or from the filesystem cache.
070 * </p></li>
071 *
072 * <li><p> A region of a file may be {@link FileLock </code>locked<code>}
073 * against access by other programs. </p></li>
074 *
075 * </ul>
076 *
077 * <p> File channels are safe for use by multiple concurrent threads. The
078 * {@link Channel#close close} method may be invoked at any time, as specified
079 * by the {@link Channel} interface. Only one operation that involves the
080 * channel's position or can change its file's size may be in progress at any
081 * given time; attempts to initiate a second such operation while the first is
082 * still in progress will block until the first operation completes. Other
083 * operations, in particular those that take an explicit position, may proceed
084 * concurrently; whether they in fact do so is dependent upon the underlying
085 * implementation and is therefore unspecified.
086 *
087 * <p> The view of a file provided by an instance of this class is guaranteed
088 * to be consistent with other views of the same file provided by other
089 * instances in the same program. The view provided by an instance of this
090 * class may or may not, however, be consistent with the views seen by other
091 * concurrently-running programs due to caching performed by the underlying
092 * operating system and delays induced by network-filesystem protocols. This
093 * is true regardless of the language in which these other programs are
094 * written, and whether they are running on the same machine or on some other
095 * machine. The exact nature of any such inconsistencies are system-dependent
096 * and are therefore unspecified.
097 *
098 * <p> This class does not define methods for opening existing files or for
099 * creating new ones; such methods may be added in a future release. In this
100 * release a file channel can be obtained from an existing {@link
101 * java.io.FileInputStream#getChannel FileInputStream}, {@link
102 * java.io.FileOutputStream#getChannel FileOutputStream}, or {@link
103 * java.io.RandomAccessFile#getChannel RandomAccessFile} object by invoking
104 * that object's <tt>getChannel</tt> method, which returns a file channel that
105 * is connected to the same underlying file.
106 *
107 * <p> The state of a file channel is intimately connected to that of the
108 * object whose <tt>getChannel</tt> method returned the channel. Changing the
109 * channel's position, whether explicitly or by reading or writing bytes, will
110 * change the file position of the originating object, and vice versa.
111 * Changing the file's length via the file channel will change the length seen
112 * via the originating object, and vice versa. Changing the file's content by
113 * writing bytes will change the content seen by the originating object, and
114 * vice versa.
115 *
116 * <a name="open-mode"><p> At various points this class specifies that an
117 * instance that is "open for reading," "open for writing," or "open for
118 * reading and writing" is required. A channel obtained via the {@link
119 * java.io.FileInputStream#getChannel getChannel} method of a {@link
120 * java.io.FileInputStream} instance will be open for reading. A channel
121 * obtained via the {@link java.io.FileOutputStream#getChannel getChannel}
122 * method of a {@link java.io.FileOutputStream} instance will be open for
123 * writing. Finally, a channel obtained via the {@link
124 * java.io.RandomAccessFile#getChannel getChannel} method of a {@link
125 * java.io.RandomAccessFile} instance will be open for reading if the instance
126 * was created with mode <tt>"r"</tt> and will be open for reading and writing
127 * if the instance was created with mode <tt>"rw"</tt>.
128 *
129 * <a name="append-mode"><p> A file channel that is open for writing may be in
130 * <i>append mode</i>, for example if it was obtained from a file-output stream
131 * that was created by invoking the {@link
132 * java.io.FileOutputStream#FileOutputStream(java.io.File,boolean)
133 * FileOutputStream(File,boolean)} constructor and passing <tt>true</tt> for
134 * the second parameter. In this mode each invocation of a relative write
135 * operation first advances the position to the end of the file and then writes
136 * the requested data. Whether the advancement of the position and the writing
137 * of the data are done in a single atomic operation is system-dependent and
138 * therefore unspecified.
139 *
140 *
141 * @see java.io.FileInputStream#getChannel()
142 * @see java.io.FileOutputStream#getChannel()
143 * @see java.io.RandomAccessFile#getChannel()
144 *
145 * @author Mark Reinhold
146 * @author Mike McCloskey
147 * @author JSR-51 Expert Group
148 * @version 1.49, 07/05/05
149 * @since 1.4
150 */
151
152 public abstract class FileChannel extends AbstractInterruptibleChannel
153 implements ByteChannel, GatheringByteChannel,
154 ScatteringByteChannel {
155
156 /**
157 * Initializes a new instance of this class.
158 */
159 protected FileChannel() {
160 }
161
162 // -- Channel operations --
163
164 /**
165 * Reads a sequence of bytes from this channel into the given buffer.
166 *
167 * <p> Bytes are read starting at this channel's current file position, and
168 * then the file position is updated with the number of bytes actually
169 * read. Otherwise this method behaves exactly as specified in the {@link
170 * ReadableByteChannel} interface. </p>
171 */
172 public abstract int read(ByteBuffer dst) throws IOException;
173
174 /**
175 * Reads a sequence of bytes from this channel into a subsequence of the
176 * given buffers.
177 *
178 * <p> Bytes are read starting at this channel's current file position, and
179 * then the file position is updated with the number of bytes actually
180 * read. Otherwise this method behaves exactly as specified in the {@link
181 * ScatteringByteChannel} interface. </p>
182 */
183 public abstract long read(ByteBuffer[] dsts, int offset, int length)
184 throws IOException;
185
186 /**
187 * Reads a sequence of bytes from this channel into the given buffers.
188 *
189 * <p> Bytes are read starting at this channel's current file position, and
190 * then the file position is updated with the number of bytes actually
191 * read. Otherwise this method behaves exactly as specified in the {@link
192 * ScatteringByteChannel} interface. </p>
193 */
194 public final long read(ByteBuffer[] dsts) throws IOException {
195 return read(dsts, 0, dsts.length);
196 }
197
198 /**
199 * Writes a sequence of bytes to this channel from the given buffer.
200 *
201 * <p> Bytes are written starting at this channel's current file position
202 * unless the channel is in append mode, in which case the position is
203 * first advanced to the end of the file. The file is grown, if necessary,
204 * to accommodate the written bytes, and then the file position is updated
205 * with the number of bytes actually written. Otherwise this method
206 * behaves exactly as specified by the {@link WritableByteChannel}
207 * interface. </p>
208 */
209 public abstract int write(ByteBuffer src) throws IOException;
210
211 /**
212 * Writes a sequence of bytes to this channel from a subsequence of the
213 * given buffers.
214 *
215 * <p> Bytes are written starting at this channel's current file position
216 * unless the channel is in append mode, in which case the position is
217 * first advanced to the end of the file. The file is grown, if necessary,
218 * to accommodate the written bytes, and then the file position is updated
219 * with the number of bytes actually written. Otherwise this method
220 * behaves exactly as specified in the {@link GatheringByteChannel}
221 * interface. </p>
222 */
223 public abstract long write(ByteBuffer[] srcs, int offset, int length)
224 throws IOException;
225
226 /**
227 * Writes a sequence of bytes to this channel from the given buffers.
228 *
229 * <p> Bytes are written starting at this channel's current file position
230 * unless the channel is in append mode, in which case the position is
231 * first advanced to the end of the file. The file is grown, if necessary,
232 * to accommodate the written bytes, and then the file position is updated
233 * with the number of bytes actually written. Otherwise this method
234 * behaves exactly as specified in the {@link GatheringByteChannel}
235 * interface. </p>
236 */
237 public final long write(ByteBuffer[] srcs) throws IOException {
238 return write(srcs, 0, srcs.length);
239 }
240
241 // -- Other operations --
242
243 /**
244 * Returns this channel's file position. </p>
245 *
246 * @return This channel's file position,
247 * a non-negative integer counting the number of bytes
248 * from the beginning of the file to the current position
249 *
250 * @throws ClosedChannelException
251 * If this channel is closed
252 *
253 * @throws IOException
254 * If some other I/O error occurs
255 */
256 public abstract long position() throws IOException;
257
258 /**
259 * Sets this channel's file position.
260 *
261 * <p> Setting the position to a value that is greater than the file's
262 * current size is legal but does not change the size of the file. A later
263 * attempt to read bytes at such a position will immediately return an
264 * end-of-file indication. A later attempt to write bytes at such a
265 * position will cause the file to be grown to accommodate the new bytes;
266 * the values of any bytes between the previous end-of-file and the
267 * newly-written bytes are unspecified. </p>
268 *
269 * @param newPosition
270 * The new position, a non-negative integer counting
271 * the number of bytes from the beginning of the file
272 *
273 * @return This file channel
274 *
275 * @throws ClosedChannelException
276 * If this channel is closed
277 *
278 * @throws IllegalArgumentException
279 * If the new position is negative
280 *
281 * @throws IOException
282 * If some other I/O error occurs
283 */
284 public abstract FileChannel position(long newPosition)
285 throws IOException;
286
287 /**
288 * Returns the current size of this channel's file. </p>
289 *
290 * @return The current size of this channel's file,
291 * measured in bytes
292 *
293 * @throws ClosedChannelException
294 * If this channel is closed
295 *
296 * @throws IOException
297 * If some other I/O error occurs
298 */
299 public abstract long size() throws IOException;
300
301 /**
302 * Truncates this channel's file to the given size.
303 *
304 * <p> If the given size is less than the file's current size then the file
305 * is truncated, discarding any bytes beyond the new end of the file. If
306 * the given size is greater than or equal to the file's current size then
307 * the file is not modified. In either case, if this channel's file
308 * position is greater than the given size then it is set to that size.
309 * </p>
310 *
311 * @param size
312 * The new size, a non-negative byte count
313 *
314 * @return This file channel
315 *
316 * @throws NonWritableChannelException
317 * If this channel was not opened for writing
318 *
319 * @throws ClosedChannelException
320 * If this channel is closed
321 *
322 * @throws IllegalArgumentException
323 * If the new size is negative
324 *
325 * @throws IOException
326 * If some other I/O error occurs
327 */
328 public abstract FileChannel truncate(long size) throws IOException;
329
330 /**
331 * Forces any updates to this channel's file to be written to the storage
332 * device that contains it.
333 *
334 * <p> If this channel's file resides on a local storage device then when
335 * this method returns it is guaranteed that all changes made to the file
336 * since this channel was created, or since this method was last invoked,
337 * will have been written to that device. This is useful for ensuring that
338 * critical information is not lost in the event of a system crash.
339 *
340 * <p> If the file does not reside on a local device then no such guarantee
341 * is made.
342 *
343 * <p> The <tt>metaData</tt> parameter can be used to limit the number of
344 * I/O operations that this method is required to perform. Passing
345 * <tt>false</tt> for this parameter indicates that only updates to the
346 * file's content need be written to storage; passing <tt>true</tt>
347 * indicates that updates to both the file's content and metadata must be
348 * written, which generally requires at least one more I/O operation.
349 * Whether this parameter actually has any effect is dependent upon the
350 * underlying operating system and is therefore unspecified.
351 *
352 * <p> Invoking this method may cause an I/O operation to occur even if the
353 * channel was only opened for reading. Some operating systems, for
354 * example, maintain a last-access time as part of a file's metadata, and
355 * this time is updated whenever the file is read. Whether or not this is
356 * actually done is system-dependent and is therefore unspecified.
357 *
358 * <p> This method is only guaranteed to force changes that were made to
359 * this channel's file via the methods defined in this class. It may or
360 * may not force changes that were made by modifying the content of a
361 * {@link MappedByteBuffer </code>mapped byte buffer<code>} obtained by
362 * invoking the {@link #map map} method. Invoking the {@link
363 * MappedByteBuffer#force force} method of the mapped byte buffer will
364 * force changes made to the buffer's content to be written. </p>
365 *
366 * @param metaData
367 * If <tt>true</tt> then this method is required to force changes
368 * to both the file's content and metadata to be written to
369 * storage; otherwise, it need only force content changes to be
370 * written
371 *
372 * @throws ClosedChannelException
373 * If this channel is closed
374 *
375 * @throws IOException
376 * If some other I/O error occurs
377 */
378 public abstract void force(boolean metaData) throws IOException;
379
380 /**
381 * Transfers bytes from this channel's file to the given writable byte
382 * channel.
383 *
384 * <p> An attempt is made to read up to <tt>count</tt> bytes starting at
385 * the given <tt>position</tt> in this channel's file and write them to the
386 * target channel. An invocation of this method may or may not transfer
387 * all of the requested bytes; whether or not it does so depends upon the
388 * natures and states of the channels. Fewer than the requested number of
389 * bytes are transferred if this channel's file contains fewer than
390 * <tt>count</tt> bytes starting at the given <tt>position</tt>, or if the
391 * target channel is non-blocking and it has fewer than <tt>count</tt>
392 * bytes free in its output buffer.
393 *
394 * <p> This method does not modify this channel's position. If the given
395 * position is greater than the file's current size then no bytes are
396 * transferred. If the target channel has a position then bytes are
397 * written starting at that position and then the position is incremented
398 * by the number of bytes written.
399 *
400 * <p> This method is potentially much more efficient than a simple loop
401 * that reads from this channel and writes to the target channel. Many
402 * operating systems can transfer bytes directly from the filesystem cache
403 * to the target channel without actually copying them. </p>
404 *
405 * @param position
406 * The position within the file at which the transfer is to begin;
407 * must be non-negative
408 *
409 * @param count
410 * The maximum number of bytes to be transferred; must be
411 * non-negative
412 *
413 * @param target
414 * The target channel
415 *
416 * @return The number of bytes, possibly zero,
417 * that were actually transferred
418 *
419 * @throws IllegalArgumentException
420 * If the preconditions on the parameters do not hold
421 *
422 * @throws NonReadableChannelException
423 * If this channel was not opened for reading
424 *
425 * @throws NonWritableChannelException
426 * If the target channel was not opened for writing
427 *
428 * @throws ClosedChannelException
429 * If either this channel or the target channel is closed
430 *
431 * @throws AsynchronousCloseException
432 * If another thread closes either channel
433 * while the transfer is in progress
434 *
435 * @throws ClosedByInterruptException
436 * If another thread interrupts the current thread while the
437 * transfer is in progress, thereby closing both channels and
438 * setting the current thread's interrupt status
439 *
440 * @throws IOException
441 * If some other I/O error occurs
442 */
443 public abstract long transferTo(long position, long count,
444 WritableByteChannel target) throws IOException;
445
446 /**
447 * Transfers bytes into this channel's file from the given readable byte
448 * channel.
449 *
450 * <p> An attempt is made to read up to <tt>count</tt> bytes from the
451 * source channel and write them to this channel's file starting at the
452 * given <tt>position</tt>. An invocation of this method may or may not
453 * transfer all of the requested bytes; whether or not it does so depends
454 * upon the natures and states of the channels. Fewer than the requested
455 * number of bytes will be transferred if the source channel has fewer than
456 * <tt>count</tt> bytes remaining, or if the source channel is non-blocking
457 * and has fewer than <tt>count</tt> bytes immediately available in its
458 * input buffer.
459 *
460 * <p> This method does not modify this channel's position. If the given
461 * position is greater than the file's current size then no bytes are
462 * transferred. If the source channel has a position then bytes are read
463 * starting at that position and then the position is incremented by the
464 * number of bytes read.
465 *
466 * <p> This method is potentially much more efficient than a simple loop
467 * that reads from the source channel and writes to this channel. Many
468 * operating systems can transfer bytes directly from the source channel
469 * into the filesystem cache without actually copying them. </p>
470 *
471 * @param src
472 * The source channel
473 *
474 * @param position
475 * The position within the file at which the transfer is to begin;
476 * must be non-negative
477 *
478 * @param count
479 * The maximum number of bytes to be transferred; must be
480 * non-negative
481 *
482 * @return The number of bytes, possibly zero,
483 * that were actually transferred
484 *
485 * @throws IllegalArgumentException
486 * If the preconditions on the parameters do not hold
487 *
488 * @throws NonReadableChannelException
489 * If the source channel was not opened for reading
490 *
491 * @throws NonWritableChannelException
492 * If this channel was not opened for writing
493 *
494 * @throws ClosedChannelException
495 * If either this channel or the source channel is closed
496 *
497 * @throws AsynchronousCloseException
498 * If another thread closes either channel
499 * while the transfer is in progress
500 *
501 * @throws ClosedByInterruptException
502 * If another thread interrupts the current thread while the
503 * transfer is in progress, thereby closing both channels and
504 * setting the current thread's interrupt status
505 *
506 * @throws IOException
507 * If some other I/O error occurs
508 */
509 public abstract long transferFrom(ReadableByteChannel src,
510 long position, long count) throws IOException;
511
512 /**
513 * Reads a sequence of bytes from this channel into the given buffer,
514 * starting at the given file position.
515 *
516 * <p> This method works in the same manner as the {@link
517 * #read(ByteBuffer)} method, except that bytes are read starting at the
518 * given file position rather than at the channel's current position. This
519 * method does not modify this channel's position. If the given position
520 * is greater than the file's current size then no bytes are read. </p>
521 *
522 * @param dst
523 * The buffer into which bytes are to be transferred
524 *
525 * @param position
526 * The file position at which the transfer is to begin;
527 * must be non-negative
528 *
529 * @return The number of bytes read, possibly zero, or <tt>-1</tt> if the
530 * given position is greater than or equal to the file's current
531 * size
532 *
533 * @throws IllegalArgumentException
534 * If the position is negative
535 *
536 * @throws NonReadableChannelException
537 * If this channel was not opened for reading
538 *
539 * @throws ClosedChannelException
540 * If this channel is closed
541 *
542 * @throws AsynchronousCloseException
543 * If another thread closes this channel
544 * while the read operation is in progress
545 *
546 * @throws ClosedByInterruptException
547 * If another thread interrupts the current thread
548 * while the read operation is in progress, thereby
549 * closing the channel and setting the current thread's
550 * interrupt status
551 *
552 * @throws IOException
553 * If some other I/O error occurs
554 */
555 public abstract int read(ByteBuffer dst, long position)
556 throws IOException;
557
558 /**
559 * Writes a sequence of bytes to this channel from the given buffer,
560 * starting at the given file position.
561 *
562 * <p> This method works in the same manner as the {@link
563 * #write(ByteBuffer)} method, except that bytes are written starting at
564 * the given file position rather than at the channel's current position.
565 * This method does not modify this channel's position. If the given
566 * position is greater than the file's current size then the file will be
567 * grown to accommodate the new bytes; the values of any bytes between the
568 * previous end-of-file and the newly-written bytes are unspecified. </p>
569 *
570 * @param src
571 * The buffer from which bytes are to be transferred
572 *
573 * @param position
574 * The file position at which the transfer is to begin;
575 * must be non-negative
576 *
577 * @return The number of bytes written, possibly zero
578 *
579 * @throws IllegalArgumentException
580 * If the position is negative
581 *
582 * @throws NonWritableChannelException
583 * If this channel was not opened for writing
584 *
585 * @throws ClosedChannelException
586 * If this channel is closed
587 *
588 * @throws AsynchronousCloseException
589 * If another thread closes this channel
590 * while the write operation is in progress
591 *
592 * @throws ClosedByInterruptException
593 * If another thread interrupts the current thread
594 * while the write operation is in progress, thereby
595 * closing the channel and setting the current thread's
596 * interrupt status
597 *
598 * @throws IOException
599 * If some other I/O error occurs
600 */
601 public abstract int write(ByteBuffer src, long position)
602 throws IOException;
603
604 // -- Memory-mapped buffers --
605
606 /**
607 * A typesafe enumeration for file-mapping modes.
608 *
609 * @version 1.49, 07/05/05
610 * @since 1.4
611 *
612 * @see java.nio.channels.FileChannel#map
613 */
614 public static class MapMode {
615
616 /**
617 * Mode for a read-only mapping.
618 */
619 public static final MapMode READ_ONLY = new MapMode("READ_ONLY");
620
621 /**
622 * Mode for a read/write mapping.
623 */
624 public static final MapMode READ_WRITE = new MapMode(
625 "READ_WRITE");
626
627 /**
628 * Mode for a private (copy-on-write) mapping.
629 */
630 public static final MapMode PRIVATE = new MapMode("PRIVATE");
631
632 private final String name;
633
634 private MapMode(String name) {
635 this .name = name;
636 }
637
638 /**
639 * Returns a string describing this file-mapping mode.
640 *
641 * @return A descriptive string
642 */
643 public String toString() {
644 return name;
645 }
646
647 }
648
649 /**
650 * Maps a region of this channel's file directly into memory.
651 *
652 * <p> A region of a file may be mapped into memory in one of three modes:
653 * </p>
654 *
655 * <ul type=disc>
656 *
657 * <li><p> <i>Read-only:</i> Any attempt to modify the resulting buffer
658 * will cause a {@link java.nio.ReadOnlyBufferException} to be thrown.
659 * ({@link MapMode#READ_ONLY MapMode.READ_ONLY}) </p></li>
660 *
661 * <li><p> <i>Read/write:</i> Changes made to the resulting buffer will
662 * eventually be propagated to the file; they may or may not be made
663 * visible to other programs that have mapped the same file. ({@link
664 * MapMode#READ_WRITE MapMode.READ_WRITE}) </p></li>
665 *
666 * <li><p> <i>Private:</i> Changes made to the resulting buffer will not
667 * be propagated to the file and will not be visible to other programs
668 * that have mapped the same file; instead, they will cause private
669 * copies of the modified portions of the buffer to be created. ({@link
670 * MapMode#PRIVATE MapMode.PRIVATE}) </p></li>
671 *
672 * </ul>
673 *
674 * <p> For a read-only mapping, this channel must have been opened for
675 * reading; for a read/write or private mapping, this channel must have
676 * been opened for both reading and writing.
677 *
678 * <p> The {@link MappedByteBuffer </code>mapped byte buffer<code>}
679 * returned by this method will have a position of zero and a limit and
680 * capacity of <tt>size</tt>; its mark will be undefined. The buffer and
681 * the mapping that it represents will remain valid until the buffer itself
682 * is garbage-collected.
683 *
684 * <p> A mapping, once established, is not dependent upon the file channel
685 * that was used to create it. Closing the channel, in particular, has no
686 * effect upon the validity of the mapping.
687 *
688 * <p> Many of the details of memory-mapped files are inherently dependent
689 * upon the underlying operating system and are therefore unspecified. The
690 * behavior of this method when the requested region is not completely
691 * contained within this channel's file is unspecified. Whether changes
692 * made to the content or size of the underlying file, by this program or
693 * another, are propagated to the buffer is unspecified. The rate at which
694 * changes to the buffer are propagated to the file is unspecified.
695 *
696 * <p> For most operating systems, mapping a file into memory is more
697 * expensive than reading or writing a few tens of kilobytes of data via
698 * the usual {@link #read read} and {@link #write write} methods. From the
699 * standpoint of performance it is generally only worth mapping relatively
700 * large files into memory. </p>
701 *
702 * @param mode
703 * One of the constants {@link MapMode#READ_ONLY READ_ONLY}, {@link
704 * MapMode#READ_WRITE READ_WRITE}, or {@link MapMode#PRIVATE
705 * PRIVATE} defined in the {@link MapMode} class, according to
706 * whether the file is to be mapped read-only, read/write, or
707 * privately (copy-on-write), respectively
708 *
709 * @param position
710 * The position within the file at which the mapped region
711 * is to start; must be non-negative
712 *
713 * @param size
714 * The size of the region to be mapped; must be non-negative and
715 * no greater than {@link java.lang.Integer#MAX_VALUE}
716 *
717 * @throws NonReadableChannelException
718 * If the <tt>mode</tt> is {@link MapMode#READ_ONLY READ_ONLY} but
719 * this channel was not opened for reading
720 *
721 * @throws NonWritableChannelException
722 * If the <tt>mode</tt> is {@link MapMode#READ_WRITE READ_WRITE} or
723 * {@link MapMode#PRIVATE PRIVATE} but this channel was not opened
724 * for both reading and writing
725 *
726 * @throws IllegalArgumentException
727 * If the preconditions on the parameters do not hold
728 *
729 * @throws IOException
730 * If some other I/O error occurs
731 *
732 * @see java.nio.channels.FileChannel.MapMode
733 * @see java.nio.MappedByteBuffer
734 */
735 public abstract MappedByteBuffer map(MapMode mode, long position,
736 long size) throws IOException;
737
738 // -- Locks --
739
740 /**
741 * Acquires a lock on the given region of this channel's file.
742 *
743 * <p> An invocation of this method will block until the region can be
744 * locked, this channel is closed, or the invoking thread is interrupted,
745 * whichever comes first.
746 *
747 * <p> If this channel is closed by another thread during an invocation of
748 * this method then an {@link AsynchronousCloseException} will be thrown.
749 *
750 * <p> If the invoking thread is interrupted while waiting to acquire the
751 * lock then its interrupt status will be set and a {@link
752 * FileLockInterruptionException} will be thrown. If the invoker's
753 * interrupt status is set when this method is invoked then that exception
754 * will be thrown immediately; the thread's interrupt status will not be
755 * changed.
756 *
757 * <p> The region specified by the <tt>position</tt> and <tt>size</tt>
758 * parameters need not be contained within, or even overlap, the actual
759 * underlying file. Lock regions are fixed in size; if a locked region
760 * initially contains the end of the file and the file grows beyond the
761 * region then the new portion of the file will not be covered by the lock.
762 * If a file is expected to grow in size and a lock on the entire file is
763 * required then a region starting at zero, and no smaller than the
764 * expected maximum size of the file, should be locked. The zero-argument
765 * {@link #lock()} method simply locks a region of size {@link
766 * Long#MAX_VALUE}.
767 *
768 * <p> Some operating systems do not support shared locks, in which case a
769 * request for a shared lock is automatically converted into a request for
770 * an exclusive lock. Whether the newly-acquired lock is shared or
771 * exclusive may be tested by invoking the resulting lock object's {@link
772 * FileLock#isShared() isShared} method.
773 *
774 * <p> File locks are held on behalf of the entire Java virtual machine.
775 * They are not suitable for controlling access to a file by multiple
776 * threads within the same virtual machine. </p>
777 *
778 * @param position
779 * The position at which the locked region is to start; must be
780 * non-negative
781 *
782 * @param size
783 * The size of the locked region; must be non-negative, and the sum
784 * <tt>position</tt> + <tt>size</tt> must be non-negative
785 *
786 * @param shared
787 * <tt>true</tt> to request a shared lock, in which case this
788 * channel must be open for reading (and possibly writing);
789 * <tt>false</tt> to request an exclusive lock, in which case this
790 * channel must be open for writing (and possibly reading)
791 *
792 * @return A lock object representing the newly-acquired lock
793 *
794 * @throws IllegalArgumentException
795 * If the preconditions on the parameters do not hold
796 *
797 * @throws ClosedChannelException
798 * If this channel is closed
799 *
800 * @throws AsynchronousCloseException
801 * If another thread closes this channel while the invoking
802 * thread is blocked in this method
803 *
804 * @throws FileLockInterruptionException
805 * If the invoking thread is interrupted while blocked in this
806 * method
807 *
808 * @throws OverlappingFileLockException
809 * If a lock that overlaps the requested region is already held by
810 * this Java virtual machine, or if another thread is already
811 * blocked in this method and is attempting to lock an overlapping
812 * region
813 *
814 * @throws NonReadableChannelException
815 * If <tt>shared</tt> is <tt>true</tt> this channel was not
816 * opened for reading
817 *
818 * @throws NonWritableChannelException
819 * If <tt>shared</tt> is <tt>false</tt> but this channel was not
820 * opened for writing
821 *
822 * @throws IOException
823 * If some other I/O error occurs
824 *
825 * @see #lock()
826 * @see #tryLock()
827 * @see #tryLock(long,long,boolean)
828 */
829 public abstract FileLock lock(long position, long size,
830 boolean shared) throws IOException;
831
832 /**
833 * Acquires an exclusive lock on this channel's file.
834 *
835 * <p> An invocation of this method of the form <tt>fc.lock()</tt> behaves
836 * in exactly the same way as the invocation
837 *
838 * <pre>
839 * fc.{@link #lock(long,long,boolean) lock}(0L, Long.MAX_VALUE, false) </pre>
840 *
841 * @return A lock object representing the newly-acquired lock
842 *
843 * @throws ClosedChannelException
844 * If this channel is closed
845 *
846 * @throws AsynchronousCloseException
847 * If another thread closes this channel while the invoking
848 * thread is blocked in this method
849 *
850 * @throws FileLockInterruptionException
851 * If the invoking thread is interrupted while blocked in this
852 * method
853 *
854 * @throws OverlappingFileLockException
855 * If a lock that overlaps the requested region is already held by
856 * this Java virtual machine, or if another thread is already
857 * blocked in this method and is attempting to lock an overlapping
858 * region of the same file
859 *
860 * @throws NonWritableChannelException
861 * If this channel was not opened for writing
862 *
863 * @throws IOException
864 * If some other I/O error occurs
865 *
866 * @see #lock(long,long,boolean)
867 * @see #tryLock()
868 * @see #tryLock(long,long,boolean)
869 */
870 public final FileLock lock() throws IOException {
871 return lock(0L, Long.MAX_VALUE, false);
872 }
873
874 /**
875 * Attempts to acquire a lock on the given region of this channel's file.
876 *
877 * <p> This method does not block. An invocation always returns
878 * immediately, either having acquired a lock on the requested region or
879 * having failed to do so. If it fails to acquire a lock because an
880 * overlapping lock is held by another program then it returns
881 * <tt>null</tt>. If it fails to acquire a lock for any other reason then
882 * an appropriate exception is thrown.
883 *
884 * <p> The region specified by the <tt>position</tt> and <tt>size</tt>
885 * parameters need not be contained within, or even overlap, the actual
886 * underlying file. Lock regions are fixed in size; if a locked region
887 * initially contains the end of the file and the file grows beyond the
888 * region then the new portion of the file will not be covered by the lock.
889 * If a file is expected to grow in size and a lock on the entire file is
890 * required then a region starting at zero, and no smaller than the
891 * expected maximum size of the file, should be locked. The zero-argument
892 * {@link #tryLock()} method simply locks a region of size {@link
893 * Long#MAX_VALUE}.
894 *
895 * <p> Some operating systems do not support shared locks, in which case a
896 * request for a shared lock is automatically converted into a request for
897 * an exclusive lock. Whether the newly-acquired lock is shared or
898 * exclusive may be tested by invoking the resulting lock object's {@link
899 * FileLock#isShared() isShared} method.
900 *
901 * <p> File locks are held on behalf of the entire Java virtual machine.
902 * They are not suitable for controlling access to a file by multiple
903 * threads within the same virtual machine. </p>
904 *
905 * @param position
906 * The position at which the locked region is to start; must be
907 * non-negative
908 *
909 * @param size
910 * The size of the locked region; must be non-negative, and the sum
911 * <tt>position</tt> + <tt>size</tt> must be non-negative
912 *
913 * @param shared
914 * <tt>true</tt> to request a shared lock,
915 * <tt>false</tt> to request an exclusive lock
916 *
917 * @return A lock object representing the newly-acquired lock,
918 * or <tt>null</tt> if the lock could not be acquired
919 * because another program holds an overlapping lock
920 *
921 * @throws IllegalArgumentException
922 * If the preconditions on the parameters do not hold
923 *
924 * @throws ClosedChannelException
925 * If this channel is closed
926 *
927 * @throws OverlappingFileLockException
928 * If a lock that overlaps the requested region is already held by
929 * this Java virtual machine, or if another thread is already
930 * blocked in this method and is attempting to lock an overlapping
931 * region of the same file
932 *
933 * @throws IOException
934 * If some other I/O error occurs
935 *
936 * @see #lock()
937 * @see #lock(long,long,boolean)
938 * @see #tryLock()
939 */
940 public abstract FileLock tryLock(long position, long size,
941 boolean shared) throws IOException;
942
943 /**
944 * Attempts to acquire an exclusive lock on this channel's file.
945 *
946 * <p> An invocation of this method of the form <tt>fc.tryLock()</tt>
947 * behaves in exactly the same way as the invocation
948 *
949 * <pre>
950 * fc.{@link #tryLock(long,long,boolean) tryLock}(0L, Long.MAX_VALUE, false) </pre>
951 *
952 * @return A lock object representing the newly-acquired lock,
953 * or <tt>null</tt> if the lock could not be acquired
954 * because another program holds an overlapping lock
955 *
956 * @throws ClosedChannelException
957 * If this channel is closed
958 *
959 * @throws OverlappingFileLockException
960 * If a lock that overlaps the requested region is already held by
961 * this Java virtual machine, or if another thread is already
962 * blocked in this method and is attempting to lock an overlapping
963 * region
964 *
965 * @throws IOException
966 * If some other I/O error occurs
967 *
968 * @see #lock()
969 * @see #lock(long,long,boolean)
970 * @see #tryLock(long,long,boolean)
971 */
972 public final FileLock tryLock() throws IOException {
973 return tryLock(0L, Long.MAX_VALUE, false);
974 }
975
976 }
|