public class Path
extends java.lang.Object
When working with Paths, leading and trailing slashes are completely disregarded. Any leading and trailing slashes in the documentation are illustrative only and could be excluded to achieve the same result. Multiple consecutive slashes are treated as a single slash. There will never be an empty string or null path part.
In addition to representing concrete paths, such as a file path or url path, a Path object may contain wildcards, regular expressions, and variable name bindings which are used when comparing a variablized abstract paths with a concrete path.
Paths are primarily used to configure Rules (Engine, Api, Endpoint and Action are all subclasses of Rule) to match against inbound Request urls to determine how the Request will be processed.
Paths can be variablized as follows:
Pattern for matching
When used in the context of a Api configuration you may see something like this:
Engine e = new Engine().withIncludeOn(null, new Path("/apis"));
.withApi(new Api().withIncludeOn(null, new Path("bookstore/{storeName:johnsBestBooks|carolsBooksOnMain}"))
.withEndpoint(new Endpoint().withIncludeOn(null, new Path("categories/:category/"))
.withAction(new BrowseCategoriesAction().withIncludeOn(null, new Path("[:subcategory]/*")))));
| Constructor and Description |
|---|
Path()
Creates an empty Path
|
Path(java.util.List<java.lang.String> parts)
Convenience overload of
Path(String...). |
Path(Path path)
Creates a clone of the supplied
Path |
Path(java.lang.String... part)
Constructs a Path based on all of the supplied
parts. |
| Modifier and Type | Method and Description |
|---|---|
void |
add(java.lang.String parts)
Adds
part to the end of the Path. |
boolean |
equals(java.lang.Object o) |
Path |
extract(java.util.Map params,
Path toMatch)
Convenience overloading of
extract(Map, Path, boolean) with greedy = true. |
Path |
extract(java.util.Map params,
Path matchingConcretePath,
boolean greedy)
Consumes the matching parts of
matchingConcretePath and extracts any named variable to matchingConcretePath if this
any of this paths parts contain variable bindings. |
java.lang.String |
first()
Simple way to pull the first element of the path without having to check for
size() > 0 first. |
java.lang.String |
get(int index)
Simple way to get element at
index without haveint to check for size() > index first. |
java.lang.String |
getVarName(int index)
Extracts a variable name form the path expression if
index exists and has a var name. |
boolean |
isOptional(int index)
Square brackets, '[]', indicate that a path path (and by implication, all following parts) are considered optional for path matching.
|
boolean |
isStatic(int index)
Checks to see if the value at
index is a wildcard, a variable, or is optional. |
boolean |
isVar(int index)
Check to see if the value at
index starts with '${', '{', ':' after removing any leading '[' characters. |
boolean |
isWildcard(int index)
Check if the path part at
index is equal to '*' without having
to check if size() @lt; index first. |
java.lang.String |
last()
Simple way to pull the last element of the path without having to check for
size() > 0 first. |
boolean |
matches(Path concretePath)
Checks if this Path is as case insensitive match, including any optional rules, wildcards, and regexes to
concretePath. |
boolean |
matches(java.lang.String toMatch)
Convenience overloading of
matches(Path). |
java.util.List<java.lang.String> |
parts()
Gets the path parts as a List.
|
java.lang.String |
remove(int index)
Simple way to remove the path part at
index without having to check for size() @lt; index first. |
int |
size() |
boolean |
startsWith(java.util.List<java.lang.String> partsToMatch)
Performs a case insensitive string match between this Path and
pathsToMatch. |
Path |
subpath(int fromIndex,
int toIndex)
Creates a new sub Path.
|
java.lang.String |
toString() |
public Path()
public Path(Path path)
Pathpath - the Path to be clonedpublic Path(java.lang.String... part)
parts.
The strings in part may themselves contain "/" characters and will be split into multiple parts correspondingly.
Meaning Path p = new Path("part1", "part2/part3", "/part4/", "////part5//part6/", "part7") is valid
and would result in a Path with parts "part1", "part2", "part3", "part4", "part5", "part6", "part7".
part - an array of path part stringspublic Path(java.util.List<java.lang.String> parts)
Path(String...).parts - an list of path part stringspublic java.util.List<java.lang.String> parts()
Method signature could easily have been "asList()"
public java.lang.String first()
size() > 0 first.public java.lang.String last()
size() > 0 first.public java.lang.String get(int index)
index without haveint to check for size() > index first.index - the index of the path part to retrivepublic void add(java.lang.String parts)
part to the end of the Path.
The parts is exploded via Utils.explode('/', part) first so while the part arg is a
single value, it could result in multiple additions.
parts - path parts to addpublic java.lang.String remove(int index)
index without having to check for size() @lt; index first.index - the index of the path part to removeindex if it existed otherwise nullpublic boolean startsWith(java.util.List<java.lang.String> partsToMatch)
pathsToMatch.
Wildcards and regular expressions are not supported in this method, only straight case insensitive string comparison.
partsToMatch - the path parts to to match againstpartsToMatch is a case insensitive match to this Path at the same index otherwise false.public int size()
public java.lang.String toString()
toString in class java.lang.Objectpublic boolean equals(java.lang.Object o)
equals in class java.lang.Objectpublic Path subpath(int fromIndex, int toIndex)
fromIndex - low endpoint (inclusive) of the subListtoIndex - high endpoint (exclusive) of the subListfromIndex (inclusive) to toIndex (exclusive)public boolean isStatic(int index)
index is a wildcard, a variable, or is optional.index - the path part to checkindex is a '*' char or starts with '[', '{' or ':'public boolean isWildcard(int index)
index is equal to '*' without having
to check if size() @lt; index first.index - the path part to checkindexpublic boolean isVar(int index)
index starts with '${', '{', ':' after removing any leading '[' characters.index - the index to checkpublic java.lang.String getVarName(int index)
index exists and has a var name.
'varName' would be extracted from getVarName(1) for the following paths.
Square brackets indicating a path component is optioanl don't impact retrieval of the var name so the following would return the same as there above counterparts:
index - the index of the var name to getindex if it existspublic boolean isOptional(int index)
For example: new Path("first/second/[third]/").matches(new Path("first/second/third"))
index - the part part to checkindex exists and starts with '[' and ends with ']'public boolean matches(java.lang.String toMatch)
matches(Path).toMatch - the path string to matchpublic boolean matches(Path concretePath)
concretePath.
As the name implies concretePath is considered to be a literal path not containing optionals, wildcards, and regexes.
As also documented above:
All non regex comparisons are performed with String.equalsIgnoreCase.
All regexes are compiled with Pattern.CASE_INSENSITIVE.
concretePath - the path to match againstconcretePathpublic Path extract(java.util.Map params, Path toMatch)
extract(Map, Path, boolean) with greedy = true.params - a map to add extracted name/value pairs totoMatch - the path to extract fromextract(Map, Path, boolean)public Path extract(java.util.Map params, Path matchingConcretePath, boolean greedy)
matchingConcretePath and extracts any named variable to matchingConcretePath if this
any of this paths parts contain variable bindings.
If greedy is true, the match will consume through matching optional path parts.
If greedy is false, variable bindings in any optional paths parts will be extracted but the parts will not be removed from matchingConcretePath.
Here is an example:
Map params = new HashMap();
Path engineMatch = new Path("apis/myapi/*");
Path apiMatch = new Path("${version:v1|v2}/:tenant")
Path endpointMatch = new Path("[${collection:books|categories|orders}]/*");
Path actionMatch = new Path("[:orderId]/*");
Path requestPath = new Path("/apis/myapi/v2/bobsBooks/orders/67890");
engineMatch.extract(requestPath);
// params is empty, requestPath is now 'v2/bobsBooks/orders/67890'
apiMatch.extract(requestPath);
//version=v2 and tenant=bobsBooks have been added to params and requestPath is now 'orders/67890'
endpointMatch.extract(requestPath);
//collection=orders has been added to params and requestPath is now '67890'
actionMatch.extract(requestPath);
//orderId=67890 has been added to params and requestPath is now empty.
The above example is very similar to how an Engine processes paths when selecting an Api, Endpoint, and Actions to run.
Engine will also add the params to the Request Url params as if they had been supplied as name value pairs by the caller on the query string.
params - the map to add extracted name/value pairs tomatchingConcretePath - the path to extract fromgreedy - if extraction should consume through optional path partsEngine.service(Request, Response),
Chain.next()Copyright © 2021 Rocket Partners, LLC. All rights reserved.