Quarkus Extension for MicroStream

MicroStream is a small and easy-to-learn library that provides you with an alternative data storage solution that is really fast and uses any POJO class you need.

It is built with no specific framework in mind, only using pure Java SE and the SLF4J API for logging. This makes it possible to use it within any of the popular frameworks of today like Spring Boot, Quarkus, Jakarta EE, or Kotlin Ktor.

To make use of the specific features of a framework, we have some integrations available. And with the release of version 8.0 of MicroStream, we have released an integration for Quarkus.

This blog describes how you can make use of the integration and what functionality it provides for your application.

Goal

Just as with any of the other integrations we have, the one for Quarkus has the same 3 main goals

– Use the configuration options that the framework provides. In the case of Quarkus, the configuration values are also read from any of the supported sources by Quarkus
– Identify the Root object through an annotation and expose it as a CDI bean
– Expose the StorageManager as a CDI bean and allow programmatic configuration of the StorageFoundation through a CDI bean.
– Allow for initialisation of the data storage when this is empty or each time the application starts up.

Add MicroStream extension

There are several options on how you can add the MicroStream extension for Quarkus to your project.

If you are using the Quarkus CLI, you use the `add-extension` option to add the required dependency

quarkus add-extension -e one.microstream:microstream-quarkus-extension:08.00.00-MS-GA

When using a Maven project, you can use the Quarkus Maven plugin to add the dependency

mvn quarkus:add-extension -Dextensions="one.microstream:microstream-quarkus-extension:08.00.00-MS-GA"

Or just add the dependency to your project, as that is the only action that is done by the previous commands.

<dependency>
   <groupId>one.microstream</groupId>
   <artifactId>microstream-quarkus-extension</artifactId>
   <version>08.00.00-MS-GA</version>
</dependency>

Configuration of MicroStream

Due to the extension, configuration values are retrieved through the Quarkus configuration options. This means that the values can be defined in any source that is supported by Quarkus, like environment variables but also the supported extensions like Hashcorp vault, Zookeeper, etc …

The keys of the values all start with one.microstream. and all the keys that are supported by MicroStream by default and which are listed on this documentation page.

Since dashes (-) are not always supported by each configuration source, you can also use a dot (.) instead of a dash.

Besides this declarative configuration, you also have the option to programmatic adapt the configuration by using the EmbeddedStorageFoundation instance.

This can be done by creating a CDI class that implements the EmbeddedStorageFoundationCustomizer interface which has a single method. This method is called after the configuration values are read and the foundation instance is passed to the method of these CDI instances. This allows the developer to fine-tune the configuration like adding the binary handlers for the new collections of JDK 12+.

@ApplicationScoped
public class FoundationCustomizer implements EmbeddedStorageFoundationCustomizer {

   @Override
   public void customize(EmbeddedStorageFoundation embeddedStorageFoundation) {
   }
}

Define the Root object

Since the setup of the StorageManager happens behind the scenes, it is nice if you could indicate which class provides you the root instance of the object graph that you consider to hold all your data.
You can programmatically define this using the EmbeddedStorageFoundationCustomizer I mentioned earlier, but you can just add the @Storage annotation to a class.

@Storage
public class DataRoot {
}

This annotation defined in the extension, has 2 purposes. First of all, it signals to the extension that an instance of this class needs to be used when there is no data yet in the storage and the root is actually null. The extension initialises a default instance and registers it as the root within MicroStream;

But it also exposes it as a CDI bean within Quarkus. Not only at first usage of your application but the class instance, linked to MicroStream as root, is made available as a CDI bean instance.

This means that you can inject this root in any CDI bean and allows you to have access to your data everywhere you might need it like service instances.

Also, the StorageManager is exposed as a CDI bean and thus store operations can also be initiated very easily.

Initialise data

Another useful feature is that you can initialise the data within your root object. This is handy when you start up your application for the first time and there is no data yet in the storage, or even each time you startup and want to perform some actions that are related to your data.

It works similarly to the customizer we saw earlier, but this time you need a CDI bean that implements the StorageManagerInitializer interface.

@ApplicationScoped
public class RootPreparation implements StorageManagerInitializer {

   @Override
   public void initialize(StorageManager storageManager) {
   }
}

The single method has a StorageManager parameter and is called by the extension right after the moment that the manager is started. From this StorageManager you can access the root object and perform any action you see fit with your data structures.

Conclusion

The integration combines the functionality of MicroStream and Quarkus. MicroStream configuration is read through the Quarkus configuration sources, programmatic tuning of the config is possible and root and StorageManager are available as CDI bean.

The extension supports Quarkus 2.x. A version compatible with Quarkus 3 is already in our code repository and will be released later.

Various examples of different kinds of usage patterns of the Quarkus extension can be found in this repository.

Watch the Video: Boost Your Quarkus Projects: Microstream 8 Persistence Extension