27 |
27 |
28 import java.io.*; |
28 import java.io.*; |
29 import java.nio.ByteBuffer; |
29 import java.nio.ByteBuffer; |
30 import java.nio.MappedByteBuffer; |
30 import java.nio.MappedByteBuffer; |
31 import java.nio.channels.spi.AbstractInterruptibleChannel; |
31 import java.nio.channels.spi.AbstractInterruptibleChannel; |
32 |
32 import java.nio.file.*; |
|
33 import java.nio.file.attribute.FileAttribute; |
|
34 import java.nio.file.spi.*; |
|
35 import java.util.Set; |
|
36 import java.util.HashSet; |
|
37 import java.util.Collections; |
33 |
38 |
34 /** |
39 /** |
35 * A channel for reading, writing, mapping, and manipulating a file. |
40 * A channel for reading, writing, mapping, and manipulating a file. |
36 * |
41 * |
37 * <p> A file channel has a current <i>position</i> within its file which can |
42 * <p> {@note revised} |
38 * be both {@link #position() </code>queried<code>} and {@link #position(long) |
43 * A file channel is a {@link SeekableByteChannel} that is connected to |
39 * </code>modified<code>}. The file itself contains a variable-length sequence |
44 * a file. It has a current <i>position</i> within its file which can |
|
45 * be both {@link #position() <i>queried</i>} and {@link #position(long) |
|
46 * <i>modified</i>}. The file itself contains a variable-length sequence |
40 * of bytes that can be read and written and whose current {@link #size |
47 * of bytes that can be read and written and whose current {@link #size |
41 * </code><i>size</i><code>} can be queried. The size of the file increases |
48 * <i>size</i>} can be queried. The size of the file increases |
42 * when bytes are written beyond its current size; the size of the file |
49 * when bytes are written beyond its current size; the size of the file |
43 * decreases when it is {@link #truncate </code><i>truncated</i><code>}. The |
50 * decreases when it is {@link #truncate </code><i>truncated</i><code>}. The |
44 * file may also have some associated <i>metadata</i> such as access |
51 * file may also have some associated <i>metadata</i> such as access |
45 * permissions, content type, and last-modification time; this class does not |
52 * permissions, content type, and last-modification time; this class does not |
46 * define methods for metadata access. |
53 * define methods for metadata access. |
48 * <p> In addition to the familiar read, write, and close operations of byte |
55 * <p> In addition to the familiar read, write, and close operations of byte |
49 * channels, this class defines the following file-specific operations: </p> |
56 * channels, this class defines the following file-specific operations: </p> |
50 * |
57 * |
51 * <ul> |
58 * <ul> |
52 * |
59 * |
53 * <li><p> Bytes may be {@link #read(ByteBuffer, long) </code>read<code>} or |
60 * <li><p> Bytes may be {@link #read(ByteBuffer, long) read} or |
54 * {@link #write(ByteBuffer, long) </code>written<code>} at an absolute |
61 * {@link #write(ByteBuffer, long) <i>written</i>} at an absolute |
55 * position in a file in a way that does not affect the channel's current |
62 * position in a file in a way that does not affect the channel's current |
56 * position. </p></li> |
63 * position. </p></li> |
57 * |
64 * |
58 * <li><p> A region of a file may be {@link #map </code>mapped<code>} |
65 * <li><p> A region of a file may be {@link #map <i>mapped</i>} |
59 * directly into memory; for large files this is often much more efficient |
66 * directly into memory; for large files this is often much more efficient |
60 * than invoking the usual <tt>read</tt> or <tt>write</tt> methods. |
67 * than invoking the usual <tt>read</tt> or <tt>write</tt> methods. |
61 * </p></li> |
68 * </p></li> |
62 * |
69 * |
63 * <li><p> Updates made to a file may be {@link #force </code>forced |
70 * <li><p> Updates made to a file may be {@link #force <i>forced |
64 * out<code>} to the underlying storage device, ensuring that data are not |
71 * out</i>} to the underlying storage device, ensuring that data are not |
65 * lost in the event of a system crash. </p></li> |
72 * lost in the event of a system crash. </p></li> |
66 * |
73 * |
67 * <li><p> Bytes can be transferred from a file {@link #transferTo </code>to |
74 * <li><p> Bytes can be transferred from a file {@link #transferTo <i>to |
68 * some other channel<code>}, and {@link #transferFrom </code>vice |
75 * some other channel</i>}, and {@link #transferFrom <i>vice |
69 * versa<code>}, in a way that can be optimized by many operating systems |
76 * versa</i>}, in a way that can be optimized by many operating systems |
70 * into a very fast transfer directly to or from the filesystem cache. |
77 * into a very fast transfer directly to or from the filesystem cache. |
71 * </p></li> |
78 * </p></li> |
72 * |
79 * |
73 * <li><p> A region of a file may be {@link FileLock </code>locked<code>} |
80 * <li><p> A region of a file may be {@link FileLock <i>locked</i>} |
74 * against access by other programs. </p></li> |
81 * against access by other programs. </p></li> |
75 * |
82 * |
76 * </ul> |
83 * </ul> |
77 * |
84 * |
78 * <p> File channels are safe for use by multiple concurrent threads. The |
85 * <p> File channels are safe for use by multiple concurrent threads. The |
94 * is true regardless of the language in which these other programs are |
101 * is true regardless of the language in which these other programs are |
95 * written, and whether they are running on the same machine or on some other |
102 * written, and whether they are running on the same machine or on some other |
96 * machine. The exact nature of any such inconsistencies are system-dependent |
103 * machine. The exact nature of any such inconsistencies are system-dependent |
97 * and are therefore unspecified. |
104 * and are therefore unspecified. |
98 * |
105 * |
99 * <p> This class does not define methods for opening existing files or for |
106 * <p> A file channel is created by invoking one of the {@link #open open} |
100 * creating new ones; such methods may be added in a future release. In this |
107 * methods defined by this class. A file channel can also be obtained from an |
101 * release a file channel can be obtained from an existing {@link |
108 * existing {@link java.io.FileInputStream#getChannel FileInputStream}, {@link |
102 * java.io.FileInputStream#getChannel FileInputStream}, {@link |
|
103 * java.io.FileOutputStream#getChannel FileOutputStream}, or {@link |
109 * java.io.FileOutputStream#getChannel FileOutputStream}, or {@link |
104 * java.io.RandomAccessFile#getChannel RandomAccessFile} object by invoking |
110 * java.io.RandomAccessFile#getChannel RandomAccessFile} object by invoking |
105 * that object's <tt>getChannel</tt> method, which returns a file channel that |
111 * that object's <tt>getChannel</tt> method, which returns a file channel that |
106 * is connected to the same underlying file. |
112 * is connected to the same underlying file. Where the file channel is obtained |
107 * |
113 * from an existing stream or random access file then the state of the file |
108 * <p> The state of a file channel is intimately connected to that of the |
114 * channel is intimately connected to that of the object whose <tt>getChannel</tt> |
109 * object whose <tt>getChannel</tt> method returned the channel. Changing the |
115 * method returned the channel. Changing the channel's position, whether |
110 * channel's position, whether explicitly or by reading or writing bytes, will |
116 * explicitly or by reading or writing bytes, will change the file position of |
111 * change the file position of the originating object, and vice versa. |
117 * the originating object, and vice versa. Changing the file's length via the |
112 * Changing the file's length via the file channel will change the length seen |
118 * file channel will change the length seen via the originating object, and vice |
113 * via the originating object, and vice versa. Changing the file's content by |
119 * versa. Changing the file's content by writing bytes will change the content |
114 * writing bytes will change the content seen by the originating object, and |
120 * seen by the originating object, and vice versa. |
115 * vice versa. |
121 * |
116 * |
122 * <a name="open-mode"></a> <p> At various points this class specifies that an |
117 * <a name="open-mode"><p> At various points this class specifies that an |
|
118 * instance that is "open for reading," "open for writing," or "open for |
123 * instance that is "open for reading," "open for writing," or "open for |
119 * reading and writing" is required. A channel obtained via the {@link |
124 * reading and writing" is required. A channel obtained via the {@link |
120 * java.io.FileInputStream#getChannel getChannel} method of a {@link |
125 * java.io.FileInputStream#getChannel getChannel} method of a {@link |
121 * java.io.FileInputStream} instance will be open for reading. A channel |
126 * java.io.FileInputStream} instance will be open for reading. A channel |
122 * obtained via the {@link java.io.FileOutputStream#getChannel getChannel} |
127 * obtained via the {@link java.io.FileOutputStream#getChannel getChannel} |
125 * java.io.RandomAccessFile#getChannel getChannel} method of a {@link |
130 * java.io.RandomAccessFile#getChannel getChannel} method of a {@link |
126 * java.io.RandomAccessFile} instance will be open for reading if the instance |
131 * java.io.RandomAccessFile} instance will be open for reading if the instance |
127 * was created with mode <tt>"r"</tt> and will be open for reading and writing |
132 * was created with mode <tt>"r"</tt> and will be open for reading and writing |
128 * if the instance was created with mode <tt>"rw"</tt>. |
133 * if the instance was created with mode <tt>"rw"</tt>. |
129 * |
134 * |
130 * <a name="append-mode"><p> A file channel that is open for writing may be in |
135 * <a name="append-mode"></a><p> A file channel that is open for writing may be in |
131 * <i>append mode</i>, for example if it was obtained from a file-output stream |
136 * <i>append mode</i>, for example if it was obtained from a file-output stream |
132 * that was created by invoking the {@link |
137 * that was created by invoking the {@link |
133 * java.io.FileOutputStream#FileOutputStream(java.io.File,boolean) |
138 * java.io.FileOutputStream#FileOutputStream(java.io.File,boolean) |
134 * FileOutputStream(File,boolean)} constructor and passing <tt>true</tt> for |
139 * FileOutputStream(File,boolean)} constructor and passing <tt>true</tt> for |
135 * the second parameter. In this mode each invocation of a relative write |
140 * the second parameter. In this mode each invocation of a relative write |
136 * operation first advances the position to the end of the file and then writes |
141 * operation first advances the position to the end of the file and then writes |
137 * the requested data. Whether the advancement of the position and the writing |
142 * the requested data. Whether the advancement of the position and the writing |
138 * of the data are done in a single atomic operation is system-dependent and |
143 * of the data are done in a single atomic operation is system-dependent and |
139 * therefore unspecified. |
144 * therefore unspecified. |
140 * |
145 * |
141 * |
|
142 * @see java.io.FileInputStream#getChannel() |
146 * @see java.io.FileInputStream#getChannel() |
143 * @see java.io.FileOutputStream#getChannel() |
147 * @see java.io.FileOutputStream#getChannel() |
144 * @see java.io.RandomAccessFile#getChannel() |
148 * @see java.io.RandomAccessFile#getChannel() |
145 * |
149 * |
146 * @author Mark Reinhold |
150 * @author Mark Reinhold |
147 * @author Mike McCloskey |
151 * @author Mike McCloskey |
148 * @author JSR-51 Expert Group |
152 * @author JSR-51 Expert Group |
149 * @since 1.4 |
153 * @since 1.4 |
|
154 * @updated 1.7 |
150 */ |
155 */ |
151 |
156 |
152 public abstract class FileChannel |
157 public abstract class FileChannel |
153 extends AbstractInterruptibleChannel |
158 extends AbstractInterruptibleChannel |
154 implements ByteChannel, GatheringByteChannel, ScatteringByteChannel |
159 implements SeekableByteChannel, GatheringByteChannel, ScatteringByteChannel |
155 { |
160 { |
156 |
|
157 /** |
161 /** |
158 * Initializes a new instance of this class. |
162 * Initializes a new instance of this class. |
159 */ |
163 */ |
160 protected FileChannel() { } |
164 protected FileChannel() { } |
161 |
165 |
|
166 /** |
|
167 * {@note new} |
|
168 * Opens or creates a file, returning a file channel to access the file. |
|
169 * |
|
170 * <p> The {@code options} parameter determines how the file is opened. |
|
171 * The {@link StandardOpenOption#READ READ} and {@link StandardOpenOption#WRITE |
|
172 * WRITE} options determine if the file should be opened for reading and/or |
|
173 * writing. If neither option (or the {@link StandardOpenOption#APPEND APPEND} |
|
174 * option) is contained in the array then the file is opened for reading. |
|
175 * By default reading or writing commences at the beginning of the file. |
|
176 * |
|
177 * <p> In the addition to {@code READ} and {@code WRITE}, the following |
|
178 * options may be present: |
|
179 * |
|
180 * <table border=1 cellpadding=5 summary=""> |
|
181 * <tr> <th>Option</th> <th>Description</th> </tr> |
|
182 * <tr> |
|
183 * <td> {@link StandardOpenOption#APPEND APPEND} </td> |
|
184 * <td> If this option is present then the file is opened for writing and |
|
185 * each invocation of the channel's {@code write} method first advances |
|
186 * the position to the end of the file and then writes the requested |
|
187 * data. Whether the advancement of the position and the writing of the |
|
188 * data are done in a single atomic operation is system-dependent and |
|
189 * therefore unspecified. This option may not be used in conjunction |
|
190 * with the {@code READ} or {@code TRUNCATE_EXISTING} options. </td> |
|
191 * </tr> |
|
192 * <tr> |
|
193 * <td> {@link StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING} </td> |
|
194 * <td> If this option is present then the existing file is truncated to |
|
195 * a size of 0 bytes. This option is ignored when the file is opened only |
|
196 * for reading. </td> |
|
197 * </tr> |
|
198 * <tr> |
|
199 * <td> {@link StandardOpenOption#CREATE_NEW CREATE_NEW} </td> |
|
200 * <td> If this option is present then a new file is created, failing if |
|
201 * the file already exists. When creating a file the check for the |
|
202 * existence of the file and the creation of the file if it does not exist |
|
203 * is atomic with respect to other file system operations. This option is |
|
204 * ignored when the file is opened only for reading. </td> |
|
205 * </tr> |
|
206 * <tr> |
|
207 * <td > {@link StandardOpenOption#CREATE CREATE} </td> |
|
208 * <td> If this option is present then an existing file is opened if it |
|
209 * exists, otherwise a new file is created. When creating a file the check |
|
210 * for the existence of the file and the creation of the file if it does |
|
211 * not exist is atomic with respect to other file system operations. This |
|
212 * option is ignored if the {@code CREATE_NEW} option is also present or |
|
213 * the file is opened only for reading. </td> |
|
214 * </tr> |
|
215 * <tr> |
|
216 * <td > {@link StandardOpenOption#DELETE_ON_CLOSE DELETE_ON_CLOSE} </td> |
|
217 * <td> When this option is present then the implementation makes a |
|
218 * <em>best effort</em> attempt to delete the file when closed by the |
|
219 * the {@link #close close} method. If the {@code close} method is not |
|
220 * invoked then a <em>best effort</em> attempt is made to delete the file |
|
221 * when the Java virtual machine terminates. </td> |
|
222 * </tr> |
|
223 * <tr> |
|
224 * <td>{@link StandardOpenOption#SPARSE SPARSE} </td> |
|
225 * <td> When creating a new file this option is a <em>hint</em> that the |
|
226 * new file will be sparse. This option is ignored when not creating |
|
227 * a new file. </td> |
|
228 * </tr> |
|
229 * <tr> |
|
230 * <td> {@link StandardOpenOption#SYNC SYNC} </td> |
|
231 * <td> Requires that every update to the file's content or metadata be |
|
232 * written synchronously to the underlying storage device. (see <a |
|
233 * href="../file/package-summary.html#integrity"> Synchronized I/O file |
|
234 * integrity</a>). </td> |
|
235 * <tr> |
|
236 * <tr> |
|
237 * <td> {@link StandardOpenOption#DSYNC DSYNC} </td> |
|
238 * <td> Requires that every update to the file's content be written |
|
239 * synchronously to the underlying storage device. (see <a |
|
240 * href="../file/package-summary.html#integrity"> Synchronized I/O file |
|
241 * integrity</a>). </td> |
|
242 * </tr> |
|
243 * </table> |
|
244 * |
|
245 * <p> An implementation may also support additional options. |
|
246 * |
|
247 * <p> The {@code attrs} parameter is an optional array of file {@link |
|
248 * FileAttribute file-attributes} to set atomically when creating the file. |
|
249 * |
|
250 * <p> The new channel is created by invoking the {@link |
|
251 * FileSystemProvider#newFileChannel newFileChannel} method on the |
|
252 * provider that created the {@code Path}. |
|
253 * |
|
254 * @param file |
|
255 * The path of the file to open or create |
|
256 * @param options |
|
257 * Options specifying how the file is opened |
|
258 * @param attrs |
|
259 * An optional list of file attributes to set atomically when |
|
260 * creating the file |
|
261 * |
|
262 * @return A new file channel |
|
263 * |
|
264 * @throws IllegalArgumentException |
|
265 * If the set contains an invalid combination of options |
|
266 * @throws UnsupportedOperationException |
|
267 * If the {@code file} is associated with a provider that does not |
|
268 * support creating file channels, or an unsupported open option is |
|
269 * specified, or the array contains an attribute that cannot be set |
|
270 * atomically when creating the file |
|
271 * @throws IOException |
|
272 * If an I/O error occurs |
|
273 * @throws SecurityException |
|
274 * If a security manager is installed and it denies an |
|
275 * unspecified permission required by the implementation. |
|
276 * In the case of the default provider, the {@link |
|
277 * SecurityManager#checkRead(String)} method is invoked to check |
|
278 * read access if the file is opened for reading. The {@link |
|
279 * SecurityManager#checkWrite(String)} method is invoked to check |
|
280 * write access if the file is opened for writing |
|
281 * |
|
282 * @since 1.7 |
|
283 */ |
|
284 public static FileChannel open(Path file, |
|
285 Set<? extends OpenOption> options, |
|
286 FileAttribute<?>... attrs) |
|
287 throws IOException |
|
288 { |
|
289 FileSystemProvider provider = file.getFileSystem().provider(); |
|
290 return provider.newFileChannel(file, options, attrs); |
|
291 } |
|
292 |
|
293 private static final FileAttribute<?>[] NO_ATTRIBUTES = new FileAttribute[0]; |
|
294 |
|
295 /** |
|
296 * {@note new} |
|
297 * Opens or creates a file, returning a file channel to access the file. |
|
298 * |
|
299 * <p> An invocation of this method behaves in exactly the same way as the |
|
300 * invocation |
|
301 * <pre> |
|
302 * fc.{@link #open(Path,Set,FileAttribute[]) open}(file, options, new FileAttribute<?>[0]); |
|
303 * </pre> |
|
304 * |
|
305 * @param file |
|
306 * The path of the file to open or create |
|
307 * @param options |
|
308 * Options specifying how the file is opened |
|
309 * |
|
310 * @return A new file channel |
|
311 * |
|
312 * @throws IllegalArgumentException |
|
313 * If the set contains an invalid combination of options |
|
314 * @throws UnsupportedOperationException |
|
315 * If the {@code file} is associated with a provider that does not |
|
316 * support creating file channels, or an unsupported open option is |
|
317 * specified |
|
318 * @throws IOException |
|
319 * If an I/O error occurs |
|
320 * @throws SecurityException |
|
321 * If a security manager is installed and it denies an |
|
322 * unspecified permission required by the implementation. |
|
323 * In the case of the default provider, the {@link |
|
324 * SecurityManager#checkRead(String)} method is invoked to check |
|
325 * read access if the file is opened for reading. The {@link |
|
326 * SecurityManager#checkWrite(String)} method is invoked to check |
|
327 * write access if the file is opened for writing |
|
328 * |
|
329 * @since 1.7 |
|
330 */ |
|
331 public static FileChannel open(Path file, OpenOption... options) |
|
332 throws IOException |
|
333 { |
|
334 Set<OpenOption> set = new HashSet<OpenOption>(options.length); |
|
335 Collections.addAll(set, options); |
|
336 return open(file, set, NO_ATTRIBUTES); |
|
337 } |
162 |
338 |
163 // -- Channel operations -- |
339 // -- Channel operations -- |
164 |
340 |
165 /** |
341 /** |
166 * Reads a sequence of bytes from this channel into the given buffer. |
342 * Reads a sequence of bytes from this channel into the given buffer. |