Package software.amazon.smithy.model.loader

Class ModelAssembler

  • public final class ModelAssembler
extends java.lang.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:
    Model.assembler()

    • Field Detail

      • ALLOW_UNKNOWN_TRAITS

        public static final java.lang.String ALLOW_UNKNOWN_TRAITS
        Allow unknown traits rather than fail.
        See Also:
        Constant Field Values

      • DISABLE_JAR_CACHE

        public static final java.lang.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:
        Constant Field Values

    • Constructor Detail

      • ModelAssembler

        public ModelAssembler()

    • Method Detail

      • copy

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

      • 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​(java.lang.String sourceLocation,
                                       java.lang.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​(java.lang.String importPath)
        Adds an import to the assembler.
        Parameters:
        importPath - Import path to add.
        Returns:
        Returns the assembler.
        See Also:
        addImport(Path)

      • addImport

        public ModelAssembler addImport​(java.nio.file.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​(java.net.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​(java.lang.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​(java.lang.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​(java.lang.String setting,
                                  java.lang.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​(java.lang.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​(java.util.function.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. If a validator or decorator throws, then there is no guarantee that all validation events are emitted to the listener.

        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.