ResourcePath (OpenAM Server Only 6.5.5 Documentation)

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 ResourcePath.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.resourcePath(String), or by deriving new resource paths from existing values, e.g. using ResourcePath.parent() or ResourcePath.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 and Description
`ResourcePath()` Creates a new empty resource path whose string representation is the empty string and which has zero path elements.
`ResourcePath(Collection<? extends Object> pathElements)` Creates a new resource path having the provided path elements.
`ResourcePath(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 and 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(ResourcePath suffix)` Creates a new resource path which is a descendant of this resource path.
`ResourcePath`	`concat(String 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(ResourcePath prefix)` Returns `true` if this resource path is equal to or begins with the provided resource resource path.
`boolean`	`startsWith(String 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 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 ResourcePath.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.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:
    
    ResourcePath.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:
    
    ResourcePath.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.resourcePath(String)

Class ResourcePath

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Constructor Detail

ResourcePath

ResourcePath

ResourcePath

Method Detail

empty

format

resourcePath

valueOf

child

compareTo

concat

concat

equals

get

hashCode

head

isEmpty

iterator

leaf

parent

size

startsWith

startsWith

subSequence

tail

toString