1 /* 2 * Copyright (c) 2007, 2013, Oracle and/or its affiliates. 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. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle 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 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. 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 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 Files#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> In the case of the default {@link java.nio.file.spi.FileSystemProvider 51 * provider}, and a security manager is set, then the permission checks are 52 * performed using the path obtained by resolving the given relative path 53 * against the <i>original path</i> of the directory (irrespective of if the 54 * directory is moved since it was opened). 55 * 56 * @since 1.7 57 */ 58 59 public interface SecureDirectoryStream<T> 60 extends DirectoryStream<T> 61 { 62 /** 63 * Opens the directory identified by the given path, returning a {@code 64 * SecureDirectoryStream} to iterate over the entries in the directory. 65 * 66 * <p> This method works in exactly the manner specified by the {@link 67 * Files#newDirectoryStream(Path) newDirectoryStream} method for the case that 68 * the {@code path} parameter is an {@link Path#isAbsolute absolute} path. 69 * When the parameter is a relative path then the directory to open is 70 * relative to this open directory. The {@link 71 * LinkOption#NOFOLLOW_LINKS NOFOLLOW_LINKS} option may be used to 72 * ensure that this method fails if the file is a symbolic link. 73 * 74 * <p> The new directory stream, once created, is not dependent upon the 75 * directory stream used to create it. Closing this directory stream has no 76 * effect upon newly created directory stream. 77 * 78 * @param path 79 * the path to the directory to open 80 * @param options 81 * options indicating how symbolic links are handled 82 * 83 * @return a new and open {@code SecureDirectoryStream} object 84 * 85 * @throws ClosedDirectoryStreamException 86 * if the directory stream is closed 87 * @throws NotDirectoryException 88 * if the file could not otherwise be opened because it is not 89 * a directory <i>(optional specific exception)</i> 90 * @throws IOException 91 * if an I/O error occurs 92 * @throws SecurityException 93 * In the case of the default provider, and a security manager is 94 * installed, the {@link SecurityManager#checkRead(String) checkRead} 95 * method is invoked to check read access to the directory. 96 */ 97 SecureDirectoryStream<T> newDirectoryStream(T path, LinkOption... options) 98 throws IOException; 99 100 /** 101 * Opens or creates a file in this directory, returning a seekable byte 102 * channel to access the file. 103 * 104 * <p> This method works in exactly the manner specified by the {@link 105 * Files#newByteChannel Files.newByteChannel} method for the 106 * case that the {@code path} parameter is an {@link Path#isAbsolute absolute} 107 * path. When the parameter is a relative path then the file to open or 108 * create is relative to this open directory. In addition to the options 109 * defined by the {@code Files.newByteChannel} method, the {@link 110 * LinkOption#NOFOLLOW_LINKS NOFOLLOW_LINKS} option may be used to 111 * ensure that this method fails if the file is a symbolic link. 112 * 113 * <p> The channel, once created, is not dependent upon the directory stream 114 * used to create it. Closing this directory stream has no effect upon the 115 * channel. 116 * 117 * @param path 118 * the path of the file to open open or create 119 * @param options 120 * options specifying how the file is opened 121 * @param attrs 122 * an optional list of attributes to set atomically when creating 123 * the file 124 * 125 * @return the seekable byte channel 126 * 127 * @throws ClosedDirectoryStreamException 128 * if the directory stream is closed 129 * @throws IllegalArgumentException 130 * if the set contains an invalid combination of options 131 * @throws UnsupportedOperationException 132 * if an unsupported open option is specified or the array contains 133 * attributes that cannot be set atomically when creating the file 134 * @throws FileAlreadyExistsException 135 * if a file of that name already exists and the {@link 136 * StandardOpenOption#CREATE_NEW CREATE_NEW} option is specified 137 * <i>(optional specific exception)</i> 138 * @throws IOException 139 * if an I/O error occurs 140 * @throws SecurityException 141 * In the case of the default provider, and a security manager is 142 * installed, the {@link SecurityManager#checkRead(String) checkRead} 143 * method is invoked to check read access to the path if the file 144 * is opened for reading. The {@link SecurityManager#checkWrite(String) 145 * checkWrite} method is invoked to check write access to the path 146 * if the file is opened for writing. 147 */ 148 SeekableByteChannel newByteChannel(T path, 149 Set<? extends OpenOption> options, 150 FileAttribute<?>... attrs) 151 throws IOException; 152 153 /** 154 * Deletes a file. 155 * 156 * <p> Unlike the {@link Files#delete delete()} method, this method does 157 * not first examine the file to determine if the file is a directory. 158 * Whether a directory is deleted by this method is system dependent and 159 * therefore not specified. If the file is a symbolic link, then the link 160 * itself, not the final target of the link, is deleted. When the 161 * parameter is a relative path then the file to delete is relative to 162 * this open directory. 163 * 164 * @param path 165 * the path of the file to delete 166 * 167 * @throws ClosedDirectoryStreamException 168 * if the directory stream is closed 169 * @throws NoSuchFileException 170 * if the file does not exist <i>(optional specific exception)</i> 171 * @throws IOException 172 * if an I/O error occurs 173 * @throws SecurityException 174 * In the case of the default provider, and a security manager is 175 * installed, the {@link SecurityManager#checkDelete(String) checkDelete} 176 * method is invoked to check delete access to the file 177 */ 178 void deleteFile(T path) throws IOException; 179 180 /** 181 * Deletes a directory. 182 * 183 * <p> Unlike the {@link Files#delete delete()} method, this method 184 * does not first examine the file to determine if the file is a directory. 185 * Whether non-directories are deleted by this method is system dependent and 186 * therefore not specified. When the parameter is a relative path then the 187 * directory to delete is relative to this open directory. 188 * 189 * @param path 190 * the path of the directory to delete 191 * 192 * @throws ClosedDirectoryStreamException 193 * if the directory stream is closed 194 * @throws NoSuchFileException 195 * if the directory does not exist <i>(optional specific exception)</i> 196 * @throws DirectoryNotEmptyException 197 * if the directory could not otherwise be deleted because it is 198 * not empty <i>(optional specific exception)</i> 199 * @throws IOException 200 * if an I/O error occurs 201 * @throws SecurityException 202 * In the case of the default provider, and a security manager is 203 * installed, the {@link SecurityManager#checkDelete(String) checkDelete} 204 * method is invoked to check delete access to the directory 205 */ 206 void deleteDirectory(T path) throws IOException; 207 208 /** 209 * Move a file from this directory to another directory. 210 * 211 * <p> This method works in a similar manner to {@link Files#move move} 212 * method when the {@link StandardCopyOption#ATOMIC_MOVE ATOMIC_MOVE} option 213 * is specified. That is, this method moves a file as an atomic file system 214 * operation. If the {@code srcpath} parameter is an {@link Path#isAbsolute 215 * absolute} path then it locates the source file. If the parameter is a 216 * relative path then it is located relative to this open directory. If 217 * the {@code targetpath} parameter is absolute then it locates the target 218 * file (the {@code targetdir} parameter is ignored). If the parameter is 219 * a relative path it is located relative to the open directory identified 220 * by the {@code targetdir} parameter. In all cases, if the target file 221 * exists then it is implementation specific if it is replaced or this 222 * method fails. 223 * 224 * @param srcpath 225 * the name of the file to move 226 * @param targetdir 227 * the destination directory 228 * @param targetpath 229 * the name to give the file in the destination directory 230 * 231 * @throws ClosedDirectoryStreamException 232 * if this or the target directory stream is closed 233 * @throws FileAlreadyExistsException 234 * if the file already exists in the target directory and cannot 235 * be replaced <i>(optional specific exception)</i> 236 * @throws AtomicMoveNotSupportedException 237 * if the file cannot be moved as an atomic file system operation 238 * @throws IOException 239 * if an I/O error occurs 240 * @throws SecurityException 241 * In the case of the default provider, and a security manager is 242 * installed, the {@link SecurityManager#checkWrite(String) checkWrite} 243 * method is invoked to check write access to both the source and 244 * target file. 245 */ 246 void move(T srcpath, SecureDirectoryStream<T> targetdir, T targetpath) 247 throws IOException; 248 249 /** 250 * Returns a new file attribute view to access the file attributes of this 251 * directory. 252 * 253 * <p> The resulting file attribute view can be used to read or update the 254 * attributes of this (open) directory. The {@code type} parameter specifies 255 * the type of the attribute view and the method returns an instance of that 256 * type if supported. Invoking this method to obtain a {@link 257 * BasicFileAttributeView} always returns an instance of that class that is 258 * bound to this open directory. 259 * 260 * <p> The state of resulting file attribute view is intimately connected 261 * to this directory stream. Once the directory stream is {@link #close closed}, 262 * then all methods to read or update attributes will throw {@link 263 * ClosedDirectoryStreamException ClosedDirectoryStreamException}. 264 * 265 * @param <V> 266 * The {@code FileAttributeView} type 267 * @param type 268 * the {@code Class} object corresponding to the file attribute view 269 * 270 * @return a new file attribute view of the specified type bound to 271 * this directory stream, or {@code null} if the attribute view 272 * type is not available 273 */ 274 <V extends FileAttributeView> V getFileAttributeView(Class<V> type); 275 276 /** 277 * Returns a new file attribute view to access the file attributes of a file 278 * in this directory. 279 * 280 * <p> The resulting file attribute view can be used to read or update the 281 * attributes of file in this directory. The {@code type} parameter specifies 282 * the type of the attribute view and the method returns an instance of that 283 * type if supported. Invoking this method to obtain a {@link 284 * BasicFileAttributeView} always returns an instance of that class that is 285 * bound to the file in the directory. 286 * 287 * <p> The state of resulting file attribute view is intimately connected 288 * to this directory stream. Once the directory stream {@link #close closed}, 289 * then all methods to read or update attributes will throw {@link 290 * ClosedDirectoryStreamException ClosedDirectoryStreamException}. The 291 * file is not required to exist at the time that the file attribute view 292 * is created but methods to read or update attributes of the file will 293 * fail when invoked and the file does not exist. 294 * 295 * @param <V> 296 * The {@code FileAttributeView} type 297 * @param path 298 * the path of the file 299 * @param type 300 * the {@code Class} object corresponding to the file attribute view 301 * @param options 302 * options indicating how symbolic links are handled 303 * 304 * @return a new file attribute view of the specified type bound to a 305 * this directory stream, or {@code null} if the attribute view 306 * type is not available 307 * 308 */ 309 <V extends FileAttributeView> V getFileAttributeView(T path, 310 Class<V> type, 311 LinkOption... options); 312 } 313
