JBoss Data Grid (JDG) HotRod Data Sources

JDG caches running in client/server mode can use a Teiid specific JCA connector for accessing as a data source, which is deployed into WildFly 10.0.0 during installation. This connector can be configured to support the accessing of a remote JDG cache using the the Hot Rod client.

It is assumed that you will be installing the JDG Hotrod Client EAP Modules Kit, which can be obtained on the Red Hat’s Customer Portal at https://access.redhat.com/jbossnetwork/restricted/listSoftware.html.

There are many different ways to configure this resource-adapter based on different usage scenarios

  • using complex pojos (i.e, pojo contains other pojo’s).

  • using either pojo protobuf annotations or protobuf definition files, to configure the JDG schema

  • wanting the enable HotRod security, using username/password and/or SSL

  • utilizing the JDG cache for materialization

To handle different pojo types in the same cache, where each pojo object can be exposed as a separate table, it will require a different configured resource-adapter for each root pojo type.

Requirement

  • (option 1) Minimum, JDG 6.2 - this requires you provide a protobuf definition file and pojo marshaller(s) for the pojo to configure the JDG schema

  • (option 2) Minimum, JDG 6.6 - this can be used when the pojo has defined protobuf annotations which are used to configure the JDG schema.

See Infinispan HotRod Translator for details on how the the metadata will be exposed or can be manually configured based on the schema that’s defined for this data source.

Resource-Adapter Configuration

The following are the sections for configuring a resource-adapter to connect, configure schema, and access cache.

HotRod Remote Cache Connection

One of the following properties is required for defining how the RemoteCacheManager will be connected to.

Property Name Property Template Description

CacheJndiName

JNDI name to find the CacheContainer

RemoteServerList

host:port\[;host:port…​\]

Specify the host and ports that will be clustered together to access the caches

HotRodClientPropertiesFile

The HotRod properties file for configuring a connection to a remote cache

Configure Which Cache and Class

The following property is required as it provides the mapping to the JDG cache and pojo that will be accessed.

Property Name Property Template Description

CacheTypeMap

cacheName:className[:pkFieldName[:cacheKeyJavaType]]

Defines the cache name and pojo components for accessing the cache

Where
  • cacheName - Name of the cache to access

  • className - Class name of the pojo that is used to store the data in the cache

  • pkFieldName - [Optional] identifies the pojo class attribute that is used as the primary key. It is required for updates or if the pojo contains complex objects used in relationships (1-to-1 or 1-to-many). The pkFieldName MUST match a corresponding getter/setter method in the pojo

  • cacheKeyJavaType - [Optional] identify primary key java type when different than class attribute type

See Module Configuration for information on configuring the pojo jar.

Configure JDG Schema

There are 2 options for how the JDG schema can be configured

  • use protobuf definition file (.proto) and marshallers

  • use the pojo annotations

Regardless of which option that is chosen, there must also be a deployed pojo jar that contains the class(es).

Using Protobuf Definition and Marshaller(s)

The following properties are required when the protobuf definition file (.proto) and the pojo marshaller(s) are being used to configure the JDG schema.

Property Name Req. Property Template Description

ProtobufDefinitionFile

Y

Path to the Google Protobuf descriptor file that’s packaged in a jar (ex: /quickstart/addressbook.proto)

MessageMarshallers

Y

className:marshallerClassName \[,className:marshallerClassName,..\]

Contains Class name(s) mapped to its respective message marshaller(s) that is to be registered for serialization

MessageDescriptor

Y

Message descriptor package name in the protobuf descriptor file

Using Pojo Annotations

The pojo class is the object that is used to store the data in the cache. It should be built accordingly.

The following property must be configured to defined the relationship classes

Property Name Property Template Description

ChildClasses

className[,className,..]]

comma separated list of class names that indicate the child classes to register in the JDG schema

Module Configuration

The module configuration describes what’s required of the pojo jar that contains the class(es) used to access the data.

The following property must be defined in order to configure the pojo jar on the server.

Property Name Req. Description

module

Y

Specify the WildFly module that contains the cache classes that need to be loaded. This module must contain the className defined in the above section, see Configure Which Cache and Class

The following is an example of the module.xml that should be used when deploying the pojo.

Sample module.xml
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.0" name="com.client.quickstart.addressbook.pojos">
    <resources>
        <resource-root path="jdg-remote-cache-pojos.jar" />
    </resources>

    <dependencies>
        <module name="org.infinispan.client.hotrod" slot="jdg-7.0" optional="true" services="export"/>
   	<module name="org.infinispan.protostream" slot="jdg-7.0"  optional="true" services="export"/>
    </dependencies>
</module>

Using for External Materialization

The following are the additional properties that need to be configured if using the Remote Cache for external materialization.

Property Name Req. Description

StagingCacheName

Y

Cache name for the staging cache used in materialization

AliasCacheName

Y

Cache name for the alias cache used in tracking aliasing of the caches used in materialization. This cache can be shared with other configured materializations.

JDG Resource Adapter Security Options

Enable Hotrod Client SSL

To enable the Hotrod client in the resource-adapter to communicate using SSL, configure the following properties on the resource adapter.

Property Name Req. Description

TrustStoreFileName

Y

File name of the truststore

TrustStorePassword

Y

TrustStore Password

KeyStoreFileName

Y

File name of the keystore

KeyStorePassword

Y

KeyStore Password

SNIHostName

N

SNI Host Name

See the SSL Encrption guide for more details on the properties.

Enable using Hot Rod Authentication

This section describes how to configure the JDG resource-adapter to utilize the Hot Rod Client authentication.

The JDG server will need to have its hotrod-connector configured to enable accessing using authentication.

Example configured hotrod-connector
<hotrod-connector socket-binding="hotrod" cache-container="default">
   <authentication security-realm="ApplicationRealm">
      <sasl server-name="myhotrodserver" mechanisms="DIGEST-MD5" qop="auth" />
   </authentication>
</hotrod-connector>

Note the following

  • server-name attribute - it is the name that the server declares to incoming clients and therefore the client configuration must match the [AuthServerName] property.

  • security-realm - it should be the same one defined for [AuthApplicationRealm]

  • mechanisms - it should be the same one defined for [AuthSASLMechanism]

The following properties define how the JDG resource-adapter must be configured to talk to the JDG server based on its defined hotrod_connector.

Property Name Req. Description

AuthServerName

Y

The name declared as the server_name in the JDG Server

AuthApplicationRealm

Y

The security realm defined in the JDG server.

AuthSASLMechanism

Y

The SASL mechanisms (e.g., PLAN, DIGEST-MD5, etc.)

The Hot Rod protocol supports authentication leveraging different SASL mechanisms. The supported SASL mechanisms (usually shortened as mechs) are.

  • PLAIN - This is the most insecure mech, since credentials are sent over the wire in plain-text format, however it is the simplest to get to work. In combination with encryption (i.e. SSL) it can be used safely

  • DIGEST-MD5 - This mech hashes the credentials before sending them over the wire, so it is more secure than PLAIN

  • GSSAPI - This mech uses Kerberos tickets, and therefore requires the presence of a properly configured Kerberos Domain Controller (such as Microsoft Active Directory)

  • EXTERNAL - This mech obtains credentials from the underlying transport (i.e. from a X.509 client certificate) and therefore requires encryption using client-certificates to be enabled.

If using Hot Rod Authentication, then the following admin user will need to be defined so that metadata can be obtained without having to have a user execute a query. This user can be any JDG authorized user.

Property Name Req. Description

AdminUserName

Y

Username for administration operation

AdminPassword

Y

Password for administration operation

There are 2 options for passing the users credentials to JDG

  • username/password

  • Subject

When the username/password are not provided, the logic will be expecting to pull the Subject from the current context to use to as the credentials for the user.

To configure username/password, set the following properties

Property Name Req. Description

AuthUserName

N

authorized username

AuthPassword

N

authorized password

See the Hot Rod Authentication guide for more details on the properties.

Examples

There are many ways to create the data source, using CLI, AdminShell, admin-console etc.

1st Example

The 1st example is an xml snippet of a resource-adapter that is using probufs and marshallers to configure the JDG schema.

Sample Resource Adapter defining Protobuf Definition and Marshaller
batch

/subsystem=resource-adapters/resource-adapter=ispnHotrod:add(module=org.jboss.teiid.resource-adapter.infinispan.dsl)
/subsystem=resource-adapters/resource-adapter=ispnHotrod/connection-definitions=infinispanHotRodDS:add(jndi-name="java:/PersonJDGSource", class-name=org.teiid.resource.adapter.infinispan.dsl.InfinispanManagedConnectionFactory, enabled=true, use-java-context=true)
/subsystem=resource-adapters/resource-adapter=ispnHotrod/connection-definitions=infinispanHotRodDS/config-properties=CacheTypeMap:add(value="datasourceCache:com.client.quickstart.addressbook.pojos.domain.Person;id")
/subsystem=resource-adapters/resource-adapter=ispnHotrod/connection-definitions=infinispanHotRodDS/config-properties=Module:add(value="com.client.quickstart.addressbook.pojos")
/subsystem=resource-adapters/resource-adapter=ispnHotrod/connection-definitions=infinispanHotRodDS/config-properties=RemoteServerList:add(value="127.0.0.1:11322")

/subsystem=resource-adapters/resource-adapter=ispnHotrod/connection-definitions=infinispanHotRodDS/config-properties=ProtobufDefinitionFile:add(value="/quickstart/addressbook.proto")
/subsystem=resource-adapters/resource-adapter=ispnHotrod/connection-definitions=infinispanHotRodDS/config-properties=MessageDescriptor:add(value="quickstart.Person")
/subsystem=resource-adapters/resource-adapter=ispnHotrod/connection-definitions=infinispanHotRodDS/config-properties=MessageMarshallers:add(value=" com.client.quickstart.addressbook.pojos.domain.Person:com.client.quickstart.addressbook.pojos.marshallers.PersonMarshaller,com.client.quickstart.addressbook.pojos.domain.Address:com.client.quickstart.addressbook.pojos.marshallers.AddressMarshaller,com.client.quickstart.addressbook.pojos.domain.PhoneNumber:com.client.quickstart.addressbook.pojos.marshallers.PhoneNumberMarshaller")

/subsystem=resource-adapters/resource-adapter=ispnHotrod:activate

runbatch

2nd Example

The 2nd example showing a pojo example with annotations and the xml snippet of the resource-adapter.

Sample Pojo with Annotations
public class Person {

   @ProtoField(number = 2, required = true)
   public String name;
   @ProtoField(number = 1, required = true)
   public int id;
   @ProtoField(number = 3)
   public String email;
   private List<PhoneNumber> phones;

   public String getName() {
      return name;
   }

   public void setName(String name) {
      this.name = name;
   }

   public int getId() {
      return id;
   }

   public void setId(int id) {
      this.id = id;
   }

   public String getEmail() {
      return email;
   }

   public void setEmail(String email) {
      this.email = email;
   }

   public List<PhoneNumber> getPhones() {
      return phones;
   }

   public void setPhones(List<PhoneNumber> phones) {
      this.phones = phones;
   }
}
Sample Resource Adapter using Pojo with annotations
  batch

/subsystem=resource-adapters/resource-adapter=ispnHotrod:add(module=org.jboss.teiid.resource-adapter.infinispan.dsl)
/subsystem=resource-adapters/resource-adapter=ispnHotrod/connection-definitions=infinispanHotRodDS:add(jndi-name="java:/PersonJDGSource", class-name=org.teiid.resource.adapter.infinispan.dsl.InfinispanManagedConnectionFactory, enabled=true, use-java-context=true)
/subsystem=resource-adapters/resource-adapter=ispnHotrod/connection-definitions=infinispanHotRodDS/config-properties=CacheTypeMap:add(value="primaryCache:org.jboss.as.quickstarts.datagrid.hotrod.query.domain.Person;id")
/subsystem=resource-adapters/resource-adapter=ispnHotrod/connection-definitions=infinispanHotRodDS/config-properties=Module:add(value="com.client.quickstart.addressbook.pojos")
/subsystem=resource-adapters/resource-adapter=ispnHotrod/connection-definitions=infinispanHotRodDS/config-properties=RemoteServerList:add(value="127.0.0.1:11322")
/subsystem=resource-adapters/resource-adapter=ispnHotrod:activate

runbatch

3rd Example

The 3rd example is using the JDG data source for materialization.

Sample Resource Adapter for external materialization
 batch

/subsystem=resource-adapters/resource-adapter=ispnHotrod:add(module=org.jboss.teiid.resource-adapter.infinispan.dsl)
/subsystem=resource-adapters/resource-adapter=ispnHotrod/connection-definitions=infinispanHotRodDS:add(jndi-name="java:/PersonJDGSource", class-name=org.teiid.resource.adapter.infinispan.dsl.InfinispanManagedConnectionFactory, enabled=true, use-java-context=true)
/subsystem=resource-adapters/resource-adapter=ispnHotrod/connection-definitions=infinispanHotRodDS/config-properties=CacheTypeMap:add(value="primaryCache:org.jboss.as.quickstarts.datagrid.hotrod.query.domain.Person;id")
/subsystem=resource-adapters/resource-adapter=ispnHotrod/connection-definitions=infinispanHotRodDS/config-properties=Module:add(value="com.client.quickstart.addressbook.pojos")
/subsystem=resource-adapters/resource-adapter=ispnHotrod/connection-definitions=infinispanHotRodDS/config-properties=RemoteServerList:add(value="127.0.0.1:11322")
/subsystem=resource-adapters/resource-adapter=ispnHotrod/connection-definitions=infinispanHotRodDS/config-properties=StagingCacheName:add(value="stagingCache")
/subsystem=resource-adapters/resource-adapter=ispnHotrod/connection-definitions=infinispanHotRodDS/config-properties=AliasCacheName:add(value="aliasCache")
/subsystem=resource-adapters/resource-adapter=ispnHotrod:activate

runbatch

results matching ""

    No results matching ""