Conectando-se ao Amazon DocumentDB com um driver Java MongoDB - Amazon DocumentDB
Configurar o projetoCrie a cadeia de conexãoEscreva o código de conexãoLidar com exceções de conexãoExecutar o códigoPráticas recomendadas

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á.

Conectando-se ao Amazon DocumentDB com um driver Java MongoDB

Esta seção fornece um step-by-step guia para se conectar ao Amazon DocumentDB usando drivers Java. Isso fará com que você comece a integrar o DocumentDB aos seus aplicativos Java.

Etapa 1: configurar o projeto do

  1. Usando o Maven, crie um projeto java:

    mvn archetype:generate -DgroupId=com.docdb.guide -DartifactId=my-docdb-project -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

  2. Adicione o driver Java do MongoDB como uma dependência para o projeto em seu arquivo 'pom.xml':

    <dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>mongodb-driver-sync</artifactId> 
    <version>5.3.0</version> 
</dependency>

Etapa 2: criar a cadeia de conexão

A cadeia de conexão do Amazon DocumentDB é essencial para estabelecer uma conexão entre seu aplicativo e seu cluster DocumentDB. Essa sequência de caracteres encapsula informações cruciais, como o endpoint do cluster, a porta, os detalhes de autenticação e várias opções de conexão. Para criar uma cadeia de conexão do DocumentDB, você normalmente começa com o formato básico:

"mongodb://username:password@cluster-endpoint:port/?[connection options]"

Você precisará substituir “nome de usuário” e “senha” por suas credenciais reais. Você pode encontrar o endpoint e o número da porta do seu cluster no AWS Management Console e por meio do AWS CLI. Consulte Localizar os endpoints de um cluster para encontrar o endpoint de cluster para seu cluster. A porta padrão do DocumentDB é 27017.

Exemplos de cadeias de conexão

  • Fazendo uma conexão com o DocumentDB usando criptografia em trânsito e garantindo que as solicitações de leitura sejam enviadas para réplicas de leitura e gravem no primário:

    "mongodb://username:password@cluster-endpoint:27017/?tls=true& 
   tlsCAFile=global-bundle.pem& 
   readPreference=secondaryPreferred&
   retryWrites=false"

  • Fazendo uma conexão com o DocumentDB usando a autenticação do IAM:

    "mongodb://cluster-endpoint:27017/?tls=true& 
   tlsCAFile=global-bundle.pem& 
   readPreference=secondaryPreferred&
   retryWrites=false&
   authSource=%24external&
   authMechanism=MONGODB-AWS"

As diferentes opções disponíveis para a cadeia de conexão são as seguintes:

certificado TLS

tls=true|false— Essa opção ativa ou desativa o Transport Layer Security (TLS). Por padrão, a criptografia em trânsito está habilitada no cluster Amazon DocumentDB e, portanto, a menos que o TLS esteja desativado no nível do cluster, o valor dessa opção deve ser. true

Ao usar o TLS, o código precisa fornecer um certificado SSL ao criar uma conexão com um cluster do DocumentDB. Baixe o certificado necessário para fazer a conexão segura com o cluster: global-bundle.pem. Há duas maneiras de usar o global-bundle.pem arquivo.

  • Opção 1 — Extraia todos os certificados do global-bundle.pem arquivo e use a ferramenta chave do Java para armazená-los em um .jks arquivo que possa ser usado posteriormente no código. Consulte a guia Java Conectar-se com o TLS habilitado para ver o script que mostra como fazer isso.

  • Opção 2 — Adicione dinamicamente o global-bundle.pem arquivo no código, crie um armazenamento de chaves na memória e use-o SSLContext para fornecer o certificado como parte da conexão.

Lendo a partir de réplicas lidas

replicaSet=rs0&readPreference=secondaryPreferred— A especificação dessas duas opções encaminha todas as solicitações de leitura para as réplicas de leitura e as solicitações de gravação para a instância primária. O uso replicaSet=rs0 na cadeia de conexão permite que o driver do MongoDB mantenha uma visão atualizada automaticamente da topologia do cluster, permitindo que os aplicativos mantenham a visibilidade das configurações atuais dos nós à medida que as instâncias são adicionadas ou removidas. Não fornecer essas opções ou especificar readPreference=primary envia todas as leituras e gravações para a instância primária. Para obter mais opções parareadPreference, consulteOpções de preferência de leitura.

Escreva uma preocupação e um diário

A preocupação com a gravação determina o nível de reconhecimento solicitado do banco de dados para operações de gravação. Os drivers do MongoDB oferecem uma opção para ajustar arquivos de registro e de diário. O Amazon DocumentDB não espera que você defina a preocupação de gravação e o diário e ignora os valores enviados para w e j (e)writeConcern. journal O DocumentDB sempre grava dados comwriteConcern: majority ejournal: true para que as gravações sejam gravadas de forma duradoura na maioria dos nós antes de enviar uma confirmação ao cliente.

RetryWrites

retryWrites=false— O DocumentDB não suporta gravações que podem ser repetidas e, portanto, esse atributo sempre deve ser definido como. false

Autenticação do IAM

authSource=%24externale authMechanism=MONGODB-AWS — Esses dois parâmetros são usados para autenticar usando AWS Identity and Access Management. Atualmente, a autenticação do IAM só está disponível na versão 5.0 do cluster baseado em instância. Para obter mais informações, consulte Autenticação usando identidade do IAM.

Pool de conexões

Essas opções estão disponíveis para agrupamento de conexões:

  • maxPoolSize— Define o número máximo de conexões que podem ser criadas no pool. Quando todas as conexões estão em uso e uma nova solicitação é recebida, ela espera que uma conexão fique disponível. O padrão para drivers Java do MongoDB é 100.

  • minPoolSize— Indica o número mínimo de conexões que devem ser mantidas no pool o tempo todo. O padrão para drivers Java do MongoDB é 0.

  • maxIdleTimeMS— Determina por quanto tempo uma conexão pode permanecer inativa no pool antes de ser fechada e removida. O padrão para drivers Java do MongoDB é 100 milissegundos.

  • waitQueueTimeoutMS— Configura quanto tempo um thread deve esperar até que uma conexão fique disponível quando o pool estiver em seu tamanho máximo. Se uma conexão não estiver disponível dentro desse período, uma exceção será lançada. O valor padrão para os drivers Java do MongoDB é 120.000 milissegundos (2 minutos).

Parâmetros de tempo limite de conexão

O tempo limite é um mecanismo para limitar a quantidade de tempo que uma operação ou tentativa de conexão pode levar até que seja considerada falha. Os seguintes parâmetros de tempo limite estão disponíveis para evitar esperas indefinidas e gerenciar a alocação de recursos:

  • connectTimeoutMS— Configura quanto tempo o driver esperará para estabelecer uma conexão com o cluster. O padrão é 10.000 milissegundos (10 segundos).

  • socketTimeoutMS— Especifica quanto tempo o driver aguardará por uma resposta do servidor para uma operação de não gravação. O padrão é 0, (sem tempo limite ou infinito).

  • serverSelectionTimeoutMS— Especifique quanto tempo o driver esperará para encontrar um servidor disponível no cluster. O valor padrão dessa configuração é de 30 segundos e é suficiente para que uma nova instância primária seja eleita durante o failover.

Etapa 3: escrever o código de conexão

O exemplo de código a seguir mostra como fazer uma conexão TLS com o Amazon DocumentDB:

public static MongoClient makeDbConnection(String dbName, String DbUserName, String DbPassword,
    String DbClusterEndPoint, String keyStorePass) throws Exception {
    MongoClient connectedClient;
    String connectionOptions = "?replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false";
    String connectionUrl = "mongodb://" + DbUserName + ":" + DbPassword + "@" + DbClusterEndPoint + ":27017/" +
        dbName + connectionOptions;

    try {
        KeyStore trustStore = KeyStore.getInstance(KeyStore.getDefaultType());
        try (FileInputStream fis = new FileInputStream("src/main/resources/certs/truststore.jks")) {
            trustStore.load(fis, keyStorePass.toCharArray());
            TrustManagerFactory tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
            tmf.init(trustStore);

            SSLContext sslContext = SSLContext.getInstance("TLSv1.2");
            sslContext.init(null, tmf.getTrustManagers(), new SecureRandom());
            ConnectionString connectionString = new ConnectionString(connectionUrl);
            MongoClientSettings settings = MongoClientSettings.builder()
                .applyConnectionString(connectionString)
                .applyToSslSettings(builder - > {
                    builder.enabled(true);
                    builder.context(sslContext);
                })
                .build();
            connectedClient = MongoClients.create(settings);
        }
        return connectedClient;
    } catch (MongoException e5) {
        throw new RuntimeException(e5);
    } catch (Exception e) {
        throw new RuntimeException(e);
    }
}

Etapa 4: lidar com exceções de conexão

Ao trabalhar com o DocumentDB em aplicativos Java, lidar com exceções de conexão é crucial para manter operações de banco de dados robustas e confiáveis. Gerenciando adequadamente, essas exceções não apenas ajudam a diagnosticar problemas rapidamente, mas também garantem que seu aplicativo possa lidar com interrupções temporárias na rede ou indisponibilidade do servidor, melhorando a estabilidade e a experiência do usuário. Algumas das exceções críticas relacionadas ao estabelecimento de conexão incluem:

  • MongoException— Uma exceção geral e pode ser emitida em vários cenários não cobertos por exceções mais específicas. Certifique-se de que essa exceção seja tratada após todas as outras exceções específicas, pois essa é uma exceção geral do MongoDB de catch all.

  • MongoTimeoutException— Emitido quando uma operação atinge o tempo limite. Por exemplo, consultar um endpoint de cluster inexistente.

  • MongoSocketException— Emitido para problemas relacionados à rede. Por exemplo, desconexão repentina da rede durante uma operação.

  • MongoSecurityException— Emitido quando a autenticação falha. Por exemplo, conectar-se com credenciais incorretas.

  • MongoConfigurationException— Emitido quando há um erro na configuração do cliente. Por exemplo, usando uma cadeia de conexão inválida.

Etapa 5: Executando o código

O exemplo de código a seguir cria uma conexão Amazon DocumentDB e imprime todos os bancos de dados:

public static void TestConnection() {
    try (MongoClient mongoClient = makeDbConnection(DATABASE_NAME, DB_USER_NAME, DB_PASSWORD, DB_CLUSTER_ENDPOINT, KEYSTORE_PASSWORD)) {
        List < String > databases = mongoClient.listDatabaseNames().into(new ArrayList < > ());
        System.out.println("Databases: " + databases);
    } catch (MongoException e) {
        System.err.println("MongoDB error: " + e.getMessage());
        throw new RuntimeException(e);
    }
}

Melhores práticas de conexão

A seguir estão as melhores práticas a serem consideradas ao se conectar ao Amazon DocumentDB com um driver Java MongoDB:

  • Sempre feche o seu MongoClientquando não precisar mais que o cliente libere recursos.

  • Trate as exceções de forma adequada e implemente o registro de erros adequado.

  • Use variáveis de ambiente ou AWS Secrets Manager para armazenar informações confidenciais, como nomes de usuário e senhas.