Docs Menu
Docs Home
/ / /
Java Sync Driver

What's New

On this page

  • What's New in 5.2
  • What's New in 5.1.3
  • What's New in 5.1.2
  • What's New in 5.1.1
  • What's New in 5.1
  • What's New in 5.0
  • What's New in 4.11
  • What's New in 4.10
  • What's New in 4.9
  • What's New in 4.8
  • What's New in 4.7.1
  • What's New in 4.7
  • What's New in 4.6
  • What's New in 4.5.1
  • What's New in 4.5
  • What's New in 4.4
  • What's New in 4.3
  • What's New in 4.2
  • What's New in 4.1
  • What's New in 4.0

Learn what's new in:

  • Version 5.2

  • Version 5.1.3

  • Version 5.1.2

  • Version 5.1.1

  • Version 5.1

  • Version 5.0

  • Version 4.11

  • Version 4.10

  • Version 4.9

  • Version 4.8

  • Version 4.7.1

  • Version 4.7.0

  • Version 4.6

  • Version 4.5.1

  • Version 4.5

  • Version 4.4

  • Version 4.3

  • Version 4.2

  • Version 4.1

  • Version 4.0

New features of the 5.2 driver release include:

  • A forward-slash (/) character between the host names and client options in a connection URI is optional. The driver parses the following connection URI examples in the same way:

    // Connection URI with delimiting forward-slash
    String uri = "mongodb://example.com/?w=majority";
    // Connection URI without delimiting forward-slash
    String uri = "mongodb://example.com?w=majority";
  • Adds the SearchIndexType class, which you can pass when constructing a SearchIndexModel instance. This change allows you to specify the index type when creating an Atlas Search or Vector Search index. To learn more, see Atlas Search and Vector Search Indexes in the Indexes guide.

  • Delegates the implementation of the algorithms that implement the SCRAM-SHA-1 and SCRAM-SHA-256 authentication mechanisms to the configured JCA provider. This change means that your application can use a configured FIPS-compliant JCA provider to provide a higher level of security.

  • Revises the mongodb-crypt dependency versioning to match the versioning for the JVM drivers. Future versions of mongodb-crypt will be released alongside the driver and will share the same version number. You must upgrade your mongodb-crypt dependency to v5.2.0 when upgrading your driver for this release. To learn more, see the In-Use Encryption guide.

  • Performance improvements due to implementation of native cryptography on all supported platforms. The following list describes the actions needed to implement this improvement depending on your operating system:

    • Windows: Upgrade your mongodb-crypt version to v5.2.0.

    • Mac: Upgrade your mongodb-crypt version to v5.2.0.

    • Linux: Install libmongocrypt.so directly on the file system, instead of using the file that is bundled within the mongodb-crypt JAR file. You can find Linux instructions to install libmongocrypt in the Server manual. If you use a package manager to install libmongocrypt, Java Native Access (JNA) will find it there without further configuration. Alternatively, you can specify the search path by setting the LD_LIBRARY_PATH environment variable to the file path of the libmongocrypt package.

      We recommend direct installation because the bundled shared library does not link with OpenSSL due to the potential for OpenSSL binary incompatibilities.

      The shared library loading is handled by JNA. You can view the rules for library loading search path order in the NativeLibrary class documentation.

  • Fixes an issue that caused the InsertOneResult.getInsertedId() and InsertManyResult.getInsertedIds() methods to return incorrect document IDs in some situations. This change is backported to Java driver v5.1.4 and v4.11.4.

  • When a sharded cluster operation is unsuccessful, the driver avoids selecting the same mongos server for operation retry attempts if other mongos servers are available.

  • Adds reachability metadata needed when your application uses GraalVM Native Image. This metadata replaces the need for collecting reachability metadata when using the driver libraries. To learn more, see Reachability Metadata in the GraalVM documentation.

    This change does not add the libjnidispatch and libmongocrypt resource entries, because adding entries for all supported platforms (targets) significantly affects the size of native executables built using GraalVM Native Image. View this sample resource-config.json file in the driver GitHub repository to see how to specify these entries explicitly if your application depends on the org.mongodb:mongodb-crypt library.

  • Enables exact vector search by extending the VectorSearchOptions API to introduce the following specific option subtypes:

    • ExactVectorSearchOptions: Use this options type to enable precise matching, ensuring that results are the closest vectors to a given query vector.

    • ApproximateVectorSearchOptions: Use this options type to enable searches that might not return the exact closest vectors. You can pass a numCandidates parameter when instantiating this type to specify the number of nearest neighbors to consider.

    To learn more about using the Atlas Vector Search feature, see Atlas Vector Search in the Aggregates Builders guide.

The 5.1.3 driver patch release includes the following changes:

  • Fixes an issue that could cause assertion errors when using Cursor types.

The 5.1.2 driver patch release includes the following changes:

  • Fixes an issue that prevents the driver from encoding and decoding concrete classes that extend generic base classes, in cases that you specify the base class as the generic type of the MongoCollection instance.

  • Fixes an issue related to how domain names are validated when you use SOCKS5 proxy functionality, allowing you to use domain names with more than six characters in the top-level domain.

The 5.1.1 driver patch release includes the following changes:

  • When using the MONGODB-OIDC authentication mechanism, you must not include comma characters in the authMechanismProperties connection string value. To learn more about this behavior, see the MONGODB-OIDC section of the Enterprise Authentication guide.

  • Optimizes GridFS throughput by removing redundant byte array cloning. The GridFSDownloadStream and GridFSUploadStream types use the BsonDocument type instead of Document.

Warning

Deprecations in this release

To avoid breaking changes in future major releases of the driver, replace any application code that depends on deprecated program elements.

This section includes the following information:

  • Support for MongoDB Server v3.6 is deprecated and will be removed in the next driver version release. To learn how to upgrade your MongoDB Server deployment, see Release Notes in the MongoDB Server manual.

  • Internal testing of GraalVM native image technology. These tests involve building native applications by using the GraalVM native-image tool.

  • Enhanced support for the MONGODB-OIDC authentication mechanism. For more information about OIDC, see the MONGODB-OIDC section of the Enterprise Authentication Mechanisms guide.

  • Introduces the serverMonitoringMode connection URI option. For more information about this option, see the Connection Options guide.

Warning

Breaking changes in this release

This driver version introduces breaking changes. For a list of these changes, see the Version 5.0 Breaking Changes section in the Upgrade guide.

Warning

Deprecations in this release

To avoid breaking changes in future major releases of the driver, replace any application code that depends on deprecated program elements.

This section includes the following information:

  • The org.mongodb.scala.Observable.completeWithUnit() method is deprecated. This method is not useful anymore because the driver now exposes org.mongodb.scala.Observable[Unit] instead of org.mongodb.scala.Observable[Void]. This relates to a breaking change about Observables in this release.

  • The getElapsedTime() method on com.mongodb.event.ConnectionReadyEvent includes the time taken to deliver the ConnectionCreatedEvent. That is, the time returned includes the duration of the com.mongodb.event.ConnectionPoolListener.connectionCreated() method.

    The getElapsedTime() methods on com.mongodb.event.ConnectionCheckedOutFailedEvent and com.mongodb.event.ConnectionCheckedOutEvent include the time taken to deliver the com.mongodb.event.ConnectionCheckOutStartedEvent. That is, the time returned includes the duration of the com.mongodb.eventConnectionPoolListener.connectionCheckOutStarted() method.

The 5.0 driver release introduces the following features:

  • Adds support for the authorizedCollection option of the listCollections command. This was done by changing the com.mongodb.client.MongoDatabase.listCollectionNames() methods. The return type is now com.mongodb.client.ListCollectionNamesIterable, while previously it was a MongoIterable<String>. This change allows the return value to be configured using the ListCollectionNamesIterable.authorizedCollections() method and specifying the authorizedCollections option. Equivalent changes were made to following classes and interfaces:

    • com.mongodb.reactivestreams.client.MongoDatabase

    • org.mongodb.scala.MongoDatabase

    • com.mongodb.kotlin.client.MongoDatabase

    • com.mongodb.kotlin.client.coroutine.MongoDatabase

    These changes introduce a binary breaking change to the listCollectionsNames() method. For more information about the MongoDatabase.listCollectionNames() method and the authorizedCollections option, see the listCollections Server manual page or Get a List of Collections.

Note

The v5.0.2 patch release fixed an issue related to how domain names are validated when you use SOCKS5 proxy functionality, allowing you to use domain names with more than six characters in the top-level domain.

This section includes the following information:

Warning

Deprecations in this release

To avoid breaking changes in future major releases of the driver, replace any application code that depends on deprecated methods and types.

The 4.11 driver release deprecates the following items:

  • The getStats() and isCapped() instance methods of the DBCollection class are deprecated. The corresponding server commands are deprecated in MongoDB v6.2 and later. Use the $collStats aggregation pipeline stage to retrieve the information provided by these methods instead. You can run the aggregation as shown in the following code example:

    Cursor cursor = collection.aggregate(Arrays.asList(
    new BasicDBObject("$collStats",
    new BasicDBObject("storageStats", new BasicDBObject()))),
    AggregationOptions.builder().build()
    );

    To determine whether a collection is a capped collection, access the value of the storageStats.capped field returned by Cursor instance in the preceding example aggregation.

    To learn more about the $collStats aggregation operator, see the $collStats (aggregation) Server manual entry.

  • The following network address-related methods are deprecated and will be removed in v5.0:

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

    • The UnixServerAddress method 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.

  • The following methods and types related to the StreamFactory interface are deprecated and scheduled for removal in v5.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 by using MongoClientSettings.Builder.streamFactoryFactory(), your code might resemble the following:

    import com.mongodb.connection.netty.NettyStreamFactoryFactory;
    // ...
    MongoClientSettings settings = MongoClientSettings.builder()
    .streamFactoryFactory(NettyStreamFactoryFactory.builder().build())
    .build();

    Replace this code with the TransportSettings.nettyBuilder() as shown in the following example:

    import com.mongodb.connection.TransportSettings;
    // ...
    MongoClientSettings settings = MongoClientSettings.builder()
    .transportSettings(TransportSettings.nettyBuilder().build())
    .build();

New features of the 4.11 driver release include:

Note

The v4.11.3 patch release fixed an issue related to how domain names are validated when you use SOCKS5 proxy functionality, allowing you to use domain names with more than six characters in the top-level domain.

  • Added the getSplitEvent() method to the ChangeStreamDocument class to identify fragments of a change stream event that exceeds 16MB. You must use the aggregation stage $changeStreamSplitLargeEvent in your change stream to handle events that exceed 16MB. To learn more, see Split Large Change Stream Events.

  • Added an aggregation stage builder for $vectorSearch. To learn more, see Atlas Vector Search.

  • Added Atlas Search index management helpers. To learn more, see Atlas Search Indexes.

  • Updated Snappy and Zstd compression library dependency versions. To learn more about the current dependency versions, see Network Compression.

  • Added getElapsedTime() methods to the following classes to monitor the duration of connection pool events:

  • Support for Java 21 virtual threads and structured concurrency. The driver internals were updated to avoid unnecessary pinning of virtual threads and to preserve interrupted status of a thread, as the latter matters for structured concurrency where it is used for cancellation.

    To learn more about virtual threads, see the Virtual Threads JDK enhancement proposal. To learn more about structured concurrency, see the Structured Concurrency JDK enhancement proposal.

  • Updated API documentation for the following types:

New features of the 4.10 driver release include:

  • Implementation of the Accumulators.percentile() and Accumulators.median() methods for statistical aggregations.

  • Interfaces in the com.mongodb.client.model.search package are now marked as @Sealed instead of @Evolving. Sealed interfaces must not be extended or implemented by consumers of the library.

  • Resolved an issue where the driver emitted duplicate log messages for retry operations. The driver now correctly emits one log message for each retry operation.

  • The org.bson.codecs.Parameterizable interface is deprecated. 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.

  • Support for custom DNS resolvers.

  • Support for Queryable Encryption (QE). To learn more about the requirements for using the QE feature, see the Queryable Encryption Driver Compatibility Table.

Important

Aggregation Expression Operations Are in Beta

This driver version introduces an API for creating aggregation expressions. This feature is in beta phase.

New features of the 4.9 driver release include:

  • Added a new exception to identify when a constructor annotated by BsonCreator contains parameters with annotations other than BsonProperty or BsonId.

  • Changed the log message format for command monitoring messages reported by the org.mongodb.driver.protocol.command package.

  • Added support for the $documents aggregation pipeline stage to the Aggregates helper class.

  • Added MongoClientSettings.Builder.applyToLoggerSettings() and LoggerSettings.Builder.maxDocumentLength() methods that let you specify a maximum length for the extended JSON representation of a BSON document in a log message.

Warning

Breaking Changes in v4.8

The v4.8 driver contains breaking changes. See Version 4.8 Breaking Changes and Driver Version 4.8 Server Support Changes for more information.

Important

Deprecation Notice

The MapCodec and IterableCodec classes are deprecated. Instead of MapCodec, use MapCodecProvider. Instead of IterableCodec, use CollectionCodecProvider, or IterableCodecProvider for Iterable types that aren't Collection types.

Behavioral changes with the 4.8 driver release include:

  • Requirement that you 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.

  • Logging of new connection messages at the DEBUG level instead of at INFO.

New features of the 4.8 driver release include:

  • Support for authentication with AWS. The driver takes an optional dependency on both AWS SDK version 1 and version 2.

  • Support for obtaining credentials from the environment for both GCP and Azure for in-use encryption.

  • Support for deserialization of records containing components with generic parameters.

  • Support for deserialization of records containing components with more specific container types, such as SortedSet, NavigableMap, LinkedList, or TreeSet.

  • Support for recursive record types, records whose type definitions contain cycles.

  • Inclusion of the disambiguatedPaths field in change stream update events when the showExpandedEvents server feature is enabled on MongoDB v6.1 and later. Learn more about this field from the getDisambiguatedPaths() API documentation. Learn more about the showExpandedEvents setting from the Expanded Events server documentation.

The 4.7.1 driver patches a bug that affects Client-Side Field Level Encryption and Queryable Encryption. The bug can cause data corruption when rotating Data Encryption Keys (DEKs) encrypted with a Customer Master Key hosted on Google Cloud Key Management Service or Azure Key Vault. The bug was present in version 4.7.0 of the driver in the RewrapManyDataKey method and causes the loss of your DEKs.

Important

Back Up your Key Vault Collection

Always back up your Key Vault Collection before you rotate your DEKs. If you lose your DEKs, you lose access to all the data encrypted with those keys.

Warning

Breaking Changes in v4.7

The v4.7 driver contains breaking changes. See Version 4.7 Breaking Changes for more information.

New features of the 4.7 driver release include:

  • Added full support for MongoDB 6.0.

  • Added the following change stream support improvements:

    • Enhanced pre-image and post-image support for change streams. Change stream watch helpers now accept whenAvailable and required for the fullDocument option. See the change stream reference documentation for more information.

    • Added a new fullDocumentBeforeChange option, which accepts whenAvailable and required.

    • Change events now include a fullDocumentBeforeChange field when configured for display on your MongoDB collection.

    • Added showExpandedEvents support for change streams.

    • Added wallTime support to the ChangeStreamDocument class.

  • Added clustered index creation support.

  • Support for new features related to Queryable Encryption, including support for automatic encryption (MongoDB v6.0 Enterprise or later is required) and manual encryption.

    • Support for the new Queryable Encryption shared library, which removes the need for the mongocryptd process. The queryable encryption shared library requires org.mongodb:mongodb-crypt version 1.5.1.1 or later.

  • Added a new API for encryption key management.

  • Added builder API methods for more aggregation stages including $search/$searchMeta (Atlas only), $densify, and $fill. Learn more about these methods on the Aggregates Builder page.

  • Added the BsonExtraElements annotation that can be used with POJO encoding and decoding. BsonExtraElements enables decoding objects that might receive new fields in the future without requiring developers to explicitly map those new fields.

  • Performance optimizations including:

    • Lock-free implementations of the server session pool and the buffer pool.

    • A new cleanup implementation of DBCursor that uses Java's Cleaner API instead of finalization, available in Java 9 or later.

  • The setWindowFields builder API is no longer a beta feature. Changes in the API break both binary and source compatibility. See Version 4.7 Breaking Changes for more information.

New features of the 4.6 Java driver release include:

If the DNS server returns an NXDomain error, indicating a non-existent domain, the 4.5.1 driver no longer throws an exception.

New features of the 4.5 Java driver release include:

  • Added support for specifying custom service names of SRV resource records. See the srvServiceName setting in the Connection Options guide for more information.

  • Added support to customize UUID representation in a codec registry using the CodecRegistries.withUuidRepresentation() method.

  • Added support for overriding listener settings in ClusterSettings, ServerSettings and ConnectionPoolSettings builders.

  • All events received by ClusterListener, ServerListener, and ServerMonitorListener are now totally ordered using a happens-before relationship when the listeners are not shared by different MongoClient instances. To learn more about the happens-before ordering, see Happens-before Order in the Java Language Specification.

  • Added EnumCodec and EnumCodecProvider classes to separate codec support for enum types from the PojoCodec class. The default codec registries, which you can access from the MongoClientSettings and the Bson interfaces, now include the enum codec classes. If your application uses a custom enumeration codec and one of the default registries, ensure you order them as described in the section on overriding codecs.

  • Resolved performance issues that impacted versions 4.4 and 4.3 of the driver. Performance in this version is similar to performance in 4.2.

  • Resolved an issue in which errors originating from retrieving the cluster description weren't passed to the onError Subscriber callback

  • Resolved an issue with releasing ByteBuf instances when you connect with compression enabled.

  • Removed an unnecessary dependency on the javax.annotation.* packages from the org.mongodb.driver-core OSGi bundle.

New features of the 4.4 Java driver release include:

  • Compatibility with MongoDB 5.1 and support for Java 17

  • Added support for index hints in an AggregateIterable

  • Added support for the $merge and $out aggregation stages on secondaries

  • Use of the mergeObjects() method in the Updates builder

  • DocumentCodec does not ignore a CodecRegistry when writing to an Iterable or a Map instance

New features of the 4.3 Java driver release include:

  • Added support for the MongoDB Stable API. For more information, see our Stable API guide.

    Note

    Starting from February 2022, the Versioned API is known the Stable API. All concepts and features remain the same with this naming change.

  • Added support for connection to MongoDB Atlas Serverless Instances. For more information about setup, see our documentation on how to Create a New Serverless Instance

  • Added a builder API for the setWindowFields pipeline stage to allow the use of window operators

  • Added support for setting Netty io.netty.handler.ssl.SslContext

  • Added support for snapshot reads to ClientSession

  • Limited the rate of establishing new connections per connection pool

  • Removed most restrictions on allowed characters in the field names of documents you insert or replace. This is a behavioral change for any application that is relying on client-side enforcement of these restrictions.

The following table shows the restriction status on allowed characters in the field names of documents:

Character
Operation
Description
.
Insert and Replace
Removed restrictions on field names containing this character.
$
Insert
Removed restrictions on field names starting with this character.
$
Replace
Removed restrictions in nested documents on field names containing this character.
$
Replace
Kept restrictions in top-level documents on field names starting with this character. This prevents accidental use of a replace operation when the intention was to use an update operation.

Note

Unacknowledged writes using dollar-prefixed or dotted keys might be silently rejected by pre-5.0 servers, where some restrictions on field names are still enforced in the server.

Warning

Breaking Changes in v4.2

The v4.2 driver contains breaking changes. See Version 4.2 Breaking Changes for more information.

New features of the 4.2 Java driver release include:

  • Added Azure and GCP key stores to client-side field level encryption

  • Added Kerberos caching tickets for reuse in multiple authentication requests

  • Added MongoClients instances with MongoClientSettings or ConnectionString as the configuration

  • Use of the explain() method on find and aggregate commands

  • Added a JsonObject class to make encoding from and decoding to JSON more efficient by avoiding an intermediate Map representation

  • Added a BsonRepresentation annotation that allows you to represent the ObjectId BSON values as a String in POJO classes

  • Added a Filters.empty() method

New features of the 4.1 Java driver release include:

  • Significant reduction in client-perceived failover times during planned maintenance events

  • The update() and delete() methods now support index hints

  • The find() method supports allowDiskUse() for sorts that require too much memory to execute in RAM

  • Added support for the MONGODB-AWS authentication mechanism using Amazon Web Services (AWS) Identity and Access Management (IAM) credentials

  • Authentication requires fewer round trips to the server, resulting in faster connection setup

Warning

Breaking Changes in v4.0

The v4.0 driver contains breaking changes. See Version 4.0 Breaking Changes for more information.

This release adds no new features.

Back

Quick Reference