The Hazelcast Cloud Developer Hub

Welcome to the Hazelcast Cloud developer hub. You'll find comprehensive guides and documentation to help you start working with Hazelcast Cloud as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Java Client

Quick Setup

Follow the below instructions to connect a Java client to your cluster.

1. Create a cluster as explained in the Create a Cluster section. After you create the cluster, the cluster specific page will load and cluster's state will be "Pending" for some seconds, as shown below.

2. When the cluster's state becomes "Running", the previously inactive button Configure Client on this page becomes active. Click on it and the following dialog appears:

3. Click on the Java tab (which is the default when the above dialog displays) and download the ZIP file as instructed in Step 1 in the above dialog box.
4. Extract the ZIP file and run the command, in the extracted folder, shown in the Step 2 in the above dialog box. If you are using Windows, run mvnw.cmd instead of mvnw.

You should see log output similar to the following:

Connection Successful! in your logs means that your client application has successfully connected to your cluster in Hazelcast Cloud. The sample code inserts random entries to your cluster as you can see in the logs. In your Hazelcast Cloud console (your cluster's page which you can reach from the "Clusters" top menu), you should see the charts begin to be populated with metrics of your map, as shown below:

Also, you can see your client listed under the "Client Statistics" at the bottom of your cluster's page:

Client Code

Now, as we have successfully connected and put data into the cluster, let's review and explain the client code you downloaded.

You may want to open the directory (extracted from the ZIP file you downloaded in the Step 3 above) as a Maven Java project in your favorite IDE.

Alternatively, you can simply go to src/main/java/com/hazelcast/cloud in the directory mentioned above. If you had enabled encryption in your cluster, open the ClientWithSsl.java file. Otherwise, open the Client.java file. We will explain both files line by line in the following sections.

Client.java

This is the downloaded sample client code when your cluster does not have an encryption.

public class Client {

    public static void main(String[] args) throws InterruptedException {
        ClientConfig config = new ClientConfig();
        config.setGroupConfig(new GroupConfig("YOUR_CLUSTER_NAME", "YOUR_CLUSTER_PASSWORD"));
        config.setProperty("hazelcast.client.statistics.enabled","true");
        config.setProperty(ClientProperty.HAZELCAST_CLOUD_DISCOVERY_TOKEN.getName(), "YOUR_CLUSTER_DISCOVERY_TOKEN");
        HazelcastInstance client = HazelcastClient.newHazelcastClient(config);
        IMap<String, String> map = client.getMap("map");
        map.put("key", "value");
        if(map.get("key").equals("value")) {
            System.out.println("Connection Successful!");
            System.out.println("Now, `map` will be filled with random entries.");
        }
        else {
            throw new RuntimeException("Connection failed, check your configuration.");
        }
        Random random = new Random();
        while (true) {
            int randomKey = (int) random.nextInt(100_000);
            map.put("key" + randomKey, "value" + randomKey);
            map.get("key" + random.nextInt(100_000));
            if(randomKey % 10 == 0 ) {
                System.out.println("map size:" + map.size());
            }
            Thread.sleep(100);
        }
    }

}

First, we create an empty client configuration using the following line:

ClientConfig config = new ClientConfig();

Then, we set the cluster name and password via GroupConfig using the following line:

`config.setGroupConfig(new GroupConfig("YOUR_CLUSTER_NAME", "YOUR_CLUSTER_PASSWORD"));`

The cluster name and password are unique to your cluster. The client is authenticated using this password.

To enable Hazelcast to send the client statistics to the cluster's page, we use the following line:

config.setProperty("hazelcast.client.statistics.enabled","true");

Then, we set the discovery token using the following line:

config.setProperty(ClientProperty.HAZELCAST_CLOUD_DISCOVERY_TOKEN.getName(), "YOUR_CLUSTER_DISCOVERY_TOKEN");

This token is also unique to your cluster and used to discover Hazelcast cluster members.

Now, we create the client with config using the following line:

HazelcastInstance client = HazelcastClient.newHazelcastClient(config);

This step creates the connection between your application and the cluster.

We get/create a map and put a simple entry ("key", "value") using the following lines, respectively:

IMap<String, String> map = client.getMap("map");
map.put("key", "value");

Then, we check if the entry has been put successfully and let the code throw an exception if the value is not correct using the following lines:

if(map.get("key").equals("value")) {
            System.out.println("Connection Successful!");
            System.out.println("Now, `map` will be filled with random entries.");
        }
        else {
            throw new RuntimeException("Connection failed, check your configuration.");
        }

Finally, we put random entries with 100-millisecond intervals using the following lines:

Random random = new Random();
        while (true) {
            int randomKey = (int) random.nextInt(100_000);
            map.put("key" + randomKey, "value" + randomKey);
            map.get("key" + random.nextInt(100_000));
            if(randomKey % 10 == 0 ) {
                System.out.println("map size:" + map.size());
            }
            Thread.sleep(100);
        }

ClientWithSsl.java

This is the downloaded sample client code when your cluster has encryption enabled.

public class ClientWithSsl {

    public static void main(String[] args) throws InterruptedException {
      ClassLoader classLoader = ClientWithSsl.class.getClassLoader();
      Properties props = new Properties();
      props.setProperty("javax.net.ssl.keyStore", classLoader.getResource("client.keystore").getPath());
      props.setProperty("javax.net.ssl.keyStorePassword", "YOUR_KEY_STORE_PASSWORD");
      props.setProperty("javax.net.ssl.trustStore", classLoader.getResource("client.truststore").getPath());
      props.setProperty("javax.net.ssl.trustStorePassword", "YOUR_TRUST_STORE_PASSWORD");
      ClientConfig config = new ClientConfig();
      config.getNetworkConfig().setSSLConfig(new SSLConfig().setEnabled(true).setProperties(props));
      config.getGroupConfig().setName("YOUR_CLUSTER_NAME").setPassword("YOUR_CLUSTER_PASSWORD");
      config.setProperty("hazelcast.client.statistics.enabled","true");
      config.setProperty(ClientProperty.HAZELCAST_CLOUD_DISCOVERY_TOKEN.getName(), "YOUR_CLUSTER_DISCOVERY_TOKEN");
      HazelcastInstance client = HazelcastClient.newHazelcastClient(config);
      IMap<String, String> map = client.getMap("map");
      map.put("key", "value");
      if(map.get("key").equals("value")) {
        System.out.println("Connection Successful!");
        System.out.println("Now, `map` will be filled with random entries.");
      }
      else {
        throw new RuntimeException("Connection failed, check your configuration.");
      }
      Random random = new Random();
      while (true) {
        int randomKey = (int) random.nextInt(100_000);
        map.put("key" + randomKey, "value" + randomKey);
        map.get("key" + random.nextInt(100_000));
        if(randomKey % 10 == 0 ) {
          System.out.println("map size:" + map.size());
        }
        Thread.sleep(100);
      }
    }

}

The only difference between this one and the Client.java is the lines that enable and configure TLS encryption on the client side. The following lines set the paths and passwords for the TLS keystore and truststore files:

ClassLoader classLoader = ClientWithSsl.class.getClassLoader();
      Properties props = new Properties();
      props.setProperty("javax.net.ssl.keyStore", classLoader.getResource("client.keystore").getPath());
      props.setProperty("javax.net.ssl.keyStorePassword", "YOUR_KEY_STORE_PASSWORD");
      props.setProperty("javax.net.ssl.trustStore", classLoader.getResource("client.truststore").getPath());
      props.setProperty("javax.net.ssl.trustStorePassword", "YOUR_TRUST_STORE_PASSWORD");

The above example code finds the keystore and truststore in the classloader's resources directory. You can find these files under /src/main/resources in the extracted ZIP's directory. If you move these files to another directory, you should set the above properties accordingly.

Project Setup

The example client application you downloaded is a plain Maven Java project. See the pom.xml below:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.hazelcast.cloud</groupId>
    <artifactId>hazelcast-cloud-java-sample-client</artifactId>
    <version>1.0-BETA</version>

    <dependencies>
        <dependency>
            <groupId>com.hazelcast</groupId>
            <artifactId>hazelcast-enterprise-client</artifactId>
            <version>3.11.1</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>1.6.0</version>
                <executions>
                    <execution>
                        <id>client</id>
                        <goals>
                            <goal>java</goal>
                        </goals>
                        <configuration>
                            <mainClass>com.hazelcast.cloud.Client</mainClass>
                        </configuration>
                    </execution>
                    <execution>
                        <id>client-with-ssl</id>
                        <goals>
                            <goal>java</goal>
                        </goals>
                        <configuration>
                            <mainClass>com.hazelcast.cloud.ClientWithSsl</mainClass>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

    <repositories>
        <repository>
            <id>hazelcast-ee</id>
            <name>Sonatype Repository</name>
            <url>https://repository-hazelcast-l337.forge.cloudbees.com/release</url>
        </repository>
    </repositories>
</project>

The application has just one dependency: hazelcast-enterprise-client.
You may want to use the Hazelcast Open Source client, but you can only use it when encryption is disabled since the Open Source Java client does not support the TLS encryption.

Declarative Configuration

The easiest way to configure your client declaratively is to put the hazelcast-client.xml file to your project's classpath. You can find others ways here. The following is a sample XML file for configuring the client to connect to Hazelcast Cloud:

<?xml version="1.0" encoding="UTF-8"?>
<hazelcast-client xsi:schemaLocation="http://www.hazelcast.com/schema/client-config hazelcast-client-config-3.11.xsd"
                  xmlns="http://www.hazelcast.com/schema/client-config"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <group>
        <name>YOUR_CLUSTER_NAME</name>
        <password>YOUR_CLUSTER_PASSWORD</password>
    </group>
    <properties>
        <property name="hazelcast.client.statistics.enabled">true</property>
    </properties>
    <network>
        <hazelcast-cloud enabled="true">
            <discovery-token>YOUR_CLUSTER_DISCOVERY_TOKEN</discovery-token>
        </hazelcast-cloud>
    </network>
</hazelcast-client>

Finally, you need to create a Hazelcast client with the empty constructor as shown below:

HazelcastInstance client = HazelcastClient.newHazelcastClient();

More Configuration Options

Please refer to the Hazelcast IMDG Reference Manual for further configuration options.

Updated about a month ago

Java Client


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.