Migrate from the Legacy API

Overview

On this page, you can identify the changes you must make to migrate from the legacy API to the current API. You can also learn about features unique to the current Java driver and the benefits of migrating to the new API.

The legacy API, packaged as the mongodb-driver-legacy JAR, contains the legacy synchronous Java driver and uses naming conventions used in earlier versions of the driver.

The current API, packaged as the mongodb-driver-sync JAR, contains the current synchronous Java driver. It features the MongoCollection interface as an entry point to CRUD operations. It does not contain the legacy API.

To perform a migration from the legacy API to the current API, ensure your code no longer references the legacy API, updating your code when necessary. Then, replace the legacy API and any uber JAR that contains it with the current API JAR in your application dependencies.

In addition to updating your application to handle any necessary changes, always check for any other differences in options and return values before moving it to production.

Current API Benefits

You can continue to use the legacy API with each new MongoDB Server release. However, the legacy API does not support any updates introduced in MongoDB Server 3.0 or later. Additionally, the legacy API lacks support for certain features of the current Java driver. Some features only available in the non-legacy API include:

• Change streams, a MongoDB Server feature designed to monitor real-time changes to a single collection, database, or deployment

• Multi-document ACID transactions, which ensure atomicity of reads and writes to multiple documents and allow for transactions across multiple operations, collections, databases, documents, and shards

• Time series collections, which store sequences of measurements over a period of time and improve query efficiency for time series data

• Queryable Encryption, which allows you to encrypt sensitive workloads and to query the encrypted data

• Java records, or concise Java classes that separate business logic from data representation and reduce boilerplate code

• Native POJO support, which provides automatic or custom mapping between MongoDB documents and Java objects

To learn about more features of the current API, see What's New.

API Changes

The following table shows the majority of the changes in class and method names between the legacy and current API.

In addition to the preceding items, consider the following changes:

• The current API uses Options classes and method chaining rather than overloaded methods.

• The current API uses relaxed JSON format by default in driver versions 4.0 and later. 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 generic type for MongoCollection in the current API is org.bson.Document. You can specify BasicDBObject as a type parameter if it eases your migration.

• In the current API, the aggregation pipeline you pass to the aggregate() method accepts a list of objects that extend the Bson interface. In the legacy API, it accepts a list of objects that extend the DBObject interface.

  The method signatures also differ between the APIs. See the following API documentation for more information:

  • aggregate() method in the current API

  • aggregate() method in the legacy API

  • Bson interface

  • DBObject interface

Frequently Asked Questions

This section answers questions that may arise about the legacy API.

{"_id": 1, "val": 1}

MongoClient client = new MongoClient(URI);
DB db = client.getDB(DATABASE);
DBCollection col = db.getCollection(COLLECTION);
// Retrieves one document in the collection and prints it
DBObject doc = col.find().one();
System.out.println(doc.toString());

MongoClient client = MongoClients.create(URI);
MongoDatabase db = client.getDatabase(DATABASE);
MongoCollection<Document> col = db.getCollection(COLLECTION);
// Prints the first document retrieved from the collection as JSON 
Document doc = col.find().first();
System.out.println(doc.toJson());

{"_id": 1, "val": 1}

MongoClientURI mongoURI = new MongoClientURI(URI,
        MongoClientOptions.builder()
                .writeConcern(WriteConcern.W1));
MongoClient client = new MongoClient(mongoURI);

MongoClientSettings options = MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString(URI))
        .writeConcern(WriteConcern.W1).build();
MongoClient client = MongoClients.create(options);