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>/standalone/deployments" directory. The, create a empty marker file with same name as the VDB with extension ".dodeploy" in the same directory. For eample, if your vdb name is "enterprise.vdb", then marker file name must be "enterprise.vdb.dodeploy". 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.
This only works in the Standalone mode. For domain mode, you can use any other available methods.
Use the admin web console 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.
JBoss AS provides command line interface (CLI) for doing any kind of administrative task. Execute "bin/jboss-admin.sh --connect" command and run
deploy [--all-server-groups] /path/to/my.vdb
to deploy the VDB. Note that in domain mode, you need to either select a perticular "server-group" or all available server groups are deployment options. Check out CLI documentation for more general usage of the CLI.
Teiid provides a groovy based AdminShell scripting tool, which can be used to deploy a VDB. Check out the "deploy" method. Consult the AdminShell documentation for more information. Note that using the AdminShell scripting, you can automate deployment of artifacts in your environment. When using AdminShell, in domain mode, the VDB is deployed to all the servers.
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. When using Admin API, in domain mode, the VDB is deployed to all the servers.
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 data from Oracle RDBMS 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 sources, other supported data sources have a corresponding JCA connector (.rar) files in "<jboss-install>/standalone/deployments"" directory. Either directly edit the standalone-teiid.xml or use CLI or Admin API to create the required data sources by the VDB. Example configurations are provided for all the sources in "<jboss-install>/docs/teiid/datasources" directory. Note that in the domain mode, you must either use CLI or admin-console or AdminShell to configure.
Some data sources 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 database vendor. Typically only the client JDBC jar and the settings like connection url and user credentails change.
There are 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 AS7 is described here.
Copy the Oracle JDBC JAR file into "<jboss-install>/standalone/deployments" directory, or use CLI and use "deploy" command to deploy the jar file.
Create a "data source" to the Oracle instance in the JBoss container. This typically is done by using "admin-console" application or CLI applications. You can also use Admin API to create this data source. You can manually copy the following xml fragment under "data source" subsystem in standlone-teiid.xml file
<datasource jndi-name="java:/OracleDS" pool-name="OracleDS" enabled="true" jta="true" use-java-context="true" use-ccm="true"> <connection-url>jdbc:oracle:thin:{host}:1521:orcl</connection-url> <driver>ojdbc6.jar</driver> <pool> <prefill>false</prefill> <use-strict-min>false</use-strict-min> <flush-strategy>FailingConnectionOnly</flush-strategy> </pool> <security> <user-name>{user}</user-name> <password>{password}</password> </security> </datasource>
Template files for different databases can found at {jboss-as}/docs/teiid/datasources directory
If you like create using CLI, you can issue command like
/subsystem=datasources/data-source=oracel-ds:add(jndi-name=java:/OracleDS, pool-name=oracle-ds, driver-name=oracle, connection-url=jdbc:oracle:thin:{host}:1521:orcl,user-name={user}, password={password}) /subsystem=datasources/data-source=oracel-ds:enable
File data sources use a Teiid specific JCA connector. You need to create following XML fragment, and copy it under "resource-adapters" subsystem in standalone.xml file or use the CLI to create connection factory.
Example 2.1. Template for creating a File based data source
<!-- If susbsytem is already defined, only copy the contents under it and edit to suit your needs --> <subsystem xmlns="urn:jboss:domain:resource-adapters:1.0"> <resource-adapters> <resource-adapter> <archive>teiid-connector-file.rar</archive> <transaction-support>NoTransaction</transaction-support> <connection-definitions> <connection-definition class-name="org.teiid.resource.adapter.file.FileManagedConnectionFactory" jndi-name="java:/fileDS" enabled="true" use-java-context="true" pool-name="file-ds"> <!-- Directory where the data files are stored --> <config-property name="ParentDirectory">/home/rareddy/testing/</config-property> <!-- Optional properties --> <!-- Set FileMapping to redirect specific relative paths (case sensitive) to alternative locations. The string value specifies a map in the format key=value(,key=value)* --> <!-- <config-property name="FileMapping">file1.txt=fileX.txt,file2.txt=fileY.txt</config-property> --> <!-- Set AllowParentPaths to false to disallow .. in paths. This prevent requesting files that are not contained in the parent directory --> <config-property name="AllowParentPaths">true</config-property> </connection-definition> </connection-definitions> </resource-adapter> </resource-adapters> </subsystem>
You can use CLI to configure the same, however it is a multi-step process. For domain mode, you must use CLI, or admin-console or AdminShell/Admin API
Web service data sources use a Teiid specific JCA connector. You need to create following XML fragment, and copy it under "resource-adapters" subsystem in standalone.xml file or use the CLI to create connection factory.
Example 2.2. Template for creating a web service based data source
<!-- If susbsytem is already defined, only copy the contents under it and edit to suit your needs --> <subsystem xmlns="urn:jboss:domain:resource-adapters:1.0"> <resource-adapters> <resource-adapter> <archive>teiid-connector-ws.rar</archive> <transaction-support>NoTransaction</transaction-support> <connection-definitions> <connection-definition class-name="org.teiid.resource.adapter.ws.WSManagedConnectionFactory" jndi-name="java:/wsDS" enabled="true" use-java-context="true" pool-name="ws-ds"> <config-property name="EndPoint">http://somewhere.com</config-property> </connection-definition> </connection-definitions> </resource-adapter> </resource-adapters> </subsystem>
You can use CLI to configure the same, however it is a multi-step process. For domain mode, you must use CLI, or admin-console or AdminShell/Admin API
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.
Example 2.3. Sample Spring XML Configuration To Set Timeouts
<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}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, is not configurable. The local name is followed by .http-conduit. It will be based upon the configName setting, with a default value of teiid.
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.4. Example WS-Security enabled data source
<!-- If susbsytem is already defined, only copy the contents under it and edit to suit your needs --> <subsystem xmlns="urn:jboss:domain:resource-adapters:1.0"> <resource-adapters> <resource-adapter> <archive>teiid-connector-ws.rar</archive> <transaction-support>NoTransaction</transaction-support> <connection-definitions> <connection-definition class-name="org.teiid.resource.adapter.ws.WSManagedConnectionFactory" jndi-name="java:/wsDS" enabled="true" use-java-context="true" pool-name="ws-ds"> <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> </connection-definition> </connection-definitions> </resource-adapter> </resource-adapters> </subsystem>
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.5. Example logging data source
<!-- If susbsytem is already defined, only copy the contents under it and edit to suit your needs --> <subsystem xmlns="urn:jboss:domain:resource-adapters:1.0"> <resource-adapters> <resource-adapter> <archive>teiid-connector-ws.rar</archive> <transaction-support>NoTransaction</transaction-support> <connection-definitions> <connection-definition class-name="org.teiid.resource.adapter.ws.WSManagedConnectionFactory" jndi-name="java:/wsDS" enabled="true" use-java-context="true" pool-name="ws-ds"> <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> </connection-definition> </connection-definitions> </resource-adapter> </resource-adapters> </subsystem>
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.6. 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 following XML fragment, and copy it under "resource-adapters" subsystem in standalone.xml file or use the CLI to create connection factory.
Example 2.7. Template for creating a Salesforce based data source
<!-- If susbsytem is already defined, only copy the contents under it and edit to suit your needs --> <subsystem xmlns="urn:jboss:domain:resource-adapters:1.0"> <resource-adapters> <resource-adapter> <archive>teiid-connector-salesforce.rar</archive> <transaction-support>NoTransaction</transaction-support> <connection-definitions> <connection-definition class-name="org.teiid.resource.adapter.salesforce.SalesForceManagedConnectionFactory" jndi-name="java:/sfDS" enabled="true" use-java-context="true" pool-name="sf-ds"> <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> </connection-definition> </connection-definitions> </resource-adapter> </resource-adapters> </subsystem>
You can use CLI to configure the same, however it is a multi-step process. For domain mode, you must use CLI, or admin-console or AdminShell/Admin API
Salesforce 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. The namespace URI for the QName in your config file should be "urn:partner.soap.sforce.com", with configuration name "SforceService". For sample cxf configuration file and details on configuration see Web Service Data Sources
See the CXF documentation for all possible configuration options.
The CXF configuration in Salesforce data source is only used for http bus configuration not for purposes of ws-security, Salesforce has its own security authentication.
LDAP data sources use a Teiid specific JCA connector. You need to create following XML fragment, and copy it under "resource-adapters" subsystem in standalone.xml file or use the CLI to create connection factory.
Example 2.8. Template for creating an LDAP based data source
<!-- If susbsytem is already defined, only copy the contents under it and edit to suit your needs --> <subsystem xmlns="urn:jboss:domain:resource-adapters:1.0"> <resource-adapters> <resource-adapter> <archive>teiid-connector-ldap.rar</archive> <transaction-support>NoTransaction</transaction-support> <connection-definitions> <connection-definition class-name="org.teiid.resource.adapter.ldap.LDAPManagedConnectionFactory" jndi-name="java:/ldapDS" enabled="true" use-java-context="true" pool-name="ldap-ds"> <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> </connection-definition> </connection-definitions> </resource-adapter> </resource-adapters> </subsystem>
You can use CLI to configure the same, however it is a multi-step process. For domain mode, you must use CLI, or admin-console or AdminShell/Admin API
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 there is alreay a VDB name/version that matches the current deployment, then connections to the previous VDB will be terminated and its cache entries will be flushed. Any new connections will then be made to the new 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.