Kotlin code example standards

Kotlin SDK Standards Document

This document summarizes important points for writing and reviewing code examples written for the AWS SDK for Kotlin. For more information on tools and standards, see the complete list in TCX Code Examples Standards.

General Structure

Service folders with examples should follow the common structure that uses folders for Actions, Scenarios, and Tests, with a top level Gradle build file.

Code examples that use a Kotlin client should follow the Client Builder Pattern, which is a common design pattern used with Kotlin. In addition, the method that uses the Kotlin client has to be a suspend function that adheres to Kotlin coroutine functionality.

suspend fun getRepositoryURI(repoName: String?): String? {
        require(!(repoName == null || repoName.isEmpty())) { "Repository name cannot be null or empty" }
        val request =
            DescribeRepositoriesRequest {
                repositoryNames = listOf(repoName)
            }

        EcrClient { region = "us-east-1" }.use { ecrClient ->
            val describeRepositoriesResponse = ecrClient.describeRepositories(request)
            if (!describeRepositoriesResponse.repositories?.isEmpty()!!) {
                return describeRepositoriesResponse?.repositories?.get(0)?.repositoryUri
            } else {
                println("No repositories found for the given name.")
                return ""
            }
        }
    }

Examples should use JDK 17+ and string interpolation ($repoName).

val instructions = """
1. Authenticate with ECR - Before you can pull the image from Amazon ECR, you need to authenticate with the registry. You can do this using the AWS CLI:

    aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin $accountId.dkr.ecr.us-east-1.amazonaws.com

2. Describe the image using this command:

   aws ecr describe-images --repository-name $repoName --image-ids imageTag=$localImageName

3. Run the Docker container and view the output using this command:

   docker run --rm $accountId.dkr.ecr.us-east-1.amazonaws.com/$repoName:$localImageName
"""

Methods should provide JavaDoc details that provides a summary, parameter, and return type below the snippet tag.

/**
 * Retrieves the repository URI for the specified repository name.
 *
 * @param repoName the name of the repository to retrieve the URI for.
 * @return the repository URI for the specified repository name.
 */
suspend fun getRepositoryURI(repoName: String?): String? {

When a service is added or updated, update the Kotlin Github repo so it will be included in the build/lint/format and Weathertop tests.

New scenarios should have two classes. One class that uses main() controls the flow of the program. The other class, which is the Action class contains Kotlin SDK method calls.

You can create Request objects separately for service method calls.

Use parameterized values for any AWS database query operations. (See the Redshift scenario as an example).

Import statements should not include any unused imports, wildcards, and be ordered alphabetically.

All Kotlin code examples should be lintered using ktlint 12.1.1 (or higher).

Tests must use @TestInstance and @TestMethodOrder JUNT annotations.

@TestInstance(TestInstance.Lifecycle.PER_CLASS)
@TestMethodOrder(MethodOrderer.OrderAnnotation::class)
class ECRTest {

Integration tests should be marked with @Order(1) for ordering tests and use runBlocking{}.

   @Test
    @Tag("IntegrationTest")
    @Order(2)
    fun testHello() =
        runBlocking {
            listImageTags(repoName)
            println("Test 2 passed")
        }

Use Gradle for dependency management.

Recommend keeping dependencies up-to-date and following best practices for dependency management. That is, every 3-4 months - update the Kotlin SDK build.

Metadata for Action examples should contain at minimum the following snippets.

• A snippet to show the action itself within context.
• If more than one variation of the Action is included, use descriptions in the metadata to explain the differences.

Metadata for scenario examples should contain the Action class and Scenario that contains the main() that contains the ouptu of the program.