Docs 菜单
Docs 主页
/
客户端库
/
Scala
Docs 主页
/
客户端库
/
Scala
Docs 主页
/
客户端库
/
Scala

升级驱动程序版本

Overview

在本节中，您可以确定必须对应用程序进行哪些更改才能将驾驶员程序升级到新版本。

升级前，请执行以下操作：

  • 确保新的驾驶员版本与应用程序连接到的MongoDB Server版本以及应用程序运行所在的Java运行时环境 (JRE) 兼容。要查看兼容性信息，请参阅 兼容性页面。

  • 在“重大更改”部分中，解决应用程序正在使用的驾驶员程序的当前版本与计划升级版本之间发生的任何重大更改。要学习；了解有关MongoDB Server发布兼容性更改的更多信息，请参阅服务器版本兼容性更改部分。

提示

为了最大限度地减少将来升级驾驶员版本时应用程序可能需要的更改次数，请使用 Stable API。

重大更改

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

本节中的重大更改按引入它们的驾驶员版本进行分类。 升级驾驶员版本时，解决当前版本和升级版本之间的所有重大更改。 示例，如果您要将驾驶员从 v4.0 升级到 v4.7，解决v4.0 之后的版本中的所有重大更改。 包括为 v4.7 列出的任何内容。

版本 5.5破坏性变更

版本 5.2破坏性变更

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

  • 删除对MongoDB Server v3.6 的支持。 要学习；了解有关此更改的更多信息，请参阅驱动程序版本 5.2服务器支持更改部分。

  • 修改mongodb-crypt依赖项版本控制以匹配Java虚拟机（JVM）驱动程序的版本控制。未来版本的 mongodb-crypt 将与驾驶员一起发布，并股票相同的版本号。您必须将 mongodb-crypt 依赖项升级到 v5。2。0在为此发布升级驾驶员时。

版本 5.1破坏性变更

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

  • 使用 MONGODB-OIDC身份验证机制时，不得在 authMechanismProperties 连接string值中包含逗号字符。

版本 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() 方法的 connectTimeout 超时持续时间参数的数据类型。 此参数的数据类型现在是 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()。

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

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

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

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

    构造一个 jnr.unixsocket.UnixSocketAddress实例，而不是 getUnixSocketAddress()。将 UNIX 套接字文件的完整路径传递给构造函数。默认下， MongoDB会创建位于 "/tmp/mongodb-27017.sock" 的 UNIX 套接字文件。要学习；了解有关 UnixSocketAddress 类的更多信息，请参阅 UnixSocketAddress API文档。

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

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

  • 移除 collStats 命令的 DBCollection.getStats() 和 DBCollection.isCapped() 辅助方法。您可以使用 $collStats 聚合管道阶段来代替这些方法。

  • 删除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 选项。 以下 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包的更多信息，请参阅API文档。

  • 为 listCollections 命令添加 authorizedCollection 选项。 这在 MongoDatabase.listCollectionNames() 方法中引入了重大二进制更改。 此更改不需要对源代码进行任何更改，但您必须重新编译使用此方法的任何代码。

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

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

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

    • NettyStreamFactoryFactory 类。 而是调用 TransportSettings.nettyBuilder() 方法来创建 NettyTransportSettings对象。 然后，调用 MongoClientSettings.Builder.transportSettings() 方法以应用设置。

    • NettyStreamFactory 类。

    • AsynchronousSocketChannelStreamFactory 类。

    • AsynchronousSocketChannelStreamFactoryFactory 类。

    • BufferProvider 接口。

    • SocketStreamFactory 类。

    • Stream 接口。

    • StreamFactory 接口。

    • StreamFactoryFactory 接口。

    • TlsChannelStreamFactoryFactory 类。

版本 4.8 重大更改

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

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

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

  • RecordCodec 将指定为 List 或 Map 字段的类型参数的 POJO 和记录类反序列化为正确的记录和 POJO 类型。 以前，此编解码器将它们反序列化为 Document 值。

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

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

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

版本 4.7 重大更改

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

  • setWindowFields 构建器API不再提供beta。新的管道阶段构建器方法破坏了二进制和源代码兼容性。有关新 setWindowFields() 方法签名的信息，请参阅 Aggregates API文档。

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

版本 4.2 破坏性更改

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

  • 更新 ObjectId 类及其 serialVersionUID字段以使用新格式，最大限度地减少不同版本驾驶员之间的序列化兼容性问题。

    如果使用驾驶员版本 4.2 或更高版本的应用程序尝试对任何包含 ObjectId 且由先前版本的驾驶员序列化的对象执行Java对象序列化，Java会抛出 InvalidClassException。

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

版本 4.0 重大更改

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

  • 删除了 3.12发布中标记为已弃用的多个类和方法。

  • 修改插入辅助方法以返回 InsertOneResult 或 InsertManyResult对象，而不是 void。

  • 修改 BsonDocument、Document 和 DbObject 类中的 toJson() 方法，返回宽松JSON格式，而不是严格JSON格式。 这使JSON文档更具可读性，但更难以识别BSON类型信息，例如 32 位和 64 位整数之间的差异。 如果您的应用程序依赖于严格JSON格式，请在读取或写入数据时使用严格模式。

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

    您指定的 UUID 表示严格控制驾驶员解码 UUID 的方式。 在版本 4.0 中，JAVA_LEGACY 表示仅适用于子类型 3。 在以前版本的驾驶员中，如果指定了 JAVA_LEGACY 表示形式，驾驶员会将子类型 3 和 4 的二进制对象解码为 UUID。

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

  • 连接池不再限制需要连接MongoDB 的等待队列线程或异步任务的数量。 应用程序会根据需要限制请求，而不是依赖驾驶员来抛出 MongoWaitQueueFullException。

  • 驾驶员不再使用 java.util.logging包进行记录，仅支持 SLF4J 日志记录框架。

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

  • Java驾驶员mongo-java-driver 和 mongodb-driver 的 uber JAR 不再发布。 如果您的应用程序依赖于这些 uber JAR，请将它们作为依赖项删除并改用以下包之一：

    • 如果您的应用程序使用当前的API，请将 mongodb-driver-sync包添加为依赖项。

    • 如果您的应用程序使用旧版API，请将 mongodb-driver-legacy包添加为依赖项。

  • 有几个类引入了二进制兼容性中断，例如插入辅助方法的方法签名更改。 针对此版本或更高版本重新编译链接到驾驶员的任何类，以确保它们继续工作。

服务器版本兼容性更改

服务器发布兼容性更改是对Scala驾驶员的修改，停止支持一设立MongoDB Server版本。

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

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

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

v5.5驾驶员不再支持MongoDB Server 4.0。要使用 v5.5驾驶员，您必须连接到MongoDB Server 4.2 或更高版本。要学习；了解如何升级MongoDB Server部署，请参阅MongoDB Server手册中的发布说明。

服务器版本8.1 支持变更

您无法使用 3.x 版本的Scala驾驶员连接到运行MongoDB Server v8.1 的MongoDB 部署。 从MongoDB Server v8.1 开始，buildinfo 命令需要身份验证，从而导致与 v3.x 驾驶员。

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

v5.2驾驶员不再支持MongoDB Server 3.6。要使用 v5.2驾驶员，您必须连接到MongoDB Server 4.0 或更高版本。要学习；了解如何升级MongoDB Server部署，请参阅MongoDB Server手册中的发布说明。

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

v4.8驾驶员不再支持MongoDB Server 3.4 及更早版本。要使用 v4.8驾驶员，您必须连接到MongoDB Server 3.6 或更高版本。要学习；了解如何升级MongoDB Server部署，请参阅MongoDB Server手册中的发布说明。

后退

新增功能

来年

兼容性

在此页面上