Package software.amazon.smithy.codegen.core

Class Symbol

  • All Implemented Interfaces:
    SymbolContainer, SymbolDependencyContainer, ToSmithyBuilder<Symbol>
    public final class Symbol
extends java.lang.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"

    • Nested Class Summary

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

    • Method Detail

      • builder

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

      • getNamespace

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

      • getNamespaceDelimiter

        public java.lang.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 java.lang.String getName()
        Gets the unqualified name of the symbol, that is, a name without namespace.
        Returns:
        Returns the name of the symbol.

      • getDeclarationFile

        public java.lang.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 java.lang.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 java.lang.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 java.lang.String relativize​(java.lang.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.

      • toReferencedSymbol

        public Symbol toReferencedSymbol​(java.lang.String alias)
        Converts the symbol to a Symbol that refers to this Symbol using a SymbolReference. This makes it easier to refer to a type using an alias but still through a Symbol to be compatible with SymbolProvider.

        The following example creates a Symbol that is referred to as "__Document" in code, but is an alias of "foo.Document". 

        
 Symbol aliasedSymbol = Symbol.builder()
         .name("Document")
         .namespace("foo", ".")
         .build()
         .toReferenceSymbol("__Document");

        When used with a SymbolWriter, the writer should add an import on "foo.Document" and alias it to "__Document".

        The created symbol uses an empty namespace (""). If this is not compatible with specific ImportContainers to understand that the aliased symbol itself needs no imports, then you can augment the symbol with other metadata by instead using toReferencedSymbolBuilder(String).

        Note that this does not work with every programming language. For example, Java does not support aliasing whereas TypeScript does.

        Parameters:
        alias - Alias to use to refer to the symbol.
        Returns:
        Returns the created Symbol.
        See Also:
        toReferencedSymbolBuilder(String)

      • toReferencedSymbolBuilder

        public Symbol.Builder toReferencedSymbolBuilder​(java.lang.String alias)
        Converts the symbol to a Symbol.Builder that refers to this Symbol using a SymbolReference via an alias. This makes it easier to refer to type using an alias but still use a Symbol to be compatible with SymbolProviders.
        Parameters:
        alias - Alias to use to refer to the symbol.
        Returns:
        Returns a SymbolBuilder that is prepared with the symbol and alias.
        See Also:
        toReferencedSymbol(String)

      • getReferences

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

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

      • 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 java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • equals

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

      • hashCode

        public int hashCode()

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

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