HazelcastClient API Documentation

class HazelcastClient(**kwargs)[source]

Bases: object

Hazelcast client instance to access and manipulate distributed data structures on the Hazelcast clusters.

Keyword Arguments
  • cluster_members (list[str]) – Candidate address list that the client will use to establish initial connection. By default, set to ["127.0.0.1"].

  • cluster_name (str) – Name of the cluster to connect to. The name is sent as part of the the client authentication message and may be verified on the member. By default, set to dev.

  • client_name (str) – Name of the client instance. By default, set to hz.client_${CLIENT_ID}, where CLIENT_ID starts from 0 and it is incremented by 1 for each new client.

  • connection_timeout (float) – Socket timeout value in seconds for the client to connect member nodes. Setting this to 0 makes the connection blocking. By default, set to 5.0.

  • socket_options (list[tuple]) – List of socket option tuples. The tuples must contain the parameters passed into the socket.setsockopt() in the same order.

  • redo_operation (bool) – When set to True, the client will redo the operations that were executing on the server in case if the client lost connection. This can happen because of network problems, or simply because the member died. However it is not clear whether the operation was performed or not. For idempotent operations this is harmless, but for non idempotent ones retrying can cause to undesirable effects. Note that the redo can be processed on any member. By default, set to False.

  • smart_routing (bool) – Enables smart mode for the client instead of unisocket client. Smart clients send key based operations to owner of the keys. Unisocket clients send all operations to a single node. By default, set to True.

  • ssl_enabled (bool) – If it is True, SSL is enabled. By default, set to False.

  • ssl_cafile (str) – Absolute path of concatenated CA certificates used to validate server’s certificates in PEM format. When SSL is enabled and cafile is not set, a set of default CA certificates from default locations will be used.

  • ssl_certfile (str) – Absolute path of the client certificate in PEM format.

  • ssl_keyfile (str) – Absolute path of the private key file for the client certificate in the PEM format. If this parameter is None, private key will be taken from the certfile.

  • ssl_password (str|bytes|bytearray|function) – Password for decrypting the keyfile if it is encrypted. The password may be a function to call to get the password. It will be called with no arguments, and it should return a string, bytes, or bytearray. If the return value is a string it will be encoded as UTF-8 before using it to decrypt the key. Alternatively a string, bytes, or bytearray value may be supplied directly as the password.

  • ssl_protocol (int|str) – Protocol version used in SSL communication. By default, set to TLSv1_2. See the hazelcast.config.SSLProtocol for possible values.

  • ssl_ciphers (str) – String in the OpenSSL cipher list format to set the available ciphers for sockets. More than one cipher can be set by separating them with a colon.

  • cloud_discovery_token (str) – Discovery token of the Hazelcast Cloud cluster. When this value is set, Hazelcast Cloud discovery is enabled.

  • async_start (bool) – Enables non-blocking start mode of the client. When set to True, the client creation will not wait to connect to cluster. The client instance will throw exceptions until it connects to cluster and becomes ready. If set to False, the client will block until a cluster connection established and it is ready to use the client instance. By default, set to False.

  • reconnect_mode (int|str) – Defines how the client reconnects to cluster after a disconnect. By default, set to ON. See the hazelcast.config.ReconnectMode for possible values.

  • retry_initial_backoff (float) – Wait period in seconds after the first failure before retrying. Must be non-negative. By default, set to 1.0.

  • retry_max_backoff (float) – Upper bound for the backoff interval in seconds. Must be non-negative. By default, set to 30.0.

  • retry_jitter (float) – Defines how much to randomize backoffs. At each iteration the calculated back-off is randomized via following method in pseudo-code Random(-jitter * current_backoff, jitter * current_backoff). Must be in range [0.0, 1.0]. By default, set to 0.0 (no randomization).

  • retry_multiplier (float) – The factor with which to multiply backoff after a failed retry. Must be greater than or equal to 1. By default, set to 1.05.

  • cluster_connect_timeout (float) – Timeout value in seconds for the client to give up connecting to the cluster. Must be non-negative or equal to -1. By default, set to -1. -1 means that the client will not stop trying to the target cluster. (infinite timeout)

  • portable_version (int) – Default value for the portable version if the class does not have the get_portable_version() method. Portable versions are used to differentiate two versions of the hazelcast.serialization.api.Portable classes that have added or removed fields, or fields with different types.

  • data_serializable_factories (dict[int, dict[int, class]]) –

    Dictionary of factory id and corresponding hazelcast.serialization.api.IdentifiedDataSerializable factories. A factory is simply a dictionary with class id and callable class constructors.

    FACTORY_ID = 1
    CLASS_ID = 1
    
    class SomeSerializable(IdentifiedDataSerializable):
        # omitting the implementation
        pass
    
    
    client = HazelcastClient(data_serializable_factories={
        FACTORY_ID: {
            CLASS_ID: SomeSerializable
        }
    })
    

  • portable_factories (dict[int, dict[int, class]]) –

    Dictionary of factory id and corresponding hazelcast.serialization.api.Portable factories. A factory is simply a dictionary with class id and callable class constructors.

    FACTORY_ID = 2
    CLASS_ID = 2
    
    class SomeSerializable(Portable):
        # omitting the implementation
        pass
    
    
    client = HazelcastClient(portable_factories={
        FACTORY_ID: {
            CLASS_ID: SomeSerializable
        }
    })
    

  • class_definitions (list[hazelcast.serialization.portable.classdef.ClassDefinition]) – List of all portable class definitions.

  • check_class_definition_errors (bool) – When enabled, serialization system will check for class definitions error at start and throw an HazelcastSerializationError with error definition. By default, set to True.

  • is_big_endian (bool) – Defines if big-endian is used as the byte order for the serialization. By default, set to True.

  • default_int_type (int|str) – Defines how the int/long type is represented on the cluster side. By default, it is serialized as INT (32 bits). See the hazelcast.config.IntType for possible values.

  • global_serializer (hazelcast.serialization.api.StreamSerializer) – Defines the global serializer. This serializer is registered as a fallback serializer to handle all other objects if a serializer cannot be located for them.

  • custom_serializers (dict[class, hazelcast.serialization.api.StreamSerializer]) –

    Dictionary of class and the corresponding custom serializers.

    class SomeClass:
        # omitting the implementation
        pass
    
    
    class SomeClassSerializer(StreamSerializer):
        # omitting the implementation
        pass
    
    client = HazelcastClient(custom_serializers={
        SomeClass: SomeClassSerializer
    })
    

  • near_caches (dict[str, dict[str, any]]) –

    Dictionary of near cache names and the corresponding near cache configurations as a dictionary. The near cache configurations contains the following options. When an option is missing from the configuration, it will be set to its default value.

    • invalidate_on_change (bool): Enables cluster-assisted invalidate on change behavior. When set to True, entries are invalidated when they are changed in cluster. By default, set to True.

    • in_memory_format (int|str): Specifies in which format data will be stored in the Near Cache. By default, set to BINARY. See the hazelcast.config.InMemoryFormat for possible values.

    • time_to_live (float): Maximum number of seconds that an entry can stay in cache. When not set, entries won’t be evicted due to expiration.

    • max_idle (float): Maximum number of seconds that an entry can stay in the Near Cache until it is accessed. When not set, entries won’t be evicted due to inactivity.

    • eviction_policy (int|str): Defines eviction policy configuration. By default, set to LRU. See the hazelcast.config.EvictionPolicy for possible values.

    • eviction_max_size (int): Defines maximum number of entries kept in the memory before eviction kicks in. By default, set to 10000.

    • eviction_sampling_count (int): Number of random entries that are evaluated to see if some of them are already expired. By default, set to 8.

    • eviction_sampling_pool_size (int): Size of the pool for eviction candidates. The pool is kept sorted according to the eviction policy. By default, set to 16.

  • load_balancer (hazelcast.util.LoadBalancer) – Load balancer implementation for the client.

  • membership_listeners (list[tuple[function, function]]) – List of membership listener tuples. Tuples must be of size 2. The first element will be the function to be called when a member is added, and the second element will be the function to be called when the member is removed with the hazelcast.core.MemberInfo as the only parameter. Any of the elements can be None, but not at the same time.

  • lifecycle_listeners (list[function]) – List of lifecycle listeners. Listeners will be called with the new lifecycle state as the only parameter when the client changes lifecycle states.

  • flake_id_generators (dict[str, dict[str, any]]) –

    Dictionary of flake id generator names and the corresponding flake id generator configurations as a dictionary. The flake id generator configurations contains the following options. When an option is missing from the configuration, it will be set to its default value.

    • prefetch_count (int): Defines how many IDs are pre-fetched on the background when a new flake id is requested from the cluster. Should be in the range 1..100000. By default, set to 100.

    • prefetch_validity (float): Defines for how long the pre-fetched IDs can be used. If this time elapsed, a new batch of IDs will be fetched. Time unit is in seconds. By default, set to 600 (10 minutes).

      The IDs contain timestamp component, which ensures rough global ordering of IDs. If an ID is assigned to an object that was created much later, it will be much out of order. If you don’t care about ordering, set this value to 0 for unlimited ID validity.

  • reliable_topics (dict[str, dict[str, any]]) –

    Dictionary of reliable topic names and the corresponding reliable topic configurations as a dictionary. The reliable topic configurations contain the following options. When an option is missing from the configuration, it will be set to its default value.

    • overload_policy (int|str): Policy to handle an overloaded topic. By default, set to BLOCK. See the hazelcast.config.TopicOverloadPolicy for possible values.

    • read_batch_size (int): Number of messages the reliable topic will try to read in batch. It will get at least one, but if there are more available, then it will try to get more to increase throughput. By default, set to 10.

  • labels (list[str]) – Labels for the client to be sent to the cluster.

  • heartbeat_interval (float) – Time interval between the heartbeats sent by the client to the member nodes in seconds. By default, set to 5.0.

  • heartbeat_timeout (float) – If there is no message passing between the client and a member within the given time via this property in seconds, the connection will be closed. By default, set to 60.0.

  • invocation_timeout (float) –

    When an invocation gets an exception because

    • Member throws an exception.

    • Connection between the client and member is closed.

    • The client’s heartbeat requests are timed out.

    Time passed since invocation started is compared with this property. If the time is already passed, then the exception is delegated to the user. If not, the invocation is retried. Note that, if invocation gets no exception and it is a long running one, then it will not get any exception, no matter how small this timeout is set. Time unit is in seconds. By default, set to 120.0.

  • invocation_retry_pause (float) – Pause time between each retry cycle of an invocation in seconds. By default, set to 1.0.

  • statistics_enabled (bool) – When set to True, the client statistics collection is enabled. By default, set to False.

  • statistics_period (float) – The period in seconds the statistics run.

  • shuffle_member_list (bool) – The Client shuffles the given member list to prevent all clients to connect to the same node when this property is set to True. When it is set to False, the client tries to connect to the nodes in the given order. By default, set to True.

  • backup_ack_to_client_enabled (bool) – Enables the client to get backup acknowledgements directly from the member that backups are applied, which reduces number of hops and increases performance for smart clients. This option has no effect for unisocket clients. By default, set to True (enabled).

  • operation_backup_timeout (float) – If an operation has backups, defines how long the invocation will wait for acks from the backup replicas in seconds. If acks are not received from some backups, there won’t be any rollback on other successful replicas. By default, set to 5.0.

  • fail_on_indeterminate_operation_state (bool) – When enabled, if an operation has sync backups and acks are not received from backup replicas in time, or the member which owns primary replica of the target partition leaves the cluster, then the invocation fails with hazelcast.errors.IndeterminateOperationStateError. However, even if the invocation fails, there will not be any rollback on other successful replicas. By default, set to False (do not fail).

  • creds_username (str) – Username for credentials authentication (Enterprise feature).

  • creds_password (str) – Password for credentials authentication (Enterprise feature).

  • token_provider (hazelcast.security.TokenProvider) – Token provider for custom authentication (Enterprise feature). Note that token_provider setting has priority over credentials settings.

  • use_public_ip (bool) – When set to True, the client uses the public IP addresses reported by members while connecting to them, if available. By default, set to False.

get_executor(name)[source]

Creates cluster-wide ExecutorService.

Parameters

name (str) – Name of the Executor proxy.

Returns

Executor proxy for the given name.

Return type

hazelcast.proxy.executor.Executor

get_flake_id_generator(name)[source]

Creates or returns a cluster-wide FlakeIdGenerator.

Parameters

name (str) – Name of the FlakeIdGenerator proxy.

Returns

FlakeIdGenerator proxy for the given name

Return type

hazelcast.proxy.flake_id_generator.FlakeIdGenerator

get_queue(name)[source]

Returns the distributed queue instance with the specified name.

Parameters

name (str) – Name of the distributed queue.

Returns

Distributed queue instance with the specified name.

Return type

hazelcast.proxy.queue.Queue

get_list(name)[source]

Returns the distributed list instance with the specified name.

Parameters

name (str) – Name of the distributed list.

Returns

Distributed list instance with the specified name.

Return type

hazelcast.proxy.list.List

get_map(name)[source]

Returns the distributed map instance with the specified name.

Parameters

name (str) – Name of the distributed map.

Returns

Distributed map instance with the specified name.

Return type

hazelcast.proxy.map.Map

get_multi_map(name)[source]

Returns the distributed MultiMap instance with the specified name.

Parameters

name (str) – Name of the distributed MultiMap.

Returns

Distributed MultiMap instance with the specified name.

Return type

hazelcast.proxy.multi_map.MultiMap

get_pn_counter(name)[source]

Returns the PN Counter instance with the specified name.

Parameters

name (str) – Name of the PN Counter.

Returns

The PN Counter.

Return type

hazelcast.proxy.pn_counter.PNCounter

get_reliable_topic(name)[source]

Returns the ReliableTopic instance with the specified name.

Parameters

name (str) – Name of the ReliableTopic.

Returns

The ReliableTopic.

Return type

hazelcast.proxy.reliable_topic.ReliableTopic

get_replicated_map(name)[source]

Returns the distributed ReplicatedMap instance with the specified name.

Parameters

name (str) – Name of the distributed ReplicatedMap.

Returns

Distributed ReplicatedMap instance with the specified name.

Return type

hazelcast.proxy.replicated_map.ReplicatedMap

get_ringbuffer(name)[source]

Returns the distributed Ringbuffer instance with the specified name.

Parameters

name (str) – Name of the distributed Ringbuffer.

Returns

Distributed RingBuffer instance with the specified name.

Return type

hazelcast.proxy.ringbuffer.Ringbuffer

get_set(name)[source]

Returns the distributed Set instance with the specified name.

Parameters

name (str) – Name of the distributed Set.

Returns

Distributed Set instance with the specified name.

Return type

hazelcast.proxy.set.Set

get_topic(name)[source]

Returns the Topic instance with the specified name.

Parameters

name (str) – Name of the Topic.

Returns

The Topic.

Return type

hazelcast.proxy.topic.Topic

new_transaction(timeout=120, durability=1, type=1)[source]

Creates a new Transaction associated with the current thread using default or given options.

Parameters
  • timeout (int) – The timeout in seconds determines the maximum lifespan of a transaction. So if a transaction is configured with a timeout of 2 minutes, then it will automatically rollback if it hasn’t committed yet.

  • durability (int) – The durability is the number of machines that can take over if a member fails during a transaction commit or rollback.

  • type (int) – The transaction type which can be TWO_PHASE or ONE_PHASE.

Returns

New Transaction associated with the current thread.

Return type

hazelcast.transaction.Transaction

add_distributed_object_listener(listener_func)[source]

Adds a listener which will be notified when a new distributed object is created or destroyed.

Parameters

listener_func (function) – Function to be called when a distributed object is created or destroyed.

Returns

A registration id which is used as a key to remove the listener.

Return type

hazelcast.future.Future[str]

remove_distributed_object_listener(registration_id)[source]

Removes the specified distributed object listener.

Returns silently if there is no such listener added before.

Parameters

registration_id (str) – The id of registered listener.

Returns

True if registration is removed, False otherwise.

Return type

hazelcast.future.Future[bool]

get_distributed_objects()[source]

Returns all distributed objects such as; queue, map, set, list, topic, lock, multimap.

Also, as a side effect, it clears the local instances of the destroyed proxies.

Returns

List of instances created by Hazelcast.

Return type

list[hazelcast.proxy.base.Proxy]

shutdown()[source]

Shuts down this HazelcastClient.

property name

Name of the client.

Type

str

property lifecycle_service

Lifecycle service allows you to check if the client is running and add and remove lifecycle listeners.

Type

LifecycleService

property partition_service

Partition service allows you to get partition count, introspect the partition owners, and partition ids of keys.

Type

PartitionService

property cluster_service

Cluster service allows you to get the list of the cluster members and add and remove membership listeners.

Type

ClusterService

property cp_subsystem

CP Subsystem offers set of in-memory linearizable data structures.

Type

CPSubsystem