Language:
Format:

Red Hat Training

A Red Hat training course is available for Red Hat JBoss Data Virtualization

4.11. Resource Adapters

4.11.1. Resource Adapters in JBoss Data Virtualization

With the exception of JDBC data sources, JBoss Data Virtualization provides a JCA adapter for each supported data source. These are the resource adapter identifiers, as specified in the server configuration file:

File Adapter - file
Google Spreadsheet Adapter - google
Red Hat JBoss Data Grid (6.1 & 6.2) Adapter - infinispan
LDAP Adapter - ldap
Salesforce Adapter - salesforce
Web Services Adapter - webservice
Mongo DB Adapter (technical preview) - mongodb

Note

A resource adapter for the JDBC translator is provided with JBoss EAP by default.

4.11.2. Configuring Resource Adapters

You can use Management Console, AdminShell, or Management CLI (or, in standalone mode, directly edit the server configuration file) to configure resource adapters for data sources required by a VDB.

Note

Note that in domain mode, you must use Management CLI, Management Console or AdminShell to configure data sources. Refer to the JBoss Enterprise Application Platform Administration and Configuration Guide for an example of how to configure resource adapters using the Management Console.

Important

If you configure a resource adapter using either a CLI script or the AdminShell, the name of the resource adapter must not be the same as that of an existing one. (Teiid Designer handles this by creating a unique name for the resource adapter.)

The reasons for this are as follows:

Any time a resource adapter with a duplicate name is added, the server has to be restarted. This conforms with the way Red Hat JBoss EAP's JCA system was designed, in that multiple instances of resource adapters with the same name are only recognised when the server is launched.
Anytime you delete a resource adapter by name, all instances with the same name will be deleted.

4.11.3. Example Configuration

Example configuration, as it would appear in the server configuration file, can be found in the EAP_HOME/docs/teiid/datasources/ directory.

Note

This configuration will need to be adjusted with file paths and properties appropriate to your installation. The JNDI name must be the same JNDI name used in the VDB.

4.11.4. Resource Adapter Properties

For a full listing of configuration properties, you can run the following command from within the Management CLI:

/subsystem=teiid:read-rar-description(rar-name=ADAPTER_ID)

ADAPTER_ID refers to the identifier of the resource adapter as specified in the server configuration file.

4.11.5. Configuring Resource Adapters Using CLI Scripts

This is the preferred method for configuring resource adapters.

JBoss Data Virtualization provides an example Management CLI script for configuring each of the provided resource adapters. A script for a particular resource adapter can be found in the EAP_HOME/docs/teiid/datasources/DATASOURCE directory.

When configuring resource adapters using the Management CLI, you must provide a properties file. Sample properties files are provided in the same directory as the sample scripts.

You can run these scripts (once JBoss Data Virtualization is running) by executing the following command:

./EAP_HOME/bin/jboss-cli.sh --connect --file=EAP_HOME/docs/teiid/datasources/DATASOURCE/SCRIPT.cli --properties=EAP_HOME/docs/teiid/datasources/DATASOURCE/SCRIPT.properties

For more information about using the Management CLI, see the JBoss Enterprise Application Platform Administration and Configuration Guide.

Note

These scripts will need to be adjusted with file paths and properties appropriate to your installation. The JNDI name must be the same JNDI name used in the VDB.

4.11.6. File Adapter Properties

The following table describes the configuration properties that can be configured for the File resource adapter:

Config property	Example	Description
ParentDirectory		Directory where the data files are stored.
FileMapping	file1.txt=fileX.txt,file2.txt=fileY.txt	Set FileMapping to redirect specific relative paths (case sensitive) to alternative locations. The string value specifies a map in the format key=value(,key=value)*. Optional.
AllowParentPaths	true	Set AllowParentPaths to false to disallow '..' in paths. This prevents requesting files that are not contained in the parent directory. Optional.

4.11.7. Google Spreadsheet Resource Adapter Properties

4.11.7.1. Google Spreadsheet Resource Adapter Properties

The following table describes the configuration properties that can be configured for the Google Spreadsheet resource adapter:

Config property	Description
AuthMethod	This is the authentication method used to access Google. If the setting is `OAuth2` it is necessary to provide a `RefreshToken`.
RefreshToken	This is required only if `AuthMethod=OAuth2`
Username	Username for the Google account. Required only if `AuthMethod=ClientLogin`
Password	Password for the Google account. Required only if `AuthMethod=ClientLogin`
SpreadsheetName	The name of the spreadsheet to which this resource adapter is connecting. Required.
BatchSize	The maximum number of rows that can be fetched at a time. Default is 4096.

4.11.7.2. Obtaining an OAuth Refresh Token

When using the Google Spreadsheet resource adapter with OAuth authentication, you will need to obtain an OAuth refresh token.

Procedure 4.9. Obtaining an OAuth Refresh Token

Get an authorization code
Click on the following link: Get Authorization Code
Click on Allow access to allow the Teiid Google Connector to access the Google account in which the spreadsheet resides.

Obtain the refresh token

Copy the authorization code from the previous step into the code field of the following POST request and run it from the command line:

curl \--data-urlencode code=AUTH_CODE \
--data-urlencode client_id=217138521084.apps.googleusercontent.com \
--data-urlencode client_secret=gXQ6-lOkEjE1lVcz7giB4Poy \
--data-urlencode redirect_uri=urn:ietf:wg:oauth:2.0:oob \
--data-urlencode grant_type=authorization_code https://accounts.google.com/o/oauth2/token

The refresh token will be in the response.

4.11.8. JBoss Data Grid Resource Adapter Properties

The JBoss Data Grid (JDG) resource adapter can be configured to support the following caching modes:

Cache Type	Obtain Cache By
Remote Cache	using JNDI
Remote Cache	1 or more host:port combinations specified
Remote Cache	referring to HotRod client properties file specified

The following table describes the configuration properties that can be configured for the resource adapter:

Property Name	Required	Property Template	Description
CacheTypeMap	Y	cacheName:className[;pkFieldName] [,cacheName:className[;pkFieldName]..]	This property maps the root Java class name to the cache and identifies the primary key.
module	N		This property specifies the JBoss EAP module containing the cache classes defined in CacheTypeMap.
CacheJndiName	N		This is the JNDI name used to find the CacheContainer.
RemoteServerList	N	host:port[;host:portâ¦.]	This property specifies the host (and ports) that will be clustered together to access the caches defined in CacheTypeMap.
ConfigurationFileNameForLocalCache	N		This is the XML configuration file for configuring a local cache.
HotRodClientPropertiesFile	N		This is the HotRod properties file for configuring a connection to a remote cache.

Note

When you use Teiid Designer to reverse-engineer the view into a pojo, a BigDecimal data type is defined in the view. Unfortunately for the Google Protobuf used for serialization, complex data types cannot be converted to either C or C++. It is therefore recommended that you use primitive data types only. (You will come across this situation if you are trying to materialize a view that contains a complex data type or if there is an existing JDG cache that contains a POJO that has complex data types.)

As the protobuffer does not support BigDecimal directly, you have three options:

use all primitive data types
implement a marshaller that will handle the conversion, which means the .proto file will also need to be created (see Red Hat JBoss Data Grid for the creation of files)
create a view that will convert the BigdDecimal to a string, then materialize that view.

4.11.9. JDG HotRod Translator

The Infinispan HotRod Translator, known by the type ispn-hotrod, can read the java objects from a remote Red Hat JBoss Data Grid Cache via the Hot Rod client using the Google Protobuf for serialization. This will enable Red Hat JBoss Data Virtualization to query the remote cache using JDG DSL.

This translator retrieves objects from a cache and transform into rows and columns, allows you to perform writes to the cache and enables you to use external materialization to improve query performance.

The connector has these capabilities:

Compare Criteria - EQ
Compare Criteria Ordered - LT, GT, LE, GE - if the supportsCompareCriteriaOrdered translator override is set to true. It defaults to false.
And/Or Criteria
In Criteria
Like Criteria
Order By
INSERT, UPDATE, DELETE (non-transactional)

The following is not pushed down to JDG for processing, but is processed withing Red Hat JBoss Data Virtualization:

Not (NE)
IsNull

It currently has these limitations:

support for 'Not' has been disabled.
boolean data type: JDG will throw an exception if no value is specified on the insert or when no default value is defined in the protobuf definition file.
char data type: is not a supported type in theProtobuf data types (https://developers.google.com/protocol-buffers/docs/proto#scalar). You would either have to handle conversion in the protobuf marshaller or create a Red Hat JBoss Data Virtualization view with the data type as char.
1-to-Many, currently only supports Collection or Array, not Maps.
Write transactions are not supported by JDG when you are using the Hot Rod client

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

To take advantage of the cache's index being enabled, you should annotate the class. See JDG Indexing With Protobuf Annotations at https://access.redhat.com/documentation/en-US/Red_Hat_JBoss_Data_Grid/6.6/html-single/Infinispan_Query_Guide/index.html#Custom_Fields_Indexing_with_Protobuf
The class should be packaged into a jar so that it can be deployed as a module

Here is an example:

	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;
   }
}

To configure the use of the pojo, deploy the pojo jar as a module in the Red Hat JBoss EAP server and then define the "lib" property in the -vdb.xml and assign the correct module name. This can be done using the following template:

     <property name ="lib" value ="{pojo_module_name}"></property>

There are several options to defining the metadata representing your object in the cache:

"Recommended" Use the Teiid Connection Importer in Teiid Designer to create the physical source model based on your object cache.
Use Teiid Designer to manually create the physical source model based on your object cache using the below Definition Requirements.

A simple VDB that only defines the data source to use:

    <model name="People" type="Physical">
        <property name="importer.useFullSchemaName" value="false"/>

        <source name="infinispan-hotrod-connector" translator-name="ispn-hotrod" connection-jndi-name="java:/infinispanRemoteDSL" />
    </model>

The metadata will be resolved by reverse engineering the defined object in the cache. This can be useful when using the Teiid Designer Teiid Connection Importer for building the physical source model(s).

You can also define the metadata using DDL.

Note, this also shows a container class, PhoneNumber, as an example of the foreign key that’s defines the relationship.

<vdb name="PeopleVDB" version="1">
    <model name="People" visible="true">
        <property name="importer.useFullSchemaName" value="false"/>

        <source name="infinispan-cache-dsl-connector" translator-name="ispn-hotrod" connection-jndi-name="java:/infinispanRemote" />

        <metadata type="DDL"><![CDATA[

 CREATE FOREIGN TABLE Person (
	PersonObject object OPTIONS (NAMEINSOURCE 'this', UPDATABLE FALSE, SEARCHABLE 'Unsearchable', NATIVE_TYPE 'java.lang.Object'),
	id integer NOT NULL OPTIONS (SEARCHABLE 'Searchable', NATIVE_TYPE 'int'),
	name string OPTIONS (SEARCHABLE 'Searchable', NATIVE_TYPE 'java.lang.String'),
	email string OPTIONS (SEARCHABLE 'Searchable', NATIVE_TYPE 'java.lang.String'),
	CONSTRAINT PK_ID PRIMARY KEY(id)
) OPTIONS (NAMEINSOURCE 'PersonsCache', UPDATABLE TRUE);

CREATE FOREIGN TABLE PhoneNumber (
	number string OPTIONS (NAMEINSOURCE 'phone.number', SEARCHABLE 'Searchable', NATIVE_TYPE 'java.lang.String'),
	type string OPTIONS (NAMEINSOURCE 'phone.type', SEARCHABLE 'Searchable', NATIVE_TYPE 'java.lang.String'),
	id integer NOT NULL OPTIONS (SELECTABLE FALSE, UPDATABLE FALSE, SEARCHABLE 'Searchable', NATIVE_TYPE 'int'),
	CONSTRAINT FK_PERSON FOREIGN KEY(id) REFERENCES Person (id) OPTIONS (NAMEINSOURCE 'phones')
) OPTIONS (NAMEINSOURCE 'PersonsCache', UPDATABLE TRUE);

         ]> </metadata>
    </model>

</vdb>

Each Google-registered class in the cache will have a corresponding table created.
The table for the root class, must have a primary key defined, which must map to an attribute in the class.
The data type for the attribute in the class must match the JDG cache key data type.
The table "name in source" (NIS) will be the name of the JDG cache this table/class is stored
The table columns will be created from the google protobuf definition, that corresponds to a registered class.
Columns will be identified as SEARCHABLE if either the protobuf definition for a column indicates its indexed or the pojo class has the attribute/method annotated.
Attributes defined as repeatable (i.e., collections, arrays, etc.) or a container class, will be supported as 1-to-* relationships, and will have corresponding registered class (if they are to be searched).
A 1-to-* relationship class must have a foreign key to map to the root class/table, where the name in source for the foreign key is the name of the root class method to access those child objects. Note, this is the class method, not a reference in the google protobuf definition.
A container/child class will have attributes where the NIS contain a period. Example: phone.number. This is because this maps to to google protobuf definition and what is expected to be used in the DSL query.

This translator supports using the cache for external materialization. However, there are specific configuration changes that are required at the [Infinispan-HotRod resource-adapter] and at the translator.

External materialization is enabled by the use of native queries in the BEFORE_LOAD_SCRIPT and AFTER_LOAD_SCRIPT. A translator override will need to be set to enable native queries:

SupportsNativeQueries=true

You must define these properties:

Table 4.25. Configuration Properties

Script	Native Query	Description
teiid_rel:MATVIEW_BEFORE_LOAD_SCRIPT	truncate cache	Truncates the cache identified as the staging cache.
teiid_rel:MATVIEW_AFTER_LOAD_SCRIPT	swap cache names	Swaps the aliases for the caches, so that the primary cache points to the recently-loaded cache.

This example defines the load scripts in DDL:

..
"teiid_rel:MATVIEW_BEFORE_LOAD_SCRIPT" 'execute StockMatCache.native(''truncate cache'');',
"teiid_rel:MATVIEW_LOAD_SCRIPT" 'insert into StockMatCache.Stock (productId, symbol, price, companyName) SELECT  A.ID, S.symbol, S.price, A.COMPANY_NAME FROM Stocks.StockPrices AS S, Accounts.PRODUCT AS A WHERE S.symbol = A.SYMBOL',
"teiid_rel:MATVIEW_AFTER_LOAD_SCRIPT"  'execute StockMatCache.native(''swap cache names'');',

Native queries are used to simulate how the query is performed in the RDBMS and renaming tables, because JDG does not currently support renaming a cache. hence, the native queries will trigger the clearing of the "staging" cache, and the swapping of the cache aliases.

Additionally, the execution of native queries is done through the support of direct query procedures. The procedure to be executed is called native.

Warning

This feature is turned off by default because of its security risk. It coul allow someone to execute any command against the source. To enable this feature, set the Override Execution Property called SupportsDirectQueryProcedure to true.

See the Infinispan-HotRod resource adapter for this JCA Resource translator. It can be configured to look up the cache container via JNDI, server list, or Hot Rod properties.

4.11.10. LDAP Adapter Properties

The following table describes the configuration properties that can be configured for the LDAP resource adapter:

Config property	Property Template	Description
LdapUrl		LDAP Directory URL. This property is mandatory.
LdapAdminUserDN	cn=???,ou=???,dc=???	LDAP administration user DN. This property is mandatory.
LdapAdminUserPassword		LDAP administration password. This property is mandatory.
LdapTxnTimeoutInMillis		LDAP transaction timeout in milliseconds. -1 = no timeout. This property is optional.

4.11.11. Salesforce Adapter Properties

The following table describes the configuration properties that can be configured for the Salesforce resource adapter:

Config property	Description
URL	The URL to connect to.
username	The username.
password	The password.
requestTimeout	This is an optional property for setting timeouts, which can also be done through the CXF config.
connectTimeout	This is an optional property for setting timeouts, which can also be done through the CXF config.
configFile	Use this property to supply specific configuration for the SalesForce service. This configuration must contain config for "SforceService" service with namespace "urn:partner.soap.sforce.com".

4.11.12. Web Services Adapter Properties

The following table describes the configuration properties that can be configured for the Web Services resource adapter:

Config property	Example	Description
EndPoint		End point URL for the web service
SecurityType	HTTPBasic	Use for http basic security.
AuthUserName		Use for http basic security.
AuthPassword		Use for http basic security.
RequestTimeout		This is an optional property for setting timeouts, which can also be done through the CXF config.
ConnectTimeout		This is an optional property for setting timeouts, which can also be done through the CXF config.
ConfigFile		Use these properties to supply specific CXF configuration for this service. This file must contain a configuration for the name defined on the "EndPointName" property.
EndPointName	WebSVC	Use with ConfigFile. These properties to supply specific CXF configuration for this service.

4.11.13. MongoDB Adapter Properties

The following table describes the configuration properties that can be configured for the MongoDB resource adapter:

Config property	Example	Description
RemoteServerList	localhost:27017	MongoDB server list in this form host:port[;host:port...]*
Database		Database name.
Username		Use this property together with Password to supply credentials.
Password		Use this property together with Username to supply credentials.

Select Your Language

Red Hat Training

4.11. Resource Adapters

4.11.1. Resource Adapters in JBoss Data Virtualization

4.11.2. Configuring Resource Adapters

4.11.3. Example Configuration

4.11.4. Resource Adapter Properties

4.11.5. Configuring Resource Adapters Using CLI Scripts

4.11.6. File Adapter Properties

4.11.7. Google Spreadsheet Resource Adapter Properties

4.11.7.1. Google Spreadsheet Resource Adapter Properties

4.11.7.2. Obtaining an OAuth Refresh Token

4.11.8. JBoss Data Grid Resource Adapter Properties

4.11.9. JDG HotRod Translator

4.11.10. LDAP Adapter Properties

4.11.11. Salesforce Adapter Properties

4.11.12. Web Services Adapter Properties

4.11.13. MongoDB Adapter Properties

Quick Links

Help

Site Info

Related Sites

About

Red Hat legal and privacy links

Red Hat legal and privacy links

Language and Page Formatting Options

Red Hat Training

4.11. Resource Adapters

4.11.1. Resource Adapters in JBoss Data Virtualization

4.11.2. Configuring Resource Adapters

4.11.3. Example Configuration

4.11.4. Resource Adapter Properties

4.11.5. Configuring Resource Adapters Using CLI Scripts

4.11.6. File Adapter Properties

4.11.7. Google Spreadsheet Resource Adapter Properties

4.11.7.1. Google Spreadsheet Resource Adapter Properties

4.11.7.2. Obtaining an OAuth Refresh Token

4.11.8. JBoss Data Grid Resource Adapter Properties

4.11.9. JDG HotRod Translator

4.11.10. LDAP Adapter Properties

4.11.11. Salesforce Adapter Properties

4.11.12. Web Services Adapter Properties

4.11.13. MongoDB Adapter Properties

Quick Links

Help

Site Info

Related Sites

Systems Status

About

Red Hat legal and privacy links

Red Hat legal and privacy links