View a markdown version of this page

Set up a Gradle project that uses the AWS SDK for Java 2.x - AWS SDK for Java 2.x
Enforce consistent SDK module versions

Set up a Gradle project that uses the AWS SDK for Java 2.x

You can use Gradle to set up and build AWS SDK for Java 2.x projects.

The initial steps in the following example come from Gradle's Getting Started guide for version 8.4. If you use a different version, your results may differ slightly.

To create a Java application with Gradle (command line)

  1. Create a directory to hold your project. In this example, demo is the directory name.

  2. Inside the demo directory, execute the gradle init command and supply the values highlighted in red as shown in the following command line output. For the walk through, we choose Kotlin as the build script DSL language, but a complete example for Groovy is also shown at the end of this topic.

    > gradle init
Starting a Gradle Daemon (subsequent builds will be faster)

Select type of project to generate:
1: basic
2: application
3: library
4: Gradle plugin
Enter selection (default: basic) [1..4] 2

Select implementation language:
1: C++
2: Groovy
3: Java
4: Kotlin
5: Scala
6: Swift
Enter selection (default: Java) [1..6] 3

Generate multiple subprojects for application? (default: no) [yes, no] no
Select build script DSL:
1: Kotlin
2: Groovy
Enter selection (default: Kotlin) [1..2] <Enter>

Select test framework:
1: JUnit 4
2: TestNG
3: Spock
4: JUnit Jupiter
Enter selection (default: JUnit Jupiter) [1..4] 4

Project name (default: demo): <Enter>
Source package (default: demo): <Enter>
Enter target version of Java (min. 7) (default: 11): <Enter>
Generate build using new APIs and behavior (some features may change in the next minor release)? (default: no) [yes, no] <Enter>

> Task :init
To learn more about Gradle by exploring our Samples at https://docs.gradle.org/8.4/samples/sample_building_java_applications.html

BUILD SUCCESSFUL in 3m 43s
2 actionable tasks: 2 executed

  3. After the init task completes, the demo directory contains the following tree structure. We take a closer look at the main build file, build.gradle.kts (highlighted in red), in the next section.

    ├── app
│   ├── build.gradle.kts
│   └── src
│       ├── main
│       │   ├── java
│       │   │   └── demo
│       │   │       └── App.java
│       │   └── resources
│       └── test
│           ├── java
│           │   └── demo
│           │       └── AppTest.java
│           └── resources
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
└── settings.gradle.kts

    The build.gradle.kts file contains the following scaffolded content.

    /*
 * This file was generated by the Gradle 'init' task.
 *
 * This generated file contains a sample Java application project to get you started.
 * For more details on building Java & JVM projects, please refer to https://docs.gradle.org/8.4/userguide/building_java_projects.html in the Gradle documentation.
 */

plugins {
    // Apply the application plugin to add support for building a CLI application in Java.
    application
}

repositories {
    // Use Maven Central for resolving dependencies.
    mavenCentral()
}

dependencies {
    // Use JUnit Jupiter for testing.
    testImplementation("org.junit.jupiter:junit-jupiter:5.9.3")

    testRuntimeOnly("org.junit.platform:junit-platform-launcher")

    // This dependency is used by the application.
    implementation("com.google.guava:guava:33.3.0-jre")
}

// Apply a specific Java toolchain to ease working on different environments.
java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(11))
    }
}

application {
    // Define the main class for the application.
    mainClass.set("demo.App")
}

tasks.named<Test>("test") {
    // Use JUnit Platform for unit tests.
    useJUnitPlatform()
}

  4. Use the scaffolded Gradle build file as the basis for your AWS project.

    1. To manage SDK dependencies for your Gradle project, add the Maven bill of materials (BOM) for the AWS SDK for Java 2.x to the dependencies section of the build.gradle.kts file.

      ...
dependencies {
    implementation(platform("software.amazon.awssdk:bom:2.27.21"))
    // With the bom declared, you specify individual SDK dependencies without a version.
 ...
}
...
      Note

      In this example build file, replace 2.27.21 with the latest version of the SDK for Java 2.x. Find the latest version available in Maven central repository.

    2. Specify the SDK modules your application needs in the dependencies section. As an example, the following adds a dependency on Amazon Simple Storage Service. 

      ...
dependencies {    
    implementation(platform("software.amazon.awssdk:bom:2.27.21"))
    implementation("software.amazon.awssdk:s3")
 ...
}
...

      Gradle automatically resolves the correct version of declared dependencies by using the information from the BOM.

The following examples show complete Gradle build files in both the Kotlin and Groovy DSLs. The build file contains dependencies for Amazon S3, authentication, logging, and testing. The source and target version of Java is version 11.

Kotlin DSL (build.gradle.kts)
/*
 * This file was generated by the Gradle 'init' task.
 *
 * This generated file contains a sample Java application project to get you started.
 * For more details on building Java & JVM projects, please refer to https://docs.gradle.org/8.4/userguide/building_java_projects.html in the Gradle documentation.
 */

plugins {
    // Apply the application plugin to add support for building a CLI application in Java.
    application
}

repositories {
    // Use Maven Central for resolving dependencies.
    mavenCentral()
}

dependencies {
    implementation(platform("software.amazon.awssdk:bom:2.20.56"))
    implementation("software.amazon.awssdk:s3")
    implementation("software.amazon.awssdk:sso")
    implementation("software.amazon.awssdk:ssooidc")
    implementation(platform("org.apache.logging.log4j:log4j-bom:2.20.0"))
    implementation("org.apache.logging.log4j:log4j-slf4j2-impl")
    implementation("org.apache.logging.log4j:log4j-1.2-api")
    testImplementation(platform("org.junit:junit-bom:5.10.0"))
    testImplementation("org.junit.jupiter:junit-jupiter")
}

// Apply a specific Java toolchain to ease working on different environments.
java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(11))
    }
}

application {
    // Define the main class for the application.
    mainClass.set("demo.App")
}

tasks.named<Test>("test") {
    // Use JUnit Platform for unit tests.
    useJUnitPlatform()
}
Groovy DSL (build.gradle)
/*
 * This file was generated by the Gradle 'init' task.
 *
 * This generated file contains a sample Java application project to get you started.
 * For more details on building Java & JVM projects, please refer to https://docs.gradle.org/8.4/userguide/building_java_projects.html in the Gradle documentation.
 */

plugins {
    // Apply the application plugin to add support for building a CLI application in Java.
    id 'application'
}

repositories {
    // Use Maven Central for resolving dependencies.
    mavenCentral()
}

dependencies {
    implementation platform('software.amazon.awssdk:bom:2.27.21')
    implementation 'software.amazon.awssdk:s3'
    implementation 'software.amazon.awssdk:sso'
    implementation 'software.amazon.awssdk:ssooidc'
    implementation platform('org.apache.logging.log4j:log4j-bom:2.20.0')
    implementation 'org.apache.logging.log4j:log4j-slf4j2-impl'
    implementation 'org.apache.logging.log4j:log4j-1.2-api'
    testImplementation platform('org.junit:junit-bom:5.10.0')
    testImplementation 'org.junit.jupiter:junit-jupiter'
}

// Apply a specific Java toolchain to ease working on different environments.
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(11)
    }
}

application {
    // Define the main class for the application.
    mainClass = 'demo_groovy.App'
}

tasks.named('test') {
    // Use JUnit Platform for unit tests.
    useJUnitPlatform()
}

For next steps, see the Getting Started guide on the Gradle website for instructions on how to build and run a Gradle application.

Enforce consistent SDK module versions

Important

Use a single AWS SDK for Java 2.x version throughout your Gradle build. If the modules resolve to different versions, your application can throw runtime exceptions or fail to compile, depending on which components differ. For more information, see component version compatibility in the SDK's versioning policy on the GitHub website.

The platform(...) form shown earlier imports the BOM versions as recommendations. During conflict resolution, Gradle selects the highest requested version. As a result, if another part of the dependency graph requests a different software.amazon.awssdk version, that version wins and leaves a mixed set of SDK versions.

To guarantee a single SDK version, use enforcedPlatform(...) instead. This form imports the BOM versions as forced (strict) constraints that override every other version in the graph for software.amazon.awssdk modules. The following examples show the dependencies block for the Kotlin and Groovy DSLs. In the build file you created earlier, replace only the platform("software.amazon.awssdk:bom:...") line with the enforcedPlatform(...) line shown here, so that the build file declares the SDK BOM only once. Leave any other platform(...) declarations, such as those for the Log4j or JUnit BOMs, unchanged. Replace the version number with the latest version of the SDK for Java 2.x.

Kotlin DSL (build.gradle.kts)
dependencies {
    implementation(enforcedPlatform("software.amazon.awssdk:bom:2.27.21"))
    implementation("software.amazon.awssdk:s3")
}
Groovy DSL (build.gradle)
dependencies {
    implementation enforcedPlatform('software.amazon.awssdk:bom:2.27.21')
    implementation 'software.amazon.awssdk:s3'
}
Note

Find the latest version in the Maven Central repository on the Sonatype website.

Important

Because enforcedPlatform(...) applies forced constraints, it can downgrade or override versions across the entire dependency graph, including transitive dependencies, not only the ones you declare. Gradle applies this override without failing the build. If another library in your build requires a newer SDK version than the BOM provides, the downgrade can cause runtime errors such as NoSuchMethodError or NoClassDefFoundError when that library calls an API that the older version does not contain. To resolve this, update the BOM to a version that satisfies every library in your build. The AWS SDK for Java 2.x BOM manages only software.amazon.awssdk artifacts, so this effect applies only to those modules. Prefer enforcedPlatform(...) for final applications. Avoid it in published libraries, because the forced versions leak to downstream consumers.

For more information about diagnosing problems that result from mismatched SDK versions, see Classpath errors.