升级驱动程序版本

版本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。此更改破坏了二进制兼容性，需要重新编译，但不需要代码更改。

• 删除了在 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()

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

• 删除了ServerAddress方法getSocketAddress()和getSocketAddresses()。

  不再使用getSocketAddress()，而是使用java.net.InetAddress的实例方法getByName()。

  不再使用getSocketAddresses()，而是使用java.net.InetAddress的实例方法getAllByName()。

• 删除了 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 聚合管道阶段。

• 移除了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(BulkWriteResult, List<BulkWriteError>, WriteConcernError, ServerAddress)

  • MongoCursorNotFoundException(long, ServerAddress)

  • MongoQueryException(ServerAddress, int, String)

  • MongoQueryException(ServerAddress, int, String, String)

  • MongoQueryException(MongoCommandException)

• 移除了以下对BulkWriteResult.acknowledged()方法的重载

  • acknowledged(Type, int, List<BulkWriteUpsert>)

  • acknowledged(Type, int, Integer, List<BulkWriteUpsert>)

  • acknowledged(int, int, int, Integer, List<BulkWriteUpsert>)

• 移除了以下ChangeStreamDocument构造函数

  • ChangeStreamDocument(String, BsonDocument, BsonDocument, BsonDocument, TDocument, TDocument, BsonDocument, ...)

  • ChangeStreamDocument(String, BsonDocument, BsonDocument, BsonDocument, TDocument, BsonDocument, BsonTimestamp, ...)

  • ChangeStreamDocument(OperationType, BsonDocument, BsonDocument, BsonDocument, TDocument, BsonDocument, BsonTimestamp, ...)

• 移除了以下事件的构造函数

  • CommandEvent(RequestContext, int, ConnectionDescription, String)

  • CommandEvent(int, ConnectionDescription, String)

  • CommandEvent(RequestContext, long, int, ConnectionDescription, String)

  • CommandFailedEvent(RequestContext, int, ConnectionDescription, String, long, Throwable)

  • CommandFailedEvent(int, ConnectionDescription, String, long, Throwable)

  • CommandStartedEvent(RequestContext, int, ConnectionDescription, String, String, BsonDocument)

  • CommandStartedEvent(int, ConnectionDescription, String, String, BsonDocument)

  • CommandSucceededEvent(RequestContext, int, ConnectionDescription, String, BsonDocument, long)

  • CommandSucceededEvent(int, ConnectionDescription, String, BsonDocument, long)

  • ConnectionCheckedInEvent(ConnectionId)

  • ConnectionCheckedOutEvent(ConnectionId, long)

  • ConnectionCheckedOutEvent(ConnectionId)

  • ConnectionCheckOutFailedEvent(ServerId, long, Reason)

  • ConnectionCheckOutFailedEvent(ServerId, Reason)

  • ConnectionCheckOutStartedEvent(ServerId)

  • ConnectionReadyEvent(ConnectionId)

  • ServerHeartbeatFailedEvent(ConnectionId, long, Throwable)

  • ServerHeartbeatSucceededEvent(ConnectionId, BsonDocument, long)

• 从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()创建的NettyTransportSettings，并通过MongoClientSettings.Builder.transportSettings()应用。

  • 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 类型。

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

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

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

版本 4.7 破坏性变更

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

  如果您的应用程序使用的是低于v4.7的版本，请更新源代码以使用新的方法签名，并重新构建二进制文件。

版本4.2重大变更

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

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

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

版本 4.0 的重大更改

• 在3.12版本中标记为已弃用的几个类和方法在本版本中被删除。

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

• BsonDocument、Document和DbObject上的toJson()方法现在返回一个宽松的JSON格式，而不是严格的JSON格式。这使得JSON文档更易于阅读，但可能会使识别BSON类型信息（例如32位和64位整数的区别）变得更加困难。如果您的应用程序依赖于严格的JSON格式，请在读写数据时使用严格模式。

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

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

  关于枚举 UuidRepresentation 的成员列表，请参阅 v4.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 服务器支持变更

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

服务器版本 8.1 支持变更

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

驱动程序版本 4.8 服务器支持变更

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