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