Upgrade Driver Versions

The driver ends support for connecting to MongoDB Server versions v3.4 and earlier. To learn more about this change, see the Version 4.8 Server Release Support Changes section.

You must add an explicit dependency on the org.bson.codecs.record module if your application deploys the driver in an OSGi container and relies on the driver for encoding and decoding Java records.

The RecordCodec, implemented in v4.6, deserialized POJOs and record classes that are specified as type parameters of List or Map fields of a record as Document values instead of their respective classes. This version now deserializes them to the proper record and POJO types.

For example, the following record class definitions show a Book record that contains a List that receives a Chapter type parameter:

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

Starting in this version, the codec deserializes data in the List into Chapter record classes instead of Document values.

The setWindowFields builder API is no longer beta. The new builder breaks binary and source compatibility. See the Aggregates API documentation for information the new setWindowFields() method signatures.

If your application uses this builder in a version prior to v4.7, update your source code to use the new method signature and rebuild your binary.

The ObjectId class and its serialVersionUID 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 an InvalidClassException.

To learn more about Java Object Serialization, see the Java Documentation on Serializable Objects.

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 on BsonDocument, Document, and DbObject 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 from JAVA_LEGACY to UNSPECIFIED. Applications that store or retrieve UUID values must explicitly specify which representation to use. You can specify the representation in the uuidRepresentation property of MongoClientSettings.

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, the JAVA_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 and mongodb-driver, are no longer published. If your application relies on one of these, you must switch to either mongodb-driver-sync or mongodb-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.

The v4.8 driver drops support for MongoDB Server v3.4 and earlier. To use the v4.8 driver, your MongoDB Server must be v3.6 or later. To learn how to upgrade your MongoDB Server deployment, see Release Notes in the MongoDB Server manual.