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 26 package java.nio.file.attribute; 27 28 import java.io.IOException; 29 30 /** 31 * A file attribute view that provides a view of a <em>basic set</em> of file 32 * attributes common to many file systems. The basic set of file attributes 33 * consist of <em>mandatory</em> and <em>optional</em> file attributes as 34 * defined by the {@link BasicFileAttributes} interface. 35 36 * <p> The file attributes are retrieved from the file system as a <em>bulk 37 * operation</em> by invoking the {@link #readAttributes() readAttributes} method. 38 * This class also defines the {@link #setTimes setTimes} method to update the 39 * file's time attributes. 40 * 41 * <p> Where dynamic access to file attributes is required, the attributes 42 * supported by this attribute view have the following names and types: 43 * <blockquote> 44 * <table border="1" cellpadding="8" summary="Supported attributes"> 45 * <tr> 46 * <th> Name </th> 47 * <th> Type </th> 48 * </tr> 49 * <tr> 50 * <td> "lastModifiedTime" </td> 51 * <td> {@link FileTime} </td> 52 * </tr> 53 * <tr> 54 * <td> "lastAccessTime" </td> 55 * <td> {@link FileTime} </td> 56 * </tr> 57 * <tr> 58 * <td> "creationTime" </td> 59 * <td> {@link FileTime} </td> 60 * </tr> 61 * <tr> 62 * <td> "size" </td> 63 * <td> {@link Long} </td> 64 * </tr> 65 * <tr> 66 * <td> "isRegularFile" </td> 67 * <td> {@link Boolean} </td> 68 * </tr> 69 * <tr> 70 * <td> "isDirectory" </td> 71 * <td> {@link Boolean} </td> 72 * </tr> 73 * <tr> 74 * <td> "isSymbolicLink" </td> 75 * <td> {@link Boolean} </td> 76 * </tr> 77 * <tr> 78 * <td> "isOther" </td> 79 * <td> {@link Boolean} </td> 80 * </tr> 81 * <tr> 82 * <td> "fileKey" </td> 83 * <td> {@link Object} </td> 84 * </tr> 85 * </table> 86 * </blockquote> 87 * 88 * <p> The {@link java.nio.file.Files#getAttribute getAttribute} method may be 89 * used to read any of these attributes as if by invoking the {@link 90 * #readAttributes() readAttributes()} method. 91 * 92 * <p> The {@link java.nio.file.Files#setAttribute setAttribute} method may be 93 * used to update the file's last modified time, last access time or create time 94 * attributes as if by invoking the {@link #setTimes setTimes} method. 95 * 96 * @since 1.7 97 */ 98 99 public interface BasicFileAttributeView 100 extends FileAttributeView 101 { 102 /** 103 * Returns the name of the attribute view. Attribute views of this type 104 * have the name {@code "basic"}. 105 */ 106 @Override name()107 String name(); 108 109 /** 110 * Reads the basic file attributes as a bulk operation. 111 * 112 * <p> It is implementation specific if all file attributes are read as an 113 * atomic operation with respect to other file system operations. 114 * 115 * @return the file attributes 116 * 117 * @throws IOException 118 * if an I/O error occurs 119 * @throws SecurityException 120 * In the case of the default provider, a security manager is 121 * installed, its {@link SecurityManager#checkRead(String) checkRead} 122 * method is invoked to check read access to the file 123 */ readAttributes()124 BasicFileAttributes readAttributes() throws IOException; 125 126 /** 127 * Updates any or all of the file's last modified time, last access time, 128 * and create time attributes. 129 * 130 * <p> This method updates the file's timestamp attributes. The values are 131 * converted to the epoch and precision supported by the file system. 132 * Converting from finer to coarser granularities result in precision loss. 133 * The behavior of this method when attempting to set a timestamp that is 134 * not supported or to a value that is outside the range supported by the 135 * underlying file store is not defined. It may or not fail by throwing an 136 * {@code IOException}. 137 * 138 * <p> If any of the {@code lastModifiedTime}, {@code lastAccessTime}, 139 * or {@code createTime} parameters has the value {@code null} then the 140 * corresponding timestamp is not changed. An implementation may require to 141 * read the existing values of the file attributes when only some, but not 142 * all, of the timestamp attributes are updated. Consequently, this method 143 * may not be an atomic operation with respect to other file system 144 * operations. Reading and re-writing existing values may also result in 145 * precision loss. If all of the {@code lastModifiedTime}, {@code 146 * lastAccessTime} and {@code createTime} parameters are {@code null} then 147 * this method has no effect. 148 * 149 * <p> <b>Usage Example:</b> 150 * Suppose we want to change a file's last access time. 151 * <pre> 152 * Path path = ... 153 * FileTime time = ... 154 * Files.getFileAttributeView(path, BasicFileAttributeView.class).setTimes(null, time, null); 155 * </pre> 156 * 157 * @param lastModifiedTime 158 * the new last modified time, or {@code null} to not change the 159 * value 160 * @param lastAccessTime 161 * the last access time, or {@code null} to not change the value 162 * @param createTime 163 * the file's create time, or {@code null} to not change the value 164 * 165 * @throws IOException 166 * if an I/O error occurs 167 * @throws SecurityException 168 * In the case of the default provider, a security manager is 169 * installed, its {@link SecurityManager#checkWrite(String) checkWrite} 170 * method is invoked to check write access to the file 171 * 172 * @see java.nio.file.Files#setLastModifiedTime 173 */ setTimes(FileTime lastModifiedTime, FileTime lastAccessTime, FileTime createTime)174 void setTimes(FileTime lastModifiedTime, 175 FileTime lastAccessTime, 176 FileTime createTime) throws IOException; 177 } 178