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.
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 TypeMethodDescriptiondefault void
configure
(S settings, ObjectNode integrationSettings) Configures the integration.default void
Allows generators to write additional files, perform additional tasks, and interact directly with aFileManifest
used to write files to the plugin's output.default SymbolProvider
decorateSymbolProvider
(Model model, S settings, SymbolProvider symbolProvider) Updates theSymbolProvider
used when generating code.default List<? extends CodeInterceptor<? extends CodeSection,
W>> interceptors
(C codegenContext) Gets a list ofCodeInterceptor
s to register with theAbstractCodeWriter
s created by the code generator.default 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 byrunBefore()
andrunAfter()
.runAfter()
Gets the name of the integrations that this integration must come after.Gets the names of integrations that this integration must come before.static <I extends SmithyIntegration<?,
?, ?>>
List<I>Topologically sorts a list of integrations based on priority, runBefore, and runAfter, and integration names.
-
Method Details
-
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 byrunBefore()
andrunAfter()
.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
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()
ismy-integration
Would receive the extra settings from the key of the same name within theintegrations
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
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
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
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 theSymbolProvider
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 originalSymbolProvider
.- Returns:
- The decorated
SymbolProvider
.
-
interceptors
Gets a list ofCodeInterceptor
s to register with theAbstractCodeWriter
s created by the code generator.This integration method should be called only after
preprocessModel(software.amazon.smithy.model.Model, S)
anddecorateSymbolProvider(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
CodeInterceptor
s.
-
customize
Allows generators to write additional files, perform additional tasks, and interact directly with aFileManifest
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
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.
-