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.attribute;
27
28 import java.nio.file.*;
29 import java.io.IOException;
30 import java.util.*;
31
32 /**
33 * This class consists exclusively of static methods that operate on or return
34 * the attributes of files or file stores. These methods provide for convenient
35 * use of the {@link AttributeView attribute-views} defined in this package.
36 *
37 * @since 1.7
38 */
39
40 public final class Attributes {
41 private Attributes() { }
42
43 /**
44 * Reads the basic file attributes of a file.
45 *
46 * <p> The {@code options} array may be used to indicate how symbolic links
47 * are handled for the case that the file is a symbolic link. By default,
48 * symbolic links are followed and the file attributes of the final target
49 * of the link are read. If the option {@link LinkOption#NOFOLLOW_LINKS
50 * NOFOLLOW_LINKS} is present then symbolic links are not followed and so
51 * the method returns the file attributes of the symbolic link itself.
52 * This option should be used where there is a need to determine if a
53 * file is a symbolic link:
54 * <pre>
55 * boolean isSymbolicLink = Attributes.readBasicFileAttributes(file, NOFOLLOW_LINKS).isSymbolicLink();
56 * </pre>
57 *
58 * <p> It is implementation specific if all file attributes are read as an
59 * atomic operation with respect to other file system operations.
60 *
61 * @param file
62 * A file reference that locates the file
63 * @param options
64 * Options indicating how symbolic links are handled
65 *
66 * @return The basic file attributes
67 *
68 * @throws IOException
69 * If an I/O error occurs
70 * @throws SecurityException
71 * In the case of the default provider, the security manager's {@link
72 * SecurityManager#checkRead(String) checkRead} method is invoked
73 * to check read access to file
74 *
75 * @see BasicFileAttributeView#readAttributes
76 */
77 public static BasicFileAttributes readBasicFileAttributes(FileRef file,
78 LinkOption... options)
79 throws IOException
80 {
81 return file.getFileAttributeView(BasicFileAttributeView.class, options)
82 .readAttributes();
83 }
84
85 /**
86 * Reads the POSIX file attributes of a file.
87 *
88 * <p> The {@code file} parameter locates a file that supports the {@link
89 * PosixFileAttributeView}. This file attribute view provides access to a
90 * subset of the file attributes commonly associated with files on file
91 * systems used by operating systems that implement the Portable Operating
92 * System Interface (POSIX) family of standards. It is implementation
93 * specific if all file attributes are read as an atomic operation with
94 * respect to other file system operations.
95 *
96 * <p> The {@code options} array may be used to indicate how symbolic links
97 * are handled for the case that the file is a symbolic link. By default,
98 * symbolic links are followed and the file attributes of the final target
99 * of the link are read. If the option {@link LinkOption#NOFOLLOW_LINKS
100 * NOFOLLOW_LINKS} is present then symbolic links are not followed and so
101 * the method returns the file attributes of the symbolic link itself.
102 *
103 * @param file
104 * A file reference that locates the file
105 * @param options
106 * Options indicating how symbolic links are handled
107 *
108 * @return The POSIX file attributes
109 *
110 * @throws UnsupportedOperationException
111 * If the {@code PosixFileAttributeView} is not available
112 * @throws IOException
113 * If an I/O error occurs
114 * @throws SecurityException
115 * In the case of the default provider, and a security manager is
116 * installed, it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt>
117 * or its {@link SecurityManager#checkRead(String) checkRead} method
118 * denies read access to the file.
119 *
120 * @see PosixFileAttributeView#readAttributes
121 */
122 public static PosixFileAttributes readPosixFileAttributes(FileRef file,
123 LinkOption... options)
124 throws IOException
125 {
126 PosixFileAttributeView view =
127 file.getFileAttributeView(PosixFileAttributeView.class, options);
128 if (view == null)
129 throw new UnsupportedOperationException();
130 return view.readAttributes();
131 }
132
133 /**
134 * Reads the DOS file attributes of a file.
135 *
136 * <p> The {@code file} parameter locates a file that supports the {@link
137 * DosFileAttributeView}. This file attribute view provides access to
138 * legacy "DOS" attributes supported by the file systems such as File
139 * Allocation Table (FAT), commonly used in <em>consumer devices</em>. It is
140 * implementation specific if all file attributes are read as an atomic
141 * operation with respect to other file system operations.
142 *
143 * <p> The {@code options} array may be used to indicate how symbolic links
144 * are handled for the case that the file is a symbolic link. By default,
145 * symbolic links are followed and the file attributes of the final target
146 * of the link are read. If the option {@link LinkOption#NOFOLLOW_LINKS
147 * NOFOLLOW_LINKS} is present then symbolic links are not followed and so
148 * the method returns the file attributes of the symbolic link itself.
149 *
150 * @param file
151 * A file reference that locates the file
152 * @param options
153 * Options indicating how symbolic links are handled
154 *
155 * @return The DOS file attributes
156 *
157 * @throws UnsupportedOperationException
158 * If the {@code DosFileAttributeView} is not available
159 * @throws IOException
160 * If an I/O error occurs
161 * @throws SecurityException
162 * In the case of the default provider, the security manager's {@link
163 * SecurityManager#checkRead(String) checkRead} method is invoked
164 * to check read access to file
165 *
166 * @see DosFileAttributeView#readAttributes
167 */
168 public static DosFileAttributes readDosFileAttributes(FileRef file,
169 LinkOption... options)
170 throws IOException
171 {
172 DosFileAttributeView view =
173 file.getFileAttributeView(DosFileAttributeView.class, options);
174 if (view == null)
175 throw new UnsupportedOperationException();
176 return view.readAttributes();
177 }
178
179 /**
180 * Returns the owner of a file.
181 *
182 * <p> The {@code file} parameter locates a file that supports the {@link
183 * FileOwnerAttributeView}. This file attribute view provides access to
184 * a file attribute that is the owner of the file.
185 *
186 * @param file
187 * A file reference that locates the file
188 *
189 * @return A user principal representing the owner of the file
190 *
191 * @throws UnsupportedOperationException
192 * If the {@code FileOwnerAttributeView} is not available
193 * @throws IOException
194 * If an I/O error occurs
195 * @throws SecurityException
196 * In the case of the default provider, and a security manager is
197 * installed, it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt>
198 * or its {@link SecurityManager#checkRead(String) checkRead} method
199 * denies read access to the file.
200 *
201 * @see FileOwnerAttributeView#getOwner
202 */
203 public static UserPrincipal getOwner(FileRef file) throws IOException {
204 FileOwnerAttributeView view =
205 file.getFileAttributeView(FileOwnerAttributeView.class);
206 if (view == null)
207 throw new UnsupportedOperationException();
208 return view.getOwner();
209 }
210
211 /**
212 * Updates the file owner.
213 *
214 * <p> The {@code file} parameter locates a file that supports the {@link
215 * FileOwnerAttributeView}. This file attribute view provides access to
216 * a file attribute that is the owner of the file.
217 *
218 * @param file
219 * A file reference that locates the file
220 * @param owner
221 * The new file owner
222 *
223 * @throws UnsupportedOperationException
224 * If the {@code FileOwnerAttributeView} is not available
225 * @throws IOException
226 * If an I/O error occurs
227 * @throws SecurityException
228 * In the case of the default provider, and a security manager is
229 * installed, it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt>
230 * or its {@link SecurityManager#checkWrite(String) checkWrite}
231 * method denies write access to the file.
232 *
233 * @see FileOwnerAttributeView#setOwner
234 */
235 public static void setOwner(FileRef file, UserPrincipal owner)
236 throws IOException
237 {
238 FileOwnerAttributeView view =
239 file.getFileAttributeView(FileOwnerAttributeView.class);
240 if (view == null)
241 throw new UnsupportedOperationException();
242 view.setOwner(owner);
243 }
244
245 /**
246 * Reads a file's Access Control List (ACL).
247 *
248 * <p> The {@code file} parameter locates a file that supports the {@link
249 * AclFileAttributeView}. This file attribute view provides access to ACLs
250 * based on the ACL model specified in
251 * <a href="http://www.ietf.org/rfc/rfc3530.txt"><i>RFC 3530</i></a>.
252 *
253 * @param file
254 * A file reference that locates the file
255 *
256 * @return An ordered list of {@link AclEntry entries} representing the
257 * ACL. The returned list is modifiable.
258 *
259 * @throws UnsupportedOperationException
260 * If the {@code AclAttributeView} is not available
261 * @throws IOException
262 * If an I/O error occurs
263 * @throws SecurityException
264 * In the case of the default provider, and a security manager is
265 * installed, it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt>
266 * or its {@link SecurityManager#checkRead(String) checkRead} method
267 * denies read access to the file.
268 *
269 * @see AclFileAttributeView#getAcl
270 */
271 public static List<AclEntry> getAcl(FileRef file) throws IOException {
272 AclFileAttributeView view =
273 file.getFileAttributeView(AclFileAttributeView.class);
274 if (view == null)
275 throw new UnsupportedOperationException();
276 return view.getAcl();
277 }
278
279 /**
280 * Updates a file's Access Control List (ACL).
281 *
282 * <p> The {@code file} parameter locates a file that supports the {@link
283 * AclFileAttributeView}. This file attribute view provides access to ACLs
284 * based on the ACL model specified in
285 * <a href="http://www.ietf.org/rfc/rfc3530.txt"><i>RFC 3530</i></a>.
286 *
287 * @param file
288 * A file reference that locates the file
289 * @param acl
290 * The new file ACL
291 *
292 * @throws UnsupportedOperationException
293 * If the {@code AclFileAttributeView} is not available
294 * @throws IOException
295 * If an I/O error occurs
296 * @throws SecurityException
297 * In the case of the default provider, and a security manager is
298 * installed, it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt>
299 * or its {@link SecurityManager#checkWrite(String) checkWrite}
300 * method denies write access to the file.
301 *
302 * @see AclFileAttributeView#setAcl
303 */
304 public static void setAcl(FileRef file, List<AclEntry> acl)
305 throws IOException
306 {
307 AclFileAttributeView view =
308 file.getFileAttributeView(AclFileAttributeView.class);
309 if (view == null)
310 throw new UnsupportedOperationException();
311 view.setAcl(acl);
312 }
313
314 /**
315 * Updates a file's last modified time attribute. The file time is converted
316 * to the epoch and precision supported by the file system. Converting from
317 * finer to coarser granularities result in precision loss. The behavior of
318 * this method when attempting to set a timestamp to a value that is outside
319 * the range supported by the underlying file store is not defined. It may
320 * or not fail by throwing an {@code IOException}.
321 *
322 * <p> If the file system does not support a last modified time attribute
323 * then this method has no effect.
324 *
325 * <p> <b>Usage Example:</b>
326 * Suppose we want to set the last modified time to the current time:
327 * <pre>
328 * FileTime now = FileTime.fromMillis(System.currentTimeMillis());
329 * Attributes.setLastModifiedTime(file, now);
330 * </pre>
331 *
332 * @param file
333 * A file reference that locates the file
334 * @param lastModifiedTime
335 * The new last modified time
336 *
337 * @throws IOException
338 * If an I/O error occurs
339 * @throws SecurityException
340 * In the case of the default provider, the security manager's {@link
341 * SecurityManager#checkWrite(String) checkWrite} method is invoked
342 * to check write access to file
343 *
344 * @see BasicFileAttributeView#setTimes
345 */
346 public static void setLastModifiedTime(FileRef file,
347 FileTime lastModifiedTime)
348 throws IOException
349 {
350 if (lastModifiedTime == null)
351 throw new NullPointerException("'lastModifiedTime' is null");
352 file.getFileAttributeView(BasicFileAttributeView.class)
353 .setTimes(lastModifiedTime, null, null);
354 }
355
356 /**
357 * Updates a file's last access time attribute. The file time is converted
358 * to the epoch and precision supported by the file system. Converting from
359 * finer to coarser granularities result in precision loss. The behavior of
360 * this method when attempting to set a timestamp to a value that is outside
361 * the range supported by the underlying file store is not defined. It may
362 * or not fail by throwing an {@code IOException}.
363 *
364 * <p> If the file system does not support a last access time attribute then
365 * this method has no effect.
366 *
367 * @param file
368 * A file reference that locates the file
369 * @param lastAccessTime
370 * The new last access time
371 *
372 * @throws IOException
373 * If an I/O error occurs
374 * @throws SecurityException
375 * In the case of the default provider, the security manager's {@link
376 * SecurityManager#checkWrite(String) checkWrite} method is invoked
377 * to check write access to file
378 *
379 * @see BasicFileAttributeView#setTimes
380 */
381 public static void setLastAccessTime(FileRef file,
382 FileTime lastAccessTime)
383 throws IOException
384 {
385 if (lastAccessTime == null)
386 throw new NullPointerException("'lastAccessTime' is null");
387 file.getFileAttributeView(BasicFileAttributeView.class)
388 .setTimes(null, lastAccessTime, null);
389 }
390
391 /**
392 * Sets a file's POSIX permissions.
393 *
394 * <p> The {@code file} parameter is a reference to an existing file. It
395 * supports the {@link PosixFileAttributeView} that provides access to file
396 * attributes commonly associated with files on file systems used by
397 * operating systems that implement the Portable Operating System Interface
398 * (POSIX) family of standards.
399 *
400 * @param file
401 * A file reference that locates the file
402 * @param perms
403 * The new set of permissions
404 *
405 * @throws UnsupportedOperationException
406 * If {@code PosixFileAttributeView} is not available
407 * @throws ClassCastException
408 * If the sets contains elements that are not of type {@code
409 * PosixFilePermission}
410 * @throws IOException
411 * If an I/O error occurs
412 * @throws SecurityException
413 * In the case of the default provider, and a security manager is
414 * installed, it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt>
415 * or its {@link SecurityManager#checkWrite(String) checkWrite}
416 * method denies write access to the file.
417 *
418 * @see PosixFileAttributeView#setPermissions
419 */
420 public static void setPosixFilePermissions(FileRef file,
421 Set<PosixFilePermission> perms)
422 throws IOException
423 {
424 PosixFileAttributeView view =
425 file.getFileAttributeView(PosixFileAttributeView.class);
426 if (view == null)
427 throw new UnsupportedOperationException();
428 view.setPermissions(perms);
429 }
430
431 /**
432 * Reads the space attributes of a file store.
433 *
434 * <p> The {@code store} parameter is a file store that supports the
435 * {@link FileStoreSpaceAttributeView} providing access to the space related
436 * attributes of the file store. It is implementation specific if all attributes
437 * are read as an atomic operation with respect to other file system operations.
438 *
439 * @param store
440 * The file store
441 *
442 * @return The file store space attributes
443 *
444 * @throws UnsupportedOperationException
445 * If the file store space attribute view is not supported
446 * @throws IOException
447 * If an I/O error occurs
448 *
449 * @see FileStoreSpaceAttributeView#readAttributes()
450 */
451 public static FileStoreSpaceAttributes readFileStoreSpaceAttributes(FileStore store)
452 throws IOException
453 {
454 FileStoreSpaceAttributeView view =
455 store.getFileStoreAttributeView(FileStoreSpaceAttributeView.class);
456 if (view == null)
457 throw new UnsupportedOperationException();
458 return view.readAttributes();
459 }
460 }