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.nio.ByteBuffer; 29 import java.util.List; 30 import java.io.IOException; 31 32 /** 33 * A file attribute view that provides a view of a file's user-defined 34 * attributes, sometimes known as <em>extended attributes</em>. User-defined 35 * file attributes are used to store metadata with a file that is not meaningful 36 * to the file system. It is primarily intended for file system implementations 37 * that support such a capability directly but may be emulated. The details of 38 * such emulation are highly implementation specific and therefore not specified. 39 * 40 * <p> This {@code FileAttributeView} provides a view of a file's user-defined 41 * attributes as a set of name/value pairs, where the attribute name is 42 * represented by a {@code String}. An implementation may require to encode and 43 * decode from the platform or file system representation when accessing the 44 * attribute. The value has opaque content. This attribute view defines the 45 * {@link #read read} and {@link #write write} methods to read the value into 46 * or write from a {@link ByteBuffer}. This {@code FileAttributeView} is not 47 * intended for use where the size of an attribute value is larger than {@link 48 * Integer#MAX_VALUE}. 49 * 50 * <p> User-defined attributes may be used in some implementations to store 51 * security related attributes so consequently, in the case of the default 52 * provider at least, all methods that access user-defined attributes require the 53 * {@code RuntimePermission("accessUserDefinedAttributes")} permission when a 54 * security manager is installed. 55 * 56 * <p> The {@link java.nio.file.FileStore#supportsFileAttributeView 57 * supportsFileAttributeView} method may be used to test if a specific {@link 58 * java.nio.file.FileStore FileStore} supports the storage of user-defined 59 * attributes. 60 * 61 * <p> Where dynamic access to file attributes is required, the {@link 62 * java.nio.file.Files#getAttribute getAttribute} method may be used to read 63 * the attribute value. The attribute value is returned as a byte array (byte[]). 64 * The {@link java.nio.file.Files#setAttribute setAttribute} method may be used 65 * to write the value of a user-defined attribute from a buffer (as if by 66 * invoking the {@link #write write} method), or byte array (byte[]). 67 * 68 * @since 1.7 69 */ 70 71 public interface UserDefinedFileAttributeView 72 extends FileAttributeView 73 { 74 /** 75 * Returns the name of this attribute view. Attribute views of this type 76 * have the name {@code "user"}. 77 */ 78 @Override name()79 String name(); 80 81 /** 82 * Returns a list containing the names of the user-defined attributes. 83 * 84 * @return An unmodifiable list containing the names of the file's 85 * user-defined 86 * 87 * @throws IOException 88 * If an I/O error occurs 89 * @throws SecurityException 90 * In the case of the default provider, a security manager is 91 * installed, and it denies {@link 92 * RuntimePermission}<tt>("accessUserDefinedAttributes")</tt> 93 * or its {@link SecurityManager#checkRead(String) checkRead} method 94 * denies read access to the file. 95 */ list()96 List<String> list() throws IOException; 97 98 /** 99 * Returns the size of the value of a user-defined attribute. 100 * 101 * @param name 102 * The attribute name 103 * 104 * @return The size of the attribute value, in bytes. 105 * 106 * @throws ArithmeticException 107 * If the size of the attribute is larger than {@link Integer#MAX_VALUE} 108 * @throws IOException 109 * If an I/O error occurs 110 * @throws SecurityException 111 * In the case of the default provider, a security manager is 112 * installed, and it denies {@link 113 * RuntimePermission}<tt>("accessUserDefinedAttributes")</tt> 114 * or its {@link SecurityManager#checkRead(String) checkRead} method 115 * denies read access to the file. 116 */ size(String name)117 int size(String name) throws IOException; 118 119 /** 120 * Read the value of a user-defined attribute into a buffer. 121 * 122 * <p> This method reads the value of the attribute into the given buffer 123 * as a sequence of bytes, failing if the number of bytes remaining in 124 * the buffer is insufficient to read the complete attribute value. The 125 * number of bytes transferred into the buffer is {@code n}, where {@code n} 126 * is the size of the attribute value. The first byte in the sequence is at 127 * index {@code p} and the last byte is at index {@code p + n - 1}, where 128 * {@code p} is the buffer's position. Upon return the buffer's position 129 * will be equal to {@code p + n}; its limit will not have changed. 130 * 131 * <p> <b>Usage Example:</b> 132 * Suppose we want to read a file's MIME type that is stored as a user-defined 133 * attribute with the name "{@code user.mimetype}". 134 * <pre> 135 * UserDefinedFileAttributeView view = 136 * Files.getFileAttributeView(path, UserDefinedFileAttributeView.class); 137 * String name = "user.mimetype"; 138 * ByteBuffer buf = ByteBuffer.allocate(view.size(name)); 139 * view.read(name, buf); 140 * buf.flip(); 141 * String value = Charset.defaultCharset().decode(buf).toString(); 142 * </pre> 143 * 144 * @param name 145 * The attribute name 146 * @param dst 147 * The destination buffer 148 * 149 * @return The number of bytes read, possibly zero 150 * 151 * @throws IllegalArgumentException 152 * If the destination buffer is read-only 153 * @throws IOException 154 * If an I/O error occurs or there is insufficient space in the 155 * destination buffer for the attribute value 156 * @throws SecurityException 157 * In the case of the default provider, a security manager is 158 * installed, and it denies {@link 159 * RuntimePermission}<tt>("accessUserDefinedAttributes")</tt> 160 * or its {@link SecurityManager#checkRead(String) checkRead} method 161 * denies read access to the file. 162 * 163 * @see #size 164 */ read(String name, ByteBuffer dst)165 int read(String name, ByteBuffer dst) throws IOException; 166 167 /** 168 * Writes the value of a user-defined attribute from a buffer. 169 * 170 * <p> This method writes the value of the attribute from a given buffer as 171 * a sequence of bytes. The size of the value to transfer is {@code r}, 172 * where {@code r} is the number of bytes remaining in the buffer, that is 173 * {@code src.remaining()}. The sequence of bytes is transferred from the 174 * buffer starting at index {@code p}, where {@code p} is the buffer's 175 * position. Upon return, the buffer's position will be equal to {@code 176 * p + n}, where {@code n} is the number of bytes transferred; its limit 177 * will not have changed. 178 * 179 * <p> If an attribute of the given name already exists then its value is 180 * replaced. If the attribute does not exist then it is created. If it 181 * implementation specific if a test to check for the existence of the 182 * attribute and the creation of attribute are atomic with respect to other 183 * file system activities. 184 * 185 * <p> Where there is insufficient space to store the attribute, or the 186 * attribute name or value exceed an implementation specific maximum size 187 * then an {@code IOException} is thrown. 188 * 189 * <p> <b>Usage Example:</b> 190 * Suppose we want to write a file's MIME type as a user-defined attribute: 191 * <pre> 192 * UserDefinedFileAttributeView view = 193 * FIles.getFileAttributeView(path, UserDefinedFileAttributeView.class); 194 * view.write("user.mimetype", Charset.defaultCharset().encode("text/html")); 195 * </pre> 196 * 197 * @param name 198 * The attribute name 199 * @param src 200 * The buffer containing the attribute value 201 * 202 * @return The number of bytes written, possibly zero 203 * 204 * @throws IOException 205 * If an I/O error occurs 206 * @throws SecurityException 207 * In the case of the default provider, a security manager is 208 * installed, and it denies {@link 209 * RuntimePermission}<tt>("accessUserDefinedAttributes")</tt> 210 * or its {@link SecurityManager#checkWrite(String) checkWrite} 211 * method denies write access to the file. 212 */ write(String name, ByteBuffer src)213 int write(String name, ByteBuffer src) throws IOException; 214 215 /** 216 * Deletes a user-defined attribute. 217 * 218 * @param name 219 * The attribute name 220 * 221 * @throws IOException 222 * If an I/O error occurs or the attribute does not exist 223 * @throws SecurityException 224 * In the case of the default provider, a security manager is 225 * installed, and it denies {@link 226 * RuntimePermission}<tt>("accessUserDefinedAttributes")</tt> 227 * or its {@link SecurityManager#checkWrite(String) checkWrite} 228 * method denies write access to the file. 229 */ delete(String name)230 void delete(String name) throws IOException; 231 } 232