Package software.amazon.smithy.model.transform

Class ModelTransformer

  • public final class ModelTransformer
extends java.lang.Object
    Class used to transform Models.

    • Method Detail

      • create

        public static ModelTransformer create()
        Creates a ModelTransformer using ModelTransformerPlugin instances discovered using the com.software.smithy.transform class loader and any modules found in the module path.
        Returns:
        Returns the created ModelTransformer.

      • createWithPlugins

        public static ModelTransformer createWithPlugins​(java.util.List<ModelTransformerPlugin> plugins)
        Creates a ModelTransformer using a list of ModelTransformer plugins.
        Parameters:
        plugins - Plugins to use with the transformer.
        Returns:
        Returns the created ModelTransformer.

      • createWithServiceProviders

        public static ModelTransformer createWithServiceProviders​(java.lang.ClassLoader classLoader)
        Creates a ModelTransformer that finds ModelTransformerPlugin service providers using the given ClassLoader.
        Parameters:
        classLoader - ClassLoader used to find ModelTransformerPlugin instances.
        Returns:
        Returns the created ModelTransformer.

      • replaceShapes

        public Model replaceShapes​(Model model,
                           java.util.Collection<? extends Shape> shapes)
        Adds or replaces shapes into the model while ensuring that the model is in a consistent state.
        Parameters:
        model - Model to transform.
        shapes - Shapes to add or replace in the model.base.
        Returns:
        Returns the transformed model.base.

      • removeShapes

        public Model removeShapes​(Model model,
                          java.util.Collection<? extends Shape> shapes)
        Removes shapes from the model while ensuring that the model is in a consistent state.
        Parameters:
        model - Model to transform.
        shapes - Shapes to add or replace in the model.base.
        Returns:
        Returns the transformed model.base.

      • removeShapesIf

        public Model removeShapesIf​(Model model,
                            java.util.function.Predicate<Shape> predicate)
        Removes shapes from the model that match the given predicate.
        Parameters:
        model - Model to transform.
        predicate - Predicate that accepts a shape and returns true to remove it.
        Returns:
        Returns the transformed model.base.

      • renameShapes

        public Model renameShapes​(Model model,
                          java.util.Map<ShapeId,​ShapeId> renamed)
        Renames shapes using ShapeId pairs while ensuring that the transformed model is in a consistent state.

        This transformer ensures that when an aggregate shape is renamed, all members are updated in the model.

        Parameters:
        model - Model to transform.
        renamed - Map of shapeIds
        Returns:
        Returns the transformed model.base.

      • renameShapes

        public Model renameShapes​(Model model,
                          java.util.Map<ShapeId,​ShapeId> renamed,
                          java.util.function.Supplier<ModelAssembler> modelAssemblerSupplier)
        Renames shapes using ShapeId pairs while ensuring that the transformed model is in a consistent state.

        This transformer ensures that when an aggregate shape is renamed, all members are updated in the model.

        Parameters:
        model - Model to transform.
        renamed - Map of shapeIds
        modelAssemblerSupplier - Supplier used to create ModelAssemblers in each transform.
        Returns:
        Returns the transformed model.

      • filterTraits

        public Model filterTraits​(Model model,
                          java.util.function.BiPredicate<Shape,​Trait> predicate)
        Filters traits out of the model that do not match the given predicate.

        The predicate function accepts the shape that a trait is attached to and the trait. If the predicate returns false, then the trait is removed from the shape.

        Parameters:
        model - Model to transform.
        predicate - Predicate that accepts a (Shape, Trait) and returns false if the trait should be removed.
        Returns:
        Returns the transformed model.base.

      • removeTraitsIf

        public Model removeTraitsIf​(Model model,
                            java.util.function.BiPredicate<Shape,​Trait> predicate)
        Filters traits out of the model that match a predicate function.

        The predicate function accepts the shape that a trait is attached to and the trait. If the predicate returns true, then the trait is removed from the shape.

        Parameters:
        model - Model to transform.
        predicate - Predicate that accepts a (Shape, Trait) and returns true if the trait should be removed.
        Returns:
        Returns the transformed model.base.

      • filterMetadata

        public Model filterMetadata​(Model model,
                            java.util.function.BiPredicate<java.lang.String,​Node> predicate)
        Filters out metadata key-value pairs from a model that do not match a predicate.
        Parameters:
        model - Model to transform.
        predicate - A predicate that accepts a metadata key-value pair. If the predicate returns true, then the metadata key-value pair is kept. Otherwise, it is removed.
        Returns:
        Returns the transformed model.base.

      • mapTraits

        public Model mapTraits​(Model model,
                       java.util.function.BiFunction<Shape,​Trait,​Trait> mapper)
        Maps over all traits in the model using a mapping function that accepts the shape the trait is applied to, a trait, and returns a trait, possibly even a different kind of trait.

        An exception is thrown if a trait is returned that targets a different shape than the Shape passed into the mapper function.

        Parameters:
        model - Model to transform.
        mapper - Mapping function that accepts a (Shape, Trait) and returns the mapped Trait.
        Returns:
        Returns the transformed model.base.

      • mapTraits

        public Model mapTraits​(Model model,
                       java.util.List<java.util.function.BiFunction<Shape,​Trait,​Trait>> mappers)
        Maps over all traits in the model using multiple mapping functions.

        Note: passing in a list of mappers is much more efficient than invoking mapTraits multiple times because it reduces the number of intermediate models that are needed to perform the transformation.

        Parameters:
        model - Model to transform.
        mappers - Mapping functions that accepts a (Shape, Trait) and returns the mapped Trait.
        Returns:
        Returns the transformed model.base.
        See Also:
        for more information.

      • mapShapes

        public Model mapShapes​(Model model,
                       java.util.function.Function<Shape,​Shape> mapper)
        Maps over all shapes in the model using a mapping function, allowing shapes to be replaced with completely different shapes or slightly modified shapes.

        An exception is thrown if a mapper returns a shape with a different shape ID or a different type.

        Parameters:
        model - Model to transform.
        mapper - Mapping function that accepts a shape and returns a shape with the same ID.
        Returns:
        Returns the transformed model.base.

      • mapShapes

        public Model mapShapes​(Model model,
                       java.util.List<java.util.function.Function<Shape,​Shape>> mappers)
        Maps over all shapes in the model using multiple mapping functions.

        Note: passing in a list of mappers is much more efficient than invoking mapShapes multiple times because it reduces the number of intermediate models that are needed to perform the transformation.

        Parameters:
        model - Model to transform.
        mappers - Mapping functions that accepts a shape and returns a shape with the same ID.
        Returns:
        Returns the transformed model.base.
        See Also:
        for more information.

      • removeUnreferencedShapes

        public Model removeUnreferencedShapes​(Model model)
        Removes shapes (excluding service shapes) that are not referenced by any other shapes.
        Parameters:
        model - Model to transform.
        Returns:
        Returns the transformed model.base.

      • removeUnreferencedShapes

        public Model removeUnreferencedShapes​(Model model,
                                      java.util.function.Predicate<Shape> keepFilter)
        Removes shapes (excluding service shapes) that are not referenced by any other shapes. Shapes that are part of the prelude or that act as the shape of any trait, regardless of if the trait is in use in the model, are never considered unreferenced.
        Parameters:
        model - Model to transform.
        keepFilter - Predicate function that accepts an unreferenced shape and returns true to remove the shape or false to keep the shape in the model.base.
        Returns:
        Returns the transformed model.base.

      • removeUnreferencedTraitDefinitions

        public Model removeUnreferencedTraitDefinitions​(Model model)
        Removes definitions for traits that are not used by any shape in the model.base. Trait definitions that are part of the prelude will not be removed.
        Parameters:
        model - Model to transform
        Returns:
        Returns the transformed model.base.

      • removeUnreferencedTraitDefinitions

        public Model removeUnreferencedTraitDefinitions​(Model model,
                                                java.util.function.Predicate<Shape> keepFilter)
        Removes trait definitions for traits that are not used by any shape in the model.

        Trait definitions that are part of the prelude will not be removed.

        Parameters:
        model - Model to transform
        keepFilter - Predicate function that accepts an unreferenced trait shape (that has the TraitDefinition trait) and returns true to remove the definition or false to keep the definition in the model.base.
        Returns:
        Returns the transformed model.base.

      • scrubTraitDefinitions

        public Model scrubTraitDefinitions​(Model model)
        Removes all trait definitions from a model and all shapes that are only connected to the graph either directly or transitively by a trait definition shape.

        This can be useful when serializing a Smithy model to a format that does not include trait definitions and the shapes used by trait definitions would have no meaning (e.g., OpenAPI).

        Parameters:
        model - Model to transform.
        Returns:
        Returns the transformed model.base.

      • scrubTraitDefinitions

        public Model scrubTraitDefinitions​(Model model,
                                   java.util.function.Predicate<Shape> keepFilter)
        Removes trait definitions from a model and all shapes that are only connected to the graph either directly or transitively by a trait definition shape.

        This can be useful when serializing a Smithy model to a format that does not include trait definitions and the shapes used by trait definitions would have no meaning (e.g., OpenAPI).

        Parameters:
        model - Model to transform.
        keepFilter - Predicate function that accepts an trait shape (that has the TraitDefinition trait) and returns true to remove the definition or false to keep the definition in the model.
        Returns:
        Returns the transformed model.

      • getModelWithoutTraitShapes

        public Model getModelWithoutTraitShapes​(Model model)
        Gets all shapes from a model where shapes that define traits or shapes that are only used as part of a trait definition have been removed.
        Parameters:
        model - Model that contains shapes.
        Returns:
        Returns a model that contains matching shapes.

      • getModelWithoutTraitShapes

        public Model getModelWithoutTraitShapes​(Model model,
                                        java.util.function.Predicate<Shape> keepFilter)
        Gets all shapes from a model where shapes that define traits or shapes that are only used as part of a trait definition have been removed.
        Parameters:
        model - Model that contains shapes.
        keepFilter - Predicate function that accepts a trait shape (that has the TraitDefinition trait) and returns true to remove the definition or false to keep the definition in the model.
        Returns:
        Returns a model that contains matching shapes.

      • sortMembers

        public Model sortMembers​(Model model,
                         java.util.Comparator<MemberShape> comparator)
        Reorders the members of structure and union shapes using the given Comparator.

        Note that by default, Smithy models retain the order in which members are defined in the model. However, in programming languages where this isn't important, it may be desirable to order members alphabetically or using some other kind of order.

        Parameters:
        model - Model that contains shapes.
        comparator - Comparator used to order members of unions and structures.
        Returns:
        Returns a model that contains matching shapes.

      • changeShapeType

        public Model changeShapeType​(Model model,
                             java.util.Map<ShapeId,​ShapeType> shapeToType)
        Changes the type of each given shape.

        The following transformations are permitted:

        • Any simple type to any simple type
        • List to set
        • Set to list
        • Structure to union
        • Union to structure
        Parameters:
        model - Model to transform.
        shapeToType - Map of shape IDs to the new type to use for the shape.
        Returns:
        Returns the transformed model.
        Throws:
        ModelTransformException - if an incompatible type transform is attempted.

      • changeShapeType

        public Model changeShapeType​(Model model,
                             java.util.Map<ShapeId,​ShapeType> shapeToType,
                             ChangeShapeTypeOption... changeShapeTypeOptions)
        Changes the type of each given shape.

        The following transformations are permitted:

        • Any simple type to any simple type
        • List to set
        • Set to list
        • Structure to union
        • Union to structure
        Parameters:
        model - Model to transform.
        shapeToType - Map of shape IDs to the new type to use for the shape.
        changeShapeTypeOptions - An array of options to enable when changing types.
        Returns:
        Returns the transformed model.
        Throws:
        ModelTransformException - if an incompatible type transform is attempted.

      • changeStringEnumsToEnumShapes

        public Model changeStringEnumsToEnumShapes​(Model model,
                                           boolean synthesizeEnumNames)
        Changes each compatible string shape with the enum trait to an enum shape.

        A member will be created on the shape for each entry in the EnumTrait.

        When the enum definition from the enum trait has been marked as deprecated, or tagged as "internal", the corresponding enum shape member will be marked with the DeprecatedTrait or InternalTrait accordingly.

        Parameters:
        model - Model to transform.
        synthesizeEnumNames - Whether enums without names should have names synthesized if possible.
        Returns:
        Returns the transformed model.

      • changeStringEnumsToEnumShapes

        public Model changeStringEnumsToEnumShapes​(Model model)
        Changes each compatible string shape with the enum trait to an enum shape.

        A member will be created on the shape for each entry in the EnumTrait.

        Strings with enum traits that don't define names are not converted.

        Parameters:
        model - Model to transform.
        Returns:
        Returns the transformed model.

      • downgradeEnums

        public Model downgradeEnums​(Model model)
        Changes each enum shape to a string shape and each intEnum to an integer.
        Parameters:
        model - Model to transform.
        Returns:
        Returns the transformed model.

      • copyServiceErrorsToOperations

        public Model copyServiceErrorsToOperations​(Model model,
                                           ServiceShape forService)
        Copies the errors defined on the given service onto each operation bound to the service, effectively flattening service error inheritance.
        Parameters:
        model - Model to modify.
        forService - Service shape to use as the basis for copying errors to operations.
        Returns:
        Returns the transformed model.

      • createDedicatedInputAndOutput

        public Model createDedicatedInputAndOutput​(Model model,
                                           java.lang.String inputSuffix,
                                           java.lang.String outputSuffix)
        Updates the model so that every operation has a dedicated input shape marked with the input trait and output shape marked with the output trait, and the targeted shapes all have a consistent shape name of OperationName + inputSuffix / outputSuffix depending on the context.

        If an operation's input already targets a shape marked with the input trait, then the existing input shape is used as input, though the shape will be renamed if it does not use the given inputSuffix. If an operation's output already targets a shape marked with the output trait, then the existing output shape is used as output, though the shape will be renamed if it does not use the given outputSuffix.

        If the operation's input shape starts with the name of the operation and is only used throughout the model as the input of the operation, then it is updated to have the input trait, and the name remains unaltered.

        If the operation's output shape starts with the name of the operation and is only used throughout the model as the output of the operation, then it is updated to have the output trait, and the name remains unaltered.

        If the operation's input shape does not start with the operation's name or is used in other places throughout the model, a copy of the targeted input structure is created, the name of the shape becomes OperationName + inputSuffix, and the input trait is added to the shape. The operation is then updated to target the created shape, and the original shape is left as-is in the model.

        If the operation's output shape does not start with the operation's name or is used in other places throughout the model, a copy of the targeted output structure is created, the name of the shape becomes OperationName + outputSuffix, and the output trait is added to the shape. The operation is then updated to target the created shape, and the original shape is left as-is in the model.

        If a naming conflict occurs while attempting to create a new shape, then the default naming conflict resolver will attempt to name the shape OperationName + "Operation" + inputSuffix / outputSuffix depending on the context. If the name is still in conflict with other shapes in the model, then a ModelTransformException is thrown.

        Any time a shape is renamed, the original shape ID of the shape is captured on the shape using the synthetic OriginalShapeIdTrait. This might be useful for protocols that need to serialize input and output shape names.

        Parameters:
        model - Model to update.
        inputSuffix - Suffix to append to dedicated input shapes (e.g., "Input").
        outputSuffix - Suffix to append to dedicated input shapes (e.g., "Output").
        Returns:
        Returns the updated model.
        Throws:
        ModelTransformException - if an input or output shape name conflict occurs.

      • flattenAndRemoveMixins

        public Model flattenAndRemoveMixins​(Model model)
        Flattens mixins out of the model and removes them from the model.
        Parameters:
        model - Model to flatten.
        Returns:
        Returns the flattened model.

      • addClientOptional

        public Model addClientOptional​(Model model,
                               boolean applyWhenNoDefaultValue)
        Add the clientOptional trait to members that are effectively nullable because they are part of a structure marked with the input trait or they aren't required and don't have a default trait.
        Parameters:
        model - Model to transform.
        applyWhenNoDefaultValue - Set to true to add clientOptional to members that target shapes with no zero value (e.g., structure and union).
        Returns:
        Returns the transformed model.

      • downgradeToV1

        public Model downgradeToV1​(Model model)
        Removes Smithy IDL 2.0 features from a model that are not strictly necessary to keep for consistency with the rest of Smithy.

        This transformer is lossy, and converts enum shapes to string shapes with the enum trait, intEnum shapes to integer shapes, flattens and removes mixins, removes properties from resources, and removes default traits that have no impact on IDL 1.0 semantics (i.e., default traits on structure members set to something other than null, or default traits on any other shape that are not the zero value of the shape of a 1.0 model).

        Parameters:
        model - Model to downgrade.
        Returns:
        Returns the downgraded model.

      • removeInvalidDefaults

        public Model removeInvalidDefaults​(Model model)
        Remove default traits if the default conflicts with the range trait of the shape.
        Parameters:
        model - Model to transform.
        Returns:
        Returns the transformed model.

      • deconflictErrorsWithSharedStatusCode

        public Model deconflictErrorsWithSharedStatusCode​(Model model,
                                                  ServiceShape forService)
        Deconflicts errors that share a status code.
        Parameters:
        model - Model to transform.
        Returns:
        Returns the transformed model.

      • flattenPaginationInfoIntoOperations

        public Model flattenPaginationInfoIntoOperations​(Model model,
                                                 ServiceShape forService)
        Flattens all service-level pagination information into operation-level pagination traits.
        Parameters:
        model - Model to transform.
        Returns:
        Returns the transformed model.

      • filterDeprecatedRelativeDate

        public Model filterDeprecatedRelativeDate​(Model model,
                                          java.lang.String relativeDate)
        Removes any shapes that were deprecated before the specified date.

        The relative date used as a filter should match the ISO 8601 Calendar date format (i.e. YYYY-MM-DD with optional hyphens).

        Note: Shapes with @deprecated trait but no since property are not filtered.

        Parameters:
        model - Model to transform.
        relativeDate - ISO 8601 calendar date to use to filter out deprecated shapes.
        Returns:
        Returns the transformed model.
        See Also:
        ISO 8601

      • filterDeprecatedRelativeVersion

        public Model filterDeprecatedRelativeVersion​(Model model,
                                             java.lang.String relativeVersion)
        Removes any shapes that were deprecated before the specified version.

        The version used should be a valid Semantic Version (SemVer). For example, 1.2.3.1.

        Note: Shapes with @deprecated trait but no since property are not filtered.

        Parameters:
        model - Model to transform.
        relativeVersion - Semantic Version to use to filter out deprecated shapes.
        Returns:
        Returns the transformed model.
        See Also:
        SemVer

      • makeIdempotencyTokensClientOptional

        public Model makeIdempotencyTokensClientOptional​(Model model)
        Makes any @idempotencyToken fields @clientOptional so that missing tokens can be injected.

        Idempotency tokens that are required should fail validation, but shouldn't be required to create a type, allowing for a default value to be injected when missing.

        Parameters:
        model - Model to transform.
        Returns:
        Returns the transformed model.