Package software.amazon.smithy.codegen.core

Class SymbolDependency

java.lang.Object
software.amazon.smithy.codegen.core.SymbolDependency
All Implemented Interfaces:
Comparable<SymbolDependency>, SymbolDependencyContainer, ToSmithyBuilder<SymbolDependency>
public final class SymbolDependency extends Object implements SymbolDependencyContainer, ToSmithyBuilder<SymbolDependency>, 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.

  • Method Details

    • builder

      public static SymbolDependency.Builder builder()
      Returns:
      Returns a builder.

    • gatherDependencies

      public static Map<String,Map<String,SymbolDependency>> gatherDependencies(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 Map<String,Map<String,SymbolDependency>> gatherDependencies(Stream<SymbolDependency> symbolStream, 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 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 String getPackageName()
      Gets the package name referenced by the dependency.
      Returns:
      Returns the package name.

    • getVersion

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

    • getDependencies

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

    • toBuilder

      public SymbolDependency.Builder toBuilder()
      Description copied from interface: ToSmithyBuilder
      Take this object and create a builder that contains all of the current property values of this object.
      Specified by:
      toBuilder in interface ToSmithyBuilder<SymbolDependency>
      Returns:
      a builder for type T

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(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 Comparable<SymbolDependency>

    • getProperties

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

    • getProperty

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

    • getProperty

      public <T> Optional<T> getProperty(String name, 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:
      IllegalArgumentException - if the value is not of the given type.

    • expectProperty

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

    • expectProperty

      public <T> T expectProperty(String name, 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:
      IllegalArgumentException - if the property is not present.
      IllegalArgumentException - if the value is not of the given type.