Package software.amazon.smithy.build

Class SmithyBuild

java.lang.Object
software.amazon.smithy.build.SmithyBuild
public final class SmithyBuild extends Object
Runs the projections and plugins found in a SmithyBuildConfig and writes the artifacts to a FileManifest.

  • Field Details

  • Constructor Details

    • SmithyBuild

      public SmithyBuild()

    • SmithyBuild

      public SmithyBuild(SmithyBuildConfig config)

  • Method Details

    • create

      public static SmithyBuild create(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(ClassLoader classLoader, 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.

    • getDefaultOutputDirectory

      public static Path getDefaultOutputDirectory()
      Gets the default directory where smithy-build artifacts are written.
      Returns:
      Returns the build output path.

    • 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:
      IllegalStateException - if a SmithyBuildConfig is not set.
      SmithyBuildException - if the build fails.
      See Also:

    • build

      public void build(Consumer<ProjectionResult> resultCallback, BiConsumer<String,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:
      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(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(Path importBasePath)
      Deprecated.

    • outputDirectory

      public SmithyBuild outputDirectory(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:

    • outputDirectory

      public SmithyBuild outputDirectory(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:

    • fileManifestFactory

      public SmithyBuild fileManifestFactory(Function<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(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(Function<String,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:

    • pluginFactory

      public SmithyBuild pluginFactory(Function<String,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:

    • pluginClassLoader

      public SmithyBuild pluginClassLoader(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(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.

      Unsupported model files are ignored and not treated as sources. This can happen when adding model files from a directory that contains a mix of model files and non-model files. Filtering models here prevents unsupported files from appearing in places like JAR manifest files where they are not allowed.

      Parameters:
      pathToSources - Path to source directories to mark.
      Returns:
      Returns the builder.

    • projectionFilter

      public SmithyBuild projectionFilter(Predicate<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(Predicate<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.