Package org.pkl.core.module

Interface ModuleKey

All Superinterfaces:

ReaderBase

public interface ModuleKey
extends ReaderBase

SPI for identifying, resolving, caching, and resolving a Pkl module. Standard implementations can be created using ModuleKeys.

Method Summary

Modifier and Type	Method	Description
default @Nullable java.nio.file.Path	getFileCacheLocation()	The relative file cache path for this module, or null if this module should not be cached on the file system.
java.net.URI	getUri()	Returns the absolute URI of this module.
default boolean	isCached()	Tells if this module should be cached in memory.
default boolean	isLocal()	Tells if the modules represented by this module key is local to the environment.
ResolvedModuleKey	resolve(SecurityManager securityManager)	Resolves this module to a canonical form suitable for loading and caching the module.
default java.net.URI	resolveUri(java.net.URI uri)

Methods inherited from interface org.pkl.core.runtime.ReaderBase

hasElement, hasFragmentPaths, hasHierarchicalUris, isGlobbable, listElements, resolveUri

Method Detail

getUri

java.net.URI getUri()

Returns the absolute URI of this module. This URI is used for identifying the module in user facing messages, for example stack traces. Typically, this URI contains all information necessary for resolving and loading the module.

resolve

ResolvedModuleKey resolve(SecurityManager securityManager)
                   throws java.io.IOException,
                          SecurityManagerException

Resolves this module to a canonical form suitable for loading and caching the module. This may involve I/O. Throws FileNotFoundException if this module cannot be found.

Throws:

java.io.IOException

SecurityManagerException

resolveUri

default java.net.URI resolveUri(java.net.URI uri)
                         throws java.io.IOException,
                                SecurityManagerException

Throws:

java.io.IOException

SecurityManagerException

isCached

default boolean isCached()

Tells if this module should be cached in memory.

Caching a module means caching its entire evaluation state, not just its resolved URI or source code.

Turning off module caching is mostly useful for synthetic modules that cannot be referenced (imported) from other modules. An example for this is a module representing code typed in a REPL.

isLocal

default boolean isLocal()

Tells if the modules represented by this module key is local to the environment.

A module that is local, and also ReaderBase.hasHierarchicalUris(), supports triple-dot imports.

As a best practice, a module key should be considered local if its source can be loaded in a low latency environment (for example, from disk or from memory). On the flip-side, a module loaded from a remove server should not be considered local.

getFileCacheLocation

default @Nullable java.nio.file.Path getFileCacheLocation()

The relative file cache path for this module, or null if this module should not be cached on the file system.