Package org.forgerock.json.resource

Class ResourcePath

java.lang.Object
org.forgerock.json.resource.ResourcePath
All Implemented Interfaces:
Comparable<ResourcePath>, Iterable<String>
public final class ResourcePath extends Object implements Comparable<ResourcePath>, Iterable<String>
A relative path, or URL, to a resource. A resource path is an ordered list of zero or more path elements in big-endian order. The string representation of a resource path conforms to the URL path encoding rules defined in RFC 3986 section 3.3: 
 
 path          = path-abempty    ; begins with "/" or is empty
                 / ...

 path-abempty  = *( "/" segment )
 segment       = *pchar
 pchar         = unreserved / pct-encoded / sub-delims / ":" / "@"

 unreserved    = ALPHA / DIGIT / "-" / "." / "_" / "~"
 pct-encoded   = "%" HEXDIG HEXDIG
 sub-delims    = "!" / "$" / "&" / "'" / "(" / ")"
                 / "*" / "+" / "," / ";" / "="

 HEXDIG        =  DIGIT / "A" / "B" / "C" / "D" / "E" / "F"
 ALPHA         =  %x41-5A / %x61-7A   ; A-Z / a-z
 DIGIT         =  %x30-39             ; 0-9
The empty resource path having zero path elements may be obtained by calling empty(). Resource paths are case insensitive and empty path elements are not allowed. In addition, resource paths will be automatically trimmed such that any leading or trailing slashes are removed. In other words, all resource paths will be considered to be "relative". At the moment the relative path elements "." and ".." are not supported.

New resource paths can be created from their string representation using resourcePath(String), or by deriving new resource paths from existing values, e.g. using parent() or child(Object).

Example: 

 ResourcePath base = ResourcePath.valueOf("commons/rest");
 ResourcePath child = base.child("hello world");
 child.toString(); // commons/rest/hello%20world

 ResourcePath user = base.child("users").child(123);
 user.toString(); // commons/rest/users/123

  • Constructor Summary

    Constructors
    Constructor
    Description
    ResourcePath()
    Creates a new empty resource path whose string representation is the empty string and which has zero path elements.
    ResourcePath(Object... pathElements)
    Creates a new resource path having the provided path elements.
    ResourcePath(Collection<? extends Object> pathElements)
    Creates a new resource path having the provided path elements.

  • Method Summary

    Modifier and Type
    Method
    Description
    ResourcePath
    child(Object pathElement)
    Creates a new resource path which is a child of this resource path.
    int
    compareTo(ResourcePath o)
    Compares this resource path with the provided resource path.
    ResourcePath
    concat(String suffix)
    Creates a new resource path which is a descendant of this resource path.
    ResourcePath
    concat(ResourcePath suffix)
    Creates a new resource path which is a descendant of this resource path.
    static ResourcePath
    empty()
    Returns the empty resource path whose string representation is the empty string and which has zero path elements.
    boolean
    equals(Object obj)
    Returns true if obj is a resource path having the exact same elements as this resource path.
    static ResourcePath
    format(String template, Object... pathElements)
    Creates a new resource path using the provided path template and unencoded path elements.
    String
    get(int index)
    Returns the path element at the specified position in this resource path.
    int
    hashCode()
    Returns a hash code for this resource path.
    ResourcePath
    head(int endIndex)
    Returns a resource path which is a subsequence of the path elements contained in this resource path beginning with the first element (0) and ending with the element at position endIndex-1.
    boolean
    isEmpty()
    Returns true if this resource path contains no path elements.
    Iterator<String>
    iterator()
    Returns an iterator over the path elements in this resource path.
    String
    leaf()
    Returns the last path element in this resource path.
    ResourcePath
    parent()
    Returns the resource path which is the immediate parent of this resource path, or null if this resource path is empty.
    static ResourcePath
    resourcePath(String path)
    Parses the provided string representation of a resource path.
    int
    size()
    Returns the number of elements in this resource path, or 0 if it is empty.
    boolean
    startsWith(String prefix)
    Returns true if this resource path is equal to or begins with the provided resource resource path.
    boolean
    startsWith(ResourcePath prefix)
    Returns true if this resource path is equal to or begins with the provided resource resource path.
    ResourcePath
    subSequence(int beginIndex, int endIndex)
    Returns a resource path which is a subsequence of the path elements contained in this resource path beginning with the element at position beginIndex and ending with the element at position endIndex-1.
    ResourcePath
    tail(int beginIndex)
    Returns a resource path which is a subsequence of the path elements contained in this resource path beginning with the element at position beginIndex and ending with the last element in this resource path.
    String
    toString()
    Returns the URL path encoded string representation of this resource path.
    static ResourcePath
    valueOf(String path)
    Parses the provided string representation of a resource path.

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface java.lang.Iterable

    forEach, spliterator

  • Constructor Details

    • ResourcePath

      public ResourcePath()
      Creates a new empty resource path whose string representation is the empty string and which has zero path elements. This method is provided in order to comply with the Java Collections Framework recommendations. However, it is recommended that applications use empty() in order to avoid unnecessary memory allocation.

    • ResourcePath

      public ResourcePath(Collection<? extends Object> pathElements)
      Creates a new resource path having the provided path elements.
      Parameters:
      pathElements - The unencoded path elements.

    • ResourcePath

      public ResourcePath(Object... pathElements)
      Creates a new resource path having the provided path elements.
      Parameters:
      pathElements - The unencoded path elements.

  • Method Details

    • empty

      public static ResourcePath empty()
      Returns the empty resource path whose string representation is the empty string and which has zero path elements.
      Returns:
      The empty resource path.

    • format

      public static ResourcePath format(String template, Object... pathElements)
      Creates a new resource path using the provided path template and unencoded path elements. This method first URL encodes each of the path elements and then substitutes them into the template using String.format(String, Object...). Finally, the formatted string is parsed as a resource path using resourcePath(String).

      This method may be useful in cases where the structure of a resource path is not known at compile time, for example, it may be obtained from a configuration file. Example usage: 

       String template = "rest/users/%s"
 ResourcePath path = ResourcePath.format(template, "bjensen");
      Parameters:
      template - The resource path template.
      pathElements - The path elements to be URL encoded and then substituted into the template.
      Returns:
      The formatted template parsed as a resource path.
      Throws:
      IllegalArgumentException - If the formatted template contains empty path elements.
      See Also:
      • Paths.urlEncode(Object)

    • resourcePath

      public static ResourcePath resourcePath(String path)
      Parses the provided string representation of a resource path.
      Parameters:
      path - The URL-encoded resource path to be parsed.
      Returns:
      The provided string representation of a resource path.
      Throws:
      IllegalArgumentException - If the resource path contains empty path elements.
      See Also:

    • valueOf

      public static ResourcePath valueOf(String path)
      Parses the provided string representation of a resource path.
      Parameters:
      path - The URL-encoded resource path to be parsed.
      Returns:
      The provided string representation of a resource path.
      Throws:
      IllegalArgumentException - If the resource path contains empty path elements.
      See Also:

    • child

      public ResourcePath child(Object pathElement)
      Creates a new resource path which is a child of this resource path. The returned resource path will have the same path elements as this resource path and, in addition, the provided path element.
      Parameters:
      pathElement - The unencoded child path element.
      Returns:
      A new resource path which is a child of this resource path.

    • compareTo

      public int compareTo(ResourcePath o)
      Compares this resource path with the provided resource path. Resource paths are compared case sensitively and ancestors sort before descendants.
      Specified by:
      compareTo in interface Comparable<ResourcePath>
      Parameters:
      o -
      Returns:

    • concat

      public ResourcePath concat(ResourcePath suffix)
      Creates a new resource path which is a descendant of this resource path. The returned resource path will have be formed of the concatenation of this resource path and the provided resource path.
      Parameters:
      suffix - The resource path to be appended to this resource path.
      Returns:
      A new resource path which is a descendant of this resource path.

    • concat

      public ResourcePath concat(String suffix)
      Creates a new resource path which is a descendant of this resource path. The returned resource path will have be formed of the concatenation of this resource path and the provided resource path.
      Parameters:
      suffix - The resource path to be appended to this resource path.
      Returns:
      A new resource path which is a descendant of this resource path.
      Throws:
      IllegalArgumentException - If the the suffix contains empty path elements.

    • equals

      public boolean equals(Object obj)
      Returns true if obj is a resource path having the exact same elements as this resource path.
      Overrides:
      equals in class Object
      Parameters:
      obj - The object to be compared.
      Returns:
      true if obj is a resource path having the exact same elements as this resource path.

    • get

      public String get(int index)
      Returns the path element at the specified position in this resource path. The path element at position 0 is the top level element (closest to root).
      Parameters:
      index - The index of the path element to be returned, where 0 is the top level element.
      Returns:
      The path element at the specified position in this resource path.
      Throws:
      IndexOutOfBoundsException - If the index is out of range (index < 0 || index >= size()).

    • hashCode

      public int hashCode()
      Returns a hash code for this resource path.
      Overrides:
      hashCode in class Object
      Returns:
      A hash code for this resource path.

    • head

      public ResourcePath head(int endIndex)
      Returns a resource path which is a subsequence of the path elements contained in this resource path beginning with the first element (0) and ending with the element at position endIndex-1. The returned resource path will therefore have the size endIndex. Calling this method is equivalent to: 
       subSequence(0, endIndex);
      Parameters:
      endIndex - The end index, exclusive.
      Returns:
      A resource path which is a subsequence of the path elements contained in this resource path.
      Throws:
      IndexOutOfBoundsException - If endIndex is bigger than size().

    • isEmpty

      public boolean isEmpty()
      Returns true if this resource path contains no path elements.
      Returns:
      true if this resource path contains no path elements.

    • iterator

      public Iterator<String> iterator()
      Returns an iterator over the path elements in this resource path. The returned iterator will not support the Iterator.remove() method and will return path elements starting with index 0, then 1, then 2, etc.
      Specified by:
      iterator in interface Iterable<String>
      Returns:
      An iterator over the path elements in this resource path.

    • leaf

      public String leaf()
      Returns the last path element in this resource path. Calling this method is equivalent to: 
       resourcePath.get(resourcePath.size() - 1);
      Returns:
      The last path element in this resource path.

    • parent

      public ResourcePath parent()
      Returns the resource path which is the immediate parent of this resource path, or null if this resource path is empty.
      Returns:
      The resource path which is the immediate parent of this resource path, or null if this resource path is empty.

    • size

      public int size()
      Returns the number of elements in this resource path, or 0 if it is empty.
      Returns:
      The number of elements in this resource path, or 0 if it is empty.

    • startsWith

      public boolean startsWith(ResourcePath prefix)
      Returns true if this resource path is equal to or begins with the provided resource resource path.
      Parameters:
      prefix - The resource path prefix.
      Returns:
      true if this resource path is equal to or begins with the provided resource resource path.

    • startsWith

      public boolean startsWith(String prefix)
      Returns true if this resource path is equal to or begins with the provided resource resource path.
      Parameters:
      prefix - The resource path prefix.
      Returns:
      true if this resource path is equal to or begins with the provided resource resource path.
      Throws:
      IllegalArgumentException - If the the prefix contains empty path elements.

    • subSequence

      public ResourcePath subSequence(int beginIndex, int endIndex)
      Returns a resource path which is a subsequence of the path elements contained in this resource path beginning with the element at position beginIndex and ending with the element at position endIndex-1. The returned resource path will therefore have the size endIndex - beginIndex.
      Parameters:
      beginIndex - The beginning index, inclusive.
      endIndex - The end index, exclusive.
      Returns:
      A resource path which is a subsequence of the path elements contained in this resource path.
      Throws:
      IndexOutOfBoundsException - If beginIndex is negative, or endIndex is bigger than size(), or if beginIndex is bigger than endIndex.

    • tail

      public ResourcePath tail(int beginIndex)
      Returns a resource path which is a subsequence of the path elements contained in this resource path beginning with the element at position beginIndex and ending with the last element in this resource path. The returned resource path will therefore have the size size() - beginIndex. Calling this method is equivalent to: 
       subSequence(beginIndex, size());
      Parameters:
      beginIndex - The beginning index, inclusive.
      Returns:
      A resource path which is a subsequence of the path elements contained in this resource path.
      Throws:
      IndexOutOfBoundsException - If beginIndex is negative, or if beginIndex is bigger than size().

    • toString

      public String toString()
      Returns the URL path encoded string representation of this resource path.
      Overrides:
      toString in class Object
      Returns:
      The URL path encoded string representation of this resource path.
      See Also: