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 "Classpath" 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 26 package java.nio.file; 27 28 import java.nio.file.attribute.*; 29 import java.util.Map; 30 import java.io.InputStream; 31 import java.io.OutputStream; 32 import java.io.IOException; 33 34 /** 35 * A reference to a file. 36 * 37 * <p> A {@code FileRef} is an object that locates a file and defines methods to 38 * open the file for reading or writing. It also provides access to associated 39 * metadata or file attributes. 40 * 41 * @since 1.7 42 * @see java.nio.file.attribute.Attributes 43 * @see java.io.File#toPath 44 */ 45 46 public interface FileRef { 47 48 /** 49 * Opens the file referenced by this object, returning an input stream to 50 * read from the file. The stream will not be buffered, and is not required 51 * to support the {@link InputStream#mark mark} or {@link InputStream#reset 52 * reset} methods. The stream will be safe for access by multiple concurrent 53 * threads. Reading commences at the beginning of the file. 54 * 55 * <p> The {@code options} parameter determines how the file is opened. 56 * If no options are present then it is equivalent to opening the file with 57 * the {@link StandardOpenOption#READ READ} option. In addition to the {@code 58 * READ} option, an implementation may also support additional implementation 59 * specific options. 60 * 61 * @return an input stream to read bytes from the file 62 * 63 * @throws IllegalArgumentException 64 * if an invalid combination of options is specified 65 * @throws UnsupportedOperationException 66 * if an unsupported option is specified 67 * @throws IOException 68 * if an I/O error occurs 69 * @throws SecurityException 70 * In the case of the default provider, and a security manager is 71 * installed, the {@link SecurityManager#checkRead(String) checkRead} 72 * method is invoked to check read access to the file. 73 */ 74 InputStream newInputStream(OpenOption... options) throws IOException; 75 76 /** 77 * Opens or creates the file located by this object for writing, returning 78 * an output stream to write bytes to the file. 79 * 80 * <p> The {@code options} parameter determines how the file is opened. 81 * If no options are present then this method creates a new file for writing 82 * or truncates an existing file. In addition to the {@link StandardOpenOption 83 * standard} options, an implementation may also support additional 84 * implementation specific options. 85 * 86 * <p> The resulting stream will not be buffered. The stream will be safe 87 * for access by multiple concurrent threads. 88 * 89 * @param options 90 * options specifying how the file is opened 91 * 92 * @return a new output stream 93 * 94 * @throws IllegalArgumentException 95 * if {@code options} contains an invalid combination of options 96 * @throws UnsupportedOperationException 97 * if an unsupported option is specified 98 * @throws IOException 99 * if an I/O error occurs 100 * @throws SecurityException 101 * In the case of the default provider, and a security manager is 102 * installed, the {@link SecurityManager#checkWrite(String) checkWrite} 103 * method is invoked to check write access to the file. 104 */ 105 OutputStream newOutputStream(OpenOption... options) throws IOException; 106 107 /** 108 * Returns a file attribute view of a given type. 109 * 110 * <p> A file attribute view provides a read-only or updatable view of a 111 * set of file attributes. This method is intended to be used where the file 112 * attribute view defines type-safe methods to read or update the file 113 * attributes. The {@code type} parameter is the type of the attribute view 114 * required and the method returns an instance of that type if supported. 115 * The {@link BasicFileAttributeView} type supports access to the basic 116 * attributes of a file. Invoking this method to select a file attribute 117 * view of that type will always return an instance of that class. 118 * 119 * <p> The {@code options} array may be used to indicate how symbolic links 120 * are handled by the resulting file attribute view for the case that the 121 * file is a symbolic link. By default, symbolic links are followed. If the 122 * option {@link LinkOption#NOFOLLOW_LINKS NOFOLLOW_LINKS} is present then 123 * symbolic links are not followed. This option is ignored by implementations 124 * that do not support symbolic links. 125 * 126 * @param type 127 * the {@code Class} object corresponding to the file attribute view 128 * @param options 129 * options indicating how symbolic links are handled 130 * 131 * @return a file attribute view of the specified type, or {@code null} if 132 * the attribute view type is not available 133 * 134 * @throws UnsupportedOperationException 135 * If options contains an unsupported option. This exception is 136 * specified to allow the {@code LinkOption} enum be extended 137 * in future releases. 138 * 139 * @see Attributes#readBasicFileAttributes 140 */ 141 <V extends FileAttributeView> V getFileAttributeView(Class<V> type, 142 LinkOption... options); 143 144 /** 145 * Sets the value of a file attribute. 146 * 147 * <p> The {@code attribute} parameter identifies the attribute to be set 148 * and takes the form: 149 * <blockquote> 150 * [<i>view-name</i><b>:</b>]<i>attribute-name</i> 151 * </blockquote> 152 * where square brackets [...] delineate an optional component and the 153 * character {@code ':'} stands for itself. 154 * 155 * <p> <i>view-name</i> is the {@link FileAttributeView#name name} of a {@link 156 * FileAttributeView} that identifies a set of file attributes. If not 157 * specified then it defaults to {@code "basic"}, the name of the file 158 * attribute view that identifies the basic set of file attributes common to 159 * many file systems. <i>attribute-name</i> is the name of the attribute 160 * within the set. 161 * 162 * <p> <b>Usage Example:</b> 163 * Suppose we want to set the DOS "hidden" attribute: 164 * <pre> 165 * file.setAttribute("dos:hidden", true); 166 * </pre> 167 * 168 * @param attribute 169 * the attribute to set 170 * @param value 171 * the attribute value 172 * @param options 173 * options indicating how symbolic links are handled 174 * 175 * @throws UnsupportedOperationException 176 * if the attribute view is not available or it does not support 177 * updating the attribute 178 * @throws IllegalArgumentException 179 * if the attribute value is of the correct type but has an 180 * inappropriate value 181 * @throws ClassCastException 182 * If the attribute value is not of the expected type or is a 183 * collection containing elements that are not of the expected 184 * type 185 * @throws IOException 186 * If an I/O error occurs 187 * @throws SecurityException 188 * In the case of the default provider, and a security manager is 189 * installed, its {@link SecurityManager#checkWrite(String) checkWrite} 190 * method denies write access to the file. If this method is invoked 191 * to set security sensitive attributes then the security manager 192 * may be invoked to check for additional permissions. 193 */ 194 void setAttribute(String attribute, Object value, LinkOption... options) 195 throws IOException; 196 197 /** 198 * Reads the value of a file attribute. 199 * 200 * <p> The {@code attribute} parameter identifies the attribute to be read 201 * and takes the form: 202 * <blockquote> 203 * [<i>view-name</i><b>:</b>]<i>attribute-name</i> 204 * </blockquote> 205 * where square brackets [...] delineate an optional component and the 206 * character {@code ':'} stands for itself. 207 * 208 * <p> <i>view-name</i> is the {@link FileAttributeView#name name} of a {@link 209 * FileAttributeView} that identifies a set of file attributes. If not 210 * specified then it defaults to {@code "basic"}, the name of the file 211 * attribute view that identifies the basic set of file attributes common to 212 * many file systems. <i>attribute-name</i> is the name of the attribute. 213 * 214 * <p> The {@code options} array may be used to indicate how symbolic links 215 * are handled for the case that the file is a symbolic link. By default, 216 * symbolic links are followed and the file attribute of the final target 217 * of the link is read. If the option {@link LinkOption#NOFOLLOW_LINKS 218 * NOFOLLOW_LINKS} is present then symbolic links are not followed and so 219 * the method returns the file attribute of the symbolic link. 220 * 221 * <p> <b>Usage Example:</b> 222 * Suppose we require the user ID of the file owner on a system that 223 * supports a "{@code unix}" view: 224 * <pre> 225 * int uid = (Integer)file.getAttribute("unix:uid"); 226 * </pre> 227 * 228 * @param attribute 229 * the attribute to read 230 * @param options 231 * options indicating how symbolic links are handled 232 * @return the attribute value or {@code null} if the attribute view 233 * is not available or it does not support reading the attribute 234 * 235 * reading the attribute 236 * @throws IOException 237 * if an I/O error occurs 238 * @throws SecurityException 239 * In the case of the default provider, and a security manager is 240 * installed, its {@link SecurityManager#checkRead(String) checkRead} 241 * method denies read access to the file. If this method is invoked 242 * to read security sensitive attributes then the security manager 243 * may be invoked to check for additional permissions. 244 */ 245 Object getAttribute(String attribute, LinkOption... options) throws IOException; 246 247 /** 248 * Reads a set of file attributes as a bulk operation. 249 * 250 * <p> The {@code attributes} parameter identifies the attributes to be read 251 * and takes the form: 252 * <blockquote> 253 * [<i>view-name</i><b>:</b>]<i>attribute-list</i> 254 * </blockquote> 255 * where square brackets [...] delineate an optional component and the 256 * character {@code ':'} stands for itself. 257 * 258 * <p> <i>view-name</i> is the {@link FileAttributeView#name name} of a {@link 259 * FileAttributeView} that identifies a set of file attributes. If not 260 * specified then it defaults to {@code "basic"}, the name of the file 261 * attribute view that identifies the basic set of file attributes common to 262 * many file systems. 263 * 264 * <p> The <i>attribute-list</i> component is a comma separated list of 265 * zero or more names of attributes to read. If the list contains the value 266 * {@code "*"} then all attributes are read. Attributes that are not supported 267 * are ignored and will not be present in the returned map. It is 268 * implementation specific if all attributes are read as an atomic operation 269 * with respect to other file system operations. 270 * 271 * <p> The following examples demonstrate possible values for the {@code 272 * attributes} parameter: 273 * 274 * <blockquote> 275 * <table border="0"> 276 * <tr> 277 * <td> {@code "*"} </td> 278 * <td> Read all {@link BasicFileAttributes basic-file-attributes}. </td> 279 * </tr> 280 * <tr> 281 * <td> {@code "size,lastModifiedTime,lastAccessTime"} </td> 282 * <td> Reads the file size, last modified time, and last access time 283 * attributes. </td> 284 * </tr> 285 * <tr> 286 * <td> {@code "posix:*"} </td> 287 * <td> Read all {@link PosixFileAttributes POSIX-file-attributes}.. </td> 288 * </tr> 289 * <tr> 290 * <td> {@code "posix:permissions,owner,size"} </td> 291 * <td> Reads the POSX file permissions, owner, and file size. </td> 292 * </tr> 293 * </table> 294 * </blockquote> 295 * 296 * <p> The {@code options} array may be used to indicate how symbolic links 297 * are handled for the case that the file is a symbolic link. By default, 298 * symbolic links are followed and the file attribute of the final target 299 * of the link is read. If the option {@link LinkOption#NOFOLLOW_LINKS 300 * NOFOLLOW_LINKS} is present then symbolic links are not followed and so 301 * the method returns the file attribute of the symbolic link. 302 * 303 * @param attributes 304 * The attributes to read 305 * @param options 306 * Options indicating how symbolic links are handled 307 * 308 * @return A map of the attributes returned; may be empty. The map's keys 309 * are the attribute names, its values are the attribute values 310 * 311 * @throws IOException 312 * If an I/O error occurs 313 * @throws SecurityException 314 * In the case of the default provider, and a security manager is 315 * installed, its {@link SecurityManager#checkRead(String) checkRead} 316 * method denies read access to the file. If this method is invoked 317 * to read security sensitive attributes then the security manager 318 * may be invoke to check for additional permissions. 319 */ 320 Map<String,?> readAttributes(String attributes, LinkOption... options) 321 throws IOException; 322 }