Package software.amazon.smithy.model.loader

Class ModelAssembler

java.lang.Object
software.amazon.smithy.model.loader.ModelAssembler
public final class ModelAssembler extends Object
Assembles and validates a Model from documents, files, shapes, and other sources.

Validation vents are aggregated into a Set to ensure that duplicate events are not emitted.

Smithy models found on the class path can be discovered using model discovery. Model discovery must be explicitly requested of a ModelAssembler by invoking discoverModels() or discoverModels(ClassLoader).

See Also:

  • Field Details

    • ALLOW_UNKNOWN_TRAITS

      public static final String ALLOW_UNKNOWN_TRAITS
      Allow unknown traits rather than fail.
      See Also:

    • DISABLE_JAR_CACHE

      public static final String DISABLE_JAR_CACHE
      Sets URLConnection.setUseCaches(boolean) to false.

      When running in a build environment, using caches can cause exceptions like `java.util.zip.ZipException: ZipFile invalid LOC header (bad signature)` because a previously loaded JAR might change between builds. The "assembler.disableJarCache" setting should be set to true when embedding Smithy into an environment where this can occur.

      See Also:

  • Constructor Details

    • ModelAssembler

      public ModelAssembler()

  • Method Details

    • copy

      public ModelAssembler copy()
      Creates a copy of the current model assembler.
      Returns:
      Returns the created model assembler copy.

    • reset

      public ModelAssembler reset()
      Resets the state of the ModelAssembler.

      The following properties of the ModelAssembler are cleared when this method is called:

      The state of disablePrelude is reset such that the prelude is no longer disabled after calling reset.

      Returns:
      Returns the model assembler.

    • traitFactory

      public ModelAssembler traitFactory(TraitFactory traitFactory)
      Uses a custom TraitFactory to resolve and configure traits.
      Parameters:
      traitFactory - Trait factory to use instead of the default.
      Returns:
      Returns the assembler.

    • validatorFactory

      public ModelAssembler validatorFactory(ValidatorFactory validatorFactory)
      Sets a custom ValidatorFactory used to dynamically resolve validator definitions.

      Note that if you do not provide an explicit validatorFactory, a default factory is utilized that uses service discovery.

      Parameters:
      validatorFactory - Validator factory to use.
      Returns:
      Returns the assembler.

    • addValidator

      public ModelAssembler addValidator(Validator validator)
      Registers a validator to be used when validating the model.
      Parameters:
      validator - Validator to register.
      Returns:
      Returns the assembler.

    • addUnparsedModel

      public ModelAssembler addUnparsedModel(String sourceLocation, String model)
      Adds a string containing an unparsed model to the assembler.

      The provided sourceLocation string must end with ".json" or ".smithy" to be parsed correctly.

      Parameters:
      sourceLocation - Source location to assume for the unparsed content.
      model - Unparsed model source.
      Returns:
      Returns the assembler.

    • addDocumentNode

      public ModelAssembler addDocumentNode(Node document)
      Adds a parsed JSON model file as a Node to the assembler.
      Parameters:
      document - Parsed document node to add.
      Returns:
      Returns the assembler.

    • addImport

      public ModelAssembler addImport(String importPath)
      Adds an import to the assembler.
      Parameters:
      importPath - Import path to add.
      Returns:
      Returns the assembler.
      See Also:

    • addImport

      public ModelAssembler addImport(Path importPath)
      Adds an import to the assembler.

      If a directory is found, all ".json" and ".ion" files that contain a "smithy" key-value pair found in the directory and any subdirectories are imported into the model.

      Parameters:
      importPath - Import path to add.
      Returns:
      Returns the assembler.

    • addImport

      public ModelAssembler addImport(URL url)
      Adds an import to the assembler from a URL.

      The provided URL can point to a .json model, .smithy model, or a .jar file that contains Smithy models. 

       
 Model model = Model.assembler()
      .addImport(getClass().getClassLoader().getResource("model.json"))
      .assemble()
      .unwrap();
      Parameters:
      url - Resource URL to load and add.
      Returns:
      Returns the assembler.

    • disablePrelude

      public ModelAssembler disablePrelude()
      Disables automatically loading the prelude models.
      Returns:
      Returns the assembler.

    • addShape

      public ModelAssembler addShape(Shape shape)
      Explicitly injects a shape into the assembled model.
      Parameters:
      shape - Shape to add.
      Returns:
      Returns the assembler.

    • addShapes

      public ModelAssembler addShapes(Shape... shapes)
      Explicitly injects multiple shapes into the assembled model.
      Parameters:
      shapes - Shapes to add.
      Returns:
      Returns the assembler.

    • addTrait

      public ModelAssembler addTrait(ShapeId target, Trait trait)
      Explicitly adds a trait to a shape in the assembled model.
      Parameters:
      target - Shape to add the trait to.
      trait - Trait to add.
      Returns:
      Returns the assembler.

    • addModel

      public ModelAssembler addModel(Model model)
      Merges a loaded model into the model assembler.
      Parameters:
      model - Model to merge in.
      Returns:
      Returns the model assembler.

    • putMetadata

      public ModelAssembler putMetadata(String name, Node value)
      Adds metadata to the model.
      Parameters:
      name - Metadata key to set.
      value - Metadata value to set.
      Returns:
      Returns the model assembler.

    • discoverModels

      public ModelAssembler discoverModels(ClassLoader loader)
      Discovers models by merging in all models returns by ModelDiscovery manifests using the provided ClassLoader.
      Parameters:
      loader - Class loader to use to discover models.
      Returns:
      Returns the model assembler.

    • discoverModels

      public ModelAssembler discoverModels()
      Discovers models by merging in all models returns by ModelDiscovery manifests using the thread context ClassLoader.
      Returns:
      Returns the model assembler.

    • putProperty

      public ModelAssembler putProperty(String setting, Object value)
      Puts a configuration property on the ModelAssembler.

      Any number of properties can be given to the model assembler to affect how models are loaded. Some properties like ALLOW_UNKNOWN_TRAITS are built-in properties, while other properties can be custom properties that are specific to certain ModelLoader implementations.

      The following example configures the ModelAssembler to emit warnings for unknown traits rather than fail: 

      
 ModelAssembler assembler = Model.assembler();
 assembler.putProperty(ModelAssembler.ALLOW_UNKNOWN_TRAITS, true);
      Parameters:
      setting - Name of the property to put.
      value - Value to set for the property.
      Returns:
      Returns the assembler.

    • removeProperty

      public ModelAssembler removeProperty(String setting)
      Removes a setting from the ModelAssembler.
      Parameters:
      setting - Setting to remove.
      Returns:
      Returns the assembler.

    • disableValidation

      public ModelAssembler disableValidation()
      Disables additional validation of the model.
      Returns:
      Returns the assembler.

    • validationEventListener

      public ModelAssembler validationEventListener(Consumer<ValidationEvent> eventListener)
      Sets a listener that is invoked each time a ValidationEvent is encountered while loading and validating the model.

      The consumer could be invoked simultaneously by multiple threads. It's up to the consumer to perform any necessary synchronization. Providing an event listener is useful for things like CLIs so that events can be streamed to stdout as soon as they are encountered, rather than waiting until the entire model is parsed and validated.

      Parameters:
      eventListener - Listener invoked for each ValidationEvent.
      Returns:
      Returns the assembler.

    • assemble

      public ValidatedResult<Model> assemble()
      Assembles the model and returns the validated result.
      Returns:
      Returns the validated result that optionally contains a Model and validation events.