Getting started with JBoss Data Grid for xPaaS - Hot Rod Service

This article describes how to get started with JBoss Data Grid on OpenShift using the Hot Rod service. 

JBoss Data Grid for xPaaS is currently only supported in Client-Server Mode. Applications can remotely access the data grid server using Hot Rod, Memcached or REST client APIs. For details on the REST service please see here. 

Hot Rod is a binary TCP client-server protocol that enables clients to do smart routing of requests in partitioned or distributed JBoss Data Grid server clusters. 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. Hot Rod provides failover to a server cluster by the servers providing regular updates to clients about the cluster topology.

In OpenShift one can access the DataGrid via a clustered IP address called Service. Exposing a Hot Rod services in OpenShift means that other applications running in OpenShift can access the data grid using Hot Rod and the clustered IP address. Default the Hot Rod service is listening on 11222, but the Hot Rod service is default exposed via 11333. The reason for this is that the Hot Rod client will connect via the service on 11333, but then the cluster view directly to the pods making up the service using port 11222. This way one can scale JBoss Data Grid by increasing the amount of replicas ( e.g. pods ) that are used. Since Hot Rod is aware of the cluster topology and also aware of the distribution mechanism Hot Rod clients can directly connect to the pod containing the data entry without having to do additional network hops. 

Above picture illustrates an example of an application running in JBoss Enterprise Application Platform accessing a cluster of JBoss Data Grid nodes in a single OpenShift project. The red connections illustrate how the client connects to the cluster and get the full topology of the cluster back. The orange connections illustrate how the application access data in the data grid. 

How to Connect a Hot Rod Client to a JDG Server in OpenShift

All the client needs to connect to the data grid is the Hot Rod Service IP and the Hot Rod Port. The most common way to pass this information to a client in OpenShift is via environment variables. If the data grid and the application is in the same project, one can use templates to automatically inject these environment variables. For example, the EAP pod can be started with the following environment variable from the template. If our data grid service definition looks something like this:

{     "kind": "Service",     "apiVersion": "v1",     "spec": {         "ports": [             {                 "port": 11333,                 "targetPort": 11333             }         ],         "selector": {             "deploymentConfig": "${APPLICATION_NAME}-datagrid"         }     },     "metadata": {         "name": "${APPLICATION_NAME}-datagrid-hotrod",         "labels": {             "application": "${APPLICATION_NAME}-datagrid"         },         "annotations": {             "description": "Hot Rod service for clustered applications."         }     } }

If we have the EAP application in the same project it will automatically get the following environment variables populated. 

• ${APPLICATION_NAME}_DATAGRID_HOTROD_SERVICE_HOST - contains the IP address to the Hot Rod Service, for example, 172.30.99.35
• ${APPLICATION_NAME}_DATAGRID_HOTROD_SERVICE_PORT - contains the port used to expose the Hot Rod Service, for example, 11333

"env": [

  {

    "name": "JDG_SERVICE_NAME",

    "value": "${APPLICATION_NAME}_DATAGRID"

  }

]

In the application we will programmatically have to read the environment variables like this:

@Produces @MyCache

public RemoteCache<Long, Task> getRemoteCache() throws IOException, DataGridConfigurationException {

RemoteCacheManager cacheManager = this.getCacheManager();

return cacheManager.getCache(CACHE_NAME);

}

public RemoteCacheManager getCacheManager() throws DataGridConfigurationException {

ConfigurationBuilder builder = new ConfigurationBuilder();

builder

.nearCache()

.mode(NearCacheMode.LAZY)

.maxEntries(500)

.addServer()

.host(getHotRodHostFromEnvironment())

.port(getHotRodPortFromEnvironment())

return new RemoteCacheManager(builder.build(), true);

}

private static String getHotRodHostFromEnvironment() throws DataGridConfigurationException {

String hotrodServiceName = System.getenv("JDG_SERVICE_NAME");

if(hotrodServiceName == null) {

throw new DataGridConfigurationException("Failed to get JDG Service Name from environment variables. please make sure that you set this value before starting the container");

}

String hotRodHost=System.getenv(hotrodServiceName.toUpperCase().replace('-','_') + ENV_VAR_SUFFIX_HOTROD_SERVICE_HOST);

if(hotRodHost == null) {

throw new DataGridConfigurationException(String.format("Failed to get hostname/ip address for service %s",hotrodServiceName));

}

return hotRodHost;

}

private static int getHotRodPortFromEnvironment() throws DataGridConfigurationException {

String hotrodServiceName = System.getenv(ENV_VAR_JDG_SERVICE_NAME);

if(hotrodServiceName == null) {

throw new DataGridConfigurationException("Failed to get JDG Service Name from environment variables. please make sure that you set this value before starting the container");

}

String hotRodPort=System.getenv(hotrodServiceName.toUpperCase().replace('-','_') + "");

if(hotRodPort == null) {

throw new DataGridConfigurationException(String.format("Failed to get Hot Rod Port for service %s",hotrodServiceName));

}

return Integer.parseInt(hotRodPort);

}

public static class DataGridConfigurationException extends Exception

{

private static final long serialVersionUID = -4667039447165906505L;

public DataGridConfigurationException(String msg) {

        super(msg);

    }



}

Note that the above code uses CDI to inject a Cache object with Qualifier MyCache so that it can be injected into the service like like this: 

@Inject

@MyCache

RemoteCache<Long, Task> cache;

See here for a complete template for connecting to JBoss Data Grid using Hot Rod from a JBoss EAP application