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. 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.