Red Hat Training

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

3.9. Data Source Deployment

3.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, and so forth. The example below uses the CLI tool.

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 3.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.
Username	Connection User's Name	True.	None.
Password	Connection User's password	True.	None.
InstanceName	Accumulo instance name	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)

3.9.2. 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, and so forth. The example below uses the CLI tool.

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)

3.9.3. 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 below uses the CLI tool.

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)

3.9.4. Google Spreadsheet Data Sources

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 to drive authentication. The JCA connector connects to exactly one spreadsheet with each sheet exposed as a table. Authentication to your google account may be done using OAuth, which requires a refresh token:

Table 3.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

3.9.5. Red Hat JBoss Data Grid Hot Rod Data Sources

Red Hat JBoss Data Grid's Hot Rod data sources use a Red Hat JBoss Data Virtualization-specific JCA connector that is deployed upon installation. Detailed below are the different configuration options available to you depending on the version of Red Hat JBoss Data Grid you are using.

3.9.5.1. Red Hat JBoss Data Grid 6.x Configuration

You can configure the JCA connector to support accessing a remote JDG cache using the Hot Rod client.

There are two options for how the JDG schema can be configured in the connector: protobuf annotations or protobuf (.proto) file with marshaller(s). The following are the requirements:

Minimum requirement: JDG 6.2 - this requires you provide a protobuf definition file and pojo marshaller for the pojo to be cached
Minimum requirement: 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

Regardless of the option you choose, the following property is required as it provides the mapping to the JDG cache and pojo that will be accessed.

Table 3.3. Required Cache 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.

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

If the pojo is to be used to define the schema, then you should use the protobuf annotations. See JDG Protobuf Annotations in the Custom Fields Indexing with Protobuf section of the Red Hat JBoss Data Grid 7.1 Developer Guide.
If the protobuf definition and mashaller(s) are to be used, then these should also be packaged in the jar (or a separate jar that is included in the classpath).
The class should be packaged into a jar so that it can be deployed as a module.

To configure the resource-adapter to use the pojo, do the following:

Deploy the pojo jar as a module in the Red Hat JBoss EAP server.
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>
```

One of the following properties is required for defining how the RemoteCacheManager will be created and accessed:

Table 3.4. Optional Cache 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 additional properties are required when the protobuf definition file (.proto) and the pojo marshaller(s) are being used to configure the JDG schema:

Table 3.5. Properties when using protobuf definition file (.proto) and pojo marshaller(s)

Property Name	Required?	Property Template	Description
ProtobufDefinitionFile	Yes	NA	Path to the Google Protobuf file that is packaged in a jar (here is an example: `/quickstart/addressbook.proto`)
MessageMarshallers	Yes	marshaller \[,marshaller,..\]	Contains class names mapped to its respective message marshaller (class:marshaller,\[class:marshaller,..\]) that are registered for serialization.
MessageDescriptor	Yes	NA	Message descriptor class name for the root object in cache.
Module	No	NA	JBoss EAP server module where the jar with pojos is located.

These are the additional properties that need to be configured if you are using the Remote Cache for external materialization:

Table 3.6. Remote Cache Properties for External Materialization

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 aliases 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:

<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="Module">
					com.client.quickstart.pojos
				</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="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>

3.9.5.2. Red Hat JBoss Data Grid 7.x Configuration

These are the properties defined in the RAR file:

Table 3.7. Properties

Property Name	Required?	Description
RemoteServerList	Yes	A comma separated list of server locations. Each location can contain an optional port, of the format host:port.
UserName	No	If remote server is secured, this property used as username to log in.
Password	No	If remote server is secured, this property used as password to log in.
SaslMechanism	No	If remote server is secured, this property defines the type of security. Allowed values are "CRAM-MD5", "DIGEST-MD5", "PLAIN", "EXTERNAL". "EXTERNAL" is when certificate based security at use, all others use username/password.
AuthenticationRealm	No	Realm to use for authentication.
AuthenticationServerName	No	Infinispan server name where the Authentication is handled.
TrustStoreFileName	No	When "EXTERNAL" SaslMechnism used, use this property to define truststore. Alternatively JAVA system property "javax.net.ssl.trustStore" can also be defined instead.
TrustStorePassword	No	When "EXTERNAL" SaslMechnism used, use this property to define truststore password. Alternatively JAVA system property "javax.net.ssl.trustStorePassword" can also be defined instead.
KeyStoreFileName	No	When "EXTERNAL" SaslMechnism used, use this property to define keystore. Alternatively JAVA system property "javax.net.ssl.keyStore" can also be defined instead.
KeyStorePassword	No	When "EXTERNAL" SaslMechnism used, use this property to define keystore password. Alternatively JAVA system property "javax.net.ssl.keyStorePassword" can also be defined instead.

The example below shows a resource-adapter's XML code. This code is used to connect to the JDG StockMat quick start:

<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:/infinispanStockMat" enabled="true" use-java-context="true" pool-name="infinispanStockMat">
				<config-property name="RemoteServerList">
					127.0.0.1:11322
				</config-property>
			</connection-definition>
		</connection-definitions>
</resource-adapter>

The example below shows how to use the CLI tool to create the same JDG Hot Rod data source as above. You can use this in both standalone and domain modes. Execute the following commands using the CLI once you are 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=ispnStockMat:add(module=org.jboss.teiid.resource-adapter.infinispan.hotrod)
/subsystem=resource-adapters/resource-adapter=ispnStockMat/connection-definitions=infinispanStockMat:add(jndi-name="java:/infinispanStockMat", class-name=org.teiid.resource.adapter.infinispan.hotrod.InfinispanManagedConnectionFactory, enabled=true, use-java-context=true)
/subsystem=resource-adapters/resource-adapter=ispnStockMat/connection-definitions=infinispanStockMat/config-properties=RemoteServerList:add(value="127.0.0.1:11322")
/subsystem=resource-adapters/resource-adapter=ispnStockMat:activate
run-batch

To discover all the properties that are supported by this JDG Hot Rod Connector, first create a resource-adapter and then execute this command in the CLI, replacing the rar-name with the name of that resource-adapter:

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

3.9.6. JDBC Data Sources

3.9.6.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 EAP_HOME/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 EAP is running in standalone mode, you can also manually copy this ojdbc6.jar to the EAP_HOME/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, and so forth. The example below uses the CLI tool.

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=oracle-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=oracle-ds:enable

3.9.6.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:

Install (or deploy) the JDBC JAR driver file.
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.

Important

The jdbc driver to support JDK 1.4/1.5 has been deprecated.

3.9.6.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.

3.9.6.4. Install a JDBC Driver with the Management CLI

Procedure 3.5. Install a JDBC Driver with the Management CLI

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

3.9.6.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 3.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.

Change to, or create, an empty temporary directory.
Create a META-INF subdirectory.
Create a META-INF/services subdirectory.
Create a META-INF/services/java.sql.Driver file, which contains one line indicating the fully-qualified class name of the JDBC driver.

Use the JAR command-line tool to update the JAR like this:

jar \-uf jdbc-driver.jar META-INF/services/java.sql.Driver

Section 1.2.2, “Log in to the Management Console”
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.

3.9.6.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 3.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.

3.9.6.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

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

- Management CLI
  1. Section 1.3.1, “Launch the Management CLI”.
  2. 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
```
  3. 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)
```
  4. Enable the datasource:
```
xa-data-source enable --name=XA_DATASOURCE_NAME
```
- Management Console
  1. Section 1.2.2, “Log in 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 at the top left.
    3. Expand the Subsystems menu on the left of the console, then expand the Connector menu.
    4. Select Datasources.
  3. Select the XA Datasource tab.
  4. 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.

3.9.6.8. Datasource Parameters

Table 3.8. 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 3.13, “Security parameters”.
validation	Contains child elements which are validation settings. See Table 3.14, “Validation parameters”.
timeout	Contains child elements which are timeout settings. See Table 3.15, “Timeout parameters”.
statement	Contains child elements which are statement settings. See Table 3.16, “Statement parameters”.

Table 3.9. 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 3.11, “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 3.10. 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	Contains child elements which are pooling settings. See Table 3.11, “Pool parameters common to non-XA and XA datasources” and Table 3.12, “XA pool parameters”.
recovery	Contains child elements which are recovery settings. See Table 3.17, “Recovery parameters”.

Table 3.11. 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 3.12. 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 3.13. 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 3.14. 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 3.15. 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 3.16. 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 3.17. 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.

3.9.6.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.

Table 3.18. JDBC driver download locations

Vendor	Download Location
MySQL	http://www.mysql.com/products/connector/
PostgreSQL	http://jdbc.postgresql.org/
Oracle	http://www.oracle.com/technetwork/database/features/jdbc/index-091264.html
IBM	http://www-306.ibm.com/software/data/db2/java/
Sybase	http://www.sybase.com/products/allproductsa-z/softwaredeveloperkit/jconnect
Microsoft	http://msdn.microsoft.com/data/jdbc/

3.9.7. 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, and so forth. The example below uses the CLI tool.

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)

3.9.8. 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 below uses the CLI tool.

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 3.19. 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)

3.9.9. 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 downloaded 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.

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)

3.9.10. 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, and so forth. The example below uses the CLI tool.

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)

3.9.11. 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, and so forth. The example below uses the CLI tool.

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)

3.9.12. 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, and so forth. The example below uses the CLI tool.

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 3.20. 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 EndPointName 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 and the CXF Configuration chapter of this book for examples of using the CXF configuration file.

Select Your Language

Language:

Language:

Red Hat Training

3.9. Data Source Deployment

3.9.1. Accumulo Data Sources

3.9.2. Cassandra Data Sources

3.9.3. File Data Source

3.9.4. Google Spreadsheet Data Sources

3.9.5. Red Hat JBoss Data Grid Hot Rod Data Sources

3.9.5.1. Red Hat JBoss Data Grid 6.x Configuration

3.9.5.2. Red Hat JBoss Data Grid 7.x Configuration

3.9.6. JDBC Data Sources

3.9.6.1. JDBC Data Sources

3.9.6.2. Configuring JDBC Data Sources

3.9.6.3. Example Configuration

3.9.6.4. Install a JDBC Driver with the Management CLI

3.9.6.5. Install a JDBC Driver with the Management Console

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

3.9.6.7. Create an XA Datasource with the Management Interfaces

3.9.6.8. Datasource Parameters

3.9.6.9. JDBC Driver Download Locations

3.9.7. LDAP Data Sources

3.9.8. MongoDB Data Sources

3.9.9. Apache Phoenix Data Source

3.9.10. Salesforce Data Sources

3.9.11. Solr Data Sources

3.9.12. Web Service Data Sources

Quick Links

Help

Site Info

Related Sites

About

Red Hat legal and privacy links

Red Hat legal and privacy links

Language:

Language and Page Formatting Options

Language:

Red Hat Training

3.9. Data Source Deployment

3.9.1. Accumulo Data Sources

3.9.2. Cassandra Data Sources

3.9.3. File Data Source

3.9.4. Google Spreadsheet Data Sources

3.9.5. Red Hat JBoss Data Grid Hot Rod Data Sources

3.9.5.1. Red Hat JBoss Data Grid 6.x Configuration

3.9.5.2. Red Hat JBoss Data Grid 7.x Configuration

3.9.6. JDBC Data Sources

3.9.6.1. JDBC Data Sources

3.9.6.2. Configuring JDBC Data Sources

3.9.6.3. Example Configuration

3.9.6.4. Install a JDBC Driver with the Management CLI

3.9.6.5. Install a JDBC Driver with the Management Console

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

3.9.6.7. Create an XA Datasource with the Management Interfaces

3.9.6.8. Datasource Parameters

3.9.6.9. JDBC Driver Download Locations

3.9.7. LDAP Data Sources

3.9.8. MongoDB Data Sources

3.9.9. Apache Phoenix Data Source

3.9.10. Salesforce Data Sources

3.9.11. Solr Data Sources

3.9.12. Web Service Data Sources

Quick Links

Help

Site Info

Related Sites

Systems Status

About

Red Hat legal and privacy links

Red Hat legal and privacy links