src/share/classes/java/nio/file/Files.java

Print this page




1695      *
1696      * <p> <b>Usage Example:</b>
1697      * Suppose we want to set the DOS "hidden" attribute:
1698      * <pre>
1699      *    Path path = ...
1700      *    Files.setAttribute(path, "dos:hidden", true);
1701      * </pre>
1702      *
1703      * @param   path
1704      *          the path to the file
1705      * @param   attribute
1706      *          the attribute to set
1707      * @param   value
1708      *          the attribute value
1709      * @param   options
1710      *          options indicating how symbolic links are handled
1711      *
1712      * @return  the {@code path} parameter
1713      *
1714      * @throws  UnsupportedOperationException
1715      *          if the attribute view is not available or it does not support
1716      *          updating the attribute
1717      * @throws  IllegalArgumentException
1718      *          if the attribute value is of the correct type but has an

1719      *          inappropriate value
1720      * @throws  ClassCastException
1721      *          if the attribute value is not of the expected type or is a
1722      *          collection containing elements that are not of the expected
1723      *          type
1724      * @throws  IOException
1725      *          if an I/O error occurs
1726      * @throws  SecurityException
1727      *          In the case of the default provider, and a security manager is
1728      *          installed, its {@link SecurityManager#checkWrite(String) checkWrite}
1729      *          method denies write access to the file. If this method is invoked
1730      *          to set security sensitive attributes then the security manager
1731      *          may be invoked to check for additional permissions.
1732      */
1733     public static Path setAttribute(Path path, String attribute, Object value,
1734                                     LinkOption... options)
1735         throws IOException
1736     {
1737         provider(path).setAttribute(path, attribute, value, options);
1738         return path;


1759      * are handled for the case that the file is a symbolic link. By default,
1760      * symbolic links are followed and the file attribute of the final target
1761      * of the link is read. If the option {@link LinkOption#NOFOLLOW_LINKS
1762      * NOFOLLOW_LINKS} is present then symbolic links are not followed.
1763      *
1764      * <p> <b>Usage Example:</b>
1765      * Suppose we require the user ID of the file owner on a system that
1766      * supports a "{@code unix}" view:
1767      * <pre>
1768      *    Path path = ...
1769      *    int uid = (Integer)Files.getAttribute(path, "unix:uid");
1770      * </pre>
1771      *
1772      * @param   path
1773      *          the path to the file
1774      * @param   attribute
1775      *          the attribute to read
1776      * @param   options
1777      *          options indicating how symbolic links are handled
1778      *
1779      * @return  the attribute value or {@code null} if the attribute view
1780      *          is not available or it does not support reading the attribute
1781      *




1782      * @throws  IOException
1783      *          if an I/O error occurs
1784      * @throws  SecurityException
1785      *          In the case of the default provider, and a security manager is
1786      *          installed, its {@link SecurityManager#checkRead(String) checkRead}
1787      *          method denies read access to the file. If this method is invoked
1788      *          to read security sensitive attributes then the security manager
1789      *          may be invoked to check for additional permissions.
1790      */
1791     public static Object getAttribute(Path path, String attribute,
1792                                       LinkOption... options)
1793         throws IOException
1794     {
1795         // only one attribute should be read
1796         if (attribute.indexOf('*') >= 0 || attribute.indexOf(',') >= 0)
1797             return null;
1798         Map<String,Object> map = readAttributes(path, attribute, options);

1799         String name;
1800         int pos = attribute.indexOf(':');
1801         if (pos == -1) {
1802             name = attribute;
1803         } else {
1804             name = (pos == attribute.length()) ? "" : attribute.substring(pos+1);
1805         }
1806         return map.get(name);
1807     }
1808 
1809     /**
1810      * Reads a set of file attributes as a bulk operation.
1811      *
1812      * <p> The {@code attributes} parameter identifies the attributes to be read
1813      * and takes the form:
1814      * <blockquote>
1815      * [<i>view-name</i><b>:</b>]<i>attribute-list</i>
1816      * </blockquote>
1817      * where square brackets [...] delineate an optional component and the
1818      * character {@code ':'} stands for itself.


1851      * <tr>
1852      *   <td> {@code "posix:permissions,owner,size"} </td>
1853      *   <td> Reads the POSX file permissions, owner, and file size. </td>
1854      * </tr>
1855      * </table>
1856      * </blockquote>
1857      *
1858      * <p> The {@code options} array may be used to indicate how symbolic links
1859      * are handled for the case that the file is a symbolic link. By default,
1860      * symbolic links are followed and the file attribute of the final target
1861      * of the link is read. If the option {@link LinkOption#NOFOLLOW_LINKS
1862      * NOFOLLOW_LINKS} is present then symbolic links are not followed.
1863      *
1864      * @param   path
1865      *          the path to the file
1866      * @param   attributes
1867      *          the attributes to read
1868      * @param   options
1869      *          options indicating how symbolic links are handled
1870      *
1871      * @return  a map of the attributes returned; may be empty. The map's keys
1872      *          are the attribute names, its values are the attribute values
1873      *





1874      * @throws  IOException
1875      *          if an I/O error occurs
1876      * @throws  SecurityException
1877      *          In the case of the default provider, and a security manager is
1878      *          installed, its {@link SecurityManager#checkRead(String) checkRead}
1879      *          method denies read access to the file. If this method is invoked
1880      *          to read security sensitive attributes then the security manager
1881      *          may be invoke to check for additional permissions.
1882      */
1883     public static Map<String,Object> readAttributes(Path path, String attributes,
1884                                                     LinkOption... options)
1885         throws IOException
1886     {
1887         return provider(path).readAttributes(path, attributes, options);
1888     }
1889 
1890     /**
1891      * Returns a file's POSIX file permissions.
1892      *
1893      * <p> The {@code path} parameter is associated with a {@code FileSystem}




1695      *
1696      * <p> <b>Usage Example:</b>
1697      * Suppose we want to set the DOS "hidden" attribute:
1698      * <pre>
1699      *    Path path = ...
1700      *    Files.setAttribute(path, "dos:hidden", true);
1701      * </pre>
1702      *
1703      * @param   path
1704      *          the path to the file
1705      * @param   attribute
1706      *          the attribute to set
1707      * @param   value
1708      *          the attribute value
1709      * @param   options
1710      *          options indicating how symbolic links are handled
1711      *
1712      * @return  the {@code path} parameter
1713      *
1714      * @throws  UnsupportedOperationException
1715      *          if the attribute view is not available

1716      * @throws  IllegalArgumentException
1717      *          if the attribute name is not specified, or is not recognized, or 
1718      *          the attribute value is of the correct type but has an 
1719      *          inappropriate value
1720      * @throws  ClassCastException
1721      *          if the attribute value is not of the expected type or is a
1722      *          collection containing elements that are not of the expected
1723      *          type
1724      * @throws  IOException
1725      *          if an I/O error occurs
1726      * @throws  SecurityException
1727      *          In the case of the default provider, and a security manager is
1728      *          installed, its {@link SecurityManager#checkWrite(String) checkWrite}
1729      *          method denies write access to the file. If this method is invoked
1730      *          to set security sensitive attributes then the security manager
1731      *          may be invoked to check for additional permissions.
1732      */
1733     public static Path setAttribute(Path path, String attribute, Object value,
1734                                     LinkOption... options)
1735         throws IOException
1736     {
1737         provider(path).setAttribute(path, attribute, value, options);
1738         return path;


1759      * are handled for the case that the file is a symbolic link. By default,
1760      * symbolic links are followed and the file attribute of the final target
1761      * of the link is read. If the option {@link LinkOption#NOFOLLOW_LINKS
1762      * NOFOLLOW_LINKS} is present then symbolic links are not followed.
1763      *
1764      * <p> <b>Usage Example:</b>
1765      * Suppose we require the user ID of the file owner on a system that
1766      * supports a "{@code unix}" view:
1767      * <pre>
1768      *    Path path = ...
1769      *    int uid = (Integer)Files.getAttribute(path, "unix:uid");
1770      * </pre>
1771      *
1772      * @param   path
1773      *          the path to the file
1774      * @param   attribute
1775      *          the attribute to read
1776      * @param   options
1777      *          options indicating how symbolic links are handled
1778      *
1779      * @return  the attribute value

1780      *
1781      * @throws  UnsupportedOperationException
1782      *          if the attribute view is not available
1783      * @throws  IllegalArgumentException
1784      *          if the attribute name is not specified or is not recognized
1785      * @throws  IOException
1786      *          if an I/O error occurs
1787      * @throws  SecurityException
1788      *          In the case of the default provider, and a security manager is
1789      *          installed, its {@link SecurityManager#checkRead(String) checkRead}
1790      *          method denies read access to the file. If this method is invoked
1791      *          to read security sensitive attributes then the security manager
1792      *          may be invoked to check for additional permissions.
1793      */
1794     public static Object getAttribute(Path path, String attribute,
1795                                       LinkOption... options)
1796         throws IOException
1797     {
1798         // only one attribute should be read
1799         if (attribute.indexOf('*') >= 0 || attribute.indexOf(',') >= 0)
1800             throw new IllegalArgumentException(attribute);
1801         Map<String,Object> map = readAttributes(path, attribute, options);
1802         assert map.size() == 1;
1803         String name;
1804         int pos = attribute.indexOf(':');
1805         if (pos == -1) {
1806             name = attribute;
1807         } else {
1808             name = (pos == attribute.length()) ? "" : attribute.substring(pos+1);
1809         }
1810         return map.get(name);
1811     }
1812 
1813     /**
1814      * Reads a set of file attributes as a bulk operation.
1815      *
1816      * <p> The {@code attributes} parameter identifies the attributes to be read
1817      * and takes the form:
1818      * <blockquote>
1819      * [<i>view-name</i><b>:</b>]<i>attribute-list</i>
1820      * </blockquote>
1821      * where square brackets [...] delineate an optional component and the
1822      * character {@code ':'} stands for itself.


1855      * <tr>
1856      *   <td> {@code "posix:permissions,owner,size"} </td>
1857      *   <td> Reads the POSX file permissions, owner, and file size. </td>
1858      * </tr>
1859      * </table>
1860      * </blockquote>
1861      *
1862      * <p> The {@code options} array may be used to indicate how symbolic links
1863      * are handled for the case that the file is a symbolic link. By default,
1864      * symbolic links are followed and the file attribute of the final target
1865      * of the link is read. If the option {@link LinkOption#NOFOLLOW_LINKS
1866      * NOFOLLOW_LINKS} is present then symbolic links are not followed.
1867      *
1868      * @param   path
1869      *          the path to the file
1870      * @param   attributes
1871      *          the attributes to read
1872      * @param   options
1873      *          options indicating how symbolic links are handled
1874      *
1875      * @return  a map of the attributes returned; The map's keys are the
1876      *          attribute names, its values are the attribute values
1877      *
1878      * @throws  UnsupportedOperationException
1879      *          if the attribute view is not available
1880      * @throws  IllegalArgumentException
1881      *          if no attributes are specified or an unrecognized attributes is
1882      *          specified
1883      * @throws  IOException
1884      *          if an I/O error occurs
1885      * @throws  SecurityException
1886      *          In the case of the default provider, and a security manager is
1887      *          installed, its {@link SecurityManager#checkRead(String) checkRead}
1888      *          method denies read access to the file. If this method is invoked
1889      *          to read security sensitive attributes then the security manager
1890      *          may be invoke to check for additional permissions.
1891      */
1892     public static Map<String,Object> readAttributes(Path path, String attributes,
1893                                                     LinkOption... options)
1894         throws IOException
1895     {
1896         return provider(path).readAttributes(path, attributes, options);
1897     }
1898 
1899     /**
1900      * Returns a file's POSIX file permissions.
1901      *
1902      * <p> The {@code path} parameter is associated with a {@code FileSystem}