[id='hotrod-client-intelligence_{context}']
= Client Intelligence
Hot Rod clients use intelligence mechanisms to efficiently send requests to {brandname} Server clusters.
By default, the Hot Rod protocol has the `HASH_DISTRIBUTION_AWARE` intelligence mechanism enabled. This mechanism
allows the client to self-discover the nodes of a cluster. In this case, there is no need during the configuration
phase to pass the full list of cluster nodes.

.`BASIC` intelligence
Clients do not receive topology change events for {brandname} clusters, such as nodes joining or leaving, and use only the list of {brandname} Server network locations that you add to the client configuration.

[NOTE]
====
Enable `BASIC` intelligence to use the Hot Rod client configuration when a {brandname} Server does not send internal and hidden cluster topology to the Hot Rod client.
====

.`TOPOLOGY_AWARE` intelligence
Clients receive and store topology change events for {brandname} clusters to dynamically keep track of {brandname} Servers on the network.

To receive cluster topology, clients need the network location, either IP address or host name, of at least one Hot Rod server at startup.
After the client connects, {brandname} Server transmits the topology to the client.
When {brandname} Server nodes join or leave the cluster, {brandname} transmits an updated topology to the client.

.`HASH_DISTRIBUTION_AWARE` intelligence
Clients receive and store topology change events for {brandname} clusters in addition to hashing information that enables clients to identify which nodes store specific keys.

For example, consider a `put(k,v)` operation. The client calculates the hash value for the key so it can locate the exact {brandname} Server node on which the data resides.
Clients can then connect directly to that node to perform read and write operations.

The benefit of `HASH_DISTRIBUTION_AWARE` intelligence is that {brandname} Server does not need to look up values based on key hashes, which uses less server-side resources.
Another benefit is that {brandname} Server responds to client requests more quickly because they do not need to make additional network roundtrips.

[discrete]
== Configuration

By default, the Hot Rod client uses the intelligence that you configure globally for all {brandname} clusters.

.ConfigurationBuilder
[source,java,options="nowrap",subs=attributes+,role="primary"]
----
include::code_examples/HotRodClientIntelligence.java[]
----

.hotrod-client.properties
[source,options="nowrap",subs=attributes+,role="secondary"]
----
include::properties/hotrod-client-intelligence.properties[]
----

When you configure the Hot Rod client to use multiple {brandname} clusters, you can use different intelligence for each cluster.

.ConfigurationBuilder
[source,java,options="nowrap",subs=attributes+,role="primary"]
----
include::code_examples/HotRodClientIntelligenceCluster.java[]
----

.hotrod-client.properties
[source,options="nowrap",subs=attributes+,role="secondary"]
----
include::properties/hotrod-client-intelligence-cluster.properties[]
----


[discrete]
== Failed Server Timeout

If a server does not report the topology as BASIC, or the client is unable to connect to a server due to network issues, the client will mark the server as failed.
A client does not attempt to connect to a server marked as failed until the client receives an updated topology.
Because BASIC topology never sends an update, the client will not re-attempt connection.

To avoid such a situation, you can use the `serverFailureTimeout` setting that clears the failed server status after a defined period of time.
{brandname} will try to reconnect to the server after the defined timeout. If the server is still unreachable, it is marked as failed again and the connection will be re-attempted after the defined timeout.
You can disable reconnection attempts by setting the `serverFailureTimeout` value to `-1`.

.ConfigurationBuilder
[source,java,options="nowrap",subs=attributes+,role="primary"]
----
include::code_examples/HotRodClientFailedServerTimeout.java[]
----

.hotrod-client.properties
[source,options="nowrap",subs=attributes+,role="secondary"]
----
include::properties/hotrod-client-failed-server-timeout.properties[]
----

[role="_additional-resources"]
.Additional resources
* link:../../apidocs/org/infinispan/client/hotrod/configuration/ClientIntelligence.html[org.infinispan.client.hotrod.configuration.ClientIntelligence]

