This manual is for an old version of Hazelcast IMDG, use the latest stable version.
Chapter 16. Clients

Chapter 16. Clients

Table of Contents

16.1. Native Client
16.1.1. Java Client
16.1.2. CSharp Client (Enterprise Edition Only)
16.2. Memcache Client
16.3. Rest Client

There are currently three ways to connect to a running Hazelcast cluster:

  1. Native Clients

  2. Memcache Clients

  3. REST Client

16.1. Native Client

Native Client enables you to do all Hazelcast operations without being a member of the cluster. It connects to one of the cluster members and delegates all cluster wide operations to it. When the relied cluster member dies, client will transparently switch to another live member.

There can be hundreds, even thousands of clients connected to the cluster. But by default there is 40 threads on server side that will handle all the requests. You may want to increase hazelcast.executor.client.thread.count property for better performance.

Imagine a trading application where all the trading data stored and managed in a 10 node Hazelcast cluster. Swing/Web applications at traders' desktops can use Native Java Client to access and modify the data in the Hazelcast cluster.

Currently Hazelcast has Native Java and C# Client available.

LiteMember vs. Native Client

LiteMember is a member of the cluster, it has socket connection to every member in the cluster and it knows where the data is so it will get to the data much faster. But LiteMember has the clustering overhead and it must be on the same data center even on the same RAC. However Native client is not member and relies on one of the cluster members. Native Clients can be anywhere in the LAN or WAN. It scales much better and overhead is quite less. So if your clients are less than Hazelcast nodes then LiteMember can be an option; otherwise definitely try Native Client. As a rule of thumb: Try Native client first, if it doesn't perform well enough for you, then consider LiteMember.

The following picture describes the clients connecting to Hazelcast Cluster. Note the difference between LiteMember and Java Client

16.1.1. Java Client

You can do almost all hazelcast operations with Java Client. It already implements the same interface. You must include hazelcast-client.jar into your classpath.

import com.hazelcast.core.HazelcastInstance;
import com.hazelcast.client.HazelcastClient;

import java.util.Map;
import java.util.Collection;


ClientConfig clientConfig = new ClientConfig();
clientConfig.getGroupConfig().setName("dev").setPassword("dev-pass");
clientConfig.addAddress("10.90.0.1", "10.90.0.2:5702");

HazelcastInstance client = HazelcastClient.newHazelcastClient(clientConfig);
//All cluster operations that you can do with ordinary HazelcastInstance
Map<String, Customer> mapCustomers = client.getMap("customers");
mapCustomers.put("1", new Customer("Joe", "Smith"));
mapCustomers.put("2", new Customer("Ali", "Selam"));
mapCustomers.put("3", new Customer("Avi", "Noyan"));

Collection<Customer> colCustomers = mapCustomers.values();
for (Customer customer : colCustomers) {
     // process customer
}

16.1.2. CSharp Client (Enterprise Edition Only)

You can use native C# client to connect to the running Hazelcast instances. All you need is to include Hazelcast.Client.dll into your C# project. The API is very similar to Java native client. Note that C# client doesn't have automatic reconnection feature. If the node that it connected dies, it will not switch to another member. User must connect to another member itself.


using System;
using System.Collections.Generic;

using Hazelcast.Client;
using Hazelcast.Core;

ClientConfig clientConfig = new ClientConfig();
clientConfig.GroupConfig.Name = "dev";
clientConfig.GroupConfig.Password = "dev-pass";
clientConfig.addAddress("10.90.0.1");

HazelcastClient client = HazelcastClient.newHazelcastClient(clientConfig);
//Allmost all cluster operations that you can do with ordinary HazelcastInstance
//Note that the Customer class must have Serializable attribute or implement Hazelcast.IO.DataSerializable
IMap<String, Customer> mapCustomers = client.getMap("customers");
mapCustomers.put("1", new Customer("Joe", "Smith"));
mapCustomers.put("2", new Customer("Ali", "Selam"));
mapCustomers.put("3", new Customer("Avi", "Noyan"));

ICollection<Customer> colCustomers = mapCustomers.values();
foreach (Customer customer in colCustomers) {
     // process customer
}

You can serialize back and forth Java and C# Objects between C# client and Hazelcast server. All you need is to have your classes that you want to share to implement DataSerializable both on Java and C# in the exact same way. And on C# ClientConfig you must set a TypeConverter implementation that will convert Java Class name into C# Type and vice versa. A basic TypeConverter might look like this.


public class MyTypeConverter: Hazelcast.IO.ITypeConverter
{
    public string getJavaName(Type type)
    {
        if(type.Equals(typeof(Hazelcast.Client.Examples.MyCSharpClass)))
            return "com.hazelcast.examples.MyClass";

        return null;
    }

    public Type getType(String javaName)
    {
        if("com.hazelcast.examples.MyClass".Equals(javaName))
            return typeof(Hazelcast.Client.Examples.MyCSharpClass);

        return null;
    }
}

            

A basic MyCSharpClass implementing DataSerializable


using System;
using Hazelcast.IO;

public class MyCSharpClass: Hazelcast.IO.DataSerializable
{
    String field1 = "";
    int field2;

    public MyCSharpClass ()
    {
    }

    public MyCSharpClass (String f1, int f2)
    {
        this.field1 = f1;
        this.field2 = f2;
    }

    public void writeData(IDataOutput dout){
        dout.writeUTF(field1);
        dout.writeInt(field2);
    }

    public void readData(IDataInput din){
        field1 = din.readUTF();
        field2 = din.readInt();
    }
}