com.springsource.util.io
Class PathReference

java.lang.Object
  extended by com.springsource.util.io.PathReference

public final class PathReference
extends java.lang.Object

Represents a reference, by path, to a location on the file system. This location may be a file or a directory, or it may point to a non-existent location.

Concurrent Semantics
Threadsafe.


Nested Class Summary
static interface PathReference.PathFilter
          Allows filtering during PathReference operations.
 
Field Summary
private  java.io.File file
          The File handle that backs this reference.
 
Constructor Summary
PathReference(java.io.File file)
          Creates a new PathReference for the supplied File.
PathReference(java.lang.String path)
          Creates a new PathReference for the supplied path.
PathReference(java.net.URI uri)
          Creates a new PathReference for the supplied URI which must point to a file location.
 
Method Summary
static PathReference concat(java.lang.String... parts)
          Creates a new PathReference by concatenating the supplied parts, treating each part as a separate path element.
 PathReference copy(PathReference dest)
          Same as calling copy(to, false).
 PathReference copy(PathReference dest, boolean recursive)
          Same as calling copy(to, recursive, null);
 PathReference copy(PathReference dest, boolean recursive, PathReference.PathFilter filter)
          Copies the contents of the file/directory to location referenced supplied PathReference.
private static void copyFile(java.io.File src, java.io.File dest)
          Copies src to dest.
 PathReference createDirectory()
          Creates a directory at the location of this PathReference.
 PathReference createFile()
          Creates a new file at the location of this PathReference.
 boolean delete()
          Delete the file/directory referenced by this PathReference.
 boolean delete(boolean recursive)
          Delete the file/directory referenced by this PathReference.
 boolean equals(java.lang.Object that)
          
 boolean exists()
          Queries whether or not this PathReference points to a vaild file or directory.
 java.lang.String fileContents()
          Gets the contents of the File pointed to by this PathReference.
 java.lang.String getAbsolutePath()
          Gets the absolute path of this PathReference.
 java.lang.String getCanonicalPath()
          Gets the canonical path of this PathReference.
 java.lang.String getName()
          Gets the name of the file or directory referenced by this PathReference.
 PathReference getParent()
          Gets the parent directory of this PathReference.
 int hashCode()
          
 boolean isAbsolute()
          Queries whether or not the path of this PathReference is absolute.
 boolean isDirectory()
          Queries whether or not this PathReference points to a directory.
 boolean isFile()
          Queries whether or not this PathReference points to a file.
 PathReference newChild(java.lang.String name)
          Creates a new PathReference by concatenating the path of this PathReference with the supplied name.
private static void recursiveCopy(java.io.File src, java.io.File dest, PathReference.PathFilter filter)
          Recursively copy the contents of src to dest.
 PathReference toAbsoluteReference()
          Creates a PathReference that points to the absolute location of this PathReference.
 PathReference toCanonicalReference()
          Creates a PathReference that points to the canonical location of this PathReference.
 java.io.File toFile()
          Converts this PathReference to a File.
 java.lang.String toString()
          
 boolean touch()
          Set the last modified time of the File pointed to by this PathReference to the current time.
 java.net.URI toURI()
          Converts this PathReference into a URI.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

file

private final java.io.File file
The File handle that backs this reference.

Constructor Detail

PathReference

public PathReference(java.lang.String path)
Creates a new PathReference for the supplied path.

Parameters:
path - the path to reference.

PathReference

public PathReference(java.net.URI uri)
Creates a new PathReference for the supplied URI which must point to a file location.

Parameters:
uri - the file URI to reference

PathReference

public PathReference(java.io.File file)
Creates a new PathReference for the supplied File.

Parameters:
file - the file to reference.
Method Detail

toFile

public java.io.File toFile()
Converts this PathReference to a File.

Returns:
the File.

exists

public boolean exists()
Queries whether or not this PathReference points to a vaild file or directory.

Returns:
true if the location is valid, otherwise false.

isFile

public boolean isFile()
Queries whether or not this PathReference points to a file.

Returns:
true if this location points to a file, otherwise false.

isDirectory

public boolean isDirectory()
Queries whether or not this PathReference points to a directory.

Returns:
true if this location points to a directory, otherwise false.

getName

public java.lang.String getName()
Gets the name of the file or directory referenced by this PathReference.

Returns:
the file or directory name.
See Also:
File.getName()

getParent

public PathReference getParent()
Gets the parent directory of this PathReference.

Returns:
the parent directory.
See Also:
File.getParentFile()

isAbsolute

public boolean isAbsolute()
Queries whether or not the path of this PathReference is absolute.

Returns:
true if the path is absolute, otherwise false.

getAbsolutePath

public java.lang.String getAbsolutePath()
Gets the absolute path of this PathReference.

Returns:
the absolute path.

toURI

public java.net.URI toURI()
Converts this PathReference into a URI.

Returns:
the URI of this PathReference.
See Also:
File.toURI()

getCanonicalPath

public java.lang.String getCanonicalPath()
Gets the canonical path of this PathReference.

Returns:
the canonical path.

toAbsoluteReference

public PathReference toAbsoluteReference()
Creates a PathReference that points to the absolute location of this PathReference.

Returns:
the new PathReference.

toCanonicalReference

public PathReference toCanonicalReference()
Creates a PathReference that points to the canonical location of this PathReference.

Returns:
the new PathReference.

toString

public java.lang.String toString()

Overrides:
toString in class java.lang.Object

delete

public boolean delete()
Delete the file/directory referenced by this PathReference. Has the same effect as calling delete(false).

Returns:
true if the file is deleted, otherwise false.

delete

public boolean delete(boolean recursive)
Delete the file/directory referenced by this PathReference. Nested contents can optionally be deleted by passing recursive = true. Non-recursive deletes will fail (return false for non-empty directories).

Parameters:
recursive - should the delete process nested contents recursively.
Returns:
true if the file is deleted, otherwise false.

copy

public PathReference copy(PathReference dest)
Same as calling copy(to, false).

Parameters:
dest - the destination to copy to.
Returns:
the final destination PathReference.

copy

public PathReference copy(PathReference dest,
                          boolean recursive)
Same as calling copy(to, recursive, null);

Parameters:
dest - the destination to copy to.
recursive - whether the copy should be recursive or not.
Returns:
the final destination PathReference.

copy

public PathReference copy(PathReference dest,
                          boolean recursive,
                          PathReference.PathFilter filter)
Copies the contents of the file/directory to location referenced supplied PathReference. The exact semantics of the copy depend on the state of both the source and destination locations.

When copying a file, if the destination location already exists and is a file then a FatalIOException is thrown. If the destination location exists and is a directory, the file is copied into this directory with the same name as the source location. If the destination location does not exist, then the file is copied to this location directly.

When copying a directory, if the destination location exists then the directory is copied into the already existing directory with the same name as the source location. If the destination location does not exist, then the directory is copied directly to the destination location and thus gets the name defined by the destination location.

A PathReference.PathFilter can be used to specify exactly which files will be included in the copy. Passing null for the filter includes all files.

Non-recursive copies on non-empty directories will fail with FatalIOException.

Parameters:
dest - the destination to copy to.
recursive - whether the copy should be recursive or not.
filter - a PathFilter controlling which files are included in the copy.
Returns:
the final destination PathReference.

newChild

public PathReference newChild(java.lang.String name)
Creates a new PathReference by concatenating the path of this PathReference with the supplied name. Note that this method does not create a physical file or directory at the child location.

Parameters:
name - the name of the new child entry.
Returns:
the child PathReference.

createFile

public PathReference createFile()
Creates a new file at the location of this PathReference.

Returns:
this PathReference for chaining purposes.

createDirectory

public PathReference createDirectory()
Creates a directory at the location of this PathReference.

Returns:
this PathReference for chaining purposes.

concat

public static PathReference concat(java.lang.String... parts)
Creates a new PathReference by concatenating the supplied parts, treating each part as a separate path element.

Parameters:
parts - the path elements.
Returns:
the PathReference for the concatenated path.

recursiveCopy

private static void recursiveCopy(java.io.File src,
                                  java.io.File dest,
                                  PathReference.PathFilter filter)
Recursively copy the contents of src to dest.

Parameters:
src - the source file.
dest - the destination file.

copyFile

private static void copyFile(java.io.File src,
                             java.io.File dest)
Copies src to dest.

Parameters:
src - the source File.
dest - the destination File.

hashCode

public int hashCode()

Overrides:
hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object that)

Overrides:
equals in class java.lang.Object

fileContents

public java.lang.String fileContents()
                              throws java.io.IOException
Gets the contents of the File pointed to by this PathReference.

Returns:
the file contents as a String.
Throws:
java.io.IOException - if the file cannot be found or read.

touch

public boolean touch()
Set the last modified time of the File pointed to by this PathReference to the current time. Note: the behaviour is not the same as UNIX(TM) touch as the latter also sets the file access time.

Returns:
true iff this operation succeeded, false otherwise