升级驱动程序版本
Overview
在本节中,您可以确定可能需要对应用程序进行哪些更改,以将驱动程序升级到新版本。
升级前,请执行以下操作:
确保新版本与应用程序连接到的 MongoDB Server 版本以及应用程序运行所在的 Java 运行时环境 (JRE) 兼容。有关此信息,请参阅 Java 兼容性页面。
在破坏性变更 (breaking change) 部分解决应用程序使用的驱动程序的当前版本与计划升级版本之间发生的任何破坏性变更 (breaking change)。要了解有关 MongoDB 服务器版本兼容性变更的更多信息,请参阅服务器版本兼容性变更部分。
提示
为了最大限度地减少应用程序将来升级驱动程序版本时可能需要的更改量,请使用Stable API。
重大更改
破坏性变更 (breaking change) 是对特定版本驱动程序中的约定或行为的修改,如果在升级前未解决,可能会阻止应用程序正常工作。
本部分中的重大更改按引入它们的驱动程序版本进行分类。升级驱动程序版本时,请解决当前版本和升级版本之间的所有重大更改。例如,如果您要将驱动程序从 v4.0 升级到 v4.5,请解决 v4.0 之后的版本的所有重大更改,包括 v4.5 下列出的任何更改。
版本 5.2破坏性变更
该驾驶员不再与MongoDB Server版本 v3.6 兼容。要学习;了解有关此更改的更多信息,请参阅驱动程序版本 5.2服务器支持更改部分。
版本 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()
。构建
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
聚合管道阶段来代替这些方法。有关如何使用此管道阶段的示例,请参阅 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
类。使用NettyTransportSettings
,可由TransportSettings.nettyBuilder()
创建并通过MongoClientSettings.Builder.transportSettings()
应用。NettyStreamFactory
类AsynchronousSocketChannelStreamFactory
类AsynchronousSocketChannelStreamFactoryFactory
类BufferProvider
接口SocketStreamFactory
类Stream
接口StreamFactory
接口StreamFactoryFactory
接口TlsChannelStreamFactoryFactory
类
版本 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。对多个类的更新引入了二进制兼容性中断,例如插入辅助方法的方法签名更改。针对此版本或更高版本重新编译所有链接到驱动程序的类,以确保它们继续运行。
服务器版本兼容性更改
服务器版本兼容性更改是对 MongoDB Java 驱动程序的修改,不再支持一组 MongoDB 服务器版本。
该驱动程序在 MongoDB Server 版本的生命周期结束 (EOL) 后将停止支持。
要了解有关 MongoDB 支持 EOL 产品的更多信息,请参阅旧版支持政策。
驱动程序版本5.2 服务器支持变更
v5.2 驾驶员不再支持MongoDB Server v3.6 。要使用 v5.2 驾驶员,您的MongoDB Server必须是 v4.0 或更高版本。要学习;了解如何升级MongoDB Server部署,请参阅MongoDB Server手册中的发布说明。
服务器版本8.1 支持变更
您无法使用3 .x 版本的Java驾驶员连接到运行MongoDB Server v 8.1的部署。 从MongoDB Server v 8.1开始, buildinfo
命令需要身份验证,导致与 v 3不兼容。 驾驶员。
驱动程序版本4.8 服务器支持变更
v4.8 驱动程序不再支持 MongoDB Server v3.4 及更早版本。如要使用 v4.8 驱动程序,您的 MongoDB Server 必须是 v3.6 或更新版本。如要了解如何升级 MongoDB Server 部署,请参阅 MongoDB Server 手册中的发行说明。