/*

 * 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;

}