JBoss.orgCommunity Documentation
A VDBis the primary means to define a Virtual Database in Teiid. A user can create a VDB using Teiid Designer or follow the instructions in the Reference Guide to create a "Dynamic VDB" without Teiid Designer.
Once you have a "VDB" built it can be deployed/removed in Teiid runtime in different ways.
If VDB versioning is not used to give distinct version numbers, overwriting a VDB of the same name will terminate all connections to the old VDB. It is recommended that VDB versioning be used for production systems.
Removing an existing VDB will immediately clean up VDB file resources, but will not automatically terminate existing sessions.
Copy the VDB file into the "<jboss-install>/server/<profile>/deploy" directory. Make sure that there are no other VDB files with the same name. If a VDB already exists with the same name, then this VDB will be replaced with the new VDB. This is the simplest way to deploy a VDB. This is mostly designed for quick deployment during development, when the Teiid server is available locally on the developer machine.
Use the JOPR-based web console configuration system. Check out the JOPR plugin at:
http://<host>:<port>/admin-console
More details for this can be found in the Admin Console VDB deployment section.This is the easiest way to deploy a VDB to a remote server.
Teiid provides a groovy based AdminShell scripting tool, which can be used to deploy a VDB. Check out the "deployVDB" method. Consult the AdminShell documentation for more information. Note that using the AdminShell scripting, you can automate the deployment of artifacts in your environment.
The Admin API (look in org.teiid.adminpi.*) provides Java API methods that lets a user connect to a Teiid runtime and deploy a VDB. If you need to programmatically deploy a VDB use this method. This method is preferable for OEM users, who are trying to extend the Teiid's capabilities through their applications.
Apart from deploying the VDB, the user is also responsible for providing all the necessary dependent libraries, configuration for creating the data sources that are needed by the models (schemas) defined in "META-INF/vdb.xml" file inside your VDB. For example, if you are trying to integrate Oracle and File sources in your VDB, then you are responsible for providing the JDBC driver for the Oracle source and any necessary documents and configuration that are needed by the File Translator.
Data source instances may be used by only one VDB, or may be shared with as many VDBs or other applications as makes since for your deployments. Consider sharing connections to sources that have heavy-weight and resource constrained connections.
With the exception of JDBC, each of the data sources supported by has a corresponding .rar (zip format) file in <jboss-install>/server/<profile>/deploy/teiid/connectors. If not using JOPR or other tooling to create your -ds.xml files, you can consult the .rar files META-INF/ra.xml for a full description of how the source can be configured.
Some -ds.xml files may contain passwords or other sensitive information. See the WIKI article EncryptingDataSourcePasswords to not store passwords in plain text.
Once the VDB and its dependencies are deployed, then client applications can connect using the JDBC API. If there are any errors in the deployment, a connection attempt will not be successful and a message will be logged. You can use the admin-console tool or check the log files for errors and correct them before proceeding.
The following is an example highlighting configuring an Oracle data source. The process is nearly identical regardless of the vendor. Typically only the client jar and the setting in the -ds.xml file change.
There are templates for all the data sources in the "<jboss-install>/docs/examples/jca" directory.
Copy the Oracle JDBC JAR file into "<jboss-install>/server/<profile>/lib" directory
Create a "data source" to the Oracle instance in the JBoss container. This typically done by creating "xxx-ds.xml" file and copying this file to the "<jboss-install>/server/<profile>/deploy" directory. The following shows a "-ds.xml" file template for Oracle. You can also use admin-console to create this data source.
<?xml version="1.0" encoding="UTF-8"?>
<datasources>
<xa-datasource>
<jndi-name>OracleDS</jndi-name>
<!-- uncomment to enable interleaving <interleaving/> -->
<isSameRM-override-value>false</isSameRM-override-value>
<xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
<xa-datasource-property name="URL">jdbc:oracle:oci8:@tc</xa-datasource-property>
<xa-datasource-property name="User">scott</xa-datasource-property>
<xa-datasource-property name="Password">tiger</xa-datasource-property>
<!-- Uses the pingDatabase method to check a connection is still valid before handing it out from the pool -->
<!--valid-connection-checker-class-name>
org.jboss.resource.adapter.jdbc.vendor.OracleValidConnectionChecker
</valid-connection-checker-class-name-->
<!-- Checks the Oracle error codes and messages for fatal errors -->
<exception-sorter-class-name>
org.jboss.resource.adapter.jdbc.vendor.OracleExceptionSorter
</exception-sorter-class-name>
<!-- Oracles XA datasource cannot reuse a connection outside a transaction once enlisted in a global transaction and vice-versa -->
<no-tx-separate-pools/>
<!-- corresponding type-mapping in the standardjbosscmp-jdbc.xml (optional) -->
<metadata>
<type-mapping>Oracle9i</type-mapping>
</metadata>
</xa-datasource>
</datasources>File data sources use a Teiid specific JCA connector. You need to create "-ds.xml" file and copy it to the "<jboss-install>/server/<profile>/deploy" directory.
Example 2.1. Template for creating a File based data source
<?xml version="1.0" encoding="UTF-8"?>
<connection-factories>
<no-tx-connection-factory>
<jndi-name>text-source</jndi-name>
<rar-name>teiid-connector-file.rar</rar-name>
<connection-definition>javax.resource.cci.ConnectionFactory</connection-definition>
<config-property name="ParentDirectory">path-to-the-directory-of-data-file</config-property>
</no-tx-connection-factory>
</connection-factories>Web service data sources use a Teiid specific JCA connector. You need to create "-ds.xml" file and copy it to the "<jboss-install>/server/<profile>/deploy" directory.
Example 2.2. Template for creating a web service based data source
<?xml version="1.0" encoding="UTF-8"?>
<connection-factories>
<no-tx-connection-factory>
<jndi-name>somewhere-ws-source</jndi-name>
<rar-name>teiid-connector-ws.rar</rar-name>
<connection-definition>javax.resource.cci.ConnectionFactory</connection-definition>
<config-property name="EndPoint">http://somewhere.com</config-property>
</no-tx-connection-factory>
</connection-factories>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 1 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 be http://teiid.org.
See the sections on WS-Security, Logging, etc. for examples of using the CXF configuration file.
See the CXF documentation for all possible configuration options.
The CXF configuration is currently only applicable to non-binary web service calls.
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 specifing only a single port configration to use.
Example 2.3. Example WS-Security enabled data source
<?xml version="1.0" encoding="UTF-8"?>
<connection-factories>
<no-tx-connection-factory>
<jndi-name>somewhere-ws-source</jndi-name>
<rar-name>teiid-connector-ws.rar</rar-name>
<connection-definition>javax.resource.cci.ConnectionFactory</connection-definition>
<config-property name="EndPoint">http://somewhere.com</config-property>
<config-property name="ConfigFile">${jboss.server.home.dir}/server/default/conf/xxx-jbossws-cxf.xml</config-property>
<config-property name="ConfigName">port_x</config-property>
<config-property name="SecurityType">WSSecurity</config-property>
</no-tx-connection-factory>
</connection-factories>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 class="org.apache.cxf.binding.soap.saaj.SAAJOutInterceptor"/>
<ref bean="Timestamp_Request"/>
</jaxws:outInterceptors>
</jaxws:client>
<bean
class="org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor"
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. The configuration may contain other port confiruations with different local names.
For more information on configuring CXF interceptors, please consult the CXF documentation or the JBossWS-CXF documentation.
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.
Example 2.4. Example logging data source
<?xml version="1.0" encoding="UTF-8"?>
<connection-factories>
<no-tx-connection-factory>
<jndi-name>somewhere-ws-source</jndi-name>
<rar-name>teiid-connector-ws.rar</rar-name>
<connection-definition>javax.resource.cci.ConnectionFactory</connection-definition>
<config-property name="EndPoint">http://somewhere.com</config-property>
<config-property name="ConfigFile">${jboss.server.home.dir}/server/default/conf/xxx-jbossws-cxf.xml</config-property>
<config-property name="ConfigName">port_y</config-property>
</no-tx-connection-factory>
</connection-factories>Corresponding xxx-jbossws-cxf.xml
<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. See the CXF documentation for all possible options.
Example 2.5. Example Disabling Hostname Verification
<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>
Salesforce data sources use a Teiid specific JCA connector. You need to create "-ds.xml" file and copy it to the "<jboss-install>/server/<profile>/deploy" directory.
Example 2.6. Template for creating a Salesforce based data source
<?xml version="1.0" encoding="UTF-8"?>
<connection-factories>
<no-tx-connection-factory>
<jndi-name>sf-source</jndi-name>
<rar-name>teiid-connector-salesforce.rar</rar-name>
<connection-definition>javax.resource.cci.ConnectionFactory</connection-definition>
<config-property name="URL">https://test.salesforce.com/services/Soap/u/10.0</config-property>
<config-property name="username">username</config-property>
<config-property name="password">password</config-property>
</no-tx-connection-factory>
</connection-factories>LDAP data sources use a Teiid specific JCA connector. You need to create "-ds.xml" file and copy it to the "<jboss-install>/server/<profile>/deploy" directory.
Example 2.7. Template for creating an LDAP based data source
<?xml version="1.0" encoding="UTF-8"?>
<connection-factories>
<no-tx-connection-factory>
<jndi-name>ldap-source</jndi-name>
<rar-name>teiid-connector-ldap.rar</rar-name>
<connection-definition>javax.resource.cci.ConnectionFactory</connection-definition>
<config-property name="LdapAdminUserDN">cn=x,ou=y,dc=z</config-property>
<config-property name="LdapAdminUserPassword">password</config-property>
<config-property name="LdapUrl">ldap://ldapServer:389</config-property>
</no-tx-connection-factory>
</connection-factories>VDB Versioning is a feature that allows multiple versions of a VDB to be deployed at the same time with additional support to determine which version will be used. When a user connects to Teiid the desired VDB version can be set as a connection property (See the Client Developers Guide). If a specific version is set, then only that VDB may be connected to. If no version is set, then the deployed VDBs are searched for the appropriate version. This feature helps support more fluid migration scenarios.
Setting the version can either be done in the vdb.xml, which is useful for dynamic vdbs, or through a naming convention of the deployment file - vdbname.version.vdb, e.g. marketdata.2.vdb. The deployer is responsible for choosing an appropriate version number. If the version number is same as an existing VDB existing connections to the previous VDB will remain valid and any new connections will be made to the new VDB - note that the new VDB may be able to use cache entries of the previous VDB.
Once deployed a VDB has an updatable property called connection type, which is used to determine what connections can be made to the VDB. The connection type can be one of:
NONE - disallow new connections.
BY_VERSION - the default setting. Allow connections only if the version is specified or if this is the earliest BY_VERSION vdb and there are no vdbs marked as ANY.
ANY - allow connections with or without a version specified.
The connection type may be changed either through the AdminConsole or the AdminAPI.
If only a select few applications are to migrate to the new VDB version, then a freshly deployed VDB would be left as BY_VERSION. This ensures that only applications that know the new version may use it.
If only a select few applications are to remain on the current VDB version, then their connection settings would need to be updated to reference the current VDB by its version. Then the newly deployed vdb would have its connection type set to ANY, which allows all new connections to be made against the newer version. If a rollback is needed in this scenario, then the newly deployed vdb would have its connection type set to NONE or BY_VERSION accordingly.
VDBs from prior release contain an older configuration file version that is no longer supported. You can use the migration utility (bin/migrate.sh or bin/migrate.bat) supplied with the AdminShell download to update these VDBs for use with Teiid 7. Note - XML and File based sources from previous releases have changed, and require manual changes to the VDB.