software.amazon.smithy.model.traits

Interface Trait

All Superinterfaces:

FromSourceLocation, ToNode, ToShapeId

All Known Implementing Classes:

AbstractTrait, ActionPermissionDescriptionTrait, AnnotationTrait, ApiKeySourceTrait, ArnReferenceTrait, ArnTrait, AuthDefinitionTrait, AuthorizersTrait, AuthorizerTrait, AuthTrait, AwsJson1_0Trait, AwsJson1_1Trait, AwsProtocolTrait, AwsQueryErrorTrait, AwsQueryTrait, BoxTrait, CfnAdditionalIdentifierTrait, CfnExcludePropertyTrait, CfnMutabilityTrait, CfnNameTrait, CfnResourceTrait, ClientDiscoveredEndpointTrait, ClientEndpointDiscoveryIdTrait, ClientEndpointDiscoveryTrait, CognitoUserPoolsTrait, ConditionKeysTrait, ControlPlaneTrait, CorsTrait, DataPlaneTrait, DataTrait, DefineConditionKeysTrait, DeprecatedTrait, DisableConditionKeyInferenceTrait, DocumentationTrait, DynamicTrait, Ec2QueryNameTrait, Ec2QueryTrait, EndpointTrait, EnumTrait, ErrorTrait, EventHeaderTrait, EventPayloadTrait, ExamplesTrait, ExternalDocumentationTrait, HostLabelTrait, HttpApiKeyAuthTrait, HttpBasicAuthTrait, HttpBearerAuthTrait, HttpChecksumRequiredTrait, HttpChecksumTrait, HttpDigestAuthTrait, HttpErrorTrait, HttpHeaderTrait, HttpLabelTrait, HttpMalformedRequestTestsTrait, HttpPayloadTrait, HttpPrefixHeadersTrait, HttpQueryParamsTrait, HttpQueryTrait, HttpRequestTestsTrait, HttpResponseCodeTrait, HttpResponseTestsTrait, HttpTrait, IamResourceTrait, IdempotencyTokenTrait, IdempotentTrait, IdRefTrait, InputTrait, IntegrationTrait, InternalTrait, JsonNameTrait, LengthTrait, MediaTypeTrait, MockIntegrationTrait, MqttJsonTrait, NoReplaceTrait, OptionalAuthTrait, OriginalShapeIdTrait, OutputTrait, PaginatedTrait, PatternTrait, PrivateTrait, ProtocolDefinitionTrait, PublishTrait, RangeTrait, ReadonlyTrait, RecommendedTrait, ReferencesTrait, RequestValidatorTrait, RequiredActionsTrait, RequiredTrait, RequiresLengthTrait, ResourceIdentifierTrait, RestJson1Trait, RestXmlTrait, RetryableTrait, S3UnwrappedXmlOutputTrait, SensitiveTrait, ServiceTrait, SigV4Trait, SinceTrait, SparseTrait, StreamingTrait, StringListTrait, StringTrait, SubscribeTrait, SupportedPrincipalTypesTrait, SuppressTrait, TagsTrait, TimestampFormatTrait, TitleTrait, TopicLabelTrait, TraitDefinition, UniqueItemsTrait, UnitTypeTrait, UnsignedPayloadTrait, UnstableTrait, WaitableTrait, XmlAttributeTrait, XmlFlattenedTrait, XmlNamespaceTrait, XmlNameTrait

public interface Trait
extends FromSourceLocation, ToNode, ToShapeId

Traits provide additional context and semantics to shapes.

A trait complements a Shape by providing additional information to help correctly interpret any specific representation of it or to add information about constraints on the logical structure of the Shape. For example, one Trait object might reflect details about how a Shape is bound to JSON while another might reflect details about how that same Shape is bound to Ion.

Traits are discovered through Java SPI using the TraitService interface. All traits that are defined in a Smithy MUST provide a TraitService in order for the concrete trait type to be created for the trait in code. Otherwise, the trait is created as a DynamicTrait.

Traits may perform as much validation in their constructor; any exception thrown while creating a trait when assembling a model will automatically include the name of the trait in the thrown exception message. Any validation that requires more context than is provided to the trait constructor should be performed by implementing a Validator class for the trait that is automatically registered each time the model is validated by implementing the Validator interface and registering the validator through SPI.

Method Summary

Modifier and Type	Method and Description
static <S extends Shape,T extends Trait> java.util.stream.Stream<Pair<S,T>>	flatMapStream(S shape, java.lang.Class<T> traitClass) Deprecated.
static java.lang.String	getIdiomaticTraitName(java.lang.String traitName) Gets the idiomatic name of a prelude trait by stripping off the smithy.api# prefix.
static java.lang.String	getIdiomaticTraitName(ToShapeId id) Gets the idiomatic name of a prelude trait by stripping off the smithy.api# prefix.
default boolean	isSynthetic() Checks if this trait is persisted with the shape, or if it is a synthetic, or transient trait, only meant to temporarily aid in some kind of in-memory model transformation.
static java.lang.String	makeAbsoluteName(java.lang.String traitName) Makes the given trait name absolute if it is relative.
static java.lang.String	makeAbsoluteName(java.lang.String traitName, java.lang.String defaultNamespace) Makes the given trait name absolute if it is relative.
ShapeId	toShapeId() Gets the shape ID of the trait.

Methods inherited from interface software.amazon.smithy.model.FromSourceLocation

getSourceLocation

Methods inherited from interface software.amazon.smithy.model.node.ToNode

toNode

Method Detail

toShapeId

ShapeId toShapeId()

Gets the shape ID of the trait.

Specified by:

toShapeId in interface ToShapeId

Returns:

Returns the fully-qualified shape ID of the trait.

isSynthetic

default boolean isSynthetic()

Checks if this trait is persisted with the shape, or if it is a synthetic, or transient trait, only meant to temporarily aid in some kind of in-memory model transformation.

Because synthetic traits are not persisted with shapes, they also do not need to be defined in Smithy's semantic model before they can be used in the model.

Returns:

Returns true if the trait is not persisted on the shape.

flatMapStream

@Deprecated
static <S extends Shape,T extends Trait> java.util.stream.Stream<Pair<S,T>> flatMapStream(S shape,
                                                                                                      java.lang.Class<T> traitClass)

Deprecated.

Used in a stream flatMapStream to return a Stream with a Pair of Shape and Trait if the trait is present on the given shape.

This method is deprecated because it generally results in harder to read code using unnamed tuples. Use Shape.hasTrait(Class) and Shape.expectTrait(Class) instead.

Type Parameters:

S - Shape

T - Trait

Parameters:

shape - Shape to query for the trait.

traitClass - Trait to retrieve.

Returns:

Returns the Stream of the found trait or an empty stream.

getIdiomaticTraitName

static java.lang.String getIdiomaticTraitName(java.lang.String traitName)

Gets the idiomatic name of a prelude trait by stripping off the smithy.api# prefix. This is used in various error messages.

Parameters:

traitName - Trait name to make idiomatic.

Returns:

Returns the idiomatic trait name.

getIdiomaticTraitName

static java.lang.String getIdiomaticTraitName(ToShapeId id)

Gets the idiomatic name of a prelude trait by stripping off the smithy.api# prefix. This is used in various error messages.

Parameters:

id - Trait name to make idiomatic.

Returns:

Returns the idiomatic trait name.

makeAbsoluteName

static java.lang.String makeAbsoluteName(java.lang.String traitName)

Makes the given trait name absolute if it is relative.

The namespace used to resolve with the trait name is the prelude namespace, smithy.api.

Parameters:

traitName - Trait name to make absolute.

Returns:

Returns the absolute trait name.

makeAbsoluteName

static java.lang.String makeAbsoluteName(java.lang.String traitName,
                                         java.lang.String defaultNamespace)

Makes the given trait name absolute if it is relative.

Parameters:

traitName - Trait name to make absolute.

defaultNamespace - Namespace to use if the name is relative.

Returns:

Returns the absolute trait name.