升级驱动程序版本

版本 5.0 破坏性变更 (breaking change)

此驱动程序版本引入了以下破坏性变更 (breaking change)：

• 对 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()

• 更改BsonDecimal128值响应方法调用的方式，其响应方式与Decimal128值相同。 特别是， 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 会创建位于 的 UNIX"/tmp/mongodb-27017.sock" 套接字文件。要了解有关UnixSocketAddress 的更多信息，请参阅 UnixSocketAddress API 文档。

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

• 从ReadPreference和TaggableReadPreference类中删除isSlaveOk()方法。 要检查读取偏好是否允许从副本集的从节点读取，请改用这些类中的isSecondaryOk()方法。

• 移除 collStats 命令的 DBCollection.getStats() 和 DBCollection.isCapped() 辅助方法。您可以使用 $collStats 聚合管道阶段来代替这些方法。有关如何使用此管道阶段的示例，请参阅 Java 驱动程序的 4.11 中的新增功能。

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

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

• 删除了以下与geoHaystack索引一起使用的方法：

  • Indexes.geoHaystack()

  • IndexOptions.getBucketSize()

  • IndexOptions.bucketSize()

  相反，您可以在 2d 索引上使用 $geoNear 聚合管道阶段或地理空间查询操作符。有关更多信息，请参阅 MongoDB Server 手册中的“地理空间查询”页面。

• 从查找操作中删除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()方法中引入了重大二进制更改，这意味着使用这些方法的任何代码都必须重新编译。 此更改不需要对源代码进行任何更改。

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

  • streamFactoryFactory() MongoClientSettings.Builder中的方法。 请改用MongoClientSettings.Builder.transportSettings()方法。

  • getStreamFactoryFactory() MongoClientSettings中的方法。 请改用MongoClientSettings.getTransportSettings()方法。

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

  • NettyStreamFactory class

  • AsynchronousSocketChannelStreamFactory class

  • AsynchronousSocketChannelStreamFactoryFactory class

  • BufferProvider 接口

  • SocketStreamFactory class

  • Stream 接口

  • StreamFactory 接口

  • StreamFactoryFactory 接口

  • TlsChannelStreamFactoryFactory class

版本 4.8 重大更改

• 驱动程序不再支持连接到 v 3.4及更早版本的 MongoDB Server。要了解有关此更改的更多信息，请参阅驱动程序版本4.8服务器支持更改部分。

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

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

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

  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 对象序列化”的更多信息，请参阅 Java 文档中的可序列化对象部分。

版本 4.0 重大更改

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

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

• BsonDocument、Document 和 DbObject 上的 toJson() 方法返回宽松 JSON 格式，而不是严格 JSON 格式。这增加了 JSON 文档的可读性，但也更难以识别 BSON 类型信息，例如 32 位和 64 位整数之间的差异。如果应用程序依赖于严格 JSON 格式，请在读取或写入数据时使用严格模式。请参阅文档数据格式：扩展 JSON 指南，了解如何在当前 API 中指定 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 驱动程序版本。

• uber JAR、mongo-java-driver 和 mongodb-driver 均不再发布。如果您的应用程序依赖其中一项，则必须根据应用程序使用的 API 切换到 mongodb-driver-sync 或 mongodb-driver-legacy。确保从依赖项中删除 uber JAR。

• 对多个类的更新引入了二进制兼容性中断，例如插入辅助方法的方法签名更改。针对此版本或更高版本重新编译所有链接到驱动程序的类，以确保它们继续运行。

服务器版本8.1支持更改

您无法使用3 .x 版本的 Java 驱动程序连接到运行 MongoDB Server v 8.1的部署。从 MongoDB Server v 8.1开始， buildinfo命令需要身份验证，导致与 v 3 .x 驱动程序不兼容。

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

v4.8 驱动程序不再支持 MongoDB Server v3.4 及更早版本。如要使用 v4.8 驱动程序，您的 MongoDB Server 必须是 v3.6 或更新版本。如要了解如何升级 MongoDB Server 部署，请参阅 MongoDB Server 手册中的发行说明。