Package software.amazon.smithy.codegen.core

Class SymbolDependency

  • All Implemented Interfaces:
    java.lang.Comparable<SymbolDependency>, SymbolDependencyContainer, ToSmithyBuilder<SymbolDependency>
    public final class SymbolDependency
extends java.lang.Object
implements SymbolDependencyContainer, ToSmithyBuilder<SymbolDependency>, java.lang.Comparable<SymbolDependency>
    Represents a dependency that is introduced by a Symbol.

    SymbolProvider implementations sometimes need to refer to Symbol values that require a dependency to be brought in when generating code. A dependency can be associated with the Symbol to specify the relationship of a Symbol to a dependency.

    This dependency class was designed to be as generic as possible while still allowing for some extension points through typed properties. If a feature you need is missing (for example, specifying a GitHub repository), use TypedPropertiesBag.Builder.putProperty(java.lang.String, java.lang.Object) to add a property on the dependency that can be understood by you code generator.

    It's up to code generators to make sense of the values provided in a dependency and to aggregate them in a meaningful way. This class uses a package + version combination to define the coordinates of a dependency. Some dependency managers like Maven use a group + package + version combination. In cases like this, it is recommended to specify the package of the symbol as the group + package name (e.g., "software.amazon.smithy.model:0.9.3" becomes a package of "software.amazon.smithy.model" and a version of "0.9.3").

    The dependencyType of a dependency is application and target-specific. When omitted, it defaults to an empty string (""). An arbitrary string value can be provided and should refer to something that makes sense for the target language. For illustrative purposed only: a code generator that targets JavaScript and NPM could set the dependencyType of a dependency to "devDependencies" to add the dependency to the "devDependencies" property of a generated package.json.

    version is also an opaque values that is target-specific and can even be specific to a dependencyType. For example, PHP's Composer provides a section named "suggest" that is a map of package names to a description of the suggestion. A SymbolDependency that is meant to define a "suggest" entry for a composer.json file could set the dependencyType to "suggest", the packageName to the name of the suggested package, and version to the description of the suggestion.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  SymbolDependency.Builder
      Builds a SymbolDependency.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static SymbolDependency.Builder builder()  
      int compareTo​(SymbolDependency other)
      Dependencies can be sorted based on the natural sort order of the dependencyType, packageName, and finally the version.
      boolean equals​(java.lang.Object o)  
      java.lang.Object expectProperty​(java.lang.String name)
      Gets a specific additional property or throws if missing.
      <T> T expectProperty​(java.lang.String name, java.lang.Class<T> type)
      Gets a specific additional property or throws if missing or if the property is not an instance of the given type.
      <T> T expectProperty​(Property<T> property)
      Get a property and throw if it isn't present.
      static java.util.Map<java.lang.String,​java.util.Map<java.lang.String,​SymbolDependency>> gatherDependencies​(java.util.stream.Stream<SymbolDependency> symbolStream)
      Gets a mapping of all dependencies used by the provided symbols.
      static java.util.Map<java.lang.String,​java.util.Map<java.lang.String,​SymbolDependency>> gatherDependencies​(java.util.stream.Stream<SymbolDependency> symbolStream, java.util.function.BinaryOperator<SymbolDependency> versionMergeFunction)
      Gets a mapping of all dependencies used by the provided symbols.
      java.util.List<SymbolDependency> getDependencies()
      Gets the list of dependencies that this object introduces.
      java.lang.String getDependencyType()
      Gets the type of dependency (for example, "dev", "optional", etc).
      java.lang.String getPackageName()
      Gets the package name referenced by the dependency.
      java.util.Map<java.lang.String,​java.lang.Object> getProperties()
      Gets the additional properties of the object.
      java.util.Optional<java.lang.Object> getProperty​(java.lang.String name)
      Gets a specific property if present.
      <T> java.util.Optional<T> getProperty​(java.lang.String name, java.lang.Class<T> type)
      Gets an additional property of a specific type.
      <T> java.util.Optional<T> getProperty​(Property<T> property)
      Get a typed property if present.
      java.util.Map<Property<?>,​java.lang.Object> getTypedProperties()
      Gets the additional typed properties of the object.
      java.lang.String getVersion()
      Gets the version string of the dependency.
      int hashCode()  
      SymbolDependency.Builder toBuilder()
      Take this object and create a builder that contains all of the current property values of this object.
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    • Method Detail

      • gatherDependencies

        public static java.util.Map<java.lang.String,​java.util.Map<java.lang.String,​SymbolDependency>> gatherDependencies​(java.util.stream.Stream<SymbolDependency> symbolStream)
        Gets a mapping of all dependencies used by the provided symbols.

        Given a stream of symbols, the dependencies of the symbol are gathered into a map of the dependencyType to a map of a package name to package version.

        By default, when two versions conflict, an exception is thrown. In the case the a conflict is possible or it is necessary to detect incompatibilities, use gatherDependencies(Stream, BinaryOperator) and provide a custom version merge function.

        Parameters:
        symbolStream - Stream of symbols to compute from.
        Returns:
        Returns a map of dependency types to a map of package to version.
        Throws:
        CodegenException - when two package versions conflict.

      • gatherDependencies

        public static java.util.Map<java.lang.String,​java.util.Map<java.lang.String,​SymbolDependency>> gatherDependencies​(java.util.stream.Stream<SymbolDependency> symbolStream,
                                                                                                                              java.util.function.BinaryOperator<SymbolDependency> versionMergeFunction)
        Gets a mapping of all dependencies used by the provided symbols.

        Given a stream of symbols, the dependencies of the symbol are gathered into a map of the dependencyType to a map of a package name to package version. Dependencies are sorted while they are collected, meaning that newer versions of a conflicting dependency typically take precedence over older versions. However, this is not always true with a natural sort order (e.g., 0.9 and 0.10).

        versionMergeFunction is invoked each time a package import version of a package conflicts with another version of the same package for the same dependency type. The function accepts the dependency type, the package name, the previous version that was registered, the new conflicting version, and is expected to return the version that should be used or can throw in the case of an incompatible conflict. It is a target-specific concern to determine if two version are compatible or to find an acceptable compromise between the two versions.

        Parameters:
        symbolStream - Stream of symbols to compute from.
        versionMergeFunction - Function that determines which two conflicting versions wins.
        Returns:
        Returns a map of dependency types to a map of package to version.

      • getDependencyType

        public java.lang.String getDependencyType()
        Gets the type of dependency (for example, "dev", "optional", etc).

        This value defaults to an empty string if not explicitly set.

        Returns:
        Returns the dependency type.

      • getPackageName

        public java.lang.String getPackageName()
        Gets the package name referenced by the dependency.
        Returns:
        Returns the package name.

      • getVersion

        public java.lang.String getVersion()
        Gets the version string of the dependency.
        Returns:
        Returns the version.

      • getDependencies

        public java.util.List<SymbolDependency> getDependencies()
        Description copied from interface: SymbolDependencyContainer
        Gets the list of dependencies that this object introduces.

        A dependency is a dependency on another package that a Symbol or type requires. It is quite different from a reference since a reference only refers to a symbol; a reference provides no context as to whether or not a dependency is required or the dependency's coordinates.

        Specified by:
        getDependencies in interface SymbolDependencyContainer
        Returns:
        Returns the dependencies.

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • equals

        public boolean equals​(java.lang.Object o)

      • hashCode

        public int hashCode()

      • compareTo

        public int compareTo​(SymbolDependency other)
        Dependencies can be sorted based on the natural sort order of the dependencyType, packageName, and finally the version.
        Specified by:
        compareTo in interface java.lang.Comparable<SymbolDependency>

      • getProperties

        public java.util.Map<java.lang.String,​java.lang.Object> getProperties()
        Gets the additional properties of the object.
        Returns:
        Returns a map of additional property strings.

      • getTypedProperties

        public java.util.Map<Property<?>,​java.lang.Object> getTypedProperties()
        Gets the additional typed properties of the object.
        Returns:
        Returns a map of additional typed properties.

      • getProperty

        public java.util.Optional<java.lang.Object> getProperty​(java.lang.String name)
        Gets a specific property if present.
        Parameters:
        name - Property to retrieve.
        Returns:
        Returns the optionally found property.

      • getProperty

        public <T> java.util.Optional<T> getProperty​(Property<T> property)
        Get a typed property if present.
        Type Parameters:
        T - value type of the property
        Parameters:
        property - property key to get by exact reference identity.
        Returns:
        Returns the optionally found property.

      • getProperty

        public <T> java.util.Optional<T> getProperty​(java.lang.String name,
                                             java.lang.Class<T> type)
        Gets an additional property of a specific type.
        Type Parameters:
        T - Type of value to expect.
        Parameters:
        name - Name of the property to get.
        type - Type of value to expect.
        Returns:
        Returns a map of additional property strings.
        Throws:
        java.lang.IllegalArgumentException - if the value is not of the given type.

      • expectProperty

        public java.lang.Object expectProperty​(java.lang.String name)
        Gets a specific additional property or throws if missing.
        Parameters:
        name - Property to retrieve.
        Returns:
        Returns the found property.
        Throws:
        java.lang.IllegalArgumentException - if the property is not present.

      • expectProperty

        public <T> T expectProperty​(java.lang.String name,
                            java.lang.Class<T> type)
        Gets a specific additional property or throws if missing or if the property is not an instance of the given type.
        Type Parameters:
        T - Type of value to expect.
        Parameters:
        name - Property to retrieve.
        type - Type of value to expect.
        Returns:
        Returns the found property.
        Throws:
        java.lang.IllegalArgumentException - if the property is not present.
        java.lang.IllegalArgumentException - if the value is not of the given type.

      • expectProperty

        public <T> T expectProperty​(Property<T> property)
        Get a property and throw if it isn't present.
        Type Parameters:
        T - value type of the property.
        Parameters:
        property - property key to get by exact reference identity.
        Throws:
        java.lang.IllegalArgumentException - if the property isn't found.