net.java.truevfs.kernel.spec

Class FsNodePath

java.lang.Object

net.java.truevfs.kernel.spec.FsNodePath

All Implemented Interfaces:

Serializable, Comparable<FsNodePath>

@Immutable
public final class FsNodePath
extends Object
implements Serializable, Comparable<FsNodePath>

Addresses a file system node. The purpose of a file system path is to parse a URI and decompose it into a file system mount point and node name.

Specification

A path adds the following syntax constraints to a Uniform Resource Identifier:

1. The URI must not define a fragment component.
2. If the URI is opaque, its scheme specific part must contain at least one mount point separator "!/". The part up to the last mount point separator is parsed according to the syntax constraints for an FsMountPoint and set as the value of the mountPoint property. The part after the last mount point separator is parsed according to the syntax constraints for an FsNodeName and set as the value of the node name property.
3. Otherwise, if the URI is absolute, it's resolved with ".", parsed according to the syntax constraints for an FsMountPoint and set as the value of the mountPoint property. The URI relativized to this mount point is parsed according to the syntax constraints for an FsNodeName and set as the value of the node name property.
4. Otherwise, the value of the mountPoint property is set to null and the URI is parsed according to the syntax constraints for an FsNodeName and set as the value of the node name property.

For opaque URIs of the form jar:<url>!/<node>, these constraints build a close subset of the syntax allowed by a JarURLConnection.

Examples

Examples for valid node path URIs:

uri property	mountPoint URI	nodeName URI
foo	(null)	foo
foo:/bar	foo:/	bar
foo:/bar/	foo:/bar	(empty - not null)
foo:bar:/baz!/bang	foo:bar:/baz!/	bang

Examples for invalid node path URIs:

URI	Issue
/foo	leading slash separator not allowed if URI is not absolute
foo/	trailing slash separator not allowed if URI is not absolute
foo:bar	missing mount point separator in opaque URI
foo:bar:baz:/bang!/boom	dito for bar:baz:/bang

Identities

For any path p, it's generally true that new FsNodePath(p.getUri()).equals(p).

Furthermore, it's generally true that new FsNodePath(p.getMountPoint(), p.getNodeName()).equals(p).

Serialization

This class supports serialization with both ObjectOutputStream and XMLEncoder.

Author:

Christian Schlichtherle

See Also:

FsMountPoint, FsNodeName, FsScheme, Serialized Form

Constructor Summary

Constructors

Constructor and Description
FsNodePath(File file) Equivalent to new FsNodePath(file.toURI(), FsUriModifier.CANONICALIZE).
FsNodePath(FsMountPoint mountPoint, FsNodeName nodeName) Constructs a new path by composing its URI from the given nullable mount point and node name.
FsNodePath(URI uri) Equivalent to new FsNodePath(uri, FsUriModifier.NULL).
FsNodePath(URI uri, FsUriModifier modifier) Constructs a new path by parsing the given URI.

Method Summary

Modifier and Type	Method and Description
int	compareTo(FsNodePath that) Implements a natural ordering which is consistent with equals(Object).
static FsNodePath	create(URI uri) Equivalent to create(uri, FsUriModifier.NULL).
static FsNodePath	create(URI uri, FsUriModifier modifier) Constructs a new path by parsing the given URI.
boolean	equals(Object that) Returns true iff the given object is a path name and its URI equals the URI of this path name.
FsMountPoint	getMountPoint() Returns the mount point component or null iff this path's URI is not absolute.
FsNodeName	getNodeName() Returns the node name component.
URI	getUri() Returns the URI for this node path.
int	hashCode() Returns a hash code which is consistent with equals(Object).
FsNodePath	resolve(FsNodeName nodeName) Resolves the given node name against this path.
URI	toHierarchicalUri() Returns a URI which is recursively transformed from the URI of this path so that it's absolute and hierarchical.
String	toString() Equivalent to calling URI.toString() on getUri().

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

FsNodePath

public FsNodePath(File file)

Equivalent to new FsNodePath(file.toURI(), FsUriModifier.CANONICALIZE). Note that this constructor is expected not to throw any exceptions.

FsNodePath

public FsNodePath(@CheckForNull
                  FsMountPoint mountPoint,
                  FsNodeName nodeName)

Constructs a new path by composing its URI from the given nullable mount point and node name.

Parameters:

mountPoint - the nullable mount point.

nodeName - the node name.

FsNodePath

@ConstructorProperties(value="uri")
public FsNodePath(URI uri)
                                               throws URISyntaxException

Equivalent to new FsNodePath(uri, FsUriModifier.NULL).

Throws:

URISyntaxException

FsNodePath

public FsNodePath(URI uri,
                  FsUriModifier modifier)
           throws URISyntaxException

Constructs a new path by parsing the given URI.

Parameters:

uri - the non-null URI.

modifier - the URI modifier.

Throws:

URISyntaxException - if uri does not conform to the syntax constraints for paths.

Method Detail

compareTo

public int compareTo(FsNodePath that)

Implements a natural ordering which is consistent with equals(Object).

Specified by:

compareTo in interface Comparable<FsNodePath>

create

public static FsNodePath create(URI uri)

Equivalent to create(uri, FsUriModifier.NULL).

create

public static FsNodePath create(URI uri,
                                FsUriModifier modifier)

Constructs a new path by parsing the given URI. This static factory method calls new FsNodePath(uri, modifier) and wraps any thrown URISyntaxException in an IllegalArgumentException.

Parameters:

uri - the URI.

modifier - the URI modifier.

Returns:

A new path.

Throws:

IllegalArgumentException - if uri does not conform to the syntax constraints for paths.

equals

public boolean equals(@CheckForNull
                      Object that)

Returns true iff the given object is a path name and its URI equals the URI of this path name. Note that this ignores the mount point and node name.

Overrides:

equals in class Object

getMountPoint

@Nullable
public FsMountPoint getMountPoint()

Returns the mount point component or null iff this path's URI is not absolute.

Returns:

The nullable mount point.

getNodeName

public FsNodeName getNodeName()

Returns the node name component. This may be empty, but is never null.

Returns:

The node name component.

getUri

public URI getUri()

Returns the URI for this node path.

Returns:

The URI for this node path.

hashCode

public int hashCode()

Returns a hash code which is consistent with equals(Object).

Overrides:

hashCode in class Object

resolve

public FsNodePath resolve(FsNodeName nodeName)

Resolves the given node name against this path.

Parameters:

nodeName - a node name relative to this path.

Returns:

A new path with an absolute URI.

toHierarchicalUri

public URI toHierarchicalUri()

Returns a URI which is recursively transformed from the URI of this path so that it's absolute and hierarchical. If this path is already in absolute and hierarchical form, its URI gets returned.

For example, the path URIs zip:file:/archive!/node and tar:file:/archive!/node would both produce the hierarchical URI file:/archive/node.

Returns:

A URI which is recursively transformed from the URI of this path so that it's absolute and hierarchical.

toString

public String toString()

Equivalent to calling URI.toString() on getUri().

Overrides:

toString in class Object