XStream

Plugins and module boundaries

Built-in implementations and contributed plugins use the same extension contracts. Core owns discovery, lifecycle and resource management; plugins own domain behavior and parameter validation.

Extension Implementation and guide
DataCatalog / Dataset / Item / DataView xstream-data
InlineOperatorProvider Job-local operators
OperatorExecutor xstream-plugin-operator-executors
SourceAnalyzer / SourceArchive / SourceBuildRecipe xstream-plugin-source-analysis
ChatPlanner xstream-designer
CheckpointStoreProvider / CheckpointStore Execution policies and checkpoints

Implement public no-argument classes and list them in META-INF/services/<fully-qualified-interface>. Add the plugin JAR and dependencies to the host classpath and restart; do not edit a central registry. Executor contracts are defined in xstream-execution-api as xstream.execution.OperatorExecutor; bundled implementations use xstream.operator.executors. Source-review contracts use xstream.operator. Registration filenames must match the actual interface names.

Scientific views preserve arrays and sequences rather than silently flattening them into records. Keep format dependencies in their data plugins. Operator code runs in isolated environments; host-installed plugins themselves are trusted code. Include configuration examples, registration instructions and contract tests for contributions; module guides list current validation commands.

The items View support is registered as xstream.data.ItemsViewSupport in META-INF/services/xstream.data.DataViewSupport. A contributed dataset provider may advertise views: [items] and implement DatasetAccess.view(path, ItemReferences.View) using the shared Arrow schema. ItemReferences.foreach consumes references incrementally. Members retain their View capabilities; their content is opened separately. See Item reference streams and ItemsSpec for contract tests.

Local development

The standalone engine supports source-directory references, reusable builds and direct source submission; see local operator libraries. LocalOperatorBuilder is an implemented build extension point with built-in python and command providers registered through ServiceLoader.

Dependency environment plugins

DependencyEnvironmentProvider is discovered through ServiceLoader. Built-in python, jvm and native implementations live in plugins/xstream-plugin-dependencies. See the dependency environment guide for registration, configuration and contract tests. The local builder also provides a jvm implementation.

Remote data plugins

RemoteItemProvider is a ServiceLoader extension point in xstream-execution-api for remote data access. See local execution and remote data for registration, configuration, resource contracts and tests.

Geospatial and HDF5 extensions

Optional plugins: GDAL raster and vector formats and HDF5 hierarchies and arrays. Both use the same format extension contracts and document installation, configuration, capability limits and native contract tests. Native dependencies belong to plugins rather than core.