Module org.microbean.loader

Package org.microbean.loader

Class SystemPropertyProvider

java.lang.Object

org.microbean.loader.spi.AbstractProvider

org.microbean.loader.SystemPropertyProvider

All Implemented Interfaces:

Provider

public class SystemPropertyProvider
extends AbstractProvider

An AbstractProvider that can return Values backed by System properties.

While System properties are often casually assumed to be stable and String-typed, the exact opposite is true: System properties may contain arbitrarily-typed Objects under arbitrarily-typed keys, and the properties themselves may be replaced at any point. This means that all Values supplied by this SystemPropertyProvider are non-deterministic and may change type and presence from one call to another.

It is also worth mentioning explicitly that, deliberately, no type conversion of any System property value takes place in this class.

Author:

Laird Nelson

See Also:

• System.getProperty(String, String)
• System.getProperties()
• System.setProperties(Properties)
• Properties.getProperty(String, String)
• Value.determinism()

Constructor Summary

Constructors

Constructor	Description
SystemPropertyProvider()	Creates a new SystemPropertyProvider that uses flat keys, does not presume that the only things stored in the System properties are Strings, and honors the fact that System properties are mutable.
SystemPropertyProvider(boolean flatKeys, boolean onlyStrings, boolean mutable)	Creates a new SystemPropertyProvider.

Method Summary

Modifier and Type	Method	Description
protected Supplier<?>	find(Loader<?> requestor, Path<? extends Type> absolutePath)	Returns a Supplier suitable for the System property represented by the supplied Path.
protected static final String	key(Path<?> path, boolean flat)	Returns a String representation of the supplied Path.
protected <T extends Type> Path<T>	path(Loader<?> requestor, Path<T> absolutePath)	Overrides the AbstractProvider.path(Loader, Path) method to return a (relative) Path consisting solely of the last element of the supplied absolutePath.

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

SystemPropertyProvider

public SystemPropertyProvider()

Creates a new SystemPropertyProvider that uses flat keys, does not presume that the only things stored in the System properties are Strings, and honors the fact that System properties are mutable.

See Also:

• SystemPropertyProvider(boolean, boolean, boolean)

SystemPropertyProvider

public SystemPropertyProvider(boolean flatKeys,
 boolean onlyStrings,
 boolean mutable)

Creates a new SystemPropertyProvider.

Parameters:

flatKeys - whether the key for a system property is derived from a Path's last element's name only

onlyStrings - whether all System properties are expected to be String-typed

mutable - whether System properties should be treated as mutable (which they are, strictly speaking, but for many applications this may not matter in practice)

Method Details

find

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

Returns a Supplier suitable for the System property represented by the supplied Path.

This method never returns null. Its overrides may if they wish.

The name of the last element of the supplied Path is taken to be the name of the System property value to retrieve. If the type erasure of the supplied Path's qualified() method is assignable from String.class, then calls will be made by the returned Value's get() method to System.getProperty(String) before simple calls to System.getProperties().get(String).

Any Supplier returned by this method will be non-deterministic, since system properties may change at any point. Additionally, if the supplied Path's type is not assignable from that borne by a System property value, then the Supplier will return null from its get() method in such a case, indicating that the value is present but cannot be represented. Overrides are strongly encouraged to abide by these conditions.

Specified by:

find in class AbstractProvider

Parameters:

requestor - the Loader seeking a Value; must not be null

absolutePath - an absolute Path for which a Value is being sought; must not be null

Returns:

a Supplier suitable for the System property whose name is represented by the supplied Path's last Element's name

Throws:

NullPointerException - if an argument for either parameter is null

See Also:

• AbstractProvider.get(Loader, Path)

Idempotency:

This method is idempotent and deterministic. Overrides must be idempotent, but need not be deterministic. Suppliers returned by this method or its overrides are not guaranteed to be idempotent or deterministic.

Nullability:

This method never returns null but its overrides may.

Thread Safety:

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

path

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

Overrides the AbstractProvider.path(Loader, Path) method to return a (relative) Path consisting solely of the last element of the supplied absolutePath.

Overrides:

path in class AbstractProvider

Type Parameters:

T - the type of both the supplied and returned Paths

Parameters:

requestor - the Loader seeking a Value; must not be null

absolutePath - an absolute Path for which a Value is being sought; must not be null

Returns:

a Path that will be used to build a Value to be returned by the AbstractProvider.get(Loader, Path) method

See Also:

• AbstractProvider.path(Loader, Path)

Idempotency:

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

Nullability:

This method does not, but overrides may, return null.

Thread Safety:

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

key

protected static final String key(Path<?> path,
 boolean flat)

Returns a String representation of the supplied Path.

Parameters:

path - the Path in question; must not be null

flat - whether the key is derived from the supplied Path's last element's name only

Returns:

a String representation of the supplied Path

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.