Automatic sources dropoff on 2020-06-10 18:32:38.095721 The change is generated with prebuilt drop tool. Change-Id: I24cbf6ba6db262a1ae1445db1427a08fee35b3b4
diff --git a/java/nio/file/attribute/UserDefinedFileAttributeView.java b/java/nio/file/attribute/UserDefinedFileAttributeView.java new file mode 100644 index 0000000..56e7135 --- /dev/null +++ b/java/nio/file/attribute/UserDefinedFileAttributeView.java
@@ -0,0 +1,231 @@ +/* + * Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package java.nio.file.attribute; + +import java.nio.ByteBuffer; +import java.util.List; +import java.io.IOException; + +/** + * A file attribute view that provides a view of a file's user-defined + * attributes, sometimes known as <em>extended attributes</em>. User-defined + * file attributes are used to store metadata with a file that is not meaningful + * to the file system. It is primarily intended for file system implementations + * that support such a capability directly but may be emulated. The details of + * such emulation are highly implementation specific and therefore not specified. + * + * <p> This {@code FileAttributeView} provides a view of a file's user-defined + * attributes as a set of name/value pairs, where the attribute name is + * represented by a {@code String}. An implementation may require to encode and + * decode from the platform or file system representation when accessing the + * attribute. The value has opaque content. This attribute view defines the + * {@link #read read} and {@link #write write} methods to read the value into + * or write from a {@link ByteBuffer}. This {@code FileAttributeView} is not + * intended for use where the size of an attribute value is larger than {@link + * Integer#MAX_VALUE}. + * + * <p> User-defined attributes may be used in some implementations to store + * security related attributes so consequently, in the case of the default + * provider at least, all methods that access user-defined attributes require the + * {@code RuntimePermission("accessUserDefinedAttributes")} permission when a + * security manager is installed. + * + * <p> The {@link java.nio.file.FileStore#supportsFileAttributeView + * supportsFileAttributeView} method may be used to test if a specific {@link + * java.nio.file.FileStore FileStore} supports the storage of user-defined + * attributes. + * + * <p> Where dynamic access to file attributes is required, the {@link + * java.nio.file.Files#getAttribute getAttribute} method may be used to read + * the attribute value. The attribute value is returned as a byte array (byte[]). + * The {@link java.nio.file.Files#setAttribute setAttribute} method may be used + * to write the value of a user-defined attribute from a buffer (as if by + * invoking the {@link #write write} method), or byte array (byte[]). + * + * @since 1.7 + */ + +public interface UserDefinedFileAttributeView + extends FileAttributeView +{ + /** + * Returns the name of this attribute view. Attribute views of this type + * have the name {@code "user"}. + */ + @Override + String name(); + + /** + * Returns a list containing the names of the user-defined attributes. + * + * @return An unmodifiable list containing the names of the file's + * user-defined + * + * @throws IOException + * If an I/O error occurs + * @throws SecurityException + * In the case of the default provider, a security manager is + * installed, and it denies {@link + * RuntimePermission}<tt>("accessUserDefinedAttributes")</tt> + * or its {@link SecurityManager#checkRead(String) checkRead} method + * denies read access to the file. + */ + List<String> list() throws IOException; + + /** + * Returns the size of the value of a user-defined attribute. + * + * @param name + * The attribute name + * + * @return The size of the attribute value, in bytes. + * + * @throws ArithmeticException + * If the size of the attribute is larger than {@link Integer#MAX_VALUE} + * @throws IOException + * If an I/O error occurs + * @throws SecurityException + * In the case of the default provider, a security manager is + * installed, and it denies {@link + * RuntimePermission}<tt>("accessUserDefinedAttributes")</tt> + * or its {@link SecurityManager#checkRead(String) checkRead} method + * denies read access to the file. + */ + int size(String name) throws IOException; + + /** + * Read the value of a user-defined attribute into a buffer. + * + * <p> This method reads the value of the attribute into the given buffer + * as a sequence of bytes, failing if the number of bytes remaining in + * the buffer is insufficient to read the complete attribute value. The + * number of bytes transferred into the buffer is {@code n}, where {@code n} + * is the size of the attribute value. The first byte in the sequence is at + * index {@code p} and the last byte is at index {@code p + n - 1}, where + * {@code p} is the buffer's position. Upon return the buffer's position + * will be equal to {@code p + n}; its limit will not have changed. + * + * <p> <b>Usage Example:</b> + * Suppose we want to read a file's MIME type that is stored as a user-defined + * attribute with the name "{@code user.mimetype}". + * <pre> + * UserDefinedFileAttributeView view = + * Files.getFileAttributeView(path, UserDefinedFileAttributeView.class); + * String name = "user.mimetype"; + * ByteBuffer buf = ByteBuffer.allocate(view.size(name)); + * view.read(name, buf); + * buf.flip(); + * String value = Charset.defaultCharset().decode(buf).toString(); + * </pre> + * + * @param name + * The attribute name + * @param dst + * The destination buffer + * + * @return The number of bytes read, possibly zero + * + * @throws IllegalArgumentException + * If the destination buffer is read-only + * @throws IOException + * If an I/O error occurs or there is insufficient space in the + * destination buffer for the attribute value + * @throws SecurityException + * In the case of the default provider, a security manager is + * installed, and it denies {@link + * RuntimePermission}<tt>("accessUserDefinedAttributes")</tt> + * or its {@link SecurityManager#checkRead(String) checkRead} method + * denies read access to the file. + * + * @see #size + */ + int read(String name, ByteBuffer dst) throws IOException; + + /** + * Writes the value of a user-defined attribute from a buffer. + * + * <p> This method writes the value of the attribute from a given buffer as + * a sequence of bytes. The size of the value to transfer is {@code r}, + * where {@code r} is the number of bytes remaining in the buffer, that is + * {@code src.remaining()}. The sequence of bytes is transferred from the + * buffer starting at index {@code p}, where {@code p} is the buffer's + * position. Upon return, the buffer's position will be equal to {@code + * p + n}, where {@code n} is the number of bytes transferred; its limit + * will not have changed. + * + * <p> If an attribute of the given name already exists then its value is + * replaced. If the attribute does not exist then it is created. If it + * implementation specific if a test to check for the existence of the + * attribute and the creation of attribute are atomic with respect to other + * file system activities. + * + * <p> Where there is insufficient space to store the attribute, or the + * attribute name or value exceed an implementation specific maximum size + * then an {@code IOException} is thrown. + * + * <p> <b>Usage Example:</b> + * Suppose we want to write a file's MIME type as a user-defined attribute: + * <pre> + * UserDefinedFileAttributeView view = + * FIles.getFileAttributeView(path, UserDefinedFileAttributeView.class); + * view.write("user.mimetype", Charset.defaultCharset().encode("text/html")); + * </pre> + * + * @param name + * The attribute name + * @param src + * The buffer containing the attribute value + * + * @return The number of bytes written, possibly zero + * + * @throws IOException + * If an I/O error occurs + * @throws SecurityException + * In the case of the default provider, a security manager is + * installed, and it denies {@link + * RuntimePermission}<tt>("accessUserDefinedAttributes")</tt> + * or its {@link SecurityManager#checkWrite(String) checkWrite} + * method denies write access to the file. + */ + int write(String name, ByteBuffer src) throws IOException; + + /** + * Deletes a user-defined attribute. + * + * @param name + * The attribute name + * + * @throws IOException + * If an I/O error occurs or the attribute does not exist + * @throws SecurityException + * In the case of the default provider, a security manager is + * installed, and it denies {@link + * RuntimePermission}<tt>("accessUserDefinedAttributes")</tt> + * or its {@link SecurityManager#checkWrite(String) checkWrite} + * method denies write access to the file. + */ + void delete(String name) throws IOException; +}