0
# AWS SDK for Kotlin Core Runtime
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: aws.sdk.kotlin:aws-core-jvm
7
- **Package Type**: maven
8
- **Language**: Kotlin (JVM target)
9
- **Installation**: Add to `build.gradle.kts` dependencies:
10

11
```kotlin
12
implementation("aws.sdk.kotlin:aws-core-jvm:1.5.31")
13
```
14

15
For Gradle Groovy DSL:
16
```groovy
17
implementation 'aws.sdk.kotlin:aws-core-jvm:1.5.31'
18
```
19

20
For Maven:
21
```xml
22
<dependency>
23
    <groupId>aws.sdk.kotlin</groupId>
24
    <artifactId>aws-core-jvm</artifactId>
25
    <version>1.5.31</version>
26
</dependency>
27
```
28

29
## Core Imports
30

31
```kotlin
32
import aws.sdk.kotlin.runtime.AwsServiceException
33
import aws.sdk.kotlin.runtime.ClientException
34
import aws.sdk.kotlin.runtime.ConfigurationException
35
import aws.sdk.kotlin.runtime.client.AwsClientOption
36
```
37

38
## Basic Usage
39

40
```kotlin
41
import aws.sdk.kotlin.runtime.AwsServiceException
42
import aws.sdk.kotlin.runtime.ClientException
43
import aws.sdk.kotlin.runtime.ConfigurationException
44
import aws.sdk.kotlin.runtime.client.AwsClientOption
45

46
// Exception handling
47
try {
48
    // AWS service call
49
} catch (ex: AwsServiceException) {
50
    println("AWS service error: ${ex.message}")
51
    println("Error metadata: ${ex.sdkErrorMetadata}")
52
} catch (ex: ClientException) {
53
    println("Client error: ${ex.message}")
54
} catch (ex: ConfigurationException) {
55
    println("Configuration error: ${ex.message}")
56
}
57

58
// Client options usage
59
val regionKey = AwsClientOption.Region
60
val accountIdKey = AwsClientOption.AccountId
61
```
62

63
## Architecture
64

65
The AWS Core module is built around several key components:
66

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

72
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.
73

74
## Capabilities
75

76
### Exception Classes
77

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

80
```kotlin { .api }
81
/**
82
 * Base class for AWS error metadata
83
 */
84
public open class AwsErrorMetadata : ServiceErrorMetadata()
85

86
/**
87
 * Base class for all AWS modeled service exceptions
88
 */
89
public open class AwsServiceException : SmithyServiceException {
90
    public constructor()
91
    public constructor(message: String?)
92
    public constructor(message: String?, cause: Throwable?)
93
    public constructor(cause: Throwable?)
94
    
95
    override val sdkErrorMetadata: AwsErrorMetadata
96
}
97

98
/**
99
 * Base class for all exceptions originating from the AWS runtime
100
 */
101
public open class ClientException : SmithyClientException {
102
    public constructor()
103
    public constructor(message: String?)
104
    public constructor(message: String?, cause: Throwable?)
105
    public constructor(cause: Throwable?)
106
}
107

108
/**
109
 * Indicates an error with client-side configuration.
110
 */
111
public open class ConfigurationException : ClientException {
112
    public constructor()
113
    public constructor(message: String?)
114
    public constructor(message: String?, cause: Throwable?)
115
    public constructor(cause: Throwable?)
116
}
117
```
118

119
### Client Configuration
120

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

123
```kotlin { .api }
124
/**
125
 * A collection of AWS service client options. NOTE: most options are configured by default through the service
126
 * config
127
 */
128
public object AwsClientOption {
129
    /**
130
     * The AWS region the client should use. Note this is not always the same as [AwsSigningAttributes.SigningRegion] in
131
     * the case of global services like IAM.
132
     *
133
     * NOTE: Synonymous with [aws.smithy.kotlin.runtime.awsprotocol.AwsAttributes.Region]
134
     */
135
    public val Region: AttributeKey<String>
136
    
137
    /**
138
     * The ID of the AWS account requests are routed to.
139
     */
140
    public val AccountId: AttributeKey<String>
141
}
142
```
143

144
### Internal API Annotations
145

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

148
```kotlin { .api }
149
/**
150
 * API marked with this annotation is internal to the client runtime/generated SDK and it is not intended to be used outside.
151
 * It could be modified or removed without any notice. Using it outside of the client-runtime could cause undefined behaviour and/or
152
 * any strange effects.
153
 *
154
 * We strongly recommend to not use such API.
155
 * @suppress
156
 */
157
@Suppress("DEPRECATION")
158
@RequiresOptIn(
159
    level = RequiresOptIn.Level.ERROR,
160
    message = "This API is internal to aws-runtime and generated SDKs and should not be used. It could be removed or changed without notice.",
161
)
162
@Target(
163
    AnnotationTarget.CLASS,
164
    AnnotationTarget.TYPEALIAS,
165
    AnnotationTarget.FUNCTION,
166
    AnnotationTarget.PROPERTY,
167
    AnnotationTarget.FIELD,
168
    AnnotationTarget.CONSTRUCTOR,
169
)
170
public annotation class InternalSdkApi
171
```
172

173
## Types
174

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

177
```kotlin { .api }
178
// Import statements for external types
179
import aws.smithy.kotlin.runtime.ServiceErrorMetadata
180
import aws.smithy.kotlin.runtime.ClientException as SmithyClientException
181
import aws.smithy.kotlin.runtime.ServiceException as SmithyServiceException
182
import aws.smithy.kotlin.runtime.collections.AttributeKey
183

184
// External type definitions
185
interface ServiceErrorMetadata
186
abstract class SmithyServiceException
187
abstract class SmithyClientException
188
class AttributeKey<T>
189
```
190

191
## Error Handling
192

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

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

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