diff -r 5e6af6d106cb -r 80dfe4469bbd jdk/src/share/classes/java/nio/file/Path.java
--- a/jdk/src/share/classes/java/nio/file/Path.java Tue Feb 24 09:11:42 2009 +0000
+++ b/jdk/src/share/classes/java/nio/file/Path.java Tue Feb 24 11:31:04 2009 +0000
@@ -37,7 +37,8 @@
*
*
On many platforms a path is the means to locate and access files
* in a file system. A path is hierarchical and composed of a sequence of
- * directory names separated by a special separator or delimiter.
+ * directory and file name elements separated by a special separator or
+ * delimiter.
*
*
Path operations
*
@@ -141,7 +142,7 @@
/**
* Returns the file system that created this object.
*
- * @return The file system that created this object
+ * @return the file system that created this object
*/
public abstract FileSystem getFileSystem();
@@ -159,7 +160,7 @@
* Returns the root component of this path as a {@code Path} object,
* or {@code null} if this path does not have a root component.
*
- * @return A path representing the root component of this path,
+ * @return a path representing the root component of this path,
* or {@code null}
*/
public abstract Path getRoot();
@@ -169,7 +170,7 @@
* file name is the farthest element from the root in the directory
* hierarchy.
*
- * @return A path representing the name of the file or directory, or
+ * @return a path representing the name of the file or directory, or
* {@code null} if this path has zero elements
*/
public abstract Path getName();
@@ -195,14 +196,14 @@
* subpath(0, getNameCount()-1);
*
*
- * @return A path representing the path's parent
+ * @return a path representing the path's parent
*/
public abstract Path getParent();
/**
* Returns the number of name elements in the path.
*
- * @return The number of elements in the path, or {@code 0} if this path
+ * @return the number of elements in the path, or {@code 0} if this path
* only represents a root component
*/
public abstract int getNameCount();
@@ -216,14 +217,14 @@
* has index {@link #getNameCount count}{@code -1}.
*
* @param index
- * The index of the element
+ * the index of the element
*
- * @return The name element
+ * @return the name element
*
* @throws IllegalArgumentException
- * If {@code index} is negative, {@code index} is greater than or
+ * if {@code index} is negative, {@code index} is greater than or
* equal to the number of elements, or this path has zero name
- * elements.
+ * elements
*/
public abstract Path getName(int index);
@@ -240,15 +241,15 @@
* endIndex-1}.
*
* @param beginIndex
- * The index of the first element, inclusive
+ * the index of the first element, inclusive
* @param endIndex
- * The index of the last element, exclusive
+ * the index of the last element, exclusive
*
- * @return A new {@code Path} object that is a subsequence of the name
+ * @return a new {@code Path} object that is a subsequence of the name
* elements in this {@code Path}
*
* @throws IllegalArgumentException
- * If {@code beginIndex} is negative, or greater than or equal to
+ * if {@code beginIndex} is negative, or greater than or equal to
* the number of elements. If {@code endIndex} is less than or
* equal to {@code beginIndex}, or larger than the number of elements.
*/
@@ -269,7 +270,7 @@
* this path does not start with the given path.
*
* @param other
- * The given path
+ * the given path
*
* @return {@code true} if this path starts with the given path; otherwise
* {@code false}
@@ -293,7 +294,7 @@
* then this path does not end with the given path.
*
* @param other
- * The given path
+ * the given path
*
* @return {@code true} if this path ends with the given path; otherwise
* {@code false}
@@ -318,9 +319,9 @@
* path may result in the path that locates a different file than the original
* path. This can arise when the preceding name is a symbolic link.
*
- * @return The resulting path, or this path if it does not contain
+ * @return the resulting path, or this path if it does not contain
* redundant name elements, or {@code null} if this path does not
- * have a root component and all name elements are redundant.
+ * have a root component and all name elements are redundant
*
* @see #getParent
* @see #toRealPath
@@ -344,9 +345,9 @@
* unspecified.
*
* @param other
- * The path to resolve against this path; can be {@code null}
+ * the path to resolve against this path; can be {@code null}
*
- * @return The resulting path
+ * @return the resulting path
*
* @see #relativize
*/
@@ -358,9 +359,9 @@
* #resolve(Path) resolve} method.
*
* @param other
- * The path string to resolve against this path
+ * the path string to resolve against this path
*
- * @return The resulting path
+ * @return the resulting path
*
* @throws InvalidPathException
* If the path string cannot be converted to a Path.
@@ -400,13 +401,13 @@
* dependent if {@code "a/b/../x"} would locate the same file as {@code "/a/x"}.
*
* @param other
- * The resulting path
+ * the resulting path
*
- * @return The resulting relative path, or {@code null} if both paths are
+ * @return the resulting relative path, or {@code null} if both paths are
* equal
*
* @throws IllegalArgumentException
- * If {@code other} is not a {@code Path} that can be relativized
+ * if {@code other} is not a {@code Path} that can be relativized
* against this path
*/
public abstract Path relativize(Path other);
@@ -440,18 +441,18 @@
* exist
*
* @throws NoSuchFileException
- * If the value of the {@code failIfNotExists} is {@code true} and
+ * if the value of the {@code failIfNotExists} is {@code true} and
* the file does not exist (optional specific exception)
* @throws DirectoryNotEmptyException
- * If the file is a directory and could not otherwise be deleted
+ * if the file is a directory and could not otherwise be deleted
* because the directory is not empty (optional specific
* exception)
* @throws IOException
- * If an I/O error occurs
+ * if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkDelete(String)} method
- * is invoked to check delete access to the file
+ * is invoked to check delete access to the file.
*/
public abstract void delete(boolean failIfNotExists) throws IOException;
@@ -476,22 +477,22 @@
* create symbolic links, in which case this method may throw {@code IOException}.
*
* @param target
- * The target of the link
+ * the target of the link
* @param attrs
- * The array of attributes to set atomically when creating the
+ * the array of attributes to set atomically when creating the
* symbolic link
*
* @return this path
*
* @throws UnsupportedOperationException
- * If the implementation does not support symbolic links or the
+ * if the implementation does not support symbolic links or the
* array contains an attribute that cannot be set atomically when
* creating the symbolic link
* @throws FileAlreadyExistsException
- * If a file with the name already exists (optional specific
+ * if a file with the name already exists (optional specific
* exception)
* @throws IOException
- * If an I/O error occurs
+ * if an I/O error occurs
* @throws SecurityException
* In the case of the the default provider, and a security manager
* is installed, it denies {@link LinkPermission}("symbolic")
@@ -517,24 +518,24 @@
* create hard links or to create links to directories.
*
* @param existing
- * A reference to an existing file
+ * a reference to an existing file
*
* @return this path
*
* @throws UnsupportedOperationException
- * If the implementation does not support adding an existing file
+ * if the implementation does not support adding an existing file
* to a directory
* @throws FileAlreadyExistsException
- * If the entry could not otherwise be created because a file of
+ * if the entry could not otherwise be created because a file of
* that name already exists (optional specific exception)
* @throws IOException
- * If an I/O error occurs
+ * if an I/O error occurs
* @throws SecurityException
* In the case of the the default provider, and a security manager
* is installed, it denies {@link LinkPermission}("hard")
* or its {@link SecurityManager#checkWrite(String) checkWrite}
* method denies write access to both this path and the path of the
- * existing file
+ * existing file.
*
* @see BasicFileAttributes#linkCount
*/
@@ -549,15 +550,15 @@
* returned {@code Path} object will be associated with the same file
* system as this {@code Path}.
*
- * @return A {@code Path} object representing the target of the link
+ * @return a {@code Path} object representing the target of the link
*
* @throws UnsupportedOperationException
- * If the implementation does not support symbolic links
+ * if the implementation does not support symbolic links
* @throws NotLinkException
- * If the target could otherwise not be read because the file
+ * if the target could otherwise not be read because the file
* is not a link (optional specific exception)
* @throws IOException
- * If an I/O error occurs
+ * if an I/O error occurs
* @throws SecurityException
* In the case of the the default provider, and a security manager
* is installed, it checks that {@code FilePermission} has been
@@ -605,13 +606,13 @@
* A format for compound URIs is not defined in this release; such a scheme
* may be added in a future release.
*
- * @return An absolute, hierarchical URI with a non-empty path component
+ * @return an absolute, hierarchical URI with a non-empty path component
*
* @throws IOError
- * If an I/O error occurs obtaining the absolute path, or where a
+ * if an I/O error occurs obtaining the absolute path, or where a
* file system is constructed to access the contents of a file as
- * a file system, the URI of the enclosing file system cannot be
- * obtained.
+ * a file system, and the URI of the enclosing file system cannot be
+ * obtained
*
* @throws SecurityException
* In the case of the the default provider, and a security manager
@@ -630,10 +631,10 @@
* against a file system default directory. Depending on the implementation,
* this method may throw an I/O error if the file system is not accessible.
*
- * @return A {@code Path} object representing the absolute path
+ * @return a {@code Path} object representing the absolute path
*
* @throws IOError
- * If an I/O error occurs
+ * if an I/O error occurs
* @throws SecurityException
* In the case of the the default provider, and a security manager
* is installed, its {@link SecurityManager#checkPropertyAccess(String)
@@ -670,11 +671,11 @@
* name is a symbolic link then the names are only removed if it guaranteed
* that the resulting path will locate the same file as this path.
*
- * @return An absolute path represent the real path of the file
+ * @return an absolute path represent the real path of the file
* located by this object
*
* @throws IOException
- * If the file does not exist or an I/O error occurs
+ * if the file does not exist or an I/O error occurs
* @throws SecurityException
* In the case of the the default provider, and a security manager
* is installed, its {@link SecurityManager#checkRead(String) checkRead}
@@ -743,20 +744,20 @@
* file system activities.
*
* @param target
- * The target location
+ * the target location
* @param options
- * Options specifying how the copy should be done
+ * options specifying how the copy should be done
*
- * @return The target
+ * @return the target
*
* @throws UnsupportedOperationException
- * If the array contains a copy option that is not supported
+ * if the array contains a copy option that is not supported
* @throws FileAlreadyExistsException
- * The target file exists and cannot be replaced because the
+ * if the target file exists and cannot be replaced because the
* {@code REPLACE_EXISTING} option is not specified, or the target
* file is a non-empty directory (optional specific exception)
* @throws IOException
- * If an I/O error occurs
+ * if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkRead(String) checkRead}
@@ -829,23 +830,23 @@
* original file.
*
* @param target
- * The target location
+ * the target location
* @param options
- * Options specifying how the move should be done
+ * options specifying how the move should be done
*
- * @return The target
+ * @return the target
*
* @throws UnsupportedOperationException
- * If the array contains a copy option that is not supported
+ * if the array contains a copy option that is not supported
* @throws FileAlreadyExistsException
- * The target file exists and cannot be replaced because the
+ * if the target file exists and cannot be replaced because the
* {@code REPLACE_EXISTING} option is not specified, or the target
* file is a non-empty directory
* @throws AtomicMoveNotSupportedException
- * The options array contains the {@code ATOMIC_MOVE} option but
+ * if the options array contains the {@code ATOMIC_MOVE} option but
* the file cannot be moved as an atomic file system operation.
* @throws IOException
- * If an I/O error occurs
+ * if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkWrite(String) checkWrite}
@@ -875,13 +876,13 @@
* directory that execute in a race-free manner then the returned directory
* stream is a {@link SecureDirectoryStream}.
*
- * @return A new and open {@code DirectoryStream} object
+ * @return a new and open {@code DirectoryStream} object
*
* @throws NotDirectoryException
- * If the file could not otherwise be opened because it is not
+ * if the file could not otherwise be opened because it is not
* a directory (optional specific exception)
* @throws IOException
- * If an I/O error occurs
+ * if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkRead(String) checkRead}
@@ -920,19 +921,19 @@
* stream is a {@link SecureDirectoryStream}.
*
* @param glob
- * The glob pattern
+ * the glob pattern
*
- * @return A new and open {@code DirectoryStream} object
+ * @return a new and open {@code DirectoryStream} object
*
* @throws java.util.regex.PatternSyntaxException
- * If the pattern is invalid
+ * if the pattern is invalid
* @throws UnsupportedOperationException
- * If the pattern syntax is not known to the implementation
+ * if the pattern syntax is not known to the implementation
* @throws NotDirectoryException
- * If the file could not otherwise be opened because it is not
+ * if the file could not otherwise be opened because it is not
* a directory (optional specific exception)
* @throws IOException
- * If an I/O error occurs
+ * if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkRead(String) checkRead}
@@ -986,15 +987,15 @@
* DirectoryStream<Path> stream = dir.newDirectoryStream(filter);
*
* @param filter
- * The directory stream filter
+ * the directory stream filter
*
- * @return A new and open {@code DirectoryStream} object
+ * @return a new and open {@code DirectoryStream} object
*
* @throws NotDirectoryException
- * If the file could not otherwise be opened because it is not
+ * if the file could not otherwise be opened because it is not
* a directory (optional specific exception)
* @throws IOException
- * If an I/O error occurs
+ * if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkRead(String) checkRead}
@@ -1018,19 +1019,19 @@
* occurrence is ignored.
*
* @param attrs
- * An optional list of file attributes to set atomically when
+ * an optional list of file attributes to set atomically when
* creating the file
*
- * @return This path
+ * @return this path
*
* @throws UnsupportedOperationException
- * If the array contains an attribute that cannot be set atomically
+ * if the array contains an attribute that cannot be set atomically
* when creating the file
* @throws FileAlreadyExistsException
- * If a file of that name already exists
+ * if a file of that name already exists
* (optional specific exception)
* @throws IOException
- * If an I/O error occurs
+ * if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkWrite(String) checkWrite}
@@ -1053,19 +1054,19 @@
* but the last occurrence is ignored.
*
* @param attrs
- * An optional list of file attributes to set atomically when
+ * an optional list of file attributes to set atomically when
* creating the directory
*
- * @return This path
+ * @return this path
*
* @throws UnsupportedOperationException
- * If the array contains an attribute that cannot be set atomically
+ * if the array contains an attribute that cannot be set atomically
* when creating the directory
* @throws FileAlreadyExistsException
- * If a directory could not otherwise be created because a file of
+ * if a directory could not otherwise be created because a file of
* that name already exists (optional specific exception)
* @throws IOException
- * If an I/O error occurs
+ * if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkWrite(String) checkWrite}
@@ -1185,16 +1186,16 @@
* @return a new seekable byte channel
*
* @throws IllegalArgumentException
- * If the set contains an invalid combination of options
+ * if the set contains an invalid combination of options
* @throws UnsupportedOperationException
- * If an unsupported open option is specified or the array contains
+ * if an unsupported open option is specified or the array contains
* attributes that cannot be set atomically when creating the file
* @throws FileAlreadyExistsException
- * If a file of that name already exists and the {@link
+ * if a file of that name already exists and the {@link
* StandardOpenOption#CREATE_NEW CREATE_NEW} option is specified
* (optional specific exception)
* @throws IOException
- * If an I/O error occurs
+ * if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkRead(String) checkRead}
@@ -1219,16 +1220,16 @@
* FileChannel}.
*
* @param options
- * Options specifying how the file is opened
+ * options specifying how the file is opened
*
* @return a new seekable byte channel
*
* @throws IllegalArgumentException
- * If the set contains an invalid combination of options
+ * if the set contains an invalid combination of options
* @throws UnsupportedOperationException
- * If an unsupported open option is specified
+ * if an unsupported open option is specified
* @throws FileAlreadyExistsException
- * If a file of that name already exists and the {@link
+ * if a file of that name already exists and the {@link
* StandardOpenOption#CREATE_NEW CREATE_NEW} option is specified
* (optional specific exception)
* @throws IOException {@inheritDoc}
@@ -1245,10 +1246,10 @@
* InputStream#reset reset} methods. The stream will be safe for access by
* multiple concurrent threads. Reading commences at the beginning of the file.
*
- * @return An input stream to read bytes from the file
+ * @return an input stream to read bytes from the file
*
* @throws IOException
- * If an I/O error occurs
+ * if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkRead(String) checkRead}
@@ -1279,16 +1280,16 @@
*
*
* @param options
- * Options specifying how the file is opened
+ * options specifying how the file is opened
*
* @return a new seekable byte channel
*
* @throws IllegalArgumentException
- * If {@code options} contains an invalid combination of options
+ * if {@code options} contains an invalid combination of options
* @throws UnsupportedOperationException
- * If an unsupported open option is specified
+ * if an unsupported open option is specified
* @throws IOException
- * If an I/O error occurs
+ * if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkWrite(String) checkWrite}
@@ -1312,20 +1313,20 @@
* for access by multiple concurrent threads.
*
* @param options
- * Options specifying how the file is opened
+ * options specifying how the file is opened
* @param attrs
- * An optional list of file attributes to set atomically when
+ * an optional list of file attributes to set atomically when
* creating the file
*
- * @return A new output stream
+ * @return a new output stream
*
* @throws IllegalArgumentException
- * If the set contains an invalid combination of options
+ * if the set contains an invalid combination of options
* @throws UnsupportedOperationException
- * If an unsupported open option is specified or the array contains
+ * if an unsupported open option is specified or the array contains
* attributes that cannot be set atomically when creating the file
* @throws IOException
- * If an I/O error occurs
+ * if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkWrite(String) checkWrite}
@@ -1349,7 +1350,7 @@
* @return {@code true} if the file is considered hidden
*
* @throws IOException
- * If an I/O error occurs
+ * if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkRead(String) checkRead}
@@ -1448,26 +1449,26 @@
* on the existence of the link after it is registered.
*
* @param watcher
- * The watch service to which this object is to be registered
+ * the watch service to which this object is to be registered
* @param events
- * The events for which this object should be registered
+ * the events for which this object should be registered
* @param modifiers
- * The modifiers, if any, that modify how the object is registered
+ * the modifiers, if any, that modify how the object is registered
*
- * @return A key representing the registration of this object with the
+ * @return a key representing the registration of this object with the
* given watch service
*
* @throws UnsupportedOperationException
- * If unsupported events or modifiers are specified
+ * if unsupported events or modifiers are specified
* @throws IllegalArgumentException
- * If an invalid combination of events or modifiers is specified
+ * if an invalid combination of events or modifiers is specified
* @throws ClosedWatchServiceException
- * If the watch service is closed
+ * if the watch service is closed
* @throws NotDirectoryException
- * If the file is registered to watch the entries in a directory
+ * if the file is registered to watch the entries in a directory
* and the file is not a directory (optional specific exception)
* @throws IOException
- * If an I/O error occurs
+ * if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkRead(String) checkRead}
@@ -1537,7 +1538,7 @@
* is the name of the file or directory denoted by this path. The {@link
* #getRoot root} component, if present, is not returned by the iterator.
*
- * @return An iterator over the name elements of this path.
+ * @return an iterator over the name elements of this path.
*/
@Override
public abstract Iterator iterator();
@@ -1550,9 +1551,9 @@
* provider, platform specific. This method does not access the file system
* and neither file is required to exist.
*
- * @param other The path compared to this path.
+ * @param other the path compared to this path.
*
- * @return Zero if the argument is {@link #equals equal} to this path, a
+ * @return zero if the argument is {@link #equals equal} to this path, a
* value less than zero if this path is lexicographically less than
* the argument, or a value greater than zero if this path is
* lexicographically greater than the argument
@@ -1574,14 +1575,14 @@
* This method satisfies the general contract of the {@link
* java.lang.Object#equals(Object) Object.equals} method.
*
- * @param ob
- * The object to which this object is to be compared
+ * @param other
+ * the object to which this object is to be compared
*
* @return {@code true} if, and only if, the given object is a {@code Path}
* that is identical to this {@code Path}
*/
@Override
- public abstract boolean equals(Object ob);
+ public abstract boolean equals(Object other);
/**
* Computes a hash code for this path.
@@ -1590,7 +1591,7 @@
* satisfies the general contract of the {@link Object#hashCode
* Object.hashCode} method.
*
- * @return The hash-code value for this Path
+ * @return the hash-code value for this path
*/
@Override
public abstract int hashCode();
@@ -1605,7 +1606,7 @@
* The returned path string uses the default name {@link
* FileSystem#getSeparator separator} to separate names in the path.
*
- * @return The string representation of this path
+ * @return the string representation of this path
*/
@Override
public abstract String toString();