Module org.microbean.path

Package org.microbean.path

Class Path<T>

java.lang.Object

org.microbean.path.Path<T>

Type Parameters:

T - the type of the Path; most notably not necessarily the type of the thing the Path "points to"; more like an additional qualifier

All Implemented Interfaces:

Constable, Iterable<Path.Element<?>>, Qualified<String,Object,T>

public final class Path<T>
extends Object
implements Iterable<Path.Element<?>>, Qualified<String,Object,T>

A qualified sequence of named and qualified elements that "points to" an object and that can be used for many different purposes.

A Path can be used like a javax.naming.Name, or like a java.nio.file.Path, or like a java.net.URI. It differs from these other objects in that it combines some of their concepts together.

Author:

Laird Nelson

See Also:

• Path.Element

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	Path.Element<T>	An element normally within a Path, consisting of a Qualifiers, a name, and an optional thing that it designates or points to.

Nested classes/interfaces inherited from interface org.microbean.qualifier.Qualified

Qualified.Record<K extends Comparable<? super K>,V extends Object,T extends Object>

Constructor Summary

Constructors

Constructor	Description
Path(Path.Element<? extends T> lastElement)	Creates a new Path.
Path(Qualifiers<? extends String,?> qualifiers, List<? extends Path.Element<?>> elements, Path.Element<? extends T> lastElement)	Creates a new Path.
Path(Qualifiers<? extends String,?> qualifiers, Path.Element<? extends T> lastElement)	Creates a new Path.

Method Summary

Modifier and Type	Method	Description
final boolean	absolute()	Returns true if and only if this Path is absolute, which means that its first Path.Element is a root Path.Element.
final Optional<? extends ConstantDesc>	describeConstable()	Returns an Optional containing a ConstantDesc representing this Path, or an empty Optional if this Path cannot be represented as a ConstantDesc.
final boolean	endsWith(Path<?> other)	Returns true if this Path ends with a Path that is equal to the supplied Path.
final boolean	endsWith(Path<?> other, BiPredicate<? super Path.Element<?>,? super Path.Element<?>> p)	Returns true if this Path ends with a Path that is equal to the supplied Path.
final boolean	equals(Object other)	Returns true if and only if the supplied Object is equal to this Path.
final Path.Element<?>	get(int index)	Returns the Path.Element found at the supplied zero-based index.
final int	hashCode()	Returns a hashcode for this Path.
final int	indexOf(Path<?> other)	Returns the zero-based index identifying the position of the first occurrence of a Path equal to the supplied Path within this Path, or a negative value if the supplied Path does not occur within this Path.
final int	indexOf(Path<?> path, BiPredicate<? super Path.Element<?>,? super Path.Element<?>> p)	Returns the zero-based index identifying the position of the first occurrence of a Path equal to supplied Path within this Path, or a negative value if the supplied Path does not occur within this Path.
final boolean	isRoot()	Returns true if this Path is a root path, which is true when it has only one element and that element is root.
final Iterator<Path.Element<?>>	iterator()	Returns an Iterator that iterates over the elements of this Path, including the last element.
final Path.Element<T>	lastElement()	Returns the last Path.Element in this Path.
final int	lastIndexOf(Path<?> other)	Returns the zero-based index identifying the position of the last occurrence of a Path equal to the supplied Path within this Path, or a negative value if the supplied Path does not occur within this Path.
final int	lastIndexOf(Path<?> path, BiPredicate<? super Path.Element<?>,? super Path.Element<?>> p)	Returns the zero-based index identifying the position of the last occurrence of a Path equal to supplied Path within this Path, or a negative value if the supplied Path does not occur within this Path.
static final <T> Path<T>	of(Path.Element<? extends T> lastElement)	Returns a (usually new) Path formed from the supplied lastElement.
static final <T> Path<T>	of(Qualifiers<? extends String,?> pathQualifiers, List<? extends Path.Element<?>> elements, Path.Element<? extends T> lastElement)	Return a (usually new) Path formed from the supplied arguments and returns it.
static final <T> Path<T>	of(Qualifiers<? extends String,?> pathQualifiers, Path.Element<? extends T> lastElement)	Return a (usually new) Path formed from the supplied arguments and returns it.
static final <T> Path<T>	of(T qualified)	Returns a (usually new) Path formed from a Path.Element formed from the supplied qualified and an empty name.
static final <T> Path<T>	of(T qualified, String name)	Returns a (usually new) Path formed from a Path.Element formed from the supplied qualified and the supplied name.
static final <T> Path<T>	of(T qualified, String... names)	Returns a (usually new) Path formed from Path.Elements formed from the supplied qualified and the supplied array of names.
static final <T> Path<T>	of(T qualified, List<? extends String> names)	Returns a (usually new) Path formed from Path.Elements formed from the supplied qualified and the supplied List of names.
final Stream<Path.Element<?>>	parallelStream()	Returns a possibly parallel Stream of this Path's Path.Elements.
final <U> Path<U>	plus(Collection<? extends Path.Element<?>> elements, Path.Element<? extends U> lastElement)	Returns a new Path consisting of this Path's qualifiers, this Path's elements, the supplied elements, and the supplied lastElement.
final <U> Path<U>	plus(Path.Element<? extends U> element)	Returns a new Path consisting of this Path's qualifiers and elments plus the supplied element.
final <U> Path<U>	plus(Path<? extends U> path)	Returns a new Path consisting of this Path's qualifiers combined with a prefixed version of the supplied Path's qualifiers, this Path's elements, the supplied Path's elements, and the supplied Path's last element.
final T	qualified()	Calls the Path.Element.qualified() method on the last element in this Path and returns the result.
final Qualifiers<String,Object>	qualifiers()	Returns the Qualifiers that qualifies this Path.
static final Path<?>	root()	Returns a Path that is a root path.
final int	size()	Returns the number of Path.Elements in this Path, which is always greater than or equal to 1.
final Spliterator<Path.Element<?>>	spliterator()	Returns a Spliterator for the elements of this Path, including the last element.
final boolean	startsWith(Path<?> other)	Returns true if this Path starts with a Path that is equal to the supplied Path.
final boolean	startsWith(Path<?> other, BiPredicate<? super Path.Element<?>,? super Path.Element<?>> p)	Returns true if this Path starts with a Path that is equal to the supplied Path.
final Stream<Path.Element<?>>	stream()	Returns a Stream of this Path's Path.Elements.
final String	toString()	Returns a non-null String representation of this Path.
final Path<T>	transliterate()	Transliterates this Path into another, semantically equivalent Path by producing a Path that is otherwise equal to this Path but that will return true from its transliterated() method.
final @Experimental Path<T>	transliterate(BiFunction<? super String,? super Path.Element<?>,? extends Path.Element<?>> f)	Transliterates this Path into another, semantically equivalent Path by applying the supplied BiFunction, and returns the transliterated Path.
final boolean	transliterated()	Returns true if and only if this Path is the result of a call to transliterate(BiFunction).

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach

Constructor Details

Path

public Path(Path.Element<? extends T> lastElement)

Creates a new Path.

Parameters:

lastElement - the last element of this Path; must not be null

Throws:

NullPointerException - if any parameter is null

See Also:

• Path(Qualifiers, List, Element)

Path

public Path(Qualifiers<? extends String,?> qualifiers,
 Path.Element<? extends T> lastElement)

Creates a new Path.

Parameters:

qualifiers - the Path's qualifiers; must not be null

lastElement - the last element of this Path; must not be null

Throws:

NullPointerException - if any parameter is null

See Also:

• Path(Qualifiers, List, Element)

Path

public Path(Qualifiers<? extends String,?> qualifiers,
 List<? extends Path.Element<?>> elements,
 Path.Element<? extends T> lastElement)

Creates a new Path.

Parameters:

qualifiers - the Path's qualifiers; must not be null

elements - the elements of this Path; must not be null; may be empty

lastElement - the last element of this Path; must not be null

Throws:

NullPointerException - if any parameter is null

Method Details

transliterated

public final boolean transliterated()

Returns true if and only if this Path is the result of a call to transliterate(BiFunction).

Returns:

true if this Path is transliterated; false otherwise

transliterate

public final Path<T> transliterate()

Transliterates this Path into another, semantically equivalent Path by producing a Path that is otherwise equal to this Path but that will return true from its transliterated() method.

Transliteration can be needed when a Path is defined by a Java class and used by an application containing that Java class—because another Java class may have used the same element names to refer to different things.

If this Path is already transliterated then it is returned.

This method calls transliterate(BiFunction) with null as its sole argument.

Returns:

the transliterated Path, which may be this Path; never null

See Also:

• transliterate(BiFunction)
• transliterated()

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

transliterate

@Experimental
public final @Experimental Path<T> transliterate(BiFunction<? super String,? super Path.Element<?>,? extends Path.Element<?>> f)

Transliterates this Path into another, semantically equivalent Path by applying the supplied BiFunction, and returns the transliterated Path.

The supplied BiFunction accepts a Java package name as its first argument, which will be the first package name encountered in the current thread's stack that identifies a caller whose package name is not equal to Path.class.getPackageName(). Its second argument is a Element from this Path. It must return a Path.Element representing the transliteration of its second argument (which may be the second argument itself).

Transliteration can be needed when a Path is defined by a Java class and used by an application containing that Java class—because another Java class may have used the same element names to refer to different things.

If this Path is already transliterated then it is returned.

Parameters:

f - a BiFunction responsible for the transliteration, element by element; may be null

Returns:

the transliterated Path, which may be this Path; never null

See Also:

• transliterated()

Idempotency:

This method is idempotent and deterministic, but the supplied BiFunction may not be.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads, but the supplied BiFunction may not be.

describeConstable

public final Optional<? extends ConstantDesc> describeConstable()

Returns an Optional containing a ConstantDesc representing this Path, or an empty Optional if this Path cannot be represented as a ConstantDesc.

A Path instance may be represented by a ConstantDesc only when the return value of an invocation of the Path.Element.describeConstable() method on its last element returns a non-empty Optional.

Specified by:

describeConstable in interface Constable

Specified by:

describeConstable in interface Qualified<String,Object,T>

Returns:

an Optional containing a ConstantDesc representing this Path; never null; possibly empty

See Also:

• Path.Element.describeConstable()

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

qualifiers

public final Qualifiers<String,Object> qualifiers()

Returns the Qualifiers that qualifies this Path.

Specified by:

qualifiers in interface Qualified<String,Object,T>

Returns:

the Qualifiers that qualifies this Path

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

get

public final Path.Element<?> get(int index)

Returns the Path.Element found at the supplied zero-based index.

Parameters:

index - the index of the Path.Element to return; must be 0 or greater and less than this Path's size

Returns:

the Path.Element found at the supplied zero-based index

Throws:

IndexOutOfBoundsException - if index does not meet the requirements described above

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

iterator

public final Iterator<Path.Element<?>> iterator()

Returns an Iterator that iterates over the elements of this Path, including the last element.

Specified by:

iterator in interface Iterable<T>

Returns:

an Iterator that iterates over the elements of this Path, including the last element

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

spliterator

public final Spliterator<Path.Element<?>> spliterator()

Returns a Spliterator for the elements of this Path, including the last element.

Specified by:

spliterator in interface Iterable<T>

Returns:

a Spliterator for the elements of this Path, including the last element

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

stream

public final Stream<Path.Element<?>> stream()

Returns a Stream of this Path's Path.Elements.

Returns:

a possibly parallel Stream of this Path's Path.Elements

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

parallelStream

public final Stream<Path.Element<?>> parallelStream()

Returns a possibly parallel Stream of this Path's Path.Elements.

Returns:

a possibly parallel Stream of this Path's Path.Elements

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

size

public final int size()

Returns the number of Path.Elements in this Path, which is always greater than or equal to 1.

Returns:

the number of Path.Elements in this Path

Idempotency:

This method is idempotent and deterministic.

Thread Safety:

This method is safe for concurrent use by multiple threads.

indexOf

public final int indexOf(Path<?> other)

Returns the zero-based index identifying the position of the first occurrence of a Path equal to the supplied Path within this Path, or a negative value if the supplied Path does not occur within this Path.

Parameters:

other - the other Path; must not be null

Returns:

the zero-based index identifying the position of the first occurrence of a Path equal to supplied Path within this Path, or a negative value if the supplied Path does not occur within this Path

Throws:

NullPointerException - if other is null

Idempotency:

This method is idempotent and deterministic.

Thread Safety:

This method is safe for concurrent use by multiple threads.

indexOf

public final int indexOf(Path<?> path,
 BiPredicate<? super Path.Element<?>,? super Path.Element<?>> p)

Returns the zero-based index identifying the position of the first occurrence of a Path equal to supplied Path within this Path, or a negative value if the supplied Path does not occur within this Path.

The supplied BiPredicate is used to test each Path.Element of the supplied Path against Path.Elements from this Path. The first argument is a Path.Element drawn from this Path. The second argument is an Path.Element drawn from the supplied Path. The BiPredicate returns true if its arguments are deemed to match. The supplied BiPredicate's BiPredicate.test(Object, Object) method must be idempotent and deterministic.

Parameters:

path - the other Path; must not be null

p - the BiPredicate used to test Path.Elements; must not be null

Returns:

the zero-based index identifying the position of the first occurrence of a Path equal to supplied Path within this Path, or a negative value if the supplied Path does not occur within this Path

Throws:

NullPointerException - if either path or p is null

Idempotency:

This method is idempotent and deterministic.

Thread Safety:

This method is safe for concurrent use by multiple threads.

startsWith

public final boolean startsWith(Path<?> other)

Returns true if this Path starts with a Path that is equal to the supplied Path.

This method returns true if and only if:

• other is identical to this Path, or
• An invocation of the indexOf(Path) method with other as its sole argument returns 0

Parameters:

other - the other Path; must not be null

Returns:

true if this Path starts with a Path that is equal to the supplied Path; false otherwise

Throws:

NullPointerException - if other is null

See Also:

• indexOf(Path)

Idempotency:

This method is idempotent and deterministic.

Thread Safety:

This method is safe for concurrent use by multiple threads.

lastElement

public final Path.Element<T> lastElement()

Returns the last Path.Element in this Path.

Returns:

the last Path.Element in this Path

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

lastIndexOf

public final int lastIndexOf(Path<?> other)

Returns the zero-based index identifying the position of the last occurrence of a Path equal to the supplied Path within this Path, or a negative value if the supplied Path does not occur within this Path.

Parameters:

other - the other Path; must not be null

Returns:

the zero-based index identifying the position of the last occurrence of a Path equal to supplied Path within this Path, or a negative value if the supplied Path does not occur within this Path

Throws:

NullPointerException - if other is null

Idempotency:

This method is idempotent and deterministic.

Thread Safety:

This method is safe for concurrent use by multiple threads.

lastIndexOf

public final int lastIndexOf(Path<?> path,
 BiPredicate<? super Path.Element<?>,? super Path.Element<?>> p)

Returns the zero-based index identifying the position of the last occurrence of a Path equal to supplied Path within this Path, or a negative value if the supplied Path does not occur within this Path.

The supplied BiPredicate is used to test each Path.Element of the supplied Path against Path.Elements from this Path. The first argument is a Path.Element drawn from this Path. The second argument is an Path.Element drawn from the supplied Path. The BiPredicate returns true if its arguments are deemed to match. The supplied BiPredicate's BiPredicate.test(Object, Object) method must be idempotent and deterministic.

Parameters:

path - the other Path; must not be null

p - the BiPredicate used to test Path.Elements; must not be null

Returns:

the zero-based index identifying the position of the last occurrence of a Path equal to supplied Path within this Path, or a negative value if the supplied Path does not occur within this Path

Throws:

NullPointerException - if either path or p is null

Idempotency:

This method is idempotent and deterministic.

Thread Safety:

This method is safe for concurrent use by multiple threads.

startsWith

public final boolean startsWith(Path<?> other,
 BiPredicate<? super Path.Element<?>,? super Path.Element<?>> p)

Returns true if this Path starts with a Path that is equal to the supplied Path.

The supplied BiPredicate is used to test each Path.Element of the supplied Path against Path.Elements from this Path. The first argument is a Path.Element drawn from this Path. The second argument is a Path.Element drawn from the supplied Path. The BiPredicate returns true if its arguments are deemed to match. The supplied BiPredicate's BiPredicate.test(Object, Object) method must be idempotent and deterministic.

This method returns true if and only if:

• other is identical to this Path, or
• An invocation of the indexOf(Path, BiPredicate) method with other and p as its arguments returns 0

Parameters:

other - the other Path; must not be null

p - the BiPredicate used to test Path.Elements; must not be null

Returns:

true if this Path starts with a Path that is equal to the supplied Path; false otherwise

Throws:

NullPointerException - if other is null

See Also:

• indexOf(Path, BiPredicate)

Idempotency:

This method is idempotent and deterministic.

Thread Safety:

This method is safe for concurrent use by multiple threads.

endsWith

public final boolean endsWith(Path<?> other)

Returns true if this Path ends with a Path that is equal to the supplied Path.

This method returns true if and only if:

• other is identical to this Path, or
• An invocation of the lastIndexOf(Path) method with other as its sole argument returns 0 or a positive int, and that number plus the supplied Path's size is equal to this Path's size

Parameters:

other - the other Path; must not be null

Returns:

true if this Path ends with a Path that is equal to the supplied Path; false otherwise

Throws:

NullPointerException - if other is null

See Also:

• lastIndexOf(Path)

Idempotency:

This method is idempotent and deterministic.

Thread Safety:

This method is safe for concurrent use by multiple threads.

endsWith

public final boolean endsWith(Path<?> other,
 BiPredicate<? super Path.Element<?>,? super Path.Element<?>> p)

Returns true if this Path ends with a Path that is equal to the supplied Path.

The supplied BiPredicate is used to test each Path.Element of the supplied Path against Path.Elements from this Path. The first argument is a Path.Element drawn from this Path. The second argument is a Path.Element drawn from the supplied Path. The BiPredicate returns true if its arguments are deemed to match. The supplied BiPredicate's BiPredicate.test(Object, Object) method must be idempotent and deterministic.

This method returns true if and only if:

• other is identical to this Path, or
• An invocation of the indexOf(Path, BiPredicate) method with other and p as its arguments returns 0 or a positive int, and if that number plus the supplied Path's size is equal to this Path's size

Parameters:

other - the other Path; must not be null

p - the BiPredicate used to test Path.Elements; must not be null

Returns:

true if this Path ends with a Path that is equal to the supplied Path; false otherwise

Throws:

NullPointerException - if other is null

See Also:

• lastIndexOf(Path, BiPredicate)

Idempotency:

This method is idempotent and deterministic.

Thread Safety:

This method is safe for concurrent use by multiple threads.

qualified

public final T qualified()

Calls the Path.Element.qualified() method on the last element in this Path and returns the result.

Specified by:

qualified in interface Qualified<String,Object,T>

Returns:

the result of invoking the Path.Element.qualified() method on the last element in this Path

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method may return null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

isRoot

public final boolean isRoot()

Returns true if this Path is a root path, which is true when it has only one element and that element is root.

Returns:

true if this Path is a root path; false otherwise

Idempotency:

This method is idempotent and deterministic.

Thread Safety:

This method is safe for concurrent use by multiple threads.

absolute

public final boolean absolute()

Returns true if and only if this Path is absolute, which means that its first Path.Element is a root Path.Element.

Returns:

true if and only if this Path is absolute

hashCode

public final int hashCode()

Returns a hashcode for this Path.

Overrides:

hashCode in class Object

Returns:

a hashcode for this Path

Idempotency:

This method is idempotent and deterministic.

Thread Safety:

This method is safe for concurrent use by multiple threads.

equals

public final boolean equals(Object other)

Returns true if and only if the supplied Object is equal to this Path.

Overrides:

equals in class Object

Parameters:

other - the Object to test; may be null in which case false will be returned

Returns:

true if and only if the supplied Object is equal to this Path

Idempotency:

This method is idempotent and deterministic.

Thread Safety:

This method is safe for concurrent use by multiple threads.

plus

public final <U> Path<U> plus(Path.Element<? extends U> element)

Returns a new Path consisting of this Path's qualifiers and elments plus the supplied element.

Type Parameters:

U - the type of the new Path

Parameters:

element - the new Path's last element; must not be null

Returns:

a new Path consisting of this Path's qualifiers and elments plus the supplied element

Throws:

NullPointerException - if element is null

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

plus

public final <U> Path<U> plus(Collection<? extends Path.Element<?>> elements,
 Path.Element<? extends U> lastElement)

Returns a new Path consisting of this Path's qualifiers, this Path's elements, the supplied elements, and the supplied lastElement.

Type Parameters:

U - the type of the new Path

Parameters:

elements - additional elements; must not be null

lastElement - the new Path's last element; must not be null

Returns:

a new Path consisting of this Path's qualifiers, this Path's elements, the supplied elements, and the supplied lastElement

Throws:

NullPointerException - if element is null

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

plus

public final <U> Path<U> plus(Path<? extends U> path)

Returns a new Path consisting of this Path's qualifiers combined with a prefixed version of the supplied Path's qualifiers, this Path's elements, the supplied Path's elements, and the supplied Path's last element.

The new Path's qualifiers are those of this Path plus those of the supplied Path, where each qualifier in the supplied Path's qualifiers has been prefixed with a String formed from the names of all the elements in this Path.

Type Parameters:

U - the type of the new Path

Parameters:

path - the Path to logically append; must not be null

Returns:

a new Path consisting of this Path's qualifiers combined with a prefixed version of the supplied Path's qualifiers, this Path's elements, the supplied Path's elements, and the supplied Path's last element

Throws:

NullPointerException - if path is null

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

toString

public final String toString()

Returns a non-null String representation of this Path.

The format of the returned String is deliberately undefined and may change between revisions of this class without notice.

Overrides:

toString in class Object

Returns:

a non-null String representation of this Path

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

root

public static final Path<?> root()

Returns a Path that is a root path.

Returns:

a Path that is a root path

See Also:

• isRoot()

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

of

public static final <T> Path<T> of(T qualified)

Returns a (usually new) Path formed from a Path.Element formed from the supplied qualified and an empty name.

Type Parameters:

T - the type of the Path

Parameters:

qualified - the qualified item of what will be the last Path.Element

Returns:

a Path

Throws:

NullPointerException - if qualified is null

See Also:

• of(Object, List)

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

of

public static final <T> Path<T> of(T qualified,
 String name)

Returns a (usually new) Path formed from a Path.Element formed from the supplied qualified and the supplied name.

Type Parameters:

T - the type of the Path

Parameters:

qualified - the qualified item of what will be the last Path.Element

name - the name of what will be the last Path.Element

Returns:

a Path

Throws:

NullPointerException - if name is null

IllegalArgumentException - if qualified is null and name is null or an empty String}

See Also:

• of(Object, List)

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

of

public static final <T> Path<T> of(T qualified,
 String... names)

Returns a (usually new) Path formed from Path.Elements formed from the supplied qualified and the supplied array of names.

Type Parameters:

T - the type of the Path

Parameters:

qualified - the qualified item of what will be the last Path.Element

names - an array of names from which Path.Elements will be synthesized; must not be null

Returns:

a Path

Throws:

NullPointerException - if names is null

IllegalArgumentException - if qualified is null and the last element of names is an empty String

See Also:

• of(Object, List)

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

of

public static final <T> Path<T> of(Path.Element<? extends T> lastElement)

Returns a (usually new) Path formed from the supplied lastElement.

Type Parameters:

T - the type of the Path

Parameters:

lastElement - the last Path.Element; must not be null

Returns:

a Path

Throws:

NullPointerException - if lastElement is null

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

of

public static final <T> Path<T> of(T qualified,
 List<? extends String> names)

Returns a (usually new) Path formed from Path.Elements formed from the supplied qualified and the supplied List of names.

Type Parameters:

T - the type of the Path

Parameters:

qualified - the qualified item of what will be the last Path.Element

names - a List of names from which Path.Elements will be synthesized; must not be null

Returns:

a Path

Throws:

NullPointerException - if names is null

IllegalArgumentException - if qualified is null and the last element of names is an empty String

See Also:

• Element(Qualifiers, Object, String)

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

of

public static final <T> Path<T> of(Qualifiers<? extends String,?> pathQualifiers,
 Path.Element<? extends T> lastElement)

Return a (usually new) Path formed from the supplied arguments and returns it.

Type Parameters:

T - the type of the Path

Parameters:

pathQualifiers - the Path's qualifiers; must not be null

lastElement - the last Element of the Path; must not be null

Returns:

a (usually new) Path

Throws:

NullPointerException - if any argument is null

See Also:

• Path(Qualifiers, List, Element)

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

of

public static final <T> Path<T> of(Qualifiers<? extends String,?> pathQualifiers,
 List<? extends Path.Element<?>> elements,
 Path.Element<? extends T> lastElement)

Return a (usually new) Path formed from the supplied arguments and returns it.

Type Parameters:

T - the type of the new Path

Parameters:

pathQualifiers - the Path's qualifiers; must not be null

elements - the interior Path.Elements of the Path; must not be null

lastElement - the last Element of the Path; must not be null

Returns:

a (usually new) Path

Throws:

NullPointerException - if any argument is null

See Also:

• Path(Qualifiers, List, Element)

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.