< prev index next >
src/java.base/share/classes/java/io/File.java
Print this page
*** 80,94 ****
* virtual machine was invoked.
*
* <p> The <em>parent</em> of an abstract pathname may be obtained by invoking
* the {@link #getParent} method of this class and consists of the pathname's
* prefix and each name in the pathname's name sequence except for the last.
! * Each directory's absolute pathname is an ancestor of any <tt>File</tt>
* object with an absolute abstract pathname which begins with the directory's
* absolute pathname. For example, the directory denoted by the abstract
! * pathname <tt>"/usr"</tt> is an ancestor of the directory denoted by the
! * pathname <tt>"/usr/local/bin"</tt>.
*
* <p> The prefix concept is used to handle root directories on UNIX platforms,
* and drive specifiers, root directories and UNC pathnames on Microsoft Windows platforms,
* as follows:
*
--- 80,94 ----
* virtual machine was invoked.
*
* <p> The <em>parent</em> of an abstract pathname may be obtained by invoking
* the {@link #getParent} method of this class and consists of the pathname's
* prefix and each name in the pathname's name sequence except for the last.
! * Each directory's absolute pathname is an ancestor of any {@code File}
* object with an absolute abstract pathname which begins with the directory's
* absolute pathname. For example, the directory denoted by the abstract
! * pathname {@code "/usr"} is an ancestor of the directory denoted by the
! * pathname {@code "/usr/local/bin"}.
*
* <p> The prefix concept is used to handle root directories on UNIX platforms,
* and drive specifiers, root directories and UNC pathnames on Microsoft Windows platforms,
* as follows:
*
*** 372,408 ****
}
this.prefixLength = fs.prefixLength(this.path);
}
/**
! * Creates a new <tt>File</tt> instance by converting the given
! * <tt>file:</tt> URI into an abstract pathname.
*
! * <p> The exact form of a <tt>file:</tt> URI is system-dependent, hence
* the transformation performed by this constructor is also
* system-dependent.
*
* <p> For a given abstract pathname <i>f</i> it is guaranteed that
*
! * <blockquote><tt>
! * new File(</tt><i> f</i><tt>.{@link #toURI() toURI}()).equals(</tt><i> f</i><tt>.{@link #getAbsoluteFile() getAbsoluteFile}())
! * </tt></blockquote>
*
* so long as the original abstract pathname, the URI, and the new abstract
* pathname are all created in (possibly different invocations of) the same
* Java virtual machine. This relationship typically does not hold,
! * however, when a <tt>file:</tt> URI that is created in a virtual machine
* on one operating system is converted into an abstract pathname in a
* virtual machine on a different operating system.
*
* @param uri
* An absolute, hierarchical URI with a scheme equal to
! * <tt>"file"</tt>, a non-empty path component, and undefined
* authority, query, and fragment components
*
* @throws NullPointerException
! * If <tt>uri</tt> is <tt>null</tt>
*
* @throws IllegalArgumentException
* If the preconditions on the parameter do not hold
*
* @see #toURI()
--- 372,410 ----
}
this.prefixLength = fs.prefixLength(this.path);
}
/**
! * Creates a new {@code File} instance by converting the given
! * {@code file:} URI into an abstract pathname.
*
! * <p> The exact form of a {@code file:} URI is system-dependent, hence
* the transformation performed by this constructor is also
* system-dependent.
*
* <p> For a given abstract pathname <i>f</i> it is guaranteed that
*
! * <blockquote><code>
! * new File(</code><i> f</i><code>.{@link
! * #toURI() toURI}()).equals(</code><i> f</i><code>.{@link
! * #getAbsoluteFile() getAbsoluteFile}())
! * </code></blockquote>
*
* so long as the original abstract pathname, the URI, and the new abstract
* pathname are all created in (possibly different invocations of) the same
* Java virtual machine. This relationship typically does not hold,
! * however, when a {@code file:} URI that is created in a virtual machine
* on one operating system is converted into an abstract pathname in a
* virtual machine on a different operating system.
*
* @param uri
* An absolute, hierarchical URI with a scheme equal to
! * {@code "file"}, a non-empty path component, and undefined
* authority, query, and fragment components
*
* @throws NullPointerException
! * If {@code uri} is {@code null}
*
* @throws IllegalArgumentException
* If the preconditions on the parameter do not hold
*
* @see #toURI()
*** 579,589 ****
* <p> A canonical pathname is both absolute and unique. The precise
* definition of canonical form is system-dependent. This method first
* converts this pathname to absolute form if necessary, as if by invoking the
* {@link #getAbsolutePath} method, and then maps it to its unique form in a
* system-dependent way. This typically involves removing redundant names
! * such as <tt>"."</tt> and <tt>".."</tt> from the pathname, resolving
* symbolic links (on UNIX platforms), and converting drive letters to a
* standard case (on Microsoft Windows platforms).
*
* <p> Every pathname that denotes an existing file or directory has a
* unique canonical form. Every pathname that denotes a nonexistent file
--- 581,591 ----
* <p> A canonical pathname is both absolute and unique. The precise
* definition of canonical form is system-dependent. This method first
* converts this pathname to absolute form if necessary, as if by invoking the
* {@link #getAbsolutePath} method, and then maps it to its unique form in a
* system-dependent way. This typically involves removing redundant names
! * such as {@code "."} and {@code ".."} from the pathname, resolving
* symbolic links (on UNIX platforms), and converting drive letters to a
* standard case (on Microsoft Windows platforms).
*
* <p> Every pathname that denotes an existing file or directory has a
* unique canonical form. Every pathname that denotes a nonexistent file
*** 685,711 ****
}
return new URL("file", "", slashify(getAbsolutePath(), isDirectory()));
}
/**
! * Constructs a <tt>file:</tt> URI that represents this abstract pathname.
*
* <p> The exact form of the URI is system-dependent. If it can be
* determined that the file denoted by this abstract pathname is a
* directory, then the resulting URI will end with a slash.
*
* <p> For a given abstract pathname <i>f</i>, it is guaranteed that
*
! * <blockquote><tt>
! * new {@link #File(java.net.URI) File}(</tt><i> f</i><tt>.toURI()).equals(</tt><i> f</i><tt>.{@link #getAbsoluteFile() getAbsoluteFile}())
! * </tt></blockquote>
*
* so long as the original abstract pathname, the URI, and the new abstract
* pathname are all created in (possibly different invocations of) the same
* Java virtual machine. Due to the system-dependent nature of abstract
* pathnames, however, this relationship typically does not hold when a
! * <tt>file:</tt> URI that is created in a virtual machine on one operating
* system is converted into an abstract pathname in a virtual machine on a
* different operating system.
*
* <p> Note that when this abstract pathname represents a UNC pathname then
* all components of the UNC (including the server name component) are encoded
--- 687,714 ----
}
return new URL("file", "", slashify(getAbsolutePath(), isDirectory()));
}
/**
! * Constructs a {@code file:} URI that represents this abstract pathname.
*
* <p> The exact form of the URI is system-dependent. If it can be
* determined that the file denoted by this abstract pathname is a
* directory, then the resulting URI will end with a slash.
*
* <p> For a given abstract pathname <i>f</i>, it is guaranteed that
*
! * <blockquote><code>
! * new {@link #File(java.net.URI) File}(</code><i> f</i>{@code
! * .toURI()).equals(}<i> f</i><code>.{@link #getAbsoluteFile() getAbsoluteFile}())
! * </code></blockquote>
*
* so long as the original abstract pathname, the URI, and the new abstract
* pathname are all created in (possibly different invocations of) the same
* Java virtual machine. Due to the system-dependent nature of abstract
* pathnames, however, this relationship typically does not hold when a
! * {@code file:} URI that is created in a virtual machine on one operating
* system is converted into an abstract pathname in a virtual machine on a
* different operating system.
*
* <p> Note that when this abstract pathname represents a UNC pathname then
* all components of the UNC (including the server name component) are encoded
*** 714,724 ****
* {@link Path#toUri toUri} method to encode the server name in the authority
* component of the resulting {@code URI}. The {@link #toPath toPath} method
* may be used to obtain a {@code Path} representing this abstract pathname.
*
* @return An absolute, hierarchical URI with a scheme equal to
! * <tt>"file"</tt>, a path representing this abstract pathname,
* and undefined authority, query, and fragment components
* @throws SecurityException If a required system property value cannot
* be accessed.
*
* @see #File(java.net.URI)
--- 717,727 ----
* {@link Path#toUri toUri} method to encode the server name in the authority
* component of the resulting {@code URI}. The {@link #toPath toPath} method
* may be used to obtain a {@code Path} representing this abstract pathname.
*
* @return An absolute, hierarchical URI with a scheme equal to
! * {@code "file"}, a path representing this abstract pathname,
* and undefined authority, query, and fragment components
* @throws SecurityException If a required system property value cannot
* be accessed.
*
* @see #File(java.net.URI)
*** 1512,1526 ****
* A convenience method to set the owner's write permission for this abstract
* pathname. On some platforms it may be possible to start the Java virtual
* machine with special privileges that allow it to modify files that
* disallow write operations.
*
! * <p> An invocation of this method of the form <tt>file.setWritable(arg)</tt>
* behaves in exactly the same way as the invocation
*
! * <pre>
! * file.setWritable(arg, true) </pre>
*
* @param writable
* If <code>true</code>, sets the access permission to allow write
* operations; if <code>false</code> to disallow write operations
*
--- 1515,1530 ----
* A convenience method to set the owner's write permission for this abstract
* pathname. On some platforms it may be possible to start the Java virtual
* machine with special privileges that allow it to modify files that
* disallow write operations.
*
! * <p> An invocation of this method of the form {@code file.setWritable(arg)}
* behaves in exactly the same way as the invocation
*
! * <pre>{@code
! * file.setWritable(arg, true)
! * }</pre>
*
* @param writable
* If <code>true</code>, sets the access permission to allow write
* operations; if <code>false</code> to disallow write operations
*
*** 1589,1603 ****
* A convenience method to set the owner's read permission for this abstract
* pathname. On some platforms it may be possible to start the Java virtual
* machine with special privileges that allow it to read files that are
* marked as unreadable.
*
! * <p>An invocation of this method of the form <tt>file.setReadable(arg)</tt>
* behaves in exactly the same way as the invocation
*
! * <pre>
! * file.setReadable(arg, true) </pre>
*
* @param readable
* If <code>true</code>, sets the access permission to allow read
* operations; if <code>false</code> to disallow read operations
*
--- 1593,1608 ----
* A convenience method to set the owner's read permission for this abstract
* pathname. On some platforms it may be possible to start the Java virtual
* machine with special privileges that allow it to read files that are
* marked as unreadable.
*
! * <p>An invocation of this method of the form {@code file.setReadable(arg)}
* behaves in exactly the same way as the invocation
*
! * <pre>{@code
! * file.setReadable(arg, true)
! * }</pre>
*
* @param readable
* If <code>true</code>, sets the access permission to allow read
* operations; if <code>false</code> to disallow read operations
*
*** 1669,1683 ****
* A convenience method to set the owner's execute permission for this
* abstract pathname. On some platforms it may be possible to start the Java
* virtual machine with special privileges that allow it to execute files
* that are not marked executable.
*
! * <p>An invocation of this method of the form <tt>file.setExcutable(arg)</tt>
* behaves in exactly the same way as the invocation
*
! * <pre>
! * file.setExecutable(arg, true) </pre>
*
* @param executable
* If <code>true</code>, sets the access permission to allow execute
* operations; if <code>false</code> to disallow execute operations
*
--- 1674,1689 ----
* A convenience method to set the owner's execute permission for this
* abstract pathname. On some platforms it may be possible to start the Java
* virtual machine with special privileges that allow it to execute files
* that are not marked executable.
*
! * <p>An invocation of this method of the form {@code file.setExcutable(arg)}
* behaves in exactly the same way as the invocation
*
! * <pre>{@code
! * file.setExecutable(arg, true)
! * }</pre>
*
* @param executable
* If <code>true</code>, sets the access permission to allow execute
* operations; if <code>false</code> to disallow execute operations
*
*** 1781,1796 ****
/**
* Returns the size of the partition <a href="#partName">named</a> by this
* abstract pathname.
*
! * @return The size, in bytes, of the partition or <tt>0L</tt> if this
* abstract pathname does not name a partition
*
* @throws SecurityException
* If a security manager has been installed and it denies
! * {@link RuntimePermission}<tt>("getFileSystemAttributes")</tt>
* or its {@link SecurityManager#checkRead(String)} method denies
* read access to the file named by this abstract pathname
*
* @since 1.6
*/
--- 1787,1802 ----
/**
* Returns the size of the partition <a href="#partName">named</a> by this
* abstract pathname.
*
! * @return The size, in bytes, of the partition or {@code 0L} if this
* abstract pathname does not name a partition
*
* @throws SecurityException
* If a security manager has been installed and it denies
! * {@link RuntimePermission}{@code ("getFileSystemAttributes")}
* or its {@link SecurityManager#checkRead(String)} method denies
* read access to the file named by this abstract pathname
*
* @since 1.6
*/
*** 1817,1834 ****
* inaccurate by any external I/O operations including those made
* on the system outside of this virtual machine. This method
* makes no guarantee that write operations to this file system
* will succeed.
*
! * @return The number of unallocated bytes on the partition or <tt>0L</tt>
* if the abstract pathname does not name a partition. This
* value will be less than or equal to the total file system size
* returned by {@link #getTotalSpace}.
*
* @throws SecurityException
* If a security manager has been installed and it denies
! * {@link RuntimePermission}<tt>("getFileSystemAttributes")</tt>
* or its {@link SecurityManager#checkRead(String)} method denies
* read access to the file named by this abstract pathname
*
* @since 1.6
*/
--- 1823,1840 ----
* inaccurate by any external I/O operations including those made
* on the system outside of this virtual machine. This method
* makes no guarantee that write operations to this file system
* will succeed.
*
! * @return The number of unallocated bytes on the partition or {@code 0L}
* if the abstract pathname does not name a partition. This
* value will be less than or equal to the total file system size
* returned by {@link #getTotalSpace}.
*
* @throws SecurityException
* If a security manager has been installed and it denies
! * {@link RuntimePermission}{@code ("getFileSystemAttributes")}
* or its {@link SecurityManager#checkRead(String)} method denies
* read access to the file named by this abstract pathname
*
* @since 1.6
*/
*** 1858,1875 ****
* after this call. It is likely to be made inaccurate by any external
* I/O operations including those made on the system outside of this
* virtual machine. This method makes no guarantee that write operations
* to this file system will succeed.
*
! * @return The number of available bytes on the partition or <tt>0L</tt>
* if the abstract pathname does not name a partition. On
* systems where this information is not available, this method
* will be equivalent to a call to {@link #getFreeSpace}.
*
* @throws SecurityException
* If a security manager has been installed and it denies
! * {@link RuntimePermission}<tt>("getFileSystemAttributes")</tt>
* or its {@link SecurityManager#checkRead(String)} method denies
* read access to the file named by this abstract pathname
*
* @since 1.6
*/
--- 1864,1881 ----
* after this call. It is likely to be made inaccurate by any external
* I/O operations including those made on the system outside of this
* virtual machine. This method makes no guarantee that write operations
* to this file system will succeed.
*
! * @return The number of available bytes on the partition or {@code 0L}
* if the abstract pathname does not name a partition. On
* systems where this information is not available, this method
* will be equivalent to a call to {@link #getFreeSpace}.
*
* @throws SecurityException
* If a security manager has been installed and it denies
! * {@link RuntimePermission}{@code ("getFileSystemAttributes")}
* or its {@link SecurityManager#checkRead(String)} method denies
* read access to the file named by this abstract pathname
*
* @since 1.6
*/
< prev index next >