author | alanb |
Fri, 02 Nov 2012 15:50:11 +0000 | |
changeset 14342 | 8435a30053c1 |
parent 14014 | da3648e13e67 |
child 16048 | e8891a5d639f |
permissions | -rw-r--r-- |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1 |
/* |
14342
8435a30053c1
7197491: update copyright year to match last edit in jdk8 jdk repository
alanb
parents:
14014
diff
changeset
|
2 |
* Copyright (c) 2007, 2012, Oracle and/or its affiliates. All rights reserved. |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
3 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
4 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
5 |
* This code is free software; you can redistribute it and/or modify it |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
6 |
* under the terms of the GNU General Public License version 2 only, as |
5506 | 7 |
* published by the Free Software Foundation. Oracle designates this |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
8 |
* particular file as subject to the "Classpath" exception as provided |
5506 | 9 |
* by Oracle in the LICENSE file that accompanied this code. |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
10 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
11 |
* This code is distributed in the hope that it will be useful, but WITHOUT |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
12 |
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
13 |
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
14 |
* version 2 for more details (a copy is included in the LICENSE file that |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
15 |
* accompanied this code). |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
16 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
17 |
* You should have received a copy of the GNU General Public License version |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
18 |
* 2 along with this work; if not, write to the Free Software Foundation, |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
19 |
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
20 |
* |
5506 | 21 |
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
22 |
* or visit www.oracle.com if you need additional information or have any |
|
23 |
* questions. |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
24 |
*/ |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
25 |
|
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
26 |
package java.nio.file; |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
27 |
|
8158 | 28 |
import java.nio.file.attribute.*; |
29 |
import java.nio.file.spi.FileSystemProvider; |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
30 |
import java.nio.file.spi.FileTypeDetector; |
8158 | 31 |
import java.nio.channels.SeekableByteChannel; |
32 |
import java.io.InputStream; |
|
33 |
import java.io.OutputStream; |
|
34 |
import java.io.Reader; |
|
35 |
import java.io.Writer; |
|
36 |
import java.io.BufferedReader; |
|
37 |
import java.io.BufferedWriter; |
|
38 |
import java.io.InputStreamReader; |
|
39 |
import java.io.OutputStreamWriter; |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
40 |
import java.io.IOException; |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
41 |
import java.util.*; |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
42 |
import java.security.AccessController; |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
43 |
import java.security.PrivilegedAction; |
8158 | 44 |
import java.nio.charset.Charset; |
45 |
import java.nio.charset.CharsetDecoder; |
|
46 |
import java.nio.charset.CharsetEncoder; |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
47 |
|
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
48 |
/** |
8158 | 49 |
* This class consists exclusively of static methods that operate on files, |
50 |
* directories, or other types of files. |
|
51 |
* |
|
52 |
* <p> In most cases, the methods defined here will delegate to the associated |
|
53 |
* file system provider to perform the file operations. |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
54 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
55 |
* @since 1.7 |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
56 |
*/ |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
57 |
|
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
58 |
public final class Files { |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
59 |
private Files() { } |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
60 |
|
8158 | 61 |
/** |
62 |
* Returns the {@code FileSystemProvider} to delegate to. |
|
63 |
*/ |
|
64 |
private static FileSystemProvider provider(Path path) { |
|
65 |
return path.getFileSystem().provider(); |
|
66 |
} |
|
67 |
||
68 |
// -- File contents -- |
|
69 |
||
70 |
/** |
|
71 |
* Opens a file, returning an input stream to read from the file. The stream |
|
72 |
* will not be buffered, and is not required to support the {@link |
|
73 |
* InputStream#mark mark} or {@link InputStream#reset reset} methods. The |
|
74 |
* stream will be safe for access by multiple concurrent threads. Reading |
|
75 |
* commences at the beginning of the file. Whether the returned stream is |
|
76 |
* <i>asynchronously closeable</i> and/or <i>interruptible</i> is highly |
|
77 |
* file system provider specific and therefore not specified. |
|
78 |
* |
|
79 |
* <p> The {@code options} parameter determines how the file is opened. |
|
80 |
* If no options are present then it is equivalent to opening the file with |
|
81 |
* the {@link StandardOpenOption#READ READ} option. In addition to the {@code |
|
82 |
* READ} option, an implementation may also support additional implementation |
|
83 |
* specific options. |
|
84 |
* |
|
85 |
* @param path |
|
86 |
* the path to the file to open |
|
87 |
* @param options |
|
88 |
* options specifying how the file is opened |
|
89 |
* |
|
90 |
* @return a new input stream |
|
91 |
* |
|
92 |
* @throws IllegalArgumentException |
|
93 |
* if an invalid combination of options is specified |
|
94 |
* @throws UnsupportedOperationException |
|
95 |
* if an unsupported option is specified |
|
96 |
* @throws IOException |
|
97 |
* if an I/O error occurs |
|
98 |
* @throws SecurityException |
|
99 |
* In the case of the default provider, and a security manager is |
|
100 |
* installed, the {@link SecurityManager#checkRead(String) checkRead} |
|
101 |
* method is invoked to check read access to the file. |
|
102 |
*/ |
|
103 |
public static InputStream newInputStream(Path path, OpenOption... options) |
|
104 |
throws IOException |
|
105 |
{ |
|
106 |
return provider(path).newInputStream(path, options); |
|
107 |
} |
|
108 |
||
109 |
/** |
|
110 |
* Opens or creates a file, returning an output stream that may be used to |
|
111 |
* write bytes to the file. The resulting stream will not be buffered. The |
|
112 |
* stream will be safe for access by multiple concurrent threads. Whether |
|
113 |
* the returned stream is <i>asynchronously closeable</i> and/or |
|
114 |
* <i>interruptible</i> is highly file system provider specific and |
|
115 |
* therefore not specified. |
|
116 |
* |
|
117 |
* <p> This method opens or creates a file in exactly the manner specified |
|
118 |
* by the {@link #newByteChannel(Path,Set,FileAttribute[]) newByteChannel} |
|
119 |
* method with the exception that the {@link StandardOpenOption#READ READ} |
|
120 |
* option may not be present in the array of options. If no options are |
|
121 |
* present then this method works as if the {@link StandardOpenOption#CREATE |
|
122 |
* CREATE}, {@link StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING}, |
|
123 |
* and {@link StandardOpenOption#WRITE WRITE} options are present. In other |
|
124 |
* words, it opens the file for writing, creating the file if it doesn't |
|
125 |
* exist, or initially truncating an existing {@link #isRegularFile |
|
126 |
* regular-file} to a size of {@code 0} if it exists. |
|
127 |
* |
|
128 |
* <p> <b>Usage Examples:</b> |
|
129 |
* <pre> |
|
130 |
* Path path = ... |
|
131 |
* |
|
8539
eeb9fc5a68c1
7020888: (file) Miscellaneous and trivial clean-ups (typos and opportunities to use suppressed exceptions)
alanb
parents:
8166
diff
changeset
|
132 |
* // truncate and overwrite an existing file, or create the file if |
eeb9fc5a68c1
7020888: (file) Miscellaneous and trivial clean-ups (typos and opportunities to use suppressed exceptions)
alanb
parents:
8166
diff
changeset
|
133 |
* // it doesn't initially exist |
8158 | 134 |
* OutputStream out = Files.newOutputStream(path); |
135 |
* |
|
136 |
* // append to an existing file, fail if the file does not exist |
|
137 |
* out = Files.newOutputStream(path, APPEND); |
|
138 |
* |
|
139 |
* // append to an existing file, create file if it doesn't initially exist |
|
8539
eeb9fc5a68c1
7020888: (file) Miscellaneous and trivial clean-ups (typos and opportunities to use suppressed exceptions)
alanb
parents:
8166
diff
changeset
|
140 |
* out = Files.newOutputStream(path, CREATE, APPEND); |
8158 | 141 |
* |
142 |
* // always create new file, failing if it already exists |
|
8539
eeb9fc5a68c1
7020888: (file) Miscellaneous and trivial clean-ups (typos and opportunities to use suppressed exceptions)
alanb
parents:
8166
diff
changeset
|
143 |
* out = Files.newOutputStream(path, CREATE_NEW); |
8158 | 144 |
* </pre> |
145 |
* |
|
146 |
* @param path |
|
147 |
* the path to the file to open or create |
|
148 |
* @param options |
|
149 |
* options specifying how the file is opened |
|
150 |
* |
|
151 |
* @return a new output stream |
|
152 |
* |
|
153 |
* @throws IllegalArgumentException |
|
154 |
* if {@code options} contains an invalid combination of options |
|
155 |
* @throws UnsupportedOperationException |
|
156 |
* if an unsupported option is specified |
|
157 |
* @throws IOException |
|
158 |
* if an I/O error occurs |
|
159 |
* @throws SecurityException |
|
160 |
* In the case of the default provider, and a security manager is |
|
161 |
* installed, the {@link SecurityManager#checkWrite(String) checkWrite} |
|
162 |
* method is invoked to check write access to the file. The {@link |
|
163 |
* SecurityManager#checkDelete(String) checkDelete} method is |
|
164 |
* invoked to check delete access if the file is opened with the |
|
165 |
* {@code DELETE_ON_CLOSE} option. |
|
166 |
*/ |
|
167 |
public static OutputStream newOutputStream(Path path, OpenOption... options) |
|
168 |
throws IOException |
|
169 |
{ |
|
170 |
return provider(path).newOutputStream(path, options); |
|
171 |
} |
|
172 |
||
173 |
/** |
|
174 |
* Opens or creates a file, returning a seekable byte channel to access the |
|
175 |
* file. |
|
176 |
* |
|
177 |
* <p> The {@code options} parameter determines how the file is opened. |
|
178 |
* The {@link StandardOpenOption#READ READ} and {@link |
|
179 |
* StandardOpenOption#WRITE WRITE} options determine if the file should be |
|
180 |
* opened for reading and/or writing. If neither option (or the {@link |
|
181 |
* StandardOpenOption#APPEND APPEND} option) is present then the file is |
|
182 |
* opened for reading. By default reading or writing commence at the |
|
183 |
* beginning of the file. |
|
184 |
* |
|
185 |
* <p> In the addition to {@code READ} and {@code WRITE}, the following |
|
186 |
* options may be present: |
|
187 |
* |
|
188 |
* <table border=1 cellpadding=5 summary=""> |
|
189 |
* <tr> <th>Option</th> <th>Description</th> </tr> |
|
190 |
* <tr> |
|
191 |
* <td> {@link StandardOpenOption#APPEND APPEND} </td> |
|
192 |
* <td> If this option is present then the file is opened for writing and |
|
193 |
* each invocation of the channel's {@code write} method first advances |
|
194 |
* the position to the end of the file and then writes the requested |
|
195 |
* data. Whether the advancement of the position and the writing of the |
|
196 |
* data are done in a single atomic operation is system-dependent and |
|
197 |
* therefore unspecified. This option may not be used in conjunction |
|
198 |
* with the {@code READ} or {@code TRUNCATE_EXISTING} options. </td> |
|
199 |
* </tr> |
|
200 |
* <tr> |
|
201 |
* <td> {@link StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING} </td> |
|
202 |
* <td> If this option is present then the existing file is truncated to |
|
203 |
* a size of 0 bytes. This option is ignored when the file is opened only |
|
204 |
* for reading. </td> |
|
205 |
* </tr> |
|
206 |
* <tr> |
|
207 |
* <td> {@link StandardOpenOption#CREATE_NEW CREATE_NEW} </td> |
|
208 |
* <td> If this option is present then a new file is created, failing if |
|
209 |
* the file already exists or is a symbolic link. When creating a file the |
|
210 |
* check for the existence of the file and the creation of the file if it |
|
211 |
* does not exist is atomic with respect to other file system operations. |
|
212 |
* This option is ignored when the file is opened only for reading. </td> |
|
213 |
* </tr> |
|
214 |
* <tr> |
|
215 |
* <td > {@link StandardOpenOption#CREATE CREATE} </td> |
|
216 |
* <td> If this option is present then an existing file is opened if it |
|
217 |
* exists, otherwise a new file is created. This option is ignored if the |
|
218 |
* {@code CREATE_NEW} option is also present or the file is opened only |
|
219 |
* for reading. </td> |
|
220 |
* </tr> |
|
221 |
* <tr> |
|
222 |
* <td > {@link StandardOpenOption#DELETE_ON_CLOSE DELETE_ON_CLOSE} </td> |
|
223 |
* <td> When this option is present then the implementation makes a |
|
224 |
* <em>best effort</em> attempt to delete the file when closed by the |
|
225 |
* {@link SeekableByteChannel#close close} method. If the {@code close} |
|
226 |
* method is not invoked then a <em>best effort</em> attempt is made to |
|
227 |
* delete the file when the Java virtual machine terminates. </td> |
|
228 |
* </tr> |
|
229 |
* <tr> |
|
230 |
* <td>{@link StandardOpenOption#SPARSE SPARSE} </td> |
|
231 |
* <td> When creating a new file this option is a <em>hint</em> that the |
|
232 |
* new file will be sparse. This option is ignored when not creating |
|
233 |
* a new file. </td> |
|
234 |
* </tr> |
|
235 |
* <tr> |
|
236 |
* <td> {@link StandardOpenOption#SYNC SYNC} </td> |
|
237 |
* <td> Requires that every update to the file's content or metadata be |
|
238 |
* written synchronously to the underlying storage device. (see <a |
|
239 |
* href="package-summary.html#integrity"> Synchronized I/O file |
|
240 |
* integrity</a>). </td> |
|
241 |
* <tr> |
|
242 |
* <tr> |
|
243 |
* <td> {@link StandardOpenOption#DSYNC DSYNC} </td> |
|
244 |
* <td> Requires that every update to the file's content be written |
|
245 |
* synchronously to the underlying storage device. (see <a |
|
246 |
* href="package-summary.html#integrity"> Synchronized I/O file |
|
247 |
* integrity</a>). </td> |
|
248 |
* </tr> |
|
249 |
* </table> |
|
250 |
* |
|
251 |
* <p> An implementation may also support additional implementation specific |
|
252 |
* options. |
|
253 |
* |
|
254 |
* <p> The {@code attrs} parameter is optional {@link FileAttribute |
|
255 |
* file-attributes} to set atomically when a new file is created. |
|
256 |
* |
|
257 |
* <p> In the case of the default provider, the returned seekable byte channel |
|
258 |
* is a {@link java.nio.channels.FileChannel}. |
|
259 |
* |
|
260 |
* <p> <b>Usage Examples:</b> |
|
261 |
* <pre> |
|
262 |
* Path path = ... |
|
263 |
* |
|
264 |
* // open file for reading |
|
265 |
* ReadableByteChannel rbc = Files.newByteChannel(path, EnumSet.of(READ))); |
|
266 |
* |
|
267 |
* // open file for writing to the end of an existing file, creating |
|
268 |
* // the file if it doesn't already exist |
|
269 |
* WritableByteChannel wbc = Files.newByteChannel(path, EnumSet.of(CREATE,APPEND)); |
|
270 |
* |
|
271 |
* // create file with initial permissions, opening it for both reading and writing |
|
12421 | 272 |
* {@code FileAttribute<Set<PosixFilePermission>> perms = ...} |
8158 | 273 |
* SeekableByteChannel sbc = Files.newByteChannel(path, EnumSet.of(CREATE_NEW,READ,WRITE), perms); |
274 |
* </pre> |
|
275 |
* |
|
276 |
* @param path |
|
277 |
* the path to the file to open or create |
|
278 |
* @param options |
|
279 |
* options specifying how the file is opened |
|
280 |
* @param attrs |
|
281 |
* an optional list of file attributes to set atomically when |
|
282 |
* creating the file |
|
283 |
* |
|
284 |
* @return a new seekable byte channel |
|
285 |
* |
|
286 |
* @throws IllegalArgumentException |
|
287 |
* if the set contains an invalid combination of options |
|
288 |
* @throws UnsupportedOperationException |
|
289 |
* if an unsupported open option is specified or the array contains |
|
290 |
* attributes that cannot be set atomically when creating the file |
|
291 |
* @throws FileAlreadyExistsException |
|
292 |
* if a file of that name already exists and the {@link |
|
293 |
* StandardOpenOption#CREATE_NEW CREATE_NEW} option is specified |
|
294 |
* <i>(optional specific exception)</i> |
|
295 |
* @throws IOException |
|
296 |
* if an I/O error occurs |
|
297 |
* @throws SecurityException |
|
298 |
* In the case of the default provider, and a security manager is |
|
299 |
* installed, the {@link SecurityManager#checkRead(String) checkRead} |
|
300 |
* method is invoked to check read access to the path if the file is |
|
301 |
* opened for reading. The {@link SecurityManager#checkWrite(String) |
|
302 |
* checkWrite} method is invoked to check write access to the path |
|
303 |
* if the file is opened for writing. The {@link |
|
304 |
* SecurityManager#checkDelete(String) checkDelete} method is |
|
305 |
* invoked to check delete access if the file is opened with the |
|
306 |
* {@code DELETE_ON_CLOSE} option. |
|
307 |
* |
|
308 |
* @see java.nio.channels.FileChannel#open(Path,Set,FileAttribute[]) |
|
309 |
*/ |
|
310 |
public static SeekableByteChannel newByteChannel(Path path, |
|
311 |
Set<? extends OpenOption> options, |
|
312 |
FileAttribute<?>... attrs) |
|
313 |
throws IOException |
|
314 |
{ |
|
315 |
return provider(path).newByteChannel(path, options, attrs); |
|
316 |
} |
|
317 |
||
318 |
/** |
|
319 |
* Opens or creates a file, returning a seekable byte channel to access the |
|
320 |
* file. |
|
321 |
* |
|
322 |
* <p> This method opens or creates a file in exactly the manner specified |
|
323 |
* by the {@link #newByteChannel(Path,Set,FileAttribute[]) newByteChannel} |
|
324 |
* method. |
|
325 |
* |
|
326 |
* @param path |
|
327 |
* the path to the file to open or create |
|
328 |
* @param options |
|
329 |
* options specifying how the file is opened |
|
330 |
* |
|
331 |
* @return a new seekable byte channel |
|
332 |
* |
|
333 |
* @throws IllegalArgumentException |
|
334 |
* if the set contains an invalid combination of options |
|
335 |
* @throws UnsupportedOperationException |
|
336 |
* if an unsupported open option is specified |
|
337 |
* @throws FileAlreadyExistsException |
|
338 |
* if a file of that name already exists and the {@link |
|
339 |
* StandardOpenOption#CREATE_NEW CREATE_NEW} option is specified |
|
340 |
* <i>(optional specific exception)</i> |
|
341 |
* @throws IOException |
|
342 |
* if an I/O error occurs |
|
343 |
* @throws SecurityException |
|
344 |
* In the case of the default provider, and a security manager is |
|
345 |
* installed, the {@link SecurityManager#checkRead(String) checkRead} |
|
346 |
* method is invoked to check read access to the path if the file is |
|
347 |
* opened for reading. The {@link SecurityManager#checkWrite(String) |
|
348 |
* checkWrite} method is invoked to check write access to the path |
|
349 |
* if the file is opened for writing. The {@link |
|
350 |
* SecurityManager#checkDelete(String) checkDelete} method is |
|
351 |
* invoked to check delete access if the file is opened with the |
|
352 |
* {@code DELETE_ON_CLOSE} option. |
|
353 |
* |
|
354 |
* @see java.nio.channels.FileChannel#open(Path,OpenOption[]) |
|
355 |
*/ |
|
356 |
public static SeekableByteChannel newByteChannel(Path path, OpenOption... options) |
|
357 |
throws IOException |
|
358 |
{ |
|
359 |
Set<OpenOption> set = new HashSet<OpenOption>(options.length); |
|
360 |
Collections.addAll(set, options); |
|
361 |
return newByteChannel(path, set); |
|
362 |
} |
|
363 |
||
364 |
// -- Directories -- |
|
365 |
||
10891
8c554ab7cfed
7103889: (fs) Reduce String concatenation when iterating over directory
alanb
parents:
9050
diff
changeset
|
366 |
private static class AcceptAllFilter |
8c554ab7cfed
7103889: (fs) Reduce String concatenation when iterating over directory
alanb
parents:
9050
diff
changeset
|
367 |
implements DirectoryStream.Filter<Path> |
8c554ab7cfed
7103889: (fs) Reduce String concatenation when iterating over directory
alanb
parents:
9050
diff
changeset
|
368 |
{ |
8c554ab7cfed
7103889: (fs) Reduce String concatenation when iterating over directory
alanb
parents:
9050
diff
changeset
|
369 |
private AcceptAllFilter() { } |
8c554ab7cfed
7103889: (fs) Reduce String concatenation when iterating over directory
alanb
parents:
9050
diff
changeset
|
370 |
|
8c554ab7cfed
7103889: (fs) Reduce String concatenation when iterating over directory
alanb
parents:
9050
diff
changeset
|
371 |
@Override |
8c554ab7cfed
7103889: (fs) Reduce String concatenation when iterating over directory
alanb
parents:
9050
diff
changeset
|
372 |
public boolean accept(Path entry) { return true; } |
8c554ab7cfed
7103889: (fs) Reduce String concatenation when iterating over directory
alanb
parents:
9050
diff
changeset
|
373 |
|
8c554ab7cfed
7103889: (fs) Reduce String concatenation when iterating over directory
alanb
parents:
9050
diff
changeset
|
374 |
static final AcceptAllFilter FILTER = new AcceptAllFilter(); |
8c554ab7cfed
7103889: (fs) Reduce String concatenation when iterating over directory
alanb
parents:
9050
diff
changeset
|
375 |
} |
8c554ab7cfed
7103889: (fs) Reduce String concatenation when iterating over directory
alanb
parents:
9050
diff
changeset
|
376 |
|
8158 | 377 |
/** |
378 |
* Opens a directory, returning a {@link DirectoryStream} to iterate over |
|
379 |
* all entries in the directory. The elements returned by the directory |
|
380 |
* stream's {@link DirectoryStream#iterator iterator} are of type {@code |
|
381 |
* Path}, each one representing an entry in the directory. The {@code Path} |
|
382 |
* objects are obtained as if by {@link Path#resolve(Path) resolving} the |
|
383 |
* name of the directory entry against {@code dir}. |
|
384 |
* |
|
385 |
* <p> When not using the try-with-resources construct, then directory |
|
386 |
* stream's {@code close} method should be invoked after iteration is |
|
387 |
* completed so as to free any resources held for the open directory. |
|
388 |
* |
|
389 |
* <p> When an implementation supports operations on entries in the |
|
390 |
* directory that execute in a race-free manner then the returned directory |
|
391 |
* stream is a {@link SecureDirectoryStream}. |
|
392 |
* |
|
393 |
* @param dir |
|
394 |
* the path to the directory |
|
395 |
* |
|
396 |
* @return a new and open {@code DirectoryStream} object |
|
397 |
* |
|
398 |
* @throws NotDirectoryException |
|
399 |
* if the file could not otherwise be opened because it is not |
|
400 |
* a directory <i>(optional specific exception)</i> |
|
401 |
* @throws IOException |
|
402 |
* if an I/O error occurs |
|
403 |
* @throws SecurityException |
|
404 |
* In the case of the default provider, and a security manager is |
|
405 |
* installed, the {@link SecurityManager#checkRead(String) checkRead} |
|
406 |
* method is invoked to check read access to the directory. |
|
407 |
*/ |
|
408 |
public static DirectoryStream<Path> newDirectoryStream(Path dir) |
|
409 |
throws IOException |
|
410 |
{ |
|
10891
8c554ab7cfed
7103889: (fs) Reduce String concatenation when iterating over directory
alanb
parents:
9050
diff
changeset
|
411 |
return provider(dir).newDirectoryStream(dir, AcceptAllFilter.FILTER); |
8158 | 412 |
} |
413 |
||
414 |
/** |
|
415 |
* Opens a directory, returning a {@link DirectoryStream} to iterate over |
|
416 |
* the entries in the directory. The elements returned by the directory |
|
417 |
* stream's {@link DirectoryStream#iterator iterator} are of type {@code |
|
418 |
* Path}, each one representing an entry in the directory. The {@code Path} |
|
419 |
* objects are obtained as if by {@link Path#resolve(Path) resolving} the |
|
420 |
* name of the directory entry against {@code dir}. The entries returned by |
|
421 |
* the iterator are filtered by matching the {@code String} representation |
|
422 |
* of their file names against the given <em>globbing</em> pattern. |
|
423 |
* |
|
424 |
* <p> For example, suppose we want to iterate over the files ending with |
|
425 |
* ".java" in a directory: |
|
426 |
* <pre> |
|
427 |
* Path dir = ... |
|
428 |
* try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir, "*.java")) { |
|
429 |
* : |
|
430 |
* } |
|
431 |
* </pre> |
|
432 |
* |
|
433 |
* <p> The globbing pattern is specified by the {@link |
|
434 |
* FileSystem#getPathMatcher getPathMatcher} method. |
|
435 |
* |
|
436 |
* <p> When not using the try-with-resources construct, then directory |
|
437 |
* stream's {@code close} method should be invoked after iteration is |
|
438 |
* completed so as to free any resources held for the open directory. |
|
439 |
* |
|
440 |
* <p> When an implementation supports operations on entries in the |
|
441 |
* directory that execute in a race-free manner then the returned directory |
|
442 |
* stream is a {@link SecureDirectoryStream}. |
|
443 |
* |
|
444 |
* @param dir |
|
445 |
* the path to the directory |
|
446 |
* @param glob |
|
447 |
* the glob pattern |
|
448 |
* |
|
449 |
* @return a new and open {@code DirectoryStream} object |
|
450 |
* |
|
451 |
* @throws java.util.regex.PatternSyntaxException |
|
452 |
* if the pattern is invalid |
|
453 |
* @throws NotDirectoryException |
|
454 |
* if the file could not otherwise be opened because it is not |
|
455 |
* a directory <i>(optional specific exception)</i> |
|
456 |
* @throws IOException |
|
457 |
* if an I/O error occurs |
|
458 |
* @throws SecurityException |
|
459 |
* In the case of the default provider, and a security manager is |
|
460 |
* installed, the {@link SecurityManager#checkRead(String) checkRead} |
|
461 |
* method is invoked to check read access to the directory. |
|
462 |
*/ |
|
463 |
public static DirectoryStream<Path> newDirectoryStream(Path dir, String glob) |
|
464 |
throws IOException |
|
465 |
{ |
|
466 |
// avoid creating a matcher if all entries are required. |
|
467 |
if (glob.equals("*")) |
|
468 |
return newDirectoryStream(dir); |
|
469 |
||
470 |
// create a matcher and return a filter that uses it. |
|
471 |
FileSystem fs = dir.getFileSystem(); |
|
472 |
final PathMatcher matcher = fs.getPathMatcher("glob:" + glob); |
|
473 |
DirectoryStream.Filter<Path> filter = new DirectoryStream.Filter<Path>() { |
|
474 |
@Override |
|
475 |
public boolean accept(Path entry) { |
|
476 |
return matcher.matches(entry.getFileName()); |
|
477 |
} |
|
478 |
}; |
|
479 |
return fs.provider().newDirectoryStream(dir, filter); |
|
480 |
} |
|
481 |
||
482 |
/** |
|
483 |
* Opens a directory, returning a {@link DirectoryStream} to iterate over |
|
484 |
* the entries in the directory. The elements returned by the directory |
|
485 |
* stream's {@link DirectoryStream#iterator iterator} are of type {@code |
|
486 |
* Path}, each one representing an entry in the directory. The {@code Path} |
|
487 |
* objects are obtained as if by {@link Path#resolve(Path) resolving} the |
|
488 |
* name of the directory entry against {@code dir}. The entries returned by |
|
489 |
* the iterator are filtered by the given {@link DirectoryStream.Filter |
|
490 |
* filter}. |
|
491 |
* |
|
492 |
* <p> When not using the try-with-resources construct, then directory |
|
493 |
* stream's {@code close} method should be invoked after iteration is |
|
494 |
* completed so as to free any resources held for the open directory. |
|
495 |
* |
|
496 |
* <p> Where the filter terminates due to an uncaught error or runtime |
|
497 |
* exception then it is propagated to the {@link Iterator#hasNext() |
|
498 |
* hasNext} or {@link Iterator#next() next} method. Where an {@code |
|
499 |
* IOException} is thrown, it results in the {@code hasNext} or {@code |
|
500 |
* next} method throwing a {@link DirectoryIteratorException} with the |
|
501 |
* {@code IOException} as the cause. |
|
502 |
* |
|
503 |
* <p> When an implementation supports operations on entries in the |
|
504 |
* directory that execute in a race-free manner then the returned directory |
|
505 |
* stream is a {@link SecureDirectoryStream}. |
|
506 |
* |
|
507 |
* <p> <b>Usage Example:</b> |
|
508 |
* Suppose we want to iterate over the files in a directory that are |
|
509 |
* larger than 8K. |
|
510 |
* <pre> |
|
511 |
* DirectoryStream.Filter<Path> filter = new DirectoryStream.Filter<Path>() { |
|
512 |
* public boolean accept(Path file) throws IOException { |
|
14014 | 513 |
* return (Files.size(file) > 8192L); |
8158 | 514 |
* } |
515 |
* }; |
|
516 |
* Path dir = ... |
|
517 |
* try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir, filter)) { |
|
518 |
* : |
|
519 |
* } |
|
520 |
* </pre> |
|
521 |
* |
|
522 |
* @param dir |
|
523 |
* the path to the directory |
|
524 |
* @param filter |
|
525 |
* the directory stream filter |
|
526 |
* |
|
527 |
* @return a new and open {@code DirectoryStream} object |
|
528 |
* |
|
529 |
* @throws NotDirectoryException |
|
530 |
* if the file could not otherwise be opened because it is not |
|
531 |
* a directory <i>(optional specific exception)</i> |
|
532 |
* @throws IOException |
|
533 |
* if an I/O error occurs |
|
534 |
* @throws SecurityException |
|
535 |
* In the case of the default provider, and a security manager is |
|
536 |
* installed, the {@link SecurityManager#checkRead(String) checkRead} |
|
537 |
* method is invoked to check read access to the directory. |
|
538 |
*/ |
|
539 |
public static DirectoryStream<Path> newDirectoryStream(Path dir, |
|
540 |
DirectoryStream.Filter<? super Path> filter) |
|
541 |
throws IOException |
|
542 |
{ |
|
543 |
return provider(dir).newDirectoryStream(dir, filter); |
|
544 |
} |
|
545 |
||
546 |
// -- Creation and deletion -- |
|
547 |
||
548 |
/** |
|
549 |
* Creates a new and empty file, failing if the file already exists. The |
|
550 |
* check for the existence of the file and the creation of the new file if |
|
551 |
* it does not exist are a single operation that is atomic with respect to |
|
552 |
* all other filesystem activities that might affect the directory. |
|
553 |
* |
|
554 |
* <p> The {@code attrs} parameter is optional {@link FileAttribute |
|
555 |
* file-attributes} to set atomically when creating the file. Each attribute |
|
556 |
* is identified by its {@link FileAttribute#name name}. If more than one |
|
557 |
* attribute of the same name is included in the array then all but the last |
|
558 |
* occurrence is ignored. |
|
559 |
* |
|
560 |
* @param path |
|
561 |
* the path to the file to create |
|
562 |
* @param attrs |
|
563 |
* an optional list of file attributes to set atomically when |
|
564 |
* creating the file |
|
565 |
* |
|
566 |
* @return the file |
|
567 |
* |
|
568 |
* @throws UnsupportedOperationException |
|
569 |
* if the array contains an attribute that cannot be set atomically |
|
570 |
* when creating the file |
|
571 |
* @throws FileAlreadyExistsException |
|
572 |
* if a file of that name already exists |
|
573 |
* <i>(optional specific exception)</i> |
|
574 |
* @throws IOException |
|
575 |
* if an I/O error occurs or the parent directory does not exist |
|
576 |
* @throws SecurityException |
|
577 |
* In the case of the default provider, and a security manager is |
|
578 |
* installed, the {@link SecurityManager#checkWrite(String) checkWrite} |
|
579 |
* method is invoked to check write access to the new file. |
|
580 |
*/ |
|
581 |
public static Path createFile(Path path, FileAttribute<?>... attrs) |
|
582 |
throws IOException |
|
583 |
{ |
|
584 |
EnumSet<StandardOpenOption> options = |
|
585 |
EnumSet.<StandardOpenOption>of(StandardOpenOption.CREATE_NEW, StandardOpenOption.WRITE); |
|
586 |
newByteChannel(path, options, attrs).close(); |
|
587 |
return path; |
|
588 |
} |
|
589 |
||
590 |
/** |
|
591 |
* Creates a new directory. The check for the existence of the file and the |
|
592 |
* creation of the directory if it does not exist are a single operation |
|
593 |
* that is atomic with respect to all other filesystem activities that might |
|
594 |
* affect the directory. The {@link #createDirectories createDirectories} |
|
595 |
* method should be used where it is required to create all nonexistent |
|
596 |
* parent directories first. |
|
597 |
* |
|
598 |
* <p> The {@code attrs} parameter is optional {@link FileAttribute |
|
599 |
* file-attributes} to set atomically when creating the directory. Each |
|
600 |
* attribute is identified by its {@link FileAttribute#name name}. If more |
|
601 |
* than one attribute of the same name is included in the array then all but |
|
602 |
* the last occurrence is ignored. |
|
603 |
* |
|
604 |
* @param dir |
|
605 |
* the directory to create |
|
606 |
* @param attrs |
|
607 |
* an optional list of file attributes to set atomically when |
|
608 |
* creating the directory |
|
609 |
* |
|
610 |
* @return the directory |
|
611 |
* |
|
612 |
* @throws UnsupportedOperationException |
|
613 |
* if the array contains an attribute that cannot be set atomically |
|
614 |
* when creating the directory |
|
615 |
* @throws FileAlreadyExistsException |
|
616 |
* if a directory could not otherwise be created because a file of |
|
617 |
* that name already exists <i>(optional specific exception)</i> |
|
618 |
* @throws IOException |
|
619 |
* if an I/O error occurs or the parent directory does not exist |
|
620 |
* @throws SecurityException |
|
621 |
* In the case of the default provider, and a security manager is |
|
622 |
* installed, the {@link SecurityManager#checkWrite(String) checkWrite} |
|
623 |
* method is invoked to check write access to the new directory. |
|
624 |
*/ |
|
625 |
public static Path createDirectory(Path dir, FileAttribute<?>... attrs) |
|
626 |
throws IOException |
|
627 |
{ |
|
628 |
provider(dir).createDirectory(dir, attrs); |
|
629 |
return dir; |
|
630 |
} |
|
631 |
||
632 |
/** |
|
633 |
* Creates a directory by creating all nonexistent parent directories first. |
|
634 |
* Unlike the {@link #createDirectory createDirectory} method, an exception |
|
635 |
* is not thrown if the directory could not be created because it already |
|
636 |
* exists. |
|
637 |
* |
|
638 |
* <p> The {@code attrs} parameter is optional {@link FileAttribute |
|
639 |
* file-attributes} to set atomically when creating the nonexistent |
|
640 |
* directories. Each file attribute is identified by its {@link |
|
641 |
* FileAttribute#name name}. If more than one attribute of the same name is |
|
642 |
* included in the array then all but the last occurrence is ignored. |
|
643 |
* |
|
644 |
* <p> If this method fails, then it may do so after creating some, but not |
|
645 |
* all, of the parent directories. |
|
646 |
* |
|
647 |
* @param dir |
|
648 |
* the directory to create |
|
649 |
* |
|
650 |
* @param attrs |
|
651 |
* an optional list of file attributes to set atomically when |
|
652 |
* creating the directory |
|
653 |
* |
|
654 |
* @return the directory |
|
655 |
* |
|
656 |
* @throws UnsupportedOperationException |
|
657 |
* if the array contains an attribute that cannot be set atomically |
|
658 |
* when creating the directory |
|
659 |
* @throws FileAlreadyExistsException |
|
660 |
* if {@code dir} exists but is not a directory <i>(optional specific |
|
661 |
* exception)</i> |
|
662 |
* @throws IOException |
|
663 |
* if an I/O error occurs |
|
664 |
* @throws SecurityException |
|
665 |
* in the case of the default provider, and a security manager is |
|
666 |
* installed, the {@link SecurityManager#checkWrite(String) checkWrite} |
|
667 |
* method is invoked prior to attempting to create a directory and |
|
668 |
* its {@link SecurityManager#checkRead(String) checkRead} is |
|
669 |
* invoked for each parent directory that is checked. If {@code |
|
670 |
* dir} is not an absolute path then its {@link Path#toAbsolutePath |
|
671 |
* toAbsolutePath} may need to be invoked to get its absolute path. |
|
672 |
* This may invoke the security manager's {@link |
|
673 |
* SecurityManager#checkPropertyAccess(String) checkPropertyAccess} |
|
674 |
* method to check access to the system property {@code user.dir} |
|
675 |
*/ |
|
676 |
public static Path createDirectories(Path dir, FileAttribute<?>... attrs) |
|
677 |
throws IOException |
|
678 |
{ |
|
679 |
// attempt to create the directory |
|
680 |
try { |
|
681 |
createAndCheckIsDirectory(dir, attrs); |
|
682 |
return dir; |
|
683 |
} catch (FileAlreadyExistsException x) { |
|
684 |
// file exists and is not a directory |
|
685 |
throw x; |
|
686 |
} catch (IOException x) { |
|
687 |
// parent may not exist or other reason |
|
688 |
} |
|
689 |
SecurityException se = null; |
|
690 |
try { |
|
691 |
dir = dir.toAbsolutePath(); |
|
692 |
} catch (SecurityException x) { |
|
693 |
// don't have permission to get absolute path |
|
694 |
se = x; |
|
695 |
} |
|
696 |
// find a decendent that exists |
|
697 |
Path parent = dir.getParent(); |
|
698 |
while (parent != null) { |
|
699 |
try { |
|
700 |
provider(parent).checkAccess(parent); |
|
701 |
break; |
|
702 |
} catch (NoSuchFileException x) { |
|
703 |
// does not exist |
|
704 |
} |
|
705 |
parent = parent.getParent(); |
|
706 |
} |
|
707 |
if (parent == null) { |
|
708 |
// unable to find existing parent |
|
709 |
if (se != null) |
|
710 |
throw se; |
|
711 |
throw new IOException("Root directory does not exist"); |
|
712 |
} |
|
713 |
||
714 |
// create directories |
|
715 |
Path child = parent; |
|
716 |
for (Path name: parent.relativize(dir)) { |
|
717 |
child = child.resolve(name); |
|
718 |
createAndCheckIsDirectory(child, attrs); |
|
719 |
} |
|
720 |
return dir; |
|
721 |
} |
|
722 |
||
723 |
/** |
|
724 |
* Used by createDirectories to attempt to create a directory. A no-op |
|
725 |
* if the directory already exists. |
|
726 |
*/ |
|
727 |
private static void createAndCheckIsDirectory(Path dir, |
|
728 |
FileAttribute<?>... attrs) |
|
729 |
throws IOException |
|
730 |
{ |
|
731 |
try { |
|
732 |
createDirectory(dir, attrs); |
|
733 |
} catch (FileAlreadyExistsException x) { |
|
734 |
if (!isDirectory(dir, LinkOption.NOFOLLOW_LINKS)) |
|
735 |
throw x; |
|
736 |
} |
|
737 |
} |
|
738 |
||
739 |
/** |
|
740 |
* Creates a new empty file in the specified directory, using the given |
|
741 |
* prefix and suffix strings to generate its name. The resulting |
|
742 |
* {@code Path} is associated with the same {@code FileSystem} as the given |
|
743 |
* directory. |
|
744 |
* |
|
745 |
* <p> The details as to how the name of the file is constructed is |
|
746 |
* implementation dependent and therefore not specified. Where possible |
|
747 |
* the {@code prefix} and {@code suffix} are used to construct candidate |
|
748 |
* names in the same manner as the {@link |
|
749 |
* java.io.File#createTempFile(String,String,File)} method. |
|
750 |
* |
|
751 |
* <p> As with the {@code File.createTempFile} methods, this method is only |
|
752 |
* part of a temporary-file facility. Where used as a <em>work files</em>, |
|
753 |
* the resulting file may be opened using the {@link |
|
754 |
* StandardOpenOption#DELETE_ON_CLOSE DELETE_ON_CLOSE} option so that the |
|
755 |
* file is deleted when the appropriate {@code close} method is invoked. |
|
756 |
* Alternatively, a {@link Runtime#addShutdownHook shutdown-hook}, or the |
|
757 |
* {@link java.io.File#deleteOnExit} mechanism may be used to delete the |
|
758 |
* file automatically. |
|
759 |
* |
|
760 |
* <p> The {@code attrs} parameter is optional {@link FileAttribute |
|
761 |
* file-attributes} to set atomically when creating the file. Each attribute |
|
762 |
* is identified by its {@link FileAttribute#name name}. If more than one |
|
763 |
* attribute of the same name is included in the array then all but the last |
|
764 |
* occurrence is ignored. When no file attributes are specified, then the |
|
765 |
* resulting file may have more restrictive access permissions to files |
|
766 |
* created by the {@link java.io.File#createTempFile(String,String,File)} |
|
767 |
* method. |
|
768 |
* |
|
769 |
* @param dir |
|
770 |
* the path to directory in which to create the file |
|
771 |
* @param prefix |
|
772 |
* the prefix string to be used in generating the file's name; |
|
773 |
* may be {@code null} |
|
774 |
* @param suffix |
|
775 |
* the suffix string to be used in generating the file's name; |
|
776 |
* may be {@code null}, in which case "{@code .tmp}" is used |
|
777 |
* @param attrs |
|
778 |
* an optional list of file attributes to set atomically when |
|
779 |
* creating the file |
|
780 |
* |
|
781 |
* @return the path to the newly created file that did not exist before |
|
782 |
* this method was invoked |
|
783 |
* |
|
784 |
* @throws IllegalArgumentException |
|
785 |
* if the prefix or suffix parameters cannot be used to generate |
|
786 |
* a candidate file name |
|
787 |
* @throws UnsupportedOperationException |
|
788 |
* if the array contains an attribute that cannot be set atomically |
|
789 |
* when creating the directory |
|
790 |
* @throws IOException |
|
791 |
* if an I/O error occurs or {@code dir} does not exist |
|
792 |
* @throws SecurityException |
|
793 |
* In the case of the default provider, and a security manager is |
|
794 |
* installed, the {@link SecurityManager#checkWrite(String) checkWrite} |
|
795 |
* method is invoked to check write access to the file. |
|
796 |
*/ |
|
797 |
public static Path createTempFile(Path dir, |
|
798 |
String prefix, |
|
799 |
String suffix, |
|
800 |
FileAttribute<?>... attrs) |
|
801 |
throws IOException |
|
802 |
{ |
|
8558
e51c07113d09
7023034: Files.createTempDirectory((Path)null, "temp") does not throw NPE
alanb
parents:
8539
diff
changeset
|
803 |
return TempFileHelper.createTempFile(Objects.requireNonNull(dir), |
e51c07113d09
7023034: Files.createTempDirectory((Path)null, "temp") does not throw NPE
alanb
parents:
8539
diff
changeset
|
804 |
prefix, suffix, attrs); |
8158 | 805 |
} |
806 |
||
807 |
/** |
|
808 |
* Creates an empty file in the default temporary-file directory, using |
|
809 |
* the given prefix and suffix to generate its name. The resulting {@code |
|
810 |
* Path} is associated with the default {@code FileSystem}. |
|
811 |
* |
|
812 |
* <p> This method works in exactly the manner specified by the |
|
813 |
* {@link #createTempFile(Path,String,String,FileAttribute[])} method for |
|
814 |
* the case that the {@code dir} parameter is the temporary-file directory. |
|
815 |
* |
|
816 |
* @param prefix |
|
817 |
* the prefix string to be used in generating the file's name; |
|
818 |
* may be {@code null} |
|
819 |
* @param suffix |
|
820 |
* the suffix string to be used in generating the file's name; |
|
821 |
* may be {@code null}, in which case "{@code .tmp}" is used |
|
822 |
* @param attrs |
|
823 |
* an optional list of file attributes to set atomically when |
|
824 |
* creating the file |
|
825 |
* |
|
826 |
* @return the path to the newly created file that did not exist before |
|
827 |
* this method was invoked |
|
828 |
* |
|
829 |
* @throws IllegalArgumentException |
|
830 |
* if the prefix or suffix parameters cannot be used to generate |
|
831 |
* a candidate file name |
|
832 |
* @throws UnsupportedOperationException |
|
833 |
* if the array contains an attribute that cannot be set atomically |
|
834 |
* when creating the directory |
|
835 |
* @throws IOException |
|
836 |
* if an I/O error occurs or the temporary-file directory does not |
|
837 |
* exist |
|
838 |
* @throws SecurityException |
|
839 |
* In the case of the default provider, and a security manager is |
|
840 |
* installed, the {@link SecurityManager#checkWrite(String) checkWrite} |
|
841 |
* method is invoked to check write access to the file. |
|
842 |
*/ |
|
843 |
public static Path createTempFile(String prefix, |
|
844 |
String suffix, |
|
845 |
FileAttribute<?>... attrs) |
|
846 |
throws IOException |
|
847 |
{ |
|
848 |
return TempFileHelper.createTempFile(null, prefix, suffix, attrs); |
|
849 |
} |
|
850 |
||
851 |
/** |
|
852 |
* Creates a new directory in the specified directory, using the given |
|
853 |
* prefix to generate its name. The resulting {@code Path} is associated |
|
854 |
* with the same {@code FileSystem} as the given directory. |
|
855 |
* |
|
856 |
* <p> The details as to how the name of the directory is constructed is |
|
857 |
* implementation dependent and therefore not specified. Where possible |
|
858 |
* the {@code prefix} is used to construct candidate names. |
|
859 |
* |
|
860 |
* <p> As with the {@code createTempFile} methods, this method is only |
|
861 |
* part of a temporary-file facility. A {@link Runtime#addShutdownHook |
|
862 |
* shutdown-hook}, or the {@link java.io.File#deleteOnExit} mechanism may be |
|
863 |
* used to delete the directory automatically. |
|
864 |
* |
|
865 |
* <p> The {@code attrs} parameter is optional {@link FileAttribute |
|
866 |
* file-attributes} to set atomically when creating the directory. Each |
|
867 |
* attribute is identified by its {@link FileAttribute#name name}. If more |
|
868 |
* than one attribute of the same name is included in the array then all but |
|
869 |
* the last occurrence is ignored. |
|
870 |
* |
|
871 |
* @param dir |
|
872 |
* the path to directory in which to create the directory |
|
873 |
* @param prefix |
|
874 |
* the prefix string to be used in generating the directory's name; |
|
875 |
* may be {@code null} |
|
876 |
* @param attrs |
|
877 |
* an optional list of file attributes to set atomically when |
|
878 |
* creating the directory |
|
879 |
* |
|
880 |
* @return the path to the newly created directory that did not exist before |
|
881 |
* this method was invoked |
|
882 |
* |
|
883 |
* @throws IllegalArgumentException |
|
884 |
* if the prefix cannot be used to generate a candidate directory name |
|
885 |
* @throws UnsupportedOperationException |
|
886 |
* if the array contains an attribute that cannot be set atomically |
|
887 |
* when creating the directory |
|
888 |
* @throws IOException |
|
889 |
* if an I/O error occurs or {@code dir} does not exist |
|
890 |
* @throws SecurityException |
|
891 |
* In the case of the default provider, and a security manager is |
|
892 |
* installed, the {@link SecurityManager#checkWrite(String) checkWrite} |
|
893 |
* method is invoked to check write access when creating the |
|
894 |
* directory. |
|
895 |
*/ |
|
896 |
public static Path createTempDirectory(Path dir, |
|
897 |
String prefix, |
|
898 |
FileAttribute<?>... attrs) |
|
899 |
throws IOException |
|
900 |
{ |
|
8558
e51c07113d09
7023034: Files.createTempDirectory((Path)null, "temp") does not throw NPE
alanb
parents:
8539
diff
changeset
|
901 |
return TempFileHelper.createTempDirectory(Objects.requireNonNull(dir), |
e51c07113d09
7023034: Files.createTempDirectory((Path)null, "temp") does not throw NPE
alanb
parents:
8539
diff
changeset
|
902 |
prefix, attrs); |
8158 | 903 |
} |
904 |
||
905 |
/** |
|
906 |
* Creates a new directory in the default temporary-file directory, using |
|
8539
eeb9fc5a68c1
7020888: (file) Miscellaneous and trivial clean-ups (typos and opportunities to use suppressed exceptions)
alanb
parents:
8166
diff
changeset
|
907 |
* the given prefix to generate its name. The resulting {@code Path} is |
eeb9fc5a68c1
7020888: (file) Miscellaneous and trivial clean-ups (typos and opportunities to use suppressed exceptions)
alanb
parents:
8166
diff
changeset
|
908 |
* associated with the default {@code FileSystem}. |
8158 | 909 |
* |
910 |
* <p> This method works in exactly the manner specified by {@link |
|
911 |
* #createTempDirectory(Path,String,FileAttribute[])} method for the case |
|
912 |
* that the {@code dir} parameter is the temporary-file directory. |
|
913 |
* |
|
914 |
* @param prefix |
|
915 |
* the prefix string to be used in generating the directory's name; |
|
916 |
* may be {@code null} |
|
917 |
* @param attrs |
|
918 |
* an optional list of file attributes to set atomically when |
|
919 |
* creating the directory |
|
920 |
* |
|
921 |
* @return the path to the newly created directory that did not exist before |
|
922 |
* this method was invoked |
|
923 |
* |
|
924 |
* @throws IllegalArgumentException |
|
925 |
* if the prefix cannot be used to generate a candidate directory name |
|
926 |
* @throws UnsupportedOperationException |
|
927 |
* if the array contains an attribute that cannot be set atomically |
|
928 |
* when creating the directory |
|
929 |
* @throws IOException |
|
930 |
* if an I/O error occurs or the temporary-file directory does not |
|
931 |
* exist |
|
932 |
* @throws SecurityException |
|
933 |
* In the case of the default provider, and a security manager is |
|
934 |
* installed, the {@link SecurityManager#checkWrite(String) checkWrite} |
|
935 |
* method is invoked to check write access when creating the |
|
936 |
* directory. |
|
937 |
*/ |
|
938 |
public static Path createTempDirectory(String prefix, |
|
939 |
FileAttribute<?>... attrs) |
|
940 |
throws IOException |
|
941 |
{ |
|
942 |
return TempFileHelper.createTempDirectory(null, prefix, attrs); |
|
943 |
} |
|
944 |
||
945 |
/** |
|
946 |
* Creates a symbolic link to a target <i>(optional operation)</i>. |
|
947 |
* |
|
948 |
* <p> The {@code target} parameter is the target of the link. It may be an |
|
949 |
* {@link Path#isAbsolute absolute} or relative path and may not exist. When |
|
950 |
* the target is a relative path then file system operations on the resulting |
|
951 |
* link are relative to the path of the link. |
|
952 |
* |
|
953 |
* <p> The {@code attrs} parameter is optional {@link FileAttribute |
|
954 |
* attributes} to set atomically when creating the link. Each attribute is |
|
955 |
* identified by its {@link FileAttribute#name name}. If more than one attribute |
|
956 |
* of the same name is included in the array then all but the last occurrence |
|
957 |
* is ignored. |
|
958 |
* |
|
959 |
* <p> Where symbolic links are supported, but the underlying {@link FileStore} |
|
960 |
* does not support symbolic links, then this may fail with an {@link |
|
961 |
* IOException}. Additionally, some operating systems may require that the |
|
962 |
* Java virtual machine be started with implementation specific privileges to |
|
963 |
* create symbolic links, in which case this method may throw {@code IOException}. |
|
964 |
* |
|
965 |
* @param link |
|
966 |
* the path of the symbolic link to create |
|
967 |
* @param target |
|
968 |
* the target of the symbolic link |
|
969 |
* @param attrs |
|
970 |
* the array of attributes to set atomically when creating the |
|
971 |
* symbolic link |
|
972 |
* |
|
973 |
* @return the path to the symbolic link |
|
974 |
* |
|
975 |
* @throws UnsupportedOperationException |
|
976 |
* if the implementation does not support symbolic links or the |
|
977 |
* array contains an attribute that cannot be set atomically when |
|
978 |
* creating the symbolic link |
|
979 |
* @throws FileAlreadyExistsException |
|
980 |
* if a file with the name already exists <i>(optional specific |
|
981 |
* exception)</i> |
|
982 |
* @throws IOException |
|
983 |
* if an I/O error occurs |
|
984 |
* @throws SecurityException |
|
985 |
* In the case of the default provider, and a security manager |
|
986 |
* is installed, it denies {@link LinkPermission}<tt>("symbolic")</tt> |
|
987 |
* or its {@link SecurityManager#checkWrite(String) checkWrite} |
|
988 |
* method denies write access to the path of the symbolic link. |
|
989 |
*/ |
|
990 |
public static Path createSymbolicLink(Path link, Path target, |
|
991 |
FileAttribute<?>... attrs) |
|
992 |
throws IOException |
|
993 |
{ |
|
994 |
provider(link).createSymbolicLink(link, target, attrs); |
|
995 |
return link; |
|
996 |
} |
|
997 |
||
998 |
/** |
|
999 |
* Creates a new link (directory entry) for an existing file <i>(optional |
|
1000 |
* operation)</i>. |
|
1001 |
* |
|
1002 |
* <p> The {@code link} parameter locates the directory entry to create. |
|
1003 |
* The {@code existing} parameter is the path to an existing file. This |
|
1004 |
* method creates a new directory entry for the file so that it can be |
|
1005 |
* accessed using {@code link} as the path. On some file systems this is |
|
1006 |
* known as creating a "hard link". Whether the file attributes are |
|
1007 |
* maintained for the file or for each directory entry is file system |
|
1008 |
* specific and therefore not specified. Typically, a file system requires |
|
1009 |
* that all links (directory entries) for a file be on the same file system. |
|
1010 |
* Furthermore, on some platforms, the Java virtual machine may require to |
|
1011 |
* be started with implementation specific privileges to create hard links |
|
1012 |
* or to create links to directories. |
|
1013 |
* |
|
1014 |
* @param link |
|
1015 |
* the link (directory entry) to create |
|
1016 |
* @param existing |
|
1017 |
* a path to an existing file |
|
1018 |
* |
|
1019 |
* @return the path to the link (directory entry) |
|
1020 |
* |
|
1021 |
* @throws UnsupportedOperationException |
|
1022 |
* if the implementation does not support adding an existing file |
|
1023 |
* to a directory |
|
1024 |
* @throws FileAlreadyExistsException |
|
1025 |
* if the entry could not otherwise be created because a file of |
|
1026 |
* that name already exists <i>(optional specific exception)</i> |
|
1027 |
* @throws IOException |
|
1028 |
* if an I/O error occurs |
|
1029 |
* @throws SecurityException |
|
1030 |
* In the case of the default provider, and a security manager |
|
1031 |
* is installed, it denies {@link LinkPermission}<tt>("hard")</tt> |
|
1032 |
* or its {@link SecurityManager#checkWrite(String) checkWrite} |
|
1033 |
* method denies write access to either the link or the |
|
1034 |
* existing file. |
|
1035 |
*/ |
|
1036 |
public static Path createLink(Path link, Path existing) throws IOException { |
|
1037 |
provider(link).createLink(link, existing); |
|
1038 |
return link; |
|
1039 |
} |
|
1040 |
||
1041 |
/** |
|
1042 |
* Deletes a file. |
|
1043 |
* |
|
1044 |
* <p> An implementation may require to examine the file to determine if the |
|
1045 |
* file is a directory. Consequently this method may not be atomic with respect |
|
1046 |
* to other file system operations. If the file is a symbolic link then the |
|
1047 |
* symbolic link itself, not the final target of the link, is deleted. |
|
1048 |
* |
|
1049 |
* <p> If the file is a directory then the directory must be empty. In some |
|
1050 |
* implementations a directory has entries for special files or links that |
|
1051 |
* are created when the directory is created. In such implementations a |
|
1052 |
* directory is considered empty when only the special entries exist. |
|
1053 |
* This method can be used with the {@link #walkFileTree walkFileTree} |
|
1054 |
* method to delete a directory and all entries in the directory, or an |
|
1055 |
* entire <i>file-tree</i> where required. |
|
1056 |
* |
|
1057 |
* <p> On some operating systems it may not be possible to remove a file when |
|
1058 |
* it is open and in use by this Java virtual machine or other programs. |
|
1059 |
* |
|
1060 |
* @param path |
|
1061 |
* the path to the file to delete |
|
1062 |
* |
|
1063 |
* @throws NoSuchFileException |
|
1064 |
* if the file does not exist <i>(optional specific exception)</i> |
|
1065 |
* @throws DirectoryNotEmptyException |
|
1066 |
* if the file is a directory and could not otherwise be deleted |
|
1067 |
* because the directory is not empty <i>(optional specific |
|
1068 |
* exception)</i> |
|
1069 |
* @throws IOException |
|
1070 |
* if an I/O error occurs |
|
1071 |
* @throws SecurityException |
|
1072 |
* In the case of the default provider, and a security manager is |
|
1073 |
* installed, the {@link SecurityManager#checkDelete(String)} method |
|
1074 |
* is invoked to check delete access to the file |
|
1075 |
*/ |
|
1076 |
public static void delete(Path path) throws IOException { |
|
1077 |
provider(path).delete(path); |
|
1078 |
} |
|
1079 |
||
1080 |
/** |
|
1081 |
* Deletes a file if it exists. |
|
1082 |
* |
|
1083 |
* <p> As with the {@link #delete(Path) delete(Path)} method, an |
|
1084 |
* implementation may need to examine the file to determine if the file is a |
|
1085 |
* directory. Consequently this method may not be atomic with respect to |
|
1086 |
* other file system operations. If the file is a symbolic link, then the |
|
1087 |
* symbolic link itself, not the final target of the link, is deleted. |
|
1088 |
* |
|
1089 |
* <p> If the file is a directory then the directory must be empty. In some |
|
1090 |
* implementations a directory has entries for special files or links that |
|
1091 |
* are created when the directory is created. In such implementations a |
|
1092 |
* directory is considered empty when only the special entries exist. |
|
1093 |
* |
|
1094 |
* <p> On some operating systems it may not be possible to remove a file when |
|
1095 |
* it is open and in use by this Java virtual machine or other programs. |
|
1096 |
* |
|
1097 |
* @param path |
|
1098 |
* the path to the file to delete |
|
1099 |
* |
|
1100 |
* @return {@code true} if the file was deleted by this method; {@code |
|
1101 |
* false} if the file could not be deleted because it did not |
|
1102 |
* exist |
|
1103 |
* |
|
1104 |
* @throws DirectoryNotEmptyException |
|
1105 |
* if the file is a directory and could not otherwise be deleted |
|
1106 |
* because the directory is not empty <i>(optional specific |
|
1107 |
* exception)</i> |
|
1108 |
* @throws IOException |
|
1109 |
* if an I/O error occurs |
|
1110 |
* @throws SecurityException |
|
1111 |
* In the case of the default provider, and a security manager is |
|
1112 |
* installed, the {@link SecurityManager#checkDelete(String)} method |
|
1113 |
* is invoked to check delete access to the file. |
|
1114 |
*/ |
|
1115 |
public static boolean deleteIfExists(Path path) throws IOException { |
|
1116 |
return provider(path).deleteIfExists(path); |
|
1117 |
} |
|
1118 |
||
1119 |
// -- Copying and moving files -- |
|
1120 |
||
1121 |
/** |
|
1122 |
* Copy a file to a target file. |
|
1123 |
* |
|
1124 |
* <p> This method copies a file to the target file with the {@code |
|
1125 |
* options} parameter specifying how the copy is performed. By default, the |
|
1126 |
* copy fails if the target file already exists or is a symbolic link, |
|
1127 |
* except if the source and target are the {@link #isSameFile same} file, in |
|
1128 |
* which case the method completes without copying the file. File attributes |
|
1129 |
* are not required to be copied to the target file. If symbolic links are |
|
1130 |
* supported, and the file is a symbolic link, then the final target of the |
|
1131 |
* link is copied. If the file is a directory then it creates an empty |
|
1132 |
* directory in the target location (entries in the directory are not |
|
1133 |
* copied). This method can be used with the {@link #walkFileTree |
|
1134 |
* walkFileTree} method to copy a directory and all entries in the directory, |
|
1135 |
* or an entire <i>file-tree</i> where required. |
|
1136 |
* |
|
1137 |
* <p> The {@code options} parameter may include any of the following: |
|
1138 |
* |
|
1139 |
* <table border=1 cellpadding=5 summary=""> |
|
1140 |
* <tr> <th>Option</th> <th>Description</th> </tr> |
|
1141 |
* <tr> |
|
1142 |
* <td> {@link StandardCopyOption#REPLACE_EXISTING REPLACE_EXISTING} </td> |
|
1143 |
* <td> If the target file exists, then the target file is replaced if it |
|
1144 |
* is not a non-empty directory. If the target file exists and is a |
|
1145 |
* symbolic link, then the symbolic link itself, not the target of |
|
1146 |
* the link, is replaced. </td> |
|
1147 |
* </tr> |
|
1148 |
* <tr> |
|
1149 |
* <td> {@link StandardCopyOption#COPY_ATTRIBUTES COPY_ATTRIBUTES} </td> |
|
1150 |
* <td> Attempts to copy the file attributes associated with this file to |
|
1151 |
* the target file. The exact file attributes that are copied is platform |
|
1152 |
* and file system dependent and therefore unspecified. Minimally, the |
|
1153 |
* {@link BasicFileAttributes#lastModifiedTime last-modified-time} is |
|
1154 |
* copied to the target file if supported by both the source and target |
|
1155 |
* file store. Copying of file timestamps may result in precision |
|
1156 |
* loss. </td> |
|
1157 |
* </tr> |
|
1158 |
* <tr> |
|
1159 |
* <td> {@link LinkOption#NOFOLLOW_LINKS NOFOLLOW_LINKS} </td> |
|
1160 |
* <td> Symbolic links are not followed. If the file is a symbolic link, |
|
1161 |
* then the symbolic link itself, not the target of the link, is copied. |
|
1162 |
* It is implementation specific if file attributes can be copied to the |
|
1163 |
* new link. In other words, the {@code COPY_ATTRIBUTES} option may be |
|
1164 |
* ignored when copying a symbolic link. </td> |
|
1165 |
* </tr> |
|
1166 |
* </table> |
|
1167 |
* |
|
1168 |
* <p> An implementation of this interface may support additional |
|
1169 |
* implementation specific options. |
|
1170 |
* |
|
1171 |
* <p> Copying a file is not an atomic operation. If an {@link IOException} |
|
1172 |
* is thrown then it possible that the target file is incomplete or some of |
|
1173 |
* its file attributes have not been copied from the source file. When the |
|
1174 |
* {@code REPLACE_EXISTING} option is specified and the target file exists, |
|
1175 |
* then the target file is replaced. The check for the existence of the file |
|
1176 |
* and the creation of the new file may not be atomic with respect to other |
|
1177 |
* file system activities. |
|
1178 |
* |
|
1179 |
* <p> <b>Usage Example:</b> |
|
1180 |
* Suppose we want to copy a file into a directory, giving it the same file |
|
1181 |
* name as the source file: |
|
1182 |
* <pre> |
|
1183 |
* Path source = ... |
|
1184 |
* Path newdir = ... |
|
1185 |
* Files.copy(source, newdir.resolve(source.getFileName()); |
|
1186 |
* </pre> |
|
1187 |
* |
|
1188 |
* @param source |
|
1189 |
* the path to the file to copy |
|
1190 |
* @param target |
|
1191 |
* the path to the target file (may be associated with a different |
|
1192 |
* provider to the source path) |
|
1193 |
* @param options |
|
1194 |
* options specifying how the copy should be done |
|
1195 |
* |
|
1196 |
* @return the path to the target file |
|
1197 |
* |
|
1198 |
* @throws UnsupportedOperationException |
|
1199 |
* if the array contains a copy option that is not supported |
|
1200 |
* @throws FileAlreadyExistsException |
|
1201 |
* if the target file exists but cannot be replaced because the |
|
1202 |
* {@code REPLACE_EXISTING} option is not specified <i>(optional |
|
1203 |
* specific exception)</i> |
|
1204 |
* @throws DirectoryNotEmptyException |
|
1205 |
* the {@code REPLACE_EXISTING} option is specified but the file |
|
1206 |
* cannot be replaced because it is a non-empty directory |
|
1207 |
* <i>(optional specific exception)</i> |
|
1208 |
* @throws IOException |
|
1209 |
* if an I/O error occurs |
|
1210 |
* @throws SecurityException |
|
1211 |
* In the case of the default provider, and a security manager is |
|
1212 |
* installed, the {@link SecurityManager#checkRead(String) checkRead} |
|
1213 |
* method is invoked to check read access to the source file, the |
|
1214 |
* {@link SecurityManager#checkWrite(String) checkWrite} is invoked |
|
1215 |
* to check write access to the target file. If a symbolic link is |
|
1216 |
* copied the security manager is invoked to check {@link |
|
1217 |
* LinkPermission}{@code ("symbolic")}. |
|
1218 |
*/ |
|
1219 |
public static Path copy(Path source, Path target, CopyOption... options) |
|
1220 |
throws IOException |
|
1221 |
{ |
|
1222 |
FileSystemProvider provider = provider(source); |
|
1223 |
if (provider(target) == provider) { |
|
1224 |
// same provider |
|
1225 |
provider.copy(source, target, options); |
|
1226 |
} else { |
|
1227 |
// different providers |
|
1228 |
CopyMoveHelper.copyToForeignTarget(source, target, options); |
|
1229 |
} |
|
1230 |
return target; |
|
1231 |
} |
|
1232 |
||
1233 |
/** |
|
1234 |
* Move or rename a file to a target file. |
|
1235 |
* |
|
1236 |
* <p> By default, this method attempts to move the file to the target |
|
1237 |
* file, failing if the target file exists except if the source and |
|
1238 |
* target are the {@link #isSameFile same} file, in which case this method |
|
1239 |
* has no effect. If the file is a symbolic link then the symbolic link |
|
1240 |
* itself, not the target of the link, is moved. This method may be |
|
1241 |
* invoked to move an empty directory. In some implementations a directory |
|
1242 |
* has entries for special files or links that are created when the |
|
1243 |
* directory is created. In such implementations a directory is considered |
|
1244 |
* empty when only the special entries exist. When invoked to move a |
|
1245 |
* directory that is not empty then the directory is moved if it does not |
|
1246 |
* require moving the entries in the directory. For example, renaming a |
|
1247 |
* directory on the same {@link FileStore} will usually not require moving |
|
1248 |
* the entries in the directory. When moving a directory requires that its |
|
1249 |
* entries be moved then this method fails (by throwing an {@code |
|
1250 |
* IOException}). To move a <i>file tree</i> may involve copying rather |
|
1251 |
* than moving directories and this can be done using the {@link |
|
1252 |
* #copy copy} method in conjunction with the {@link |
|
1253 |
* #walkFileTree Files.walkFileTree} utility method. |
|
1254 |
* |
|
1255 |
* <p> The {@code options} parameter may include any of the following: |
|
1256 |
* |
|
1257 |
* <table border=1 cellpadding=5 summary=""> |
|
1258 |
* <tr> <th>Option</th> <th>Description</th> </tr> |
|
1259 |
* <tr> |
|
1260 |
* <td> {@link StandardCopyOption#REPLACE_EXISTING REPLACE_EXISTING} </td> |
|
1261 |
* <td> If the target file exists, then the target file is replaced if it |
|
1262 |
* is not a non-empty directory. If the target file exists and is a |
|
1263 |
* symbolic link, then the symbolic link itself, not the target of |
|
1264 |
* the link, is replaced. </td> |
|
1265 |
* </tr> |
|
1266 |
* <tr> |
|
1267 |
* <td> {@link StandardCopyOption#ATOMIC_MOVE ATOMIC_MOVE} </td> |
|
1268 |
* <td> The move is performed as an atomic file system operation and all |
|
1269 |
* other options are ignored. If the target file exists then it is |
|
1270 |
* implementation specific if the existing file is replaced or this method |
|
1271 |
* fails by throwing an {@link IOException}. If the move cannot be |
|
1272 |
* performed as an atomic file system operation then {@link |
|
1273 |
* AtomicMoveNotSupportedException} is thrown. This can arise, for |
|
1274 |
* example, when the target location is on a different {@code FileStore} |
|
1275 |
* and would require that the file be copied, or target location is |
|
1276 |
* associated with a different provider to this object. </td> |
|
1277 |
* </table> |
|
1278 |
* |
|
1279 |
* <p> An implementation of this interface may support additional |
|
1280 |
* implementation specific options. |
|
1281 |
* |
|
1282 |
* <p> Where the move requires that the file be copied then the {@link |
|
1283 |
* BasicFileAttributes#lastModifiedTime last-modified-time} is copied to the |
|
1284 |
* new file. An implementation may also attempt to copy other file |
|
1285 |
* attributes but is not required to fail if the file attributes cannot be |
|
1286 |
* copied. When the move is performed as a non-atomic operation, and a {@code |
|
1287 |
* IOException} is thrown, then the state of the files is not defined. The |
|
1288 |
* original file and the target file may both exist, the target file may be |
|
1289 |
* incomplete or some of its file attributes may not been copied from the |
|
1290 |
* original file. |
|
1291 |
* |
|
1292 |
* <p> <b>Usage Examples:</b> |
|
1293 |
* Suppose we want to rename a file to "newname", keeping the file in the |
|
1294 |
* same directory: |
|
1295 |
* <pre> |
|
1296 |
* Path source = ... |
|
1297 |
* Files.move(source, source.resolveSibling("newname")); |
|
1298 |
* </pre> |
|
1299 |
* Alternatively, suppose we want to move a file to new directory, keeping |
|
1300 |
* the same file name, and replacing any existing file of that name in the |
|
1301 |
* directory: |
|
1302 |
* <pre> |
|
1303 |
* Path source = ... |
|
1304 |
* Path newdir = ... |
|
1305 |
* Files.move(source, newdir.resolve(source.getFileName()), REPLACE_EXISTING); |
|
1306 |
* </pre> |
|
1307 |
* |
|
1308 |
* @param source |
|
1309 |
* the path to the file to move |
|
1310 |
* @param target |
|
1311 |
* the path to the target file (may be associated with a different |
|
1312 |
* provider to the source path) |
|
1313 |
* @param options |
|
1314 |
* options specifying how the move should be done |
|
1315 |
* |
|
1316 |
* @return the path to the target file |
|
1317 |
* |
|
1318 |
* @throws UnsupportedOperationException |
|
1319 |
* if the array contains a copy option that is not supported |
|
1320 |
* @throws FileAlreadyExistsException |
|
1321 |
* if the target file exists but cannot be replaced because the |
|
1322 |
* {@code REPLACE_EXISTING} option is not specified <i>(optional |
|
1323 |
* specific exception)</i> |
|
1324 |
* @throws DirectoryNotEmptyException |
|
1325 |
* the {@code REPLACE_EXISTING} option is specified but the file |
|
1326 |
* cannot be replaced because it is a non-empty directory |
|
1327 |
* <i>(optional specific exception)</i> |
|
1328 |
* @throws AtomicMoveNotSupportedException |
|
1329 |
* if the options array contains the {@code ATOMIC_MOVE} option but |
|
1330 |
* the file cannot be moved as an atomic file system operation. |
|
1331 |
* @throws IOException |
|
1332 |
* if an I/O error occurs |
|
1333 |
* @throws SecurityException |
|
1334 |
* In the case of the default provider, and a security manager is |
|
1335 |
* installed, the {@link SecurityManager#checkWrite(String) checkWrite} |
|
1336 |
* method is invoked to check write access to both the source and |
|
1337 |
* target file. |
|
1338 |
*/ |
|
1339 |
public static Path move(Path source, Path target, CopyOption... options) |
|
1340 |
throws IOException |
|
1341 |
{ |
|
1342 |
FileSystemProvider provider = provider(source); |
|
1343 |
if (provider(target) == provider) { |
|
1344 |
// same provider |
|
1345 |
provider.move(source, target, options); |
|
1346 |
} else { |
|
1347 |
// different providers |
|
1348 |
CopyMoveHelper.moveToForeignTarget(source, target, options); |
|
1349 |
} |
|
1350 |
return target; |
|
1351 |
} |
|
1352 |
||
1353 |
// -- Miscellenous -- |
|
1354 |
||
1355 |
/** |
|
1356 |
* Reads the target of a symbolic link <i>(optional operation)</i>. |
|
1357 |
* |
|
1358 |
* <p> If the file system supports <a href="package-summary.html#links">symbolic |
|
1359 |
* links</a> then this method is used to read the target of the link, failing |
|
1360 |
* if the file is not a symbolic link. The target of the link need not exist. |
|
1361 |
* The returned {@code Path} object will be associated with the same file |
|
1362 |
* system as {@code link}. |
|
1363 |
* |
|
1364 |
* @param link |
|
1365 |
* the path to the symbolic link |
|
1366 |
* |
|
1367 |
* @return a {@code Path} object representing the target of the link |
|
1368 |
* |
|
1369 |
* @throws UnsupportedOperationException |
|
1370 |
* if the implementation does not support symbolic links |
|
1371 |
* @throws NotLinkException |
|
1372 |
* if the target could otherwise not be read because the file |
|
1373 |
* is not a symbolic link <i>(optional specific exception)</i> |
|
1374 |
* @throws IOException |
|
1375 |
* if an I/O error occurs |
|
1376 |
* @throws SecurityException |
|
1377 |
* In the case of the default provider, and a security manager |
|
1378 |
* is installed, it checks that {@code FilePermission} has been |
|
1379 |
* granted with the "{@code readlink}" action to read the link. |
|
1380 |
*/ |
|
1381 |
public static Path readSymbolicLink(Path link) throws IOException { |
|
1382 |
return provider(link).readSymbolicLink(link); |
|
1383 |
} |
|
1384 |
||
1385 |
/** |
|
1386 |
* Returns the {@link FileStore} representing the file store where a file |
|
1387 |
* is located. |
|
1388 |
* |
|
1389 |
* <p> Once a reference to the {@code FileStore} is obtained it is |
|
1390 |
* implementation specific if operations on the returned {@code FileStore}, |
|
1391 |
* or {@link FileStoreAttributeView} objects obtained from it, continue |
|
1392 |
* to depend on the existence of the file. In particular the behavior is not |
|
1393 |
* defined for the case that the file is deleted or moved to a different |
|
1394 |
* file store. |
|
1395 |
* |
|
1396 |
* @param path |
|
1397 |
* the path to the file |
|
1398 |
* |
|
1399 |
* @return the file store where the file is stored |
|
1400 |
* |
|
1401 |
* @throws IOException |
|
1402 |
* if an I/O error occurs |
|
1403 |
* @throws SecurityException |
|
1404 |
* In the case of the default provider, and a security manager is |
|
1405 |
* installed, the {@link SecurityManager#checkRead(String) checkRead} |
|
1406 |
* method is invoked to check read access to the file, and in |
|
1407 |
* addition it checks {@link RuntimePermission}<tt> |
|
1408 |
* ("getFileStoreAttributes")</tt> |
|
1409 |
*/ |
|
1410 |
public static FileStore getFileStore(Path path) throws IOException { |
|
1411 |
return provider(path).getFileStore(path); |
|
1412 |
} |
|
1413 |
||
1414 |
/** |
|
1415 |
* Tests if two paths locate the same file. |
|
1416 |
* |
|
1417 |
* <p> If both {@code Path} objects are {@link Path#equals(Object) equal} |
|
1418 |
* then this method returns {@code true} without checking if the file exists. |
|
1419 |
* If the two {@code Path} objects are associated with different providers |
|
1420 |
* then this method returns {@code false}. Otherwise, this method checks if |
|
1421 |
* both {@code Path} objects locate the same file, and depending on the |
|
1422 |
* implementation, may require to open or access both files. |
|
1423 |
* |
|
1424 |
* <p> If the file system and files remain static, then this method implements |
|
1425 |
* an equivalence relation for non-null {@code Paths}. |
|
1426 |
* <ul> |
|
1427 |
* <li>It is <i>reflexive</i>: for {@code Path} {@code f}, |
|
1428 |
* {@code isSameFile(f,f)} should return {@code true}. |
|
1429 |
* <li>It is <i>symmetric</i>: for two {@code Paths} {@code f} and {@code g}, |
|
1430 |
* {@code isSameFile(f,g)} will equal {@code isSameFile(g,f)}. |
|
1431 |
* <li>It is <i>transitive</i>: for three {@code Paths} |
|
1432 |
* {@code f}, {@code g}, and {@code h}, if {@code isSameFile(f,g)} returns |
|
1433 |
* {@code true} and {@code isSameFile(g,h)} returns {@code true}, then |
|
11519 | 1434 |
* {@code isSameFile(f,h)} will return return {@code true}. |
8158 | 1435 |
* </ul> |
1436 |
* |
|
1437 |
* @param path |
|
1438 |
* one path to the file |
|
1439 |
* @param path2 |
|
1440 |
* the other path |
|
1441 |
* |
|
1442 |
* @return {@code true} if, and only if, the two paths locate the same file |
|
1443 |
* |
|
1444 |
* @throws IOException |
|
1445 |
* if an I/O error occurs |
|
1446 |
* @throws SecurityException |
|
1447 |
* In the case of the default provider, and a security manager is |
|
1448 |
* installed, the {@link SecurityManager#checkRead(String) checkRead} |
|
1449 |
* method is invoked to check read access to both files. |
|
1450 |
* |
|
1451 |
* @see java.nio.file.attribute.BasicFileAttributes#fileKey |
|
1452 |
*/ |
|
1453 |
public static boolean isSameFile(Path path, Path path2) throws IOException { |
|
1454 |
return provider(path).isSameFile(path, path2); |
|
1455 |
} |
|
1456 |
||
1457 |
/** |
|
1458 |
* Tells whether or not a file is considered <em>hidden</em>. The exact |
|
1459 |
* definition of hidden is platform or provider dependent. On UNIX for |
|
1460 |
* example a file is considered to be hidden if its name begins with a |
|
1461 |
* period character ('.'). On Windows a file is considered hidden if it |
|
1462 |
* isn't a directory and the DOS {@link DosFileAttributes#isHidden hidden} |
|
1463 |
* attribute is set. |
|
1464 |
* |
|
1465 |
* <p> Depending on the implementation this method may require to access |
|
1466 |
* the file system to determine if the file is considered hidden. |
|
1467 |
* |
|
1468 |
* @param path |
|
1469 |
* the path to the file to test |
|
1470 |
* |
|
1471 |
* @return {@code true} if the file is considered hidden |
|
1472 |
* |
|
1473 |
* @throws IOException |
|
1474 |
* if an I/O error occurs |
|
1475 |
* @throws SecurityException |
|
1476 |
* In the case of the default provider, and a security manager is |
|
1477 |
* installed, the {@link SecurityManager#checkRead(String) checkRead} |
|
1478 |
* method is invoked to check read access to the file. |
|
1479 |
*/ |
|
1480 |
public static boolean isHidden(Path path) throws IOException { |
|
1481 |
return provider(path).isHidden(path); |
|
1482 |
} |
|
1483 |
||
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1484 |
// lazy loading of default and installed file type detectors |
8158 | 1485 |
private static class FileTypeDetectors{ |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1486 |
static final FileTypeDetector defaultFileTypeDetector = |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1487 |
sun.nio.fs.DefaultFileTypeDetector.create(); |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1488 |
static final List<FileTypeDetector> installeDetectors = |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1489 |
loadInstalledDetectors(); |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1490 |
|
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1491 |
// loads all installed file type detectors |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1492 |
private static List<FileTypeDetector> loadInstalledDetectors() { |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1493 |
return AccessController |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1494 |
.doPrivileged(new PrivilegedAction<List<FileTypeDetector>>() { |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1495 |
@Override public List<FileTypeDetector> run() { |
8158 | 1496 |
List<FileTypeDetector> list = new ArrayList<>(); |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1497 |
ServiceLoader<FileTypeDetector> loader = ServiceLoader |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1498 |
.load(FileTypeDetector.class, ClassLoader.getSystemClassLoader()); |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1499 |
for (FileTypeDetector detector: loader) { |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1500 |
list.add(detector); |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1501 |
} |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1502 |
return list; |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1503 |
}}); |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1504 |
} |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1505 |
} |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1506 |
|
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1507 |
/** |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1508 |
* Probes the content type of a file. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1509 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1510 |
* <p> This method uses the installed {@link FileTypeDetector} implementations |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1511 |
* to probe the given file to determine its content type. Each file type |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1512 |
* detector's {@link FileTypeDetector#probeContentType probeContentType} is |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1513 |
* invoked, in turn, to probe the file type. If the file is recognized then |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1514 |
* the content type is returned. If the file is not recognized by any of the |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1515 |
* installed file type detectors then a system-default file type detector is |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1516 |
* invoked to guess the content type. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1517 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1518 |
* <p> A given invocation of the Java virtual machine maintains a system-wide |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1519 |
* list of file type detectors. Installed file type detectors are loaded |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1520 |
* using the service-provider loading facility defined by the {@link ServiceLoader} |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1521 |
* class. Installed file type detectors are loaded using the system class |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1522 |
* loader. If the system class loader cannot be found then the extension class |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1523 |
* loader is used; If the extension class loader cannot be found then the |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1524 |
* bootstrap class loader is used. File type detectors are typically installed |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1525 |
* by placing them in a JAR file on the application class path or in the |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1526 |
* extension directory, the JAR file contains a provider-configuration file |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1527 |
* named {@code java.nio.file.spi.FileTypeDetector} in the resource directory |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1528 |
* {@code META-INF/services}, and the file lists one or more fully-qualified |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1529 |
* names of concrete subclass of {@code FileTypeDetector } that have a zero |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1530 |
* argument constructor. If the process of locating or instantiating the |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1531 |
* installed file type detectors fails then an unspecified error is thrown. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1532 |
* The ordering that installed providers are located is implementation |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1533 |
* specific. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1534 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1535 |
* <p> The return value of this method is the string form of the value of a |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1536 |
* Multipurpose Internet Mail Extension (MIME) content type as |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1537 |
* defined by <a href="http://www.ietf.org/rfc/rfc2045.txt"><i>RFC 2045: |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1538 |
* Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1539 |
* Message Bodies</i></a>. The string is guaranteed to be parsable according |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1540 |
* to the grammar in the RFC. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1541 |
* |
8158 | 1542 |
* @param path |
1543 |
* the path to the file to probe |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1544 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1545 |
* @return The content type of the file, or {@code null} if the content |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1546 |
* type cannot be determined |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1547 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1548 |
* @throws IOException |
8158 | 1549 |
* if an I/O error occurs |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1550 |
* @throws SecurityException |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1551 |
* If a security manager is installed and it denies an unspecified |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1552 |
* permission required by a file type detector implementation. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1553 |
*/ |
8158 | 1554 |
public static String probeContentType(Path path) |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1555 |
throws IOException |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1556 |
{ |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1557 |
// try installed file type detectors |
8158 | 1558 |
for (FileTypeDetector detector: FileTypeDetectors.installeDetectors) { |
1559 |
String result = detector.probeContentType(path); |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1560 |
if (result != null) |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1561 |
return result; |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1562 |
} |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1563 |
|
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
1564 |
// fallback to default |
8158 | 1565 |
return FileTypeDetectors.defaultFileTypeDetector.probeContentType(path); |
1566 |
} |
|
1567 |
||
1568 |
// -- File Attributes -- |
|
1569 |
||
1570 |
/** |
|
1571 |
* Returns a file attribute view of a given type. |
|
1572 |
* |
|
1573 |
* <p> A file attribute view provides a read-only or updatable view of a |
|
1574 |
* set of file attributes. This method is intended to be used where the file |
|
1575 |
* attribute view defines type-safe methods to read or update the file |
|
1576 |
* attributes. The {@code type} parameter is the type of the attribute view |
|
1577 |
* required and the method returns an instance of that type if supported. |
|
1578 |
* The {@link BasicFileAttributeView} type supports access to the basic |
|
1579 |
* attributes of a file. Invoking this method to select a file attribute |
|
1580 |
* view of that type will always return an instance of that class. |
|
1581 |
* |
|
1582 |
* <p> The {@code options} array may be used to indicate how symbolic links |
|
1583 |
* are handled by the resulting file attribute view for the case that the |
|
1584 |
* file is a symbolic link. By default, symbolic links are followed. If the |
|
1585 |
* option {@link LinkOption#NOFOLLOW_LINKS NOFOLLOW_LINKS} is present then |
|
1586 |
* symbolic links are not followed. This option is ignored by implementations |
|
1587 |
* that do not support symbolic links. |
|
1588 |
* |
|
1589 |
* <p> <b>Usage Example:</b> |
|
1590 |
* Suppose we want read or set a file's ACL, if supported: |
|
1591 |
* <pre> |
|
1592 |
* Path path = ... |
|
1593 |
* AclFileAttributeView view = Files.getFileAttributeView(path, AclFileAttributeView.class); |
|
1594 |
* if (view != null) { |
|
14014 | 1595 |
* List<AclEntry> acl = view.getAcl(); |
8158 | 1596 |
* : |
1597 |
* } |
|
1598 |
* </pre> |
|
1599 |
* |
|
1600 |
* |
|
1601 |
* @param path |
|
1602 |
* the path to the file |
|
1603 |
* @param type |
|
1604 |
* the {@code Class} object corresponding to the file attribute view |
|
1605 |
* @param options |
|
1606 |
* options indicating how symbolic links are handled |
|
1607 |
* |
|
1608 |
* @return a file attribute view of the specified type, or {@code null} if |
|
1609 |
* the attribute view type is not available |
|
1610 |
*/ |
|
1611 |
public static <V extends FileAttributeView> V getFileAttributeView(Path path, |
|
1612 |
Class<V> type, |
|
1613 |
LinkOption... options) |
|
1614 |
{ |
|
1615 |
return provider(path).getFileAttributeView(path, type, options); |
|
1616 |
} |
|
1617 |
||
1618 |
/** |
|
1619 |
* Reads a file's attributes as a bulk operation. |
|
1620 |
* |
|
1621 |
* <p> The {@code type} parameter is the type of the attributes required |
|
1622 |
* and this method returns an instance of that type if supported. All |
|
1623 |
* implementations support a basic set of file attributes and so invoking |
|
1624 |
* this method with a {@code type} parameter of {@code |
|
1625 |
* BasicFileAttributes.class} will not throw {@code |
|
1626 |
* UnsupportedOperationException}. |
|
1627 |
* |
|
1628 |
* <p> The {@code options} array may be used to indicate how symbolic links |
|
1629 |
* are handled for the case that the file is a symbolic link. By default, |
|
1630 |
* symbolic links are followed and the file attribute of the final target |
|
1631 |
* of the link is read. If the option {@link LinkOption#NOFOLLOW_LINKS |
|
1632 |
* NOFOLLOW_LINKS} is present then symbolic links are not followed. |
|
1633 |
* |
|
1634 |
* <p> It is implementation specific if all file attributes are read as an |
|
1635 |
* atomic operation with respect to other file system operations. |
|
1636 |
* |
|
1637 |
* <p> <b>Usage Example:</b> |
|
1638 |
* Suppose we want to read a file's attributes in bulk: |
|
1639 |
* <pre> |
|
1640 |
* Path path = ... |
|
1641 |
* BasicFileAttributes attrs = Files.readAttributes(path, BasicFileAttributes.class); |
|
1642 |
* </pre> |
|
1643 |
* Alternatively, suppose we want to read file's POSIX attributes without |
|
1644 |
* following symbolic links: |
|
1645 |
* <pre> |
|
1646 |
* PosixFileAttributes attrs = Files.readAttributes(path, PosixFileAttributes.class, NOFOLLOW_LINKS); |
|
1647 |
* </pre> |
|
1648 |
* |
|
1649 |
* @param path |
|
1650 |
* the path to the file |
|
1651 |
* @param type |
|
1652 |
* the {@code Class} of the file attributes required |
|
1653 |
* to read |
|
1654 |
* @param options |
|
1655 |
* options indicating how symbolic links are handled |
|
1656 |
* |
|
1657 |
* @return the file attributes |
|
1658 |
* |
|
1659 |
* @throws UnsupportedOperationException |
|
1660 |
* if an attributes of the given type are not supported |
|
1661 |
* @throws IOException |
|
1662 |
* if an I/O error occurs |
|
1663 |
* @throws SecurityException |
|
1664 |
* In the case of the default provider, a security manager is |
|
1665 |
* installed, its {@link SecurityManager#checkRead(String) checkRead} |
|
1666 |
* method is invoked to check read access to the file. If this |
|
1667 |
* method is invoked to read security sensitive attributes then the |
|
1668 |
* security manager may be invoke to check for additional permissions. |
|
1669 |
*/ |
|
1670 |
public static <A extends BasicFileAttributes> A readAttributes(Path path, |
|
1671 |
Class<A> type, |
|
1672 |
LinkOption... options) |
|
1673 |
throws IOException |
|
1674 |
{ |
|
1675 |
return provider(path).readAttributes(path, type, options); |
|
1676 |
} |
|
1677 |
||
1678 |
/** |
|
1679 |
* Sets the value of a file attribute. |
|
1680 |
* |
|
1681 |
* <p> The {@code attribute} parameter identifies the attribute to be set |
|
1682 |
* and takes the form: |
|
1683 |
* <blockquote> |
|
1684 |
* [<i>view-name</i><b>:</b>]<i>attribute-name</i> |
|
1685 |
* </blockquote> |
|
1686 |
* where square brackets [...] delineate an optional component and the |
|
1687 |
* character {@code ':'} stands for itself. |
|
1688 |
* |
|
1689 |
* <p> <i>view-name</i> is the {@link FileAttributeView#name name} of a {@link |
|
1690 |
* FileAttributeView} that identifies a set of file attributes. If not |
|
1691 |
* specified then it defaults to {@code "basic"}, the name of the file |
|
1692 |
* attribute view that identifies the basic set of file attributes common to |
|
1693 |
* many file systems. <i>attribute-name</i> is the name of the attribute |
|
1694 |
* within the set. |
|
1695 |
* |
|
1696 |
* <p> The {@code options} array may be used to indicate how symbolic links |
|
1697 |
* are handled for the case that the file is a symbolic link. By default, |
|
1698 |
* symbolic links are followed and the file attribute of the final target |
|
1699 |
* of the link is set. If the option {@link LinkOption#NOFOLLOW_LINKS |
|
1700 |
* NOFOLLOW_LINKS} is present then symbolic links are not followed. |
|
1701 |
* |
|
1702 |
* <p> <b>Usage Example:</b> |
|
1703 |
* Suppose we want to set the DOS "hidden" attribute: |
|
1704 |
* <pre> |
|
1705 |
* Path path = ... |
|
1706 |
* Files.setAttribute(path, "dos:hidden", true); |
|
1707 |
* </pre> |
|
1708 |
* |
|
1709 |
* @param path |
|
1710 |
* the path to the file |
|
1711 |
* @param attribute |
|
1712 |
* the attribute to set |
|
1713 |
* @param value |
|
1714 |
* the attribute value |
|
1715 |
* @param options |
|
1716 |
* options indicating how symbolic links are handled |
|
1717 |
* |
|
1718 |
* @return the {@code path} parameter |
|
1719 |
* |
|
1720 |
* @throws UnsupportedOperationException |
|
8808 | 1721 |
* if the attribute view is not available |
8158 | 1722 |
* @throws IllegalArgumentException |
8808 | 1723 |
* if the attribute name is not specified, or is not recognized, or |
1724 |
* the attribute value is of the correct type but has an |
|
8158 | 1725 |
* inappropriate value |
1726 |
* @throws ClassCastException |
|
1727 |
* if the attribute value is not of the expected type or is a |
|
1728 |
* collection containing elements that are not of the expected |
|
1729 |
* type |
|
1730 |
* @throws IOException |
|
1731 |
* if an I/O error occurs |
|
1732 |
* @throws SecurityException |
|
1733 |
* In the case of the default provider, and a security manager is |
|
1734 |
* installed, its {@link SecurityManager#checkWrite(String) checkWrite} |
|
1735 |
* method denies write access to the file. If this method is invoked |
|
1736 |
* to set security sensitive attributes then the security manager |
|
1737 |
* may be invoked to check for additional permissions. |
|
1738 |
*/ |
|
1739 |
public static Path setAttribute(Path path, String attribute, Object value, |
|
1740 |
LinkOption... options) |
|
1741 |
throws IOException |
|
1742 |
{ |
|
1743 |
provider(path).setAttribute(path, attribute, value, options); |
|
1744 |
return path; |
|
1745 |
} |
|
1746 |
||
1747 |
/** |
|
1748 |
* Reads the value of a file attribute. |
|
1749 |
* |
|
1750 |
* <p> The {@code attribute} parameter identifies the attribute to be read |
|
1751 |
* and takes the form: |
|
1752 |
* <blockquote> |
|
1753 |
* [<i>view-name</i><b>:</b>]<i>attribute-name</i> |
|
1754 |
* </blockquote> |
|
1755 |
* where square brackets [...] delineate an optional component and the |
|
1756 |
* character {@code ':'} stands for itself. |
|
1757 |
* |
|
1758 |
* <p> <i>view-name</i> is the {@link FileAttributeView#name name} of a {@link |
|
1759 |
* FileAttributeView} that identifies a set of file attributes. If not |
|
1760 |
* specified then it defaults to {@code "basic"}, the name of the file |
|
1761 |
* attribute view that identifies the basic set of file attributes common to |
|
1762 |
* many file systems. <i>attribute-name</i> is the name of the attribute. |
|
1763 |
* |
|
1764 |
* <p> The {@code options} array may be used to indicate how symbolic links |
|
1765 |
* are handled for the case that the file is a symbolic link. By default, |
|
1766 |
* symbolic links are followed and the file attribute of the final target |
|
1767 |
* of the link is read. If the option {@link LinkOption#NOFOLLOW_LINKS |
|
1768 |
* NOFOLLOW_LINKS} is present then symbolic links are not followed. |
|
1769 |
* |
|
1770 |
* <p> <b>Usage Example:</b> |
|
1771 |
* Suppose we require the user ID of the file owner on a system that |
|
1772 |
* supports a "{@code unix}" view: |
|
1773 |
* <pre> |
|
1774 |
* Path path = ... |
|
1775 |
* int uid = (Integer)Files.getAttribute(path, "unix:uid"); |
|
1776 |
* </pre> |
|
1777 |
* |
|
1778 |
* @param path |
|
1779 |
* the path to the file |
|
1780 |
* @param attribute |
|
1781 |
* the attribute to read |
|
1782 |
* @param options |
|
1783 |
* options indicating how symbolic links are handled |
|
1784 |
* |
|
8808 | 1785 |
* @return the attribute value |
8158 | 1786 |
* |
8808 | 1787 |
* @throws UnsupportedOperationException |
1788 |
* if the attribute view is not available |
|
1789 |
* @throws IllegalArgumentException |
|
1790 |
* if the attribute name is not specified or is not recognized |
|
8158 | 1791 |
* @throws IOException |
1792 |
* if an I/O error occurs |
|
1793 |
* @throws SecurityException |
|
1794 |
* In the case of the default provider, and a security manager is |
|
1795 |
* installed, its {@link SecurityManager#checkRead(String) checkRead} |
|
1796 |
* method denies read access to the file. If this method is invoked |
|
1797 |
* to read security sensitive attributes then the security manager |
|
1798 |
* may be invoked to check for additional permissions. |
|
1799 |
*/ |
|
1800 |
public static Object getAttribute(Path path, String attribute, |
|
1801 |
LinkOption... options) |
|
1802 |
throws IOException |
|
1803 |
{ |
|
1804 |
// only one attribute should be read |
|
1805 |
if (attribute.indexOf('*') >= 0 || attribute.indexOf(',') >= 0) |
|
8808 | 1806 |
throw new IllegalArgumentException(attribute); |
8158 | 1807 |
Map<String,Object> map = readAttributes(path, attribute, options); |
8808 | 1808 |
assert map.size() == 1; |
8158 | 1809 |
String name; |
1810 |
int pos = attribute.indexOf(':'); |
|
1811 |
if (pos == -1) { |
|
1812 |
name = attribute; |
|
1813 |
} else { |
|
1814 |
name = (pos == attribute.length()) ? "" : attribute.substring(pos+1); |
|
1815 |
} |
|
1816 |
return map.get(name); |
|
1817 |
} |
|
1818 |
||
1819 |
/** |
|
1820 |
* Reads a set of file attributes as a bulk operation. |
|
1821 |
* |
|
1822 |
* <p> The {@code attributes} parameter identifies the attributes to be read |
|
1823 |
* and takes the form: |
|
1824 |
* <blockquote> |
|
1825 |
* [<i>view-name</i><b>:</b>]<i>attribute-list</i> |
|
1826 |
* </blockquote> |
|
1827 |
* where square brackets [...] delineate an optional component and the |
|
1828 |
* character {@code ':'} stands for itself. |
|
1829 |
* |
|
1830 |
* <p> <i>view-name</i> is the {@link FileAttributeView#name name} of a {@link |
|
1831 |
* FileAttributeView} that identifies a set of file attributes. If not |
|
1832 |
* specified then it defaults to {@code "basic"}, the name of the file |
|
1833 |
* attribute view that identifies the basic set of file attributes common to |
|
1834 |
* many file systems. |
|
1835 |
* |
|
1836 |
* <p> The <i>attribute-list</i> component is a comma separated list of |
|
1837 |
* zero or more names of attributes to read. If the list contains the value |
|
1838 |
* {@code "*"} then all attributes are read. Attributes that are not supported |
|
1839 |
* are ignored and will not be present in the returned map. It is |
|
1840 |
* implementation specific if all attributes are read as an atomic operation |
|
1841 |
* with respect to other file system operations. |
|
1842 |
* |
|
1843 |
* <p> The following examples demonstrate possible values for the {@code |
|
1844 |
* attributes} parameter: |
|
1845 |
* |
|
1846 |
* <blockquote> |
|
1847 |
* <table border="0"> |
|
1848 |
* <tr> |
|
1849 |
* <td> {@code "*"} </td> |
|
1850 |
* <td> Read all {@link BasicFileAttributes basic-file-attributes}. </td> |
|
1851 |
* </tr> |
|
1852 |
* <tr> |
|
1853 |
* <td> {@code "size,lastModifiedTime,lastAccessTime"} </td> |
|
1854 |
* <td> Reads the file size, last modified time, and last access time |
|
1855 |
* attributes. </td> |
|
1856 |
* </tr> |
|
1857 |
* <tr> |
|
1858 |
* <td> {@code "posix:*"} </td> |
|
1859 |
* <td> Read all {@link PosixFileAttributes POSIX-file-attributes}. </td> |
|
1860 |
* </tr> |
|
1861 |
* <tr> |
|
1862 |
* <td> {@code "posix:permissions,owner,size"} </td> |
|
1863 |
* <td> Reads the POSX file permissions, owner, and file size. </td> |
|
1864 |
* </tr> |
|
1865 |
* </table> |
|
1866 |
* </blockquote> |
|
1867 |
* |
|
1868 |
* <p> The {@code options} array may be used to indicate how symbolic links |
|
1869 |
* are handled for the case that the file is a symbolic link. By default, |
|
1870 |
* symbolic links are followed and the file attribute of the final target |
|
1871 |
* of the link is read. If the option {@link LinkOption#NOFOLLOW_LINKS |
|
1872 |
* NOFOLLOW_LINKS} is present then symbolic links are not followed. |
|
1873 |
* |
|
1874 |
* @param path |
|
1875 |
* the path to the file |
|
1876 |
* @param attributes |
|
1877 |
* the attributes to read |
|
1878 |
* @param options |
|
1879 |
* options indicating how symbolic links are handled |
|
1880 |
* |
|
8808 | 1881 |
* @return a map of the attributes returned; The map's keys are the |
1882 |
* attribute names, its values are the attribute values |
|
8158 | 1883 |
* |
8808 | 1884 |
* @throws UnsupportedOperationException |
1885 |
* if the attribute view is not available |
|
1886 |
* @throws IllegalArgumentException |
|
1887 |
* if no attributes are specified or an unrecognized attributes is |
|
1888 |
* specified |
|
8158 | 1889 |
* @throws IOException |
1890 |
* if an I/O error occurs |
|
1891 |
* @throws SecurityException |
|
1892 |
* In the case of the default provider, and a security manager is |
|
1893 |
* installed, its {@link SecurityManager#checkRead(String) checkRead} |
|
1894 |
* method denies read access to the file. If this method is invoked |
|
1895 |
* to read security sensitive attributes then the security manager |
|
1896 |
* may be invoke to check for additional permissions. |
|
1897 |
*/ |
|
1898 |
public static Map<String,Object> readAttributes(Path path, String attributes, |
|
1899 |
LinkOption... options) |
|
1900 |
throws IOException |
|
1901 |
{ |
|
1902 |
return provider(path).readAttributes(path, attributes, options); |
|
1903 |
} |
|
1904 |
||
1905 |
/** |
|
1906 |
* Returns a file's POSIX file permissions. |
|
1907 |
* |
|
1908 |
* <p> The {@code path} parameter is associated with a {@code FileSystem} |
|
1909 |
* that supports the {@link PosixFileAttributeView}. This attribute view |
|
1910 |
* provides access to file attributes commonly associated with files on file |
|
1911 |
* systems used by operating systems that implement the Portable Operating |
|
1912 |
* System Interface (POSIX) family of standards. |
|
1913 |
* |
|
1914 |
* <p> The {@code options} array may be used to indicate how symbolic links |
|
1915 |
* are handled for the case that the file is a symbolic link. By default, |
|
1916 |
* symbolic links are followed and the file attribute of the final target |
|
1917 |
* of the link is read. If the option {@link LinkOption#NOFOLLOW_LINKS |
|
1918 |
* NOFOLLOW_LINKS} is present then symbolic links are not followed. |
|
1919 |
* |
|
1920 |
* @param path |
|
1921 |
* the path to the file |
|
1922 |
* @param options |
|
1923 |
* options indicating how symbolic links are handled |
|
1924 |
* |
|
1925 |
* @return the file permissions |
|
1926 |
* |
|
1927 |
* @throws UnsupportedOperationException |
|
1928 |
* if the associated file system does not support the {@code |
|
1929 |
* PosixFileAttributeView} |
|
1930 |
* @throws IOException |
|
1931 |
* if an I/O error occurs |
|
1932 |
* @throws SecurityException |
|
1933 |
* In the case of the default provider, a security manager is |
|
1934 |
* installed, and it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt> |
|
1935 |
* or its {@link SecurityManager#checkRead(String) checkRead} method |
|
1936 |
* denies read access to the file. |
|
1937 |
*/ |
|
1938 |
public static Set<PosixFilePermission> getPosixFilePermissions(Path path, |
|
1939 |
LinkOption... options) |
|
1940 |
throws IOException |
|
1941 |
{ |
|
1942 |
return readAttributes(path, PosixFileAttributes.class, options).permissions(); |
|
1943 |
} |
|
1944 |
||
1945 |
/** |
|
1946 |
* Sets a file's POSIX permissions. |
|
1947 |
* |
|
1948 |
* <p> The {@code path} parameter is associated with a {@code FileSystem} |
|
1949 |
* that supports the {@link PosixFileAttributeView}. This attribute view |
|
1950 |
* provides access to file attributes commonly associated with files on file |
|
1951 |
* systems used by operating systems that implement the Portable Operating |
|
1952 |
* System Interface (POSIX) family of standards. |
|
1953 |
* |
|
1954 |
* @param path |
|
1955 |
* A file reference that locates the file |
|
1956 |
* @param perms |
|
1957 |
* The new set of permissions |
|
1958 |
* |
|
1959 |
* @throws UnsupportedOperationException |
|
1960 |
* if the associated file system does not support the {@code |
|
1961 |
* PosixFileAttributeView} |
|
1962 |
* @throws ClassCastException |
|
1963 |
* if the sets contains elements that are not of type {@code |
|
1964 |
* PosixFilePermission} |
|
1965 |
* @throws IOException |
|
1966 |
* if an I/O error occurs |
|
1967 |
* @throws SecurityException |
|
1968 |
* In the case of the default provider, and a security manager is |
|
1969 |
* installed, it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt> |
|
1970 |
* or its {@link SecurityManager#checkWrite(String) checkWrite} |
|
1971 |
* method denies write access to the file. |
|
1972 |
*/ |
|
1973 |
public static Path setPosixFilePermissions(Path path, |
|
1974 |
Set<PosixFilePermission> perms) |
|
1975 |
throws IOException |
|
1976 |
{ |
|
1977 |
PosixFileAttributeView view = |
|
1978 |
getFileAttributeView(path, PosixFileAttributeView.class); |
|
1979 |
if (view == null) |
|
1980 |
throw new UnsupportedOperationException(); |
|
1981 |
view.setPermissions(perms); |
|
1982 |
return path; |
|
1983 |
} |
|
1984 |
||
1985 |
/** |
|
1986 |
* Returns the owner of a file. |
|
1987 |
* |
|
1988 |
* <p> The {@code path} parameter is associated with a file system that |
|
1989 |
* supports {@link FileOwnerAttributeView}. This file attribute view provides |
|
1990 |
* access to a file attribute that is the owner of the file. |
|
1991 |
* |
|
1992 |
* @param path |
|
1993 |
* A file reference that locates the file |
|
1994 |
* @param options |
|
1995 |
* options indicating how symbolic links are handled |
|
1996 |
* |
|
1997 |
* @return A user principal representing the owner of the file |
|
1998 |
* |
|
1999 |
* @throws UnsupportedOperationException |
|
2000 |
* if the associated file system does not support the {@code |
|
2001 |
* FileOwnerAttributeView} |
|
2002 |
* @throws IOException |
|
2003 |
* if an I/O error occurs |
|
2004 |
* @throws SecurityException |
|
2005 |
* In the case of the default provider, and a security manager is |
|
2006 |
* installed, it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt> |
|
2007 |
* or its {@link SecurityManager#checkRead(String) checkRead} method |
|
2008 |
* denies read access to the file. |
|
2009 |
*/ |
|
2010 |
public static UserPrincipal getOwner(Path path, LinkOption... options) throws IOException { |
|
2011 |
FileOwnerAttributeView view = |
|
2012 |
getFileAttributeView(path, FileOwnerAttributeView.class, options); |
|
2013 |
if (view == null) |
|
2014 |
throw new UnsupportedOperationException(); |
|
2015 |
return view.getOwner(); |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2016 |
} |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2017 |
|
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2018 |
/** |
8158 | 2019 |
* Updates the file owner. |
2020 |
* |
|
2021 |
* <p> The {@code path} parameter is associated with a file system that |
|
2022 |
* supports {@link FileOwnerAttributeView}. This file attribute view provides |
|
2023 |
* access to a file attribute that is the owner of the file. |
|
2024 |
* |
|
2025 |
* <p> <b>Usage Example:</b> |
|
2026 |
* Suppose we want to make "joe" the owner of a file: |
|
2027 |
* <pre> |
|
2028 |
* Path path = ... |
|
2029 |
* UserPrincipalLookupService lookupService = |
|
2030 |
* provider(path).getUserPrincipalLookupService(); |
|
2031 |
* UserPrincipal joe = lookupService.lookupPrincipalByName("joe"); |
|
2032 |
* Files.setOwner(path, joe); |
|
2033 |
* </pre> |
|
2034 |
* |
|
2035 |
* @param path |
|
2036 |
* A file reference that locates the file |
|
2037 |
* @param owner |
|
2038 |
* The new file owner |
|
2039 |
* |
|
2040 |
* @throws UnsupportedOperationException |
|
2041 |
* if the associated file system does not support the {@code |
|
2042 |
* FileOwnerAttributeView} |
|
2043 |
* @throws IOException |
|
2044 |
* if an I/O error occurs |
|
2045 |
* @throws SecurityException |
|
2046 |
* In the case of the default provider, and a security manager is |
|
2047 |
* installed, it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt> |
|
2048 |
* or its {@link SecurityManager#checkWrite(String) checkWrite} |
|
2049 |
* method denies write access to the file. |
|
2050 |
* |
|
2051 |
* @see FileSystem#getUserPrincipalLookupService |
|
2052 |
* @see java.nio.file.attribute.UserPrincipalLookupService |
|
2053 |
*/ |
|
2054 |
public static Path setOwner(Path path, UserPrincipal owner) |
|
2055 |
throws IOException |
|
2056 |
{ |
|
2057 |
FileOwnerAttributeView view = |
|
2058 |
getFileAttributeView(path, FileOwnerAttributeView.class); |
|
2059 |
if (view == null) |
|
2060 |
throw new UnsupportedOperationException(); |
|
2061 |
view.setOwner(owner); |
|
2062 |
return path; |
|
2063 |
} |
|
2064 |
||
2065 |
/** |
|
2066 |
* Tests whether a file is a symbolic link. |
|
2067 |
* |
|
2068 |
* <p> Where is it required to distinguish an I/O exception from the case |
|
2069 |
* that the file is not a symbolic link then the file attributes can be |
|
2070 |
* read with the {@link #readAttributes(Path,Class,LinkOption[]) |
|
2071 |
* readAttributes} method and the file type tested with the {@link |
|
2072 |
* BasicFileAttributes#isSymbolicLink} method. |
|
2073 |
* |
|
2074 |
* @return {@code true} if the file is a symbolic link; {@code false} if |
|
2075 |
* the file does not exist, is not a symbolic link, or it cannot |
|
9026 | 2076 |
* be determined if the file is a symbolic link or not. |
8158 | 2077 |
* |
2078 |
* @throws SecurityException |
|
2079 |
* In the case of the default provider, and a security manager is |
|
2080 |
* installed, its {@link SecurityManager#checkRead(String) checkRead} |
|
2081 |
* method denies read access to the file. |
|
2082 |
*/ |
|
2083 |
public static boolean isSymbolicLink(Path path) { |
|
2084 |
try { |
|
2085 |
return readAttributes(path, |
|
2086 |
BasicFileAttributes.class, |
|
2087 |
LinkOption.NOFOLLOW_LINKS).isSymbolicLink(); |
|
2088 |
} catch (IOException ioe) { |
|
2089 |
return false; |
|
2090 |
} |
|
2091 |
} |
|
2092 |
||
2093 |
/** |
|
2094 |
* Tests whether a file is a directory. |
|
2095 |
* |
|
2096 |
* <p> The {@code options} array may be used to indicate how symbolic links |
|
2097 |
* are handled for the case that the file is a symbolic link. By default, |
|
2098 |
* symbolic links are followed and the file attribute of the final target |
|
2099 |
* of the link is read. If the option {@link LinkOption#NOFOLLOW_LINKS |
|
2100 |
* NOFOLLOW_LINKS} is present then symbolic links are not followed. |
|
2101 |
* |
|
2102 |
* <p> Where is it required to distinguish an I/O exception from the case |
|
2103 |
* that the file is not a directory then the file attributes can be |
|
2104 |
* read with the {@link #readAttributes(Path,Class,LinkOption[]) |
|
2105 |
* readAttributes} method and the file type tested with the {@link |
|
2106 |
* BasicFileAttributes#isDirectory} method. |
|
2107 |
* |
|
2108 |
* @param path |
|
2109 |
* the path to the file to test |
|
2110 |
* @param options |
|
2111 |
* options indicating how symbolic links are handled |
|
2112 |
* |
|
2113 |
* @return {@code true} if the file is a directory; {@code false} if |
|
2114 |
* the file does not exist, is not a directory, or it cannot |
|
9026 | 2115 |
* be determined if the file is a directory or not. |
8158 | 2116 |
* |
2117 |
* @throws SecurityException |
|
2118 |
* In the case of the default provider, and a security manager is |
|
2119 |
* installed, its {@link SecurityManager#checkRead(String) checkRead} |
|
2120 |
* method denies read access to the file. |
|
2121 |
*/ |
|
2122 |
public static boolean isDirectory(Path path, LinkOption... options) { |
|
2123 |
try { |
|
2124 |
return readAttributes(path, BasicFileAttributes.class, options).isDirectory(); |
|
2125 |
} catch (IOException ioe) { |
|
2126 |
return false; |
|
2127 |
} |
|
2128 |
} |
|
2129 |
||
2130 |
/** |
|
2131 |
* Tests whether a file is a regular file with opaque content. |
|
2132 |
* |
|
2133 |
* <p> The {@code options} array may be used to indicate how symbolic links |
|
2134 |
* are handled for the case that the file is a symbolic link. By default, |
|
2135 |
* symbolic links are followed and the file attribute of the final target |
|
2136 |
* of the link is read. If the option {@link LinkOption#NOFOLLOW_LINKS |
|
2137 |
* NOFOLLOW_LINKS} is present then symbolic links are not followed. |
|
2138 |
* |
|
2139 |
* <p> Where is it required to distinguish an I/O exception from the case |
|
2140 |
* that the file is not a regular file then the file attributes can be |
|
2141 |
* read with the {@link #readAttributes(Path,Class,LinkOption[]) |
|
2142 |
* readAttributes} method and the file type tested with the {@link |
|
2143 |
* BasicFileAttributes#isRegularFile} method. |
|
2144 |
* |
|
2145 |
* @param path |
|
2146 |
* the path to the file |
|
2147 |
* @param options |
|
2148 |
* options indicating how symbolic links are handled |
|
2149 |
* |
|
2150 |
* @return {@code true} if the file is a regular file; {@code false} if |
|
9026 | 2151 |
* the file does not exist, is not a regular file, or it |
2152 |
* cannot be determined if the file is a regular file or not. |
|
8158 | 2153 |
* |
2154 |
* @throws SecurityException |
|
2155 |
* In the case of the default provider, and a security manager is |
|
2156 |
* installed, its {@link SecurityManager#checkRead(String) checkRead} |
|
2157 |
* method denies read access to the file. |
|
2158 |
*/ |
|
2159 |
public static boolean isRegularFile(Path path, LinkOption... options) { |
|
2160 |
try { |
|
2161 |
return readAttributes(path, BasicFileAttributes.class, options).isRegularFile(); |
|
2162 |
} catch (IOException ioe) { |
|
2163 |
return false; |
|
2164 |
} |
|
2165 |
} |
|
2166 |
||
2167 |
/** |
|
2168 |
* Returns a file's last modified time. |
|
2169 |
* |
|
2170 |
* <p> The {@code options} array may be used to indicate how symbolic links |
|
2171 |
* are handled for the case that the file is a symbolic link. By default, |
|
2172 |
* symbolic links are followed and the file attribute of the final target |
|
2173 |
* of the link is read. If the option {@link LinkOption#NOFOLLOW_LINKS |
|
2174 |
* NOFOLLOW_LINKS} is present then symbolic links are not followed. |
|
2175 |
* |
|
2176 |
* @param path |
|
2177 |
* the path to the file |
|
2178 |
* @param options |
|
2179 |
* options indicating how symbolic links are handled |
|
2180 |
* |
|
2181 |
* @return a {@code FileTime} representing the time the file was last |
|
2182 |
* modified, or an implementation specific default when a time |
|
2183 |
* stamp to indicate the time of last modification is not supported |
|
2184 |
* by the file system |
|
2185 |
* |
|
2186 |
* @throws IOException |
|
2187 |
* if an I/O error occurs |
|
2188 |
* @throws SecurityException |
|
2189 |
* In the case of the default provider, and a security manager is |
|
2190 |
* installed, its {@link SecurityManager#checkRead(String) checkRead} |
|
2191 |
* method denies read access to the file. |
|
2192 |
* |
|
2193 |
* @see BasicFileAttributes#lastModifiedTime |
|
2194 |
*/ |
|
2195 |
public static FileTime getLastModifiedTime(Path path, LinkOption... options) |
|
2196 |
throws IOException |
|
2197 |
{ |
|
2198 |
return readAttributes(path, BasicFileAttributes.class, options).lastModifiedTime(); |
|
2199 |
} |
|
2200 |
||
2201 |
/** |
|
2202 |
* Updates a file's last modified time attribute. The file time is converted |
|
2203 |
* to the epoch and precision supported by the file system. Converting from |
|
2204 |
* finer to coarser granularities result in precision loss. The behavior of |
|
2205 |
* this method when attempting to set the last modified time when it is not |
|
2206 |
* supported by the file system or is outside the range supported by the |
|
2207 |
* underlying file store is not defined. It may or not fail by throwing an |
|
2208 |
* {@code IOException}. |
|
2209 |
* |
|
2210 |
* <p> <b>Usage Example:</b> |
|
2211 |
* Suppose we want to set the last modified time to the current time: |
|
2212 |
* <pre> |
|
2213 |
* Path path = ... |
|
2214 |
* FileTime now = FileTime.fromMillis(System.currentTimeMillis()); |
|
2215 |
* Files.setLastModifiedTime(path, now); |
|
2216 |
* </pre> |
|
2217 |
* |
|
2218 |
* @param path |
|
2219 |
* the path to the file |
|
2220 |
* @param time |
|
2221 |
* the new last modified time |
|
2222 |
* |
|
2223 |
* @return the file |
|
2224 |
* |
|
2225 |
* @throws IOException |
|
2226 |
* if an I/O error occurs |
|
2227 |
* @throws SecurityException |
|
2228 |
* In the case of the default provider, the security manager's {@link |
|
2229 |
* SecurityManager#checkWrite(String) checkWrite} method is invoked |
|
2230 |
* to check write access to file |
|
2231 |
* |
|
2232 |
* @see BasicFileAttributeView#setTimes |
|
2233 |
*/ |
|
2234 |
public static Path setLastModifiedTime(Path path, FileTime time) |
|
2235 |
throws IOException |
|
2236 |
{ |
|
2237 |
getFileAttributeView(path, BasicFileAttributeView.class) |
|
2238 |
.setTimes(time, null, null); |
|
2239 |
return path; |
|
2240 |
} |
|
2241 |
||
2242 |
/** |
|
2243 |
* Returns the size of a file (in bytes). The size may differ from the |
|
2244 |
* actual size on the file system due to compression, support for sparse |
|
2245 |
* files, or other reasons. The size of files that are not {@link |
|
2246 |
* #isRegularFile regular} files is implementation specific and |
|
2247 |
* therefore unspecified. |
|
2248 |
* |
|
2249 |
* @param path |
|
2250 |
* the path to the file |
|
2251 |
* |
|
2252 |
* @return the file size, in bytes |
|
2253 |
* |
|
2254 |
* @throws IOException |
|
2255 |
* if an I/O error occurs |
|
2256 |
* @throws SecurityException |
|
2257 |
* In the case of the default provider, and a security manager is |
|
2258 |
* installed, its {@link SecurityManager#checkRead(String) checkRead} |
|
2259 |
* method denies read access to the file. |
|
2260 |
* |
|
2261 |
* @see BasicFileAttributes#size |
|
2262 |
*/ |
|
2263 |
public static long size(Path path) throws IOException { |
|
2264 |
return readAttributes(path, BasicFileAttributes.class).size(); |
|
2265 |
} |
|
2266 |
||
2267 |
// -- Accessibility -- |
|
2268 |
||
2269 |
/** |
|
2270 |
* Returns {@code false} if NOFOLLOW_LINKS is present. |
|
2271 |
*/ |
|
2272 |
private static boolean followLinks(LinkOption... options) { |
|
2273 |
boolean followLinks = true; |
|
2274 |
for (LinkOption opt: options) { |
|
2275 |
if (opt == LinkOption.NOFOLLOW_LINKS) { |
|
2276 |
followLinks = false; |
|
2277 |
continue; |
|
2278 |
} |
|
2279 |
if (opt == null) |
|
2280 |
throw new NullPointerException(); |
|
2281 |
throw new AssertionError("Should not get here"); |
|
2282 |
} |
|
2283 |
return followLinks; |
|
2284 |
} |
|
2285 |
||
2286 |
/** |
|
2287 |
* Tests whether a file exists. |
|
2288 |
* |
|
2289 |
* <p> The {@code options} parameter may be used to indicate how symbolic links |
|
2290 |
* are handled for the case that the file is a symbolic link. By default, |
|
2291 |
* symbolic links are followed. If the option {@link LinkOption#NOFOLLOW_LINKS |
|
2292 |
* NOFOLLOW_LINKS} is present then symbolic links are not followed. |
|
2293 |
* |
|
2294 |
* <p> Note that the result of this method is immediately outdated. If this |
|
2295 |
* method indicates the file exists then there is no guarantee that a |
|
2296 |
* subsequence access will succeed. Care should be taken when using this |
|
2297 |
* method in security sensitive applications. |
|
2298 |
* |
|
2299 |
* @param path |
|
2300 |
* the path to the file to test |
|
2301 |
* @param options |
|
2302 |
* options indicating how symbolic links are handled |
|
2303 |
* . |
|
2304 |
* @return {@code true} if the file exists; {@code false} if the file does |
|
2305 |
* not exist or its existence cannot be determined. |
|
2306 |
* |
|
2307 |
* @throws SecurityException |
|
2308 |
* In the case of the default provider, the {@link |
|
2309 |
* SecurityManager#checkRead(String)} is invoked to check |
|
2310 |
* read access to the file. |
|
2311 |
* |
|
2312 |
* @see #notExists |
|
2313 |
*/ |
|
2314 |
public static boolean exists(Path path, LinkOption... options) { |
|
2315 |
try { |
|
2316 |
if (followLinks(options)) { |
|
2317 |
provider(path).checkAccess(path); |
|
2318 |
} else { |
|
2319 |
// attempt to read attributes without following links |
|
2320 |
readAttributes(path, BasicFileAttributes.class, |
|
2321 |
LinkOption.NOFOLLOW_LINKS); |
|
2322 |
} |
|
2323 |
// file exists |
|
2324 |
return true; |
|
2325 |
} catch (IOException x) { |
|
2326 |
// does not exist or unable to determine if file exists |
|
2327 |
return false; |
|
2328 |
} |
|
2329 |
||
2330 |
} |
|
2331 |
||
2332 |
/** |
|
2333 |
* Tests whether the file located by this path does not exist. This method |
|
2334 |
* is intended for cases where it is required to take action when it can be |
|
2335 |
* confirmed that a file does not exist. |
|
2336 |
* |
|
2337 |
* <p> The {@code options} parameter may be used to indicate how symbolic links |
|
2338 |
* are handled for the case that the file is a symbolic link. By default, |
|
2339 |
* symbolic links are followed. If the option {@link LinkOption#NOFOLLOW_LINKS |
|
2340 |
* NOFOLLOW_LINKS} is present then symbolic links are not followed. |
|
2341 |
* |
|
2342 |
* <p> Note that this method is not the complement of the {@link #exists |
|
2343 |
* exists} method. Where it is not possible to determine if a file exists |
|
2344 |
* or not then both methods return {@code false}. As with the {@code exists} |
|
2345 |
* method, the result of this method is immediately outdated. If this |
|
2346 |
* method indicates the file does exist then there is no guarantee that a |
|
2347 |
* subsequence attempt to create the file will succeed. Care should be taken |
|
2348 |
* when using this method in security sensitive applications. |
|
2349 |
* |
|
2350 |
* @param path |
|
2351 |
* the path to the file to test |
|
2352 |
* @param options |
|
2353 |
* options indicating how symbolic links are handled |
|
2354 |
* |
|
2355 |
* @return {@code true} if the file does not exist; {@code false} if the |
|
2356 |
* file exists or its existence cannot be determined |
|
2357 |
* |
|
2358 |
* @throws SecurityException |
|
2359 |
* In the case of the default provider, the {@link |
|
2360 |
* SecurityManager#checkRead(String)} is invoked to check |
|
2361 |
* read access to the file. |
|
2362 |
*/ |
|
2363 |
public static boolean notExists(Path path, LinkOption... options) { |
|
2364 |
try { |
|
2365 |
if (followLinks(options)) { |
|
2366 |
provider(path).checkAccess(path); |
|
2367 |
} else { |
|
2368 |
// attempt to read attributes without following links |
|
2369 |
readAttributes(path, BasicFileAttributes.class, |
|
2370 |
LinkOption.NOFOLLOW_LINKS); |
|
2371 |
} |
|
2372 |
// file exists |
|
2373 |
return false; |
|
2374 |
} catch (NoSuchFileException x) { |
|
2375 |
// file confirmed not to exist |
|
2376 |
return true; |
|
2377 |
} catch (IOException x) { |
|
2378 |
return false; |
|
2379 |
} |
|
2380 |
} |
|
2381 |
||
2382 |
/** |
|
2383 |
* Used by isReadbale, isWritable, isExecutable to test access to a file. |
|
2384 |
*/ |
|
2385 |
private static boolean isAccessible(Path path, AccessMode... modes) { |
|
2386 |
try { |
|
2387 |
provider(path).checkAccess(path, modes); |
|
2388 |
return true; |
|
2389 |
} catch (IOException x) { |
|
2390 |
return false; |
|
2391 |
} |
|
2392 |
} |
|
2393 |
||
2394 |
/** |
|
2395 |
* Tests whether a file is readable. This method checks that a file exists |
|
2396 |
* and that this Java virtual machine has appropriate privileges that would |
|
2397 |
* allow it open the file for reading. Depending on the implementation, this |
|
2398 |
* method may require to read file permissions, access control lists, or |
|
2399 |
* other file attributes in order to check the effective access to the file. |
|
2400 |
* Consequently, this method may not be atomic with respect to other file |
|
2401 |
* system operations. |
|
2402 |
* |
|
2403 |
* <p> Note that the result of this method is immediately outdated, there is |
|
2404 |
* no guarantee that a subsequent attempt to open the file for reading will |
|
2405 |
* succeed (or even that it will access the same file). Care should be taken |
|
2406 |
* when using this method in security sensitive applications. |
|
2407 |
* |
|
2408 |
* @param path |
|
2409 |
* the path to the file to check |
|
2410 |
* |
|
2411 |
* @return {@code true} if the file exists and is readable; {@code false} |
|
2412 |
* if the file does not exist, read access would be denied because |
|
2413 |
* the Java virtual machine has insufficient privileges, or access |
|
2414 |
* cannot be determined |
|
2415 |
* |
|
2416 |
* @throws SecurityException |
|
2417 |
* In the case of the default provider, and a security manager is |
|
2418 |
* installed, the {@link SecurityManager#checkRead(String) checkRead} |
|
2419 |
* is invoked to check read access to the file. |
|
2420 |
*/ |
|
2421 |
public static boolean isReadable(Path path) { |
|
2422 |
return isAccessible(path, AccessMode.READ); |
|
2423 |
} |
|
2424 |
||
2425 |
/** |
|
2426 |
* Tests whether a file is writable. This method checks that a file exists |
|
2427 |
* and that this Java virtual machine has appropriate privileges that would |
|
2428 |
* allow it open the file for writing. Depending on the implementation, this |
|
2429 |
* method may require to read file permissions, access control lists, or |
|
2430 |
* other file attributes in order to check the effective access to the file. |
|
2431 |
* Consequently, this method may not be atomic with respect to other file |
|
2432 |
* system operations. |
|
2433 |
* |
|
2434 |
* <p> Note that result of this method is immediately outdated, there is no |
|
2435 |
* guarantee that a subsequent attempt to open the file for writing will |
|
2436 |
* succeed (or even that it will access the same file). Care should be taken |
|
2437 |
* when using this method in security sensitive applications. |
|
2438 |
* |
|
2439 |
* @param path |
|
2440 |
* the path to the file to check |
|
2441 |
* |
|
2442 |
* @return {@code true} if the file exists and is writable; {@code false} |
|
2443 |
* if the file does not exist, write access would be denied because |
|
2444 |
* the Java virtual machine has insufficient privileges, or access |
|
2445 |
* cannot be determined |
|
2446 |
* |
|
2447 |
* @throws SecurityException |
|
2448 |
* In the case of the default provider, and a security manager is |
|
2449 |
* installed, the {@link SecurityManager#checkWrite(String) checkWrite} |
|
2450 |
* is invoked to check write access to the file. |
|
2451 |
*/ |
|
2452 |
public static boolean isWritable(Path path) { |
|
2453 |
return isAccessible(path, AccessMode.WRITE); |
|
2454 |
} |
|
2455 |
||
2456 |
/** |
|
2457 |
* Tests whether a file is executable. This method checks that a file exists |
|
2458 |
* and that this Java virtual machine has appropriate privileges to {@link |
|
2459 |
* Runtime#exec execute} the file. The semantics may differ when checking |
|
2460 |
* access to a directory. For example, on UNIX systems, checking for |
|
2461 |
* execute access checks that the Java virtual machine has permission to |
|
2462 |
* search the directory in order to access file or subdirectories. |
|
2463 |
* |
|
2464 |
* <p> Depending on the implementation, this method may require to read file |
|
2465 |
* permissions, access control lists, or other file attributes in order to |
|
2466 |
* check the effective access to the file. Consequently, this method may not |
|
2467 |
* be atomic with respect to other file system operations. |
|
2468 |
* |
|
2469 |
* <p> Note that the result of this method is immediately outdated, there is |
|
2470 |
* no guarantee that a subsequent attempt to execute the file will succeed |
|
2471 |
* (or even that it will access the same file). Care should be taken when |
|
2472 |
* using this method in security sensitive applications. |
|
2473 |
* |
|
2474 |
* @param path |
|
2475 |
* the path to the file to check |
|
2476 |
* |
|
2477 |
* @return {@code true} if the file exists and is executable; {@code false} |
|
2478 |
* if the file does not exist, execute access would be denied because |
|
2479 |
* the Java virtual machine has insufficient privileges, or access |
|
2480 |
* cannot be determined |
|
2481 |
* |
|
2482 |
* @throws SecurityException |
|
2483 |
* In the case of the default provider, and a security manager is |
|
2484 |
* installed, the {@link SecurityManager#checkExec(String) |
|
2485 |
* checkExec} is invoked to check execute access to the file. |
|
2486 |
*/ |
|
2487 |
public static boolean isExecutable(Path path) { |
|
2488 |
return isAccessible(path, AccessMode.EXECUTE); |
|
2489 |
} |
|
2490 |
||
2491 |
// -- Recursive operations -- |
|
2492 |
||
2493 |
/** |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2494 |
* Walks a file tree. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2495 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2496 |
* <p> This method walks a file tree rooted at a given starting file. The |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2497 |
* file tree traversal is <em>depth-first</em> with the given {@link |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2498 |
* FileVisitor} invoked for each file encountered. File tree traversal |
3722
08849c86a297
6868627: (spec) Files.walkFileTree doesn't make it clear that uncaught errors and exceptions are propagated
alanb
parents:
3065
diff
changeset
|
2499 |
* completes when all accessible files in the tree have been visited, or a |
08849c86a297
6868627: (spec) Files.walkFileTree doesn't make it clear that uncaught errors and exceptions are propagated
alanb
parents:
3065
diff
changeset
|
2500 |
* visit method returns a result of {@link FileVisitResult#TERMINATE |
6695
0e91810597f9
6907737: (file) FileVisitor and Files.walkFileTree issues
alanb
parents:
5506
diff
changeset
|
2501 |
* TERMINATE}. Where a visit method terminates due an {@code IOException}, |
0e91810597f9
6907737: (file) FileVisitor and Files.walkFileTree issues
alanb
parents:
5506
diff
changeset
|
2502 |
* an uncaught error, or runtime exception, then the traversal is terminated |
0e91810597f9
6907737: (file) FileVisitor and Files.walkFileTree issues
alanb
parents:
5506
diff
changeset
|
2503 |
* and the error or exception is propagated to the caller of this method. |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2504 |
* |
8158 | 2505 |
* <p> For each file encountered this method attempts to read its {@link |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2506 |
* java.nio.file.attribute.BasicFileAttributes}. If the file is not a |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2507 |
* directory then the {@link FileVisitor#visitFile visitFile} method is |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2508 |
* invoked with the file attributes. If the file attributes cannot be read, |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2509 |
* due to an I/O exception, then the {@link FileVisitor#visitFileFailed |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2510 |
* visitFileFailed} method is invoked with the I/O exception. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2511 |
* |
6695
0e91810597f9
6907737: (file) FileVisitor and Files.walkFileTree issues
alanb
parents:
5506
diff
changeset
|
2512 |
* <p> Where the file is a directory, and the directory could not be opened, |
0e91810597f9
6907737: (file) FileVisitor and Files.walkFileTree issues
alanb
parents:
5506
diff
changeset
|
2513 |
* then the {@code visitFileFailed} method is invoked with the I/O exception, |
0e91810597f9
6907737: (file) FileVisitor and Files.walkFileTree issues
alanb
parents:
5506
diff
changeset
|
2514 |
* after which, the file tree walk continues, by default, at the next |
0e91810597f9
6907737: (file) FileVisitor and Files.walkFileTree issues
alanb
parents:
5506
diff
changeset
|
2515 |
* <em>sibling</em> of the directory. |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2516 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2517 |
* <p> Where the directory is opened successfully, then the entries in the |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2518 |
* directory, and their <em>descendants</em> are visited. When all entries |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2519 |
* have been visited, or an I/O error occurs during iteration of the |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2520 |
* directory, then the directory is closed and the visitor's {@link |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2521 |
* FileVisitor#postVisitDirectory postVisitDirectory} method is invoked. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2522 |
* The file tree walk then continues, by default, at the next <em>sibling</em> |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2523 |
* of the directory. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2524 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2525 |
* <p> By default, symbolic links are not automatically followed by this |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2526 |
* method. If the {@code options} parameter contains the {@link |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2527 |
* FileVisitOption#FOLLOW_LINKS FOLLOW_LINKS} option then symbolic links are |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2528 |
* followed. When following links, and the attributes of the target cannot |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2529 |
* be read, then this method attempts to get the {@code BasicFileAttributes} |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2530 |
* of the link. If they can be read then the {@code visitFile} method is |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2531 |
* invoked with the attributes of the link (otherwise the {@code visitFileFailed} |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2532 |
* method is invoked as specified above). |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2533 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2534 |
* <p> If the {@code options} parameter contains the {@link |
6695
0e91810597f9
6907737: (file) FileVisitor and Files.walkFileTree issues
alanb
parents:
5506
diff
changeset
|
2535 |
* FileVisitOption#FOLLOW_LINKS FOLLOW_LINKS} option then this method keeps |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2536 |
* track of directories visited so that cycles can be detected. A cycle |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2537 |
* arises when there is an entry in a directory that is an ancestor of the |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2538 |
* directory. Cycle detection is done by recording the {@link |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2539 |
* java.nio.file.attribute.BasicFileAttributes#fileKey file-key} of directories, |
8158 | 2540 |
* or if file keys are not available, by invoking the {@link #isSameFile |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2541 |
* isSameFile} method to test if a directory is the same file as an |
6695
0e91810597f9
6907737: (file) FileVisitor and Files.walkFileTree issues
alanb
parents:
5506
diff
changeset
|
2542 |
* ancestor. When a cycle is detected it is treated as an I/O error, and the |
0e91810597f9
6907737: (file) FileVisitor and Files.walkFileTree issues
alanb
parents:
5506
diff
changeset
|
2543 |
* {@link FileVisitor#visitFileFailed visitFileFailed} method is invoked with |
0e91810597f9
6907737: (file) FileVisitor and Files.walkFileTree issues
alanb
parents:
5506
diff
changeset
|
2544 |
* an instance of {@link FileSystemLoopException}. |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2545 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2546 |
* <p> The {@code maxDepth} parameter is the maximum number of levels of |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2547 |
* directories to visit. A value of {@code 0} means that only the starting |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2548 |
* file is visited, unless denied by the security manager. A value of |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2549 |
* {@link Integer#MAX_VALUE MAX_VALUE} may be used to indicate that all |
6695
0e91810597f9
6907737: (file) FileVisitor and Files.walkFileTree issues
alanb
parents:
5506
diff
changeset
|
2550 |
* levels should be visited. The {@code visitFile} method is invoked for all |
0e91810597f9
6907737: (file) FileVisitor and Files.walkFileTree issues
alanb
parents:
5506
diff
changeset
|
2551 |
* files, including directories, encountered at {@code maxDepth}, unless the |
0e91810597f9
6907737: (file) FileVisitor and Files.walkFileTree issues
alanb
parents:
5506
diff
changeset
|
2552 |
* basic file attributes cannot be read, in which case the {@code |
0e91810597f9
6907737: (file) FileVisitor and Files.walkFileTree issues
alanb
parents:
5506
diff
changeset
|
2553 |
* visitFileFailed} method is invoked. |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2554 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2555 |
* <p> If a visitor returns a result of {@code null} then {@code |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2556 |
* NullPointerException} is thrown. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2557 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2558 |
* <p> When a security manager is installed and it denies access to a file |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2559 |
* (or directory), then it is ignored and the visitor is not invoked for |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2560 |
* that file (or directory). |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2561 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2562 |
* @param start |
8158 | 2563 |
* the starting file |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2564 |
* @param options |
8158 | 2565 |
* options to configure the traversal |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2566 |
* @param maxDepth |
8158 | 2567 |
* the maximum number of directory levels to visit |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2568 |
* @param visitor |
8158 | 2569 |
* the file visitor to invoke for each file |
2570 |
* |
|
2571 |
* @return the starting file |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2572 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2573 |
* @throws IllegalArgumentException |
8158 | 2574 |
* if the {@code maxDepth} parameter is negative |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2575 |
* @throws SecurityException |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2576 |
* If the security manager denies access to the starting file. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2577 |
* In the case of the default provider, the {@link |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2578 |
* SecurityManager#checkRead(String) checkRead} method is invoked |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2579 |
* to check read access to the directory. |
6695
0e91810597f9
6907737: (file) FileVisitor and Files.walkFileTree issues
alanb
parents:
5506
diff
changeset
|
2580 |
* @throws IOException |
8158 | 2581 |
* if an I/O error is thrown by a visitor method |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2582 |
*/ |
8158 | 2583 |
public static Path walkFileTree(Path start, |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2584 |
Set<FileVisitOption> options, |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2585 |
int maxDepth, |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2586 |
FileVisitor<? super Path> visitor) |
6695
0e91810597f9
6907737: (file) FileVisitor and Files.walkFileTree issues
alanb
parents:
5506
diff
changeset
|
2587 |
throws IOException |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2588 |
{ |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2589 |
if (maxDepth < 0) |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2590 |
throw new IllegalArgumentException("'maxDepth' is negative"); |
3847
821abab95d38
6876541: (file) Files.walkFileTree(...): no SecurityException if read access to the starting file is denied
alanb
parents:
3722
diff
changeset
|
2591 |
new FileTreeWalker(options, visitor, maxDepth).walk(start); |
8158 | 2592 |
return start; |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2593 |
} |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2594 |
|
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2595 |
/** |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2596 |
* Walks a file tree. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2597 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2598 |
* <p> This method works as if invoking it were equivalent to evaluating the |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2599 |
* expression: |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2600 |
* <blockquote><pre> |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2601 |
* walkFileTree(start, EnumSet.noneOf(FileVisitOption.class), Integer.MAX_VALUE, visitor) |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2602 |
* </pre></blockquote> |
8158 | 2603 |
* In other words, it does not follow symbolic links, and visits all levels |
8539
eeb9fc5a68c1
7020888: (file) Miscellaneous and trivial clean-ups (typos and opportunities to use suppressed exceptions)
alanb
parents:
8166
diff
changeset
|
2604 |
* of the file tree. |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2605 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2606 |
* @param start |
8158 | 2607 |
* the starting file |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2608 |
* @param visitor |
8158 | 2609 |
* the file visitor to invoke for each file |
2610 |
* |
|
2611 |
* @return the starting file |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2612 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2613 |
* @throws SecurityException |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2614 |
* If the security manager denies access to the starting file. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2615 |
* In the case of the default provider, the {@link |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2616 |
* SecurityManager#checkRead(String) checkRead} method is invoked |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2617 |
* to check read access to the directory. |
6695
0e91810597f9
6907737: (file) FileVisitor and Files.walkFileTree issues
alanb
parents:
5506
diff
changeset
|
2618 |
* @throws IOException |
8158 | 2619 |
* if an I/O error is thrown by a visitor method |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2620 |
*/ |
8158 | 2621 |
public static Path walkFileTree(Path start, FileVisitor<? super Path> visitor) |
2622 |
throws IOException |
|
2623 |
{ |
|
2624 |
return walkFileTree(start, |
|
2625 |
EnumSet.noneOf(FileVisitOption.class), |
|
2626 |
Integer.MAX_VALUE, |
|
2627 |
visitor); |
|
2628 |
} |
|
2629 |
||
2630 |
||
2631 |
// -- Utility methods for simple usages -- |
|
2632 |
||
2633 |
// buffer size used for reading and writing |
|
2634 |
private static final int BUFFER_SIZE = 8192; |
|
2635 |
||
2636 |
/** |
|
2637 |
* Opens a file for reading, returning a {@code BufferedReader} that may be |
|
2638 |
* used to read text from the file in an efficient manner. Bytes from the |
|
2639 |
* file are decoded into characters using the specified charset. Reading |
|
2640 |
* commences at the beginning of the file. |
|
2641 |
* |
|
2642 |
* <p> The {@code Reader} methods that read from the file throw {@code |
|
2643 |
* IOException} if a malformed or unmappable byte sequence is read. |
|
2644 |
* |
|
2645 |
* @param path |
|
2646 |
* the path to the file |
|
2647 |
* @param cs |
|
2648 |
* the charset to use for decoding |
|
2649 |
* |
|
2650 |
* @return a new buffered reader, with default buffer size, to read text |
|
2651 |
* from the file |
|
2652 |
* |
|
2653 |
* @throws IOException |
|
2654 |
* if an I/O error occurs opening the file |
|
2655 |
* @throws SecurityException |
|
2656 |
* In the case of the default provider, and a security manager is |
|
2657 |
* installed, the {@link SecurityManager#checkRead(String) checkRead} |
|
2658 |
* method is invoked to check read access to the file. |
|
2659 |
* |
|
2660 |
* @see #readAllLines |
|
2661 |
*/ |
|
2662 |
public static BufferedReader newBufferedReader(Path path, Charset cs) |
|
6695
0e91810597f9
6907737: (file) FileVisitor and Files.walkFileTree issues
alanb
parents:
5506
diff
changeset
|
2663 |
throws IOException |
0e91810597f9
6907737: (file) FileVisitor and Files.walkFileTree issues
alanb
parents:
5506
diff
changeset
|
2664 |
{ |
8158 | 2665 |
CharsetDecoder decoder = cs.newDecoder(); |
2666 |
Reader reader = new InputStreamReader(newInputStream(path), decoder); |
|
2667 |
return new BufferedReader(reader); |
|
2668 |
} |
|
2669 |
||
2670 |
/** |
|
2671 |
* Opens or creates a file for writing, returning a {@code BufferedWriter} |
|
2672 |
* that may be used to write text to the file in an efficient manner. |
|
2673 |
* The {@code options} parameter specifies how the the file is created or |
|
2674 |
* opened. If no options are present then this method works as if the {@link |
|
2675 |
* StandardOpenOption#CREATE CREATE}, {@link |
|
2676 |
* StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING}, and {@link |
|
2677 |
* StandardOpenOption#WRITE WRITE} options are present. In other words, it |
|
2678 |
* opens the file for writing, creating the file if it doesn't exist, or |
|
2679 |
* initially truncating an existing {@link #isRegularFile regular-file} to |
|
2680 |
* a size of {@code 0} if it exists. |
|
2681 |
* |
|
2682 |
* <p> The {@code Writer} methods to write text throw {@code IOException} |
|
2683 |
* if the text cannot be encoded using the specified charset. |
|
2684 |
* |
|
2685 |
* @param path |
|
2686 |
* the path to the file |
|
2687 |
* @param cs |
|
2688 |
* the charset to use for encoding |
|
2689 |
* @param options |
|
2690 |
* options specifying how the file is opened |
|
2691 |
* |
|
2692 |
* @return a new buffered writer, with default buffer size, to write text |
|
2693 |
* to the file |
|
2694 |
* |
|
2695 |
* @throws IOException |
|
2696 |
* if an I/O error occurs opening or creating the file |
|
2697 |
* @throws UnsupportedOperationException |
|
2698 |
* if an unsupported option is specified |
|
2699 |
* @throws SecurityException |
|
2700 |
* In the case of the default provider, and a security manager is |
|
2701 |
* installed, the {@link SecurityManager#checkWrite(String) checkWrite} |
|
2702 |
* method is invoked to check write access to the file. |
|
2703 |
* |
|
2704 |
* @see #write(Path,Iterable,Charset,OpenOption[]) |
|
2705 |
*/ |
|
2706 |
public static BufferedWriter newBufferedWriter(Path path, Charset cs, |
|
2707 |
OpenOption... options) |
|
2708 |
throws IOException |
|
2709 |
{ |
|
2710 |
CharsetEncoder encoder = cs.newEncoder(); |
|
2711 |
Writer writer = new OutputStreamWriter(newOutputStream(path, options), encoder); |
|
2712 |
return new BufferedWriter(writer); |
|
2713 |
} |
|
2714 |
||
2715 |
/** |
|
2716 |
* Reads all bytes from an input stream and writes them to an output stream. |
|
2717 |
*/ |
|
2718 |
private static long copy(InputStream source, OutputStream sink) |
|
2719 |
throws IOException |
|
2720 |
{ |
|
2721 |
long nread = 0L; |
|
2722 |
byte[] buf = new byte[BUFFER_SIZE]; |
|
2723 |
int n; |
|
2724 |
while ((n = source.read(buf)) > 0) { |
|
2725 |
sink.write(buf, 0, n); |
|
2726 |
nread += n; |
|
2727 |
} |
|
2728 |
return nread; |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
2729 |
} |
3065
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2730 |
|
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2731 |
/** |
8158 | 2732 |
* Copies all bytes from an input stream to a file. On return, the input |
2733 |
* stream will be at end of stream. |
|
2734 |
* |
|
2735 |
* <p> By default, the copy fails if the target file already exists or is a |
|
2736 |
* symbolic link. If the {@link StandardCopyOption#REPLACE_EXISTING |
|
2737 |
* REPLACE_EXISTING} option is specified, and the target file already exists, |
|
2738 |
* then it is replaced if it is not a non-empty directory. If the target |
|
2739 |
* file exists and is a symbolic link, then the symbolic link is replaced. |
|
2740 |
* In this release, the {@code REPLACE_EXISTING} option is the only option |
|
2741 |
* required to be supported by this method. Additional options may be |
|
2742 |
* supported in future releases. |
|
3065
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2743 |
* |
8158 | 2744 |
* <p> If an I/O error occurs reading from the input stream or writing to |
2745 |
* the file, then it may do so after the target file has been created and |
|
2746 |
* after some bytes have been read or written. Consequently the input |
|
2747 |
* stream may not be at end of stream and may be in an inconsistent state. |
|
2748 |
* It is strongly recommended that the input stream be promptly closed if an |
|
2749 |
* I/O error occurs. |
|
2750 |
* |
|
2751 |
* <p> This method may block indefinitely reading from the input stream (or |
|
2752 |
* writing to the file). The behavior for the case that the input stream is |
|
2753 |
* <i>asynchronously closed</i> or the thread interrupted during the copy is |
|
2754 |
* highly input stream and file system provider specific and therefore not |
|
2755 |
* specified. |
|
3065
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2756 |
* |
8158 | 2757 |
* <p> <b>Usage example</b>: Suppose we want to capture a web page and save |
2758 |
* it to a file: |
|
2759 |
* <pre> |
|
2760 |
* Path path = ... |
|
2761 |
* URI u = URI.create("http://java.sun.com/"); |
|
2762 |
* try (InputStream in = u.toURL().openStream()) { |
|
2763 |
* Files.copy(in, path); |
|
2764 |
* } |
|
2765 |
* </pre> |
|
3065
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2766 |
* |
8158 | 2767 |
* @param in |
2768 |
* the input stream to read from |
|
2769 |
* @param target |
|
2770 |
* the path to the file |
|
2771 |
* @param options |
|
2772 |
* options specifying how the copy should be done |
|
2773 |
* |
|
2774 |
* @return the number of bytes read or written |
|
3065
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2775 |
* |
8158 | 2776 |
* @throws IOException |
2777 |
* if an I/O error occurs when reading or writing |
|
2778 |
* @throws FileAlreadyExistsException |
|
2779 |
* if the target file exists but cannot be replaced because the |
|
2780 |
* {@code REPLACE_EXISTING} option is not specified <i>(optional |
|
2781 |
* specific exception)</i> |
|
2782 |
* @throws DirectoryNotEmptyException |
|
2783 |
* the {@code REPLACE_EXISTING} option is specified but the file |
|
2784 |
* cannot be replaced because it is a non-empty directory |
|
2785 |
* <i>(optional specific exception)</i> * |
|
3065
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2786 |
* @throws UnsupportedOperationException |
8158 | 2787 |
* if {@code options} contains a copy option that is not supported |
3065
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2788 |
* @throws SecurityException |
8158 | 2789 |
* In the case of the default provider, and a security manager is |
3065
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2790 |
* installed, the {@link SecurityManager#checkWrite(String) checkWrite} |
8158 | 2791 |
* method is invoked to check write access to the file. Where the |
2792 |
* {@code REPLACE_EXISTING} option is specified, the security |
|
2793 |
* manager's {@link SecurityManager#checkDelete(String) checkDelete} |
|
2794 |
* method is invoked to check that an existing file can be deleted. |
|
3065
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2795 |
*/ |
8158 | 2796 |
public static long copy(InputStream in, Path target, CopyOption... options) |
3065
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2797 |
throws IOException |
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2798 |
{ |
8158 | 2799 |
// ensure not null before opening file |
8166
13423c0952ad
7012540: java.util.Objects.nonNull() incorrectly named
briangoetz
parents:
8158
diff
changeset
|
2800 |
Objects.requireNonNull(in); |
8158 | 2801 |
|
2802 |
// check for REPLACE_EXISTING |
|
2803 |
boolean replaceExisting = false; |
|
2804 |
for (CopyOption opt: options) { |
|
2805 |
if (opt == StandardCopyOption.REPLACE_EXISTING) { |
|
2806 |
replaceExisting = true; |
|
2807 |
} else { |
|
2808 |
if (opt == null) { |
|
2809 |
throw new NullPointerException("options contains 'null'"); |
|
2810 |
} else { |
|
2811 |
throw new UnsupportedOperationException(opt + " not supported"); |
|
2812 |
} |
|
2813 |
} |
|
3065
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2814 |
} |
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2815 |
|
8158 | 2816 |
// attempt to delete an existing file |
3065
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2817 |
SecurityException se = null; |
8158 | 2818 |
if (replaceExisting) { |
2819 |
try { |
|
2820 |
deleteIfExists(target); |
|
2821 |
} catch (SecurityException x) { |
|
2822 |
se = x; |
|
2823 |
} |
|
3065
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2824 |
} |
8158 | 2825 |
|
2826 |
// attempt to create target file. If it fails with |
|
2827 |
// FileAlreadyExistsException then it may be because the security |
|
2828 |
// manager prevented us from deleting the file, in which case we just |
|
2829 |
// throw the SecurityException. |
|
2830 |
OutputStream ostream; |
|
2831 |
try { |
|
2832 |
ostream = newOutputStream(target, StandardOpenOption.CREATE_NEW, |
|
2833 |
StandardOpenOption.WRITE); |
|
2834 |
} catch (FileAlreadyExistsException x) { |
|
3065
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2835 |
if (se != null) |
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2836 |
throw se; |
8158 | 2837 |
// someone else won the race and created the file |
2838 |
throw x; |
|
3065
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2839 |
} |
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2840 |
|
8158 | 2841 |
// do the copy |
2842 |
try (OutputStream out = ostream) { |
|
2843 |
return copy(in, out); |
|
3065
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2844 |
} |
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2845 |
} |
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2846 |
|
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2847 |
/** |
8158 | 2848 |
* Copies all bytes from a file to an output stream. |
2849 |
* |
|
2850 |
* <p> If an I/O error occurs reading from the file or writing to the output |
|
2851 |
* stream, then it may do so after some bytes have been read or written. |
|
2852 |
* Consequently the output stream may be in an inconsistent state. It is |
|
2853 |
* strongly recommended that the output stream be promptly closed if an I/O |
|
2854 |
* error occurs. |
|
2855 |
* |
|
2856 |
* <p> This method may block indefinitely writing to the output stream (or |
|
2857 |
* reading from the file). The behavior for the case that the output stream |
|
2858 |
* is <i>asynchronously closed</i> or the thread interrupted during the copy |
|
2859 |
* is highly output stream and file system provider specific and therefore |
|
2860 |
* not specified. |
|
2861 |
* |
|
2862 |
* <p> Note that if the given output stream is {@link java.io.Flushable} |
|
2863 |
* then its {@link java.io.Flushable#flush flush} method may need to invoked |
|
2864 |
* after this method completes so as to flush any buffered output. |
|
2865 |
* |
|
2866 |
* @param source |
|
2867 |
* the path to the file |
|
2868 |
* @param out |
|
2869 |
* the output stream to write to |
|
2870 |
* |
|
2871 |
* @return the number of bytes read or written |
|
2872 |
* |
|
2873 |
* @throws IOException |
|
2874 |
* if an I/O error occurs when reading or writing |
|
2875 |
* @throws SecurityException |
|
2876 |
* In the case of the default provider, and a security manager is |
|
2877 |
* installed, the {@link SecurityManager#checkRead(String) checkRead} |
|
2878 |
* method is invoked to check read access to the file. |
|
3065
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2879 |
*/ |
8158 | 2880 |
public static long copy(Path source, OutputStream out) throws IOException { |
2881 |
// ensure not null before opening file |
|
8166
13423c0952ad
7012540: java.util.Objects.nonNull() incorrectly named
briangoetz
parents:
8158
diff
changeset
|
2882 |
Objects.requireNonNull(out); |
8158 | 2883 |
|
2884 |
try (InputStream in = newInputStream(source)) { |
|
2885 |
return copy(in, out); |
|
2886 |
} |
|
2887 |
} |
|
2888 |
||
2889 |
/** |
|
2890 |
* Read all the bytes from an input stream. The {@code initialSize} |
|
2891 |
* parameter indicates the initial size of the byte[] to allocate. |
|
2892 |
*/ |
|
2893 |
private static byte[] read(InputStream source, int initialSize) |
|
3065
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2894 |
throws IOException |
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
2895 |
{ |
8158 | 2896 |
int capacity = initialSize; |
2897 |
byte[] buf = new byte[capacity]; |
|
2898 |
int nread = 0; |
|
2899 |
int rem = buf.length; |
|
2900 |
int n; |
|
2901 |
// read to EOF which may read more or less than initialSize (eg: file |
|
2902 |
// is truncated while we are reading) |
|
2903 |
while ((n = source.read(buf, nread, rem)) > 0) { |
|
2904 |
nread += n; |
|
2905 |
rem -= n; |
|
2906 |
assert rem >= 0; |
|
2907 |
if (rem == 0) { |
|
2908 |
// need larger buffer |
|
2909 |
int newCapacity = capacity << 1; |
|
2910 |
if (newCapacity < 0) { |
|
2911 |
if (capacity == Integer.MAX_VALUE) |
|
2912 |
throw new OutOfMemoryError("Required array size too large"); |
|
2913 |
newCapacity = Integer.MAX_VALUE; |
|
2914 |
} |
|
2915 |
rem = newCapacity - capacity; |
|
2916 |
buf = Arrays.copyOf(buf, newCapacity); |
|
2917 |
capacity = newCapacity; |
|
2918 |
} |
|
2919 |
} |
|
2920 |
return (capacity == nread) ? buf : Arrays.copyOf(buf, nread); |
|
2921 |
} |
|
2922 |
||
2923 |
/** |
|
2924 |
* Read all the bytes from a file. The method ensures that the file is |
|
2925 |
* closed when all bytes have been read or an I/O error, or other runtime |
|
2926 |
* exception, is thrown. |
|
2927 |
* |
|
2928 |
* <p> Note that this method is intended for simple cases where it is |
|
2929 |
* convenient to read all bytes into a byte array. It is not intended for |
|
2930 |
* reading in large files. |
|
2931 |
* |
|
2932 |
* @param path |
|
2933 |
* the path to the file |
|
2934 |
* |
|
2935 |
* @return a byte array containing the bytes read from the file |
|
2936 |
* |
|
2937 |
* @throws IOException |
|
2938 |
* if an I/O error occurs reading from the stream |
|
2939 |
* @throws OutOfMemoryError |
|
2940 |
* if an array of the required size cannot be allocated, for |
|
2941 |
* example the file is larger that {@code 2GB} |
|
2942 |
* @throws SecurityException |
|
2943 |
* In the case of the default provider, and a security manager is |
|
2944 |
* installed, the {@link SecurityManager#checkRead(String) checkRead} |
|
2945 |
* method is invoked to check read access to the file. |
|
2946 |
*/ |
|
2947 |
public static byte[] readAllBytes(Path path) throws IOException { |
|
2948 |
long size = size(path); |
|
2949 |
if (size > (long)Integer.MAX_VALUE) |
|
2950 |
throw new OutOfMemoryError("Required array size too large"); |
|
2951 |
||
2952 |
try (InputStream in = newInputStream(path)) { |
|
2953 |
return read(in, (int)size); |
|
2954 |
} |
|
2955 |
} |
|
2956 |
||
2957 |
/** |
|
2958 |
* Read all lines from a file. This method ensures that the file is |
|
2959 |
* closed when all bytes have been read or an I/O error, or other runtime |
|
2960 |
* exception, is thrown. Bytes from the file are decoded into characters |
|
2961 |
* using the specified charset. |
|
2962 |
* |
|
2963 |
* <p> This method recognizes the following as line terminators: |
|
2964 |
* <ul> |
|
2965 |
* <li> <code>\u000D</code> followed by <code>\u000A</code>, |
|
2966 |
* CARRIAGE RETURN followed by LINE FEED </li> |
|
2967 |
* <li> <code>\u000A</code>, LINE FEED </li> |
|
2968 |
* <li> <code>\u000D</code>, CARRIAGE RETURN </li> |
|
2969 |
* </ul> |
|
2970 |
* <p> Additional Unicode line terminators may be recognized in future |
|
2971 |
* releases. |
|
2972 |
* |
|
2973 |
* <p> Note that this method is intended for simple cases where it is |
|
2974 |
* convenient to read all lines in a single operation. It is not intended |
|
2975 |
* for reading in large files. |
|
2976 |
* |
|
2977 |
* @param path |
|
2978 |
* the path to the file |
|
2979 |
* @param cs |
|
2980 |
* the charset to use for decoding |
|
2981 |
* |
|
2982 |
* @return the lines from the file as a {@code List}; whether the {@code |
|
2983 |
* List} is modifiable or not is implementation dependent and |
|
2984 |
* therefore not specified |
|
2985 |
* |
|
2986 |
* @throws IOException |
|
2987 |
* if an I/O error occurs reading from the file or a malformed or |
|
2988 |
* unmappable byte sequence is read |
|
2989 |
* @throws SecurityException |
|
2990 |
* In the case of the default provider, and a security manager is |
|
2991 |
* installed, the {@link SecurityManager#checkRead(String) checkRead} |
|
2992 |
* method is invoked to check read access to the file. |
|
2993 |
* |
|
2994 |
* @see #newBufferedReader |
|
2995 |
*/ |
|
2996 |
public static List<String> readAllLines(Path path, Charset cs) |
|
2997 |
throws IOException |
|
2998 |
{ |
|
2999 |
try (BufferedReader reader = newBufferedReader(path, cs)) { |
|
3000 |
List<String> result = new ArrayList<>(); |
|
3001 |
for (;;) { |
|
3002 |
String line = reader.readLine(); |
|
3003 |
if (line == null) |
|
3004 |
break; |
|
3005 |
result.add(line); |
|
3006 |
} |
|
3007 |
return result; |
|
3065
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
3008 |
} |
452aaa2899fc
6838333: New I/O: Update file system API to jsr203/nio2-b101
alanb
parents:
2057
diff
changeset
|
3009 |
} |
8158 | 3010 |
|
3011 |
/** |
|
3012 |
* Writes bytes to a file. The {@code options} parameter specifies how the |
|
3013 |
* the file is created or opened. If no options are present then this method |
|
3014 |
* works as if the {@link StandardOpenOption#CREATE CREATE}, {@link |
|
3015 |
* StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING}, and {@link |
|
3016 |
* StandardOpenOption#WRITE WRITE} options are present. In other words, it |
|
3017 |
* opens the file for writing, creating the file if it doesn't exist, or |
|
3018 |
* initially truncating an existing {@link #isRegularFile regular-file} to |
|
3019 |
* a size of {@code 0}. All bytes in the byte array are written to the file. |
|
3020 |
* The method ensures that the file is closed when all bytes have been |
|
3021 |
* written (or an I/O error or other runtime exception is thrown). If an I/O |
|
3022 |
* error occurs then it may do so after the file has created or truncated, |
|
3023 |
* or after some bytes have been written to the file. |
|
3024 |
* |
|
3025 |
* <p> <b>Usage example</b>: By default the method creates a new file or |
|
8539
eeb9fc5a68c1
7020888: (file) Miscellaneous and trivial clean-ups (typos and opportunities to use suppressed exceptions)
alanb
parents:
8166
diff
changeset
|
3026 |
* overwrites an existing file. Suppose you instead want to append bytes |
8158 | 3027 |
* to an existing file: |
3028 |
* <pre> |
|
3029 |
* Path path = ... |
|
3030 |
* byte[] bytes = ... |
|
3031 |
* Files.write(path, bytes, StandardOpenOption.APPEND); |
|
3032 |
* </pre> |
|
3033 |
* |
|
3034 |
* @param path |
|
3035 |
* the path to the file |
|
3036 |
* @param bytes |
|
3037 |
* the byte array with the bytes to write |
|
3038 |
* @param options |
|
3039 |
* options specifying how the file is opened |
|
3040 |
* |
|
3041 |
* @return the path |
|
3042 |
* |
|
3043 |
* @throws IOException |
|
3044 |
* if an I/O error occurs writing to or creating the file |
|
3045 |
* @throws UnsupportedOperationException |
|
3046 |
* if an unsupported option is specified |
|
3047 |
* @throws SecurityException |
|
3048 |
* In the case of the default provider, and a security manager is |
|
3049 |
* installed, the {@link SecurityManager#checkWrite(String) checkWrite} |
|
3050 |
* method is invoked to check write access to the file. |
|
3051 |
*/ |
|
3052 |
public static Path write(Path path, byte[] bytes, OpenOption... options) |
|
3053 |
throws IOException |
|
3054 |
{ |
|
3055 |
// ensure bytes is not null before opening file |
|
8166
13423c0952ad
7012540: java.util.Objects.nonNull() incorrectly named
briangoetz
parents:
8158
diff
changeset
|
3056 |
Objects.requireNonNull(bytes); |
8158 | 3057 |
|
3058 |
try (OutputStream out = Files.newOutputStream(path, options)) { |
|
3059 |
int len = bytes.length; |
|
3060 |
int rem = len; |
|
3061 |
while (rem > 0) { |
|
3062 |
int n = Math.min(rem, BUFFER_SIZE); |
|
3063 |
out.write(bytes, (len-rem), n); |
|
3064 |
rem -= n; |
|
3065 |
} |
|
3066 |
} |
|
3067 |
return path; |
|
3068 |
} |
|
3069 |
||
3070 |
/** |
|
3071 |
* Write lines of text to a file. Each line is a char sequence and is |
|
3072 |
* written to the file in sequence with each line terminated by the |
|
3073 |
* platform's line separator, as defined by the system property {@code |
|
3074 |
* line.separator}. Characters are encoded into bytes using the specified |
|
3075 |
* charset. |
|
3076 |
* |
|
3077 |
* <p> The {@code options} parameter specifies how the the file is created |
|
3078 |
* or opened. If no options are present then this method works as if the |
|
3079 |
* {@link StandardOpenOption#CREATE CREATE}, {@link |
|
3080 |
* StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING}, and {@link |
|
3081 |
* StandardOpenOption#WRITE WRITE} options are present. In other words, it |
|
3082 |
* opens the file for writing, creating the file if it doesn't exist, or |
|
3083 |
* initially truncating an existing {@link #isRegularFile regular-file} to |
|
3084 |
* a size of {@code 0}. The method ensures that the file is closed when all |
|
3085 |
* lines have been written (or an I/O error or other runtime exception is |
|
3086 |
* thrown). If an I/O error occurs then it may do so after the file has |
|
3087 |
* created or truncated, or after some bytes have been written to the file. |
|
3088 |
* |
|
3089 |
* @param path |
|
3090 |
* the path to the file |
|
3091 |
* @param lines |
|
3092 |
* an object to iterate over the char sequences |
|
3093 |
* @param cs |
|
3094 |
* the charset to use for encoding |
|
3095 |
* @param options |
|
3096 |
* options specifying how the file is opened |
|
3097 |
* |
|
3098 |
* @return the path |
|
3099 |
* |
|
3100 |
* @throws IOException |
|
3101 |
* if an I/O error occurs writing to or creating the file, or the |
|
3102 |
* text cannot be encoded using the specified charset |
|
3103 |
* @throws UnsupportedOperationException |
|
3104 |
* if an unsupported option is specified |
|
3105 |
* @throws SecurityException |
|
3106 |
* In the case of the default provider, and a security manager is |
|
3107 |
* installed, the {@link SecurityManager#checkWrite(String) checkWrite} |
|
3108 |
* method is invoked to check write access to the file. |
|
3109 |
*/ |
|
3110 |
public static Path write(Path path, Iterable<? extends CharSequence> lines, |
|
3111 |
Charset cs, OpenOption... options) |
|
3112 |
throws IOException |
|
3113 |
{ |
|
3114 |
// ensure lines is not null before opening file |
|
8166
13423c0952ad
7012540: java.util.Objects.nonNull() incorrectly named
briangoetz
parents:
8158
diff
changeset
|
3115 |
Objects.requireNonNull(lines); |
8158 | 3116 |
CharsetEncoder encoder = cs.newEncoder(); |
3117 |
OutputStream out = newOutputStream(path, options); |
|
3118 |
try (BufferedWriter writer = new BufferedWriter(new OutputStreamWriter(out, encoder))) { |
|
3119 |
for (CharSequence line: lines) { |
|
3120 |
writer.append(line); |
|
3121 |
writer.newLine(); |
|
3122 |
} |
|
3123 |
} |
|
3124 |
return path; |
|
3125 |
} |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
diff
changeset
|
3126 |
} |