1 /*
   2  * Copyright (c) 2007, 2013, 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.io.IOException;
  29 
  30 /**
  31  * A file attribute view that provides a view of the legacy "DOS" file attributes.
  32  * These attributes are supported by file systems such as the File Allocation
  33  * Table (FAT) format commonly used in <em>consumer devices</em>.
  34  *
  35  * <p> A {@code DosFileAttributeView} is a {@link BasicFileAttributeView} that
  36  * additionally supports access to the set of DOS attribute flags that are used
  37  * to indicate if the file is read-only, hidden, a system file, or archived.
  38  *
  39  * <p> Where dynamic access to file attributes is required, the attributes
  40  * supported by this attribute view are as defined by {@code
  41  * BasicFileAttributeView}, and in addition, the following attributes are
  42  * supported:
  43  * <blockquote>
  44  * <table class="altrows">
  45  * <caption style="display:none">Supported attributes</caption>
  46  * <thead>
  47  *   <tr>
  48  *     <th> Name </th>
  49  *     <th> Type </th>
  50  *   </tr>
  51  * </thead>
  52  * <tbody>
  53  *   <tr>
  54  *     <td> readonly </td>
  55  *     <td> {@link Boolean} </td>
  56  *   </tr>
  57  *   <tr>
  58  *     <td> hidden </td>
  59  *     <td> {@link Boolean} </td>
  60  *   </tr>
  61  *   <tr>
  62  *     <td> system </td>
  63  *     <td> {@link Boolean} </td>
  64  *   </tr>
  65  *   <tr>
  66  *     <td> archive </td>
  67  *     <td> {@link Boolean} </td>
  68  *   </tr>
  69  * </tbody>
  70  * </table>
  71  * </blockquote>
  72  *
  73  * <p> The {@link java.nio.file.Files#getAttribute getAttribute} method may
  74  * be used to read any of these attributes, or any of the attributes defined by
  75  * {@link BasicFileAttributeView} as if by invoking the {@link #readAttributes
  76  * readAttributes()} method.
  77  *
  78  * <p> The {@link java.nio.file.Files#setAttribute setAttribute} method may
  79  * be used to update the file's last modified time, last access time or create
  80  * time attributes as defined by {@link BasicFileAttributeView}. It may also be
  81  * used to update the DOS attributes as if by invoking the {@link #setReadOnly
  82  * setReadOnly}, {@link #setHidden setHidden}, {@link #setSystem setSystem}, and
  83  * {@link #setArchive setArchive} methods respectively.
  84  *
  85  * @since 1.7
  86  */
  87 
  88 public interface DosFileAttributeView
  89     extends BasicFileAttributeView
  90 {
  91     /**
  92      * Returns the name of the attribute view. Attribute views of this type
  93      * have the name {@code "dos"}.
  94      */
  95     @Override
  96     String name();
  97 
  98     /**
  99      * @throws  IOException                             {@inheritDoc}
 100      * @throws  SecurityException                       {@inheritDoc}
 101      */
 102     @Override
 103     DosFileAttributes readAttributes() throws IOException;
 104 
 105     /**
 106      * Updates the value of the read-only attribute.
 107      *
 108      * <p> It is implementation specific if the attribute can be updated as an
 109      * atomic operation with respect to other file system operations. An
 110      * implementation may, for example, require to read the existing value of
 111      * the DOS attribute in order to update this attribute.
 112      *
 113      * @param   value
 114      *          the new value of the attribute
 115      *
 116      * @throws  IOException
 117      *          if an I/O error occurs
 118      * @throws  SecurityException
 119      *          In the case of the default, and a security manager is installed,
 120      *          its  {@link SecurityManager#checkWrite(String) checkWrite} method
 121      *          is invoked to check write access to the file
 122      */
 123     void setReadOnly(boolean value) throws IOException;
 124 
 125     /**
 126      * Updates the value of the hidden attribute.
 127      *
 128      * <p> It is implementation specific if the attribute can be updated as an
 129      * atomic operation with respect to other file system operations. An
 130      * implementation may, for example, require to read the existing value of
 131      * the DOS attribute in order to update this attribute.
 132      *
 133      * @param   value
 134      *          the new value of the attribute
 135      *
 136      * @throws  IOException
 137      *          if an I/O error occurs
 138      * @throws  SecurityException
 139      *          In the case of the default, and a security manager is installed,
 140      *          its  {@link SecurityManager#checkWrite(String) checkWrite} method
 141      *          is invoked to check write access to the file
 142      */
 143     void setHidden(boolean value) throws IOException;
 144 
 145     /**
 146      * Updates the value of the system attribute.
 147      *
 148      * <p> It is implementation specific if the attribute can be updated as an
 149      * atomic operation with respect to other file system operations. An
 150      * implementation may, for example, require to read the existing value of
 151      * the DOS attribute in order to update this attribute.
 152      *
 153      * @param   value
 154      *          the new value of the attribute
 155      *
 156      * @throws  IOException
 157      *          if an I/O error occurs
 158      * @throws  SecurityException
 159      *          In the case of the default, and a security manager is installed,
 160      *          its  {@link SecurityManager#checkWrite(String) checkWrite} method
 161      *          is invoked to check write access to the file
 162      */
 163     void setSystem(boolean value) throws IOException;
 164 
 165     /**
 166      * Updates the value of the archive attribute.
 167      *
 168      * <p> It is implementation specific if the attribute can be updated as an
 169      * atomic operation with respect to other file system operations. An
 170      * implementation may, for example, require to read the existing value of
 171      * the DOS attribute in order to update this attribute.
 172      *
 173      * @param   value
 174      *          the new value of the attribute
 175      *
 176      * @throws  IOException
 177      *          if an I/O error occurs
 178      * @throws  SecurityException
 179      *          In the case of the default, and a security manager is installed,
 180      *          its  {@link SecurityManager#checkWrite(String) checkWrite} method
 181      *          is invoked to check write access to the file
 182      */
 183     void setArchive(boolean value) throws IOException;
 184 }