org.meshcms.util
Class Path

java.lang.Object
  org.meshcms.util.Path

All Implemented Interfaces:

java.lang.Cloneable, java.lang.Comparable, java.io.Serializable

public class Path

extends java.lang.Object

implements java.lang.Comparable, java.io.Serializable, java.lang.Cloneable

An abstract representation of a file path. The root of the path is undefined, and the path can be relative (i.e. can start with '..'). Example of paths are:

• (the empty path)
  This is meant as the (relative) root;
• filename.txt
• home/user/document.html
• ../../directoryname

A Path can be created from any object. When you call a constructor, the path is initialized as empty, then the objects passed to the constructor are added to it. When all objects have been added, the path is simplified by removing redundant elements. For example, "home/user/../otheruser" is reduced to "home/otheruser". After the constructor returns, the Path object is immutable. When you call a method to modify it (like one of the add() methods), it returns a new Path that is the result of the requested operation. The objects are added as follows:

• if the object is null, nothing is added;
• if it is another Path, its elements are added;
• if it is a String, it is split in tokens (divided by slashes or backslashes) and these tokens are added as elements;
• if it is a Collection, any member of the Collection is added as a separate object;
• if it is an array of Strings, any member of the array is added as a separate String (to be tokenized);
• if it is another kind of object, its toString() method is called and the returned String is tokenized and added.

Author:

Luciano Vernaschi

See Also:

Serialized Form

Field Summary

protected java.lang.String[]	elements
protected java.lang.String	pathName
static Path	ROOT

Constructor Summary

Path()
Creates an empty path.

Path(java.lang.Object o)
Creates a path and adds an object to it.

Path(java.lang.Object o1, java.lang.Object o2)
Creates a path and adds two objects to it.

Path(java.lang.Object o1, java.lang.Object o2, java.lang.Object o3)
Creates a path and adds three objects to it.

Method Summary

Path	add(java.lang.Object o) Adds an object to the current path.
Path	add(java.lang.Object o1, java.lang.Object o2) Adds two objects to the current path.
protected void	addObjectToList(java.util.List list, java.lang.Object o)
protected java.lang.Object	clone()
static Path	commonPart(Path p1, Path p2) Returns the common part between the two Paths.
int	compareTo(java.lang.Object o) Compares this path to a new Path built by calling new Path(o)
int	compareTo(Path other) Compares two paths.
boolean	equals(java.lang.Object o) Checks the two paths for equality.
java.lang.String	getAsLink() Returns this path object encoded As a link: if the path is not empty, adds a slash at the beginning.
Path	getCommonPath(Path other) Returns the common part between the two Paths (between this path and the other path).
java.lang.String	getElementAt(int index) Returns the element at the given index.
int	getElementCount() Returns the number of elements of the current path.
java.lang.String[]	getElements() Returns a copy of the elements array.
java.io.File	getFile(java.io.File parent) Returns a File object relative to the given file.
java.lang.String	getLastElement() Returns the last element of the current path (usually the file name).
Path	getParent() Return the parent of the current path.
Path	getPartial(int count) Returns a parent of the current path, whose element count is equal to the passed value.
Path	getRelativeTo(java.lang.Object root) Returns the current path as relative to the given root.
int	hashCode() Returns the hash code of the String that representes this path.
boolean	isChildOf(Path parent) Checks if this path is a child of the parent path.
boolean	isContainedIn(Path root) Checkes if the current path is contained in another path.
boolean	isRelative() Cheks if this path is relative (when the first element of this path is "..")
boolean	isRoot() Returns true if this path is a ROOT path (when the path is empty)
Path	replace(int index, java.lang.String element)
Path	successor() Returns the successor of this Path, as defined in the Javadoc of java.util.TreeMap.subMap(...)
java.lang.String	toString() Returns the String representation of the current path.

Methods inherited from class java.lang.Object

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

Field Detail

pathName

protected java.lang.String pathName

elements

protected java.lang.String[] elements

ROOT

public static final Path ROOT

Constructor Detail

Path

public Path()

Creates an empty path.

Path

public Path(java.lang.Object o)

Creates a path and adds an object to it.

Parameters:

o - the Object to be added to this new path

Path

public Path(java.lang.Object o1,
            java.lang.Object o2)

Creates a path and adds two objects to it.

Parameters:

o1 - the Object 1 to be added

o2 - the Object 2 to be added

Path

public Path(java.lang.Object o1,
            java.lang.Object o2,
            java.lang.Object o3)

Creates a path and adds three objects to it.

Parameters:

o1 - the Object 1 to be added

o2 - the Object 2 to be added

o3 - the Object 3 to be added

Method Detail

addObjectToList

protected void addObjectToList(java.util.List list,
                               java.lang.Object o)

add

public Path add(java.lang.Object o)

Adds an object to the current path.

Parameters:

o - the Object to be added to the current path

Returns:

a new Path which is the combination of the current path and the added object

add

public Path add(java.lang.Object o1,
                java.lang.Object o2)

Adds two objects to the current path.

Parameters:

o1 - Object 1 to add

o2 - Object 2 to add

Returns:

a new Path which is the combination of the current path and the added objects

getParent

public Path getParent()

Return the parent of the current path. The parent of the root path is '..' (a Path with one element whose value is "..").

Returns:

the parent of the current path.

getPartial

public Path getPartial(int count)

Returns a parent of the current path, whose element count is equal to the passed value.

Parameters:

count - the count

Returns:

the parent of he current path

getCommonPath

public Path getCommonPath(Path other)

Returns the common part between the two Paths (between this path and the other path).

Parameters:

other - the second path

Returns:

the common path

isRelative

public boolean isRelative()

Cheks if this path is relative (when the first element of this path is "..")

Returns:

true when the first element of the current path is "..".

isRoot

public boolean isRoot()

Returns true if this path is a ROOT path (when the path is empty)

Returns:

true if the path is empty.

isChildOf

public boolean isChildOf(Path parent)

Checks if this path is a child of the parent path.

Parameters:

parent - the parent path

Returns:

true if the path current path is contained in the given path directly. Example:

 Path myPath = new Path("home/user/myfile.txt");
 myPath.isChildOf(new Path("nohome")); // returns false
 myPath.isChildOf(new Path("home")); // returns false
 myPath.isChildOf(new Path("home/user")); // returns true
 

isContainedIn

public boolean isContainedIn(Path root)

Checkes if the current path is contained in another path.

Parameters:

root - the othr path where to check if the current path is contained.

Returns:

true if the current path is contained in the given path (at any depth). Example:

 Path myPath = new Path("home/user/myfile.txt");
 myPath.isContainedIn(new Path("nohome")); // returns false
 myPath.isContainedIn(new Path("home")); // returns true
 myPath.isContainedIn(new Path("home/user")); // returns true
 

getRelativeTo

public Path getRelativeTo(java.lang.Object root)

Returns the current path as relative to the given root. Example:

 Path myPath = new Path("home/user/myfile.txt");
 myPath.getRelativeTo(new Path("home")); // returns "user/myfile.txt"
 

Parameters:

root - the root to relate this path to.

Returns:

the current path as relative to the given root.

getFile

public java.io.File getFile(java.io.File parent)

Returns a File object relative to the given file.

Parameters:

parent - the parent file as a relative base

Returns:

the new relative file.

getElementCount

public int getElementCount()

Returns the number of elements of the current path. Example:

 new Path().getElementCount(); // returns 0
 new Path("home/user").getElementCount(); // returns 2
 new Path("../user").getElementCount(); // returns 2






Returns:
the number of elements the current path has.

getElementAt

public java.lang.String getElementAt(int index)

Returns the element at the given index. There is no check for the index value, so an ArrayIndexOutOfBoundsException might be thrown.

Parameters:

index - the index for the searched element.

Returns:

element at the given index

getLastElement

public java.lang.String getLastElement()

Returns the last element of the current path (usually the file name). For the root path the empty String is returned.

Returns:

the last element of the Path

toString

public java.lang.String toString()

Returns the String representation of the current path. The separator between elements is always a slash, regardless of the platform.

getAsLink

public java.lang.String getAsLink()

Returns this path object encoded As a link: if the path is not empty, adds a slash at the beginning.

Returns:

a link represenation of this path.

compareTo

public int compareTo(java.lang.Object o)

Compares this path to a new Path built by calling new Path(o)

Specified by:

compareTo in interface java.lang.Comparable

compareTo

public int compareTo(Path other)

Compares two paths. Please note that path1.compareTo(path2) is different from path1.toString().compareTo(path2.toString()), since this method compares the single elements of the paths.

Parameters:

other - the path to compare to this path

Returns:

-1, 0 or 1 as a compare result.

hashCode

public int hashCode()

Returns the hash code of the String that representes this path.

equals

public boolean equals(java.lang.Object o)

Checks the two paths for equality. They are equal when their string representations are equal.

commonPart

public static Path commonPart(Path p1,
                              Path p2)

Returns the common part between the two Paths.

Parameters:

p1 - the Path 1

p2 - the Path 2

Returns:

a Path representing the common part between p1 and p2

successor

public Path successor()

Returns the successor of this Path, as defined in the Javadoc of java.util.TreeMap.subMap(...). This is useful when you need to use that method to get a closed range submap (or headmap, or tailmap) of Paths.

Returns:

the successor path

clone

protected java.lang.Object clone()
                          throws java.lang.CloneNotSupportedException

Throws:

java.lang.CloneNotSupportedException

replace

public Path replace(int index,
                    java.lang.String element)

getElements

public java.lang.String[] getElements()

Returns a copy of the elements array.