Package software.amazon.smithy.model.traits

Interface Trait

All Superinterfaces:
FromSourceLocation, ToNode, ToShapeId
All Known Implementing Classes:
AbstractTrait, ActionNameTrait, ActionPermissionDescriptionTrait, AddedDefaultTrait, AnnotationTrait, ApiKeySourceTrait, ArnReferenceTrait, ArnTrait, AuthDefinitionTrait, AuthorizersTrait, AuthorizerTrait, AuthTrait, AwsJson1_0Trait, AwsJson1_1Trait, AwsProtocolTrait, AwsQueryCompatibleTrait, AwsQueryErrorTrait, AwsQueryTrait, BoxTrait, CfnAdditionalIdentifierTrait, CfnDefaultValueTrait, CfnExcludePropertyTrait, CfnMutabilityTrait, CfnNameTrait, CfnResourceTrait, ClientContextParamsTrait, ClientDiscoveredEndpointTrait, ClientEndpointDiscoveryIdTrait, ClientEndpointDiscoveryTrait, ClientOptionalTrait, CognitoUserPoolsTrait, ConditionKeysTrait, ConditionKeyValueTrait, ContextParamTrait, ControlPlaneTrait, CorsTrait, DataPlaneTrait, DataTrait, DefaultTrait, DefineConditionKeysTrait, DeprecatedTrait, DisableConditionKeyInferenceTrait, DocumentationTrait, DualStackOnlyEndpointsTrait, DynamicTrait, Ec2QueryNameTrait, Ec2QueryTrait, EndpointModifierTrait, EndpointRuleSetTrait, EndpointTestsTrait, EndpointTrait, EnumTrait, EnumValueTrait, ErrorTrait, EventHeaderTrait, EventPayloadTrait, ExamplesTrait, ExternalDocumentationTrait, HostLabelTrait, HttpApiKeyAuthTrait, HttpBasicAuthTrait, HttpBearerAuthTrait, HttpChecksumRequiredTrait, HttpChecksumTrait, HttpDigestAuthTrait, HttpErrorTrait, HttpHeaderTrait, HttpLabelTrait, HttpMalformedRequestTestsTrait, HttpPayloadTrait, HttpPrefixHeadersTrait, HttpQueryParamsTrait, HttpQueryTrait, HttpRequestTestsTrait, HttpResponseCodeTrait, HttpResponseTestsTrait, HttpTrait, IamActionTrait, IamResourceTrait, IdempotencyTokenTrait, IdempotentTrait, IdRefTrait, InputTrait, IntegrationTrait, InternalTrait, JsonNameTrait, LengthTrait, MediaTypeTrait, MixinTrait, MockIntegrationTrait, MqttJsonTrait, NestedPropertiesTrait, NoAuthTrait, NoReplaceTrait, NotPropertyTrait, OptionalAuthTrait, OriginalShapeIdTrait, OutputTrait, PaginatedTrait, PatternTrait, PrivateTrait, PropertyTrait, ProtocolDefinitionTrait, PublishTrait, RangeTrait, ReadonlyTrait, RecommendedTrait, ReferencesTrait, RequestCompressionTrait, RequestValidatorTrait, RequiredActionsTrait, RequiredTrait, RequiresLengthTrait, ResourceIdentifierTrait, RestJson1Trait, RestXmlTrait, RetryableTrait, RuleBasedEndpointsTrait, S3UnwrappedXmlOutputTrait, SensitiveTrait, ServiceResolvedConditionKeysTrait, ServiceTrait, SigV4ATrait, SigV4Trait, SinceTrait, SmokeTestsTrait, SparseTrait, SpecificationExtensionTrait, StandardPartitionalEndpointsTrait, StandardRegionalEndpointsTrait, StaticContextParamsTrait, StreamingTrait, StringListTrait, StringTrait, SubscribeTrait, SupportedPrincipalTypesTrait, SuppressTrait, SyntheticEnumTrait, TagEnabledTrait, TaggableTrait, TagsTrait, TimestampFormatTrait, TitleTrait, TopicLabelTrait, TraitDefinition, TraitValidatorsTrait, 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 Details

    • 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> Stream<Pair<S,T>> flatMapStream(S shape, 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 String getIdiomaticTraitName(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 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 String makeAbsoluteName(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 String makeAbsoluteName(String traitName, 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.