Docs Home → Develop Applications → MongoDB Drivers → Java
Upgrade Driver Versions
On this page
Overview
In this section, you can identify the changes you need to make to your application to upgrade your driver to a new version.
Before you upgrade, perform the following actions:
Ensure the new version is compatible with the MongoDB Server versions your application connects to and the Java Runtime Environment (JRE) your application runs on. See the Java Compatibility page for this information.
Address any breaking changes between the current version of the driver your application is using and your planned upgrade version in the section on Breaking Changes below.
Tip
To minimize the amount of changes your application may require when upgrading driver versions in the future, use the Stable API.
Breaking Changes
A breaking change is a modification in a convention or behavior in a specific version of the driver that may prevent your application from working properly if not addressed before upgrading.
The breaking changes in this section are categorized by the driver version that introduced them. When upgrading driver versions, address all the breaking changes between the current and upgrade versions. For example, if you are upgrading the driver from v4.0 to v4.5, address all breaking changes from the version after v4.0 including any listed under v4.5.
Version 4.2 Breaking Changes
The
ObjectId
class and itsserialVersionUID
field were updated to use a new format that minimizes serialization compatibility issues across different versions of the driver.If an application using this version or later of the driver attempts to perform Java Object Serialization on any objects that contain an
ObjectId
and were serialized by a prior version of the driver, Java throws anInvalidClassException
.To learn more about Java Object Serialization, see the Java Documentation on Serializable Objects.
Version 4.0 Breaking Changes
Several classes and methods marked as deprecated in the 3.12 release were removed in this version.
The insert helper methods return an insert result object instead of
void
.The
toJson()
methods onBsonDocument
,Document
, andDbObject
return a relaxed JSON format instead of a strict JSON format. This makes the JSON documents more readable, but can make it more difficult to identify the BSON type information, such as the difference between a 32-bit and 64-bit integer. If your application relies on the strict JSON format, use the strict mode when reading or writing data. Learn how to specify the JSON format in the current API in the Document Data Format: Extended JSON guide.The default BSON representation of
java.util.UUID
value was changed fromJAVA_LEGACY
toUNSPECIFIED
. Applications that store or retrieve UUID values must explicitly specify which representation to use. You can specify the representation in theuuidRepresentation
property ofMongoClientSettings
.The UUID representation that you specify strictly controls how the driver decodes UUIDs. In previous versions of the driver, if you specified the
JAVA_LEGACY
representation, the driver would decode binary objects of subtypes 3 and 4 as UUIDs. In version 4.0, theJAVA_LEGACY
representation works only with subtype 3.For a list of members in the
UuidRepresentation
enum, see the v4.0 API documentation.The connection pool no longer restricts the number of wait queue threads or asynchronous tasks that require a connection to MongoDB. The application should throttle requests as necessary rather than depend on the driver to throw a
MongoWaitQueueFullException
.The driver no longer logs using the
java.util.logging
(JUL) package and only supports the SLF4J logging framework.The embedded and Android drivers were removed. If your application relies on these drivers, you must continue to use a 3.x Java driver version.
The uber JARs,
mongo-java-driver
andmongodb-driver
, are no longer published. If your application relies on one of these, you must switch to eithermongodb-driver-sync
ormongodb-driver-legacy
depending on which API the application uses. Make sure you remove the uber JARs from your dependencies.Updates to several classes introduced binary compatibility breaks, such as the method signature change to the insert helper methods. Recompile any classes that link to the driver against this version or later to ensure that they continue to work.