Chapter 14. The Hot Rod Interface

14.1. About Hot Rod

Hot Rod is a binary TCP client-server protocol used in Red Hat JBoss Data Grid. It was created to overcome deficiencies in other client/server protocols, such as Memcached.

Hot Rod will failover on a server cluster that undergoes a topology change. Hot Rod achieves this by providing regular updates to clients about the cluster topology.

Hot Rod enables clients to do smart routing of requests in partitioned or distributed Red Hat JBoss Data Grid server clusters. To do this, Hot Rod allows clients to determine the partition that houses a key and then communicate directly with the server that has the key. This functionality relies on Hot Rod updating the cluster topology with clients, and that the clients use the same consistent hash algorithm as the servers.

Red Hat JBoss Data Grid contains a server module that implements the Hot Rod protocol. The Hot Rod protocol facilitates faster client and server interactions in comparison to other text-based protocols and allows clients to make decisions about load balancing, failover and data location operations.

14.2. The Benefits of Using Hot Rod over Memcached

Red Hat JBoss Data Grid offers a choice of protocols for allowing clients to interact with the server in a Remote Client-Server environment. When deciding between using memcached or Hot Rod, the following should be considered.

Memcached

The memcached protocol causes the server endpoint to use the memcached text wire protocol. The memcached wire protocol has the benefit of being commonly used, and is available for almost any platform. All of JBoss Data Grid’s functions, including clustering, state sharing for scalability, and high availability, are available when using memcached.

However the memcached protocol lacks dynamicity, resulting in the need to manually update the list of server nodes on your clients in the event one of the nodes in a cluster fails. Also, memcached clients are not aware of the location of the data in the cluster. This means that they will request data from a non-owner node, incurring the penalty of an additional request from that node to the actual owner, before being able to return the data to the client. This is where the Hot Rod protocol is able to provide greater performance than memcached.

Hot Rod

JBoss Data Grid’s Hot Rod protocol is a binary wire protocol that offers all the capabilities of memcached, while also providing better scaling, durability, and elasticity.

The Hot Rod protocol does not need the hostnames and ports of each node in the remote cache, whereas memcached requires these parameters to be specified. Hot Rod clients automatically detect changes in the topology of clustered Hot Rod servers; when new nodes join or leave the cluster, clients update their Hot Rod server topology view. Consequently, Hot Rod provides ease of configuration and maintenance, with the advantage of dynamic load balancing and failover.

Additionally, the Hot Rod wire protocol uses smart routing when connecting to a distributed cache. This involves sharing a consistent hash algorithm between the server nodes and clients, resulting in faster read and writing capabilities than memcached.

Warning

When using JCache over Hot Rod it is not possible to create remote clustered caches, as the operation is executed on a single node as opposed to the entire cluster; however, once a cache has been created on the cluster it may be obtained using the cacheManager.getCache method.

It is recommended to create caches using either configuration files or the CLI.

14.3. Hot Rod Hash Functions

Hot Rod uses the same algorithm as on the server. The Hot Rod client always connects to the primary owner of the key, which is the first node in the list of owners. For more information about consistent hashing in Red Hat JBoss Data Grid, see Distribution Mode’s Consistent Hash Algorithm.

14.4. The Hot Rod Interface Connector

14.4.1. The Hot Rod Interface Connector

The following enables a Hot Rod server using the hotrod socket binding.

<hotrod-connector socket-binding="hotrod"
		  cache-container="local" />

The connector creates a supporting topology cache with default settings. These settings can be tuned by adding the <topology-state-transfer /> child element to the connector as follows:

<hotrod-connector socket-binding="hotrod"
		  cache-container="local">
   <topology-state-transfer lazy-retrieval="false"
   			    lock-timeout="1000"
   			    replication-timeout="5000" />
</hotrod-connector>

The Hot Rod connector can be tuned with additional settings. See Configure Hot Rod Connectors for more information on how to configure the Hot Rod connector.

Note

The Hot Rod connector can be secured using SSL. See the Hot Rod Authentication Using SASL section of the Developer Guide for more information.

14.4.2. Configure Hot Rod Connectors

The following procedure describes the attributes used to configure the Hot Rod connector in Red Hat JBoss Data Grid’s Remote Client-Server Mode. Both the hotrod-connector and topology-state-transfer elements must be configured based on the following procedure.

Configuring Hot Rod Connectors for Remote Client-Server Mode

<subsystem xmlns="urn:infinispan:server:endpoint:8.1">
	<hotrod-connector socket-binding="hotrod"
			  cache-container="local"
			  worker-threads="${VALUE}"
			  idle-timeout="${SECONDS}"
			  tcp-nodelay="${TRUE/FALSE}"
			  send-buffer-size="${VALUE}"
			  receive-buffer-size="${VALUE}" >
		<topology-state-transfer lock-timeout"="${MILLISECONDS}"
				 replication-timeout="${MILLISECONDS}"
				 external-host="${HOSTNAME}"
				 external-port="${PORT}"
				 lazy-retrieval="${TRUE/FALSE}"  />
	</hotrod-connector>
</subsystem>

  1. The hotrod-connector element defines the configuration elements for use with Hot Rod.

    • The socket-binding parameter specifies the socket binding port used by the Hot Rod connector. This is a mandatory parameter.
    • The cache-container parameter names the cache container used by the Hot Rod connector. This is a mandatory parameter.
    • The worker-threads parameter specifies the number of worker threads available for the Hot Rod connector. The default value for this parameter is 160. This is an optional parameter.
    • The idle-timeout parameter specifies the time, in seconds, that the connector can remain idle before the connection times out. The default value for this parameter is 0, which means that no timeout period is set. This is an optional parameter.
    • The tcp-nodelay parameter specifies whether TCP packets will be delayed and sent out in batches. Valid values for this parameter are true and false. The default value for this parameter is true. This is an optional parameter.
    • The send-buffer-size parameter indicates the size of the send buffer for the Hot Rod connector. The default value for this parameter is the size of the TCP stack buffer. This is an optional parameter.
    • The receive-buffer-size parameter indicates the size of the receive buffer for the Hot Rod connector. The default value for this parameter is the size of the TCP stack buffer. This is an optional parameter.
  2. The topology-state-transfer element specifies the topology state transfer configurations for the Hot Rod connector. This element can only occur once within a hotrod-connector element.

    • The lock-timeout parameter specifies the time (in milliseconds) after which the operation attempting to obtain a lock times out. The default value for this parameter is 10 seconds. This is an optional parameter.
    • The replication-timeout parameter specifies the time (in milliseconds) after which the replication operation times out. The default value for this parameter is 10 seconds. This is an optional parameter.
    • The external-host parameter specifies the hostname sent by the Hot Rod server to clients listed in the topology information. The default value for this parameter is the host address. This is an optional parameter.
    • The external-port parameter specifies the port sent by the Hot Rod server to clients listed in the topology information. The default value for this parameter is the configured port. This is an optional parameter.
    • The lazy-retrieval parameter indicates whether the Hot Rod connector will carry out retrieval operations lazily. The default value for this parameter is true. This is an optional parameter.