MongoTemplate

The student will learn:

At the conclusion of this lecture and related exercises, the student will be able to:

The following snippet shows a dependency declaration for MongoDB APIs.

That dependency primarily brings in dependencies that are general to Spring Data and specific to MongoDB.

That is enough to cover integration with an external MongoDB during operational end-to-end scenarios. Next we need to address the integration test environment.

MongoDB is written in C++. That means that we cannot simply instantiate MongoDB within our integration test JVM. We have at least three options:

Each should be able to do the job for what we want to do here. However,

This lecture will use the Flapdoodle Embedded Mongo setup. The following Maven dependency will bring in Flapdoodle libraries and trigger the Spring Boot Embedded MongoDB Auto Configuration

A test instance of MongoDB is downloaded and managed through a test library called Flapdoodle Embedded Mongo. It is called "embedded", but unlike H2 and other embedded Java RDBMS implementations — the only thing that is embedded about this capability is the logical management feel. The library downloads a MongoDB instance (cached), starts, and stops the instance as part of running the test. Spring Data MongoDB includes a starter that will activate Flapdoodle when running a unit integration test and it detects the library on the classpath. We can bypass the use of Flapdoodle and use an externally managed MongoDB instance by turning off the Flapdoodle starter.

There are two primary beans of interest when we connect and interact with MongoDB: MongoClient and MongoOperations/MongoTemplate.

To communicate with an explicit MongoDB server, we need to supply various properties or combine them into a single spring.data.mongodb.uri

The following example property file lists the individual properties commented out and the combined properties expressed as a URL. These will be used to automatically instantiate an injectable MongoClient and MongoTemplate instance.

The MongoDB starter takes care of declaring key MongoClient and MongoTemplate @Bean instances that can be injected into components. Generally, injection of the MongoClient will not be necessary.

Alternatively, we can inject using the interface of MongoTemplate.

By default, Spring Boot will automatically use the Embedded MongoDB and Flapdoodle test instance for our MongoDB. For development, we may want to work against a live MongoDB instance so that we can interactively inspect the database using the Mongo shell. The only way to prevent using Embedded MongoDB during testing — is to disable the starter.

The following snippet shows the command-line system property that will disable EmbeddedMongoAutoConfiguration from activating. That will leave only the standard MongoAutoConfiguration to execute and setup MongoClient using spring.data.mongodb properties.

To make things simpler, I added a conditional @Configuration class that would automatically trigger the exclusion of the EmbeddedMongoAutoConfiguration when the spring.data.mongodb.uri was present.

With the ability to turn on/off the EmbeddedMongo and MongoDB configurations, it would be nice to make this work seamlessly with profiles. We know that we can define an @ActiveProfiles for integration tests to use, but this is very static. It cannot be changed during normal build time using a command-line option.

What we can do is take advantage of the resolver option of @ActiveProfiles. Anything we list in profiles is the default. Anything that is returned from the resolver is what is used. The resolver is an instance of ActiveProfilesResolver.

I implemented a simple class based on an example from the internet from Amit Kumar. ^[2] The class will inspect the spring.profiles.active if present and return an array of strings containing those profiles. If the property does not exist, then the default options of the test class are used.

The following snippet shows how that is performed.

The following snippet shows how TestProfileResolver can be used by an integration test.

In case you got a bit lost in that testing detour, we are now at a point where we can begin interacting with our chosen MongoDB instance using an injected MongoOperations (the interface) or MongoTemplate (the implementation class).

I wanted to show you how to use the running MongoDB when we write the integration tests using MongoTemplate so that you can inspect the live DB instance with the Mongo shell while the database is undergoing changes. Refer to the previous MongoDB lecture for information on how to connect the DB with the Mongo shell.

Class properties will be mapped, by default to a field of the same name. The @Field annotation can be used to customize that behavior.

We can annotate a property with @Transient to prevent a property from being stored in the database.

Spring Data Mongo leverages constructors in the following order

Given our example, the all-args constructor will be used.

For properties not yet set by the constructor, Spring Data Mongo will set fields using the following order

MongoTemplate offers an explicit insert() that will always attempt to insert a new document without checking if the ID already exists. If the created document has a generated ID not yet assigned — then this should always successfully add a new document.

One thing to note about class mapping is that MongoTemplate adds an additional field to the document during insert. This field is added to support polymorphic instantiation of result classes.

This behavior can be turned off by configuring your own instance of MongoTemplate and following the following example.

The save() command is an "upsert" (Update or Insert) command and likely the simplest form of "upsert" provided by MongoTemplate (there are more). It can be used to insert a document if new or replace if already exists - based only on the evaluation of the ID.

remove() is another command that accepts a document as its primary input. It returns some metrics about what was found and removed.

The snippet below shows the successful removal of an existing document. The DeleteResult response document provides feedback of what occurred.

findById() will return the complete document associated with the supplied ID.

The following snippet shows an example of the document being found.

No document found does not throw an exception — just returns a null object.

exists() accepts a Query and returns a simple true or false. The query can be as simple or complex as necessary.

The following snippet looks for documents with a matching ID.

MongoTemplate was smart enough to translate the "id" property to the _id field and the String value to an ObjectId when building the criteria with a mapped class.

delete() is another command that can operate on a criteria filter.

The update() command can be used to perform actions on individual fields. The following example changes the title of the first document that matches the provided criteria. Update commands can have a minor complexity to include incrementing, renaming, and moving fields — as well as manipulating arrays.

If the document was not found and we want to be in a state where one will exist with the desired title, we could use an upsert() instead of an update().

We can express offset and limit on the Query object using skip() and limit() builder methods.

In the example below, a findOne() with skip() is performed to locate a single, random document.

We could have also expressed the command with find() and limit(1).

With offset and limit, we often need to express sort — which can get complex. Spring Data defines a Sort class that can express a sequence of properties to sort in ascending and/or descending order. That too can be assigned to the Query instance.

Spring Data provides a Pageable type that can express sort, offset, and limit — using Sort, pageSize, and pageNumber. That too can be assigned to the Query instance.

MongoDB has made a lot of great strides in scale and performance by providing flexible document structures. Individual caller commands to change a document represent separate, atomic transactions. Documents can be as large or small as one desires and should take document atomicity into account when forming document schema.

However, as of MongoDB 4.0, MongoDB supports multi-document atomic transactions if absolutely necessary. The following online resource provides some background on how to accomplish this. ^[3]

MongoDB documentation does warn against its use. So multi-document acid transactions should not be a first choice.

Since MongoDB does not support a fixed schema or enforcement of foreign references between documents, there is very little for the database to keep consistent. The primary consistency rules the database must enforce are any unique indexes — requiring that specific fields be unique within the collection.

Within the context of a single document change — MongoDB ^[4]

The durability of a Mongo transaction is a function of the number of nodes within a cluster that acknowledge a change before returning the call to the client. UNACKNOWLEDGED is fast but extremely unreliable. Other ranges, including MAJORITY at least guarantee that one or more nodes in the cluster have written the change. These are expressed using the MongoDB WriteConcern class.

MongoTemplate allows us to set the WriteConcern for follow-on MongoTemplate commands.

Durability is a more advanced topic and requires coverage of system administration and cluster setup — which is well beyond the scope of this lecture. My point of bringing this and other ACID topics up here is to only point out that the MongoTemplate offers access to these additional features.