Siapkan proyek Anda Buat string koneksi Tulis kode koneksi Tangani pengecualian koneksi Menjalankan kode Praktik terbaik

Menghubungkan ke Amazon DocumentDB dengan driver MongoDB Java

Bagian ini menyediakan panduan langkah demi langkah untuk menghubungkan ke Amazon DocumentDB menggunakan driver Java. Ini akan membantu Anda memulai dengan mengintegrasikan DocumentDB ke dalam aplikasi Java Anda.

Langkah 1: Siapkan proyek Anda

Menggunakan Maven, buat proyek java:


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

Tambahkan driver MongoDB Java sebagai dependensi untuk proyek di file 'pom.xml' Anda:


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

Langkah 2: Buat string koneksi

String koneksi Amazon DocumentDB sangat penting untuk membuat koneksi antara aplikasi Anda dan cluster DocumentDB Anda. String ini merangkum informasi penting seperti titik akhir cluster, port, detail otentikasi, dan berbagai opsi koneksi. Untuk membuat string koneksi DocumentDB, Anda biasanya mulai dengan format dasar:


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

Anda harus mengganti “nama pengguna” dan “kata sandi” dengan kredenSIAL Anda yang sebenarnya. Anda dapat menemukan titik akhir cluster dan nomor port Anda di Konsol Manajemen AWS serta melalui AWS CLI. Lihat Menemukan titik akhir klaster untuk menemukan titik akhir cluster untuk cluster Anda. Port default untuk DocumentDB adalah 27017.

Contoh string koneksi

Membuat koneksi ke DocumentDB menggunakan enkripsi dalam transit dan memastikan permintaan baca digunakan untuk membaca replika dan menulis ke primer:


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

Membuat koneksi ke DocumentDB menggunakan otentikasi IAM:


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

Pilihan berbeda yang tersedia untuk string koneksi adalah sebagai berikut:

Sertifikat TLS
Membaca dari replika baca
Tulis kekhawatiran dan jurnal
RetryWrites
Autentikasi IAM
Kolam koneksi
Parameter batas waktu koneksi

Sertifikat TLS

tls=true|false- Opsi ini mengaktifkan atau menonaktifkan Transport Layer Security (TLS). Secara default, enkripsi saat transit diaktifkan di cluster Amazon DocumentDB dan oleh karena itu, kecuali TLS dinonaktifkan di tingkat cluster, nilai untuk opsi ini seharusnya. true

Saat menggunakan TLS, kode perlu memberikan sertifikat SSL saat membuat koneksi ke cluster DocumentDB. Unduh sertifikat yang diperlukan untuk membuat koneksi aman ke cluster: global-bundle.pem. Ada dua cara untuk menggunakan global-bundle.pem file.

Opsi 1 — Ekstrak semua sertifikat dari global-bundle.pem file dan gunakan keytool Java untuk menyimpannya dalam .jks file yang nantinya dapat digunakan dalam kode. Lihat tab Java Menghubungkan dengan TLS diaktifkan untuk skrip yang menunjukkan cara melakukan ini.
Opsi 2 — Tambahkan global-bundle.pem file dalam kode secara dinamis, buat keystore dalam memori dan gunakan SSLContext untuk menyediakan sertifikat sebagai bagian dari membuat koneksi.

Membaca dari replika baca

replicaSet=rs0&readPreference=secondaryPreferred- Menentukan dua opsi ini merutekan semua permintaan baca ke replika baca, dan tulis permintaan ke instance utama. Menggunakan replicaSet=rs0 string koneksi memungkinkan driver MongoDB untuk mempertahankan tampilan topologi cluster yang diperbarui secara otomatis, memungkinkan aplikasi untuk mempertahankan visibilitas konfigurasi node saat instance ditambahkan atau dihapus. Tidak menyediakan opsi ini atau menentukan readPreference=primary mengirimkan semua pembacaan dan penulisan ke instance utama. Untuk opsi lainnyareadPreference, lihatBaca opsi preferensi.

Tulis kekhawatiran dan jurnal

Masalah menulis menentukan tingkat pengakuan yang diminta dari database untuk operasi penulisan. Driver MongoDB menyediakan opsi untuk menyetel masalah tulis dan file jurnal. Amazon DocumentDB tidak mengharapkan Anda untuk mengatur masalah tulis dan jurnal, dan mengabaikan nilai yang dikirim untuk w dan j (writeConcerndanjournal). DocumentDB selalu menulis data denganwriteConcern: majority danjournal: true sehingga penulisan direkam secara tahan lama pada sebagian besar node sebelum mengirim pengakuan ke klien.

RetryWrites

retryWrites=false- DocumentDB tidak mendukung penulisan yang dapat dicoba ulang dan oleh karena itu atribut ini harus selalu disetel ke. false

Autentikasi IAM

authSource=%24externaldan authMechanism=MONGODB-AWS — Kedua parameter ini digunakan untuk mengotentikasi menggunakan AWS Identity and Access Management. Otentikasi IAM saat ini hanya tersedia di cluster berbasis instance versi 5.0. Untuk informasi selengkapnya, lihat Otentikasi menggunakan identitas IAM.

Kolam koneksi

Opsi ini tersedia untuk pengumpulan koneksi:

maxPoolSize— Menetapkan jumlah maksimum koneksi yang dapat dibuat di kolam. Ketika semua koneksi digunakan dan permintaan baru masuk, itu menunggu koneksi tersedia. Default untuk driver MongoDB Java adalah 100.
minPoolSize— Menunjukkan jumlah minimum koneksi yang harus dipertahankan di kolam setiap saat. Default untuk driver MongoDB Java adalah 0.
maxIdleTimeMS— Menentukan berapa lama koneksi dapat tetap diam di kolam sebelum ditutup dan dilepas. Default untuk driver MongoDB Java adalah 100 milidetik.
waitQueueTimeoutMS— Mengkonfigurasi berapa lama thread harus menunggu koneksi tersedia saat kumpulan berada pada ukuran maksimumnya. Jika koneksi tidak tersedia dalam waktu ini, pengecualian dilemparkan. Nilai default untuk driver MongoDB Java adalah 120.000 milidetik (2 menit).

Parameter batas waktu koneksi

Batas waktu adalah mekanisme untuk membatasi jumlah waktu yang dibutuhkan operasi atau upaya koneksi sebelum dianggap gagal. Parameter batas waktu berikut tersedia untuk mencegah penantian tak terbatas dan mengelola alokasi sumber daya:

connectTimeoutMS— Mengkonfigurasi berapa lama pengemudi akan menunggu untuk membuat koneksi ke cluster. Defaultnya adalah 10.000 milidetik (10 detik).
socketTimeoutMS— Menentukan berapa lama driver akan menunggu respons dari server untuk operasi non-tulis. Defaultnya adalah 0, (tidak ada batas waktu atau tak terbatas).
serverSelectionTimeoutMS— Spesies berapa lama driver akan menunggu untuk menemukan server yang tersedia di cluster. Nilai default untuk pengaturan ini adalah 30 detik dan cukup untuk instans utama baru yang dipilih selama failover.

Langkah 3: Tulis kode koneksi

Contoh kode berikut menunjukkan cara membuat koneksi TLS ke Amazon DocumentDB:

Ini menciptakan objek Java KeyStore dan SSLContext >.
Ini juga menciptakan MongoClientSettings objek dengan meneruskannya ke ConnectionString objek. Untuk membuat koneksi TLS, Anda harus menggunakan MongoClientSettings objek untuk mengikat connectionstring dansslcontext.
Menggunakan MongoClients mendapatkan MongoClient objek.


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);
    }
}

Langkah 4: Tangani pengecualian koneksi

Saat bekerja dengan DocumentDB dalam aplikasi Java, penanganan pengecualian koneksi sangat penting untuk mempertahankan operasi database yang kuat dan andal. Mengelola dengan benar, pengecualian ini tidak hanya membantu mendiagnosis masalah dengan cepat, tetapi juga memastikan bahwa aplikasi Anda dapat menangani gangguan jaringan sementara atau ketidaktersediaan server dengan anggun, yang mengarah ke peningkatan stabilitas dan pengalaman pengguna. Beberapa pengecualian penting yang terkait dengan membangun koneksi meliputi:

MongoException— Pengecualian umum dan dapat dikeluarkan dalam berbagai skenario yang tidak tercakup oleh pengecualian yang lebih spesifik. Pastikan pengecualian ini ditangani setelah semua pengecualian spesifik lainnya karena ini adalah pengecualian catch all MongoDB umum.
MongoTimeoutException- Diterbitkan ketika waktu operasi habis. Misalnya, menanyakan titik akhir cluster yang tidak ada.
MongoSocketException- Diterbitkan untuk masalah terkait jaringan. Misalnya, pemutusan jaringan mendadak selama operasi.
MongoSecurityException- Diterbitkan ketika otentikasi gagal. Misalnya, menghubungkan dengan kredenSIAL yang salah.
MongoConfigurationException- Diterbitkan ketika ada kesalahan dalam konfigurasi klien. Misalnya, menggunakan string koneksi yang tidak valid.

Langkah 5: Menjalankan kode

Contoh kode berikut membuat koneksi Amazon DocumentDB dan mencetak semua database:


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);
    }
}

Praktik terbaik koneksi

Berikut ini adalah praktik terbaik yang perlu dipertimbangkan saat menghubungkan ke Amazon DocumentDB dengan driver MongoDB Java:

Selalu tutup MongoClient ketika Anda tidak lagi membutuhkan klien untuk melepaskan sumber daya.
Tangani pengecualian dengan tepat dan terapkan logging kesalahan yang tepat.
Gunakan variabel lingkungan atau AWS Secrets Manager untuk menyimpan informasi sensitif seperti nama pengguna dan kata sandi.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Panduan pemrograman Java DocumentDB

Operasi CRUD dengan Java