升级驱动程序版本

版本 5.2 的重大更改

• 该驱动程序不再与 MongoDB 服务器版本 v3.6 兼容。有关此更改的更多信息，请参阅驱动程序版本 5.2 服务器支持更改部分。

版本 5.0 的重大更改

本驱动程序版本引入了以下重大更改

• 对以下内容进行了以下更改ConnectionId 类

  • ConnectionId 构造函数现在接受第二个参数为类型 long，而不是类型 int。同样，构造函数现在接受第三个参数为类型 Long，而不是类型 Integer。由于此更改破坏了二进制兼容性，因此必须重新编译调用 ConnectionId 构造函数的任何现有代码。

  • withServerValue() 方法现在接受类型为 long 的参数，而不是类型为 int。此更改破坏了二进制兼容性，因此必须重新编译调用 withServerValue() 方法的任何代码。

  • getServerValue() 方法现在返回类型为 Long 的值，而不是类型为 Integer 的值。同样，getLocalValue() 方法返回类型为 long 的值，而不是类型为 int 的值。由于此更改破坏了二进制和源代码兼容性，因此必须更新使用这些方法的任何源代码并重新构建二进制文件。

• 将 org.bson.codecs.record.annotations 包中的以下记录注释替换为来自 org.bson.codecs.pojo.annotations 包的同名注释

  • BsonId

  • BsonProperty

  • BsonRepresentation

• 更改了 SocketSettings.Builder.connectTimeout() 和 SocketSettings.Builder.readTimeout() 方法中超时持续时间参数的数据类型。此参数的数据类型现在是 long 而不是 int。

  在早期版本中，此参数对于两种方法都是int类型。此更改破坏了二进制兼容性，需要重新编译，但不需要更改代码。要查看如何调用SocketSettings方法的示例，请参阅“指定MongoClient设置”指南中的SocketSettings 示例。

• 移除了在Beta版本中发布的Filters.eqFull()方法，该方法允许在执行向量搜索时构建相等性过滤器。在实例化VectorSearchOptions类型时，可以使用Filters.eq()方法，如下面的代码所示。

  VectorSearchOptions opts = vectorSearchOptions().filter(eq("x", 8));

• 移除了org.mongodb.scala.ObservableImplicits.ToSingleObservableVoid隐式类。这意味着org.reactivestreams.Publisher[Void]类型不再自动转换为org.mongodb.scala.SingleObservable[Void]。API还公开了org.mongodb.scala.Observable[Unit]而不是org.mongodb.scala.Observable[Void]。

  有关更多信息，请参阅Scala API 文档中的 Observable 特征。

• 更改了ClusterSettings计算ClusterConnectionMode的方式，使其更加一致，无论配置如何，都使用指定的副本集名称。以前，只有当副本集名称由连接字符串设置时，才会考虑副本集名称。

  例如，以下两个代码示例都返回值ClusterConnectionMode.MULTIPLE，而以前第二个返回值是ClusterConnectionMode.SINGLE。

  ClusterSettings.builder()
      .applyConnectionString(new ConnectionString("mongodb://127.0.0.1:27017/?replicaSet=replset"))
      .build()
      .getMode()

  ClusterSettings.builder()
      .hosts(Collections.singletonList(
              new ServerAddress("127.0.0.1", 27017)
      ))
      .requiredReplicaSetName("replset")
      .build()
      .getMode()

• 通过使其以与Decimal128值相同的方式响应方法调用，更改了BsonDecimal128值的响应方式。特别是，BsonDecimal128.isNumber()现在返回true，而BsonDecimal128.asNumber()返回等效的BsonNumber。

• 移除ServerAddress中的getSocketAddress()和getSocketAddresses()方法。

  使用java.net.InetAddress的实例方法getByName()代替getSocketAddress()。

  使用java.net.InetAddress的实例方法getAllByName()代替getSocketAddresses()。

• 移除UnixServerAddress中的getSocketAddress()和getUnixSocketAddress()方法。

  不再使用 getUnixSocketAddress()，而是构建一个 jnr.unixsocket.UnixSocketAddress 实例。将 UNIX 套接字文件的完整路径传递给构造函数。默认情况下，MongoDB 在 "/tmp/mongodb-27017.sock" 创建一个 UNIX 套接字文件。有关 UnixSocketAddress 的更多信息，请参阅UnixSocketAddress API 文档。

• 移除了 Parameterizable 接口。不再在自定义 Codec 类型上实现此接口，而是在编码器的 CodecProvider 上重写 CodecProvider.get() 方法，如果编码器旨在用于参数化类型。

• 从 ReadPreference 和 TaggableReadPreference 类中移除了 isSlaveOk() 方法。要检查读取偏好是否允许从副本集的次要成员读取，请使用这些类中的 isSecondaryOk() 方法。

• 从用于 collStats 命令的 DBCollection.getStats() 和 DBCollection.isCapped() 辅助方法中删除。不再使用这些方法，而是可以使用 $collStats 聚合管道阶段。有关如何使用此管道阶段的示例，请参阅4.11 版本中的新增功能（Java 驱动程序）。

• 移除了 MapCodec 和 IterableCodec 类。不再使用 MapCodec，而是使用 MapCodecProvider。不再使用 IterableCodec，而是使用 CollectionCodecProvider，或对于不是 Collection 类型的 Iterable 类型，使用 IterableCodecProvider。

• 从 MapReducePublisher 和 MapReduceIterable 类中移除了 sharded() 和 nonAtomic() 方法。

• 移除了用于 geoHaystack 索引的以下方法

  • Indexes.geoHaystack()

  • IndexOptions.getBucketSize()

  • IndexOptions.bucketSize()

  相反，您可以使用 $geoNear 聚合管道阶段或对 2d 索引上的地理空间查询运算符。有关更多信息，请参阅 MongoDB 服务器手册中的地理空间查询页面。

• 从查找操作中移除了 oplogReplay 选项。这包括以下方法

  • DBCursor.oplogReplay()

  • DBCollectionFindOptions.isOplogReplay()

  • DBCollectionFindOptions.oplogReplay()

  • FindPublisher.oplogReplay()

  • FindIterable.oplogReplay()

• 移除了以下 Exception 构造函数

  • MongoBulkWriteException（批量写入结果，批量写入错误列表，写入关注错误，服务器地址）

  • MongoCursorNotFoundException（长整型，服务器地址）

  • MongoQueryException（服务器地址，整数，字符串）

  • MongoQueryException（服务器地址，整数，字符串，字符串）

  • MongoQueryException（MongoCommandException）

• 删除了以下 BulkWriteResult.acknowledged() 方法重载

  • acknowledged（类型，整数，批量写入更新列表）

  • acknowledged（类型，整数，整数，批量写入更新列表）

  • acknowledged（整数，整数，整数，整数，批量写入更新列表）

• 删除以下 ChangeStreamDocument 构造函数

  • ChangeStreamDocument（字符串，BsonDocument，BsonDocument，BsonDocument，TDocument，TDocument，BsonDocument，...）

  • ChangeStreamDocument（字符串，BsonDocument，BsonDocument，BsonDocument，TDocument，BsonDocument，BsonTimestamp，...）

  • ChangeStreamDocument（操作类型，BsonDocument，BsonDocument，BsonDocument，TDocument，BsonDocument，BsonTimestamp，...）

• 删除以下事件构造函数

  • CommandEvent（请求上下文，整数，连接描述，字符串）

  • CommandEvent（整数，连接描述，字符串）

  • CommandEvent（请求上下文，长整型，整数，连接描述，字符串）

  • CommandFailedEvent（请求上下文，整数，连接描述，字符串，长整型，Throwable）

  • CommandFailedEvent（整数，连接描述，字符串，长整型，Throwable）

  • CommandStartedEvent（请求上下文，整数，连接描述，字符串，字符串，BsonDocument）

  • CommandStartedEvent（整数，连接描述，字符串，字符串，BsonDocument）

  • CommandSucceededEvent（请求上下文，整数，连接描述，字符串，BsonDocument，长整型）

  • CommandSucceededEvent（整数，连接描述，字符串，BsonDocument，长整型）

  • ConnectionCheckedInEvent（连接ID）

  • ConnectionCheckedOutEvent（连接ID，长整型）

  • ConnectionCheckedOutEvent（连接ID）

  • ConnectionCheckOutFailedEvent（服务器ID，长整型，原因）

  • ConnectionCheckOutFailedEvent（服务器ID，原因）

  • ConnectionCheckOutStartedEvent（服务器ID）

  • ConnectionReadyEvent（连接ID）

  • ServerHeartbeatFailedEvent（连接ID，长整型，Throwable）

  • ServerHeartbeatSucceededEvent（连接ID，BsonDocument，长整型）

• 删除了 WriteConcernError 类中的 errorLabels 选项。这包括 addLabel() 和 getErrorLabels() 方法以及包含 errorLabels 参数的构造函数。相反，您可以使用包含 WriteConcernError 的 MongoException 对象中的错误标签。

• 删除以下 com.mongodb.event 包中的类

  • ConnectionAddedEvent

  • ConnectionPoolOpenedEvent

  • ConnectionRemovedEvent

  • ClusterListenerAdapter

  • ConnectionPoolListenerAdapter

  • ServerListenerAdapter

  • ServerMonitorListenerAdapter

  由于这些删除，以下方法也从 ConnectionPoolListener 接口删除

  • connectionAdded

  • connectionPoolOpened

  • connectionRemoved

  有关事件包的更多信息，请参阅 com.mongodb.event 包文档

• 为 listCollections 命令添加了对新选项 authorizedCollection 的支持。这导致 MongoDatabase.listCollectionNames() 方法中的二进制变更，意味着使用这些方法的任何代码都必须重新编译。此更改不需要对源代码进行任何修改。

• 删除了以下与 Stream 接口相关的以下方法和类型

  • streamFactoryFactory() 方法从 MongoClientSettings.Builder 中移除。请使用 MongoClientSettings.Builder.transportSettings() 方法代替。

  • getStreamFactoryFactory() 方法从 MongoClientSettings 中移除。请使用 MongoClientSettings.getTransportSettings() 方法代替。

  • NettyStreamFactoryFactory 类。请使用可由 TransportSettings.nettyBuilder() 创建并通过 MongoClientSettings.Builder.transportSettings() 应用的 NettyTransportSettings。

  • NettyStreamFactory 类

  • AsynchronousSocketChannelStreamFactory 类

  • AsynchronousSocketChannelStreamFactoryFactory 类

  • BufferProvider 接口

  • SocketStreamFactory 类

  • Stream 接口

  • StreamFactory 接口

  • StreamFactoryFactory 接口

  • TlsChannelStreamFactoryFactory 类

版本 4.8 破坏性更改

• 驱动程序结束了对 MongoDB 服务器版本 v3.4 及更早版本的支持。有关此更改的更多信息，请参阅 驱动程序版本 4.8 服务器支持更改 部分。

• 如果您的应用程序在OSGi容器中部署驱动程序并依赖于驱动程序进行Java记录的编码和解码，您必须显式添加对org.bson.codecs.record模块的依赖。

• 在v4.6中实现的RecordCodec将指定为记录的List或Map字段类型参数的POJO和记录类反序列化为Document值，而不是它们的相应类。此版本现在将它们反序列化为正确的记录和POJO类型。

  例如，以下记录类定义显示了包含一个接收Chapter类型参数的List的Book记录。

  public record Book(String title, List<Chapter> chapters) {}
  public record Chapter(Integer number, String text) {}

  从本版本开始，编解码器将List中的数据反序列化为Chapter记录类，而不是Document值。

版本4.7重大更改

• setWindowFields构建器API不再处于测试阶段。新的构建器破坏了二进制和源兼容性。有关新setWindowFields()方法签名的信息，请参阅聚合API文档。

  如果您的应用程序在v4.7之前使用此构建器，请更新源代码以使用新的方法签名并重新构建二进制文件。

版本 4.2 破坏性变更

• ObjectId 类及其 serialVersionUID 字段已更新，以使用一种新的格式，该格式最小化了不同版本驱动程序之间的序列化兼容性问题。

  如果使用此版本或更高版本驱动程序的应用程序尝试对包含 ObjectId 并由先前版本的驱动程序序列化的任何对象执行 Java 对象序列化，Java 将抛出 InvalidClassException。

  有关 Java 对象序列化的更多信息，请参阅 Oracle Java 文档中的 可序列化对象。

版本 4.0 破坏性变更

• 在 3.12 版本中标记为已过时的几个类和方法已在此版本中删除。

• 插入辅助方法返回一个插入结果对象，而不是 void。

• toJson() 方法在 BsonDocument、Document 和 DbObject 上返回一个宽松的 JSON 格式，而不是严格的 JSON 格式。这使得 JSON 文档更易于阅读，但可能更难识别 BSON 类型信息，例如 32 位和 64 位整数的区别。如果您的应用程序依赖于严格的 JSON 格式，请在读取或写入数据时使用严格模式。有关如何在当前 API 中指定 JSON 格式的说明，请参阅文档数据格式：扩展 JSON指南。

• java.util.UUID 值的默认 BSON 表示形式已从 JAVA_LEGACY 更改为 UNSPECIFIED。存储或检索 UUID 值的应用程序必须明确指定要使用哪种表示形式。您可以在 MongoClientSettings 的 uuidRepresentation 属性中指定表示形式。

  您指定的 UUID 表示形式严格控制驱动程序如何解码 UUID。在驱动程序的先前版本中，如果指定了 JAVA_LEGACY 表示形式，则驱动程序会将子类型 3 和 4 的二进制对象解码为 UUID。在 4.0 版本中，JAVA_LEGACY 表示形式仅与子类型 3 一起使用。

  有关 UuidRepresentation 枚举成员的列表，请参阅4.0 API 文档。

• 连接池不再限制等待队列线程或需要连接到 MongoDB 的异步任务的数量。应用程序应根据需要调节请求，而不是依赖于驱动程序抛出 MongoWaitQueueFullException。

• 驱动程序不再使用 java.util.logging（JUL）包进行日志记录，并且仅支持 SLF4J 日志框架。

• 已删除嵌入式和 Android 驱动程序。如果您的应用程序依赖于这些驱动程序，则必须继续使用 3.x Java 驱动程序版本。

• 已停止发布超级 JAR，mongo-java-driver 和 mongodb-driver。如果您的应用程序依赖于其中之一，则必须根据应用程序使用的 API 切换到 mongodb-driver-sync 或 mongodb-driver-legacy。请确保从依赖项中删除超级 JAR。

• 对多个类的更新引入了二进制兼容性问题，例如将插入辅助方法的签名更改为。请重新编译所有链接到该版本或更高版本的驱动程序的类，以确保它们继续正常工作。

驱动程序版本 5.2 服务器支持更改

v5.2 驱动程序不再支持 MongoDB 服务器 v3.6。要使用 v5.2 驱动程序，您的 MongoDB 服务器版本必须是 v4.0 或更高版本。有关如何升级 MongoDB 服务器部署的信息，请参阅 MongoDB 服务器手册中的发行说明。

服务器版本 8.1 支持更改

您不能使用Java驱动程序的3.x版本连接到运行MongoDB服务器v8.1的部署。从MongoDB服务器v8.1开始，buildinfo命令需要认证，导致与v3.x驱动程序不兼容。

驱动程序版本4.8对服务器支持的变化

驱动程序v4.8不再支持MongoDB服务器v3.4及更早版本。要使用v4.8驱动程序，您的MongoDB服务器必须是v3.6或更高版本。有关如何升级MongoDB服务器部署的信息，请参阅MongoDB服务器手册中的发行说明。