Exercício – Configurar a aplicação Java com o Maven

15 minutos

Nesta unidade, irá criar uma aplicação da consola básica com um IDE à sua escolha para editar código. Opcionalmente, irá utilizar um terminal à sua escolha para executar o código.

Criar recursos do Azure Cosmos DB

Para concluir este laboratório, o Microsoft Learn fornece um sandbox gratuito do Azure no qual pode criar contas e recursos. Vai configurar uma conta do Azure Cosmos DB nesta subscrição e, depois, criar uma base de dados e um contentor.

Inicie sessão no portal do Azure com a mesma conta que utilizou para ativar o sandbox.
Com o portal do Azure, crie uma conta do Azure Cosmos DB com um nome à sua escolha. Quando surgir a oportunidade para escolher um grupo de recursos para a sua conta, localize o grupo de recursos [grupo de recursos do Sandbox] e selecione-o.
Na conta do Azure Cosmos DB, crie uma base de dados denominada Utilizadores.
No banco de dados Usuários, crie um contêiner chamado WebCustomers com uma chave de partição /userId. Aprovisione 400 RU/s para WebCustomers.

Criar o seu diretório de trabalho

Porporcionamos um modelo para a aplicação Java. Clone o repositório do modelo para o sistema.
```
git clone https://github.com/MicrosoftDocs/mslearn-cosmos-java-sql.git
```
Abra o Explorador de Ficheiros do Windows e aceda ao repositório clonado. Introduza o subdiretório java_lab.

Importante

O trabalho deste módulo estará no subdiretório java_lab.
O modelo contém um ficheiro pom.xml do Maven que já solicita as dependências necessárias para o seu projeto. Abra este ficheiro e examine-o para localizar a dependência seguinte:
```
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-cosmos</artifactId>
    <version>4.8.0</version>
</dependency>
```
Esta dependência extrai a versão mais recente do SDK Java do Azure Cosmos DB. Pode fechar este ficheiro.
Em seguida, criará e executará o Hello World. Com o IDE ou o terminal, abra este projeto. Dependendo do IDE, pode haver a opção para abrir o ficheiro pom.xml no subdiretório java como um projeto.

Depois que o projeto estiver aberto, vá para src/main/java/com/azure/cosmos/examples/mslearnbasicapp e abra o CosmosApp.java, que é um modelo para o aplicativo Java que desenvolveremos. Deve ter um aspeto semelhante a:
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public final class CosmosApp {

    /** For application to log INFO and ERROR. */
    private static Logger logger = LoggerFactory.getLogger(CosmosApp.class.getSimpleName());

    private CosmosApp() {
        // not called
    }

    /**
    * Main.
    * @param args Command line arguments
    */
    public static void main(final String[] args) {
        logger.info("Hello World.");
    }
}
```
No estado em que se encontra, o código da aplicação implementa um simples “Hello World”.
Se o IDE oferecer ferramentas para criar e executar seu aplicativo Maven: compile e execute seu aplicativo usando o IDE e confirme se o aplicativo registra Hello World no terminal.
Se você usará o terminal para criar e executar seu aplicativo Maven: Use o seguinte comando para criar o projeto Maven:
```
mvn clean package
```
Em seguida, execute:
```
mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"  
```
Confirme se a aplicação cria um registo da seguinte saída no terminal:
```
INFO: Hello World.
```

Ligar a aplicação ao Azure Cosmos DB

Na classe CosmosApp, crie as seguintes variáveis de classe estática para os seus detalhes da ligação do Azure Cosmos DB:

/** Azure Cosmos DB endpoint URI. */
private static String endpointUri = "<your-cosmosdb-hostname>";

/** Azure Cosmos DB primary key. */
private static String primaryKey = "<your-cosmosdb-master-key>";

Volte ao portal do Azure, aceda ao painel Chaves e copie/cole a chave primária e o URI do ponto final do Azure Cosmos DB nas definições de variáveis anteriores.

Por exemplo, se o URI for https://cosmosacct.documents.azure.com:443/, a atribuição de novas variáveis terá o seguinte aspeto: private static String endpointUri = "https://cosmosacct.documents.azure.com:443/";. Se a chave primária for elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==, a atribuição de novas variáveis terá o seguinte aspeto: private static String primaryKey = "elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==";.

Criar a instância do CosmosAsyncClient

Agora, é altura de criar uma instância do CosmosAsyncClient, que é a representação do lado do cliente do serviço Azure Cosmos DB. Este cliente é utilizado para configurar e executar pedidos no serviço.

Em CosmosApp.java, adicione a seguinte declaração de variáveis estáticas à classe CosmosApp:
```
/** Azure Cosmos DB client instance. */
private static CosmosAsyncClient client;

/** Azure Cosmos DB database instance. */
private static CosmosAsyncDatabase database;

/** Azure Cosmos DB container instance. */
private static CosmosAsyncContainer container;
```
Muito provavelmente, as classes client, database e container ainda não foram importadas para o ficheiro Java. É uma boa altura para tratar disso. Alguns IDEs podem permitir-lhe importar automaticamente dependências com base no código que escrever, o que pode ser útil aqui. De modo geral, pode esperar que, ao ser-lhe fornecido um bloco de código para colar, tenha de adicionar algumas instruções import para que funcione.
Crie um método private void denominado basicOperations sem argumentos na classe.

Adicione o seguinte código para criar uma instância do CosmosAsyncClient no método basicOperations e inclua código para verificar se a base de dados Utilizadores existe.

 client = new CosmosClientBuilder()
     .endpoint(endpointUri)
     .key(primaryKey)
     .consistencyLevel(ConsistencyLevel.EVENTUAL)
     .directMode()
     .contentResponseOnWriteEnabled(true)
     .buildAsyncClient();

 database = client.getDatabase("Users");
 container = database.getContainer("WebCustomers");            

 logger.info("Database and container validation complete");

 client.close();

Nesta altura, o método basicOperations contém o código para interagir com o Azure Cosmos DB. No entanto, este método não é chamadomain, por isso a nossa aplicação ainda serve para imprimir "Hello World". Como verificação, construa e execute o CosmosApp.java no IDE ou execute o programa no terminal usando:
```
mvn clean package
mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"  
```
Confirme se a aplicação ainda cria um registo da seguinte saída no terminal:
```
INFO: Hello World.
```

Copie e cole o código a seguir no main método, substituindo a linha atual logger.info("Hello World."); .

try {
    CosmosApp p = new CosmosApp();
    p.basicOperations();
} catch (CosmosException e) {
    logger.error("Failed while executing app.", e);
} finally {
    logger.info("End of demo, press any key to exit.");
}

Isto acionará o código do Azure Cosmos DB na nossa aplicação.

Crie e execute CosmosApp.java no IDE ou execute o programa no terminal com:
```
mvn clean package
mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"  
```
Pode ver um grande número de mensagens de registo no terminal, algumas das quais são geradas pelo próprio SDK. Leia e confirme se a aplicação cria um registo da seguinte saída no terminal:
```
INFO: Database and container validation complete
```

Nesta unidade, configurou a base para a sua aplicação Java do Azure Cosmos DB. Configurou a aplicação do Maven, criou um projeto básico "Hello World" e alargou-o para ligar o projeto ao ponto final do Azure Cosmos DB.

Fornecemos um modelo para a aplicação Java. Clonar o repositório do modelo para o sistema
```
git clone https://github.com/MicrosoftDocs/mslearn-cosmos-java-sql.git
```
Abra o Explorador do Windows e navegue para o repositório clonado. Introduza o subdiretório spring_lab.

Importante

Todo o trabalho deste módulo estará no subdiretório spring_lab.
O modelo contém um pom.xml do Maven que já solicita as dependências necessárias para o seu projeto. Abra este ficheiro e examine-o para localizar a dependência abaixo:
```
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-spring-data-cosmos</artifactId>
  <version>3.24.0</version>
</dependency>
```
Esta dependência extrai a versão mais recente do Azure Cosmos DB do Spring Data. Pode fechar este ficheiro.

Ligar a aplicação ao Azure Cosmos DB

Com o IDE ou o terminal, abra este projeto. Dependendo do IDE, pode existir uma opção para abrir o ficheiro pom.xml no subdiretório spring como um projeto. Depois que o projeto estiver aberto, navegue até src/main/resources/ usando uma ferramenta de explorador de arquivos. Deverá ver um ficheiro chamado application.properties.rename. O Spring Data destaca os ficheiros de configuração através dos parâmetros de configuração hard-coded; para criar o ficheiro de configuração para o projeto do Spring Data, copie o application.properties.rename para application.properties e abra o novo ficheiro application.properties. Deverá ver
```
cosmos.uri=${ACCOUNT_HOST}
cosmos.key=${ACCOUNT_KEY}
cosmos.secondaryKey=${SECONDARY_ACCOUNT_KEY}

dynamic.collection.name=spel-property-collection
# Populate query metrics
cosmos.queryMetricsEnabled=true
```
Vai povoar ${ACCOUNT_HOST} e ${ACCOUNT_KEY} com um método à sua escolha, ao copiar/colar os valores em application.properties ou ao definir essas variáveis de ambiente no IDE. No próximo passo, encontrará os valores que essas variáveis devem ter.
Volte ao portal do Azure, aceda ao painel Chaves e copie/cole a chave primária e o URI do ponto final do Azure Cosmos DB. Conforme discutido no passo anterior, utilize um método à sua escolha para atribuir a chave primária e o URI de ponto final do Azure Cosmos DB às variáveis mencionadas anteriormente.

Por exemplo, se o URI for https://cosmosacct.documents.azure.com:443/ e optar por colar o ponto final e a chave primária em application.properties, a linha em application.properties terá o seguinte aspeto: cosmos.uri=https://cosmosacct.documents.azure.com:443/. Se a chave primária for elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==, ao seguir o mesmo processo, a atribuição de novas variáveis terá o seguinte aspeto: cosmos.key=elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==.

Configurar o cliente do Azure Cosmos DB

O Azure Cosmos DB do Spring Data instancia automaticamente o cliente do Azure Cosmos DB no arranque. O cliente do Azure Cosmos DB é a representação no lado do cliente do serviço Azure Cosmos DB, utilizado para executar pedidos no serviço. O código pode configurar o cliente do Azure Cosmos DB antes de ser instanciado, com um conjunto de métodos do construtor junto com as propriedades extraídas de application.properties.

Abra o CosmosProperties.java. Disponibilizamos este ficheiro num formato concluído, portanto, basta examinar o conteúdo.
```
@ConfigurationProperties(prefix = "cosmos")
public class CosmosProperties {

    private String uri;

    private String key;

    private String secondaryKey;

    private boolean queryMetricsEnabled;

    public String getUri() {
        return uri;
    }

    public void setUri(String uri) {
        this.uri = uri;
    }

    public String getKey() {
        return key;
    }

    public void setKey(String key) {
        this.key = key;
    }

    public String getSecondaryKey() {
        return secondaryKey;
    }

    public void setSecondaryKey(String secondaryKey) {
        this.secondaryKey = secondaryKey;
    }

    public boolean isQueryMetricsEnabled() {
        return queryMetricsEnabled;
    }

    public void setQueryMetricsEnabled(boolean enableQueryMetrics) {
        this.queryMetricsEnabled = enableQueryMetrics;
    }
}
```
Observe os membros da classe uri, key, secondaryKeyqueryMetricsEnabled. Veja application.properties e observe que os nomes de membros de CosmosProperties correspondem de forma mais próxima aos nomes de propriedades de application.properties. A classe CosmosProperties apresenta getters e setters para o resto da aplicação para aceder às definições de configuração de application.properties. Observe que não há nenhum código aqui do qual solicitar a configuração de application.properties – o Spring Data compreende a estrutura deste ficheiro e define automaticamente as variáveis de membro depois de analisar o ficheiro de configuração.

Aproveitaremos esta configuração no futuro, quando configurarmos o cliente do Azure Cosmos DB.
No CosmosSampleConfiguration.java, examine a classe CosmosSampleConfiguration e localize o método cosmosClientBuilder vazio:
```
@Bean
public CosmosClientBuilder cosmosClientBuilder() {
    return null;
}
```
No arranque, o Spring Data chamará automaticamente este método, obterá o CosmosClientBuilder que este método devolve e chamará o método build(). Nesta altura, uma instância CosmosAsyncClient será criada (nos bastidores) com base nas definições de configuração contidas em CosmosClientBuilder. Pode utilizar este método para configurar CosmosClientBuilder com os métodos do construtor.
Observe que usamos injeção de construtor (em vez de injeção de campo usando @Autowired) para instanciar a properties variável e preencher suas variáveis membro com valores analisados do arquivo de configuração. Isso garante que todas as dependências necessárias estejam presentes quando a instância dessa classe é criada e facilita a escrita de código de teste no futuro.
```
//use constructor injection for spring dependencies 
public CosmosSampleConfiguration(CosmosProperties properties){
    this.properties = properties;
}
```
Podemos utilizar properties para obter o uri e a chave da nossa conta do Azure Cosmos DB e implementar cosmosClientBuilder, conforme mostrado abaixo:
```
@Bean
public CosmosClientBuilder cosmosClientBuilder() {
    DirectConnectionConfig directConnectionConfig = DirectConnectionConfig.getDefaultConfig();
    return new CosmosClientBuilder()
        .endpoint(properties.getUri())
        .key(properties.getKey())
        .directMode(directConnectionConfig);
}
```
Esta implementação
1. Obtém o uri e a chave de properties
2. Liga-os aos métodos do construtor endpoint e key
3. Além disso, configura a ligação de rede para o serviço Azure Cosmos DB (no modo direto, a aplicação cliente comunica diretamente com as partições do Azure Cosmos DB de back-end).
Volte para CosmosSampleConfiguration.java e localize o método getDatabaseName:
```
@Override
protected String getDatabaseName() { return ""; }
```
Altere o valor devolvido predefinido para "Users", que é o nome da base de dados. Desta forma, quando o Spring Data se ligar automaticamente ao Azure Cosmos DB no arranque, também se ligará à base de dados *Utilizadores.
Navegue até WebCustomer.java. Observará que a classe WebCustomer é precedida por uma anotação @Container:
```
@Container(containerName = "", ru = "")
```
@Container utiliza dois argumentos:
- containerName: O nome do contêiner do Azure Cosmos DB (WebCustomers)
- ru: A taxa de transferência provisionada em seu contêiner. 400 RU/s é uma boa predefinição para um exercício do Microsoft Learn.
Personalize o @Container para o seu caso de utilização, conforme mostrado:
```
@Data
@NoArgsConstructor
@AllArgsConstructor
@Container(containerName = "WebCustomers", ru = "400")
public class WebCustomer {
```

Neste ponto, o projeto do Spring Data é configurado para interagir com o Azure Cosmos DB. Em seguida, criará e executará o Hello World. Vá para src/main/java/com/azure/cosmos/examples/springexamples e abra CosmosSample.java, que é um modelo para o aplicativo Spring Data que desenvolveremos. Deve ter um aspeto semelhante a:

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
package com.azure.cosmos.examples.springexamples;

import com.azure.cosmos.CosmosException;
import com.azure.cosmos.examples.springexamples.common.CouponsUsed;
import com.azure.cosmos.examples.springexamples.common.OrderHistory;
import com.azure.cosmos.examples.springexamples.common.ShippingPreference;
import com.azure.cosmos.models.CosmosItemResponse;
import com.azure.cosmos.models.PartitionKey;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

@SpringBootApplication
public class CosmosSample implements CommandLineRunner {

    private final Logger logger = LoggerFactory.getLogger(CosmosSample.class);

    private ReactiveWebCustomerRepository reactiveWebCustomerRepository;

    //constructor dependency injection
    public CosmosSample(ReactiveWebCustomerRepository reactiveWebCustomerRepository){
        this.reactiveWebCustomerRepository = reactiveWebCustomerRepository;
    }

    public void run(String... var1) {
        logger.info("Hello world.");
    }
}

No estado em que se encontra, o código da aplicação implementa um simples “Hello World”.

Se o IDE oferecer ferramentas para criar e executar seu aplicativo Maven: compile e execute seu aplicativo usando o IDE e confirme se o aplicativo registra Hello World no terminal.
Se você usará o terminal para criar e executar seu aplicativo Maven: Use o seguinte comando para criar o projeto Maven:
```
mvn clean package
```
Em seguida, execute:
```
mvn spring-boot:run
```
Confirme se a aplicação cria um registo da seguinte saída no terminal, entre toda as outras saídas:
```
INFO: Hello World.
```

Nesta unidade, configurou a base para a sua aplicação Java do Azure Cosmos DB. Personalizou a aplicação do Maven e expandiu um projeto básico “Hello World” para o ligar a um ponto final do Azure Cosmos DB.

Continuar

Exercício – Configurar a aplicação Java com o Maven

Criar recursos do Azure Cosmos DB

Criar o seu diretório de trabalho

Ligar a aplicação ao Azure Cosmos DB

Criar a instância do CosmosAsyncClient

Ligar a aplicação ao Azure Cosmos DB

Configurar o cliente do Azure Cosmos DB

Comentários