Working with Cluster-Side Modules in Hazelcast Viridian

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 Viridian Serverless 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

Ingest data from an external data source into a Hazelcast map, or add data from a Hazelcast map to an external data source.

Entry processor

Atomically execute code on a map entry.

You cannot use a custom name for entry processors in Hazelcast Viridian. 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 Hazelcast Viridian. 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 Hazelcast Viridian, 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. Hazelcast Viridian 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

Hazelcast Viridian 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

Hazelcast Viridian 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 Hazelcast Viridian. If your project includes a library that’s already available in Hazelcast Viridian, 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 Viridian Serverless development cluster: It’s faster to test cluster-side modules in a development cluster.

  • Use the Hazelcast Viridian 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 you 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 either to a Viridian Serverless production cluster or a Viridian Dedicated cluster.

You must provide a payment card to run more than one Viridian cluster.

Tutorials

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