Red Hat Training

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

4.9. Data Source Deployment

4.9.1. Accumulo Data Sources

Accumulo data sources use a Data Virtualization-specific JCA connector that is deployed into JBoss EAP during installation. There are many ways to create a Accumulo data source, using CLI, AdminShell, admin-console, etc. The example shown below uses the CLI tool, as this works in both Standalone and Domain modes.
Execute the following command using the CLI once you connected to the Server. Ensure you provide the correct URL and user credentials. Add any additional properties required by the connector by duplicating the "connection-definitions" command below. Edit the JNDI name to match the JNDI name you used in VDB:
batch 
/subsystem=resource-adapters/resource-adapter=accumulo/connection-definitions=teiid:add(jndi-name=java:/accumulo-ds, class-name=org.teiid.resource.adapter.accumulo.AccumuloManagedConnectionFactory, enabled=true, use-java-context=true) 
/subsystem=resource-adapters/resource-adapter=accumulo/connection-definitions=teiid/config-properties=ZooKeeperServerList:add(value=localhost:2181) 
/subsystem=resource-adapters/resource-adapter=accumulo/connection-definitions=teiid/config-properties=Username:add(value=user) 
/subsystem=resource-adapters/resource-adapter=accumulo/connection-definitions=teiid/config-properties=Password:add(value=password) 
/subsystem=resource-adapters/resource-adapter=accumulo/connection-definitions=teiid/config-properties=InstanceName:add(value=instancename) 
/subsystem=resource-adapters/resource-adapter=accumulo/connection-definitions=teiid/config-properties=Roles:add(value=public) 
/subsystem=resource-adapters/resource-adapter=accumulo:activate 
runbatch 
These are the properties defined in the RAR file:

Table 4.1.  Properties

Property Description Required? Default?
ZooKeeperServerList
A comma-separated list of zoo keeper server locations. Each location can contain an optional port, of the format host:port
True.
None.
ZooKeeperServerList
A comma-separated list of zoo keeper server locations. Each location can contain an optional port, of the format host:port
True.
None.
Username
Connection User's Name
True.
None.
Password
Connection User's password
True.
None.
InstanceName
Accumulo instance name
True.
None.
Password
Connection User's password
True.
None.
Roles
optional visibility for user, supply multiple with comma separated
False.
None.
To find out all the properties that are supported by this Accumulo Connector execute this command in the CLI:
/subsystem=teiid:read-rar-description(rar-name=accumulo)

4.9.2. Amazon SimpleDB Data Sources

SimpleDB data sources use a Teiid specific JCA connector that is deployed into EAP during installation. There are many ways to create a SimpleDB data source, using CLI, AdminShell, admin-console, and so forth. The example shown below uses the CLI tool, as this works in both Standalone and Domain modes.
Execute the following command using the CLI once you connected to the Server. Make sure you provide the correct access keys. Add any additional properties required by the connector by duplicating the "connection-definitions" command below. Edit the JNDI name to match the JNDI name you used in the VDB.
batch 
/subsystem=resource-adapters/resource-adapter=simpledb/connection-definitions=simpledbDS:add(jndi-name=java:/simpledbDS, class-name=org.teiid.resource.adapter.simpledb.SimpleDBManagedConnectionFactory, enabled=true, use-java-context=true) 
/subsystem=resource-adapters/resource-adapter=simpledb/connection-definitions=simpledbDS/config-properties=AccessKey:add(value=xxx) 
/subsystem=resource-adapters/resource-adapter=simpledb/connection-definitions=simpledbDS/config-properties=SecretAccessKey:add(value=xxx) 
/subsystem=resource-adapters/resource-adapter=simpledb:activate 
runbatch 
To find out all the properties that are supported by this SimpleDB Connector execute the following command in the CLI:
/subsystem=teiid:read-rar-description(rar-name=simpledb)

4.9.3. Cassandra Data Sources

Cassandra's data sources use a Data Virtualization-specific JCA connector that is deployed on EAP during installation. There are many ways to create a Cassandra data source, using CLI, AdminShell, admin-console, etc. The example shown below uses the CLI tool, as this works in both Standalone and Domain modes.
Execute the following command using the CLI once you connected to the Server. Make sure you provide the correct URL and user credentials. Add any additional properties required by the connector by duplicating the "connection-definitions" command below. Edit the JNDI name to match the JNDI name you used in VDB:
 
batch 
/subsystem=resource-adapters/resource-adapter=cassandra/connection-definitions=cassandraDS:add(jndi-name=java:/cassandraDS, class-name=org.teiid.resource.adapter.cassandra.CassandraManagedConnectionFactory, enabled=true, use-java-context=true) 
/subsystem=resource-adapters/resource-adapter=cassandra/connection-definitions=cassandraDS/config-properties=Address:add(value=127.0.0.1) 
/subsystem=resource-adapters/resource-adapter=cassandra/connection-definitions=cassandraDS/config-properties=Keyspace:add(value=my-keyspace) 
/subsystem=resource-adapters/resource-adapter=cassandra:activate 
runbatch
To find out all the properties that are supported by this Cassandra Connector execute the following command in the CLI:
/subsystem=teiid:read-rar-description(rar-name=cassandra)

4.9.4. File Data Source

File data sources use a Teiid specific JCA connector that is deployed into EAP during installation. There are many ways to create the file data source, using CLI, AdminShell, admin-console, and so forth. The example shown below uses the CLI tool, as this works in both Standalone and Domain modes.
Execute following command using the CLI once you connected to the Server. Make sure you provide the correct directory name and other properties below. Add any additional properties required by the connector by duplicating the "connection-definitions" command below. Edit the JNDI name to match the JNDI name you used in the VDB:
batch 
/subsystem=resource-adapters/resource-adapter=file/connection-definitions=fileDS:add(jndi-name=java:/fileDS, class-name=org.teiid.resource.adapter.file.FileManagedConnectionFactory, enabled=true, use-java-context=true) 
/subsystem=resource-adapters/resource-adapter=file/connection-definitions=fileDS/config-properties=Parentdirectory:add(value=/home/rareddy/testing/) 
/subsystem=resource-adapters/resource-adapter=file/connection-definitions=fileDS/config-properties=AllowParentPaths:add(value=true) 
/subsystem=resource-adapters/resource-adapter=file:activate 
runbatch 
To find out all the properties that are supported by this File Connector execute the following command in the CLI:
/subsystem=teiid:read-rar-description(rar-name=file)

4.9.5. Google Spreadsheet Data Sources

You can authenticate your Google account in either of two ways: ClientLogin (which requires login and password) or OAuth (more complicated as it requires the user to supply a refresh token).
The Google JCA connector is named teiid-connector-google.rar. The examples include a sample google.xml file. The JCA connector has number of config-properties that facilitate authentication. The JCA connector connects to one spreadsheet:

Table 4.2. Configuration Properties

Property Description
AuthMethod
Method to access Google. This property can be set to OAuth2. If you do so, it is necessary to provide RefreshToken.
SpreadsheetName
Required property with name of the Spreadsheet that is datasource for this connector.
BatchSize
Maximum number of rows that can be fetched at a time. Defaults to 4096.
To obtain an OAuth Refresh Token, go to Google's authentication site:
https://accounts.google.com/o/oauth2/auth?scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive+https%3A%2F%2Fspreadsheets.google.com%2Ffeeds&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code&client_id=217138521084.apps.googleusercontent.com
Next, copy the authorization code into the following POST request and run it on command line. (The refresh token will be in the response.)
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	

4.9.6. Infinispan Data Sources

Infinispan data sources use a Teiid specific JCA connector that is deployed into EAP during installation. This connector can be configured to support the following modes of Infinispan caches:

Table 4.3. Registry Properties

Cache Type How to Obtain This Cache
Local Cache
JNDI
Local Cache
Configuration file
Remote Cache
JNDI
Remote Cache
Specify one or more host ports.
Local Cache
Specify one or more Hot Rod client property files.
You can configure these properties for this connector:

Table 4.4. Registry Properties

Property Name Required Property Template Description
CacheTypeMap
Yes
cacheName:className[;pkFieldName] [,cacheName:className[;pkFieldName]..]
Map the root Java Object class name to the cache, and identify which attribute is the primary key to the cache.
module
No
Nil
Specify the JBoss AS module that contains the cache classes that were defined in CacheTypeMap
CacheJndiName
No
Nil
JNDI name to fine the CacheContainer
RemoteServerList
No
host:port[;host:port….]
Specify the host and ports that will be clustered together to access the caches defined in CacheTypeMap
ConfigurationFileNameForLocalCache
No
Nil
The Infinispan Configuration xml file for configuring a local cache.
HotRodClientPropertiesFile
No
Nil
The HotRod properties file for configuring a connection to a remote cache
There are many ways to create the data source, using CLI, AdminShell, admin-console and so forth. The example shown below uses the CLI tool, as this works in both Standalone and Domain modes:
Execute following command using CLI once you connected to the Server. Make sure you provide the correct directory name and other properties below. Add any additional properties required by the connector by duplicating the "connection-definitions" command below. Edit the JNDI name to match the JNDI name you used in the VDB:
batch 
/subsystem=resource-adapters/resource-adapter=infinispan/connection-definitions=infinispanDS:add(jndi-name=java:/infinispanDS, class-name=org.teiid.resource.adapter.infinispan.InfinispanManagedConnectionFactory, enabled=true, use-java-context=true) 
/subsystem=resource-adapters/resource-adapter=infinispan/connection-definitions=infinispanDS/config-properties=CacheTypeMap:add(value=trades:org.somewhere.Trade;tradeId) 
/subsystem=resource-adapters/resource-adapter=infinispan/connection-definitions=infinispanDS/config-properties=Module:add(value=org.somewhere) 
/subsystem=resource-adapters/resource-adapter=infinispan/connection-definitions=infinispanDS/config-properties=CacheJndiName:add(value=java:/myCache)
runbatch 
To find out all the properties that are supported by this Infinispan Connector execute the following command in the CLI:
/subsystem=teiid:read-rar-description(rar-name=infinispan)

Important

Avoid Classloading Issues: If you are using a servlet or other type of web application to create the DefaultCacheManager for the cache, be sure not to include the Infinispan jar dependencies in the application, but add their module dependencies instead.

4.9.7. Infinispan-DSL Data Sources

You must install the Red Hat JBoss Data Grid modules in order to use this resource adapter. Note that this translator uses different JBoss Data Grid modules for remote and local modes. Please refer to the JBoss Data Grid documentation at https://access.redhat.com/documentation/en-US/Red_Hat_JBoss_Data_Grid/6.4/html/Infinispan_Query_Guide/chap-The_Infinispan_Query_DSL.html for more information about this. This JBoss Data Grid guide contains some basic information on using the Infinispan Query DSL. The jar required for library mode is infinispan-embedded-query, and in remote client-server mode the .jar is infinispan-query, which is installed by default with jboss-datagrid-server.
Infinispan-DSL data sources use a Teiid-specific JCA connector that is deployed into EAP during installation. This connector can be configured to support the following modes of Infinispan caches that will be accessed using the Hot Rod client:

Table 4.5. Properties

Cache Type Property Name How to Obtain Cache
Remote Cache
CacheJndiName
JNDI
Remote Cache
RemoteServerList
Server list: specify one or more host ports
Remote Cache
HotRodClientPropertiesFile
HotRod client properties file
This requires, at a minimum, JDG 6.3 or better, that is configured to use Google Protobuf for object serialization. This will enable Teiid to query the cache as if it was a local cache configured with Lucene indexes.
You can configure the following properties for this connector:

Table 4.6. Properties

Property Required? Property Template Description
CacheTypeMap
Yes
cacheName:className[;pkFieldName] [,cacheName:className[;pkFieldName]..]
Map the root Java Object class name to the cache, and identify which attribute is the primary key to the cache.
ProtobinFile
Yes
Nil
Path to the Google Protobin file that's packaged in a jar (such as /quickstart/addressbook.protobin)
MessageMarshallers
Yes
marshaller [,marshaller,..]
Contains Class names mapped its respective message marshaller, (class:marshaller,[class:marshaller,..]), that are to be registered for serialization
MessageDescriptor
Yes
Nil
Message descriptor class name for the root object in cache
module
No
Nil
Specify the JBoss EAP module that contains the cache classes that need to be loaded.
CacheJndiName
No
Nil
JNDI name to find the CacheContainer
RemoteServerList
No
host:port[;host:port….]
Specify the host and ports that will be clustered together to access the caches.
HotRodClientPropertiesFile
No
Nil
The HotRod properties file for configuring a connection to a remote cache
Here is the XML code for a resource-adapter that is used to connect to the JDG remote-query quick start:
<resource-adapter id="infinispanRemQS">
     <module slot="main" id="org.jboss.teiid.resource-adapter.infinispan.dsl"/>
     <connection-definitions>
         <connection-definition class-name="org.teiid.resource.adapter.infinispan.dsl.InfinispanManagedConnectionFactory" jndi-name="java:/infinispanRemote" enabled="true" use-java-context="true" pool-name="infinispanDS">
             <config-property name="CacheTypeMap">
                 addressbook:org.jboss.as.quickstarts.datagrid.hotrod.query.domain.Person;id
             </config-property>
             <config-property name="ProtobinFile">
                  /quickstart/addressbook.protobin
             </config-property>
             <config-property name="MessageDescriptor">
                 quickstart.Person
             </config-property>
             <config-property name="Module">
                 com.client.quickstart.pojos
             </config-property>
             <config-property name="MessageMarshallers">                              org.jboss.as.quickstarts.datagrid.hotrod.query.domain.Person:org.jboss.as.quickstarts.datagrid.hotrod.query.marshallers.PersonMarshaller,org.jboss.as.quickstarts.datagrid.hotrod.query.domain.PhoneNumber:org.jboss.as.quickstarts.datagrid.hotrod.query.marshallers.PhoneNumberMarshaller,org.jboss.as.quickstarts.datagrid.hotrod.query.domain.PhoneType:org.jboss.as.quickstarts.datagrid.hotrod.query.marshallers.PhoneTypeMarshaller
             </config-property>
             <config-property name="RemoteServerList">
                 127.0.0.1:11322
             </config-property>
         </connection-definition>
     </connection-definitions>
 </resource-adapter>

4.9.8. JDG HotRod Data Sources

Red Hat JBoss Data Grid HotRod data sources uses a Red Hat JBoss Data Virtualization-specific JCA connector that is deployed upon installation. You can configure this to support the following cache types using the Hot Rod client:

Table 4.7. Cache Types

Remote Cache Remote Cache Obtain Cache By
Remote Cache CacheJndiName using JNDI
Remote Cache RemoteServerList Server list, specify 1 or more host:port’s
Remote Cache HotRodClientPropertiesFile HotRod client properties file
  • (option 1) Minimum, JDG 6.2 - this requires you provide a protobuf definition file and pojo marsharller for the pojo to be cached
  • (option 2) Minimum, JDG 6.6 - this can be used when the pojo has protobuf annotations which trigger the creation of the protobuf definition and pojo marshaller by JDG.
The pojo class is the object that will be used to store the data in the cache. It should be built in order to do the following:
  • To take advantage of the cache being indexed enabled, should annotate the class. See JDG 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.
To configure this pojo, deploy the pojo jar as a module in the Red Hat JBoss EAP server. Then define the "lib" property in the -vdb.xml and assign the correct module name. You can do so using this template:
<property name ="lib" value ="{pojo_module_name}"></property>
These are required for reading and writing to and from the cache:

Table 4.8. Required Properties

Property Name Property Template Description
CacheTypeMap cacheName:className[;pkFieldName[:cacheKeyJavaType]] For the indicated cache, map the root Java Object class name. Optionally, but required for updates, identify which class attribute is the primary key to the cache. Identify primary key java type when different than class attribute type.
Set these properties to define how the RemoteCacheManager will be created/accessed:

Table 4.9. Configuration Properties

Property Name Required? Property Template Description
CacheJndiName No NA This is the JNDI name to find the CacheContainer.
RemoteServerList No host:port\[;host:port….\] Specify the host and ports that will be clustered together to access the caches.
HotRodClientPropertiesFile No NA The HotRod properties file for configuring a connection to a remote cache.
The following properties are required when the pojo is not annotated:

Table 4.10. Configuration Properties

Property Name Required? Property Template Description
ProtobinFile Yes NA Path to the Google Protobin file that’s packaged in a jar (ex: /quickstart/addressbook.protobin)
MessageMarshallers Yes marshaller \[,marshaller,..\] Contains Class names mapped its respective message marshaller, (class:marshaller,\[class:marshaller,..\]), that are to be registered for serialization.
MessageDescriptor Yes Message descriptor class name for the root object in cache. The HotRod properties file for configuring a connection to a remote cache.
These are the additional properties that need to be configured if you are using the Remote Cache for external materialization:

Table 4.11. Configuration Properties

Property Name Required? Description
StagingCacheName Yes Cache name for the staging cache used in materialization
AliasCacheName Yes Cache name for the alias cache used in tracking aliasing of the caches used in materialization
There are many ways to create the data source, including using CLI, AdminShell, admin-console and so forth. The first example shows a resource-adapter's XML code. This code is used to connect to the JDG remote-query quick start:me:
	<resource-adapter id="infinispanRemQS">
                    <module slot="main" id="org.jboss.teiid.resource-adapter.infinispan.hotrod"/>
                    <connection-definitions>
                        <connection-definition class-name="org.teiid.resource.adapter.infinispan.hotrod.InfinispanManagedConnectionFactory" jndi-name="java:/infinispanRemote" enabled="true" use-java-context="true" pool-name="infinispanDS">
                            <config-property name="CacheTypeMap">
                                addressbook:org.jboss.as.quickstarts.datagrid.hotrod.query.domain.Person;id
                            </config-property>
                            <config-property name="ProtobinFile">
                                 /quickstart/addressbook.protobin
                            </config-property>
                            <config-property name="MessageDescriptor">
                                quickstart.Person
                            </config-property>
                            <config-property name="Module">
                                com.client.quickstart.pojos
                            </config-property>
                            <config-property name="MessageMarshallers">                              org.jboss.as.quickstarts.datagrid.hotrod.query.domain.Person:org.jboss.as.quickstarts.datagrid.hotrod.query.marshallers.PersonMarshaller,org.jboss.as.quickstarts.datagrid.hotrod.query.domain.PhoneNumber:org.jboss.as.quickstarts.datagrid.hotrod.query.marshallers.PhoneNumberMarshaller,org.jboss.as.quickstarts.datagrid.hotrod.query.domain.PhoneType:org.jboss.as.quickstarts.datagrid.hotrod.query.marshallers.PhoneTypeMarshaller
                            </config-property>
                            <config-property name="RemoteServerList">
                                127.0.0.1:11322
                            </config-property>
                        </connection-definition>
                    </connection-definitions>
                </resource-adapter>
	
This example show you how to configure it for external materialization:
                <resource-adapter id="infinispanRemQSDSL">
                    <module slot="main" id="org.jboss.teiid.resource-adapter.infinispan.hotrod"/>
                    <connection-definitions>
                        <connection-definition class-name="org.teiid.resource.adapter.infinispan.hotrod.InfinispanManagedConnectionFactory" jndi-name="java:/infinispanRemoteDSL" enabled="true" use-java-context="true" pool-name="infinispanRemoteDSL">
                            <config-property name="CacheTypeMap">
                                addressbook_indexed:org.jboss.as.quickstarts.datagrid.hotrod.query.domain.Person;id
                            </config-property>
                            <config-property name="StagingCacheName">
                                addressbook_indexed_mat
                            </config-property>
                            <config-property name="AliasCacheName">
                                aliasCache
                            </config-property>
                            <config-property name="Module">
                                com.client.quickstart.addressbook.pojos
                            </config-property>
                            <config-property name="RemoteServerList">
                                127.0.0.1:11322
                            </config-property>
                        </connection-definition>
                    </connection-definitions>
                </resource-adapter>
	

4.9.9. JDBC Data Sources

4.9.9.1. JDBC Data Sources

Here is an example highlighting configuring an Oracle data source. The process is nearly identical regardless of the database vendor. Typically the JDBC jar and the configuration like connection URL and user credentials change.
There are configuration templates for all the data sources in the jboss-install/docs/teiid/datasources directory. A complete description how a data source can be added into JBoss EAP is also described here. Here are two different ways to create a datasource:
Firstly, deploy the required JDBC jar file. For example, if you are trying to create a Oracle data source, first you need to deploy the "ojdbc6.jar" file: deploy /path/to/ojdbc6.jar

Note

If JBoss EAPis running in standalone mode, you can also manually copy this 'ojdbc6.jar" to the jboss-install>/standalone/deployments directory, to automatically deploy without using the CLI tool.
Now create a data source using this driver. There are many ways to create the datasource using CLI, AdminShell or admin-console. The example shown below uses the CLI tool, as this works in both Standalone and Domain modes.
Execute the following command using the CLI once you connected to the Server. Make sure you provide the correct URL and user credentials and edit the JNDI name to match the JNDI name you used in the VDB:
/subsystem=datasources/data-source=oracel-ds:add(jndi-name=java:/OracleDS, driver-name=ojdbc6.jar, connection-url=jdbc:oracle:thin:{host}:1521:orcl,user-name={user}, password={password}) 
/subsystem=datasources/data-source=oracel-ds:enable

4.9.9.2. Configuring JDBC Data Sources

For JBoss Data Virtualization to connect to JDBC data sources, you must configure the data source in the JBoss EAP instance with the following two steps:
  1. Install (or deploy) the JDBC JAR driver file.
  2. Create (or configure) it as a data source in JBoss EAP.

Note

See the Red Hat JBoss Enterprise Application Platform Administration and Configuration Guide for more comprehensive information about configuring data sources.

4.9.9.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.9.9.4. Install a JDBC Driver with the Management CLI

Procedure 4.5. Install a JDBC Driver with the Management CLI

  1. Start the Management CLI: ./EAP_HOME/bin/jboss-cli.sh
  2. Enter the connect command.
  3. Enter the deploy PATH/FILE.jar command: deploy ojdbc6.jar
  4. Enter the quit command.

4.9.9.5. Install a JDBC Driver with the Management Console

Summary

Before your application can connect to a JDBC datasource, your datasource vendor's JDBC drivers need to be installed in a location where JBoss EAP 6 can use them. JBoss EAP 6 allows you to deploy these drivers like any other deployment. This means that you can deploy them across multiple servers in a server group, if you use a managed domain.

Prerequisites

Before performing this task, you need to meet the following prerequisites:

  • Download the JDBC driver from your database vendor.

Note

Any JDBC 4-compliant driver is automatically recognized and installed in the system by name and version. A JDBC JAR is identified using the Java service provider mechanism. Such JARs contain the META-INF/services/java.sql.Driver text, which contains the name of the Driver classes in that JAR.

Procedure 4.6. Modify the JDBC Driver JAR

If the JDBC driver JAR is not JDBC 4-compliant, it can be made deployable using the following method.
  1. Change to, or create, an empty temporary directory.
  2. Create a META-INF subdirectory.
  3. Create a META-INF/services subdirectory.
  4. Create a META-INF/services/java.sql.Driver file, which contains one line indicating the fully-qualified class name of the JDBC driver.
  5. Use the JAR command-line tool to update the JAR like this:
    jar \-uf jdbc-driver.jar META-INF/services/java.sql.Driver
  6. If you use a managed domain, deploy the JAR file to a server group. Otherwise, deploy it to your server. See the Deploy with the Management Console section of the Administration and Configuration Guide for JBoss EAP 6 for more information.
Result:

The JDBC driver is deployed, and is available for your applications to use.

4.9.9.6. Create a Non-XA Datasource with the Management Interfaces

Summary

This topic covers the steps required to create a non-XA datasource, using either the Management Console or the Management CLI.

Prerequisites

  • The JBoss EAP 6 server must be running.

Note

Prior to version 10.2 of the Oracle datasource, the <no-tx-separate-pools/> parameter was required, as mixing non-transactional and transactional connections would result in an error. This parameter may no longer be required for certain applications.

Note

To prevent issues such as duplication of driver listing, selected driver not available in a profile, or driver not displayed if a server for the profile is not running, in JBoss EAP 6.4 onwards, only JDBC drivers that are installed as modules and correctly referenced from profiles are detectable while creating a datasource using the Management Console in domain mode.

Procedure 4.7. Create a Datasource using either the Management CLI or the Management Console

    • Management CLI

      1. Launch the CLI tool and connect to your server.
      2. Run the following Management CLI command to create a non-XA datasource, configuring the variables as appropriate:

        Note

        The value for DRIVER_NAME depends on the number of classes listed in the /META-INF/services/java.sql.Driver file located in the JDBC driver JAR. If there is only one class, the value is the name of the JAR. If there are multiple classes, the value is the name of the JAR + driverClassName + "_" + majorVersion +"_" + minorVersion. Failure to do so will result in the following error being logged:
        JBAS014775:    New missing/unsatisfied dependencies
        For example, the DRIVER_NAME value required for the MySQL 5.1.31 driver, is mysql-connector-java-5.1.31-bin.jarcom.mysql.jdbc.Driver_5_1.
        data-source add --name=DATASOURCE_NAME --jndi-name=JNDI_NAME --driver-name=DRIVER_NAME  --connection-url=CONNECTION_URL
      3. Enable the datasource:
        data-source enable --name=DATASOURCE_NAME
    • Management Console

      1. Login to the Management Console.
      2. Navigate to the Datasources panel in the Management Console

        1. Select the Configuration tab from the top of the console.
        2. For Domain mode only, select a profile from the drop-down box in the top left.
        3. Expand the Subsystems menu on the left of the console, then expand the Connector menu.
        4. Select Datasources from the menu on the left of the console.
      3. Create a new datasource

        1. Click Add at the top of the Datasources panel.
        2. Enter the new datasource attributes in the Create Datasource wizard and proceed with the Next button.
        3. Enter the JDBC driver details in the Create Datasource wizard and click Next to continue.
        4. Enter the connection settings in the Create Datasource wizard.
        5. Click the Test Connection button to test the connection to the datasource and verify the settings are correct.
        6. Click Done to finish
Result

The non-XA datasource has been added to the server. It is now visible in either the standalone.xml or domain.xml file, as well as the management interfaces.

4.9.9.7. Create an XA Datasource with the Management Interfaces

Summary

This topic covers the steps required to create an XA datasource, using either the Management Console or the Management CLI.

Note

Prior to version 10.2 of the Oracle datasource, the <no-tx-separate-pools/> parameter was required, as mixing non-transactional and transactional connections would result in an error. This parameter may no longer be required for certain applications.

Procedure 4.8. Create an XA Datasource, Using Either the Management CLI or the Management Console

    • Management CLI

      1. Run the following Management CLI command to create an XA datasource, configuring the variables as appropriate:

        Note

        The value for DRIVER_NAME depends on the number of classes listed in the /META-INF/services/java.sql.Driver file located in the JDBC driver JAR. If there is only one class, the value is the name of the JAR. If there are multiple classes, the value is the name of the JAR + driverClassName + "_" + majorVersion +"_" + minorVersion. Failure to do so will result in the following error being logged:
        JBAS014775:    New missing/unsatisfied dependencies
        For example, the DRIVER_NAME value required for the MySQL 5.1.31 driver, is mysql-connector-java-5.1.31-bin.jarcom.mysql.jdbc.Driver_5_1.
        xa-data-source add --name=XA_DATASOURCE_NAME --jndi-name=JNDI_NAME --driver-name=DRIVER_NAME --xa-datasource-class=XA_DATASOURCE_CLASS
      2. Configure the XA datasource properties

        1. Set the server name

          Run the following command to configure the server name for the host:
          /subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME/xa-datasource-properties=ServerName:add(value=HOSTNAME)
        2. Set the database name

          Run the following command to configure the database name:
          /subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME/xa-datasource-properties=DatabaseName:add(value=DATABASE_NAME)
      3. Enable the datasource:
        xa-data-source enable --name=XA_DATASOURCE_NAME
    • Management Console

      1. Navigate to the Datasources panel in the Management Console

        1. Select the Configuration tab from the top of the console.
        2. For Domain mode only, select a profile from the drop-down box at the top left.
        3. Expand the Subsystems menu on the left of the console, then expand the Connector menu.
        4. Select Datasources.
      2. Select the XA Datasource tab.
      3. Create a new XA datasource

        1. Click Add.
        2. Enter the new XA datasource attributes in the Create XA Datasource wizard and click Next.
        3. Enter the JDBC driver details in the Create XA Datasource wizard and click Next.
        4. Enter the XA properties and click Next.
        5. Enter the connection settings in the Create XA Datasource wizard.
        6. Click the Test Connection button to test the connection to the XA datasource and verify the settings are correct.
        7. Click Done to finish
Result

The XA datasource has been added to the server. It is now visible in either the standalone.xml or domain.xml file, as well as the management interfaces.

4.9.9.8. Datasource Parameters

Table 4.12. Datasource parameters common to non-XA and XA datasources

Parameter Description
jndi-name The unique JNDI name for the datasource.
pool-name The name of the management pool for the datasource.
enabled Whether or not the datasource is enabled.
use-java-context
Whether to bind the datasource to global JNDI.
spy
Enable spy functionality on the JDBC layer. This logs all JDBC traffic to the datasource. Note that the logging category jboss.jdbc.spy must also be set to the log level DEBUG in the logging subsystem.
use-ccm Enable the cached connection manager.
new-connection-sql A SQL statement which executes when the connection is added to the connection pool.
transaction-isolation
One of the following:
  • TRANSACTION_READ_UNCOMMITTED
  • TRANSACTION_READ_COMMITTED
  • TRANSACTION_REPEATABLE_READ
  • TRANSACTION_SERIALIZABLE
  • TRANSACTION_NONE
url-selector-strategy-class-name A class that implements interface org.jboss.jca.adapters.jdbc.URLSelectorStrategy.
security
Contains child elements which are security settings. See Table 4.17, “Security parameters”.
validation
Contains child elements which are validation settings. See Table 4.18, “Validation parameters”.
timeout
Contains child elements which are timeout settings. See Table 4.19, “Timeout parameters”.
statement
Contains child elements which are statement settings. See Table 4.20, “Statement parameters”.

Table 4.13. Non-XA datasource parameters

Parameter Description
jta Enable JTA integration for non-XA datasources. Does not apply to XA datasources.
connection-url The JDBC driver connection URL.
driver-class The fully-qualified name of the JDBC driver class.
connection-property
Arbitrary connection properties passed to the method Driver.connect(url,props). Each connection-property specifies a string name/value pair. The property name comes from the name, and the value comes from the element content.
pool
Contains child elements which are pooling settings. See Table 4.15, “Pool parameters common to non-XA and XA datasources”.
url-delimiter
The delimiter for URLs in a connection-url for High Availability (HA) clustered databases.

Table 4.14. XA datasource parameters

Parameter Description
xa-datasource-property
A property to assign to implementation class XADataSource. Specified by name=value. If a setter method exists, in the format setName, the property is set by calling a setter method in the format of setName(value).
xa-datasource-class
The fully-qualified name of the implementation class javax.sql.XADataSource.
driver
A unique reference to the class loader module which contains the JDBC driver. The accepted format is driverName#majorVersion.minorVersion.
xa-pool
recovery
Contains child elements which are recovery settings. See Table 4.21, “Recovery parameters”.

Table 4.15. Pool parameters common to non-XA and XA datasources

Parameter Description
min-pool-size The minimum number of connections a pool holds.
max-pool-size The maximum number of connections a pool can hold.
prefill Whether to try to prefill the connection pool. An empty element denotes a true value. The default is false.
use-strict-min Whether the idle connection scan should strictly stop marking for closure of any further connections, once the min-pool-size has been reached. The default value is false.
flush-strategy
Whether the pool is flushed in the case of an error. Valid values are:
  • FailingConnectionOnly
  • IdleConnections
  • EntirePool
The default is FailingConnectionOnly.
allow-multiple-users Specifies if multiple users will access the datasource through the getConnection(user, password) method, and whether the internal pool type accounts for this behavior.

Table 4.16. XA pool parameters

Parameter Description
is-same-rm-override Whether the javax.transaction.xa.XAResource.isSameRM(XAResource) class returns true or false.
interleaving Whether to enable interleaving for XA connection factories.
no-tx-separate-pools
Whether to create separate sub-pools for each context. This is required for Oracle datasources, which do not allow XA connections to be used both inside and outside of a JTA transaction.
Using this option will cause your total pool size to be twice max-pool-size, because two actual pools will be created.
pad-xid Whether to pad the Xid.
wrap-xa-resource
Whether to wrap the XAResource in an org.jboss.tm.XAResourceWrapper instance.

Table 4.17. Security parameters

Parameter Description
user-name The username to use to create a new connection.
password The password to use to create a new connection.
security-domain Contains the name of a JAAS security-manager which handles authentication. This name correlates to the application-policy/name attribute of the JAAS login configuration.
reauth-plugin Defines a reauthentication plug-in to use to reauthenticate physical connections.

Table 4.18. Validation parameters

Parameter Description
valid-connection-checker
An implementation of interface org.jboss.jca.adaptors.jdbc.ValidConnectionChecker which provides a SQLException.isValidConnection(Connection e) method to validate a connection. An exception means the connection is destroyed. This overrides the parameter check-valid-connection-sql if it is present.
check-valid-connection-sql An SQL statement to check validity of a pool connection. This may be called when a managed connection is taken from a pool for use.
validate-on-match
Indicates whether connection level validation is performed when a connection factory attempts to match a managed connection for a given set.
Specifying "true" for validate-on-match is typically not done in conjunction with specifying "true" for background-validation. Validate-on-match is needed when a client must have a connection validated prior to use. This parameter is false by default.
background-validation
Specifies that connections are validated on a background thread. Background validation is a performance optimization when not used with validate-on-match. If validate-on-match is true, using background-validation could result in redundant checks. Background validation does leave open the opportunity for a bad connection to be given to the client for use (a connection goes bad between the time of the validation scan and prior to being handed to the client), so the client application must account for this possibility.
background-validation-millis The amount of time, in milliseconds, that background validation runs.
use-fast-fail
If true, fail a connection allocation on the first attempt, if the connection is invalid. Defaults to false.
stale-connection-checker
An instance of org.jboss.jca.adapters.jdbc.StaleConnectionChecker which provides a Boolean isStaleConnection(SQLException e) method. If this method returns true, the exception is wrapped in an org.jboss.jca.adapters.jdbc.StaleConnectionException, which is a subclass of SQLException.
exception-sorter
An instance of org.jboss.jca.adapters.jdbc.ExceptionSorter which provides a Boolean isExceptionFatal(SQLException e) method. This method validates whether an exception is broadcast to all instances of javax.resource.spi.ConnectionEventListener as a connectionErrorOccurred message.

Table 4.19. Timeout parameters

Parameter Description
use-try-lock Uses tryLock() instead of lock(). This attempts to obtain the lock for the configured number of seconds, before timing out, rather than failing immediately if the lock is unavailable. Defaults to 60 seconds. As an example, to set a timeout of 5 minutes, set <use-try-lock>300</use-try-lock>.
blocking-timeout-millis The maximum time, in milliseconds, to block while waiting for a connection. After this time is exceeded, an exception is thrown. This blocks only while waiting for a permit for a connection, and does not throw an exception if creating a new connection takes a long time. Defaults to 30000, which is 30 seconds.
idle-timeout-minutes
The maximum time, in minutes, before an idle connection is closed. The actual maximum time depends upon the idleRemover scan time, which is half of the smallest idle-timeout-minutes of any pool.
set-tx-query-timeout
Whether to set the query timeout based on the time remaining until transaction timeout. Any configured query timeout is used if no transaction exists. Defaults to false.
query-timeout Timeout for queries, in seconds. The default is no timeout.
allocation-retry The number of times to retry allocating a connection before throwing an exception. The default is 0, so an exception is thrown upon the first failure.
allocation-retry-wait-millis
How long, in milliseconds, to wait before retrying to allocate a connection. The default is 5000, which is 5 seconds.
xa-resource-timeout
If non-zero, this value is passed to method XAResource.setTransactionTimeout.

Table 4.20. Statement parameters

Parameter Description
track-statements
Whether to check for unclosed statements when a connection is returned to a pool and a statement is returned to the prepared statement cache. If false, statements are not tracked.

Valid values

  • true: statements and result sets are tracked, and a warning is issued if they are not closed.
  • false: neither statements or result sets are tracked.
  • nowarn: statements are tracked but no warning is issued. This is the default.
prepared-statement-cache-size The number of prepared statements per connection, in a Least Recently Used (LRU) cache.
share-prepared-statements
Whether asking for the same statement twice without closing it uses the same underlying prepared statement. The default is false.

Table 4.21. Recovery parameters

Parameter Description
recover-credential A username/password pair or security domain to use for recovery.
recover-plugin
An implementation of the org.jboss.jca.core.spi.recoveryRecoveryPlugin class, to be used for recovery.

4.9.9.9. JDBC Driver Download Locations

The following table gives the standard download locations for JDBC drivers of common databases used with JBoss EAP 6.

Note

These links point to third-party websites which are not controlled or actively monitored by Red Hat. For the most up-to-date drivers for your database, check your database vendor's documentation and website.

4.9.10. LDAP Data Sources

LDAP data sources use a Data Virtualization-specific JCA connector which is deployed into EAP during installation. There are many ways to create the ldap data source, using CLI, AdminShell, admin-console etc. The example shown below uses the CLI tool, as this works in both Standalone and Domain modes.
Execute the following command using the CLI once you connected to the Server. Make sure you provide the correct URL and user credentials. Add any additional properties required by the connector by duplicating the "connection-definitions" command below. Edit the JNDI name to match the JNDI name you used in the VDB:
batch 
/subsystem=resource-adapters/resource-adapter=ldap/connection-definitions=ldapDS:add(jndi-name=java:/ldapDS, class-name=org.teiid.resource.adapter.ldap.LDAPManagedConnectionFactory, enabled=true, use-java-context=true) 
/subsystem=resource-adapters/resource-adapter=ldap/connection-definitions=ldapDS/config-properties=LdapUrl:add(value=ldap://ldapServer:389) 
/subsystem=resource-adapters/resource-adapter=ldap/connection-definitions=ldapDS/config-properties=LdapAdminUserDN:add(value={cn=???,ou=???,dc=???}) 
/subsystem=resource-adapters/resource-adapter=ldap/connection-definitions=ldapDS/config-properties=LdapAdminUserPassword:add(value={pass}) 
/subsystem=resource-adapters/resource-adapter=ldap/connection-definitions=ldapDS/config-properties=LdapTxnTimeoutInMillis:add(value=-1) 
/subsystem=resource-adapters/resource-adapter=ldap:activate 
runbatch
To find out all the properties that are supported by this LDAP Connector execute the following command in the CLI:
/subsystem=teiid:read-rar-description(rar-name=ldap)

4.9.11. MongoDB Data Sources

The MongoDB data sources use a Data Virtualization-specific JCA connector that is deployed into EAP during installation. There are many ways to create a MongoDB data source, using CLI, AdminShell, admin-console and so forth. The example shown below uses the CLI tool, as this works in both Standalone and Domain modes.
Execute the following command using the CLI once you connected to the Server. Make sure you provide the correct URL and user credentials. Add any additional properties required by the connector by duplicating the "connection-definitions" command below. Edit the JNDI name to match the JNDI name you used in the VDB:
batch 
/subsystem=resource-adapters/resource-adapter=mongodb/connection-definitions=mongodbDS:add(jndi-name="java:/mongoDS", class-name=org.teiid.resource.adapter.mongodb.MongoDBManagedConnectionFactory, enabled=true, use-java-context=true) 
/subsystem=resource-adapters/resource-adapter=mongodb/connection-definitions=mongodbDS/config-properties=RemoteServerList:add(value="{host}:27017") 
/subsystem=resource-adapters/resource-adapter=mongodb/connection-definitions=mongodbDS/config-properties=Database:add(value="{db-name}") 
/subsystem=resource-adapters/resource-adapter=mongodb:activate 
runbatch
These are the properties that are defined in the RAR file:

Table 4.23. Properties

Property Description Required? Default
RemoteServerList
A comma-separated list of server locations. Each location can contain an optional port, of the format host:port
False.
Not applicable.
Username
Connection User's Name
False.
None.
Password
Connection User's password
False.
None.
Database
MongoDB database name
True.
None.
To find out all the properties that are supported by this MongoDB Connector execute the following command in the CLI:
/subsystem=teiid:read-rar-description(rar-name=mongodb)

4.9.12. Apache Phoenix Data Source

The following is an example that teaches you to set up Phoenix Data Sources, which are needed before you can use the Apache HBase Translator.
There are configuration templates for Phoenix data sources in the EAP_HOME>/docs/teiid/datasources directory. A complete description on how a data source can be added into Red Hat JBoss EAP is also described here.
Configuring a Phoenix data source is nearly identical to configuring JDBC Data Sources. The first step is deploying the Phoenix driver jar. Using below CLI command to deploy the Phoenix driver:
module add --name=org.apache.phoenix --resources=/path/to/phoenix-[version]-client.jar --dependencies=javax.api,sun.jdk,org.apache.log4j,javax.transaction.api /subsystem=datasources/jdbc-driver=phoenix:add(driver-name=phoenix,driver-module-name=org.apache.phoenix,driver-class-name=org.apache.phoenix.jdbc.PhoenixDriver
The driver jar can be download from Phoenix.
Next, create the Data Source base on above deployed driver, which is also like creating JDBC Data Source. Using below CLI command to create the data source:
/subsystem=datasources/data-source=phoenixDS:add(jndi-name=java:/phoenixDS, driver-name=phoenix, connection-url=jdbc:phoenix:{zookeeper quorum server}, enabled=true, use-java-context=true, user-name={user}, password={password})
Ensure the URL, Driver, and other properties are configured correctly: The JNDI name need to match the JNDI name you used in the VDB. The driver name need to match the driver you deployed in above steps
The URL need to match the HBase zookeeper quorum server. Here is an example:
 jdbc:phoenix [ :<zookeeper quorum> [ :<port number> ] [ :<root node> ] ], 'jdbc:phoenix:127.0.0.1:2181'
user-name/password - The user credentials for Phoenix Connection
Mapping a Phoenix table to an existing HBase table takes two steps. The first step is installing phoenix-[version]-server.jar to the classpath of every HBase region server. An easy way to do this is to copy it into the HBase lib. (For more details see the Phoenix documentation.)
Next, you must executing the DDL to map a Phoenix table to an existing HBase table. The DDL can either be executed via the Phoenix Command Line, or executed by JDBC.
The Following is a example for mapping an existing HBase Customer with the following structure:
As depicted above, the HBase Customer table have 2 column families, customer and sales, and each has 2 column qualifiers, name, city, product and amount respectively.Map this table to Phoenix via DDL:
 
CREATE TABLE IF NOT EXISTS "Customer"("ROW_ID" VARCHAR PRIMARY KEY, "customer"."city" VARCHAR, "customer"."name" VARCHAR, "sales"."amount" VARCHAR, "sales"."product" VARCHAR)
For more about mapping Phoenix table to an existing HBase table please refer to the Phoenix documentation.
Creating a new Phoenix table is just like mapping to an existing HBase table. Phoenix will create any metadata (table, column families) that do not exist. Similar to the above example the DDL to create the Phoenix/HBase Customer table would be:
CREATE TABLE IF NOT EXISTS "Customer"("ROW_ID" VARCHAR PRIMARY KEY, "customer"."city" VARCHAR, "customer"."name" VARCHAR, "sales"."amount" VARCHAR, "sales"."product" VARCHAR)

4.9.13. Salesforce Data Sources

Salesforce data sources use a Data Virtualization-specific JCA connector that is deployed into EAP during installation. There are many ways to create the salesforce data source, using CLI,AdminShell, admin-console etc. The example shown below uses the CLI tool, as this works in both Standalone and Domain modes.
Execute the following command using the CLI once you connected to the server. Make sure you provide the correct URL and user credentials. Add any additional properties required by the connector by duplicating the "connection-definitions" command below. Edit the JNDI name to match the JNDI name you used in the VDB:
batch 
/subsystem=resource-adapters/resource-adapter=salesforce/connection-definitions=sfDS:add(jndi-name=java:/sfDS, class-name=org.teiid.resource.adapter.salesforce.SalesForceManagedConnectionFactory, enabled=true, use-java-context=true) 
/subsystem=resource-adapters/resource-adapter=salesforce/connection-definitions=sfDS/config-properties=URL:add(value=https://www.salesforce.com/services/Soap/u/22.0) /subsystem=resource-adapters/resource-adapter=salesforce/connection-definitions=sfDS/config-properties=username:add(value={user}) 
/subsystem=resource-adapters/resource-adapter=salesforce/connection-definitions=sfDS/config-properties=password:add(value={password}) 
/subsystem=resource-adapters/resource-adapter=salesforce:activate 
runbatch
To find out all the properties that are supported by this Salesforce Connector execute the following command in the CLI:
/subsystem=teiid:read-rar-description(rar-name=salesforce)

4.9.14. Solr Data Sources

Solr data sources use a Data Virtualization-specific JCA connector that is deployed into EAP during installation. There are many ways to create a Solr data source, using CLI, AdminShell, admin-console, etc. The example shown below uses the CLI tool, as this works in both Standalone and Domain modes.
Execute the following command using the CLI once you connected to the Server. Make sure you provide the correct URL and user credentials. Add any additional properties required by the connector by duplicating the "connection-definitions" command below. Edit the JNDI name to match the JNDI name you used in the VDB:
batch 
/subsystem=resource-adapters/resource-adapter=solr/connection-definitions=solrDS:add(jndi-name=java:/solrDS, class-name=org.teiid.resource.adapter.solr.SolrManagedConnectionFactory, enabled=true, use-java-context=true) 
/subsystem=resource-adapters/resource-adapter=solr/connection-definitions=solrDS/config-properties=url:add(value=http://localhost:8983/solr/) 
/subsystem=resource-adapters/resource-adapter=solr/connection-definitions=solrDS/config-properties=CoreName:add(value=collection1) 
/subsystem=resource-adapters/resource-adapter=solr:activate 
runbatch
To find out all the properties that are supported by this Solr Connector execute the following command in the CLI:
/subsystem=teiid:read-rar-description(rar-name=solr)

4.9.15. Integrate Apache Solr with Red Hat JBoss Data Virtualization

In this example, you will learn how to move some data from a CSV file into Apache Solr using Red Hat JBoss Data Virtualiation. You will then issue queries to Apache Solr, to obtain the contents of a search using DV. Once the search results are available in Red Hat JBoss Data Virtualization, you can further enhance this data by integrating it with other data sources.

Prerequisites

  1. Create a temporary directory and copy Copy "/solr/example/solr/collection1" into it.
  2. Rename "/solr/example/solr/collection1" to "/solr/example/solr/babynames".
  3. Delete the contents of "/solr/example/solr/babynames/data" directory (if there are any).
  4. Delete the "/solr/example/solr/babynames/core.properties" file.
  5. Open the "/solr/example/solr/babynames/conf/schema.xml" file in a text editor and delete all of the elements under "fields" and "copyFields".
  6. Add this under "fields":
        <field indexed="true" name="_version_" stored="true" type="long"/>  
        <field indexed="true" name="_root_" stored="false" type="string"/>  
        <field indexed="true" name="id" stored="true" type="string" required="true" multiValued="false" />  
        <field indexed="true" name="state" stored="true" type="string" omitNorms="true"/>  
        <field indexed="true" name="name" required="true" stored="true" type="string"/>  
        <field indexed="true" name="gender" stored="true" type="string" omitNorms="true"/>  
        <field indexed="true" name="birthyear" stored="true" type="int"/>  
        <field indexed="true" name="totalcount" stored="true" type="int"/>  
        <field indexed="true" name="text" stored="false" type="text_general" multiValued="true"/>  
    
    These fields represent the schema for the data that is present in the baby names CSV document from above. The schemal.xml file defines the internal document structure for Solr.
  7. Save and close the file.
  8. Start Apache Solr by issuing these commands:
    cd "/solr/example"  
    java -jar start.jar  
    
  9. On the left-hand side, clck on Core Admin. (If you see Unload, click it too.)
  10. Click Add Core, and supply "babies" as the name and "babynames" as instanceDir.
    Solr is now configured with a core that can store and search documents.
You now hace a choice of building a VDB or a Dynamic VDB. First of all, you will learn how to make a VDB using Teiid Designer.
  1. Start Teiid Designer and switch to the Teiid Designer perspective.
  2. Ensure you have configured Red Hat JBoss Data Virtualization correctly and that you have a connection to it.
  3. Create a new "Teiid Model Project" and call it "BabyNames".
  4. Choose "File - import", then choose "Teiid Designer/File Source Flat - Source and View Model".
  5. Create a file-based model.
  6. You can preview the data by right-clicking on the "babies" table, and selecting "Modeling - Preview Data". Make sure you can do this successfully.
  7. Choose "File - import", then choose "Teiid Designer/Teiid Connection - Source Model" and click Next.
  8. In the "Data the Source to use for Import" dialog box, click "New".
  9. Ensure Create Data Source dialog has "solr-ds" set as the name., "solr" as the driver and "AllowCompression" set to true.
  10. Click Ok and then click Next.
  11. Make sure your "translator" is set to "solr", and click "Next".
  12. The dialog will show the DDL for the model (below), with "babies" table. Click on until you reach the Finish button.
    	CREATE FOREIGN TABLE babies (  
             id string OPTIONS (SEARCHABLE 'Searchable'),  
             birthyear integer OPTIONS (SEARCHABLE 'Searchable'),  
             name string OPTIONS (SEARCHABLE 'Searchable'),  
             state string OPTIONS (SEARCHABLE 'Searchable'),  
             gender string OPTIONS (SEARCHABLE 'Searchable'),  
            totalcount integer OPTIONS (SEARCHABLE 'Searchable')  
        ) OPTIONS (UPDATABLE TRUE);  
    
  13. Now build a VDB called "babynames" with all of the models in this VDB and deploy it to server by right-clicking.
The other option mentioned above is to build a dynamic VDB. (Skip this procedure if you built a regular VDB instead.)
  1. Open the standalone.xml in your text editor.
  2. Add this XML under the "resource-adapter" section:
    <!-- Data Source for Flat File -->		
    			    <resource-adapter id="file-ds">  
                            <module slot="main" id="org.jboss.teiid.resource-adapter.file"/>  
                            <transaction-support>NoTransaction</transaction-support>  
                            <connection-definitions>  
                                <connection-definition class-name="org.teiid.resource.adapter.file.FileManagedConnectionFactory" jndi-name="java:/file-ds" enabled="true" pool-name="file-ds">  
                                    <config-property name="ParentDirectory">  
                                        /babynames  
                                    </config-property>  
                                </connection-definition>  
                            </connection-definitions>  
                        </resource-adapter>  
    
    <!-- Data Source for Solr --> 
                        <resource-adapter id="solr-ds">  
                            <module slot="main" id="org.jboss.teiid.resource-adapter.solr"/>  
                            <transaction-support>XATransaction</transaction-support>  
                            <connection-definitions>  
                                <connection-definition class-name="org.teiid.resource.adapter.solr.SolrManagedConnectionFactory" jndi-name="java:/solr-ds" enabled="true" pool-name="solr-ds">  
                                    <config-property name="CoreName">  
                                        babies  
                                    </config-property>  
                                    <config-property name="url">  
                                        http://localhost:8983/solr/babies  
                                    </config-property>  
                                </connection-definition>  
                            </connection-definitions>  
                        </resource-adapter>  
    
  3. Start Red Hat JBoss Data Virtualization.
  4. Create this dynamic VDB file and save it as "babynames-vdb.xml":
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>  
    <vdb name="babynames" version="1">  
        <model name="solr">  
            <source name="solr" translator-name="solr" connection-jndi-name="java:/solr-ds"/>  
        </model>  
        <model name="file_source">  
            <source name="file" translator-name="file" connection-jndi-name="java:/file-ds"/>  
        </model>  
      
        <model name = "file" visible = "true" type = "VIRTUAL" >  
             <metadata type = "DDL"><![CDATA[ 
                  CREATE VIEW babies ( 
                    name varchar, 
                    state varchar, 
                    gender varchar, 
                    birthyear integer, 
                    totalcount integer 
                    ) AS 
                      SELECT A.name, A.state, A.gender, A.birthyear,  A.totalcount FROM 
               (EXEC file_source.getTextFiles('VA.TXT')) AS f, 
                      TEXTTABLE(f.file COLUMNS state string, gender string, birthyear integer, name string, totalcount integer) AS A; 
          ]]
             </metadata>  
        </model>  
    </vdb> 
    
  5. Deploy the VDB using the console or the CLI.
In order to test your integration, follow these steps.
  1. Make sure your VDB is active by checking the Console or your log files or by using web-console at http://localhost:9990/console/App.html#vdb-runtime
  2. Use a tool like JBDS Data Tools or Squirrel to execute test queries. First check the file source and then the Solr source (there should be none in Solr at first):
        select * from file.babies  
    
        select * from solr.babies  
    
  3. insert the File source records into Solr:
        insert into solr.babies (id, name, state, gender, birthyear, totalcount)  
          select f.name, f.name, f.state, f.gender, f.birthyear, f.totalcount from file.babies as f   
    
    You should see 131638 rows affected.
  4. You will now be able to issue SQL commands like these:
     select * from solr.babies  
    select * from solr.babies where name = 'Mary'  
    select * from solr.babies where name like '*ary'  
    select * from solr.babies where birthyear > 1910 and birthyear < 1920
    
  5. If you have other models like RDBMS, Salesforce, Web Service etc you can join the table between those sources and Solr. You can also issue SQL queries like INESRT/UPDATE/DELETE on Solr source to manage the documents in the store.

4.9.16. Web Service Data Sources

Web service data sources use a Data Virtualization-specific JCA connector that is deployed into EAP during installation. There are many ways to create the file data source, using CLI, AdminShell, admin-console etc. The example shown below uses the CLI tool, as this works in both Standalone and Domain modes.
Execute following command using the CLI once you connected to the Server. Make sure you provide the correct endpoint and other properties below. Add any additional properties required by the connector by duplicating the "connection-definitions" command below. Edit the JNDI name to match the JNDI name you used in the VDB:
batch 
/subsystem=resource-adapters/resource-adapter=webservice/connection-definitions=wsDS:add(jndi-name=java:/wsDS, class-name=org.teiid.resource.adapter.ws.WSManagedConnectionFactory, enabled=true, use-java-context=true) 
/subsystem=resource-adapters/resource-adapter=webservice/connection-definitions=wsDS/config-properties=EndPoint:add(value={end_point}) 
/subsystem=resource-adapters/resource-adapter=webservice:activate 
runbatch
To find out all the properties that are supported by this Web Service Connector execute the following command in the CLI:
/subsystem=teiid:read-rar-description(rar-name=webservice)
The Web Service Data Source supports specifying a WSDL using the Wsdl property. If the Wsdl property is set, then the ServiceName, EndPointName, and NamespaceUri properties should also be set. The Wsdl property may be a URL or file location or the WSDL to use. You must restart the server.

Table 4.24. Registry Properties

Property Application Required? Default? Description
EndPoint
HTTP and SOAP.
True
Not applicable.
URL for HTTP ans service endpoint for SOAP.
SecurityType
HTTP and SOAP.
false
none
Type of Authentication to used with the web service. Allowed values are "None","HTTPBasic","WSSecurity" and "Kerberos".
AuthUserName
HTTP and SOAP.
false
Not applicable.
Name value for authentication, used in HTTPBasic and WsSecurity.
AuthPassword
HTTP and SOAP.
false
Not applicable.
Password value for authentication, used in HTTPBasic and WsSecurity
ConfigFile
HTTP and SOAP.
False
Not applicable.
CXF client configuration File or URL.
ConfigName
HTTP and SOAP.
False
Not applicable.
Note that this property is deprecated.
EndPointName
HTTP and SOAP.
False
Teiid
Local part of the end point QName to use with this connection, needs to match one defined in CXF file.
ServiceName
SOAP
False
Not applicable.
Local part of the service QName to use with this connection.
NamespaceUri
SOAP.
False
http://teiid.org
Namespace URI of the service QName to use with this connection
RequestTimeout
HTTP and SOAP.
False
Not applicable.
Timeout for request.
ConnectTimeout
HTTP and SOAP.
False
Not applicable.
Timeout for connection.
Wsdl
SOAP.
False
Not applicable.
WSDL file or URL for the web service.
Each web service data source may choose a particular CXF config file and port configuration. The ConfigFile config property specifies the Spring XML configuration file for the CXF Bus and port configuration to be used by connections. If no config file is specified then the system default configuration will be used.
Only one port configuration can be used by this data source. You may explicitly set the local name of the port QName to use via the ConfigName property. The namespace URI for the QName in your config file should match your WSDL/namespace setting on the data source or use the default of http://teiid.org. See the CXF Documentation and the sections below on WS-Security, Logging, etc. for examples of using the CXF configuration file.
<beans xmlns="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"
        xsi:schemaLocation="http://cxf.apache.org/transports/http/configuration
        http://cxf.apache.org/schemas/configuration/http-conf.xsd
        http://www.springframework.org/schema/beans
        >
 
    <http-conf:conduit name="{http://teiid.org}configName.http-conduit">
        <http-conf:client ConnectionTimeout="120000" ReceiveTimeout="240000"/>
    </http-conf:conduit>
</beans>
In the conduit name {http://teiid.org}configName.http-conduit, the namespace, {http://teiid.org}, may be set via the namespace datasource property. Typically that will only need done when also supplying the wsdl setting. The local name is followed by .http-conduit. It will be based upon the configName setting, with a default value of teiid.

Note

You do not have to use the Spring configuration to set timeouts. The ConnectionTimeout and ReceiveTimeout can be set via the resource adapter connectTimeout and requestTimeout properties respectively.
To enable the use of WS-Security, the SecurityType should be set to WSSecurity. At this time Teiid does not expect a WSDL to describe the service being used. Thus a Spring XML configuration file is not only required, it must instead contain all of the relevant policy configuration. And just as with the general configuration, each data source is limited to specifying only a single port configuration to use: batch /subsystem=resource-adapters/resource-adapter=webservice/connection-definitions=wsDS:add(jndi-name=java:/wsDS, class-name=org.teiid.resource.adapter.ws.WSManagedConnectionFactory, enabled=true, use-java-context=true) /subsystem=resource-adapters/resource-adapter=webservice/connection-definitions=wsDS/config-properties=ConfigFile:add(value=${jboss.server.home.dir}/standalone/configuration/xxx-jbossws-cxf.xml) /subsystem=resource-adapters/resource-adapter=webservice/connection-definitions=wsDS/config-properties=ConfigName:add(value=port_x) /subsystem=resource-adapters/resource-adapter=webservice/connection-definitions=wsDS/config-properties=SecurityType:add(value=WSSecurity) /subsystem=resource-adapters/resource-adapter=webservice:activate runbatch
This is the corresponding xxx-jbossws-cxf.xml file that adds a timestamp to the SOAP header
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:jaxws="http://cxf.apache.org/jaxws"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
          http://www.springframework.org/schema/beans/spring-beans.xsd
          http://cxf.apache.org/jaxws
          http://cxf.apache.org/schemas/jaxws.xsd">
 
    <jaxws:client name="{http://teiid.org}port_x"
        createdFromAPI="true">
        <jaxws:outInterceptors>
            <bean/>
            <ref bean="Timestamp_Request"/>
        </jaxws:outInterceptors>
    </jaxws:client>
 
    <bean
 
        id="Timestamp_Request">
        <constructor-arg>
            <map>
                <entry key="action" value="Timestamp"/>
            <map>
        </constructor-arg>
    </bean>
 
</beans>
Note that the client port configuration is matched to the data source instance by the QName {http://teiid.org}port_x, where the namespace will match your namespace setting or the default of http://teiid.org. The configuration may contain other port configurations with different local names.
WS-Security Kerberos is only supported when the WSDL property is defined in resource-adapter connection configuration and only when WSDL Based Procedures are used. WSDL file must contain WS-Policy section, then WS-Policy section is correctly interpreted and enforced on the endpoint. This is what the sample CXF configuration looks like:
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:http="http://cxf.apache.org/transports/http/configuration"
    xmlns:jaxws="http://cxf.apache.org/jaxws"
    xmlns:cxf="http://cxf.apache.org/core"
    xmlns:p="http://cxf.apache.org/policy"
    xmlns:sec="http://cxf.apache.org/configuration/security"
    xsi:schemaLocation="http://www.springframework.org/schema/beans           http://www.springframework.org/schema/beans/spring-beans.xsd           http://cxf.apache.org/jaxws                           http://cxf.apache.org/schemas/jaxws.xsd           http://cxf.apache.org/transports/http/configuration   http://cxf.apache.org/schemas/configuration/http-conf.xsd           http://cxf.apache.org/configuration/security          http://cxf.apache.org/schemas/configuration/security.xsd           http://cxf.apache.org/core http://cxf.apache.org/schemas/core.xsd           http://cxf.apache.org/policy http://cxf.apache.org/schemas/policy.xsd">
    <bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"/>
    <cxf:bus>
        <cxf:features>
            <p:policies/>
            <cxf:logging/>
        </cxf:features>
    </cxf:bus>
 
    <jaxws:client name="{http://webservices.samples.jboss.org/}HelloWorldPort" createdFromAPI="true">
        <jaxws:properties>
            <entry key="ws-security.kerberos.client">
                <bean class="org.apache.cxf.ws.security.kerberos.KerberosClient">
                    <constructor-arg ref="cxf"/>
                    <property name="contextName" value="alice"/>
                    <property name="serviceName" value="bob@service.example.com"/>
                </bean>
            </entry>
        </jaxws:properties>
    </jaxws:client>
</beans>
Nexst, configure the security-domain in the standalone.xml file under 'security' subsystem like this:
<security-domain name="alice" cache-type="default">
    <authentication>
        <login-module code="Kerberos" flag="required">
            <module-option name="storeKey" value="true"/>
            <module-option name="useKeyTab" value="true"/>
            <module-option name="keyTab" value="/home/alice/alice.keytab"/>
            <module-option name="principal" value="alice@EXAMPLE.COM"/>
            <module-option name="doNotPrompt" value="true"/>
            <module-option name="debug" value="true"/>
            <module-option name="refreshKrb5Config" value="true"/>
        </login-module>
    </authentication>
</security-domain>
The CXF config property may also be used to control the logging of requests and responses for specific or all ports. Logging, when enabled, will be performed at an INFO level to the org.apache.cxf.interceptor context: batch /subsystem=resource-adapters/resource-adapter=webservice/connection-definitions=wsDS:add(jndi-name=java:/wsDS, class-name=org.teiid.resource.adapter.ws.WSManagedConnectionFactory, enabled=true, use-java-context=true) /subsystem=resource-adapters/resource-adapter=webservice/connection-definitions=wsDS/config-properties=ConfigFile:add(value=${jboss.server.home.dir}/standalone/configuration/xxx-jbossws-cxf.xml) /subsystem=resource-adapters/resource-adapter=webservice/connection-definitions=wsDS/config-properties=ConfigName:add(value=port_x) /subsystem=resource-adapters/resource-adapter=webservice:activate runbatch
Here is the corresponding xxx-jbossws-cxf.xml file:
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:jaxws="http://cxf.apache.org/jaxws"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
          http://www.springframework.org/schema/beans/spring-beans.xsd
          http://cxf.apache.org/jaxws
          http://cxf.apache.org/schemas/jaxws.xsd">
 
    <jaxws:client name="{http://teiid.org}port_y"
        createdFromAPI="true">
        <jaxws:features>
            <bean class="org.apache.cxf.feature.LoggingFeature"/>
        </jaxws:features>
    </jaxws:client>
 
</beans>
The CXF config property may also be used to control low level aspects of the HTTP transport:

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"
       xsi:schemaLocation="http://cxf.apache.org/transports/http/configuration
                           http://cxf.apache.org/schemas/configuration/http-conf.xsd
                           http://www.springframework.org/schema/beans
                             http://www.springframework.org/schema/beans/spring-beans.xsd">
 
  <http-conf:conduit name="{http://teiid.org}port_z.http-conduit">
     <!-- WARNING ! disableCNcheck=true should NOT be used in production -->
     <http-conf:tlsClientParameters disableCNcheck="true" />
 
  </http-conf:conduit>
</beans>
To use HTTPS, configure the CXF file like this (You can also configure HTTPBasic, kerberos and so forth):
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:sec="http://cxf.apache.org/configuration/security"
    xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"
    xmlns:jaxws="http://java.sun.com/xml/ns/jaxws"
    xsi:schemaLocation="http://cxf.apache.org/transports/http/configuration http://cxf.apache.org/schemas/configuration/http-conf.xsd http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd http://cxf.apache.org/configuration/security http://cxf.apache.org/schemas/configuration/security.xsd">
  
    <http-conf:conduit name="*.http-conduit">
        <http-conf:client ConnectionTimeout="120000" ReceiveTimeout="240000"/>
        <http-conf:tlsClientParameters secureSocketProtocol="SSL">
          <sec:trustManagers>
            <sec:keyStore type="JKS" password="changeit" file="/path/to/truststore.jks"/>
          </sec:trustManagers>
        </http-conf:tlsClientParameters>
    </http-conf:conduit>
</beans>
The kerberos support is based SPNEGO as described in http://cxf.apache.org/docs/client-http-transport-including-ssl-support.html#ClientHTTPTransport%28includingSSLsupport%29-SpnegoAuthentication%28Kerberos%29. There two types of kerberos support, this first of which is Negotiation. With this configuration, the REST service is configured with a Kerberos JAAS domain, to negotiate a token, which is then used to access the web service. For this first create a security domain in the standalone.xml file:
<security-domain name="MY_REALM" cache-type="default">
     <authentication>
         <login-module code="Kerberos" flag="required">
             <module-option name="storeKey" value="true"/>
              
             <module-option name="useKeyTab" value="true"/>
             <module-option name="keyTab" value="/home/username/service.keytab"/>
             <module-option name="principal" value="host/testserver@MY_REALM"/>
 
             <module-option name="doNotPrompt" value="true"/>
             <module-option name="debug" value="false"/>
         </login-module>
     </authentication>
</security-domain> 
Set the jboss-cxf-xxx.xml file like this:
<beans xmlns="http://www.springframework.org/schema/beans" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xmlns:sec="http://cxf.apache.org/configuration/security" 
        xmlns:http-conf="http://cxf.apache.org/transports/http/configuration" 
        xsi:schemaLocation="http://cxf.apache.org/transports/http/configuration http://cxf.apache.org/schemas/configuration/http-conf.xsd http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd http://cxf.apache.org/configuration/security http://cxf.apache.org/schemas/configuration/security.xsd"> 
  
       <http-conf:conduit name="*.http-conduit">
           <http-conf:authorization>
               <sec:AuthorizationType>Negotiate</sec:AuthorizationType>
               <sec:Authorization>MY_REALM</sec:Authorization>
           </http-conf:authorization>
       </http-conf:conduit>
</beans>
The resource adapter creation needs to define these properties:
<config-property name="ConfigFile">path/to/jboss-cxf-xxxx.xml</config-property>
<config-property name="ConfigName">test</config-property>

Important

Even though above configuration configures the value of "ConfigName", the cxf framework currently in the case of JAX-RS client does not give option to use it. For that reason use "*.http-conduit" which will apply to all the HTTP communications under this resource adapter.
The second method is Delegation. If the user is already logged into Teiid using Kerberos using JDBC/ODBC or used SPNEGO in web-tier and used pass-through authentication into Teiid, then there is no need to negotiate a new token for the Kerberos. The system can delegate the existing token. To configure for delegation, set up security domain defined exactly as defined in "negotiation", and jboss-cxf-xxx.xml file, however remove the following line from jboss-cxf-xxx.xml file, as it is not going to negotiate new token.
<sec:Authorization>MY_REALM</sec:Authorization>
Add the following properties in web service resource adapter creation. One determines that "kerberos" security being used, the second defines a security domain to be used at the data source, in this case we want to use a security domain that passes through a logged-in user:
<config-property name="SecurityType">Kerberos</config-property>
<security> 
     <security-domain>passthrough-security</security-domain> 
</security> 
To configure the "passthrough-security" security domain you must add the "security" subsystem settings:
<security-domain name="passthrough-security" cache-type="default"> 
    <authentication> 
        <login-module code="org.teiid.jboss.PassthroughIdentityLoginModule" flag="required" module="org.jboss.teiid"> 
            <module-option name="username" value="guest"/> 
            <module-option name="password" value="guest"/> 
        </login-module> 
    </authentication> 
</security-domain> 

Note

The username and password are optional. If there is no authenticated subject available in the context, these can help create a simple static user, but that user will not work with kerberos authentication as the subject will not have the kerberos token that is required.