17.2. Performing Remote Queries via the Hot Rod Java Client

Remote querying over Hot Rod can be enabled once the RemoteCacheManager has been configured with the Protobuf marshaller.
The following procedure describes how to enable remote querying over its caches.
Prerequisites

RemoteCacheManager must be configured to use the Protobuf Marshaller.

Procedure 17.1. Enabling Remote Querying via Hot Rod

  1. Add the infinispan-remote.jar

    The infinispan-remote.jar is an uberjar, and therefore no other dependencies are required for this feature.
  2. Enable indexing on the cache configuration.

    Indexing is not mandatory for Remote Queries, but it is highly recommended because it makes searches on caches that contain large amounts of data significantly faster. Indexing can be configured at any time. Enabling and configuring indexing is the same as for Library mode.
    Add the following configuration within the cache-container element loated inside the Infinispan subsystem element.
    <!-- A basic example of an indexed local cache 
        that uses the RAM Lucene directory provider -->
    <local-cache name="an-indexed-cache" start="EAGER">                       
        <!-- Enable indexing using the RAM Lucene directory provider -->
        <indexing index="ALL">
            <property name="default.directory_provider">ram</property>
        </indexing>     
    </local-cache>
  3. Register the Protobuf schema definition files

    Register the Protobuf schema definition files by adding them in the ___protobuf_metadata system cache. The cache key is a string that denotes the file name and the value is .proto file, as a string. Alternatively, protobuf schemas can also be registered by invoking the registerProtofile methods of the server's ProtobufMetadataManager MBean. There is one instance of this MBean per cache container and is backed by the ___protobuf_metadata, so that the two approaches are equivalent.
    For an example of providing the protobuf schema via ___protobuf_metadata system cache, see Example 17.8, “Registering a Protocol Buffers schema file”.
    The following example demonstrates how to invoke the registerProtofile methods of the ProtobufMetadataManager MBean.

    Example 17.1. Registering Protobuf schema definition files via JMX

    import javax.management.MBeanServerConnection;
    import javax.management.ObjectName;
    import javax.management.remote.JMXConnector;
    import javax.management.remote.JMXServiceURL;
    
    ...
    
    String serverHost = ...         // The address of your JDG server
    int serverJmxPort = ...         // The JMX port of your server
    String cacheContainerName = ... // The name of your cache container
    String schemaFileName = ...     // The name of the schema file
    String schemaFileContents = ... // The Protobuf schema file contents
    
    JMXConnector jmxConnector = JMXConnectorFactory.connect(new JMXServiceURL(
        "service:jmx:remoting-jmx://" + serverHost + ":" + serverJmxPort));
    MBeanServerConnection jmxConnection = jmxConnector.getMBeanServerConnection();
    
    ObjectName protobufMetadataManagerObjName = 
        new ObjectName("jboss.infinispan:type=RemoteQuery,name=" + 
        ObjectName.quote(cacheContainerName) + 
        ",component=ProtobufMetadataManager");
    
    jmxConnection.invoke(protobufMetadataManagerObjName, 
                         "registerProtofile", 
                         new Object[]{schemaFileName, schemaFileContents}, 
                         new String[]{String.class.getName(), String.class.getName()});
    jmxConnector.close();
    
Result

All data placed in the cache is immediately searchable, whether or not indexing is in use. Entries do not need to be annotated, unlike embedded queries. The entity classes are only meaningful to the Java client and do not exist on the server.

Once remote querying has been enabled, the QueryFactory can be obtained using the following:

Example 17.2. Obtaining the QueryFactory

import org.infinispan.client.hotrod.Search;
import org.infinispan.query.dsl.QueryFactory;
import org.infinispan.query.dsl.Query;
import org.infinispan.query.dsl.SortOrder;
...
remoteCache.put(2, new User("John", 33));
remoteCache.put(3, new User("Alfred", 40));
remoteCache.put(4, new User("Jack", 56));
remoteCache.put(4, new User("Jerry", 20));

QueryFactory qf = Search.getQueryFactory(remoteCache);
Query query = qf.from(User.class)
    .orderBy("age", SortOrder.ASC) 
    .having("name").like("J%")
    .and().having("age").gte(33)
    .toBuilder().build();

List<User> list = query.list();
assertEquals(2, list.size());
assertEquals("John", list.get(0).getName());
assertEquals(33, list.get(0).getAge());
assertEquals("Jack", list.get(1).getName());
assertEquals(56, list.get(1).getAge());
Queries can now be run over Hot Rod similar to Library mode.