Docs 菜单

升级驱动程序版本

在本节中,您可以确定可能需要对应用程序进行哪些更改,以将驱动程序升级到新版本。

升级前,请执行以下操作:

  • 确保新版本与应用程序连接到的 MongoDB Server 版本以及应用程序运行所在的 Java 运行时环境 (JRE) 兼容。有关此信息,请参阅 Java 兼容性页面。

  • 破坏性变更 (breaking change) 部分解决应用程序使用的驱动程序的当前版本与计划升级版本之间发生的任何破坏性变更 (breaking change)。要了解有关 MongoDB 服务器版本兼容性变更的更多信息,请参阅服务器版本兼容性变更部分。

提示

为了最大限度地减少应用程序将来升级驱动程序版本时可能需要的更改量,请使用Stable API。

破坏性变更 (breaking change) 是对特定版本驱动程序中的约定或行为的修改,如果在升级前未解决,可能会阻止应用程序正常工作。

本部分中的重大更改按引入它们的驱动程序版本进行分类。升级驱动程序版本时,请解决当前版本和升级版本之间的所有重大更改。例如,如果您要将驱动程序从 v4.0 升级到 v4.5,请解决 v4.0 之后的版本的所有重大更改,包括 v4.5 下列出的任何更改。

  • 该驾驶员不再与MongoDB Server版本 v3.6 兼容。要学习;了解有关此更改的更多信息,请参阅驱动程序版本 5.2服务器支持更改部分。

此驱动程序版本引入了以下破坏性变更 (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.InetAddressgetByName() 实例方法,而不是 getSocketAddress()

    使用 java.net.InetAddressgetAllByName() 实例方法,而不是 getSocketAddresses()

  • 删除 UnixServerAddress 方法 getSocketAddress()getUnixSocketAddress()

    构建 jnr.unixsocket.UnixSocketAddress 实例,而不是 getUnixSocketAddress()。将 UNIX 套接字文件的完整路径传递给构造函数。默认情况下,MongoDB 会创建位于 "/tmp/mongodb-27017.sock" 的 UNIX 套接字文件。要了解有关 UnixSocketAddress 的详情,请参阅 UnixSocketAddress API 文档。

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

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

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

  • 删除MapCodecIterableCodec类。 MapCodec使用MapCodecProvider ,而不是 。对于不是IterableCodec Collection类型的Iterable类型,请使用CollectionCodecProviderIterableCodecProvider ,而不是 。

  • MapReducePublisherMapReduceIterable类中删除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参数的构造函数。 相反,您可以使用包含WriteConcernErrorMongoException对象中包含的错误标签。

  • 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 类。使用 NettyTransportSettings,可由 TransportSettings.nettyBuilder() 创建并通过 MongoClientSettings.Builder.transportSettings() 应用。

    • NettyStreamFactory

    • AsynchronousSocketChannelStreamFactory

    • AsynchronousSocketChannelStreamFactoryFactory

    • BufferProvider接口

    • SocketStreamFactory

    • Stream接口

    • StreamFactory接口

    • StreamFactoryFactory接口

    • TlsChannelStreamFactoryFactory

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

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

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

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

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

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

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

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

  • ObjectId 类及其 serialVersionUID 字段已更新为使用新格式,这会最大限度减少不同版本的驱动程序之间的序列化兼容性问题。

    如果使用此版本或更高版本驱动程序的应用程序尝试对任何包含 ObjectId 且由先前版本的驱动程序序列化的对象执行 Java 对象序列化,则 Java 会引发 InvalidClassException

    如需了解有关“Java 对象序列化”的更多信息,请参阅 Java 文档中的可序列化对象部分。

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

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

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

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

    您指定的 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-drivermongodb-driver 均不再发布。如果您的应用程序依赖其中一项,则必须根据应用程序使用的 API 切换到 mongodb-driver-syncmongodb-driver-legacy。确保从依赖项中删除 uber JAR。

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

服务器版本兼容性更改是对 MongoDB Java 驱动程序的修改,不再支持一组 MongoDB 服务器版本。

该驱动程序在 MongoDB Server 版本的生命周期结束 (EOL) 后将停止支持。

要了解有关 MongoDB 支持 EOL 产品的更多信息,请参阅旧版支持政策

v5.2 驾驶员不再支持MongoDB Server v3.6 。要使用 v5.2 驾驶员,您的MongoDB Server必须是 v4.0 或更高版本。要学习;了解如何升级MongoDB Server部署,请参阅MongoDB Server手册中的发布说明。

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

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