or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/maven-aws-sdk-kotlin--aws-core-jvm

AWS client runtime core providing shared types and logic needed by other AWS SDK for Kotlin modules

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/aws.sdk.kotlin/aws-core-jvm@1.5.x

To install, run

npx @tessl/cli install tessl/maven-aws-sdk-kotlin--aws-core-jvm@1.5.0

index.mddocs/

AWS SDK for Kotlin Core Runtime

AWS client runtime core providing the shared types and logic needed by other AWS SDK for Kotlin modules. This foundational library includes essential exception classes, annotations, and client configuration options required for building AWS service clients.

Package Information

  • Package Name: aws.sdk.kotlin:aws-core-jvm
  • Package Type: maven
  • Language: Kotlin (JVM target)
  • Installation: Add to build.gradle.kts dependencies:
implementation("aws.sdk.kotlin:aws-core-jvm:1.5.31")

For Gradle Groovy DSL:

implementation 'aws.sdk.kotlin:aws-core-jvm:1.5.31'

For Maven:

<dependency>
    <groupId>aws.sdk.kotlin</groupId>
    <artifactId>aws-core-jvm</artifactId>
    <version>1.5.31</version>
</dependency>

Core Imports

import aws.sdk.kotlin.runtime.AwsServiceException
import aws.sdk.kotlin.runtime.ClientException
import aws.sdk.kotlin.runtime.ConfigurationException
import aws.sdk.kotlin.runtime.client.AwsClientOption

Basic Usage

import aws.sdk.kotlin.runtime.AwsServiceException
import aws.sdk.kotlin.runtime.ClientException
import aws.sdk.kotlin.runtime.ConfigurationException
import aws.sdk.kotlin.runtime.client.AwsClientOption

// Exception handling
try {
    // AWS service call
} catch (ex: AwsServiceException) {
    println("AWS service error: ${ex.message}")
    println("Error metadata: ${ex.sdkErrorMetadata}")
} catch (ex: ClientException) {
    println("Client error: ${ex.message}")
} catch (ex: ConfigurationException) {
    println("Configuration error: ${ex.message}")
}

// Client options usage
val regionKey = AwsClientOption.Region
val accountIdKey = AwsClientOption.AccountId

Architecture

The AWS Core module is built around several key components:

  • Exception Hierarchy: Structured exception classes for different error types (service errors, client errors, configuration errors)
  • Client Options: Standardized attribute keys for configuring AWS clients (region, account ID)
  • Internal APIs: Annotation system for marking internal SDK APIs that shouldn't be used externally
  • Error Metadata: AWS-specific error metadata extending Smithy's error handling system

This module serves as the foundation for all other AWS SDK for Kotlin modules, providing consistent error handling patterns and client configuration options across all AWS services.

Capabilities

Exception Classes

Core exception hierarchy for AWS SDK error handling, providing structured error types for different failure scenarios.

/**
 * Base class for AWS error metadata
 */
public open class AwsErrorMetadata : ServiceErrorMetadata()

/**
 * Base class for all AWS modeled service exceptions
 */
public open class AwsServiceException : SmithyServiceException {
    public constructor()
    public constructor(message: String?)
    public constructor(message: String?, cause: Throwable?)
    public constructor(cause: Throwable?)
    
    override val sdkErrorMetadata: AwsErrorMetadata
}

/**
 * Base class for all exceptions originating from the AWS runtime
 */
public open class ClientException : SmithyClientException {
    public constructor()
    public constructor(message: String?)
    public constructor(message: String?, cause: Throwable?)
    public constructor(cause: Throwable?)
}

/**
 * Indicates an error with client-side configuration.
 */
public open class ConfigurationException : ClientException {
    public constructor()
    public constructor(message: String?)
    public constructor(message: String?, cause: Throwable?)
    public constructor(cause: Throwable?)
}

Client Configuration

Standardized client options for AWS service configuration including region and account ID settings.

/**
 * A collection of AWS service client options. NOTE: most options are configured by default through the service
 * config
 */
public object AwsClientOption {
    /**
     * The AWS region the client should use. Note this is not always the same as [AwsSigningAttributes.SigningRegion] in
     * the case of global services like IAM.
     *
     * NOTE: Synonymous with [aws.smithy.kotlin.runtime.awsprotocol.AwsAttributes.Region]
     */
    public val Region: AttributeKey<String>
    
    /**
     * The ID of the AWS account requests are routed to.
     */
    public val AccountId: AttributeKey<String>
}

Internal API Annotations

Annotation system for marking internal SDK APIs that should not be used outside the AWS SDK.

/**
 * API marked with this annotation is internal to the client runtime/generated SDK and it is not intended to be used outside.
 * It could be modified or removed without any notice. Using it outside of the client-runtime could cause undefined behaviour and/or
 * any strange effects.
 *
 * We strongly recommend to not use such API.
 * @suppress
 */
@Suppress("DEPRECATION")
@RequiresOptIn(
    level = RequiresOptIn.Level.ERROR,
    message = "This API is internal to aws-runtime and generated SDKs and should not be used. It could be removed or changed without notice.",
)
@Target(
    AnnotationTarget.CLASS,
    AnnotationTarget.TYPEALIAS,
    AnnotationTarget.FUNCTION,
    AnnotationTarget.PROPERTY,
    AnnotationTarget.FIELD,
    AnnotationTarget.CONSTRUCTOR,
)
public annotation class InternalSdkApi

Types

The module uses types from the Smithy Kotlin runtime for integration:

// Import statements for external types
import aws.smithy.kotlin.runtime.ServiceErrorMetadata
import aws.smithy.kotlin.runtime.ClientException as SmithyClientException
import aws.smithy.kotlin.runtime.ServiceException as SmithyServiceException
import aws.smithy.kotlin.runtime.collections.AttributeKey

// External type definitions
interface ServiceErrorMetadata
abstract class SmithyServiceException
abstract class SmithyClientException
class AttributeKey<T>

Error Handling

All AWS SDK operations can throw exceptions from this module's hierarchy:

  • AwsServiceException: Thrown for errors returned by AWS services (4xx/5xx HTTP responses)
  • ClientException: Thrown for client-side errors (network issues, serialization problems)
  • ConfigurationException: Thrown for configuration errors (invalid credentials, malformed config)

Each exception provides structured error information through the AwsErrorMetadata system, allowing applications to handle different error scenarios appropriately.