This is a prerelease version.

Upgrading to Hazelcast 5.0

This section lists the distribution, documentation and API changes for you to be aware when upgrading to Hazelcast 5.0 from previous versions of Hazelcast and Jet.

Hazelcast offers tools and features for a smooth migration from IMDG/Jet 3.12/4.x to Platform 5.0. See here and here to learn more.

Merge of Hazelcast and Jet

The open source and Enterprise code and documentation of former Hazelcast IMDG and Jet have been merged as Hazelcast, as version 5.0. The following sections elaborate the changes performed for this merge.

Version Compatibility

You can find the rules for compatibility in this section.

Semantic Versioning

Hazelcast uses semantic versioning:

  • MAJOR version when you make incompatible API changes

  • MINOR version when you add functionality in a backwards-compatible manner

  • PATCH version when you make backwards-compatible issue fixes.

Compatibility with Former IMDG Versions

Hazelcast 5.0 is fully compatible with former Hazelcast IMDG 4.x and 3.12.x versions.

Compatibility with Former Jet Versions

Hazelcast 5.0’s Jet engine does not provide backwards compatibility (rolling upgrades and client compatibility); only API compatibility is provided (the API that was compiled in former Jet 4.x can be compiled in Hazelcast 5.0’s Jet engine), and these are the Job and Pipeline APIs.

For example a Hazelcast job written using Pipeline API in a previous minor version should compile in later minor versions.

Compatibility with Client Versions

All the 4.x.y versions of Hazelcast .NET, C++. Python and Node.js clients are compatible with Hazelcast 5.0. The next release of Hazelcast Go client will also be compatible.

Compatibility with Management Center Versions

Previous versions of Hazelcast Management Center does not work with Hazelcast 5.0; only Management Center 5.0 does.

API Compatibility

  • Pipeline and Job APIs provide compatibilities between Hazelcast minor versions.

  • Core API is compatible between Hazelcast patch versions.

  • Types and methods annotated with @EvolvingApi only provide PATCH level compatibility guarantee. These are typically new features where the API is subject to further changes.

  • Classes in impl packages do not provide any compatibility guarantees between versions and are not meant for public use.

Licenses

  • You are able to use your current Hazelcast Enterprise/Enterprise HD and Hazelcast Enterprise licenses when moving to Hazelcast 5.0 without any license upgrade.

  • If you have a Hazelcast Enterprise or Enterprise HD license, you will be able to discover and use Hazelcast’s Jet features (both the open source and Enterprise ones) when you move to Hazelcast 5.0.

  • Hazelcast 5.0 does not offer the former Pro Edition for Hazelcast. Existing Pro Edition customers' licenses will be renewed if requested.

  • All the features of Hazelcast open source edition are available in Hazelcast 5.0.

Merge of SQL Modules

The former Hazelcast product had hazelcast-sql, hazelcast-sql-core and hazelcast-jet-sql Maven modules in its distribution. These have been merged into a single hazelcast-sql module as a part of the Hazelcast 5.0 distribution.

Removal of Jet Spring Module

The former jet-spring module which was used to configure Hazelcast using Spring has been merged into the hazelcast-spring module.

Changes in Distribution Packaging

Former Hazelcast IMDG product had hazelcast and hazelcast-all modules for the core distribution and the distribution with all extensions, respectively. Similarly, Hazelcast Jet had slim and full distribution packaging.

The hazelcast-all module has been removed after the merge of former IMDG and Jet products.

Hazelcast 5.0 provides, like the former Jet product, slim and full packagings.

The slim one includes only the following:

  • Hazelcast runtime

  • Default configuration files (not example ones)

  • Scripts

  • SQL

  • Management Center

The full one includes the following:

  • Hazelcast and its modules contained in the former hazelcast-all

    • AWS discovery plugin

    • Kubernetes discovery plugin

    • GCP discovery plugin

    • Azure discovery plugin

    • Hazelcast Hibernate

    • Hazelcast Spring

    • SQL

  • Jet extensions

  • Management center

Scripts

With the merge of former IMDG and Jet products, there have been changes made to the scripts provided in the distributions.

See the following table for the before/after script distributions:

Before Hazelcast 5.0 (IMDG)

Before Hazelcast 5.0 (Jet)

Hazelcast 5.0

/bin

 — cluster.sh

 — cp-subsystem.sh

 — healthcheck.sh

 — start.bat

 — start.sh

 — stop-all.bat

 — stop-all.sh

/bin

 — common.sh

 — jet

 — jet-cluster-admin

 — jet-cluster-cp-admin

 — jet-start

 — jet-start.bat

 — jet-stop

 — jet-stop.bat

 — jet.bat

/bin

 — common.sh

 — hz-cli

 — hz-start

 — hz-healthcheck

 — hazelcast-stop

 — hz-cluster-admin

 — hz-cluster-cp-admin

 — hz-start.bat

 — hz-stop.bat

 — hz-cli.bat

Configurations

With the merge of former IMDG and Jet products, there have been changes made to the configuration files provided in the distributions.

See the following table for the before/after configuration distributions:

Before Hazelcast 5.0 (IMDG)

Before Hazelcast 5.0 (Jet)

Hazelcast 5.0

/bin

 — hazelcast-client-failover-full-example.xml

 — hazelcast-client-failover-full-example.yaml

 — hazelcast-client-full-example.xml

 — hazelcast-client-full-example.yaml

 — hazelcast-full-example.xml

 — hazelcast-full-example.yaml

 — hazelcast.xml

/config

 — hazelcast-client.yaml

 — hazelcast-jet.yaml

 — hazelcast.yaml

 — jmx_agent_config.yaml

 — jvm-client.options

 — jvm.options

 — log4j2.properties

/config/examples

 — hazelcast-client-full-example.xml

 — hazelcast-client-full-example.yaml

 — hazelcast-client.xml

 — hazelcast-full-example.xml

 — hazelcast-full-example.yaml

 — hazelcast-jet-full-example.xml

 — hazelcast-jet-full-example.yaml

 — hazelcast-jet.xml

 — hazelcast.xml

/config

 — hazelcast-client.yaml

 — hazelcast.yaml

 — jmx_agent_config.yaml

 — jvm-client.options

 — jvm.options

 — log4j2.properties

Merge of Declarative Configurations

The former Hazelcast and Jet declarative configuration files have been merged into a single Hazelcast XML/YAML file. Basically, the Jet configuration elements have been added to the IMDG’s XML/YAML files. See https://github.com/hazelcast/hazelcast/blob/master/hazelcast/src/main/resources/hazelcast-full-example.yaml#L3490.

Introduction of YAML Configuration Validator

Hazelcast 5.0 checks and validates your YAML configurations during a cluster startup. According to this validation:

  • the top-level hazelcast object must exist

  • client and member YAML configurations must be separate, not in the same file

  • there must be no case insensitive enum values.

While upgrading to Hazelcast 5.0, if a YAML configuration violates any of the above, the cluster will not start. You need to either edit and update your YAML configuration files accordingly or disable the validation by setting the yaml.config.validation.skip property to true.

Replacement of JetInstance with JetService

Previously, the Jet instance was created as shown below:

HazelcastInstance hz = Hazelcast.newHazelcastInstance();
JetInstance jet = hz.getJetInstance();
// as if two separate instances were created

This has been changed as follows:

HazelcastInstance hz = Hazelcast.newHazelcastInstance();
JetService jet = hz.getJet(); // no longer have shutdown(), getMap(), getList() etc.

Depreciation of the Jet and JetInstance Classes

The Jet class, which was the main entry point of the former Hazelcast product, has been deprecated. Also, we deprecated the JetInstance class, which was previously representing an instance of Jet member or Jet client. This change aims to consider Jet as an extension service to HazelcastInstance instead of being an instance on its own which encapsulates HazelcastInstance. With 5.0, we introduced a new class called JetService.

Together with HazelcastInstance, JetService replaces all the usages of the JetInstance. Previously, JetInstance was mainly used for the functionalities listed below:

  • Submitting streaming/batch jobs to the cluster and managing them → JetService replaces this functionality.

  • To access Hazelcast data structures → HazelcastInstance replaces this functionality. The only exception is Jet observables. The observables is a Jet data structure and we ported it to JetService.

  • Performing cluster operations such as shutting down the cluster → HazelcastInstance replaces this functionality.

To access Jet related services such as submitting jobs, you should use JetService which can get from HazelcastInstance#getJet() after creating HazelcastInstance using one of the static factory methods of a Hazelcast class.

Depreciation of Jet.bootstrappedInstance

Jet’s bootstrappedInstance() has been deprecated as the Jet class. As the replacement, we have introduced Hazelcast.bootstrappedInstance(). You can use it as shown below:

public class CustomJetJob {
   public static void main(String[] args) {
      HazelcastInstance hz = Hazelcast.bootstrappedInstance();
      JetInstance jet = hz.getJetInstance();
      jet.newJob(buildPipeline()).join();
    }

    public static Pipeline createPipeline() {
        // ...
    }
  }

Changes in DefaultNodeExtension

The JetNodeExtension class has been merged into the DefaultNodeExtension. With the merge of former IMDG and Jet products, there is now a single unified node extension.