Siapkan Proyek Anda Buat string koneksi Tulis kode koneksi Menangani pengecualian koneksi Menjalankan kode Praktik terbaik

Menghubungkan ke Amazon DocumentDB dengan driver MongoDB Java

Bagian ini menyediakan step-by-step panduan 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 membangun 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 kredensil Anda yang sebenarnya. Anda dapat menemukan titik akhir dan nomor port cluster Anda di AWS Management Console 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 perjalanan dan memastikan permintaan baca masuk ke replika baca dan tulis 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"

Opsi berbeda yang tersedia untuk string koneksi adalah sebagai berikut:

Sertifikat TLS
Membaca dari replika baca
Tulis kepedulian 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 dalam perjalanan diaktifkan di Amazon DocumentDB cluster dan oleh karena itu, kecuali TLS dinonaktifkan pada tingkat cluster, nilai untuk opsi ini seharusnya. true

Saat menggunakan TLS, kode perlu menyediakan 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 tersebut.

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 secara dinamis dalam kode, buat keystore dalam memori dan gunakan SSLContext untuk memberikan 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 menulis permintaan ke instance utama. Menggunakan replicaSet=rs0 dalam string koneksi memungkinkan driver MongoDB untuk mempertahankan tampilan topologi cluster yang diperbarui secara otomatis, memungkinkan aplikasi untuk mempertahankan visibilitas konfigurasi node saat ini saat instance ditambahkan atau dihapus. Tidak menyediakan opsi ini atau menentukan readPreference=primary mengirim semua pembacaan dan penulisan ke instance utama. Untuk opsi lainnyareadPreference, lihatBaca opsi preferensi.

Tulis kepedulian dan jurnal

Kepedulian menulis menentukan tingkat pengakuan yang diminta dari database untuk operasi penulisan. Driver MongoDB menyediakan opsi untuk menyetel masalah penulisan dan file jurnal. Amazon DocumentDB tidak mengharapkan Anda untuk menetapkan masalah penulisan dan jurnal, dan mengabaikan nilai yang dikirim w untuk j dan (dan). writeConcern journal DocumentDB selalu menulis data writeConcern denganmajority: journal dantrue: sehingga penulisan direkam dengan 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 mengautentikasi menggunakan AWS Identity and Access Management. Autentikasi 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 penyatuan koneksi:

maxPoolSize— Mengatur jumlah maksimum koneksi yang dapat dibuat di kolam renang. Ketika semua koneksi sedang digunakan dan permintaan baru masuk, ia 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 utas harus menunggu koneksi tersedia saat kolam 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

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

connectTimeoutMS— Mengkonfigurasi berapa lama driver 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 pengemudi akan menunggu untuk menemukan server yang tersedia di cluster. Nilai default untuk pengaturan ini adalah 30 detik dan cukup untuk instance primer baru yang akan dipilih selama failover.

Langkah 3: Tulis kode koneksi

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

Ini menciptakan Java KeyStoreSSLContextdan> objek.
Ini juga menciptakan MongoClientSettingsobjek dengan meneruskannya ke ConnectionStringobjek. Untuk membuat koneksi TLS, Anda harus menggunakan MongoClientSettings objek untuk mengikat dan. connectionstring sslcontext
Menggunakan MongoClientsmendapat MongoClientobjek.


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 dalam mendiagnosis masalah dengan cepat, tetapi juga memastikan bahwa aplikasi Anda dapat dengan anggun menangani gangguan jaringan sementara atau tidak tersedianya server, yang mengarah pada 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 catch umum semua pengecualian MongoDB.
MongoTimeoutException— Dikeluarkan saat waktu operasi habis. Misalnya, menanyakan titik akhir cluster yang tidak ada.
MongoSocketException— Dikeluarkan untuk masalah terkait jaringan. Misalnya, pemutusan jaringan tiba-tiba selama operasi.
MongoSecurityException— Diterbitkan saat otentikasi gagal. Misalnya, menghubungkan dengan kredensyal 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 Anda MongoClientketika 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