Working with Cluster-Side Modules in Viridian Cloud

Cluster-side modules are Java classes that a cluster can execute or store in the cloud. You can write cluster-side modules to execute custom code or store custom objects. This guide describes the workflows and best practices for implementing cluster-side modules.

The basic workflow for any cluster-side module is the following:

  1. Build the Java class and implement any required interfaces.

  2. Test your implementation on a development cluster.

  3. Deploy your Java classes to your cluster.

Then, you can use any client to interact with the cluster-side modules such as querying objects or triggering processes.

Workflow for building cluster-side modules

What are Cluster-Side Modules

Cluster-side modules include any code that must be deployed as Java code to the cluster, including the following:

Table 1. Cluster-side modules
Module Description

MapStore

Load additional and updated data from an external data source to your Hazelcast map, and propogate updates in your Hazelcast map to an external data source.

If you only need to ingest data, you can use the MapLoader module class.

Entry processor

Atomically execute code on a map entry.

You cannot use a custom name for entry processors in Viridian Cloud. You must use the one called default.

Executor

Asynchronously execute tasks, such as database queries, complex calculations, and image rendering.

You cannot use a custom name for executors in Viridian Cloud. You must use the one called default.

Custom object class (domain objects)

Allow clusters to store or process domain objects that you use in your applications.

Pipeline

Process streaming or batch data in Viridian Cloud, using one or more data sources and sinks.

Supported Serializers

Cluster-side modules must be serialized because they are sent to other members in the cluster and/or your client applications. Viridian Cloud supports the following serializers. Follow the links to learn more about these serializers in the Hazelcast Platform documentation.

Serializer Advantages Disadvantages Client support

Compact Serialization

  • Convenient, flexible, and can be used with no configuration

  • Does not require a class to implement an interface

  • Supports schema evolution

  • Partial deserialization is supported during queries and indexing

  • Specific to Hazelcast

  • Schema is not part of the data but schema distribution may incur costs on short-lived use cases.

All clients

Hazelcast JSON

  • No member-side coding required

  • Specific to Hazelcast

  • Requires extra metadata to be stored on members.

All clients

Serializable

  • A standard and basic Java interface

  • Requires no implementation

  • More time and CPU usage

  • More space occupancy

Java only

Externalizable

  • A standard Java interface

  • More CPU and memory efficient than Serializable

  • Serialization interface must be implemented

Java only

Requirements and Limitations

Any Java code in cluster-side modules must meet the following requirements.

Java Version

Viridian Cloud supports only Java version 11 or earlier. Do not use a Java version greater than version 11.

System-Level APIs

No code in cluster-side modules is allowed to access system-level APIs. Hazelcast throws a Java security exception if any cluster-side modules try to access these APIs.

Package Names

Your package names must not start with com.hazelcast. Hazelcast ignores these packages.

Package Size

Viridian Cloud allows you to upload packaged files up to 500 MB. Larger files are rejected.

Dependency Conflicts

The libraries in your project must not conflict with those that are built into Viridian Cloud. If your project includes a library that’s already available in Viridian Cloud, you may experience conflicts that stop Hazelcast from processing your cluster-side modules. To avoid packaging conflicting libraries in your code, we recommend using one of the following options:

  • Shaded JARs: When you shade JARs, the classes inside them are relocated and rewritten to create a private copy of them that is bundled alongside your code. To learn more about shaded JARs, see this answer on Stack Overflow.

  • Provided scope: When you use the provided scope for a JAR, it is available in your classpath during compilation but will not be packaged with your project archive. To learn more about provided scope, see the docs for your build tool:

Best Practices for Testing

Before you go into production with your cluster-side modules, it’s best to test them on a development cluster to make sure that they work as expected. To test cluster-side modules, follow these best practices:

  • Use a development cluster: It’s faster to test cluster-side modules in a development cluster.

  • Use the Viridian Cloud Maven plugin: The Maven plugin allows you to package and deploy your cluster-side modules in a single command from your IDE. You can also debug your cluster-side modules by streaming cluster logs after deployment.

Moving to Production

After testing your cluster-side modules, you need to deploy them to production.

For production, you can deploy your cluster-side modules to a production cluster on either Viridian Cloud Standard or Viridian Cloud Dedicated.

You must provide a payment card or other payment method to run more than one Viridian Cloud cluster.

Tutorials

Get hands-on with cluster-side modules by following a tutorial: