1 /*
   2  * Copyright (c) 2007, 2009, 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
  79     String name();
  80 
  81     /**
  82      * Returns a list containing the names of the user-defined attributes.
  83      *
  84      * @return  An unmodifiable list continaing 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      */
  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      */
 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 = file
 136      *        .getFileAttributeView(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      */
 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 repect 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 = file
 193      *        .getFileAttributeView(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      */
 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      */
 230     void delete(String name) throws IOException;
 231 }