Package software.amazon.smithy.codegen.core

Class Symbol

java.lang.Object
software.amazon.smithy.codegen.core.Symbol
All Implemented Interfaces:
SymbolContainer, SymbolDependencyContainer, ToSmithyBuilder<Symbol>
public final class Symbol extends Object implements SymbolContainer, SymbolDependencyContainer, ToSmithyBuilder<Symbol>
A "symbol" is created by a SymbolProvider, and represents the qualified name of a type in a target programming language.

A symbol contains an optional namespace, optional namespace delimiter, name, a map of additional properties, a declaration file the determines where the symbol is declared, and a definition file that determines where a symbol is defined.

A namespace can be used when the target language supports namespaces. The provided namespace can be in whatever format is useful to the target language. A namespace delimiter is injected between the namespace and the name when creating the fully-qualified symbol name. The "name" is the unqualified name of the symbol (e.g., "str", or "MyShape").

Additional properties can be included when it's useful to provide more information about a symbol. For example, it might be useful to identify the name of a dependency that needs to be pulled in through a package manager when a symbol is used.

The following example shows how a Java type could be made into a symbol: 

 
 Class<Symbol> klass = Symbol.class;
 Symbol symbol = Symbol.builder()
         .namespace(klass.getPackage().toString(), ".")
         .name(klass.getSimpleName())
         .build();
 System.out.println(symbol);
 // ^ outputs "software.amazon.smithy.codegen.Symbol"
 System.out.println(symbol.relativize("software.amazon.smithy.codegen");
 // ^ outputs "Symbol"

  • Method Details

    • builder

      public static Symbol.Builder builder()
      Creates a new Symbol builder.
      Returns:
      Returns the created symbol builder.

    • getNamespace

      public String getNamespace()
      Provides the namespace of the symbol or "" if empty.
      Returns:
      Returns the optional namespace.

    • getNamespaceDelimiter

      public String getNamespaceDelimiter()
      Provides the namespace delimiter of the symbol or "" if empty.

      This delimiter is injected between the namespace and name when creating the full name.

      Returns:
      Returns the optional namespace.

    • getName

      public String getName()
      Gets the unqualified name of the symbol, that is, a name without namespace.
      Returns:
      Returns the name of the symbol.

    • getDeclarationFile

      public String getDeclarationFile()
      Gets the location/filename in which the symbol is declared.

      Code generators should write the generated code for this symbol's declaration in a file with the same name that is returned from this method. Not all languages separate a symbol's definition from its declaration. This method is useful for things like C and C++ header files.

      This method returns an empty string if no value was provided in the builder.

      Returns:
      The name of the file the symbol is declared.

    • getDefinitionFile

      public String getDefinitionFile()
      Gets the location/filename in which the symbol is defined.

      Code generators should write the generated code for a symbol in a file with the same name that is returned from this method.

      This method returns an empty string if no value was provided for either the declaration file or the definition file.

      Returns:
      The name of the file the symbol is defined.

    • getFullName

      public String getFullName()
      Gets the full name of the symbol.

      The full name is the concatenation of the namespace, the namespace delimiter, and the name.

      Returns:
      Returns the fully qualified name of the symbol.

    • relativize

      public String relativize(String namespace)
      Creates a relativized Symbol for the given namespace.

      If this symbol is in the same namespace as the provided namespace, then only the symbol name is returned. Otherwise, the fully-qualified symbol is returned.

      Parameters:
      namespace - Namespace to relativize against.
      Returns:
      Returns the relativized symbol.

    • getReferences

      public List<SymbolReference> getReferences()
      Gets the list of symbols that are referenced by this symbol.
      Returns:
      Returns the Symbol references.

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

    • getSymbols

      public List<Symbol> getSymbols()
      Description copied from interface: SymbolContainer
      Returns any Symbol objects contained in the object.
      Specified by:
      getSymbols in interface SymbolContainer
      Returns:
      Returns a collection of Symbols.

    • toBuilder

      public Symbol.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<Symbol>
      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()

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