Upgrade Driver Versions

Version 5.0 Breaking Changes

This driver version introduces the following breaking changes:

• Introduces the following changes to the ConnectionId class:

  • The ConnectionId constructor now accepts a value of type long as its second parameter instead of type int. Similarly, the constructor now accepts a value of type Long as its third parameter instead of type Integer. Because this change breaks binary compatibility, recompile any existing code that calls the ConnectionId constructor.

  • The withServerValue() method now accepts a parameter of type long rather than type int. This change breaks binary compatibility, so you must recompile any code that calls the withServerValue() method.

  • The getServerValue() method now returns a value of type Long instead of type Integer. Similarly, the getLocalValue() method returns a value of type long instead of type int. Because this change breaks both binary and source compatibility, update any source code that uses these methods and rebuild your binary.

• Replaces the following record annotations from the org.bson.codecs.record.annotations package with annotations of the same name from the org.bson.codecs.pojo.annotations package:

  • BsonId

  • BsonProperty

  • BsonRepresentation

• Changes the data type of the timeout duration parameter in the SocketSettings.Builder.connectTimeout() and SocketSettings.Builder.readTimeout() methods. The data type of this parameter is now long instead of int.

  In earlier versions, this parameter is of type int for both methods. This change breaks binary compatibility and requires recompiling, but does not require code changes. To view an example that shows how to call SocketSettings methods, see the SocketSettings Example in the Specify MongoClient Settings guide.

• Removes the Filters.eqFull() method, released exclusively in Beta, which allowed you to construct an equality filter when performing a vector search. You can use the Filters.eq() method when instantiating a VectorSearchOptions type, as shown in the following code:

  VectorSearchOptions opts = vectorSearchOptions().filter(eq("x", 8));

• Removes the org.mongodb.scala.ObservableImplicits.ToSingleObservableVoid implicit class. This means the org.reactivestreams.Publisher[Void] type no longer converts automatically to org.mongodb.scala.SingleObservable[Void]. The API also exposes org.mongodb.scala.Observable[Unit] instead of org.mongodb.scala.Observable[Void].

  For more information, see the Observable trait in the Scala API documentation.

• Changes how ClusterSettings computes ClusterConnectionMode, making it more consistent by using the specified replica set name, regardless of how it is configured. Previously, replica set name was only considered if it was set by the connection string.

  For example, the following two code samples both return the value ClusterConnectionMode.MULTIPLE, while previously the second one returned 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()

• Changes how BsonDecimal128 values respond to method calls, by responding in the same way as Decimal128 values. In particular, BsonDecimal128.isNumber() now returns true, and BsonDecimal128.asNumber() returns the equivalent BsonNumber.

• Removes the ServerAddress methods getSocketAddress() and getSocketAddresses().

  Instead of getSocketAddress(), use the getByName() instance method of java.net.InetAddress.

  Instead of getSocketAddresses(), use the getAllByName() instance method of java.net.InetAddress.

• Removes the UnixServerAddress methods getSocketAddress() and getUnixSocketAddress().

  Instead of getUnixSocketAddress(), construct an instance of jnr.unixsocket.UnixSocketAddress. Pass the full path of the UNIX socket file to the constructor. By default, MongoDB creates a UNIX socket file located at "/tmp/mongodb-27017.sock". To learn more about the UnixSocketAddress, see the UnixSocketAddress API documentation.

• Removes the Parameterizable interface. Instead of implementing this interface on a custom Codec type, override the CodecProvider.get() method on the codec's CodecProvider if the codec is intended for a parameterized type.

• Removes the isSlaveOk() method from the ReadPreference and TaggableReadPreference classes. To check whether a read preference allows reading from a secondary member of a replica set, use the isSecondaryOk() methods from these classes instead.

• Removes the DBCollection.getStats() and DBCollection.isCapped() helper methods for the collStats command. Instead of these methods, you can use the $collStats aggregation pipeline stage. For an example of how to use this pipeline stage, see What's New in 4.11 for the Java driver.

• Removes the MapCodec and IterableCodec classes. Instead of MapCodec, use MapCodecProvider. Instead of IterableCodec, use CollectionCodecProvider, or IterableCodecProvider for Iterable types that aren't Collection types.

• Removes the sharded() and nonAtomic() methods from the MapReducePublisher and MapReduceIterable classes.

• Removes the following methods for use with geoHaystack indexes:

  • Indexes.geoHaystack()

  • IndexOptions.getBucketSize()

  • IndexOptions.bucketSize()

  Instead, you can use the $geoNear aggregation pipeline stage or a geospatial query operator on a 2d index. For more information, see the Geospatial Queries page in the MongoDB Server manual.

• Removes the oplogReplay option from find operations. This includes the following methods:

  • DBCursor.oplogReplay()

  • DBCollectionFindOptions.isOplogReplay()

  • DBCollectionFindOptions.oplogReplay()

  • FindPublisher.oplogReplay()

  • FindIterable.oplogReplay()

• Removes the following Exception constructors:

  • MongoBulkWriteException(BulkWriteResult, List<BulkWriteError>, WriteConcernError, ServerAddress)

  • MongoCursorNotFoundException(long, ServerAddress)

  • MongoQueryException(ServerAddress, int, String)

  • MongoQueryException(ServerAddress, int, String, String)

  • MongoQueryException(MongoCommandException)

• Removes the following overloads for the BulkWriteResult.acknowledged() method:

  • acknowledged(Type, int, List<BulkWriteUpsert>)

  • acknowledged(Type, int, Integer, List<BulkWriteUpsert>)

  • acknowledged(int, int, int, Integer, List<BulkWriteUpsert>)

• Removes the following ChangeStreamDocument constructors:

  • ChangeStreamDocument(String, BsonDocument, BsonDocument, BsonDocument, TDocument, TDocument, BsonDocument, ...)

  • ChangeStreamDocument(String, BsonDocument, BsonDocument, BsonDocument, TDocument, BsonDocument, BsonTimestamp, ...)

  • ChangeStreamDocument(OperationType, BsonDocument, BsonDocument, BsonDocument, TDocument, BsonDocument, BsonTimestamp, ...)

• Removes the following constructors for events:

  • 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)

• Removes the errorLabels option from the WriteConcernError class. This includes the addLabel() and getErrorLabels() methods and the constructor that includes an errorLabels parameter. Instead, you can use the error labels included in the MongoException object that contains the WriteConcernError.

• Removes the following classes from the com.mongodb.event package:

  • ConnectionAddedEvent

  • ConnectionPoolOpenedEvent

  • ConnectionRemovedEvent

  • ClusterListenerAdapter

  • ConnectionPoolListenerAdapter

  • ServerListenerAdapter

  • ServerMonitorListenerAdapter

  Because of these removals, the following methods were also removed from the ConnectionPoolListener interface:

  • connectionAdded

  • connectionPoolOpened

  • connectionRemoved

  For more information about the events package, see the com.mongodb.event package documentation

• Adds support for a new authorizedCollection option of the listCollections command. This introduces a breaking binary change in the MongoDatabase.listCollectionNames() methods, meaning any code using these methods must be recompiled. This change does not require any changes to source code.

• Removes the following methods and types related to the Stream interface:

  • streamFactoryFactory() method from MongoClientSettings.Builder. Use the MongoClientSettings.Builder.transportSettings() method instead.

  • getStreamFactoryFactory() method from MongoClientSettings. Use the MongoClientSettings.getTransportSettings() method instead.

  • NettyStreamFactoryFactory class. Use the NettyTransportSettings, creatable by TransportSettings.nettyBuilder() and applied through MongoClientSettings.Builder.transportSettings().

  • NettyStreamFactory class

  • AsynchronousSocketChannelStreamFactory class

  • AsynchronousSocketChannelStreamFactoryFactory class

  • BufferProvider interface

  • SocketStreamFactory class

  • Stream interface

  • StreamFactory interface

  • StreamFactoryFactory interface

  • TlsChannelStreamFactoryFactory class

Version 4.8 Breaking Changes

• The driver ends support for connecting to MongoDB Server versions v3.4 and earlier. To learn more about this change, see the Driver Version 4.8 Server 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.

Version 4.7 Breaking Changes

• 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.

Version 4.2 Breaking Changes

• 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.

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 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.

Server Version 8.1 Support Changes

You cannot use a 3.x version of the Java driver to connect to a deployment running MongoDB Server v8.1. Starting in MongoDB Server v8.1, the buildinfo command requires authentication, causing an incompatibility with the v3.x driver.

Driver Version 4.8 Server Support Changes

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.