com.hazelcast.client

## Class HazelcastClient

- java.lang.Object
- - com.hazelcast.client.HazelcastClient

-     public final class HazelcastClient
      extends Object

  The HazelcastClient is comparable to the `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.

  # Smart vs unisocket clients

  Hazelcast Client enables you to do all Hazelcast operations without being a member of the cluster. Clients can be:
  1. smart: this means that they immediately can send an operation like map.get(key) to the member that owns that specific key.
  2. unisocket: it will connect to a random member in the cluster and send requests to this member. This member then needs to send the request to the correct member.
  For more information see `ClientNetworkConfig.setSmartRouting(boolean)`.

  # High availability

  When the connected cluster member dies, client will automatically switch to another live member.

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Collection<HazelcastInstance>` | `getAllHazelcastClients()` 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` | `newHazelcastClient()` 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` | `newHazelcastFailoverClient()` 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 list
    `static void` | `shutdown(String instanceName)` Shutdown the provided client and remove it from the managed list
    `static void` | `shutdownAll()` Shuts down all the client HazelcastInstance created in this JVM.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### newHazelcastClient

          public static HazelcastInstance 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:
      1. 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
      2. "hazelcast-client.xml" file in current working directory
      3. Classpath: Hazelcast will check classpath for hazelcast-client.xml file.
      4. "hazelcast-client.yaml" file in current working directory
      5. Classpath: Hazelcast will check classpath for hazelcast-client.yaml file.
      If Hazelcast doesn't find any config file, it will start with the default configuration (hazelcast-client-default.xml) located in hazelcast.jar.
      Returns:
        the new HazelcastInstance
      See Also:
        `shutdownAll()`, `(String)`

    - #### newHazelcastClient

          public static HazelcastInstance newHazelcastClient(ClientConfig config)

      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:
        `shutdownAll()`, `(String)`

    - #### newHazelcastFailoverClient

          public static HazelcastInstance newHazelcastFailoverClient()

      Creates a client with cluster switch capability. Client will try to connect to alternative clusters according to `ClientFailoverConfig` when it disconnects from a cluster. The configuration is loaded using using the following resolution mechanism:
      1. 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
      2. it checks if a hazelcast-client-failover.xml is available in the working dir
      3. it checks if a hazelcast-client-failover.xml is available on the classpath
      4. it checks if a hazelcast-client-failover.yaml is available in the working dir
      5. it checks if a hazelcast-client-failover.yaml is available on the classpath
      6. if none available `HazelcastException` is thrown
      Returns:
        the client instance
      Throws:
        `HazelcastException` - if no failover configuration is found
        `InvalidConfigurationException` - 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 to `ClientFailoverConfig` when it disconnects from a cluster. If provided clientFailoverConfig is `null`, the configuration is loaded using using the following resolution mechanism:
      1. 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
      2. it checks if a hazelcast-client-failover.xml is available in the working dir
      3. it checks if a hazelcast-client-failover.xml is available on the classpath
      4. it checks if a hazelcast-client-failover.yaml is available in the working dir
      5. it checks if a hazelcast-client-failover.yaml is available on the classpath
      6. 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 found
        `InvalidConfigurationException` - if the provided or the loaded failover configuration is not valid

    - #### getHazelcastClientByName

          public static HazelcastInstance getHazelcastClientByName(String instanceName)

      Returns an existing HazelcastClient with instanceName.
      Parameters:
        `instanceName` - Name of the HazelcastInstance (client) which can be retrieved by `HazelcastInstance.getName()`
      Returns:
        HazelcastInstance

    - #### getAllHazelcastClients

          public static Collection<HazelcastInstance> 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:
        `getAllHazelcastClients()`

    - #### shutdown

          public static void shutdown(HazelcastInstance instance)

      Shutdown the provided client and remove it from the managed list
      Parameters:
        `instance` - the hazelcast client instance

    - #### shutdown

          public static void shutdown(String instanceName)

      Shutdown the provided client and remove it from the managed list
      Parameters:
        `instanceName` - the hazelcast client instance name

    - #### setOutOfMemoryHandler

          public static void setOutOfMemoryHandler(OutOfMemoryHandler outOfMemoryHandler)

      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:
        `OutOfMemoryError`, `OutOfMemoryHandler`

Copyright © 2019. All rights reserved.