For the most recent version of the reference documentation, see our MongoDB Java Driver documentation site.
- What's New
What’s new in 3.10
Key new features of the 3.10 Java driver release:
Native asynchronous TLS/SSL support
Previously, any use of our asynchronous drivers with TLS/SSl required the use of Netty. In 3.10, the driver supports asynchronous TLS/SSL natively, so no third-party dependency is required. To accomplish this, the driver contains code vendored from https://github.com/marianobarrios/tls-channel.
Operational improvements
When connecting with the mongodb+srv
protocol, the driver now polls DNS for changes to the SRV records when connected to a sharded
cluster. See
Polling SRV Records for Mongos Discovery
for more details.
When retryable writes are enabled, the driver now outputs log messages at DEBUG level when a retryable write is attempted. See JAVA-2964 for more details.
Codec Improvements
The driver now mutates the id property of a POJO, when inserting a document via a POJO with a null
id property of type ObjectId
. See
JAVA-2674 for more details.
JNDI
The driver now offers a JNDI ObjectFactory
implementation for creating instances of com.mongodb.client.MongoClient
, the interface
introduced in version 3.7 of the driver. See JAVA-2883 for more details.
Full list of changes
What’s new in 3.9
Key new features of the 3.9 Java driver release:
Android support
The mongodb-driver-embedded-android
module supports interaction with a MongoDB server running on an Android device.
See MongoDB Mobile for more details.
Deprecations
Numerous classes and methods have been deprecated in the 3.9 release in preparation for a major 4.0 release. See the Upgrading Guide for more information.
What’s New in 3.8
Key new features of the 3.8 Java driver release:
Transactions
The Java driver now provides support for executing CRUD operations within a transaction (requires MongoDB 4.0). See the
Transactions and MongoDB Drivers section
of the documentation and select the Java (Sync)
tab.
Change Stream enhancements
The Java driver now provides support for opening a change stream against an entire database, via new
MongoDatabase.watch
methods, or an
entire deployment, via new MongoClient.watch
methods. See
Change Streams for further details.
SCRAM-256 Authentication Mechanism
The Java driver now provides support for the SCRAM-256 authentication mechanism (requires MongoDB 4.0).
What’s New in 3.7
Key new features of the 3.7 Java driver release:
Java 9 support
Modules
The Java driver now provides a set of JAR files that are compliant with the Java 9
module specification, and Automatic-Module-Name
declarations have been added
to the manifests of those JAR files. See the Installation Guide
for information on which JAR files are now Java 9-compliant modules as well as what each of their module names is.
Note that it was not possible to modularize all the existing JAR files due to the fact that, for some of them, packages are split amongst
multiple JAR files, and this violates a core rule of the Java 9 module system which states that at most one module contains classes for any
given package. For instance, the mongodb-driver
and mongodb-driver-core
JAR files both contain classes in the com.mongodb
package,
and thus it’s not possible to make both mongodb-driver
and mongodb-driver-core
Java 9 modules. Also so-called
“uber jars” like mongo-java-driver
are not appropriate for Java 9 modularization, as they can conflict with their non-uber brethren, and
thus have not been given module names.
Note that none of the modular JAR files contain module-info
class files yet. Addition of these classes will be considered in a future
release.
New Entry Point
So that the driver can offer a modular option, a new entry point has been added to the com.mongodb.client
package.
Static methods in this entry point, com.mongodb.client.MongoClients
, returns instances of a new com.mongodb.client.MongoClient
interface. This interface, while similar to the existing com.mongodb.MongoClient
class in that it is a factory for
com.mongodb.client.MongoDatabase
instances, does not support the legacy com.mongodb.DBCollection
-based API, and thus does not suffer
from the aforementioned package-splitting issue that prevents Java 9 modularization. This new entry point is encapsulated in the new
mongodb-driver-sync
JAR file, which is also a Java 9-compliant module.
The new entry point also moves the driver further in the direction of effective deprecation of the legacy API, which is now only available
only via the mongo-java-driver
and mongodb-driver
uber-jars, which are not Java 9 modules. At this point there are no plans to offer
the legacy API as a Java 9 module.
See Connect To MongoDB for details on the new com.mongodb.client.MongoClients
and how it compares to the existing com.mongodb.MongoClient
class.
Unix domain socket support
The 3.7 driver adds support for Unix domain sockets via the jnr.unixsocket
library.
Connecting to Unix domain sockets is done via the ConnectionString
or via
UnixServerAddress
.
PojoCodec improvements
The 3.7 release brings support for Map<String, Object>
to the POJO Codec
.
JSR-310 Instant, LocalDate & LocalDateTime support
Support for Instant
, LocalDate
and LocalDateTime
has been added to the driver. The MongoDB Java drivers team would like to thank
Cezary Bartosiak for their excellent contribution to the driver. Users needing alternative data structures
and / or more flexibility regarding JSR-310 dates should check out the alternative JSR-310 codecs provider by Cezary:
bson-codecs-jsr310.
JSR-305 NonNull annotations
The public API is now annotated with JSR-305 compatible @NonNull
and @Nullable
annotations. This will allow programmers
to rely on tools like FindBugs/SpotBugs, IDEs like IntelliJ IDEA, and compilers like the Kotlin compiler to find errors in the use of the
driver via static analysis rather than via runtime failures.
Improved logging of commands
When the log level is set to DEBUG for the org.mongodb.driver.protocol.command
logger, the driver now logs additional information to aid
in debugging:
- Before sending the command, it logs the full command (up to 1000 characters), and the request id.
- After receive a response to the command, it logs the request id and elapsed time in milliseconds.
Here’s an example
10:37:29.099 [cluster-ClusterId {value='5a466138741fc252712a6d71', description='null'}-127.0.0.1:27017] DEBUG org.mongodb.driver.protocol.command -
Sending command '{ "ismaster" : 1, "$db" : "admin" } ...' with request id 4 to database admin on connection [connectionId{localValue:1, serverValue:1958}] to server 127.0.0.1:27017
10:37:29.104 [cluster-ClusterId{value='5a466138741fc252712a6d71', description='null'}-127.0.0.1:27017] DEBUG org.mongodb.driver.protocol.command -
Execution of command with request id 4 completed successfully in 22.44 ms on connection [connectionId {localValue:1, serverValue:1958}] to server 127.0.0.1:27017
Improved support for “raw” documents
When working with “raw” BSON for improved performance via the RawBsonDocument
, the efficiency
of accessing embedded documents and arrays has been drastically improved by returning raw slices of the containing document or array. For
instance
RawBsonDocument doc = new RawBsonDocument(bytes);
// returns a RawBsonDocument that is a slice of the bytes from the containing doc
BsonDocument embeddedDoc = doc.getDocument("embeddedDoc");
// returns a RawBsonArray that is a slice of the bytes from the containing doc
BsonArray embeddedArray = doc.getArray("embeddedArray");
// returns a RawBsonDocument that is a slice of the bytes from the containing array
BsonDocument embeddedDoc2 = (BsonDocument) embeddedArray.get(0);
What’s New in 3.6
Key new features of the 3.6 Java driver release:
Change Stream support
The 3.6 release adds support for change streams.
Retryable writes
The 3.6 release adds support for retryable writes using the retryWrites
option in
MongoClientOptions
.
Compression
The 3.6 release adds support for compression of messages to and from appropriately configured MongoDB servers:
Causal consistency
The 3.6 release adds support for causally consistency via the new
ClientSession
API.
Application-configured server selection
The 3.6 release adds support for application-configured control over server selection, using the serverSelector
option in
MongoClientOptions
.
POJO Codec improvements
The 3.6 release brings new improvements to the POJO Codec
:
- Improved sub-class and discriminator support.
- Support for custom Collection and Map implementations.
- Improvements to the
BsonCreator
annotation, which now supports@BsonId
and@BsonProperty
with values that represent the read name of the property. - A new
PropertyCodecProvider
API, allowing for easy and type-safe handling of container types. - Added the
SET_PRIVATE_FIELDS_CONVENTION
convention. - Added the
USE_GETTERS_FOR_SETTERS
convention.
The MongoDB Java drivers team would like to thank both Joseph Florencio and Qi Liu for their excellent contributions to the PojoCodec.
What’s New in 3.5
Key new features of the 3.5 Java driver release:
Native POJO support
The 3.5 release adds support for POJO serialization at the BSON layer, and can be used by the synchronous and asynchronous drivers. See the POJO Quick start pages for details.
Improved JSON support
The 3.5 release improves support for JSON parsing and generation.
- Implements the new Extended JSON specification
- Implements custom JSON converters to give applications full control over JSON generation for each BSON type
See the JSON reference for details.
Connection pool monitoring
The 3.5 release adds support for monitoring connection pool-related events.
SSLContext configuration
The 3.5 release supports overriding the default javax.net.ssl.SSLContext
used for SSL connections to MongoDB.
KeepAlive configuration deprecated
The 3.5 release deprecated socket keep-alive settings, also socket keep-alive checks are now on by default. It is strongly recommended that system keep-alive settings should be configured with shorter timeouts.
See the ‘does TCP keep-alive time affect MongoDB deployments?’ documentation for more information.
What’s New in 3.4
The 3.4 release includes full support for the MongoDB 3.4 server release. Key new features include:
Support for Decimal128 Format
import org.bson.types.Decimal128;
The Decimal128 format supports numbers with up to 34 decimal digits (i.e. significant digits) and an exponent range of −6143 to +6144.
To create a Decimal128
number, you can use
Decimal128.parse()
with a string:Decimal128.parse("9.9900");
new Decimal128()
with a long:new Decimal128(10L);
new Decimal128()
with ajava.math.BigDecimal
:new Decimal128(new BigDecimal("4.350000"));
Support for Collation
import com.mongodb.client.model.Collation;
Collation allows users to specify language-specific rules for string
comparison.
Use the Collation.builder()
to create the Collation
object. For example, the following example creates a Collation
object with Primary level of comparison and locale fr
.
Collation.builder().collationStrength(CollationStrength.PRIMARY).locale("fr").build()));
You can specify collation at the collection level, at an index level, or at a collation-supported operation level:
Collection Level
To specify collation at the collection level, pass a Collation
object as an option to the createCollection()
method. To specify options to the createCollection
method, use the CreateCollectionOptions
class.
database.createCollection("myColl", new CreateCollectionOptions().collation(
Collation.builder()
.collationStrength(CollationStrength.PRIMARY)
.locale("fr").build()));
Index Level
To specify collation for an index, pass a Collation
object as an option to the createIndex()
method. To specify index options, use the IndexOptions class.
IndexOptions collationIndexOptions = new IndexOptions().name("collation-fr")
.collation(Collation.builder()
.collationStrength(CollationStrength.SECONDARY)
.locale("fr").build());
collection.createIndex(
Indexes.ascending("name"), collationIndexOptions);
Operation Level
The following operations support collation by specifying the
Collation
object to their respective Iterable object.
MongoCollection.aggregate()
MongoCollection.distinct()
MongoCollection.find()
MongoCollection.mapReduce()
For example:
Collation collation = Collation.builder()
.collationStrength(CollationStrength.SECONDARY)
.locale("fr").build();
collection.find(Filters.eq("category", "cafe")).collation(collation);
collection.aggregate(Arrays.asList(
Aggregates.group("$category", Accumulators.sum("count", 1))))
.collation(collation);
The following operations support collation by specifying the
Collation
object as an option using the corresponding option class
for the method:
MongoCollection.count()
MongoCollection.deleteOne()
MongoCollection.deleteMany()
MongoCollection.findOneAndDelete()
MongoCollection.findOneAndReplace()
MongoCollection.findOneAndUpdate()
MongoCollection.updateOne()
MongoCollection.updateMany()
MongoCollection.bulkWrite()
for:DeleteManyModel
andDeleteOneModel
usingDeleteOptions
to specify the collationReplaceOneModel
,UpdateManyModel
, andUpdateOneModel
usingUpdateOptions
to specify the collation.
For example:
Collation collation = Collation.builder()
.collationStrength(CollationStrength.SECONDARY)
.locale("fr").build();
collection.count(Filters.eq("category", "cafe"), new CountOptions().collation(collation));
collection.updateOne(Filters.eq("category", "cafe"), set("stars", 1),
new UpdateOptions().collation(collation));
collection.bulkWrite(Arrays.asList(
new UpdateOneModel<>(new Document("category", "cafe"),
new Document("$set", new Document("x", 0)),
new UpdateOptions().collation(collation)),
new DeleteOneModel<>(new Document("category", "cafe"),
new DeleteOptions().collation(collation))));
For more information on collation, including the supported locales, refer to the manual.
Other MongoDB 3.4 features
- Support for specification of maximum staleness for secondary reads
- Support for the MongoDB handshake protocol.
- Builders for eight new aggregation pipeline stages
- Helpers for creating read-only views
- Support for the linearizable read concern
Support for JNDI
The synchronous driver now includes a JNDI ObjectFactory implementation.
Upgrading
See the upgrading guide on how to upgrade to 3.5.