Module org.microbean.path

Package org.microbean.path

Class Path.Element<T>

java.lang.Object

org.microbean.path.Path.Element<T>

Type Parameters:

T - the type of this Path.Element

All Implemented Interfaces:

Constable, Qualified<String,Object,T>

Enclosing class:

Path<T>

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

An element normally within a Path, consisting of a Qualifiers, a name, and an optional thing that it designates or points to.

Author:

Laird Nelson

Nested Class Summary

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
Element(String name)	Creates a new Path.Element.
Element(Qualifiers<? extends String,?> qualifiers, String name)	Creates a new Path.Element.
Element(Qualifiers<? extends String,?> qualifiers, T qualified, String name)	Creates a new Path.Element.
Element(T qualified, String name)	Creates a new Path.Element.

Method Summary

Modifier and Type	Method	Description
final Optional<? extends ConstantDesc>	describeConstable()	Returns an Optional containing a ConstantDesc representing this Path.Element.
final boolean	equals(Object other)	Returns true if the supplied Object is equal to this Path.Element.
final int	hashCode()	Returns a hashcode for this Path.Element.
final boolean	isRoot()	Returns true if this Path.Element is a root element, which is true when the qualified() method returns null and the name() method returns an empty String.
final String	name()	Returns the name of this Path.Element.
static final <T> Path.Element<T>	of(String name)	Returns a Path.Element representing the supplied arguments.
static final <T> Path.Element<T>	of(Qualifiers<? extends String,?> qualifiers, T qualified, String name)	Returns a Path.Element representing the supplied arguments.
static final <T> Path.Element<T>	of(T qualified, String name)	Returns a Path.Element representing the supplied arguments.
final T	qualified()	Returns the thing that this Path.Element describes (which may be nothing).
final Qualifiers<String,Object>	qualifiers()	Returns the Qualifiers that qualifies this Path.Element.
static final Path.Element<?>	root()	Returns a Path.Element that is a root element.
final String	toString()	Returns a non-null String representation of this Path.Element.
final Path.Element<T>	withQualifiersPrefix(String prefix)	Returns a Path.Element, usually newly created, whose qualifiers have keys that are prefixed with the supplied prefix.

Methods inherited from class java.lang.Object

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

Constructor Details

Element

public Element(String name)

Creates a new Path.Element.

Parameters:

name - the name of this Path.Element; must not be null or empty

Throws:

NullPointerException - if name is null

IllegalArgumentException - if name is empty

See Also:

• Element(Qualifiers, Object, String)

Element

public Element(T qualified,
 String name)

Creates a new Path.Element.

Parameters:

qualified - the thing this Path.Element describes; may be null

name - the name of this Path.Element; may be null only if qualified is not null

Throws:

NullPointerException - if qualified is null and name is null

IllegalArgumentException - if qualified is null and name is empty

See Also:

• Element(Qualifiers, Object, String)

Element

public Element(Qualifiers<? extends String,?> qualifiers,
 String name)

Creates a new Path.Element.

Parameters:

qualifiers - the qualifiers qualifying this Path.Element; may be null in which case an empty Qualifiers will be used instead

name - the name of this Path.Element; may be null only if qualified is not null

Throws:

NullPointerException - if name is null

IllegalArgumentException - if name is empty

See Also:

• Element(Qualifiers, Object, String)

Element

public Element(Qualifiers<? extends String,?> qualifiers,
 T qualified,
 String name)

Creates a new Path.Element.

Parameters:

qualifiers - the qualifiers qualifying this Path.Element; may be null in which case an empty Qualifiers will be used instead

qualified - the thing this Path.Element describes; may be null

name - the name of this Path.Element; may be null only if qualified is not null

Throws:

NullPointerException - if qualified is null and name is null

IllegalArgumentException - if qualified is null and name is empty

Method Details

describeConstable

public final Optional<? extends ConstantDesc> describeConstable()

Returns an Optional containing a ConstantDesc representing this Path.Element.

Specified by:

describeConstable in interface Constable

Specified by:

describeConstable in interface Qualified<String,Object,T>

Returns:

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

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.Element.

Specified by:

qualifiers in interface Qualified<String,Object,T>

Returns:

the Qualifiers that qualifies this Path.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.

qualified

public final T qualified()

Returns the thing that this Path.Element describes (which may be nothing).

Specified by:

qualified in interface Qualified<String,Object,T>

Returns:

the thing that this Path.Element describes, which may be nothing, in which case null will be returned

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.

name

public final String name()

Returns the name of this Path.Element.

Returns:

the name of this Path.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.

isRoot

public final boolean isRoot()

Returns true if this Path.Element is a root element, which is true when the qualified() method returns null and the name() method returns an empty String.

Returns:

true if and only if this Path.Element is a root element

Idempotency:

This method is idempotent and deterministic.

Thread Safety:

This method is safe for concurrent use by multiple threads.

withQualifiersPrefix

public final Path.Element<T> withQualifiersPrefix(String prefix)

Returns a Path.Element, usually newly created, whose qualifiers have keys that are prefixed with the supplied prefix.

Parameters:

prefix - the prefix to apply; may be null or empty in which case this will be returned

Returns:

a Path.Element, usually newly created, whose qualifiers have keys that are prefixed with the supplied prefix

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.

hashCode

public final int hashCode()

Returns a hashcode for this Path.Element.

Overrides:

hashCode in class Object

Returns:

a hashcode for this Path.Element

Idempotency:

This method is idempotent.

Thread Safety:

This method is safe for concurrent use by multiple threads.

equals

public final boolean equals(Object other)

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

Overrides:

equals in class Object

Parameters:

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

Returns:

true if the supplied Object is equal to this Path.Element; false otherwise

Idempotency:

This method is idempotent and deterministic.

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.Element.

The format of the String that is returned is deliberately unspecified and subject to change without notice from version to version of this class.

Overrides:

toString in class Object

Returns:

a String representation of this Path.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.

root

public static final Path.Element<?> root()

Returns a Path.Element that is a root element.

Returns:

a Path.Element that is a root 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.Element<T> of(Qualifiers<? extends String,?> qualifiers,
 T qualified,
 String name)

Returns a Path.Element representing the supplied arguments.

The returned Path.Element may be newly created or it may be cached. No assumption must be made about its identity.

Type Parameters:

T - the type of this Path.Element

Parameters:

qualifiers - the Qualifiers qualifying this Path.Element; may be null in which case an empty Qualifiers will be used instead

qualified - the thing this Path.Element describes; may be null

name - the name of this Path.Element; may be null only if qualified is not null

Returns:

a Path.Element representing the supplied arguments

Throws:

NullPointerException - if qualified is null and name is null

IllegalArgumentException - if qualified is null and name is empty

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.Element<T> of(T qualified,
 String name)

Returns a Path.Element representing the supplied arguments.

The returned Path.Element may be newly created or it may be cached. No assumption must be made about its identity.

Type Parameters:

T - the type of this Path.Element

Parameters:

qualified - the thing this Path.Element describes; may be null

name - the name of this Path.Element; may be null only if qualified is not null

Returns:

a Path.Element representing the supplied arguments

Throws:

NullPointerException - if qualified is null and name is null

IllegalArgumentException - if qualified is null and name is empty

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.Element<T> of(String name)

Returns a Path.Element representing the supplied arguments.

The returned Path.Element may be newly created or it may be cached. No assumption must be made about its identity.

Type Parameters:

T - the type of this Path.Element

Parameters:

name - the name of this Path.Element; may be null only if qualified is not null

Returns:

a Path.Element representing the supplied arguments

Throws:

NullPointerException - if qualified is null and name is null

IllegalArgumentException - if qualified is null and name is empty

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.