1 /*

     2  * Copyright 2007-2009 Sun Microsystems, Inc.  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.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any 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  * #getAttribute getAttribute} or {@link #readAttributes(String,String[])

    63  * readAttributes(String,String[])} methods may be used to read the attribute

    64  * value. The attribute value is returned as a byte array (byte[]). The {@link

    65  * #setAttribute setAttribute} method may be used to write the value of a

    66  * user-defined attribute from a buffer (as if by invoking the {@link #write

    67  * write} method), or byte array (byte[]).

    68  *

    69  * @since 1.7

    70  */

    71 

    72 public interface UserDefinedFileAttributeView

    73     extends FileAttributeView

    74 {

    75     /**

    76      * Returns the name of this attribute view. Attribute views of this type

    77      * have the name {@code "xattr"}.

    78      */

    79     @Override

    80     String name();

    81 

    82     /**

    83      * Returns a list containing the names of the user-defined attributes.

    84      *

    85      * @return  An unmodifiable list continaing the names of the file's

    86      *          user-defined

    87      *

    88      * @throws  IOException

    89      *          If an I/O error occurs

    90      * @throws  SecurityException

    91      *          In the case of the default provider, a security manager is

    92      *          installed, and it denies {@link

    93      *          RuntimePermission}<tt>("accessUserDefinedAttributes")</tt>

    94      *          or its {@link SecurityManager#checkRead(String) checkRead} method

    95      *          denies read access to the file.

    96      */

    97     List<String> list() throws IOException;

    98 

    99     /**

   100      * Returns the size of the value of a user-defined attribute.

   101      *

   102      * @param   name

   103      *          The attribute name

   104      *

   105      * @return  The size of the attribute value, in bytes.

   106      *

   107      * @throws  ArithmeticException

   108      *          If the size of the attribute is larger than {@link Integer#MAX_VALUE}

   109      * @throws  IOException

   110      *          If an I/O error occurs

   111      * @throws  SecurityException

   112      *          In the case of the default provider, a security manager is

   113      *          installed, and it denies {@link

   114      *          RuntimePermission}<tt>("accessUserDefinedAttributes")</tt>

   115      *          or its {@link SecurityManager#checkRead(String) checkRead} method

   116      *          denies read access to the file.

   117      */

   118     int size(String name) throws IOException;

   119 

   120     /**

   121      * Read the value of a user-defined attribute into a buffer.

   122      *

   123      * <p> This method reads the value of the attribute into the given buffer

   124      * as a sequence of bytes, failing if the number of bytes remaining in

   125      * the buffer is insufficient to read the complete attribute value. The

   126      * number of bytes transferred into the buffer is {@code n}, where {@code n}

   127      * is the size of the attribute value. The first byte in the sequence is at

   128      * index {@code p} and the last byte is at index {@code p + n - 1}, where

   129      * {@code p} is the buffer's position. Upon return the buffer's position

   130      * will be equal to {@code p + n}; its limit will not have changed.

   131      *

   132      * <p> <b>Usage Example:</b>

   133      * Suppose we want to read a file's MIME type that is stored as a user-defined

   134      * attribute with the name "{@code user.mimetype}".

   135      * <pre>

   136      *    UserDefinedFileAttributeView view = file

   137      *        .getFileAttributeView(UserDefinedFileAttributeView.class);

   138      *    String name = "user.mimetype";

   139      *    ByteBuffer buf = ByteBuffer.allocate(view.size(name));

   140      *    view.read(name, buf);

   141      *    buf.flip();

   142      *    String value = Charset.defaultCharset().decode(buf).toString();

   143      * </pre>

   144      *

   145      * @param   name

   146      *          The attribute name

   147      * @param   dst

   148      *          The destination buffer

   149      *

   150      * @return  The number of bytes read, possibly zero

   151      *

   152      * @throws  IllegalArgumentException

   153      *          If the destination buffer is read-only

   154      * @throws  IOException

   155      *          If an I/O error occurs or there is insufficient space in the

   156      *          destination buffer for the attribute value

   157      * @throws  SecurityException

   158      *          In the case of the default provider, a security manager is

   159      *          installed, and it denies {@link

   160      *          RuntimePermission}<tt>("accessUserDefinedAttributes")</tt>

   161      *          or its {@link SecurityManager#checkRead(String) checkRead} method

   162      *          denies read access to the file.

   163      *

   164      * @see #size

   165      */

   166     int read(String name, ByteBuffer dst) throws IOException;

   167 

   168     /**

   169      * Writes the value of a user-defined attribute from a buffer.

   170      *

   171      * <p> This method writes the value of the attribute from a given buffer as

   172      * a sequence of bytes. The size of the value to transfer is {@code r},

   173      * where {@code r} is the number of bytes remaining in the buffer, that is

   174      * {@code src.remaining()}. The sequence of bytes is transferred from the

   175      * buffer starting at index {@code p}, where {@code p} is the buffer's

   176      * position. Upon return, the buffer's position will be equal to {@code

   177      * p + n}, where {@code n} is the number of bytes transferred; its limit

   178      * will not have changed.

   179      *

   180      * <p> If an attribute of the given name already exists then its value is

   181      * replaced. If the attribute does not exist then it is created. If it

   182      * implementation specific if a test to check for the existence of the

   183      * attribute and the creation of attribute are atomic with repect to other

   184      * file system activities.

   185      *

   186      * <p> Where there is insufficient space to store the attribute, or the

   187      * attribute name or value exceed an implementation specific maximum size

   188      * then an {@code IOException} is thrown.

   189      *

   190      * <p> <b>Usage Example:</b>

   191      * Suppose we want to write a file's MIME type as a user-defined attribute:

   192      * <pre>

   193      *    UserDefinedFileAttributeView view = file

   194      *        .getFileAttributeView(UserDefinedFileAttributeView.class);

   195      *    view.write("user.mimetype", Charset.defaultCharset().encode("text/html"));

   196      * </pre>

   197      *

   198      * @param   name

   199      *          The attribute name

   200      * @param   src

   201      *          The buffer containing the attribute value

   202      *

   203      * @return  The number of bytes written, possibly zero

   204      *

   205      * @throws  IOException

   206      *          If an I/O error occurs

   207      * @throws  SecurityException

   208      *          In the case of the default provider, a security manager is

   209      *          installed, and it denies {@link

   210      *          RuntimePermission}<tt>("accessUserDefinedAttributes")</tt>

   211      *          or its {@link SecurityManager#checkWrite(String) checkWrite}

   212      *          method denies write access to the file.

   213      */

   214     int write(String name, ByteBuffer src) throws IOException;

   215 

   216     /**

   217      * Deletes a user-defined attribute.

   218      *

   219      * @param   name

   220      *          The attribute name

   221      *

   222      * @throws  IOException

   223      *          If an I/O error occurs or the attribute does not exist

   224      * @throws  SecurityException

   225      *          In the case of the default provider, a security manager is

   226      *          installed, and it denies {@link

   227      *          RuntimePermission}<tt>("accessUserDefinedAttributes")</tt>

   228      *          or its {@link SecurityManager#checkWrite(String) checkWrite}

   229      *          method denies write access to the file.

   230      */

   231     void delete(String name) throws IOException;

   232 }