Java Client

To get started using the Java Client and Embedded Server, you need to include the hazelcast.jar dependency in your classpath. You can then start using this client as if you are using the Hazelcast API.

If you prefer to use Maven, make sure you have added the appropriate hazelcast or hazelcast-enterprise dependency to your pom.xml:

You can find Java Client and Embedded Server code samples in the Hazelcast Code Samples repository.

To get started using the Java Client (Standalone), you need to add the hazelcast-java-client dependency to your pom.xml, as shown below. You can then start using this client as if you are using the Hazelcast API.

If you are using hazelcast-enterprise-java-client, you need to add the hazelcast-enterprise-java-client dependency and private hazelcast repository to your pom.xml file, as shown below:

The Client API is your gateway to access your Hazelcast cluster, including distributed objects and data pipelines (jobs).

First, you must configure your client. You can use either declarative or programmatic configuration to do this.

The following examples demonstrate the programmatic approach.

For further information on client configuration, see Configure the client. For further information on client configuration, see Configure the client.

After completing the client configuration, you must create an HazelcastClient instance that will initialize and connect to the client based on the specified configuration: After completing the client configuration, you must create an HazelcastClient instance that will initialize and connect to the client based on the specified configuration:

You can create a distributed map and populate it with some data as follows: You can create a distributed map and populate it with some data as follows:

For further information about using maps, see Distributed Map.

Lastly, after setting up your client, you can shut it down as follows:

This command releases all used resources and closes all connections to the cluster.

Hazelcast offers distributed implementations of many common data structures, most of which are supported by the Java Client and Embedded Server and Java Client (Standalone).

When you use clients in other languages, you should review the appropriate client documentation for exceptions and details. As a general rule, you should configure these data structures on the server side and access them through a proxy on the client side.

You can use any distributed map object with the client, as follows:

The addLocalEntryListener() and localKeySet() methods are not supported because locality is ambiguous for the client. For more information, see Distributed Map.

You can use a distributed multiMap object with the Java Client and Embedded Server, as follows:

The addLocalEntryListener(), localKeySet() and getLocalMultiMapStats() methods are not supported because locality is ambiguous for the client. For more information, see MultiMap.

You can use a distributed Queue object with the client, as follows:

The getLocalQueueStats() method is not supported because locality is ambiguous for the client. For more information, see Queue.

The getLocalTopicStats() method is not supported because locality is ambiguous for the client.

The distributed data structures listed below are also supported. The logic is the same for both member and client side, so see the specific sections for more information on usage.

The cluster routing mode specifies how the client connects to the cluster. It can currently be used only with Java and .NET clients.

The mode that you use depends on your network requirements due to the distributed nature of the data and cluster.

In all modes, the following information is provided to the client on initial connection:

The client is updated whenever the cluster version, cluster topology, partition groups, or CP group leader changes.

From Enterprise Edition 5.5, you can use any of the following cluster routing modes:

The following diagram shows how each mode connects to members in a cluster:

For information on configuring the cluster routing mode, see Configure Cluster Routing Mode.

If already using the legacy Smart and Unisocket client operation modes, these remain supported. However, we recommend that you update your configuration to use the appropriate cluster routing mode as these options will be removed in a future major version. For information on these modes and their configuration, select 5.4 from the version picker at the top of the navigation pane. Ensure that the cluster routing mode is not configured at the same time as the legacy client operation mode, only one should be defined.

The main areas are around client connections and retry-able operations. Some approaches to avoiding such failures are provided below.

You can configure global event listeners using ListenerConfig as the following examples show:

You can add the following types of event listeners:

To increase the performance of local read operations, the distributed map supports a local near cache for remotely stored entries. Because the client always requests data from the cluster members, it can be helpful in some use cases to configure a near cache on the client side. For a detailed explanation of this feature and its configuration, see Near cache.

Clients should provide a cluster name in order to connect to the cluster. You can configure it using ClientConfig, as the following example shows:

Hazelcast Enterprise Edition

You can define control mechanisms for clients to control authentication and authorisation. For more information, see Client Authorization.

You can provide the Java client with an identity for cluster authentication. The identity of the connecting client is defined on the client side. Usually, there are no security realms on the clients; only the identity defined in the security configuration.

On the clients, you can use the same identity types as in the security realms:

You can configure a custom classLoader for your client. It is used by the serialization service and loads any class specified in the configuration, including event listeners or ProxyFactories.

When operating a Hazelcast Enterprise cluster with the ADVANCED_CP license it is possible to configure clients to leverage direct-to-leader routing for CP Subsystem operations. When enabled, this functionality enables clients to receive a mapping of CP group leadership from the cluster and use it to send CP data structure operations directly to the relevant group leader. This leadership mapping is also updated whenever leadership changes occur.

CP data structure reads and writes must be actioned by the CP leader responsible for the group involved. By leveraging direct-to-leader routing for CP operations, clients are able to send all operations directly to their group leaders, cutting out the need for intermediate hops through other cluster members. This allows clients to achieve lower latency and higher throughput for their CP operations, while also reducing the pressure on the internal cluster network, resulting in greater cluster stability.

This functionality is disabled by default and must be explicitly enabled. This is done because you should consider your specific use-case for CP operation sending and assess the impact of direct to leader routing on your topology. In scenarios where clients have increased latency to CP group leaders, it may be detrimental to route all operations directly to them instead of using a faster internal cluster link and routing through another member. You should also consider that direct-to-leader routing can put uneven pressure on the cluster if CP group leaders receive a substantially greater load than other members of the cluster, which is particularly problematic when only one CP group leader is present.

You can enable CP direct-to-leader routing with a single configuration option, as the following example shows:

The following code shows the equivalent declarative configuration:

You can configure the client’s starting mode as async or sync using the configuration element async-start. When it is set to true (async), Hazelcast creates the client without waiting for a connection to the cluster. In this case, the client instance throws an exception until it connects to the cluster. If it is false, the client is not created until the cluster is ready to use clients and a connection with the cluster is established. The default value is false (sync)

You can also configure how the client reconnects to the cluster after a disconnection. This is configured using the configuration element reconnect-mode, which has three options:

The default value for reconnect-mode is ON.

The following declarative and programmatic configuration examples show how to configure a Java client’s starting and reconnecting modes:

Using CNAME, you can change the hostname resolutions and use them dynamically.

As an example, assume that you have two clusters, Cluster A and Cluster B, and two Java clients.

First, configure the Cluster A members as shown below:

Next, configure the Cluster B members as shown below:

Now, configure the two clients as shown below:

Assuming that the client configuration filenames for the above example clients are hazelcast-client-c1.xml/yaml and hazelcast-client-c2.xml/yaml, you should configure the client failover for a blue-green deployment scenario as follows:

You should also configure your clients to forget DNS lookups using the networkaddress.cache.ttl JVM parameter.

You should also configure the addresses in your clients' configuration to resolve to the hostnames of Cluster A via CNAME so that the clients will connect to Cluster A when it starts:

production1.myproject → clusterA.member1

production2.myproject → clusterA.member2

When you want the clients to switch to the other cluster, change the mapping as follows:

production1.myproject → clusterB.member1

production2.myproject → clusterB.member2

Wait for the time you configured using the networkaddress.cache.ttl JVM parameter for the client JVM to forget the old mapping.

Finally, blocklist the clients in Cluster A using Hazelcast Management Center.

Review these example configurations and the descriptions that follow:

You can manage all network-related configuration setting using either the network element (declarative) or the ClientNetworkConfig class (programmatic).

This section provides full examples for these two approaches, and then looks at the sub-elements and attributes in detail.

When an operation with sync backup is sent by a client to the Hazelcast member(s), the acknowledgment of the operation’s backup is sent to the client by the backup replica member(s). This improves the performance of the client operations.

If using the ALL_MEMBERS cluster routing mode, backup acknowledgement to the client is enabled by default. However, neither the MULTI_MEMBER nor the SINGLE_MEMBER cluster routing modes support backup acknowledgement to the client.

The following declarative example shows how to configure backup acknowledgement:

The following programmatic example shows how to configure backup acknowledgement:

You can also fine tune this feature using the following system properties:

The address List is the initial list of cluster addresses to which the client will connect. The client uses this list to find an alive member. Although it may be enough to give only one address of a member in the cluster (since all members communicate with each other), we recommended that you add the addresses for all the members.

You may want to restrict outbound ports to be used by Hazelcast-enabled applications. To fulfill this requirement, you can configure Hazelcast Java client to use only defined outbound ports. The following are example configurations.

Declarative configuration:

Programmatic configuration:

As shown in the programmatic configuration, you use the method addOutboundPort to add only one port. If you need to add a group of ports, then use the method addOutboundPortDefinition.

In the declarative configuration, the element ports can be used for both single and multiple port definitions.

You can configure the cluster routing mode to suit your requirements, as described in Client Cluster Routing Modes.

The following examples show the configuration for each cluster routing mode.

Client ALL_MEMBERS routing

To connect to all members, use the ALL_MEMBERS cluster routing mode, which can be defined as follows.

Client SINGLE_MEMBER routing

To connect to a single member, which can be used as a gateway to the other members, use the SINGLE_MEMBER cluster routing mode, which can be defined as described below.

When using the SINGLE_MEMBER cluster routing mode, consider the following:

Client MULTI_MEMBER routing

To connect to a subset partition grouping of members, which allows direct connection to the specified group and gateway connections to other members, use the MULTI_MEMBER cluster routing mode, which can be defined as follows.

To use the MULTI_MEMBER cluster routing mode, you must also define the grouping strategy to apply. For further information on configuring partition groups, see Partition Group Configuration.

When using the MULTI_MEMBER cluster routing mode, consider the following:

It enables/disables redo-able operations as described in Handling Retry-able Operation Failure. The following are the example configurations.

Declarative Configuration:

Programmatic Configuration:

Its default value is false (disabled).

Connection timeout is the timeout value in milliseconds for members to accept client connection requests.

The following code shows a declarative example configuration:

The following code shows a programmatic example configuration:

The default value is 5000 milliseconds.

Hazelcast Enterprise Edition

Any class implementing com.hazelcast.nio.SocketInterceptor is a socket interceptor. The following code sample shows an example of how to set a socket interceptor:

The first method initializes the SocketInterceptor using the defined properties. The second method informs when the socket is connected using the onConnect method.

The following example shows how to create a SocketInterceptor and add it to the client configuration:

If you want to configure the socket interceptor with a class name instead of an instance, see the example below:

You can configure the network socket options using SocketOptions. It has the following methods:

Hazelcast Enterprise Edition

You can use TLS to secure the connection between the client and the members. If you want TLS enabled for the client-cluster connection, you should set SSLConfig. For more information, see TLS.

Keys and certificates in keyStores are used to prove identity to the other side of the connection, and trustStores are used to specify trusted parties (from which the connection should be accepted). Clients only need to have their keyStores specified when TLS Mutual Authentication is required by members.

For a programmatic example, see this code example.

You can connect the Java Client and Embedded Server to a Cloud Standard cluster which is hosted on Cloud. For this, you need to enable Cloud and specify the cluster’s discovery token provided while creating the cluster; this allows the cluster to discover your clients. See the following example configurations:

The example declarative and programmatic configurations below show how to configure a Java client for connecting to a Hazelcast cluster in AWS (Amazon Web Services).

The distributed executor service is for distributed computing. It can be used to execute tasks on the cluster on a designated partition or on all the partitions. It can also be used to process entries. For more information, see Java Executor Service.

After getting an instance of IExecutorService, you can use the instance as the interface with the one provided on the server side. See Distributed Computing for detailed usage.

If you need to track clients and want to listen to their connection events, you can use the clientConnected() and clientDisconnected() methods of the ClientService class. This class must be run on the member side. The following code shows an example of how to do this:

You use the partition service to find the partition of a key. It returns all partitions. See the example code below:

Lifecycle handling performs:

You can define labels in your Java client, similar to the way labels are used for members. With client labels you can assign special roles for your clients and use these roles to perform actions specific to those client connections. For more information on labels, see Cluster Utilities.

You can also group your clients using labels. You can use Hazelcast Management Center to blocklist these client groups to prevent them connecting to a cluster. For more information, see Managing Client Connections.

The following declarative example shows how to define client using the client-labels configuration element:

The following programmatic example shows how to define client using the client-labels configuration element:

For an working code sample using client labels, see the Client labels code sample.

You can configure the client declaratively (XML), programmatically (API), or using client system properties.

For declarative configuration, the client checks the following places for the client configuration file:

If the client does not find a configuration file, it starts with the default configuration (hazelcast-client-default.xml) from the hazelcast.jar library.

If you want to define your own configuration file to create a Config object, you can do this using:

LoadBalancer enables you to send operations to one of a number of endpoints (members). Its main purpose is to determine the next member, if queried. You can use the com.hazelcast.client.LoadBalancer interface to apply different load balancing policies.

For Client cluster routing modes, the behaviour is as follows:

For example configurations, see the following code samples:

For client side serialization, use the Hazelcast configuration. For more information, see Serialization.

Normally when a client uses a Hazelcast data structure, that structure is configured on the member side and the client uses that configuration. For the Reliable Topic structure, which is backed by Ringbuffer, you need to configure it on the client side instead. The class used for this configuration is ClientReliableTopicConfig.

Here is an example programmatic configuration:

When you create a Reliable Topic structure on your client, a Ringbuffer (with the same name as the Reliable Topic) is automatically created on the member side, with the default configuration. See the Configuring Ringbuffer section for the defaults. You can edit that configuration according to your needs.

You can also declaratively configure a Reliable Topic structure on the client side, as the following declarative code example shows:

When a client is disconnected from the cluster, or is trying to connect to a cluster for the first time, it searches for new connections. You can configure the frequency of the connection attempts and client shutdown behavior using ConnectionRetryConfig (programmatic) or connection-retry (declarative).

Hazelcast Enterprise Edition

If you have Hazelcast Enterprise Edition, the client’s Near Cache can benefit from the High-Density Memory Store.

Let’s consider the Java client’s Near Cache configuration (see the Configure Client Near Cache section) without High-Density Memory Store:

You can configure this Near Cache to use Hazelcast’s High-Density Memory Store by setting the in-memory format to NATIVE. See the following configuration example:

The <eviction> element has the following attributes:

Keep in mind that you should have already enabled the High-Density Memory Store usage for your client, using the <native-memory> element in the client’s configuration.

See the High-Density Memory Store section for more information about Hazelcast’s High-Density Memory Store feature.

Hazelcast Enterprise Edition

Blue-green deployment refers to a client connection technique that reduces system downtime by deploying two mirrored clusters: blue (active) and green (idle). One of these clusters is running in production while the other is on standby.

Using the blue-green mechanism, clients can connect to another cluster automatically when they are blacklisted from their currently connected cluster. See the Hazelcast Management Center Reference Manual for information about blacklisting the clients.

The client’s behavior after this disconnection depends on its reconnect-mode. The following are the options when you are using the blue-green mechanism, i.e., you have alternative clusters for your clients to connect:

Consider the following notes for the blue-green mechanism (also valid for the disaster recovery mechanism described in the next section):

When one of your clusters is gone due to a failure, the connection between your clients and members in that cluster is gone too. When a client is disconnected because of a failure in the cluster, it first tries to reconnect to the same cluster.

The client’s behavior after this disconnection depends on its reconnect-mode, and it has the same options that are described in the above section (Blue-Green Mechanism).

If you have provided alternative clusters for your clients to connect, the client tries to connect to those alternative clusters (depending on the reconnect-mode).

When a failover starts, i.e., the client is disconnected and was configured to connect to alternative clusters, the current member list is not considered; the client cuts all the connections before attempting to connect to a new cluster and tries the clusters as configured. See the below configuration related sections.

The order of clusters that the client will try to reconnect in a blue-green or disaster recovery scenario is decided by the order of the cluster declarations defined in the client configuration.

Every time the client disconnects from a cluster and cannot connect back to the same cluster, this list is iterated over. The try-count configuration element limits the number of iterations before the client shuts down.

As an example, assume that your hazelcast-client-failover XML or YAML file defines the following order:

Which means you have three alternative clusters.

If the client is disconnected from the cluster configured in client-config2, the cluster will try to connect to the next cluster in the list, which is client-config3. If the client fails to connect to this cluster then the try-count is incremented, and the client tries to connect to the next alternative cluster, which in this case is client-config1 (because it has reached the end of the list and returns to the start). This iteration continues until either the client successfully connects to a cluster or the try-count limit is reached. If the try-count is reached without connecting, the client shuts down.

Deadline Failure Detector uses an absolute timeout for missing/lost heartbeats. After timeout, a member is considered as crashed/unavailable and marked as suspected.

Deadline Failure Detector has two configuration properties:

The following is a declarative example showing how you can configure the Deadline Failure Detector for your client (in the client’s configuration XML file, e.g., hazelcast-client.xml):

And, the following is the equivalent programmatic configuration:

In addition to the Deadline Failure Detector, the Ping Failure Detector may be configured on your client. Please note that this detector is disabled by default. The Ping Failure Detector operates at Layer 3 of the OSI protocol and provides much quicker and more deterministic detection of hardware and other lower level events. When the JVM process has enough permissions to create RAW sockets, the implementation chooses to rely on ICMP Echo requests. This is preferred.

If there are not enough permissions, it can be configured to fallback on attempting a TCP Echo on port 7. In the latter case, both a successful connection or an explicit rejection is treated as "Host is Reachable". Or, it can be forced to use only RAW sockets. This is not preferred as each call creates a heavyweight socket and moreover the Echo service is typically disabled.

For the Ping Failure Detector to rely only on the ICMP Echo requests, the following criteria need to be met:

The details of these requirements are explained in the Requirements section of Hazelcast members' Ping Failure Detector.

If any of the above criteria isn’t met, then isReachable will always fall back on TCP Echo attempts on port 7.

An example declarative configuration to use the Ping Failure Detector is as follows (in the client’s configuration XML file, e.g., hazelcast-client.xml):

And, the equivalent programmatic configuration:

The following are the descriptions of configuration elements and attributes:

In the above example configuration, the Ping Failure Detector attempts 2 pings, one every second, and waits up to 1 second for each to complete. If there is no successful ping after 2 seconds, the member gets suspected.

To enforce the Requirements, the property echo-fail-fast-on-startup can also be set to true, in which case Hazelcast fails to start if any of the requirements isn’t met.

Unlike the Hazelcast members, Ping Failure Detector works always in parallel with Deadline Failure Detector on the clients. Below is a summary table of all possible configuration combinations of the Ping Failure Detector.

The client failure detectors are responsible to determine if a member in the cluster is unreachable or crashed. The most important problem in the failure detection is to distinguish whether a member is still alive but slow, or has crashed. But according to the famous FLP result, it is impossible to distinguish a crashed member from a slow one in an asynchronous system. A workaround to this limitation is to use unreliable failure detectors. An unreliable failure detector allows a member to suspect that others have failed, usually based on liveness criteria but it can make mistakes to a certain degree.

Hazelcast Java client has two built-in failure detectors: Deadline Failure Detector and Ping Failure Detector. These client failure detectors work independently of the member failure detectors, e.g., you do not need to enable the member failure detectors to benefit from the client ones.