Java > Open Source Codes > java > nio > channels > FileChannel


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

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags