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.

All Known Subinterfaces:

TraitCodegenIntegration

All Known Implementing Classes:

AnnotationIntegration, CoreIntegration, IdRefDecoratorIntegration, JavaDocIntegration

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 Summary

Modifier and Type	Method	Description
default void	configure(S settings, ObjectNode integrationSettings)	Configures the integration.
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.
default SymbolProvider	decorateSymbolProvider(Model model, S settings, SymbolProvider symbolProvider)	Updates the SymbolProvider used when generating code.
default java.util.List<? extends CodeInterceptor<? extends CodeSection,W>>	interceptors(C codegenContext)	Gets a list of CodeInterceptors to register with the AbstractCodeWriters created by the code generator.
default java.lang.String	name()	Gets the name of the integration.
default Model	preprocessModel(Model model, S settings)	Preprocess the model before code generation.
default byte	priority()	Gets the priority ordering relative to the topologically ordered integration graph determined by runBefore() and runAfter().
default java.util.List<java.lang.String>	runAfter()	Gets the name of the integrations that this integration must come after.
default java.util.List<java.lang.String>	runBefore()	Gets the names of integrations that this integration must come before.
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.

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.

interceptors

default java.util.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<?,?,?>> 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.