Package software.amazon.smithy.codegen.core

Interface SmithyIntegration<S,W extends SymbolWriter<W,?>,C extends CodegenContext<S,W,?>>

Type Parameters:
S - The settings object used to configure the generator.
W - The type of AbstractCodeWriter used by the generator.
C - The CodegenContext value used by the generator.
public interface SmithyIntegration<S,W extends SymbolWriter<W,?>,C extends CodegenContext<S,W,?>>
This interface provides the base concept of an "Integration" to Smithy code generators.

This class provides the bare minimum that most Smithy code generators can implement as a tool to customize generators. Code generators are expected to extend this interface to add various hooks to their generator (e.g., register protocol generators, register auth scheme integrations, attach middleware, intercept and augment CodeWriter sections, etc).

This interface is currently unstable as more requirements may be added in the future.

  • Method Details

    • name

      default String name()
      Gets the name of the integration.

      This name is referred to when ordering the graph of integrations. The name defaults to the canonical class name if not overridden.

      Returns:
      Returns the integration name.

    • priority

      default byte priority()
      Gets the priority ordering relative to the topologically ordered integration graph determined by runBefore() and runAfter().

      Higher numbers come before lower numbers.

      When ordering, implementations must not allow cycles, and no two integrations may have the same name.

      Returns:
      Returns the priority order.

    • configure

      default void configure(S settings, ObjectNode integrationSettings)
      Configures the integration.

      This provides access to both the parsed settings for the generator and an unparsed ObjectNode containing settings for this particular integration.

      The following smithy-build.json file contains an example of how this configuration will be set. 

      
 {
     "version": "1.0",
     "projections": {
         "codegen-projection": {
             "plugins": {
                 "code-generator": {
                     "service": "com.example#DocumentedService",
                     "integrations": {
                         "my-integration": {
                             "example-setting": "foo"
                         }
                     }
                 }
             }
         }
     }
 }

      In this example, an integration whose name() is my-integration Would receive the extra settings from the key of the same name within the integrations node.

      Integrations SHOULD use modeled traits as much as possible to drive configuration. This is intended for configuration that doesn't make sense as a trait, such as configuring a documentation theme.

      Parameters:
      settings - Settings used to generate code.
      integrationSettings - Settings used to configure integrations.

    • runBefore

      default List<String> runBefore()
      Gets the names of integrations that this integration must come before.

      Dependencies are soft. Dependencies on integration names that cannot be found log a warning and are ignored.

      Returns:
      Returns the integration names this must come before.

    • runAfter

      default List<String> runAfter()
      Gets the name of the integrations that this integration must come after.

      Dependencies are soft. Dependencies on integration names that cannot be found log a warning and are ignored.

      Returns:
      Returns the integration names this must come after.

    • preprocessModel

      default Model preprocessModel(Model model, S settings)
      Preprocess the model before code generation.

      This can be used to remove unsupported features, remove traits from shapes (e.g., make members optional), etc.

      By default, this method will return the given model as-is.

      Parameters:
      model - Model being generated.
      settings - Settings used to generate code.
      Returns:
      Returns the updated model.

    • decorateSymbolProvider

      default SymbolProvider decorateSymbolProvider(Model model, S settings, SymbolProvider symbolProvider)
      Updates the SymbolProvider used when generating code.

      This can be used to customize the names of shapes, the package that code is generated into, add dependencies, add imports, etc.

      By default, this method will return the given symbolProvider as-is.

      This integration method should be called only after preprocessModel(software.amazon.smithy.model.Model, S).

      Parameters:
      model - Model being generated.
      settings - Settings used to generate.
      symbolProvider - The original SymbolProvider.
      Returns:
      The decorated SymbolProvider.

    • interceptors

      default List<? extends CodeInterceptor<? extends CodeSection,W>> interceptors(C codegenContext)
      Gets a list of CodeInterceptors to register with the AbstractCodeWriters created by the code generator.

      This integration method should be called only after preprocessModel(software.amazon.smithy.model.Model, S) and decorateSymbolProvider(software.amazon.smithy.model.Model, S, software.amazon.smithy.codegen.core.SymbolProvider).

      Parameters:
      codegenContext - Code generation context that can be queried when creating interceptors.
      Returns:
      Returns the list of CodeInterceptors.

    • customize

      default void customize(C codegenContext)
      Allows generators to write additional files, perform additional tasks, and interact directly with a FileManifest used to write files to the plugin's output.

      This method should generally be invoked at the end of the code generation process.

      Parameters:
      codegenContext - Code generation context that can be queried when writing additional files.

    • sort

      static <I extends SmithyIntegration<?, ?, ?>> List<I> sort(Iterable<I> integrations)
      Topologically sorts a list of integrations based on priority, runBefore, and runAfter, and integration names.
      Type Parameters:
      I - The type of integration to sort.
      Parameters:
      integrations - Integrations to sort.
      Returns:
      Returns the sorted integrations.
      Throws:
      IllegalArgumentException - If a cycle is found between integrations.
      IllegalArgumentException - If multiple integrations share the same name.