|
1 /* |
|
2 * Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved. |
|
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
|
4 * |
|
5 * This code is free software; you can redistribute it and/or modify it |
|
6 * under the terms of the GNU General Public License version 2 only, as |
|
7 * published by the Free Software Foundation. Sun designates this |
|
8 * particular file as subject to the "Classname" exception as provided |
|
9 * by Sun in the LICENSE file that accompanied this code. |
|
10 * |
|
11 * This code is distributed in the hope that it will be useful, but WITHOUT |
|
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
14 * version 2 for more details (a copy is included in the LICENSE file that |
|
15 * accompanied this code). |
|
16 * |
|
17 * You should have received a copy of the GNU General Public License version |
|
18 * 2 along with this work; if not, write to the Free Software Foundation, |
|
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
20 * |
|
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
|
22 * CA 95054 USA or visit www.sun.com if you need additional information or |
|
23 * have any questions. |
|
24 */ |
|
25 package java.nio.file; |
|
26 |
|
27 import java.nio.file.attribute.*; |
|
28 import java.nio.channels.SeekableByteChannel; |
|
29 import java.util.Set; |
|
30 import java.io.IOException; |
|
31 |
|
32 /** |
|
33 * A {@code DirectoryStream} that defines operations on files that are located |
|
34 * relative to an open directory. A {@code SecureDirectoryStream} is intended |
|
35 * for use by sophisticated or security sensitive applications requiring to |
|
36 * traverse file trees or otherwise operate on directories in a race-free manner. |
|
37 * Race conditions can arise when a sequence of file operations cannot be |
|
38 * carried out in isolation. Each of the file operations defined by this |
|
39 * interface specify a relative {@link Path}. All access to the file is relative |
|
40 * to the open directory irrespective of if the directory is moved or replaced |
|
41 * by an attacker while the directory is open. A {@code SecureDirectoryStream} |
|
42 * may also be used as a virtual <em>working directory</em>. |
|
43 * |
|
44 * <p> A {@code SecureDirectoryStream} requires corresponding support from the |
|
45 * underlying operating system. Where an implementation supports this features |
|
46 * then the {@code DirectoryStream} returned by the {@link Path#newDirectoryStream |
|
47 * newDirectoryStream} method will be a {@code SecureDirectoryStream} and must |
|
48 * be cast to that type in order to invoke the methods defined by this interface. |
|
49 * |
|
50 * <p> As specified by {@code DirectoryStream}, the iterator's {@link |
|
51 * java.util.Iterator#remove() remove} method removes the directory entry for |
|
52 * the last element returned by the iterator. In the case of a {@code |
|
53 * SecureDirectoryStream} the {@code remove} method behaves as if by invoking |
|
54 * the {@link #deleteFile deleteFile} or {@link #deleteDirectory deleteDirectory} |
|
55 * methods defined by this interface. The {@code remove} may require to examine |
|
56 * the file to determine if the file is a directory, and consequently, it may |
|
57 * not be atomic with respect to other file system operations. |
|
58 * |
|
59 * <p> In the case of the default {@link java.nio.file.spi.FileSystemProvider |
|
60 * provider}, and a security manager is set, then the permission checks are |
|
61 * performed using the path obtained by resolving the given relative path |
|
62 * against the <i>original path</i> of the directory (irrespective of if the |
|
63 * directory is moved since it was opened). |
|
64 * |
|
65 * @since 1.7 |
|
66 */ |
|
67 |
|
68 public abstract class SecureDirectoryStream |
|
69 implements DirectoryStream<Path> |
|
70 { |
|
71 /** |
|
72 * Initialize a new instance of this class. |
|
73 */ |
|
74 protected SecureDirectoryStream() { } |
|
75 |
|
76 /** |
|
77 * Opens the directory identified by the given path, returning a {@code |
|
78 * SecureDirectoryStream} to iterate over the entries in the directory. |
|
79 * |
|
80 * <p> This method works in exactly the manner specified by the {@link |
|
81 * Path#newDirectoryStream newDirectoryStream} method for the case that |
|
82 * the {@code path} parameter is an {@link Path#isAbsolute absolute} path. |
|
83 * When the parameter is a relative path then the directory to open is |
|
84 * relative to this open directory. The {@code followLinks} parameter |
|
85 * determines if links should be followed. If this parameter is {@code |
|
86 * false} and the file is a symbolic link then this method fails (by |
|
87 * throwing an I/O exception). |
|
88 * |
|
89 * <p> The new directory stream, once created, is not dependent upon the |
|
90 * directory stream used to create it. Closing this directory stream has no |
|
91 * effect upon newly created directory stream. |
|
92 * |
|
93 * @param path |
|
94 * The path to the directory to open |
|
95 * @param followLinks |
|
96 * {@code true} if the links should be followed |
|
97 * @param filter |
|
98 * The directory stream filter or {@code null}. |
|
99 * |
|
100 * @return A new and open {@code SecureDirectoryStream} object |
|
101 * |
|
102 * @throws ClosedDirectoryStreamException |
|
103 * If the directory stream is closed |
|
104 * @throws NotDirectoryException |
|
105 * If the file could not otherwise be opened because it is not |
|
106 * a directory <i>(optional specific exception)</i> |
|
107 * @throws IOException |
|
108 * If an I/O error occurs |
|
109 * @throws SecurityException |
|
110 * In the case of the default provider, and a security manager is |
|
111 * installed, the {@link SecurityManager#checkRead(String) checkRead} |
|
112 * method is invoked to check read access to the directory. |
|
113 */ |
|
114 public abstract SecureDirectoryStream newDirectoryStream(Path path, |
|
115 boolean followLinks, |
|
116 DirectoryStream.Filter<? super Path> filter) |
|
117 throws IOException; |
|
118 |
|
119 /** |
|
120 * Opens or creates a file in this directory, returning a seekable byte |
|
121 * channel to access the file. |
|
122 * |
|
123 * <p> This method works in exactly the manner specified by the {@link |
|
124 * Path#newByteChannel Path.newByteChannel} method for the |
|
125 * case that the {@code path} parameter is an {@link Path#isAbsolute absolute} |
|
126 * path. When the parameter is a relative path then the file to open or |
|
127 * create is relative to this open directory. In addition to the options |
|
128 * defined by the {@code Path.newByteChannel} method, the {@link |
|
129 * LinkOption#NOFOLLOW_LINKS NOFOLLOW_LINKS} option may be used to |
|
130 * ensure that this method fails if the file is a symbolic link. |
|
131 * |
|
132 * <p> The channel, once created, is not dependent upon the directory stream |
|
133 * used to create it. Closing this directory stream has no effect upon the |
|
134 * channel. |
|
135 * |
|
136 * @param path |
|
137 * The path of the file to open open or create |
|
138 * @param options |
|
139 * Options specifying how the file is opened |
|
140 * @param attrs |
|
141 * An optional list of attributes to set atomically when creating |
|
142 * the file |
|
143 * |
|
144 * @throws ClosedDirectoryStreamException |
|
145 * If the directory stream is closed |
|
146 * @throws IllegalArgumentException |
|
147 * If the set contains an invalid combination of options |
|
148 * @throws UnsupportedOperationException |
|
149 * If an unsupported open option is specified or the array contains |
|
150 * attributes that cannot be set atomically when creating the file |
|
151 * @throws FileAlreadyExistsException |
|
152 * If a file of that name already exists and the {@link |
|
153 * StandardOpenOption#CREATE_NEW CREATE_NEW} option is specified |
|
154 * <i>(optional specific exception)</i> |
|
155 * @throws IOException |
|
156 * If an I/O error occurs |
|
157 * @throws SecurityException |
|
158 * In the case of the default provider, and a security manager is |
|
159 * installed, the {@link SecurityManager#checkRead(String) checkRead} |
|
160 * method is invoked to check read access to the path if the file |
|
161 * is opened for reading. The {@link SecurityManager#checkWrite(String) |
|
162 * checkWrite} method is invoked to check write access to the path |
|
163 * if the file is opened for writing. |
|
164 */ |
|
165 public abstract SeekableByteChannel newByteChannel(Path path, |
|
166 Set<? extends OpenOption> options, |
|
167 FileAttribute<?>... attrs) |
|
168 throws IOException; |
|
169 |
|
170 /** |
|
171 * Deletes a file. |
|
172 * |
|
173 * <p> Unlike the {@link FileRef#delete delete()} method, this method |
|
174 * does not first examine the file to determine if the file is a directory. |
|
175 * Whether a directory is deleted by this method is system dependent and |
|
176 * therefore not specified. If the file is a symbolic-link then the link is |
|
177 * deleted (not the final target of the link). When the parameter is a |
|
178 * relative path then the file to delete is relative to this open directory. |
|
179 * |
|
180 * @param path |
|
181 * The path of the file to delete |
|
182 * |
|
183 * @throws ClosedDirectoryStreamException |
|
184 * If the directory stream is closed |
|
185 * @throws NoSuchFileException |
|
186 * If the the file does not exist <i>(optional specific exception)</i> |
|
187 * @throws IOException |
|
188 * If an I/O error occurs |
|
189 * @throws SecurityException |
|
190 * In the case of the default provider, and a security manager is |
|
191 * installed, the {@link SecurityManager#checkDelete(String) checkDelete} |
|
192 * method is invoked to check delete access to the file |
|
193 */ |
|
194 public abstract void deleteFile(Path path) throws IOException; |
|
195 |
|
196 /** |
|
197 * Deletes a directory. |
|
198 * |
|
199 * <p> Unlike the {@link FileRef#delete delete()} method, this method |
|
200 * does not first examine the file to determine if the file is a directory. |
|
201 * Whether non-directories are deleted by this method is system dependent and |
|
202 * therefore not specified. When the parameter is a relative path then the |
|
203 * directory to delete is relative to this open directory. |
|
204 * |
|
205 * @param path |
|
206 * The path of the directory to delete |
|
207 * |
|
208 * @throws ClosedDirectoryStreamException |
|
209 * If the directory stream is closed |
|
210 * @throws NoSuchFileException |
|
211 * If the the directory does not exist <i>(optional specific exception)</i> |
|
212 * @throws DirectoryNotEmptyException |
|
213 * If the directory could not otherwise be deleted because it is |
|
214 * not empty <i>(optional specific exception)</i> |
|
215 * @throws IOException |
|
216 * If an I/O error occurs |
|
217 * @throws SecurityException |
|
218 * In the case of the default provider, and a security manager is |
|
219 * installed, the {@link SecurityManager#checkDelete(String) checkDelete} |
|
220 * method is invoked to check delete access to the directory |
|
221 */ |
|
222 public abstract void deleteDirectory(Path path) throws IOException; |
|
223 |
|
224 /** |
|
225 * Move a file from this directory to another directory. |
|
226 * |
|
227 * <p> This method works in a similar manner to {@link Path#moveTo moveTo} |
|
228 * method when the {@link StandardCopyOption#ATOMIC_MOVE ATOMIC_MOVE} option |
|
229 * is specified. That is, this method moves a file as an atomic file system |
|
230 * operation. If the {@code srcpath} parameter is an {@link Path#isAbsolute |
|
231 * absolute} path then it locates the source file. If the parameter is a |
|
232 * relative path then it is located relative to this open directory. If |
|
233 * the {@code targetpath} parameter is absolute then it locates the target |
|
234 * file (the {@code targetdir} parameter is ignored). If the parameter is |
|
235 * a relative path it is located relative to the open directory identified |
|
236 * by the {@code targetdir} parameter. In all cases, if the target file |
|
237 * exists then it is implementation specific if it is replaced or this |
|
238 * method fails. |
|
239 * |
|
240 * @param srcpath |
|
241 * The name of the file to move |
|
242 * @param targetdir |
|
243 * The destination directory |
|
244 * @param targetpath |
|
245 * The name to give the file in the destination directory |
|
246 * |
|
247 * @throws ClosedDirectoryStreamException |
|
248 * If this or the target directory stream is closed |
|
249 * @throws FileAlreadyExistsException |
|
250 * The file already exists in the target directory and cannot |
|
251 * be replaced <i>(optional specific exception)</i> |
|
252 * @throws AtomicMoveNotSupportedException |
|
253 * The file cannot be moved as an atomic file system operation |
|
254 * @throws IOException |
|
255 * If an I/O error occurs |
|
256 * @throws SecurityException |
|
257 * In the case of the default provider, and a security manager is |
|
258 * installed, the {@link SecurityManager#checkWrite(String) checkWrite} |
|
259 * method is invoked to check write access to both the source and |
|
260 * target file. |
|
261 */ |
|
262 public abstract void move(Path srcpath, SecureDirectoryStream targetdir, Path targetpath) |
|
263 throws IOException; |
|
264 |
|
265 /** |
|
266 * Returns a new file attribute view to access the file attributes of this |
|
267 * directory. |
|
268 * |
|
269 * <p> The resulting file attribute view can be used to read or update the |
|
270 * attributes of this (open) directory. The {@code type} parameter specifies |
|
271 * the type of the attribute view and the method returns an instance of that |
|
272 * type if supported. Invoking this method to obtain a {@link |
|
273 * BasicFileAttributeView} always returns an instance of that class that is |
|
274 * bound to this open directory. |
|
275 * |
|
276 * <p> The state of resulting file attribute view is intimately connected |
|
277 * to this directory stream. Once the directory stream is {@link #close closed}, |
|
278 * then all methods to read or update attributes will throw {@link |
|
279 * ClosedDirectoryStreamException ClosedDirectoryStreamException}. |
|
280 * |
|
281 * @param type |
|
282 * The {@code Class} object corresponding to the file attribute view |
|
283 * |
|
284 * @return A new file attribute view of the specified type bound to |
|
285 * this directory stream, or {@code null} if the attribute view |
|
286 * type is not available |
|
287 */ |
|
288 public abstract <V extends FileAttributeView> V getFileAttributeView(Class<V> type); |
|
289 |
|
290 /** |
|
291 * Returns a new file attribute view to access the file attributes of a file |
|
292 * in this directory. |
|
293 * |
|
294 * <p> The resulting file attribute view can be used to read or update the |
|
295 * attributes of file in this directory. The {@code type} parameter specifies |
|
296 * the type of the attribute view and the method returns an instance of that |
|
297 * type if supported. Invoking this method to obtain a {@link |
|
298 * BasicFileAttributeView} always returns an instance of that class that is |
|
299 * bound to the file in the directory. |
|
300 * |
|
301 * <p> The state of resulting file attribute view is intimately connected |
|
302 * to this directory stream. Once the directory stream {@link #close closed}, |
|
303 * then all methods to read or update attributes will throw {@link |
|
304 * ClosedDirectoryStreamException ClosedDirectoryStreamException}. The |
|
305 * file is not required to exist at the time that the file attribute view |
|
306 * is created but methods to read or update attributes of the file will |
|
307 * fail when invoked and the file does not exist. |
|
308 * |
|
309 * @param path |
|
310 * The path of the file |
|
311 * @param type |
|
312 * The {@code Class} object corresponding to the file attribute view |
|
313 * @param options |
|
314 * Options indicating how symbolic links are handled |
|
315 * |
|
316 * @return A new file attribute view of the specified type bound to a |
|
317 * this directory stream, or {@code null} if the attribute view |
|
318 * type is not available |
|
319 * |
|
320 */ |
|
321 public abstract <V extends FileAttributeView> V getFileAttributeView(Path path, |
|
322 Class<V> type, |
|
323 LinkOption... options); |
|
324 } |