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 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 and Description
static class	Symbol.Builder Builds a Symbol.

Method Summary

Modifier and Type	Method and Description
static Symbol.Builder	builder() Creates a new Symbol builder.
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.
java.lang.String	getDeclarationFile() Gets the location/filename in which the symbol is declared.
java.lang.String	getDefinitionFile() Gets the location/filename in which the symbol is defined.
java.util.List<SymbolDependency>	getDependencies() Gets the list of dependencies that this object introduces.
java.lang.String	getFullName() Gets the full name of the symbol.
java.lang.String	getName() Gets the unqualified name of the symbol, that is, a name without namespace.
java.lang.String	getNamespace() Provides the namespace of the symbol or "" if empty.
java.lang.String	getNamespaceDelimiter() Provides the namespace delimiter of the symbol or "" if empty.
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.
java.util.List<SymbolReference>	getReferences() Gets the list of symbols that are referenced by this symbol.
java.util.List<Symbol>	getSymbols() Returns any Symbol objects contained in the object.
int	hashCode()
java.lang.String	relativize(java.lang.String namespace) Creates a relativized Symbol for the given namespace.
Symbol.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

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.

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.

getSymbols

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