de.fhg.igd.util
Class CanonicalPath

java.lang.Object
  de.fhg.igd.util.CanonicalPath

All Implemented Interfaces:

Implication, Cloneable, Comparable

public final class CanonicalPath
extends Object
implements Implication, Cloneable, Comparable

Represents a canonical path. A canonical path consists of a sequence of path elements, and can contain wildcards. This class provides methods to create canonical paths from strings, and to do various comparisons on canonical paths.

Wildcards are used when one canonical path is tested for implication by another. The rules are as follows:

• An asterisk ("∗") matches any corresponding path element.
• A minus ("-") matches any corresponding path element as well as any following ones.

This behaviour is roughly the one of Java's FilePermission .

Version:

"$Id: CanonicalPath.java 1913 2007-08-08 02:41:53Z jpeters $"

Author:

Volker Roth

See Also:

Implication

Field Summary

private boolean	absolute_ Indicates that the path is absolute.
static CanonicalPath	ALL A global wildcard path that matches all other paths (with the exception of the root path).
private String[]	path_ The array of path elements.
private char	separator_ The separator char.

Constructor Summary

private	CanonicalPath() Creates an unitialized instance.
	CanonicalPath(CanonicalPath parent, CanonicalPath child) Creates a new path which is the concatenation of the given paths.
	CanonicalPath(CanonicalPath parent, String child) Creates a new path which is the concatenation of the given paths.
	CanonicalPath(char separator) Creates a zero-length path with the given separator.
	CanonicalPath(String path, char separator) Creates an instance from the given string with the given separator char.

Method Summary

Object	clone() Clones this instance.
CanonicalPath	commonParent(CanonicalPath path) Creates the prefix path common to this canonical path and the given one.
int	compareTo(Object o) Returns a number smaller than zero, zero, or greater than zero as the given path is smaller, than, equal to, or greater than the given path.
String	elementAt(int index) Returns the path element at the given index.
boolean	equals(Object o) Compares this canonical path with the given object.
int	hashCode() Returns the has code of this object.
CanonicalPath	head(int length) Returns a new path instance with the first len path elements of this one.
boolean	implies(Object o) Tests if this path implies the given one.
boolean	impliesAll() Returns true if this paths implies any other path but the root path.
boolean	isAbsolute() Returns true if this path is absolute.
boolean	isPrefixOf(CanonicalPath that) Checks is this path is a prefix of the given one.
boolean	isTruePrefixOf(CanonicalPath that) Checks is this path is a true prefix of the given one.
boolean	isWildcard() Returns true if this path contains wildcard elements such as an asterisk or a minus.
int	length() Returns the length of the path in elements.
protected String[]	sanitize(String[] tmp) Sanitizes the given string by removing references to local and parent directories ('.', '..') from it as well as elements with length 0.
CanonicalPath	tail(int offset) Returns a new path instance with all path elements of this one starting from the given index.
protected String[]	tokenize(String path, char separator) Transforms the given string into an array of strings by slicing it up at the boundaries determined by means of the separator char.
String	toString() Returns the path as a string.

Methods inherited from class java.lang.Object

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

Field Detail

ALL

public static final CanonicalPath ALL

A global wildcard path that matches all other paths (with the exception of the root path).

path_

private String[] path_

The array of path elements.

absolute_

private boolean absolute_

Indicates that the path is absolute.

separator_

private char separator_

The separator char.

Constructor Detail

CanonicalPath

private CanonicalPath()

Creates an unitialized instance.

CanonicalPath

public CanonicalPath(char separator)

Creates a zero-length path with the given separator. The resulting path is absolute and resembles a root path.

Parameters:

separator - The separator char.

CanonicalPath

public CanonicalPath(String path,
                     char separator)

Creates an instance from the given string with the given separator char.

Parameters:

path - The string representation of the path.

separator - The separater char.

Throws:

NullPointerException - if path is null.

IllegalArgumentException - if the given path has zero length.

CanonicalPath

public CanonicalPath(CanonicalPath parent,
                     CanonicalPath child)

Creates a new path which is the concatenation of the given paths. If the parent path is absolute then the resulting path is absolute as well. If the parent is relative then the resulting path is also relative. This path inherits the separator char from parent.

Parameters:

parent - The parent path.

child - The child path.

Throws:

NullPointerException - if one of the given paths is null.

CanonicalPath

public CanonicalPath(CanonicalPath parent,
                     String child)

Creates a new path which is the concatenation of the given paths. If the parent path is absolute then the resulting path is absolute as well. If the parent is relative then the resulting path is also relative. This path inherits the separator char from parent, and the child is transformed with the parent's separator char. If the child stands for an absolute path then this constructor behaves as if CanonicalPath(child, c) had been called with c being the separator char of parent.

Parameters:

parent - The parent path.

child - The child path.

Throws:

NullPointerException - if one of the given paths is null.

Method Detail

tokenize

protected String[] tokenize(String path,
                            char separator)

Transforms the given string into an array of strings by slicing it up at the boundaries determined by means of the separator char.

Parameters:

path - The path to tokenize.

separator - The separator char.

Returns:

The elements of the path as a string array.

sanitize

protected String[] sanitize(String[] tmp)

Sanitizes the given string by removing references to local and parent directories ('.', '..') from it as well as elements with length 0.

Parameters:

tmp - The input array of path elements.

Returns:

The sanitized array.

Throws:

IllegalArgumentException - if the given path refers to a directory above the start of the path, e.g. "foo/..".

isAbsolute

public boolean isAbsolute()

Returns true if this path is absolute.

Returns:

true if this path is absolute.

isWildcard

public boolean isWildcard()

Returns true if this path contains wildcard elements such as an asterisk or a minus.

Returns:

true if this path is a wildcard.

impliesAll

public boolean impliesAll()

Returns true if this paths implies any other path but the root path. This methods verifies if this path consists of the single path element "-", which matches all other path elements recursively.

Returns:

true if this path implies all other paths.

length

public int length()

Returns the length of the path in elements.

Returns:

The number of elements in the path.

elementAt

public String elementAt(int index)

Returns the path element at the given index.

Returns:

The path element at index.

Throws:

ArrayIndexOutOfBoundsException - if the given index is out of range.

equals

public boolean equals(Object o)

Compares this canonical path with the given object.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns the has code of this object.

Overrides:

hashCode in class Object

Returns:

The has code.

implies

public boolean implies(Object o)

Tests if this path implies the given one.

Specified by:

implies in interface Implication

Parameters:

o - The object to test against.

Returns:

true if this path implies the given one.

toString

public String toString()

Returns the path as a string.

Overrides:

toString in class Object

Returns:

The path as a string.

tail

public CanonicalPath tail(int offset)

Returns a new path instance with all path elements of this one starting from the given index. If this path is absolute then the resulting path will be relative (unless index is zero, in that case this will be returned).

Returns:

The tail path. Contains all elements of this path except the first one.

Throws:

ArrayIndexOutOfBoundsException - if the tail's length would be zero or negative.

head

public CanonicalPath head(int length)

Returns a new path instance with the first len path elements of this one. If this path is absolute/relative then the resulting path will also be absolute/relative.

Returns:

The head path.

Throws:

IllegalArgumentException - if the given length is less than 0 or exceeds the length of this path.

isPrefixOf

public boolean isPrefixOf(CanonicalPath that)

Checks is this path is a prefix of the given one. This is the case if the length of the given path is greater than or equal to the length of this path and all path elements of this path equal the corresponding path elements of the given path. This implies that each path is its own prefix.

Parameters:

that - The CanonicalPath to compare with.

Returns:

true if this path is a prefix of the given one, and false otherwise.

isTruePrefixOf

public boolean isTruePrefixOf(CanonicalPath that)

Checks is this path is a true prefix of the given one. This is the case if the length of the given path is greater than the length of this path and all path elements of this path are equal to the corresponding path elements of the given path.

Parameters:

that - The CanonicalPath to compare with.

Returns:

true if this path is a prefix of the given one, and false otherwise.

commonParent

public CanonicalPath commonParent(CanonicalPath path)

Creates the prefix path common to this canonical path and the given one. If this path is absolute/relative and the given one is relative/absolute then an exception is thrown.

If both paths do not have a common prefix then the root path is returned. The separater equals the one of this path. In all other cases, the longest prefix common to this path and the given one is returned as a path. If this path is relative/absolute then the returned path is also relative/absolute.

Parameters:

path - The path whose common prefix with this path shall be returned.

Returns:

The common prefix.

Throws:

IllegalArgumentException - if this path is absolute/relative and the given path is relative/absolute.

clone

public Object clone()

Clones this instance. The clone refers to the same internal array of path elements as this instance. However, since instances of this class are immutable this should not pose a problem. Once created, path elements are only read never written.

Overrides:

clone in class Object

Returns:

The clone.

compareTo

public int compareTo(Object o)

Returns a number smaller than zero, zero, or greater than zero as the given path is smaller, than, equal to, or greater than the given path.

Specified by:

compareTo in interface Comparable

Parameters:

o - The object to compare to.

Throws:

ClassCastException - if the given object is not of class CanonicalPath.