Contents

1. Overview

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

2. Documentation Conventions

${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.

3. Enabling Hazelcast

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.

3.1 Enabling Hazelcast through the Admin Console

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

3.2 Enabling Hazelcast using Asadmin

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

3.3 Enabling Hazelcast in the domain.xml file

  • 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 \ tag under the appropriate \ tag (e.g. \ 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

4. Configuring Hazelcast

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).

4.1 Configuring Hazelcast with the Admin Console

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):
Property Description
Dynamic Determines if the Hazelcast member embedded in Payara will be restarted to apply any changes made
Override Configuration File Specifies the Hazelcast configuration file to use. The path specified is relative to the domain config directory. If you are using a custom GlassFish server configuration for a cluster or standalone instance e.g. cluster-config then the hazelcast configuration file should be placed in the directory with the same name e.g. $domain_root/config/cluster-config. This will ensure it is replicated to the node during startup.
Start Port Determines the port to start Hazelcast on. If this port is in use, Hazelcast will increment this port until it finds one it can use.
Multicast Port The multicast port for communications in the Hazelcast cluster.
Multicast Group The multicast group for communications in the Hazelcast cluster.
JNDI Name The JNDI name to bind the Hazelcast instance to.

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

4.2 Configuring Hazelcast using Asadmin

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

4.3 Configuring Hazelcast in the domain.xml file

  • 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 \ tag under the appropriate \ tag (e.g. \ for the Admin Server), and add one or more of the following properties to it as required:
Property Admin Console Equivalent Description
hazelcast-configuration-file Override Configuration File Specifies the Hazelcast configuration file to use. The path specified must be relative to the domain config directory.
start-port Start Port Determines the port to start Hazelcast on. If this port it in use, Hazelcast will increment this port until it finds one it can use.
multicast-group Multicast Group The multicast group for communications in the Hazelcast cluster.
multicast-port Multicast Port The multicast port for group communications in the Hazelcast cluster.
jndi-name JNDI Name The JNDI name to bind the Hazelcast instance to.

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>

5. Using Hazelcast in your Applications

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

5.1 Accessing the JNDI registered Hazelcast instance

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.

6. Using Hazelcast for the Web and EJB Container Persistence

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).

6.1 Setting Hazelcast as the Persistence provider through the Admin Console

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.

6.1.1 For the Web Container

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

6.1.2 For the EJB Container

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

6.2 Setting Hazelcast as the Persistence provider using Asadmin

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

6.2.1 For the Web Container

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

6.2.2 For the EJB Container

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

6.3 Setting Hazelcast as the Persistence provider in the domain.xml file

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

6.3.1 For the Web Container

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>

6.3.2 For the EJB Container

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>

7. Asadmin Commands

7.1 set-hazelcast-configuration

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

Option Shortcut Description Default Mandatory
--enabled Determines whether or not the embedded Hazelcast member is enabled or disabled. false Yes
--target The instance or cluster to configure. server No
--dynamic Enable or disable dynamic stopping and starting of the embedded Hazelcast member. false No
--hazelcastconfigurationfile -f The Hazelcast configuration file to use. The path is relative to domain config directory (${Product-Root}/glassfish/domains/${Domain}/config/). Using this option to point to a valid Hazelcast configuration file will cause all other options set to be ignored. Any options not specified in the Hazelcast configuration file will revert to the Hazelcast defaults. hazelcast-config.xml No
--startport The port to run Hazelcast on. If this port is busy, the port specified will be incremented until a valid port is found. 5900 No
--multicastgroup -g The multicast group for communications in the Hazelcast instance. 224.2.2.3 No
--multicastport The multicast port for communications in the Hazelcast instance. 54327 No
--jndiname -j The JNDI name to bind the Hazelcast instance to. payara/Hazelcast No

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

7.2 get-hazelcast-configuration

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

Option Shortcut Description Default Mandatory
--target The instance or cluster to get the Hazelcast configuration of. server No

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

7.3 list-hazelcast-members

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

Option Shortcut Description Default Mandatory
--target The instance or cluster to get the Hazelcast configuration of. server No

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

7.4 restart-hazelcast

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

Option Shortcut Description Default Mandatory
--target The instance or cluster to get the Hazelcast configuration of. server No

Example:
asadmin restart-hazelcast --target=server

results matching ""

    No results matching ""