--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/java/nio/file/attribute/UserDefinedFileAttributeView.java Sun Feb 15 12:25:54 2009 +0000
@@ -0,0 +1,232 @@
+/*
+ * Copyright 2007-2009 Sun Microsystems, Inc. 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. Sun designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+ * CA 95054 USA or visit www.sun.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
+ * #getAttribute getAttribute} or {@link #readAttributes(String,String[])
+ * readAttributes(String,String[])} methods may be used to read the attribute
+ * value. The attribute value is returned as a byte array (byte[]). The {@link
+ * #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 "xattr"}.
+ */
+ @Override
+ String name();
+
+ /**
+ * Returns a list containing the names of the user-defined attributes.
+ *
+ * @return An unmodifiable list continaing 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 = file
+ * .getFileAttributeView(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 repect 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 = file
+ * .getFileAttributeView(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;
+}