Explore Developer Center's New Chatbot! MongoDB AI Chatbot can be accessed at the top of your navigation to answer all your MongoDB questions.

Join us at AWS re:Invent 2024! Learn how to use MongoDB for AI use cases.
MongoDB Developer
Java
plus
Sign in to follow topics
MongoDB Developer Centerchevron-right
Developer Topicschevron-right
Languageschevron-right
Javachevron-right

Java Driver: Migrating From 4.11 to 5.0

Maxime Beugnet3 min read • Published Mar 01, 2024 • Updated Mar 01, 2024
MongoDBJava
Facebook Icontwitter iconlinkedin icon
Rate this article
star-empty
star-empty
star-empty
star-empty
star-empty

Introduction

The MongoDB Java driver 5.0.0 is now available!
While this version doesn't include many new features, it's removing a lot of deprecated methods and is preparing for the future.

How to upgrade

  • Ensure your server version is compatible with Java Driver 5.0.
  • Compile against the 4.11 version of the driver with deprecation warnings enabled.
  • Remove deprecated classes and methods.

Maven

1<dependency>
2 <groupId>org.mongodb</groupId>
3 <artifactId>mongodb-driver-sync</artifactId>
4 <version>5.0.0</version>
5</dependency>

Gradle

1implementation group: 'org.mongodb', name: 'mongodb-driver-sync', version: '5.0.0'

New features

You can read the full list of new features but here is a summary.

getElapsedTime()

The behavior of the method getElapsedTime() was modified in the following classes:
1com.mongodb.event.ConnectionReadyEvent
2com.mongodb.event.ConnectionCheckedOutFailedEvent
3com.mongodb.event.ConnectionCheckedOutEvent
If you are using one of these methods, make sure to recompile and read the details.

authorizedCollection option

5.0.0 adds support for the authorizedCollection option of the listCollections command.

Scala

The org.mongodb.scala.Observable.completeWithUnit() method is now marked deprecated.

Breaking changes

One of the best ways to identify if your code will require any changes following the upgrade to Java Driver 5.0 is to compile against 4.11.0 with deprecation warnings enabled and remove the use of any deprecated methods and classes.
You can read the full list of breaking changes but here is a summary.

StreamFactoryFactory and NettyStreamFactoryFactory

The following methods and classes have been removed in 5.0.0:
  • streamFactoryFactory() method from MongoClientSettings.Builder
  • getStreamFactoryFactory() method from MongoClientSettings
  • NettyStreamFactoryFactory class
  • NettyStreamFactory class
  • AsynchronousSocketChannelStreamFactory class
  • AsynchronousSocketChannelStreamFactoryFactory class
  • BufferProvider class
  • SocketStreamFactory class
  • Stream class
  • StreamFactory class
  • StreamFactoryFactory class
  • TlsChannelStreamFactoryFactory class
If you configure Netty using the streamFactoryFactory(), your code is probably like this:
1import com.mongodb.connection.netty.NettyStreamFactoryFactory;
2// ...
3MongoClientSettings settings = MongoClientSettings.builder()
4 .streamFactoryFactory(NettyStreamFactoryFactory.builder().build())
5 .build();
Now, you should use the TransportSettings.nettyBuilder():
1import com.mongodb.connection.TransportSettings;
2// ...
3MongoClientSettings settings = MongoClientSettings.builder()
4 .transportSettings(TransportSettings.nettyBuilder().build())
5 .build();

ConnectionId

In 4.11, the class ConnectionId was using integers.
1@Immutable
2public final class ConnectionId {
3 private static final AtomicInteger INCREMENTING_ID = new AtomicInteger();
4
5 private final ServerId serverId;
6 private final int localValue;
7 private final Integer serverValue;
8 private final String stringValue;
9 // ...
10}
1@Immutable
2public final class ConnectionId {
3 private static final AtomicLong INCREMENTING_ID = new AtomicLong();
4 private final ServerId serverId;
5 private final long localValue;
6 @Nullable
7 private final Long serverValue;
8 private final String stringValue;
9// ...
10}
While this should have a very minor impact on your code, it's breaking binary and source compatibility. Make sure to rebuild your binary and you should be good to go.

Package update

Three record annotations moved from:
1org.bson.codecs.record.annotations.BsonId
2org.bson.codecs.record.annotations.BsonProperty
3org.bson.codecs.record.annotations.BsonRepresentation
To:
1org.bson.codecs.pojo.annotations.BsonId
2org.bson.codecs.pojo.annotations.BsonProperty
3org.bson.codecs.pojo.annotations.BsonRepresentation
So if you are using these annotations, please make sure to update the imports and rebuild.

SocketSettings is now using long

The first parameters of the two following builder methods in SocketSettings are now using a long instead of an integer.
1public Builder connectTimeout(final long connectTimeout, final TimeUnit timeUnit) {/*...*/}
2public Builder readTimeout(final long readTimeout, final TimeUnit timeUnit){/*...*/}
This breaks binary compatibility but shouldn't require a code change in your code.

Filters.eqFull()

Filters.eqFull() was only released in Beta for vector search. It's now deprecated. Use Filters.eq() instead when instantiating a VectorSearchOptions.
1VectorSearchOptions opts = vectorSearchOptions().filter(eq("x", 8));

ClusterConnectionMode

The way the driver is computing the ClusterConnectionMode is now more consistent by using a specified replica set name, regardless of how it's configured.
In the following example, both the 4.11 and 5.0.0 drivers were returning the same thing: ClusterConnectionMode.MULTIPLE.
1ClusterSettings.builder()
2 .applyConnectionString(new ConnectionString("mongodb://127.0.0.1:27017/?replicaSet=replset"))
3 .build()
4 .getMode();
But in this example, the 4.11 driver was returning ClusterConnectionMode.SINGLE instead of ClusterConnectionMode.MULTIPLE.
1ClusterSettings.builder()
2 .hosts(Collections.singletonList(new ServerAddress("127.0.0.1", 27017)))
3 .requiredReplicaSetName("replset")
4 .build()
5 .getMode();

BsonDecimal128

The behaviour of BsonDecimal128 is now more consistent with the behaviour of Decimal128.
1BsonDecimal128.isNumber(); // returns true
2BsonDecimal128.asNumber(); // returns the BsonNumber

Conclusion

With the release of MongoDB Java Driver 5.0.0, it's evident that the focus has been on refining existing functionalities, removing deprecated methods, and ensuring compatibility for future enhancements. While the changes may necessitate some adjustments in your codebase, they pave the way for a more robust and efficient development experience.
Ready to upgrade? Dive into the latest version of the MongoDB Java drivers and start leveraging its enhanced capabilities today!
To finish with, don't forget to enable virtual threads in your Spring Boot 3.2.0+ projects! You just need to add this in your application.properties file:
1spring.threads.virtual.enabled=true
Got questions or itching to share your success? Head over to the MongoDB Community Forum – we're all ears and ready to help!
Top Comments in Forums
There are no comments on this article yet.
Start the Conversation

Facebook Icontwitter iconlinkedin icon
Rate this article
star-empty
star-empty
star-empty
star-empty
star-empty
Related
Quickstart

Java - Change Streams


Oct 01, 2024 | 10 min read
Tutorial

Implementing Bulk Writes using Spring Boot for MongoDB


Mar 22, 2023 | 3 min read
Quickstart

Introduction to MongoDB and Helidon


Nov 12, 2024 | 6 min read
Article

Using Atlas Search from Java


Jul 14, 2023 | 13 min read
Table of Contents
  • Introduction