• 1. Overview
• 2. Documentation Conventions
• 3. Enabling Hazelcast
  • 3.1 Enabling Hazelcast through the Admin Console
  • 3.2 Enabling Hazelcast using Asadmin
  • 3.3 Enabling Hazelcast in the domain.xml file
• 4. Configuring Hazelcast
  • 4.1 Configuring Hazelcast with the Admin Console
  • 4.2 Configuring Hazelcast using Asadmin
  • 4.3 Configuring Hazelcast in the domain.xml file
• 5. Using Hazelcast in your applications
  • 5.1 Accessing the JNDI registered Hazelcast Instance
• 6. Using Hazelcast for Web and EJB container Persistence
  • 6.1 Setting Hazelcast as the Persistence Provider through the Admin Console
    • 6.1.1 For the Web Container
    • 6.1.2 For the EJB Container
  • 6.2 Setting Hazelcast as the Persistence Provider using Asadmin
    • 6.2.1 For the Web Container
    • 6.2.2 For the EJB Container
  • 6.3 Setting Hazelcast as the Persistence Provider in the domain.xml file
    • 6.3.1 For the Web Container
    • 6.3.2 For the EJB Container
• 7. Asadmin Commands
  • 7.1 set-hazelcast-configuration
  • 7.2 get-hazelcast-configuration
  • 7.3 list-hazelcast-members
  • 7.4 restart-hazelcast

This page covers how to use the Hazelcast functionality in Payara 4.1.153.
Hazelcast is an In-Memory Data Grid, providing Web and EJB session persistence, and implementing JSR107 (JCache) in Payara Server.

${Product-Root} - This is the root of the Payara server directory, referring to where you have Payara installed.
${Domain} - This refers to the name of your Payara domain.
${Target} - This refers to the name of an instance or cluster.
... - Denotes a skipping of unrelated code that would be present in the actual file or program.
${Cluster-Config} - This refers to the name of a cluster configuration.

In the default domain configuration of Payara, Hazelcast is not enabled. It can be enabled either through the Admin Console, using a command line asadmin command, or through editing the domain.xml file.

From the Admin Console home:

• Click on the cluster, standalone instance, or Admin Server instance (server) to load the General Information page of the cluster or instance.
• Click on the Hazelcast tab to see the Hazelcast Configuration page.
• Check the Enabled box, and save your changes

The set-hazelcast-configuration asadmin command requires you to specify whether or not Hazelcast is enabled each time you run it. This command is also used to configure Hazelcast, which will be covered here. The command requires the Admin Server to be running, and will expect it to be listening on port 4848 unless specified differently with the --port asadmin utility option.

asadmin set-hazelcast-configuration --enabled=true

If no target is specified, the command will enable Hazelcast on the Admin Server instance. To enable Hazelcast on another instance or cluster, use the --target option like so:

asadmin set-hazelcast-configuration --enabled=true --target=${Target}

The dynamic option of the asadmin command defaults to false, so to enable Hazelcast without requiring a restart of the target instance/cluster, use --dynamic=true:

asadmin set-hazelcast-configuration --enabled=true --dynamic=true

• Open up the domain.xml file in your text editor of choice, it can be found under ${Product_Root}/glassfish/domains/${Domain}/config/
• Find the <hazelcast-runtime-configuration> tag under the appropriate <config> tag (e.g. <config name="server-config"> for the Admin Server), and add enabled="true" to it, like so:
  <hazelcast-runtime-configuration enabled="true"/>
  • Note - If you're editing the domain.xml of a domain that has not been started at least once, this tag will not exist and you will have to add it in yourself

Payara Server supports configuring Hazelcast through the Admin Console or domain.xml file, or by using a Hazelcast configuration file. Using a Hazelcast configuration file will cause the settings in the Admin Console and domain.xml file to be ignored, with any parameters not specified in the configuration file reverting to the Hazelcast defaults, even if they are specified in the Admin Console or domain.xml (Note - the Hazelcast defaults are not necessarily the same as the Payara Hazelcast defaults).

Navigate to the Hazelcast configuration page as detailed in Enabling Hazelcast through the Admin Console:

• Click on the cluster, standalone instance, or Admin Server instance (server) to load the General Information page of the cluster or instance.
• Click on the Hazelcast tab to see the Hazelcast Configuration page.
  From here, the following configuration options are available to you (excluding the Enabled property detailed above):

Enter your required values, and click Save. Restarting the domain or instance/cluster is not necessary for any changes made to take effect.

As noted in the Enabling Hazelcast using Asadmin section, the set-hazelcast_configuration asadmin command is used to both enable/disable Hazelcast, and to configure it. You can pass the --help option to the command to see usage instructions in your terminal. The available configuration options can be found here.

The following example demonstrates setting all of the options on a cluster called cluster1:

asadmin set-hazelcast-configuration --enabled=true --target=cluster1 --dynamic=true -f hazelcast-config.xml --startport=5902 -g 224.2.2.3 --multicastport=6666 -j payara/Hazelcast

• Open up the domain.xml file in your text editor of choice, it can be found under ${Product_Root}/glassfish/domains/${Domain}/config/
• Find the <hazelcast-runtime-configuration> tag under the appropriate <config> tag (e.g. <config name="server-config"> for the Admin Server), and add one or more of the following properties to it as required:

See here for an example configuration demonstrating each property:

<config name="server-config">
    ...  
    <hazelcast-runtime-configuration enabled="true" hazelcast-configuration-file="hazelcast-configuration.xml" start-port="5666" multicast-group"224.2.2.4" jndi-name="payara/Hazelcast1 multicast-port="54328"></hazelcast-runtime-configuration>
    ...  
</config>

The following sections will detail how to use the Hazelcast embedded in Payara within your code.

By default, the JNDI name of the hazelcast instance is payara/Hazelcast, though this can be altered as detailed in section 4.

You will need to import the following packages into your Java class:

import com.hazelcast.core.HazelcastInstance;
import javax.naming.Context;
import javax.naming.InitialContext;

To import the Hazelcast package, you will need to set the Payara Hazelcast package as a dependency in the project pom.xml file (for Maven projects), or for you to set the Hazelcast JAR as a project dependency (if using a non-Maven based project). To add the Payara Hazelcast package as a dependency in a pom, enter the following in the dependencies section of your pom:

<dependency>
    <groupId>fish.payara.appserver</groupId>
    <artifactId>payara-jsr107</artifactId>
    <version>4.1</version>
    <type>jar</type>
    <scope>provided</scope>
</dependency>

The Hazelcast JAR (for non-Maven projects), can either be downloaded from the Hazelcast website, or you can make use of the JAR packaged with Payara. The JAR packaged with Payara can be found at ${Product-Root}/glassfish/modules/hazelcast.jar.

The following will initialise a HazelcastInstance variable with the instance embedded in Payara:

Context ctx = new InitialContext();  
HazelcastInstance instance = (HazelcastInstace) ctx.lookup("payara/Hazelcast");  

You will have to wrap this in a try-catch clause, or throw the Naming Exception that this could generate.

You can use Hazelcast as the persistence provider for the Web and EJB Container in a cluster. Hazelcast must be enabled for this to work, which is detailed in section 3 (Note, even if Hazelcast is not enabled, you will still be able to select Hazelcast as the persistence provider; the persistence will fail in these circumstances).

In the left hand panel, under Configurations, expand the configuration of the cluster you wish to set Hazelcast as the persistence provider for, and click on Availability Service.

To set Hazelcast as the persistence provider of the Web Container:

• Navigate to the Web Container Availability tab
• Expand the Persistence Type drop-down menu, and select hazelcast
• Save your changes

To set Hazelcast as the persistence provider of the EJB Container:

• Navigate to the EJB Container Availability tab
• Expand the HA Persistence Type drop-down menu, and select hazelcast
• Save your changes

To configure the persistence provider with asadmin, you have to use the set command.

To set Hazelcast as the persistence provider of the Web Container, run: asadmin set ${Cluster-Config}.availability-service.web-container-availability.persistence-type=hazelcast

To set Hazelcast as the persistence provider of the EJB Container, run: asadmin set ${Cluster-Config}.availability-service.ejb-container-availability.sfsb-ha-persistence-type=hazelcast

Configuring the persistence provider via the domain.xml file requires editing the availability-service settings of a cluster configuration.

To set Hazelcast as the persistence provider of the web container, edit domain.xml as follows:

<config name="${Cluster-Config}">
    ...
    <availability-service>
        ...
        <web-container-availability persistence-type="hazelcast"></web-container-availability>
        ...
    </availability-service>
    ...
</config>

To set Hazelcast as the persistence provider of the web container, edit domain.xml as follows:

<config name="${Cluster-Config}">
    ...
    <availability-service>
        ...
        <ejb-container-availability sfsb-ha-persistence-type="hazelcast"></ejb-container-availability>
        ...
    </availability-service>
    ...
</config>

Enables/Disables and configures the embedded Hazelcast member. This command requires the Admin Server to be running.

Example:
asadmin set-hazelcast-configuration --enabled=true --target=cluster1 --dynamic=true -f hazelcast-config.xml --startport=5902 -g 224.2.2.3 --multicastport=6666 -j payara/Hazelcast

Gets the configuration settings of the embedded Hazelcast member. This command requires the Admin Server to be running.

Example:
asadmin get-hazelcast-configuration --target=server

Lists the active Hazelcast instances and their clustering. This command requires the Admin Server to be running.

Example:
asadmin list-hazelcast-members --target=server

Restarts the Hazelcast instances attached to a server or cluster. This command requires the Admin Server to be running.

Example:
asadmin restart-hazelcast --target=server