software.amazon.smithy.build

Class SmithyBuild

java.lang.Object

software.amazon.smithy.build.SmithyBuild

public final class SmithyBuild
extends java.lang.Object

Runs the projections and plugins found in a SmithyBuildConfig and writes the artifacts to a FileManifest.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	VERSION The version of Smithy build.

Constructor Summary

Constructors

Constructor and Description
SmithyBuild()
SmithyBuild(SmithyBuildConfig config)

Method Summary

Modifier and Type	Method and Description
SmithyBuildResult	build() Builds the model and applies all projections.
void	build(java.util.function.Consumer<ProjectionResult> resultCallback, java.util.function.BiConsumer<java.lang.String,java.lang.Throwable> exceptionCallback) Builds the model and applies all projections, passing each ProjectionResult to the provided callback as they are completed and each encountered exception to the provided exceptionCallback as they are encountered.
SmithyBuild	config(java.nio.file.Path configPath) Sets the required configuration object used to build the model.
SmithyBuild	config(SmithyBuildConfig config) Sets the required configuration object used to build the model.
static SmithyBuild	create(java.lang.ClassLoader classLoader) Creates a SmithyBuild implementation that is configured to discover various Smithy service providers using the given ClassLoader.
static SmithyBuild	create(java.lang.ClassLoader classLoader, java.util.function.Supplier<ModelAssembler> modelAssemblerSupplier) Creates a SmithyBuild implementation that is configured to discover various Smithy service providers using the given ClassLoader.
SmithyBuild	fileManifestFactory(java.util.function.Function<java.nio.file.Path,FileManifest> fileManifestFactory) Sets a factory function that's used to create FileManifest objects when writing SmithyBuildPlugin artifacts.
SmithyBuild	importBasePath(java.nio.file.Path importBasePath) Deprecated.
SmithyBuild	model(Model model) Sets an optional model to use with the build.
SmithyBuild	modelAssemblerSupplier(java.util.function.Supplier<ModelAssembler> modelAssemblerSupplier) Called to create ModelAssembler to load the original model and to load each projected model.
SmithyBuild	modelTransformer(ModelTransformer modelTransformer) Sets a custom ModelTransformer to use when building projections.
SmithyBuild	outputDirectory(java.nio.file.Path outputDirectory) Set a directory where the build artifacts are written.
SmithyBuild	outputDirectory(java.lang.String outputDirectory) Set a directory where the build artifacts are written.
SmithyBuild	pluginClassLoader(java.lang.ClassLoader pluginClassLoader) Sets a ClassLoader that should be used by SmithyBuild plugins when discovering services.
SmithyBuild	pluginFactory(java.util.function.Function<java.lang.String,java.util.Optional<SmithyBuildPlugin>> pluginFactory) Sets a factory function used to create plugins by name.
SmithyBuild	pluginFilter(java.util.function.Predicate<java.lang.String> pluginFilter) Sets a predicate that accepts the name of a plugin and returns true if the plugin should be built.
SmithyBuild	projectionFilter(java.util.function.Predicate<java.lang.String> projectionFilter) Sets a predicate that accepts the name of a projection and returns true if the projection should be built.
SmithyBuild	registerSources(java.nio.file.Path... pathToSources) Registers the given paths as sources of the model being built.
SmithyBuild	transformFactory(java.util.function.Function<java.lang.String,java.util.Optional<ProjectionTransformer>> transformFactory) Sets a factory function used to create transforms by name.

Methods inherited from class java.lang.Object

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

Field Detail

VERSION

public static final java.lang.String VERSION

The version of Smithy build.

See Also:

Constant Field Values

Constructor Detail

SmithyBuild

public SmithyBuild()

SmithyBuild

public SmithyBuild(SmithyBuildConfig config)

Method Detail

create

public static SmithyBuild create(java.lang.ClassLoader classLoader)

Creates a SmithyBuild implementation that is configured to discover various Smithy service providers using the given ClassLoader.

Parameters:

classLoader - ClassLoader used to discover service providers.

Returns:

Returns the created SmithyBuild object.

create

public static SmithyBuild create(java.lang.ClassLoader classLoader,
                                 java.util.function.Supplier<ModelAssembler> modelAssemblerSupplier)

Creates a SmithyBuild implementation that is configured to discover various Smithy service providers using the given ClassLoader.

Parameters:

classLoader - ClassLoader used to discover service providers.

modelAssemblerSupplier - Supplier used to create ModelAssemblers in each build.

Returns:

Returns the created SmithyBuild object.

build

public SmithyBuildResult build()

Builds the model and applies all projections.

This method loads all projections, projected models, and their results into memory so that a SmithyBuildResult can be returned. See build(Consumer, BiConsumer) for a streaming approach that uses callbacks and does not load all projections into memory at once.

Errors are aggregated together into a single SmithyBuildException that contains an aggregated error message and each encountered exception is registered to the aggregate exception through Throwable.addSuppressed(Throwable).

Returns:

Returns the result of building the model.

Throws:

java.lang.IllegalStateException - if a SmithyBuildConfig is not set.

SmithyBuildException - if the build fails.

See Also:

build(Consumer, BiConsumer)

build

public void build(java.util.function.Consumer<ProjectionResult> resultCallback,
                  java.util.function.BiConsumer<java.lang.String,java.lang.Throwable> exceptionCallback)

Builds the model and applies all projections, passing each ProjectionResult to the provided callback as they are completed and each encountered exception to the provided exceptionCallback as they are encountered.

This method differs from build() in that it does not require every projection and projection result to be loaded into memory.

The result each projection is placed in the outputDirectory. A [projection]-build-info.json file is created in the output directory. A directory is created for each projection using the projection name, and a file named model.json is place in each directory.

Parameters:

resultCallback - A thread-safe callback that receives projection results as they complete.

exceptionCallback - A thread-safe callback that receives the name of each failed projection and the exception that occurred.

Throws:

java.lang.IllegalStateException - if a SmithyBuildConfig is not set.

config

public SmithyBuild config(SmithyBuildConfig config)

Sets the required configuration object used to build the model.

Parameters:

config - Configuration to set.

Returns:

Returns the builder.

config

public SmithyBuild config(java.nio.file.Path configPath)

Sets the required configuration object used to build the model.

Parameters:

configPath - Path to the configuration to set.

Returns:

Returns the builder.

model

public SmithyBuild model(Model model)

Sets an optional model to use with the build. The provided model is used alongside any "imports" found in the configuration object.

Parameters:

model - Model to build.

Returns:

Returns the builder.

importBasePath

@Deprecated
public SmithyBuild importBasePath(java.nio.file.Path importBasePath)

Deprecated.

outputDirectory

public SmithyBuild outputDirectory(java.nio.file.Path outputDirectory)

Set a directory where the build artifacts are written.

Calling this method will supersede any outputDirectory setting returned by SmithyBuildConfig.getOutputDirectory().

If no output directory is specified here or in the config, then a default output directory of the current working directory resolved with ./build/smithy is used.

Parameters:

outputDirectory - Directory where artifacts are written.

Returns:

Returns the builder.

See Also:

SmithyBuildConfig.getOutputDirectory()

outputDirectory

public SmithyBuild outputDirectory(java.lang.String outputDirectory)

Set a directory where the build artifacts are written.

Calling this method will supersede any outputDirectory setting returned by SmithyBuildConfig.getOutputDirectory().

If no output directory is specified here or in the config, then a default output directory of the current working directory + ./build/smithy is used.

Parameters:

outputDirectory - Directory where artifacts are written.

Returns:

Returns the builder.

See Also:

SmithyBuildConfig.getOutputDirectory()

fileManifestFactory

public SmithyBuild fileManifestFactory(java.util.function.Function<java.nio.file.Path,FileManifest> fileManifestFactory)

Sets a factory function that's used to create FileManifest objects when writing SmithyBuildPlugin artifacts.

A default implementation of FileManifest.create(java.nio.file.Path) will be used if a custom factory is not provided.

Parameters:

fileManifestFactory - Factory that accepts a base path and returns a FileManifest.

Returns:

Returns the builder.

modelAssemblerSupplier

public SmithyBuild modelAssemblerSupplier(java.util.function.Supplier<ModelAssembler> modelAssemblerSupplier)

Called to create ModelAssembler to load the original model and to load each projected model.

If not provided, the runner will use a default ModelAssembler implementation that discovers traits, validators, and other service providers using the class path and module path of software.smithy.model.

Warning: this supplier can be invoked multiple times to build a single projection, cache things like service provider factories when necessary. The same instance of a ModelAssembler MUST NOT be returned from successive calls to the supplier because assemblers are created and mutated in different threads.

Parameters:

modelAssemblerSupplier - ModelValidator supplier to utilize.

Returns:

Returns the builder.

modelTransformer

public SmithyBuild modelTransformer(ModelTransformer modelTransformer)

Sets a custom ModelTransformer to use when building projections.

The runner will use a default ModelTransformer if one is not provided.

Parameters:

modelTransformer - Transformer to set.

Returns:

Returns the builder.

transformFactory

public SmithyBuild transformFactory(java.util.function.Function<java.lang.String,java.util.Optional<ProjectionTransformer>> transformFactory)

Sets a factory function used to create transforms by name.

A default implementation that utilizes Java SPI to discover implementations of ProjectionTransformer will be used if a custom factory is not provided.

Parameters:

transformFactory - Factory that accepts a transform name and returns the optionally found transform.

Returns:

Returns the builder.

See Also:

ProjectionTransformer.createServiceFactory()

pluginFactory

public SmithyBuild pluginFactory(java.util.function.Function<java.lang.String,java.util.Optional<SmithyBuildPlugin>> pluginFactory)

Sets a factory function used to create plugins by name.

A default implementation that utilizes Java SPI to discover implementations of SmithyBuildPlugin will be used if a custom factory is not provided.

Parameters:

pluginFactory - Plugin factory that accepts a plugin name and returns the optionally found plugin.

Returns:

Returns the builder.

See Also:

SmithyBuildPlugin.createServiceFactory(java.lang.Iterable<software.amazon.smithy.build.SmithyBuildPlugin>)

pluginClassLoader

public SmithyBuild pluginClassLoader(java.lang.ClassLoader pluginClassLoader)

Sets a ClassLoader that should be used by SmithyBuild plugins when discovering services.

Parameters:

pluginClassLoader - ClassLoader plugins discover services with.

Returns:

Returns the builder.

registerSources

public SmithyBuild registerSources(java.nio.file.Path... pathToSources)

Registers the given paths as sources of the model being built.

There are typically two kinds of models that are added to a build: source models and discovered models. Discovered models are someone else's models. Source models are the models owned by the package being built.

Source models are copied into the automatically executed "manifest" plugin. If no transformations were applied to the sources, then the source models are copied literally into the manifest directory output. Otherwise, a modified version of the source models are copied.

When a directory is provided, all of the files in the directory are treated as sources, and they are relativized to remove the directory. When a file is provided, the directory that contains that file is used as a source. All of the relativized files resolved in sources must be unique across the entire set of files. The sources directories are essentially flattened into a single directory.

Parameters:

pathToSources - Path to source directories to mark.

Returns:

Returns the builder.

projectionFilter

public SmithyBuild projectionFilter(java.util.function.Predicate<java.lang.String> projectionFilter)

Sets a predicate that accepts the name of a projection and returns true if the projection should be built.

Parameters:

projectionFilter - Predicate that accepts a projection name.

Returns:

Returns the builder.

pluginFilter

public SmithyBuild pluginFilter(java.util.function.Predicate<java.lang.String> pluginFilter)

Sets a predicate that accepts the name of a plugin and returns true if the plugin should be built.

Parameters:

pluginFilter - Predicate that accepts a projection name.

Returns:

Returns the builder.