Trabalhando com o AWS CDK em Java

Este é o Guia do Desenvolvedor AWS CDK v2. O CDK v1 antigo 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á.

Este é o Guia do Desenvolvedor AWS CDK v2. O CDK v1 antigo 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á.

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

O 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 AWS CDK aplicativos. Por exemplo, o Java 9 introduz o Map.of() método (uma maneira conveniente de declarar hashmaps que seriam escritos como literais de objeto em). 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 AWS CDK aplicativos. Fornecemos dicas sobre o Eclipse neste guia, mas o IntelliJ IDEA e outros IDEs podem importar projetos Maven e podem ser usados para desenvolver aplicativos em Java. NetBeans AWS CDK

É possível escrever AWS CDK aplicativos 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.

Comece com Java

Para trabalhar com o AWS CDK, você deve ter uma AWS conta e credenciais e ter instalado o Node.js e o AWS CDK Toolkit. Consulte Começando com o AWS CDK.

AWS CDK Os aplicativos Java exigem o Java 8 (v1.8) ou 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 AWS CDK projeto 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).

Gerenciando módulos da AWS Construct Libr

Use o Maven para instalar os pacotes da AWS Construct Library, que estão no gruposoftware.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 ou prefixo da AWS 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 AWS Construct Library 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 AWS CDK pacote principal é importado em código Java comosoftware.amazon.awscdk. Os módulos dos vários serviços na AWS Construct Library estão abaixo 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 import instrução Java separada para cada classe da AWS Construct Library 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 sua aplicação 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 <dependency> elemento a seguir especifica o módulo da biblioteca de construção CodeStar experimental:

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

Gerenciando 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 uma aplicação 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; as aplicações 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.

AWS CDK expressões idiomáticas em Java

Props

Todas as classes da AWS Construct Library são instanciadas usando três argumentos: o escopo no qual a construção está sendo definida (seu pai na árvore de construção), um id e props, um pacote de pares de chave/valor que a construção 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 BucketProps classe (como toda classe de adereços da AWS Construct Library) tem uma classe interna chamadaBuilder. 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 alguns APIs, AWS CDK usa JavaScript matrizes 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.

JavaScript matrizes 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 AWS CDK objetos como adereços são representados pornull. 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 o Apache ObjectUtil firstNonNullútil em algumas situações. defaultIfNull 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 aplicações CDK

O compila AWS CDK automaticamente seu aplicativo antes de executá-lo. No entanto, pode ser útil criar sua aplicação 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.