42     private Attributes() {

    41     private Attributes() { }

    43     }

    44 

    45     /**

    46      * Splits the given attribute name into the name of an attribute view and

    47      * the attribute. If the attribute view is not identified then it assumed

    48      * to be "basic".

    49      */

    50     private static String[] split(String attribute) {

    51         String[] s = new String[2];

    52         int pos = attribute.indexOf(':');

    53         if (pos == -1) {

    54             s[0] = "basic";

    55             s[1] = attribute;

    56         } else {

    57             s[0] = attribute.substring(0, pos++);

    58             s[1] = (pos == attribute.length()) ? "" : attribute.substring(pos);

    59         }

    60         return s;

    61     }

    62 

    63     /**

    64      * Sets the value of a file attribute.

    65      *

    66      * <p> The {@code attribute} parameter identifies the attribute to be set

    67      * and takes the form:

    68      * <blockquote>

    69      * [<i>view-name</i><b>:</b>]<i>attribute-name</i>

    70      * </blockquote>

    71      * where square brackets [...] delineate an optional component and the

    72      * character {@code ':'} stands for itself.

    73      *

    74      * <p> <i>view-name</i> is the {@link FileAttributeView#name name} of a {@link

    75      * FileAttributeView} that identifies a set of file attributes. If not

    76      * specified then it defaults to {@code "basic"}, the name of the file

    77      * attribute view that identifies the basic set of file attributes common to

    78      * many file systems. <i>attribute-name</i> is the name of the attribute

    79      * within the set.

    80      *

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

    82      * Suppose we want to set the DOS "hidden" attribute:

    83      * <pre>

    84      *    Attributes.setAttribute(file, "dos:hidden", true);

    85      * </pre>

    86      *

    87      * @param   file

    88      *          A file reference that locates the file

    89      * @param   attribute

    90      *          The attribute to set

    91      * @param   value

    92      *          The attribute value

    93      *

    94      * @throws  UnsupportedOperationException

    95      *          If the attribute view is not available or it does not

    96      *          support updating the attribute

    97      * @throws  IllegalArgumentException

    98      *          If the attribute value is of the correct type but has an

    99      *          inappropriate value

   100      * @throws  ClassCastException

   101      *          If the attribute value is not of the expected type or is a

   102      *          collection containing elements that are not of the expected

   103      *          type

   104      * @throws  IOException

   105      *          If an I/O error occurs

   106      * @throws  SecurityException

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

   108      *          installed, its {@link SecurityManager#checkWrite(String) checkWrite}

   109      *          method denies write access to the file. If this method is invoked

   110      *          to set security sensitive attributes then the security manager

   111      *          may be invoked to check for additional permissions.

   112      */

   113     public static void setAttribute(FileRef file, String attribute, Object value)

   114         throws IOException

   115     {

   116         String[] s = split(attribute);

   117         FileAttributeView view = file.getFileAttributeView(s[0]);

   118         if (view == null)

   119             throw new UnsupportedOperationException("View '" + s[0] + "' not available");

   120         view.setAttribute(s[1], value);

   121     }

   122 

   123     /**

   124      * Reads the value of a file attribute.

   125      *

   126      * <p> The {@code attribute} parameter identifies the attribute to be read

   127      * and takes the form:

   128      * <blockquote>

   129      * [<i>view-name</i><b>:</b>]<i>attribute-name</i>

   130      * </blockquote>

   131      * where square brackets [...] delineate an optional component and the

   132      * character {@code ':'} stands for itself.

   133      *

   134      * <p> <i>view-name</i> is the {@link FileAttributeView#name name} of a {@link

   135      * FileAttributeView} that identifies a set of file attributes. If not

   136      * specified then it defaults to {@code "basic"}, the name of the file

   137      * attribute view that identifies the basic set of file attributes common to

   138      * many file systems. <i>attribute-name</i> is the name of the attribute.

   139      *

   140      * <p> The {@code options} array may be used to indicate how symbolic links

   141      * are handled for the case that the file is a symbolic link. By default,

   142      * symbolic links are followed and the file attribute of the final target

   143      * of the link is read. If the option {@link LinkOption#NOFOLLOW_LINKS

   144      * NOFOLLOW_LINKS} is present then symbolic links are not followed and so

   145      * the method returns the file attribute of the symbolic link.

   146      *

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

   148      * Suppose we require the user ID of the file owner on a system that

   149      * supports a "{@code unix}" view:

   150      * <pre>

   151      *    int uid = (Integer)Attributes.getAttribute(file, "unix:uid");

   152      * </pre>

   153      *

   154      * @param   file

   155      *          A file reference that locates the file

   156      * @param   attribute

   157      *          The attribute to read

   158      * @param   options

   159      *          Options indicating how symbolic links are handled

   160      *

   161      * @return  The attribute value, or {@code null} if the attribute view

   162      *          is not available or it does not support reading the attribute

   163      *

   164      * @throws  IOException

   165      *          If an I/O error occurs

   166      * @throws  SecurityException

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

   168      *          installed, its {@link SecurityManager#checkRead(String) checkRead}

   169      *          method denies read access to the file. If this method is invoked

   170      *          to read security sensitive attributes then the security manager

   171      *          may be invoked to check for additional permissions.

   172      */

   173     public static Object getAttribute(FileRef file,

   174                                       String attribute,

   175                                       LinkOption... options)

   176         throws IOException

   177     {

   178         String[] s = split(attribute);

   179         FileAttributeView view = file.getFileAttributeView(s[0], options);

   180         if (view != null)

   181             return view.getAttribute(s[1]);

   182         // view not available

   183         return null;

   184     }

   185 

   186     /**

   187      * Reads a set of file attributes as a bulk operation.

   188      *

   189      * <p> The {@code attributes} parameter identifies the attributes to be read

   190      * and takes the form:

   191      * <blockquote>

   192      * [<i>view-name</i><b>:</b>]<i>attribute-list</i>

   193      * </blockquote>

   194      * where square brackets [...] delineate an optional component and the

   195      * character {@code ':'} stands for itself.

   196      *

   197      * <p> <i>view-name</i> is the {@link FileAttributeView#name name} of a {@link

   198      * FileAttributeView} that identifies a set of file attributes. If not

   199      * specified then it defaults to {@code "basic"}, the name of the file

   200      * attribute view that identifies the basic set of file attributes common to

   201      * many file systems.

   202      *

   203      * <p> The <i>attribute-list</i> component is a comma separated list of

   204      * zero or more names of attributes to read. If the list contains the value

   205      * {@code "*"} then all attributes are read. Attributes that are not supported

   206      * are ignored and will not be present in the returned map. It is

   207      * implementation specific if all attributes are read as an atomic operation

   208      * with respect to other file system operations.

   209      *

   210      * <p> The following examples demonstrate possible values for the {@code

   211      * attributes} parameter:

   212      *

   213      * <blockquote>

   214      * <table border="0">

   215      * <tr>

   216      *   <td> {@code "*"} </td>

   217      *   <td> Read all {@link BasicFileAttributes basic-file-attributes}. </td>

   218      * </tr>

   219      * <tr>

   220      *   <td> {@code "size,lastModifiedTime,lastAccessTime"} </td>

   221      *   <td> Reads the file size, last modified time, and last access time

   222      *     attributes. </td>

   223      * </tr>

   224      * <tr>

   225      *   <td> {@code "posix:*"} </td>

   226      *   <td> Read all {@link PosixFileAttributes POSIX-file-attributes}.. </td>

   227      * </tr>

   228      * <tr>

   229      *   <td> {@code "posix:permissions,owner,size"} </td>

   230      *   <td> Reads the POSX file permissions, owner, and file size. </td>

   231      * </tr>

   232      * </table>

   233      * </blockquote>

   234      *

   235      * <p> The {@code options} array may be used to indicate how symbolic links

   236      * are handled for the case that the file is a symbolic link. By default,

   237      * symbolic links are followed and the file attributes of the final target

   238      * of the link are read. If the option {@link LinkOption#NOFOLLOW_LINKS

   239      * NOFOLLOW_LINKS} is present then symbolic links are not followed and so

   240      * the method returns the file attributes of the symbolic link.

   241      *

   242      * @param   file

   243      *          A file reference that locates the file

   244      * @param   attributes

   245      *          The attributes to read

   246      * @param   options

   247      *          Options indicating how symbolic links are handled

   248      *

   249      * @return  A map of the attributes returned; may be empty. The map's keys

   250      *          are the attribute names, its values are the attribute values

   251      *

   252      * @throws  IOException

   253      *          If an I/O error occurs

   254      * @throws  SecurityException

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

   256      *          installed, its {@link SecurityManager#checkRead(String) checkRead}

   257      *          method denies read access to the file. If this method is invoked

   258      *          to read security sensitive attributes then the security manager

   259      *          may be invoke to check for additional permissions.

   260      */

   261     public static Map<String,?> readAttributes(FileRef file,

   262                                                String attributes,

   263                                                LinkOption... options)

   264         throws IOException

   265     {

   266         String[] s = split(attributes);

   267         FileAttributeView view = file.getFileAttributeView(s[0], options);

   268         if (view != null) {

   269             // further split attributes into the first and rest.

   270             String[] names = s[1].split(",");

   271             int rem = names.length-1;

   272             String first = names[0];

   273             String[] rest = new String[rem];

   274             if (rem > 0) System.arraycopy(names, 1, rest, 0, rem);

   275 

   276             return view.readAttributes(first, rest);

   277         }

   278         // view not available

   279         return Collections.emptyMap();

   280     }

   554      * Updates the value of a file's last modified time attribute.

   315      * Updates a file's last modified time attribute. The file time is converted

   555      *

   316      * to the epoch and precision supported by the file system. Converting from

   556      * <p> The time value is measured since the epoch

   317      * finer to coarser granularities result in precision loss. The behavior of

   557      * (00:00:00 GMT, January 1, 1970) and is converted to the precision supported

   318      * this method when attempting to set a timestamp to a value that is outside

   558      * by the file system. Converting from finer to coarser granularities result

   319      * the range supported by the underlying file store is not defined. It may

   559      * in precision loss.

   320      * or not fail by throwing an {@code IOException}.

   560      *

   321      *

   561      * <p> If the file system does not support a last modified time attribute then

   322      * <p> If the file system does not support a last modified time attribute

   562      * this method has no effect.

   323      * then this method has no effect.

   563      *

   324      *

   564      * @param   file

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

   565      *          A file reference that locates the file

   326      * Suppose we want to set the last modified time to the current time:

   566      *

   327      * <pre>

   328      *    FileTime now = FileTime.fromMillis(System.currentTimeMillis());

   329      *    Attributes.setLastModifiedTime(file, now);

   330      * </pre>

   331      *

   332      * @param   file

   333      *          A file reference that locates the file

   568      *          The new last modified time, or {@code -1L} to update it to

   335      *          The new last modified time

   569      *          the current time

   336      *

   570      * @param   unit

   571      *          A {@code TimeUnit} determining how to interpret the

   572      *          {@code lastModifiedTime} parameter

   573      *

   574      * @throws  IllegalArgumentException

   575      *          If the {@code lastModifiedime} parameter is a negative value other

   576      *          than {@code -1L}

   587                                            long lastModifiedTime,

   347                                            FileTime lastModifiedTime)

   588                                            TimeUnit unit)

   348         throws IOException

   589         throws IOException

   349     {

   590     {

   350         if (lastModifiedTime == null)

   351             throw new NullPointerException("'lastModifiedTime' is null");

   592             .setTimes(lastModifiedTime, null, null, unit);

   353             .setTimes(lastModifiedTime, null, null);

   593     }

   354     }

   594 

   355 

   595     /**

   356     /**

   596      * Updates the value of a file's last access time attribute.

   357      * Updates a file's last access time attribute. The file time is converted

   597      *

   358      * to the epoch and precision supported by the file system. Converting from

   598      * <p> The time value is measured since the epoch

   359      * finer to coarser granularities result in precision loss. The behavior of

   599      * (00:00:00 GMT, January 1, 1970) and is converted to the precision supported

   360      * this method when attempting to set a timestamp to a value that is outside

   600      * by the file system. Converting from finer to coarser granularities result

   361      * the range supported by the underlying file store is not defined. It may

   601      * in precision loss.

   362      * or not fail by throwing an {@code IOException}.

   607      *          The new last access time, or {@code -1L} to update it to

   370      *          The new last access time

   608      *          the current time

   371      *

   609      * @param   unit

   610      *          A {@code TimeUnit} determining how to interpret the

   611      *          {@code lastModifiedTime} parameter

   612      *

   613      * @throws  IllegalArgumentException

   614      *          If the {@code lastAccessTime} parameter is a negative value other

   615      *          than {@code -1L}

   626                                          long lastAccessTime,

   382                                          FileTime lastAccessTime)

   627                                          TimeUnit unit)

   383         throws IOException

   628         throws IOException

   384     {

   629     {

   385         if (lastAccessTime == null)

   386             throw new NullPointerException("'lastAccessTime' is null");

   631             .setTimes(null, lastAccessTime, null, unit);

   388             .setTimes(null, lastAccessTime, null);