Package software.amazon.smithy.build

Class 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 Description
      static java.lang.String VERSION
      The version of Smithy build.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method 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<software.amazon.smithy.model.loader.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​(software.amazon.smithy.model.Model model)
      Sets an optional model to use with the build.
      SmithyBuild modelAssemblerSupplier​(java.util.function.Supplier<software.amazon.smithy.model.loader.ModelAssembler> modelAssemblerSupplier)
      Called to create ModelAssembler to load the original model and to load each projected model.
      SmithyBuild modelTransformer​(software.amazon.smithy.model.transform.ModelTransformer modelTransformer)
      Sets a custom ModelTransformer to use when building projections.
      SmithyBuild outputDirectory​(java.lang.String outputDirectory)
      Set a directory where the build artifacts are written.
      SmithyBuild outputDirectory​(java.nio.file.Path 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()

    • 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<software.amazon.smithy.model.loader.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​(software.amazon.smithy.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()

      • modelAssemblerSupplier

        public SmithyBuild modelAssemblerSupplier​(java.util.function.Supplier<software.amazon.smithy.model.loader.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​(software.amazon.smithy.model.transform.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()

      • 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.