1 /* |
|
2 * Copyright (c) 2007, 2009, 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 |
|
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 } |
|