Module org.microbean.loader

Package org.microbean.loader.spi

Class AbstractTreeBasedProvider<N>

java.lang.Object

org.microbean.loader.spi.AbstractProvider

org.microbean.loader.spi.AbstractTreeBasedProvider<N>

Type Parameters:

N - the type of a node in the tree

All Implemented Interfaces:

Provider

Direct Known Subclasses:

JacksonProvider, TypesafeConfigHoconProvider

public abstract class AbstractTreeBasedProvider<N>
extends AbstractProvider

An abstract AbstractProvider whose implementations are built around tree structures of various kinds.

Author:

Laird Nelson

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AbstractTreeBasedProvider()	Creates a new AbstractTreeBasedProvider with no lower type bound.
protected	AbstractTreeBasedProvider(Type lowerTypeBound)	Creates a new AbstractTreeBasedProvider with the supplied lower type bound.

Method Summary

Modifier and Type	Method	Description
protected abstract boolean	absent(N node)	Returns true if the supplied node is null, absent or synthetic.
protected final boolean	container(N node)	Returns true if node is either a map or a list or array.
protected Supplier<?>	find(Loader<?> requestor, Path<? extends Type> absolutePath)	Returns a deterministic Supplier suitable for the current request, represented by the supplied absolutePath, as being executed by the supplied Loader, or null if no such Supplier is or ever will be suitable.
protected abstract N	get(N node, int index)	Returns the child node of the supplied parent node identified by the supplied index, or null if either the child does not exist or node is not a list node.
protected abstract N	get(N node, String name)	Returns the child node of the supplied parent node identified by the supplied name, or null if either the child does not exist or node is not a map node.
protected abstract boolean	list(N node)	Returns true if the supplied node represents a list or an array, and therefore the get(Object, int) method is likely to be relevant.
protected abstract boolean	map(N node)	Returns true if the supplied node represents a map, and therefore the get(Object, String) method is likely to be relevant.
protected abstract Iterator<String>	names(N node)	Returns an Iterator over the names of the supplied node's child nodes, or an empty Iterator if the supplied node is not a map node.
protected abstract boolean	nil(N node)	Returns true if the supplied node is null or represents an explicitly set null value.
protected final <T extends Type> Path<T>	path(Loader<?> requestor, Path<T> absolutePath)	Calls the path(Loader, Path, BiFunction) method with the supplied arguments and the return value of an invocation of the reader(Loader, Path) method and returns its result.
protected <T extends Type> Path<T>	path(Loader<?> requestor, Path<T> absolutePath, BiFunction<? super N,? super Type,?> reader)	Returns a Path for a new Value that will be returned by the AbstractProvider.get(Loader, Path) method.
protected Qualifiers<? extends String,?>	qualifiers(BiFunction<? super N,? super Type,?> reader, N qualifiersNode, String nextPathElementName)	Returns a Qualifiers derived from the supplied qualifiersNode.
protected abstract N	qualifiers(N node)	Returns a node possibly containing qualifiers applicable to the supplied node, or null.
protected abstract BiFunction<? super N,? super Type,?>	reader(Loader<?> requestor, Path<? extends Type> absolutePath)	Returns a BiFunction accepting a node and a Type and returning the result of reading an object of that type, or null if no such BiFunction could be sourced.
protected abstract N	rootNode(Loader<?> requestor, Path<? extends Type> absolutePath)	Returns the root node of the tree that is suitable for the supplied Loader and Path, or null if no tree is suitable.
protected abstract int	size(N node)	Returns the number of child nodes the supplied node has, which may be (and often is) 0.

Methods inherited from class org.microbean.loader.spi.AbstractProvider

get, lowerBound

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

AbstractTreeBasedProvider

protected AbstractTreeBasedProvider()

Creates a new AbstractTreeBasedProvider with no lower type bound.

AbstractTreeBasedProvider

protected AbstractTreeBasedProvider(Type lowerTypeBound)

Creates a new AbstractTreeBasedProvider with the supplied lower type bound.

Parameters:

lowerTypeBound - the lower type bound; may be null

Method Details

size

protected abstract int size(N node)

Returns the number of child nodes the supplied node has, which may be (and often is) 0.

If the supplied null is null, absent or a scalar, an override of this method must return 0.

Parameters:

node - the parent node; may be null in which case 0 must be returned

Returns:

the number of child nodes the supplied node has, which may be (and often is) 0

Idempotency:

Overrides of this method must be idempotent and deterministic.

Nullability:

Overrides of this method may return null.

Thread Safety:

Overrides of this method must be safe for concurrent use by multiple threads.

names

protected abstract Iterator<String> names(N node)

Returns an Iterator over the names of the supplied node's child nodes, or an empty Iterator if the supplied node is not a map node.

Parameters:

node - the parent node; may be null in which case an empty Iterator must be returned

Returns:

an Iterator; never null

Idempotency:

Overrides of this method must be idempotent and deterministic.

Nullability:

Overrides of this method must not return null.

Thread Safety:

Overrides of this method must be safe for concurrent use by multiple threads.

get

protected abstract N get(N node,
 String name)

Returns the child node of the supplied parent node identified by the supplied name, or null if either the child does not exist or node is not a map node.

Parameters:

node - the parent node; may be null in which case null must be returned

name - the name of the child; must not be null

Returns:

the child node of the supplied parent node identified by the supplied name, or null if either the child does not exist or node is not a map node

Throws:

NullPointerException - if name is null

Idempotency:

Overrides of this method must be idempotent and deterministic.

Nullability:

Overrides of this method may (and often do) return null.

Thread Safety:

Overrides of this method must be safe for concurrent use by multiple threads.

get

protected abstract N get(N node,
 int index)

Returns the child node of the supplied parent node identified by the supplied index, or null if either the child does not exist or node is not a list node.

Parameters:

node - the parent node; may be null in which case null must be returned

index - the zero-based index of the child

Returns:

the child node of the supplied parent node identified by the supplied name, or null if either the child does not exist or node is not a map node

Throws:

NullPointerException - if name is null

IndexOutOfBoundsException - if index is invalid

Idempotency:

Overrides of this method must be idempotent and deterministic.

Nullability:

Overrides of this method may (and often do) return null.

Thread Safety:

Overrides of this method must be safe for concurrent use by multiple threads.

absent

protected abstract boolean absent(N node)

Returns true if the supplied node is null, absent or synthetic.

Parameters:

node - the node to test; may be null in which case true must be returned

Returns:

true if the supplied node is null, absent or synthetic

Idempotency:

Overrides of this method must be idempotent and deterministic.

Thread Safety:

Overrides of this method must be safe for concurrent use by multiple threads.

nil

protected abstract boolean nil(N node)

Returns true if the supplied node is null or represents an explicitly set null value.

Parameters:

node - the node to test; may be null in which case true must be returned

Returns:

true if the supplied node is null or represents an explicitly set null value

Idempotency:

Overrides of this method must be idempotent and deterministic.

Thread Safety:

Overrides of this method must be safe for concurrent use by multiple threads.

map

protected abstract boolean map(N node)

Returns true if the supplied node represents a map, and therefore the get(Object, String) method is likely to be relevant.

Parameters:

node - the node to test; may be null in which case false must be returned

Returns:

true if the supplied node represents a map, and therefore the get(Object, String) method is likely to be relevant

Idempotency:

Overrides of this method must be idempotent and deterministic.

Thread Safety:

Overrides of this method must be safe for concurrent use by multiple threads.

list

protected abstract boolean list(N node)

Returns true if the supplied node represents a list or an array, and therefore the get(Object, int) method is likely to be relevant.

Parameters:

node - the node to test; may be null in which case false must be returned

Returns:

true if the supplied node represents a list or an array, and therefore the get(Object, int) method is likely to be relevant

Idempotency:

Overrides of this method must be idempotent and deterministic.

Thread Safety:

Overrides of this method must be safe for concurrent use by multiple threads.

container

protected final boolean container(N node)

Returns true if node is either a map or a list or array.

Parameters:

node - the node to test; may be null in which case false must be returned

Returns:

true if node is either a map or a list or array

Idempotency:

Overrides of this method must be idempotent and deterministic.

Thread Safety:

Overrides of this method must be safe for concurrent use by multiple threads.

reader

protected abstract BiFunction<? super N,? super Type,?> reader(Loader<?> requestor,
 Path<? extends Type> absolutePath)

Returns a BiFunction accepting a node and a Type and returning the result of reading an object of that type, or null if no such BiFunction could be sourced.

Parameters:

requestor - the Loader currently executing a request; must not be null

absolutePath - the path being requested; must not be null and must be absolute

Returns:

a BiFunction accepting a node and a Type and returning the result of reading an object of that type, or null if no such BiFunction could be sourced

Throws:

NullPointerException - if any argument is null

Idempotency:

Overrides of this method must be idempotent and deterministic.

Nullability:

Overrides of this method may return null.

Thread Safety:

Overrides of this method must be safe for concurrent use by multiple threads.

rootNode

protected abstract N rootNode(Loader<?> requestor,
 Path<? extends Type> absolutePath)

Returns the root node of the tree that is suitable for the supplied Loader and Path, or null if no tree is suitable.

Parameters:

requestor - the Loader currently executing a request; must not be null

absolutePath - the path being requested; must not be null and must be absolute

Returns:

the root node, or null

Throws:

NullPointerException - if any argument is null

Idempotency:

Overrides of this method must be idempotent and deterministic.

Nullability:

Overrides of this method may return null.

Thread Safety:

Overrides of this method must be safe for concurrent use by multiple threads.

qualifiers

protected abstract N qualifiers(N node)

Returns a node possibly containing qualifiers applicable to the supplied node, or null.

Parameters:

node - the node for which a corresponding qualifiers node should be returned; may be null in which case null must be returned

Returns:

a node possibly containing qualifiers applicable to the supplied node, or null

Idempotency:

Overrides of this method must be idempotent and deterministic.

Nullability:

Overrides of this method may (and often do) return null

Thread Safety:

Overrides of this method must be safe for concurrent use by multiple threads.

find

protected Supplier<?> find(Loader<?> requestor,
 Path<? extends Type> absolutePath)

Returns a deterministic Supplier suitable for the current request, represented by the supplied absolutePath, as being executed by the supplied Loader, or null if no such Supplier is or ever will be suitable.

Specified by:

find in class AbstractProvider

Parameters:

requestor - the Loader currently executing a request; must not be null

absolutePath - the path being requested; must not be null and must be absolute

Returns:

a Supplier, or null

Throws:

NullPointerException - if any argument is null

See Also:

• Provider.get(Loader, Path)

Idempotency:

No guarantees are made of either idempotency or determinism, either of this implementation or of its overrides.

Thread Safety:

This method is, and its overrides must be, safe for concurrent use by multiple threads.

path

protected final <T extends Type> Path<T> path(Loader<?> requestor,
 Path<T> absolutePath)

Calls the path(Loader, Path, BiFunction) method with the supplied arguments and the return value of an invocation of the reader(Loader, Path) method and returns its result.

Overrides:

path in class AbstractProvider

Type Parameters:

T - the type of both the supplied and returned Paths

Parameters:

requestor - the Loader currently executing a request; must not be null

absolutePath - the path being requested; must not be null and must be absolute

Returns:

a Path that will be used to build a Value to be returned by the AbstractProvider.get(Loader, Path) method; if null, then the AbstractProvider.get(Loader, Path) method will return null as well

Throws:

NullPointerException - if absolutePath or reader is null

See Also:

• path(Loader, Path, BiFunction)
• reader(Loader, Path)

Idempotency:

No guarantees about idempotency or determinism are made of this method.

Nullability:

This method does not return null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

path

protected <T extends Type> Path<T> path(Loader<?> requestor,
 Path<T> absolutePath,
 BiFunction<? super N,? super Type,?> reader)

Returns a Path for a new Value that will be returned by the AbstractProvider.get(Loader, Path) method.

The default implementation of this method attempts to build a Path with the same sizze as the supplied Path and differing, perhaps, only in the Qualifiers assigned to each Path.Element.

Overrides of this method must not call the path(Loader, Path) or the AbstractProvider.get(Loader, Path) methods or undefined behavior, such as an infinite loop, may result.

Type Parameters:

T - the type of the supplied Path and the returned Path

Parameters:

requestor - the Loader currently executing a request; must not be null

absolutePath - the path being requested; must not be null and must be absolute

reader - a BiFunction accepting a node and a Type and returning the result of reading an object of that type; may be null

Returns:

a Path; never null; sometimes simply the supplied absolutePath

Throws:

NullPointerException - if absolutePath or reader is null

Idempotency:

No guarantees about idempotency or determinism are made of this method or its overrides.

Nullability:

This method does not, and its overrides must not, return null.

Thread Safety:

This method is, and its overrides must be, safe for concurrent use by multiple threads.

qualifiers

protected Qualifiers<? extends String,?> qualifiers(BiFunction<? super N,? super Type,?> reader,
 N qualifiersNode,
 String nextPathElementName)

Returns a Qualifiers derived from the supplied qualifiersNode.

Parameters:

reader - a BiFunction accepting a node and a Type and returning the result of reading an object of that type; may be null

qualifiersNode - a node containing qualifier entries; may be null

nextPathElementName - the name of the next path element; may be null

Returns:

a Qualifiers; never null

Idempotency:

This method is, and its overrides must be, idempotent and deterministic.

Nullability:

This method does not, and its overrides must not, return null.

Thread Safety:

This method is, and its overrides must be, safe for concurrent use by multiple threads.