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