Class HazelcastClient
Hazelcast
class and provides the ability
the create and manage Hazelcast clients. Hazelcast clients are HazelcastInstance
implementations, so
in most cases most of the code is unaware of talking to a cluster member or a client.
ALL_MEMBERS vs MULTI_MEMBER vs SINGLE_MEMBER routing clients
Hazelcast Client enables you to do all Hazelcast operations without being a member of the cluster. Clients can use one of the following routing modes:- ALL_MEMBERS: client connects to all members of the cluster and this means that they immediately can send an operation like map.get(key) to the member that owns that specific key.
- MULTI_MEMBER: client connects to a subset of members of the cluster, based on a provided grouping strategy. This means that they can send an operation like map.get(key) to the member that owns that specific key, if that member is available in this client's subset.
- SINGLE_MEMBER: it will connect to a random single member of the cluster and send requests to this member. This member then needs to send the request to the correct member.
ClientNetworkConfig.getClusterRoutingConfig()
}.
High availability
When the connected cluster member dies, client will automatically switch to another live member.-
Method Summary
Modifier and TypeMethodDescriptionstatic Collection<HazelcastInstance>
Gets an immutable collection of all client HazelcastInstances created in this JVM.static HazelcastInstance
getHazelcastClientByName
(String instanceName) Returns an existing HazelcastClient with instanceName.static HazelcastInstance
Gets or creates a new HazelcastInstance (a new client in a cluster) with the default XML configuration looked up in: System property: Hazelcast will first check if "hazelcast.client.config" system property is set to a file or aclasspath:...
path.static HazelcastInstance
Gets or creates a new HazelcastInstance (a new client in a cluster) with a certain name.static HazelcastInstance
Creates a new HazelcastInstance (a new client in a cluster).static HazelcastInstance
newHazelcastClient
(ClientConfig config) Creates a new HazelcastInstance (a new client in a cluster).static HazelcastInstance
Creates a client with cluster switch capability.static HazelcastInstance
newHazelcastFailoverClient
(ClientFailoverConfig clientFailoverConfig) Creates a client with cluster switch capability.static void
setOutOfMemoryHandler
(OutOfMemoryHandler outOfMemoryHandler) Sets OutOfMemoryHandler to be used when an OutOfMemoryError is caught by Hazelcast Client threads.static void
shutdown
(HazelcastInstance instance) Shutdown the provided client and remove it from the managed liststatic void
Shutdown the provided client and remove it from the managed liststatic void
Shuts down all the client HazelcastInstance created in this JVM.
-
Method Details
-
newHazelcastClient
Creates a new HazelcastInstance (a new client in a cluster). This method allows you to create and run multiple instances of Hazelcast clients on the same JVM.To shutdown all running HazelcastInstances (all clients on this JVM) call
shutdownAll()
.Hazelcast will look into two places for the configuration file:
-
System property: Hazelcast will first check if "hazelcast.client.config" system property is set to a file or a
classpath:...
path. The configuration can either be an XML or a YAML configuration, distinguished by the suffix ('.xml' or '.yaml') of the provided configuration file's name Examples: -Dhazelcast.client.config=C:/myhazelcastclient.xml , -Dhazelcast.client.config=classpath:the-hazelcast-config.yaml , -Dhazelcast.client.config=classpath:com/mydomain/hazelcast.xml - "hazelcast-client.xml" file in current working directory
- Classpath: Hazelcast will check classpath for hazelcast-client.xml file.
- "hazelcast-client.yaml" file in current working directory
- Classpath: Hazelcast will check classpath for hazelcast-client.yaml file.
- Returns:
- the new HazelcastInstance
- See Also:
-
System property: Hazelcast will first check if "hazelcast.client.config" system property is set to a file or a
-
newHazelcastClient
Creates a new HazelcastInstance (a new client in a cluster). This method allows you to create and run multiple instances of Hazelcast clients on the same JVM.To shutdown all running HazelcastInstances (all clients on this JVM) call
shutdownAll()
.- Parameters:
config
- Configuration for the new HazelcastInstance (member)- Returns:
- the new HazelcastInstance
- See Also:
-
newHazelcastFailoverClient
Creates a client with cluster switch capability. Client will try to connect to alternative clusters according toClientFailoverConfig
when it disconnects from a cluster.The configuration is loaded using using the following resolution mechanism:
- first it checks if a system property 'hazelcast.client.failover.config' is set. If it exist and it begins with 'classpath:', then a classpath resource is loaded. Else it will assume it is a file reference. The configuration can either be an XML or a YAML configuration, distinguished by the suffix ('.xml' or '.yaml') of the provided configuration file's name
- it checks if a hazelcast-client-failover.xml is available in the working dir
- it checks if a hazelcast-client-failover.xml is available on the classpath
- it checks if a hazelcast-client-failover.yaml is available in the working dir
- it checks if a hazelcast-client-failover.yaml is available on the classpath
- if none available
HazelcastException
is thrown
- Returns:
- the client instance
- Throws:
HazelcastException
- if no failover configuration is foundInvalidConfigurationException
- if the loaded failover configuration is not valid
-
newHazelcastFailoverClient
public static HazelcastInstance newHazelcastFailoverClient(ClientFailoverConfig clientFailoverConfig) Creates a client with cluster switch capability. Client will try to connect to alternative clusters according toClientFailoverConfig
when it disconnects from a cluster.If provided clientFailoverConfig is
null
, the configuration is loaded using using the following resolution mechanism:- first it checks if a system property 'hazelcast.client.failover.config' is set. If it exist and it begins with 'classpath:', then a classpath resource is loaded. Else it will assume it is a file reference. The configuration can either be an XML or a YAML configuration, distinguished by the suffix ('.xml' or '.yaml') of the provided configuration file's name
- it checks if a hazelcast-client-failover.xml is available in the working dir
- it checks if a hazelcast-client-failover.xml is available on the classpath
- it checks if a hazelcast-client-failover.yaml is available in the working dir
- it checks if a hazelcast-client-failover.yaml is available on the classpath
- if none available
HazelcastException
is thrown
- Parameters:
clientFailoverConfig
- config describing the failover configs and try count- Returns:
- the client instance
- Throws:
HazelcastException
- if no failover configuration is foundInvalidConfigurationException
- if the provided or the loaded failover configuration is not valid
-
getHazelcastClientByName
Returns an existing HazelcastClient with instanceName.- Parameters:
instanceName
- Name of the HazelcastInstance (client) which can be retrieved byHazelcastInstance.getName()
- Returns:
- HazelcastInstance
-
getOrCreateHazelcastClient
Gets or creates a new HazelcastInstance (a new client in a cluster) with the default XML configuration looked up in:-
System property: Hazelcast will first check if "hazelcast.client.config" system property is set to a file or a
classpath:...
path. The configuration can either be an XML or a YAML configuration, distinguished by the suffix ('.xml' or '.yaml') of the provided configuration file's name Examples: -Dhazelcast.client.config=C:/myhazelcastclient.xml , -Dhazelcast.client.config=classpath:the-hazelcast-config.yaml , -Dhazelcast.client.config=classpath:com/mydomain/hazelcast.xml - "hazelcast-client.xml" file in current working directory
- Classpath: Hazelcast will check classpath for hazelcast-client.xml file.
- "hazelcast-client.yaml" file in current working directory
- Classpath: Hazelcast will check classpath for hazelcast-client.yaml file.
If a configuration file is not located, an
IllegalArgumentException
will be thrown. If a Hazelcast instance with the same name as the configuration exists, then it is returned, otherwise it is created.- Returns:
- the new HazelcastInstance
- Throws:
IllegalArgumentException
- if the instance name of the config is null or empty or if no config file can be located.- See Also:
-
System property: Hazelcast will first check if "hazelcast.client.config" system property is set to a file or a
-
getOrCreateHazelcastClient
Gets or creates a new HazelcastInstance (a new client in a cluster) with a certain name.If a Hazelcast instance with the same name as the configuration exists, then it is returned, otherwise it is created.
If
config
isnull
, Hazelcast will look into two places for the configuration file:-
System property: Hazelcast will first check if "hazelcast.client.config" system property is set to a file or a
classpath:...
path. The configuration can either be an XML or a YAML configuration, distinguished by the suffix ('.xml' or '.yaml') of the provided configuration file's name Examples: -Dhazelcast.client.config=C:/myhazelcastclient.xml , -Dhazelcast.client.config=classpath:the-hazelcast-config.yaml , -Dhazelcast.client.config=classpath:com/mydomain/hazelcast.xml - "hazelcast-client.xml" file in current working directory
- Classpath: Hazelcast will check classpath for hazelcast-client.xml file.
- "hazelcast-client.yaml" file in current working directory
- Classpath: Hazelcast will check classpath for hazelcast-client.yaml file.
If a configuration file is not located, an
IllegalArgumentException
will be thrown.- Parameters:
config
- Client configuration- Returns:
- the new HazelcastInstance
- Throws:
IllegalArgumentException
- if the instance name of the config is null or empty or if no config file can be located.- See Also:
-
System property: Hazelcast will first check if "hazelcast.client.config" system property is set to a file or a
-
getAllHazelcastClients
Gets an immutable collection of all client HazelcastInstances created in this JVM.In managed environments such as Java EE or OSGi Hazelcast can be loaded by multiple classloaders. Typically you will get at least one classloader per every application deployed. In these cases only the client HazelcastInstances created by the same application will be seen, and instances created by different applications are invisible.
The returned collection is a snapshot of the client HazelcastInstances. So changes to the client HazelcastInstances will not be visible in this collection.
- Returns:
- the collection of client HazelcastInstances
-
shutdownAll
public static void shutdownAll()Shuts down all the client HazelcastInstance created in this JVM.To be more precise it shuts down the HazelcastInstances loaded using the same classloader this HazelcastClient has been loaded with.
This method is mostly used for testing purposes.
- See Also:
-
shutdown
Shutdown the provided client and remove it from the managed list- Parameters:
instance
- the hazelcast client instance
-
shutdown
Shutdown the provided client and remove it from the managed list- Parameters:
instanceName
- the hazelcast client instance name
-
setOutOfMemoryHandler
Sets OutOfMemoryHandler to be used when an OutOfMemoryError is caught by Hazelcast Client threads.Warning: OutOfMemoryHandler may not be called although JVM throws OutOfMemoryError. Because error may be thrown from an external (user thread) thread and Hazelcast may not be informed about OutOfMemoryError.
- Parameters:
outOfMemoryHandler
- set when an OutOfMemoryError is caught by HazelcastClient threads- See Also:
-