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.
    All Known Subinterfaces:
    TraitCodegenIntegration
    All Known Implementing Classes:
    CoreIntegration, IdRefDecoratorIntegration, JavaDocIntegration, UniqueItemDecoratorIntegration

    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 Detail

      • name

        default java.lang.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 java.util.List<java.lang.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 java.util.List<java.lang.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.
      • 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<?,​?,​?>> java.util.List<I> sort​(java.lang.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:
        java.lang.IllegalArgumentException - If a cycle is found between integrations.
        java.lang.IllegalArgumentException - If multiple integrations share the same name.