Este é o Guia do Desenvolvedor AWS CDK v2. A CDK v1 mais antiga entrou em manutenção em 1º de junho de 2022 e encerrou o suporte em 1º de junho de 2023.

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Trabalhar com o AWS CDK no Java

Java é uma linguagem de cliente totalmente compatível com AWS CDK e considerada estável. Você pode desenvolver aplicativos AWS CDK em Java usando ferramentas familiares, incluindo o JDK (da Oracle ou uma distribuição do OpenJDK, como o Amazon Corretto) e o Apache Maven.

AWS CDK suporta Java 8 e versões posteriores. No entanto, recomendamos usar a versão mais recente possível, pois as versões posteriores da linguagem incluem melhorias que são particularmente convenientes para o desenvolvimento de aplicativos AWS CDK. Por exemplo, o Java 9 introduz o método Map.of() (uma maneira conveniente de declarar hashmaps que seriam escritos como literais de objeto no TypeScript). O Java 10 introduz a inferência de tipos locais usando a palavra-chave var.

Você pode usar qualquer editor de texto ou um IDE Java que possa ler projetos Maven para trabalhar em seus aplicativos AWS CDK. Fornecemos dicas sobre o Eclipse neste Guia, mas o IntelliJ IDEA, o NetBeans e outros IDEs podem importar projetos Maven e podem ser usados para desenvolver aplicativos AWS CDK em Java.

É possível escrever aplicativos AWS CDK em linguagens hospedadas pela JVM que não sejam Java (por exemplo, Kotlin, Groovy, Clojure ou Scala), mas a experiência pode não ser particularmente idiomática e não podemos fornecer suporte para essas linguagens.

Conceitos básicos do Java

Para trabalhar com AWS CDK, você deve ter uma conta e credenciais da AWS e ter instalado o Node.js e o Toolkit AWS CDK. Consulte Conceitos básicos da AWS CDK.

Os aplicativos AWS CDK Java exigem o Java 8 (v1.8) ou versão posterior. Recomendamos o Amazon Corretto, mas você pode usar qualquer distribuição do OpenJDK ou o JDK da Oracle. Você também precisará do Apache Maven 3.5 ou versão posterior. Você também pode usar ferramentas como o Gradle, mas os esqueletos de aplicativos gerados pelo AWS CDK Toolkit são projetos Maven.

Criação de um projeto

Você cria um novo projeto do AWS CDK invocando cdk init em um diretório vazio. Use a opção --language e especifique java:

mkdir my-project
cd my-project
cdk init app --language java

cdk init usa o nome da pasta do projeto para nomear vários elementos do projeto, incluindo classes, subpastas e arquivos. Hifens no nome da pasta são convertidos em sublinhados. No entanto, o nome deve seguir a forma de um identificador de Java; por exemplo, não deve começar com um número nem conter espaços.

O projeto resultante inclui uma referência ao pacote Maven do software.amazon.awscdk. Ele e suas dependências são instalados automaticamente pelo Maven.

Se você estiver usando um IDE, agora pode abrir ou importar o projeto. No Eclipse, por exemplo, escolha Arquivo > Importar > Maven > Projetos existentes do Maven. Certifique-se de que as configurações do projeto estejam definidas para usar o Java 8 (1.8).

Gerenciamento de módulos da Biblioteca de Constructos da AWS

Use o Maven para instalar os pacotes da Biblioteca de Constructos da AWS, que estão no grupo software.amazon.awscdk. A maioria dos constructo está no artefato aws-cdk-lib, que é adicionado aos novos projetos Java por padrão. Os módulos para serviços cujo suporte de CDK de alto nível ainda está sendo desenvolvido estão em pacotes “experimentais” separados, nomeados com uma versão curta (sem AWS ou prefixo da Amazon) do nome do serviço. Pesquise no Repositório Central do Maven para encontrar os nomes de todas as bibliotecas AWS CDK e do AWS Construct Module.

O suporte da Biblioteca de Constructos da AWS de alguns serviços está em mais de um namespace. Por exemplo, o Amazon Route 53 tem sua funcionalidade dividida em software.amazon.awscdk.route53, route53-patterns, route53resolver e route53-targets.

O pacote AWS CDK principal é importado em código Java como software.amazon.awscdk. Os módulos dos vários serviços na Biblioteca de Constructos da AWS estão em software.amazon.awscdk.services e são nomeados de forma semelhante ao nome do pacote Maven. Por exemplo, o namespace do módulo Amazon S3 é software.amazon.awscdk.services.s3.

Recomendamos escrever uma instrução import Java separada para cada classe da Biblioteca de Constructos da AWS usada em cada um dos seus arquivos de origem Java e evitar importações de caracteres curinga. Você sempre pode usar o nome totalmente qualificado de um tipo (incluindo seu namespace) sem uma declaração import.

Se seu aplicativo depender de um pacote experimental, edite o pom.xml do seu projeto <dependency> e adicione um novo elemento <dependencies> no contêiner . Por exemplo, o elemento <dependency> a seguir especifica o módulo da biblioteca de constructo experimental CodeStar:

<dependency>
    <groupId>software.amazon.awscdk</groupId>
    <artifactId>codestar-alpha</artifactId>
    <version>2.0.0-alpha.10</version>
</dependency>

Gerenciamento de dependências em Java

Em Java, as dependências são especificadas em pom.xml e instaladas usando o Maven. O contêiner <dependencies> inclui um elemento <dependency> para cada pacote. A seguir está uma seção pom.xml para um aplicativo Java típico do CDK.

<dependencies>
    <dependency>
        <groupId>software.amazon.awscdk</groupId>
        <artifactId>aws-cdk-lib</artifactId>
        <version>2.14.0</version>
    </dependency>
    <dependency>
        <groupId>software.amazon.awscdk</groupId>
        <artifactId>appsync-alpha</artifactId>
        <version>2.10.0-alpha.0</version>
    </dependency>
</dependencies>

O Maven não oferece suporte ao bloqueio de dependências. Embora seja possível especificar intervalos de versões em pom.xml, recomendamos que você sempre use versões exatas para manter suas compilações repetíveis.

O Maven instala automaticamente dependências transitivas, mas só pode haver uma cópia instalada de cada pacote. A versão mais alta especificada na árvore POM é selecionada; os aplicativos sempre têm a última palavra em qual versão dos pacotes serão instalados.

O Maven instala ou atualiza automaticamente suas dependências sempre que você constrói (mvn compile) ou empacota (mvn package) seu projeto. O CDK Toolkit faz isso automaticamente toda vez que você o executa, então geralmente não há necessidade de invocar manualmente o Maven.

Expressões idiomáticas AWS CDK em Java

Props

Todas as classes da Biblioteca de Constructos da AWS são instanciadas usando três argumentos: o escopo no qual o constructo está sendo definido (seu pai na árvore de constructos), um id e props, um pacote de pares de chave/valor que o constructo usa para configurar os recursos que cria. Outras classes e métodos também usam o padrão “pacote de atributos” para argumentos.

Em Java, os props são expressos usando o padrão Builder. Cada tipo de constructo tem um tipo de props correspondente; por exemplo, o constructo Bucket (que representa um bucket do Amazon S3) usa como props uma instância de BucketProps.

A classe BucketProps (como toda classe de props da Biblioteca de Constructos da AWS) tem uma classe interna chamada Builder. O tipo BucketProps.Builder oferece métodos para definir as várias propriedades de uma instância BucketProps. Cada método retorna a instância Builder, para que as chamadas do método possam ser encadeadas para definir várias propriedades. No final da cadeia, você liga build() para realmente produzir o objeto BucketProps.

Bucket bucket = new Bucket(this, "amzn-s3-demo-bucket", new BucketProps.Builder()
                           .versioned(true)
                           .encryption(BucketEncryption.KMS_MANAGED)
                           .build());

Constructos e outras classes que usam um objeto semelhante a props como argumento final oferecem um atalho. A classe tem uma Builder própria que instancia ela e seu objeto de props em uma única etapa. Dessa forma, você não precisa instanciar explicitamente (por exemplo) BucketProps e Bucket — e não precisa de uma importação para o tipo props.

Bucket bucket = Bucket.Builder.create(this, "amzn-s3-demo-bucket")
                           .versioned(true)
                           .encryption(BucketEncryption.KMS_MANAGED)
                           .build();

Ao derivar seu próprio constructo de um constructo existente, talvez você queira aceitar propriedades adicionais. Recomendamos que você siga esses padrões do construtor. No entanto, isso não é tão simples quanto criar uma subclasse de uma classe de constructo. Você mesmo deve fornecer as partes móveis das duas novas classes Builder. Você pode preferir simplesmente que seu constructo aceite um ou mais argumentos adicionais. Você deve fornecer construtores adicionais quando um argumento for opcional.

Estruturas genéricas

Em algumas APIs, AWS CDK usa matrizes de JavaScript ou objetos não digitados como entrada para um método. (Veja, por exemplo, o método BuildSpec.fromObject() de AWS CodeBuild.) Em Java, esses objetos são representados como java.util.Map<String, Object>. Nos casos em que os valores são todos cadeias de caracteres, você pode usar Map<String, String>.

O Java não fornece uma maneira de escrever literais para esses contêineres, como fazem algumas outras linguagens. No Java 9 e versões posteriores, você pode usar java.util.Map.of() para definir convenientemente mapas de até dez entradas em linha com uma dessas chamadas.

java.util.Map.of(
    "base-directory", "dist",
    "files", "LambdaStack.template.json"
 )

Para criar mapas com mais de dez entradas, use java.util.Map.ofEntries().

Se você estiver usando o Java 8, poderá fornecer seus próprios métodos semelhantes a esses.

As matrizes de JavaScript são representadas como List<Object> ou List<String> em Java. O método java.util.Arrays.asList é conveniente para definir List curtos.

List<String> cmds = Arrays.asList("cd lambda", "npm install", "npm install typescript")

Valores ausentes

Em Java, valores ausentes em objetos AWS CDK como props são representados por null. Você deve testar explicitamente qualquer valor que possa ser null para garantir que contenha um valor antes de fazer qualquer coisa com ele. Java não dispõe de “açúcar sintático” para lidar com valores nulos, como algumas outras linguagens fazem. Você pode achar que defaultIfNull e firstNonNull do Apache ObjectUtil são úteis em algumas situações. Como alternativa, escreva seus próprios métodos auxiliares estáticos para facilitar o tratamento de valores potencialmente nulos e tornar seu código mais legível.

Compilação e execução de aplicativos CDK

AWS CDK compila automaticamente seu aplicativo antes de executá-lo. No entanto, pode ser útil criar seu aplicativo manualmente para verificar erros e executar testes. Você pode fazer isso em seu IDE (por exemplo, pressione Control-B no Eclipse) ou emitindo mvn compile em um prompt de comando enquanto estiver no diretório raiz do seu projeto.

Execute todos os testes que você escreveu executando mvn test em um prompt de comando.