Package dev.getelements.elements.sdk

Interface ElementPathLoader

All Known Implementing Classes:

DirectoryElementPathLoader

public interface ElementPathLoader

Used to load Element instances from local paths on disk. As a single Element may span multiple sources for executable code, this provides loading semantics for code on disk in a structured manner. When loading Elements, the loader will search a Path with the following rules.

• If the Path can load using FileSystems.newFileSystem(Path), it will load
• If thd Path is a directory, it will assume all files in the directory make up the Element
• If thd Path is a not found or otherwise empty, it will return an empty Stream
• For each directory in the Path, it will create a new subordinate ElementRegistry
• Each loaded Element will follow the hierarchy of the directory.
• Empty directories, or directories containing directories will be skipped.
• Aside from those specified (lib and classpath), directory names are irrelevant. All Element metadata will come from the annotations.

When searching each directory, the ElementPathLoader will look for the following files/directories to determine the makings of the Element.

• dev.getelements.element.attributes.properties - custom attributes for the Element
• api - every file is assumed to be a jar file, shared among all Elements in a directory
• lib - every file is assumed to be a jar file, specific to that Element only
• classpath - every file inside this directory is added to the classpath

For example, let's say we have the following directories with the following Elements define inside each of them:

• foo - com.example.foo
• foo/a - com.example.foo.a
• foo/b - com.example.foo.b
• bar - com.example.bar
• bar/a - com.example.bar.a
• bar/b - com.example.bar.b

This will result in six ElementRegistry instances and Element instances chained as follows:

• Root
• Root -> Foo
• Root -> Foo -> A
• Root -> Foo -> B
• Root
• Root -> Bar
• Root -> Bar -> A
• Root -> Bar -> B

Changes for 3.6 and up. The "api" directory is now supported. Any jars in this directory are shared among all Elements in the same directory and any subdirectories. This enables each Element to share common API jars without exposing its own implementation jars to its peers. API jars should be as lean as absolutely possible, containing only the interfaces and data types needed to interact with the Element's services. When scanning a directory structure, the loader will first look for an "api" directory and load any jars found there into the classpath before loading.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	API_DIR	The API directory.
static final String	ATTRIBUTES_PROPERTIES_FILE	The name of the file which represents a particular Element's Attributes.
static final String	CLASSPATH_DIR	The Classpath directory name.
static final String	ELEMENT_PATH_ENV	The environment variable for the element path.
static final String	JAR_EXTENSION	The jar file extension.
static final String	LIB_DIR	The library directory name.

Method Summary

Modifier and Type	Method	Description
default Stream<Element>	load(MutableElementRegistry registry)	Loads all Element into the supplied registry, using the globally configured ELEMENTPATH as the source location.
default Stream<Element>	load(MutableElementRegistry registry, Path path)	Loads all Elements from the supplied Path into the supplied ElementRegistry.
Stream<Element>	load(MutableElementRegistry registry, Path path, ClassLoader baseClassLoader)	Loads all Elements from the supplied Path into the supplied ElementRegistry.
static ElementPathLoader	newDefaultInstance()	Creates a new instance of the ElementPathLoader using the system default SPI.

Field Details

JAR_EXTENSION

static final String JAR_EXTENSION

The jar file extension.

See Also:

• Constant Field Values

ELEMENT_PATH_ENV

static final String ELEMENT_PATH_ENV

The environment variable for the element path.

See Also:

• Constant Field Values

API_DIR

static final String API_DIR

The API directory.

Since:

3.6

See Also:

• Constant Field Values

LIB_DIR

static final String LIB_DIR

The library directory name.

See Also:

• Constant Field Values

CLASSPATH_DIR

static final String CLASSPATH_DIR

The Classpath directory name.

See Also:

• Constant Field Values

ATTRIBUTES_PROPERTIES_FILE

static final String ATTRIBUTES_PROPERTIES_FILE

The name of the file which represents a particular Element's Attributes. Uses the Properties format when defining the Attributes. This allows for the separation of code and configuration at deployment time.

See Also:

• Constant Field Values

Method Details

load

default Stream<Element> load(MutableElementRegistry registry)

Loads all Element into the supplied registry, using the globally configured ELEMENTPATH as the source location.

Parameters:

registry - the registry to receive the loaded Elements

load

default Stream<Element> load(MutableElementRegistry registry,
 Path path)

Loads all Elements from the supplied Path into the supplied ElementRegistry.

Parameters:

registry - the registry to use for loading the Element instances

path - the Path

Returns:

a Stream of Element instances

load

Stream<Element> load(MutableElementRegistry registry,
 Path path,
 ClassLoader baseClassLoader)

Loads all Elements from the supplied Path into the supplied ElementRegistry.

Parameters:

registry - the registry to use for loading the Element instances

path - the Path

baseClassLoader - the base ClassLoader used to load the Element

Returns:

a Stream of Element instances

newDefaultInstance

static ElementPathLoader newDefaultInstance()

Creates a new instance of the ElementPathLoader using the system default SPI.

Returns:

new ElementPathLoader