Path (Hawkular Commons Inventory Paths 0.6.1.Final API)

java.lang.Object
- org.hawkular.inventory.paths.Path

Direct Known Subclasses:

CanonicalPath, RelativePath
```
public abstract class Path
extends Object
```
Represents a path in an inventory. The path is either CanonicalPath or RelativePath.
The path can be iterated both ways either from the current segment up from the root down to the current segment using the ascendingIterator() or descendingIterator() respectively. The Iterable interface is implemented using the ascendingIterator().
The up() and down() methods can also be used to get at the paths of the ancestors in an easy manner. Note though, that these methods don't do any "database lookup" of any sort. They merely work with the path of the first path instance created.
The following examples illustrate the behavior of up() and down() methods:
```
 CanonicalPath p = CanonicalPath.of().tenant("t").environment("e").resource("r").build();
 p.down(); // == undefined (p.down().isDefined() == false)
 p.up(); // == t/e
 p.up(2); // == t
 p.up().up(2); // == undefined

 p.up().down(); // == t/e/r
 p.up().up().down(); // == t/e
 p.up().down().down(); // == undefined
 
```
The serialized form of the path has the following format:
```
 type;id/type;id/type;id
 
```
I.e. each of the path segments consists of the type of the element it represents followed by the id of the element.
The type of the entity is one of:
- t - tenant,
- e - environment,
- rt - resource type,
- mt - metric type,
- f - feed,
- m - metric,
- r - resource,
- rl - relationship
- d - structured data (configurations)
  In addition to that, the relative paths can contain the special "up" token - .. - instead of the type:id pair. E.g. a relative path may look like this: ../e;production/r;myResource.
Since:

0.2.0

Author:

Lukas Krejci

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`Path.Extender` While `CanonicalPath.Builder` or `RelativePath.Builder` provide compile-time-safe canonical path construction, this class provides the same behavior at runtime, throwing `IllegalArgumentException`s if the segments being added to a path are invalid in given context.
`protected static interface`	`Path.ExtenderConstructor`
`static class`	`Path.HintedTypeProvider` This is a type provider (`Path.TypeProvider`) implementation that tries to deduce the types on the path based on the current position and the intended type of the final segment of the path.
`static class`	`Path.Segment`
`static class`	`Path.StructuredDataHintingTypeProvider`
`static interface`	`Path.TypeProvider` An interface that is used to help parsing partially untyped path strings.

Field Summary

Fields
Modifier and Type Field and Description

protected int endIdx

protected List<Path.Segment> path

static char PATH_DELIM

protected int startIdx

static char TYPE_DELIM

Fields
Modifier and Type	Field and Description
`protected int`	`endIdx`
`protected List<Path.Segment>`	`path`
`static char`	`PATH_DELIM`
`protected int`	`startIdx`
`static char`	`TYPE_DELIM`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`Iterator<? extends Path>`	`ascendingIterator()`
`Iterator<? extends Path>`	`descendingIterator()`
`Path`	`down()` If this path was created by going `up` from another path, then this method can be used to go back down to the previous paths representing some child resource of the resource represented by this path object.
`Path`	`down(int distance)` If this path was created by going `up` from another path, then this method can be used to go back down n steps to the previous paths representing some (grand-)child resource of the resource represented by this path object.
`boolean`	`equals(Object o)`
`static Path`	`fromPartiallyUntypedString(String path, CanonicalPath canonicalPathsOrigin, CanonicalPath relativePathsOrigin, SegmentType intendedFinalType)` This is mostly meant as a helper to REST API.
`static Path`	`fromPartiallyUntypedString(String path, Path.TypeProvider typeProvider)` Parses the provided path using the type provider (`Path.TypeProvider`) to figure out the types of segments that don't explicitly mention it.
`static Path`	`fromString(String path)`
`int`	`getDepth()`
`List<Path.Segment>`	`getPath()` Get the full path represented as an array of the individual segments.
`Path.Segment`	`getSegment()`
`Path.Segment`	`getTop()`
`int`	`hashCode()`
`boolean`	`isCanonical()`
`boolean`	`isDefined()` Checks whether the path is well-formed.
`protected boolean`	`isParentOf(Path other)`
`boolean`	`isRelative()`
`abstract Path.Extender`	`modified()`
`protected abstract Path`	`newInstance(int startIdx, int endIx, List<Path.Segment> segments)`
`abstract CanonicalPath`	`toCanonicalPath()` Tries to convert this path to a canonical path.
`abstract RelativePath`	`toRelativePath()` Tries to convert this path to a relative path.
`String`	`toString()`
`Path`	`up()` Returns a path corresponding to the direct ancestor of the resource represented by this path object.
`Path`	`up(int distance)` Returns a path corresponding to the n-th ancestor in the hierarchy.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - TYPE_DELIM
```
public static final char TYPE_DELIM
```
    See Also:
    
    Constant Field Values
  - PATH_DELIM
```
public static final char PATH_DELIM
```
    See Also:
    
    Constant Field Values
  - path
```
protected final List<Path.Segment> path
```
  - startIdx
```
protected final int startIdx
```
  - endIdx
```
protected final int endIdx
```
- Method Detail
  - fromString
```
public static Path fromString(String path)
```
  - fromPartiallyUntypedString
```
public static Path fromPartiallyUntypedString(String path,
                                              Path.TypeProvider typeProvider)
```
    Parses the provided path using the type provider (Path.TypeProvider) to figure out the types of segments that don't explicitly mention it.
    This is mainly geared at REST API in which this is used to parse the relative paths out of URIs in which the type of some segments can be easily deduced from the endpoint address.
    
    Parameters:
    
    path - the path to parse
    
    typeProvider - the type provider used to figure out types of segments that don't explicitly mention it
    
    Returns:
    
    the parsed path
  - fromPartiallyUntypedString
```
public static Path fromPartiallyUntypedString(String path,
                                              CanonicalPath canonicalPathsOrigin,
                                              CanonicalPath relativePathsOrigin,
                                              SegmentType intendedFinalType)
```
    This is mostly meant as a helper to REST API. If the provided path is canonical (starts with a slash) the canonicalPathOrigin together with the intendedFinalType will be used to construct a full canonical path from the potentially untyped input. If the input path is relative, the relativePathsOrigin will be used instead.
    
    Parameters:
    
    path - the potentially partially untyped input path
    
    canonicalPathsOrigin - the origin to "prefix" the path if it is canonical
    
    relativePathsOrigin - the origin to resolve the relative path against (if the input path is relative)
    
    intendedFinalType - the intended type of the final segment of the path
  - newInstance
```
protected abstract Path newInstance(int startIdx,
                                    int endIx,
                                    List<Path.Segment> segments)
```
  - toRelativePath
```
public abstract RelativePath toRelativePath()
```
    Tries to convert this path to a relative path. This can result in a new instance construction if this instance is a canonical path.
    
    Returns:
    
    this instance converted to RelativePath
  - toCanonicalPath
```
public abstract CanonicalPath toCanonicalPath()
```
    Tries to convert this path to a canonical path. This can result in a new instance construction if this instance is a relative path.
    
    Returns:
    
    this instance converted to CanonicalPath
    
    Throws:
    
    IllegalArgumentException - if this instance is a relative path and it cannot be converted to canonical path
  - isParentOf
```
protected boolean isParentOf(Path other)
```
  - modified
```
public abstract Path.Extender modified()
```
    Returns:
    
    extender instance to produce an new path instance extending this one
  - isCanonical
```
public boolean isCanonical()
```
    Returns:
    
    true if this is an instance of CanonicalPath, false otherwise
  - isRelative
```
public boolean isRelative()
```
    Returns:
    
    true if this is an instance of RelativePath, false otherwise
  - isDefined
```
public boolean isDefined()
```
    Checks whether the path is well-formed. Going up() or down() on the path can render it undefined if it is traversed "too far" in either of the directions.
    
    Returns:
    
    true if this path is well-formed, false otherwise.
  - up
```
public Path up()
```
    Returns a path corresponding to the direct ancestor of the resource represented by this path object.
    
    Returns:
    
    the ancestor path (may be undefined.
  - up
```
public Path up(int distance)
```
    Returns a path corresponding to the n-th ancestor in the hierarchy.
    
    Parameters:
    
    distance - the distance of the ancestor from the resource represented by this path object.
    
    Returns:
    
    the ancestor path (may be undefined.
  - down
```
public Path down()
```
    If this path was created by going up from another path, then this method can be used to go back down to the previous paths representing some child resource of the resource represented by this path object.
    
    Returns:
    
    a path to a direct child of the resource represented by this path (may be undefined.
  - down
```
public Path down(int distance)
```
    If this path was created by going up from another path, then this method can be used to go back down n steps to the previous paths representing some (grand-)child resource of the resource represented by this path object.
    
    Parameters:
    
    distance - the distance from this path to the child path
    
    Returns:
    
    a path to a child of the resource represented by this path (may be undefined.
  - getDepth
```
public int getDepth()
```
    Returns:
    
    the number of ancestors. This may be less than zero for undefined paths (see isDefined()).
  - getTop
```
public Path.Segment getTop()
```
    Returns:
    
    the top segment in this path or null if this path is not defined.
  - getSegment
```
public Path.Segment getSegment()
```
    Returns:
    
    the last path segment on the path or null if this path is not defined. E.g. if this path represents "a/b/c" then the segment returned from this method is "c"
  - getPath
```
public List<Path.Segment> getPath()
```
    Get the full path represented as an array of the individual segments. The 0-th element in the array represents the segment of the root entity and the last element of the array is the segment of this path instance.
    
    Returns:
    
    the unmodifiable path segments or empty list if this path is undefined.
  - ascendingIterator
```
public Iterator<? extends Path> ascendingIterator()
```
    Returns:
    
    the iterator that ascends the path from the current segment up to the root
  - descendingIterator
```
public Iterator<? extends Path> descendingIterator()
```
    Returns:
    
    the iterator that descends from the root down to the current segment.
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - equals
```
public boolean equals(Object o)
```
    Overrides:
    
    equals in class Object
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class Path

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

TYPE_DELIM

PATH_DELIM

path

startIdx

endIdx

Method Detail

fromString

fromPartiallyUntypedString

fromPartiallyUntypedString

newInstance

toRelativePath

toCanonicalPath

isParentOf

modified

isCanonical

isRelative

isDefined

up

up

down

down

getDepth

getTop

getSegment

getPath

ascendingIterator

descendingIterator

hashCode

equals

toString