指定 MongoClient 设置

在本页

概述

MongoClient 设置
集群设置
连接池设置
记录器设置
服务器设置
套接字设置
TLS/SSL 设置

概述

在本指南中，您可以了解如何设置来控制您的MongoClient.

以下各节描述了常用设置

MongoClient 设置
集群设置
套接字设置
连接池设置
服务器设置
TLS/SSL 设置

MongoClient 设置

您可以通过创建并传递一个MongoClientSettings对象来控制您的MongoClient的行为，并通过MongoClients.create()方法使用该对象。

要创建一个MongoClientSettings对象，请使用MongoClientSettings.builder()方法，并链式调用方法来指定您的设置。在链式调用后，使用build()方法创建MongoClientSettings对象。

以下表格描述了您可以链式调用的方法来修改您的连接行为

方法	描述
`addCommandListener()`	添加一个监听器来监听命令事件.
`applicationName()`	使用`MongoClient`设置应用程序的逻辑名称。
`applyConnectionString()`	将给定`ConnectionString`的设置应用于构建器。如果您省略此方法，驱动程序将尝试连接到`localhost`。
`applyToClusterSettings()`	应用`ClusterSettings.Builder`块，然后设置集群设置。
`applyToConnectionPoolSettings()`	应用`ConnectionPoolSettings.Builder`块，然后设置连接池设置。
`applyToLoggerSettings()`	应用`LoggerSettings.Builder`块，然后设置日志记录设置。
`applyToServerSettings()`	应用`ServerSettings.Builder`块，然后设置服务器设置。
`applyToSocketSettings()`	应用 `SocketSettings.Builder` 块，然后设置套接字设置。
`applyToSslSettings()`	应用 `SslSettings.Builder` 块，然后设置 TLS/SSL 设置。
`autoEncryptionSettings()`	设置自动加密设置。如果您在您的 `AutoEncryptionSettings` 中省略了 `keyVaultClient` 或将 `bypassAutomaticEncryption` 设置为 false，驱动程序将创建一个独立的内部 `MongoClient`。内部 `MongoClient` 的配置与父 `MongoClient` 不同，通过将 `minPoolSize` 设置为 0 并省略 `AutoEncryptionSettings` 来实现。
`codecRegistry()`	设置编解码器注册表。
`commandListenerList()`	设置命令监听器。
`compressorList()`	设置用于压缩消息到服务器的压缩器。
`credential()`	设置凭证。
`readConcern()`	设置读取关注点。
`readPreference()`	设置读取优先级。默认值: `primary`
`retryReads()`	如果发生网络错误，驱动程序是否执行重试读取。默认值: `true`
`retryWrites()`	如果发生网络错误，驱动程序是否执行重试写入。默认值: `true`
`serverApi()`	设置在向服务器发送命令时使用的服务器 API。
`transportSettings()`	设置传输设置。
`uuidRepresentation()`	设置在编码 UUID 实例和解析子类型为 3 的 BSON 二进制值时使用的 UUID 表示。
`writeConcern()`	设置写关注。默认值：`WriteConcern#ACKNOWLEDGED`。有关默认值的更多信息，请参阅隐式默认写关注。

示例

此示例演示了指定一个连接字符串。

MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
    .applyConnectionString(new ConnectionString("<your connection string>"))
    .build());

注意

链式顺序

设置映射中的某些选项对应于连接字符串选项。如果在设置和连接字符串中指定了相同的选项，则链式顺序确定驱动程序使用的选项。驱动程序使用它读取的最后一个设置。

例如，此代码片段包含以下时间设置，以便驱动程序连接到可用的套接字

连接字符串指定在2 秒内
Socket 设置指定在5 秒内

MongoClient mongoClient = MongoClients.create(
   MongoClientSettings.builder().applyConnectionString(new ConnectionString("mongodb+srv://<db_username>:<db_password>@<hostname>:<port>/<auth db>?connectTimeoutMS=2000"))
      .applyToSocketSettings(builder ->
      builder.connectTimeout(5L, SECONDS))
      .build());

由于驱动程序最后读取套接字设置选项，因此驱动程序期望在超时前在5 秒内连接到可用的套接字。

提示

记录您的设置

要记录MongoClient实例设置，请将org.mongodb.driver.client命名记录器设置为INFO级别。

有关使用MongoDB Java Driver进行日志记录的更多信息，请参阅日志记录指南。

集群设置

将 applyToClusterSettings() 方法用于修改驱动在与您的 MongoDB 集群交互时的行为。

以下表格描述了您可以链接到设置以修改驱动行为的各种方法

方法

描述

addClusterListener()

添加对集群相关事件的监听器。

applyConnectionString()

使用来自 ConnectionString 对象的设置。

applySettings()

使用来自 ClusterSettings 对象中指定的集群设置。

hosts()

设置所有指定的 Mongo 部署的位置。

localThreshold()

设置服务器往返所需的时间，同时仍然符合服务器选择条件。

默认值: 15 毫秒

mode()

设置如何连接到 MongoDB 部署。

requiredClusterType()

设置集群所需的集群类型。

requiredReplicaSetName()

设置集群所需的副本集名称。

serverSelectionTimeout()

设置在选择主节点之前抛出超时异常的最大时间。

默认值: 30 秒

serverSelector()

在服务器选择之前添加服务器选择器。

srvHost()

设置用于查找 MongoDB 主机的 SRV DNS 记录要使用的域名。

如果您想启用与主机关联的 TXT 记录的处理，请使用 applyConnectionString() 方法在连接字符串中指定 SRV 域名。

例如

    MongoClient mongoClient =
      MongoClients.create(MongoClientSettings.builder()
      .applyConnectionString(new ConnectionString("mongodb+srv://host1.acme.com")))

srvMaxHosts()

设置在使用 DNS 种子列表（SRV）连接协议时，驱动程序可以连接到的最大主机数，该协议由 mongodb+srv 连接字符串前缀标识。

如果您未使用 SRV 连接协议，则会抛出异常。

示例

此示例指定驱动程序直接连接到服务器，而不管它所属的 MongoDB 集群类型如何

MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
    .applyToClusterSettings(builder ->
        builder.mode(ClusterConnectionMode.SINGLE)
    .build());

提示

这类似于您可以在连接URI中指定的directConnection参数。有关更多信息，请参阅连接选项。

连接池设置

使用applyToConnectionPoolSettings()方法来修改驱动程序管理连接池的方式。

以下表格描述了您可以链接到设置以修改驱动行为的各种方法

方法	描述
`addConnectionPoolListener()`	添加与连接池相关事件的监听器。
`applyConnectionString()`	使用来自 `ConnectionString` 对象的设置。
`applySettings()`	使用在`ConnectionPoolSettings`对象中指定的连接池设置。
`maintenanceFrequency()`	设置运行维护作业的频率。
`maintenanceInitialDelay()`	设置在运行第一个维护作业之前要等待的时间。
`maxConnectionIdleTime()`	设置连接在关闭之前可以空闲的最大时间。
`maxConnectionLifeTime()`	设置池连接在关闭之前可以存在的最大时间。
`maxSize()`	设置与连接池相关联的连接的最大数量。默认值: `100`
`maxWaitTime()`	设置等待可用连接的最大时间。默认值: `2分钟`
`minSize()`	设置与连接池相关联的连接的最小数量。默认值: `0`

注意

此 maxSize 和 minSize 设置适用于您连接的集群中的每个服务器。

例如，假设您将驱动器连接到具有三个 mongos 服务器的集群。这意味着每个 mongos 服务器可以有最多 maxSize 个连接和至少 minSize 个连接。

示例

此示例指定了连接池中 Connection 类型以下驱动器行为

线程最多等待 10 秒 以获取可用连接
最多与池关联 200 个连接

MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder().applyConnectionString(new ConnectionString("<your connection string>"))
    .applyToConnectionPoolSettings(builder ->
        builder.maxWaitTime(10, SECONDS)
        .maxSize(200)
    .build());

日志设置

将 applyToLoggerSettings() 方法用于修改驱动程序的日志行为。

以下表格描述了您可以链接到设置以修改日志行为的各种方法

方法	描述
`maxDocumentLength()`	设置单个日志消息的最大文档长度（字符）。默认值: `1000`

示例

本例指定单个日志消息的最大字符数设置为 5000 个字符。

MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder().applyConnectionString(new ConnectionString("<your connection string>"))
    .applyToLoggerSettings(builder ->
         builder.maxDocumentLength(5_000))
    .build());

服务器设置

将 applyToServerSettings() 方法用于修改驱动在监控每个 MongoDB 部署时的行为。

以下表格描述了您可以链接到设置以修改驱动行为的各种方法

方法	描述
`addServerListener()`	添加与服务器相关事件的监听器。
`addServerMonitorListener()`	添加与服务器监控相关事件的监听器。
`applyConnectionString()`	使用来自 `ConnectionString` 对象的设置。
`applySettings()`	使用 `ServerSettings` 对象中指定的服务器设置。
`heartbeatFrequency()`	设置集群监控尝试连接服务器的间隔。默认: `10 秒`
`minHeartbeatFrequency()`	设置服务器监控检查的最小间隔。默认: `500 毫秒`

示例

此示例指定了以下 MongoDB 部署中的驱动行为

服务器监控检查的最小间隔至少为 700 毫秒
集群监控每 15 秒 尝试连接服务器一次

MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder().applyConnectionString(new ConnectionString("<your connection string>"))
    .applyToServerSettings(builder ->
        builder.minHeartbeatFrequency(700, MILLISECONDS)
        .heartbeatFrequency(15, SECONDS))
    .build());

套接字设置

使用applyToSocketSettings() 方法来修改驱动程序连接和与您的MongoDB部署通信时的行为。

以下表格描述了您可以链接到设置以修改驱动行为的各种方法

方法	描述
`applyConnectionString()`	使用来自 `ConnectionString` 对象的设置。
`applySettings()`	使用在 `SocketSettings` 对象中指定的套接字设置。
`connectTimeout()`	设置连接到可用套接字前抛出超时异常的最大时间。默认: `10 秒`
`readTimeout()`	设置从可用套接字读取前抛出超时异常的最大时间。默认值: `0`，表示没有超时
`receiveBufferSize()`	设置接收时的套接字缓冲区大小。默认值: 操作系统的默认值
`sendBufferSize()`	设置发送时的套接字缓冲区大小。默认值: 操作系统的默认值

示例

此示例在MongoDB套接字中指定以下驱动程序行为

在 10 秒 内连接到可用的套接字
在 15 秒 内从可用的套接字读取

MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder().applyConnectionString(new ConnectionString("<your connection string>"))
    .applyToSocketSettings(builder ->
        builder.connectTimeout(10, SECONDS)
        .readTimeout(15, SECONDS))
    .build());

TLS/SSL 设置

使用 applyToSslSettings() 方法修改驱动在应用 TLS/SSL 保障应用与 MongoDB 连接时的行为。

以下表格描述了您可以链接到设置以修改驱动行为的各种方法

方法	描述
`applyConnectionString()`	使用来自 `ConnectionString` 对象的设置。
`applySettings()`	使用在 `SslSettings` 对象中指定的 TLS/SSL 设置。
`context()`	设置启用 TLS/SSL 时使用的 `SSLContext`。
`enabled()`	是否启用 TLS/SSL。（您必须为 Atlas 集群启用此选项。）
`invalidHostNameAllowed()`	是否允许服务器的主机名与 TLS 证书中指定的主机名不匹配。

示例

此示例指定驱动程序在连接到 MongoDB 时启用 TLS/SSL

MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder().applyConnectionString(new ConnectionString("<your connection string>"))
    .applyToSslSettings(builder ->
        builder.enabled(true))
    .build());

连接选项

下一步

网络压缩