NIO2 API

org.classpath.icedtea.java.nio.file.spi
Class AbstractPath

java.lang.Object
  extended by org.classpath.icedtea.java.nio.file.Path
      extended by org.classpath.icedtea.java.nio.file.spi.AbstractPath
All Implemented Interfaces:
java.lang.Comparable<Path>, java.lang.Iterable<Path>, FileRef, Watchable

public abstract class AbstractPath
extends Path

Base implementation class for a Path.

This class is intended to be extended by provider implementors. It implements, or provides default implementations for several of the methods defined by the Path class. It implements the copyTo and moveTo methods for the case that the source and target are not associated with the same provider.

Since:
1.7

Constructor Summary
protected AbstractPath()
          Initializes a new instance of this class.
 
Method Summary
 Path copyTo(Path target, CopyOption... options)
          Copy the file located by this path to a target location.
 Path createFile(FileAttribute<?>... attrs)
          Creates a new and empty file, failing if the file already exists.
 void delete()
          Deletes the file referenced by this object.
 boolean exists()
          Tests whether the file located by this path exists.
protected abstract  void implCopyTo(Path target, CopyOption... options)
          Copy the file located by this path to a target location.
protected abstract  void implMoveTo(Path target, CopyOption... options)
          Move the file located by this path to a target location.
 Path moveTo(Path target, CopyOption... options)
          Move or rename the file located by this path to a target location.
 SeekableByteChannel newByteChannel(OpenOption... options)
          Opens or creates a file, returning a seekable byte channel to access the file.
 DirectoryStream<Path> newDirectoryStream()
          Opens the directory referenced by this object, returning a DirectoryStream to iterate over all entries in the directory.
 DirectoryStream<Path> newDirectoryStream(java.lang.String glob)
          Opens the directory referenced by this object, returning a DirectoryStream to iterate over the entries in the directory.
 java.io.InputStream newInputStream()
          Opens the file located by this path for reading, returning an input stream to read bytes from the file.
 java.io.OutputStream newOutputStream(OpenOption... options)
          Opens or creates the file located by this path for writing, returning an output stream to write bytes to the file.
 java.io.OutputStream newOutputStream(java.util.Set<? extends OpenOption> options, FileAttribute<?>... attrs)
          Opens or creates the file located by this path for writing, returning an output stream to write bytes to the file.
 boolean notExists()
          Tests whether the file located by this path does not exist.
 WatchKey register(WatchService watcher, WatchEvent.Kind<?>... events)
          Registers an object with a watch service.
 
Methods inherited from class org.classpath.icedtea.java.nio.file.Path
compareTo, createDirectory, createLink, createSymbolicLink, delete, endsWith, equals, getFileSystem, getName, getName, getNameCount, getParent, getRoot, hashCode, isAbsolute, isHidden, iterator, newByteChannel, newDirectoryStream, normalize, readSymbolicLink, register, relativize, resolve, resolve, startsWith, subpath, toAbsolutePath, toRealPath, toString, toUri
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.classpath.icedtea.java.nio.file.FileRef
checkAccess, getFileAttributeView, getFileAttributeView, getFileStore, isSameFile
 

Constructor Detail

AbstractPath

protected AbstractPath()
Initializes a new instance of this class.

Method Detail

delete

public final void delete()
                  throws java.io.IOException
Description copied from interface: FileRef
Deletes the file referenced by this object.

An implementation may require to examine the file to determine if the file is a directory. Consequently this method may not be atomic with respect to other file system operations. If the file is a symbolic-link then the link is deleted and not the final target of the link.

If the file is a directory then the directory must be empty. In some implementations a directory has entries for special files or links that are created when the directory is created. In such implementations a directory is considered empty when only the special entries exist.

On some operating systems it may not be possible to remove a file when it is open and in use by this Java virtual machine or other programs.

Throws:
NoSuchFileException - If the file does not exist (optional specific exception)
DirectoryNotEmptyException - If the file is a directory and could not otherwise be deleted because the directory is not empty (optional specific exception)
java.io.IOException - If an I/O error occurs
java.lang.SecurityException - In the case of the default provider, and a security manager is installed, the SecurityManager.checkDelete(String) method is invoked to check delete access to the file

createFile

public final Path createFile(FileAttribute<?>... attrs)
                      throws java.io.IOException
Description copied from class: Path
Creates a new and empty file, failing if the file already exists.

This Path locates the file to create. The check for the existence of the file and the creation of the new file if it does not exist are a single operation that is atomic with respect to all other filesystem activities that might affect the directory.

The attrs parameter is an optional array of file-attributes to set atomically when creating the file. Each attribute is identified by its name. If more than one attribute of the same name is included in the array then all but the last occurrence is ignored.

Specified by:
createFile in class Path
Parameters:
attrs - An optional list of file attributes to set atomically when creating the file
Returns:
This path
Throws:
java.lang.IllegalArgumentException
FileAlreadyExistsException - If a file of that name already exists (optional specific exception)
java.io.IOException - If an I/O error occurs
java.lang.SecurityException - In the case of the default provider, and a security manager is installed, the checkWrite method is invoked to check write access to the new file.

newByteChannel

public final SeekableByteChannel newByteChannel(OpenOption... options)
                                         throws java.io.IOException
Description copied from class: Path
Opens or creates a file, returning a seekable byte channel to access the file.

This method extends the options defined by the FileRef interface and to the options specified by the newByteChannel method except that the options are specified by an array. In the case of the default provider, the returned seekable byte channel is a FileChannel.

Specified by:
newByteChannel in interface FileRef
Specified by:
newByteChannel in class Path
Parameters:
options - Options specifying how the file is opened
Returns:
a new seekable byte channel
Throws:
java.lang.IllegalArgumentException - If the set contains an invalid combination of options
FileAlreadyExistsException - If a file of that name already exists and the CREATE_NEW option is specified (optional specific exception)
java.io.IOException - If an I/O error occurs
java.lang.SecurityException - In the case of the default provider, and a security manager is installed, the checkRead method is invoked to check read access to the path if the file is opened for reading. The checkWrite method is invoked to check write access to the path if the file is opened for writing.

newInputStream

public java.io.InputStream newInputStream()
                                   throws java.io.IOException
Opens the file located by this path for reading, returning an input stream to read bytes from the file.

This method returns an InputStream that is constructed by invoking the Channels.newInputStream method. It may be overridden where a more efficient implementation is available.

Specified by:
newInputStream in class Path
Returns:
An input stream to read bytes from the file
Throws:
java.io.IOException - If an I/O error occurs
java.lang.SecurityException - In the case of the default provider, and a security manager is installed, the checkRead method is invoked to check read access to the file.

newOutputStream

public java.io.OutputStream newOutputStream(OpenOption... options)
                                     throws java.io.IOException
Opens or creates the file located by this path for writing, returning an output stream to write bytes to the file.

This method returns an OutputStream that is constructed by invoking the Channels.newOutputStream method. It may be overridden where a more efficient implementation is available.

Specified by:
newOutputStream in class Path
Parameters:
options - Options specifying how the file is opened
Returns:
a new seekable byte channel
Throws:
java.lang.IllegalArgumentException - If options contains an invalid combination of options
java.io.IOException - If an I/O error occurs
java.lang.SecurityException - In the case of the default provider, and a security manager is installed, the checkWrite method is invoked to check write access to the file.

newOutputStream

public java.io.OutputStream newOutputStream(java.util.Set<? extends OpenOption> options,
                                            FileAttribute<?>... attrs)
                                     throws java.io.IOException
Opens or creates the file located by this path for writing, returning an output stream to write bytes to the file.

This method returns an OutputStream that is constructed by invoking the Channels.newOutputStream method. It may be overridden where a more efficient implementation is available.

Specified by:
newOutputStream in class Path
Parameters:
options - Options specifying how the file is opened
attrs - An optional list of file attributes to set atomically when creating the file
Returns:
A new output stream
Throws:
java.lang.IllegalArgumentException - If the set contains an invalid combination of options
java.io.IOException - If an I/O error occurs
java.lang.SecurityException - In the case of the default provider, and a security manager is installed, the checkWrite method is invoked to check write access to the file.

newDirectoryStream

public final DirectoryStream<Path> newDirectoryStream()
                                               throws java.io.IOException
Description copied from class: Path
Opens the directory referenced by this object, returning a DirectoryStream to iterate over all entries in the directory. The elements returned by the directory stream's iterator are of type Path, each one representing an entry in the directory. The Path objects are obtained as if by resolving the name of the directory entry against this path.

The directory stream's close method should be invoked after iteration is completed so as to free any resources held for the open directory. The Files.withDirectory utility method is useful for cases where a task is performed on each accepted entry in a directory. This method closes the directory when iteration is complete (or an error occurs).

When an implementation supports operations on entries in the directory that execute in a race-free manner then the returned directory stream is a SecureDirectoryStream.

Specified by:
newDirectoryStream in class Path
Returns:
A new and open DirectoryStream object
Throws:
NotDirectoryException - If the file could not otherwise be opened because it is not a directory (optional specific exception)
java.io.IOException - If an I/O error occurs
java.lang.SecurityException - In the case of the default provider, and a security manager is installed, the checkRead method is invoked to check read access to the directory.

newDirectoryStream

public DirectoryStream<Path> newDirectoryStream(java.lang.String glob)
                                         throws java.io.IOException
Opens the directory referenced by this object, returning a DirectoryStream to iterate over the entries in the directory. The entries are filtered by matching the String representation of their file names against a given pattern.

This method constructs a PathMatcher by invoking the file system's getNameMatcher method. This method may be overridden where a more efficient implementation is available.

Specified by:
newDirectoryStream in class Path
Parameters:
glob - The glob pattern
Returns:
A new and open DirectoryStream object
Throws:
java.util.regex.PatternSyntaxException - If the pattern is invalid
java.lang.UnsupportedOperationException - If the pattern syntax is not known to the implementation
NotDirectoryException - If the file could not otherwise be opened because it is not a directory (optional specific exception)
java.io.IOException - If an I/O error occurs
java.lang.SecurityException - In the case of the default provider, and a security manager is installed, the checkRead method is invoked to check read access to the directory.

exists

public final boolean exists()
Description copied from class: Path
Tests whether the file located by this path exists.

This convenience method is intended for cases where it is required to take action when it can be confirmed that a file exists. This method simply invokes the checkAccess method to check if the file exists. If the checkAccess method succeeds then this method returns true, otherwise if an IOException is thrown (because the file doesn't exist or cannot be accessed by this Java virtual machine) then false is returned.

Note that the result of this method is immediately outdated. If this method indicates the file exists then there is no guarantee that a subsequence access will succeed. Care should be taken when using this method in security sensitive applications.

Specified by:
exists in class Path
Returns:
true if the file exists; false if the file does not exist or its existence cannot be determined.
See Also:
Path.notExists()

notExists

public final boolean notExists()
Description copied from class: Path
Tests whether the file located by this path does not exist.

This convenience method is intended for cases where it is required to take action when it can be confirmed that a file does not exist. This method invokes the checkAccess method to check if the file exists. If the file does not exist then true is returned, otherwise the file exists or cannot be accessed by this Java virtual machine and false is returned.

Note that this method is not the complement of the exists method. Where it is not possible to determine if a file exists or not then both methods return false. As with the exists method, the result of this method is immediately outdated. If this method indicates the file does exist then there is no guarantee that a subsequence attempt to create the file will succeed. Care should be taken when using this method in security sensitive applications.

Specified by:
notExists in class Path
Returns:
true if the file does not exist; false if the file exists or its existence cannot be determined.

register

public final WatchKey register(WatchService watcher,
                               WatchEvent.Kind<?>... events)
                        throws java.io.IOException
Description copied from interface: Watchable
Registers an object with a watch service.

An invocation of this method behaves in exactly the same way as the invocation

     watchable.register(watcher, events, new WatchEvent.Modifier[0]);
 

Parameters:
watcher - The watch service to which this object is to be registered
events - The events for which this object should be registered
Returns:
A key representing the registration of this object with the given watch service
Throws:
java.io.IOException - If an I/O error occurs

implCopyTo

protected abstract void implCopyTo(Path target,
                                   CopyOption... options)
                            throws java.io.IOException
Copy the file located by this path to a target location.

This method is invoked by the copyTo method for the case that this Path and the target Path are associated with the same provider.

Parameters:
target - The target location
options - Options specifying how the copy should be done
Throws:
java.lang.IllegalArgumentException - If an invalid option is specified
FileAlreadyExistsException - The target file exists and cannot be replaced because the REPLACE_EXISTING option is not specified, or the target file is a non-empty directory (optional specific exception)
java.io.IOException - If an I/O error occurs
java.lang.SecurityException - In the case of the default provider, and a security manager is installed, the checkRead method is invoked to check read access to the source file, the checkWrite is invoked to check write access to the target file. If a symbolic link is copied the security manager is invoked to check LinkPermission("symbolic").

implMoveTo

protected abstract void implMoveTo(Path target,
                                   CopyOption... options)
                            throws java.io.IOException
Move the file located by this path to a target location.

This method is invoked by the moveTo method for the case that this Path and the target Path are associated with the same provider.

Parameters:
target - The target location
options - Options specifying how the move should be done
Throws:
java.lang.IllegalArgumentException - If an invalid option is specified
FileAlreadyExistsException - The target file exists and cannot be replaced because the REPLACE_EXISTING option is not specified, or the target file is a non-empty directory
AtomicMoveNotSupportedException - The options array contains the ATOMIC_MOVE option but the file cannot be moved as an atomic file system operation.
java.io.IOException - If an I/O error occurs
java.lang.SecurityException - In the case of the default provider, and a security manager is installed, the checkWrite method is invoked to check write access to both the source and target file.

copyTo

public final Path copyTo(Path target,
                         CopyOption... options)
                  throws java.io.IOException
Copy the file located by this path to a target location.

If this path is associated with the same provider as the target then the implCopyTo method is invoked to copy the file. Otherwise, this method attempts to copy the file to the target location in a manner that may be less efficient than would be the case that target is associated with the same provider as this path.

Specified by:
copyTo in class Path
Parameters:
target - The target location
options - Options specifying how the copy should be done
Returns:
The target
Throws:
java.lang.IllegalArgumentException
FileAlreadyExistsException - The target file exists and cannot be replaced because the REPLACE_EXISTING option is not specified, or the target file is a non-empty directory (optional specific exception)
java.io.IOException - If an I/O error occurs
java.lang.SecurityException - In the case of the default provider, and a security manager is installed, the checkRead method is invoked to check read access to the source file, the checkWrite is invoked to check write access to the target file. If a symbolic link is copied the security manager is invoked to check LinkPermission("symbolic").

moveTo

public final Path moveTo(Path target,
                         CopyOption... options)
                  throws java.io.IOException
Move or rename the file located by this path to a target location.

If this path is associated with the same provider as the target then the implMoveTo method is invoked to move the file. Otherwise, this method attempts to copy the file to the target location and delete the source file. This implementation may be less efficient than would be the case that target is associated with the same provider as this path.

Specified by:
moveTo in class Path
Parameters:
target - The target location
options - Options specifying how the move should be done
Returns:
The target
Throws:
java.lang.IllegalArgumentException
FileAlreadyExistsException - The target file exists and cannot be replaced because the REPLACE_EXISTING option is not specified, or the target file is a non-empty directory
java.io.IOException - If an I/O error occurs
java.lang.SecurityException - In the case of the default provider, and a security manager is installed, the checkWrite method is invoked to check write access to both the source and target file.

NIO2 API

Submit a bug or feature

Copyright 2010 Sun Microsystems, Inc. All rights reserved. Use is subject to the terms of the GNU General Public License.