Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 `String`s, 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 `Path`s.

  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.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD