Package org.forgerock.json.resource

Class 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

      All Methods Static Methods Instance Methods Concrete Methods 
      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.

    • Constructor Detail

      • 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 Detail

      • 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:
        toString()

      • 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:
        toString()

      • 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:
        resourcePath(String)