Author: shawkins
Date: 2010-06-25 23:26:50 -0400 (Fri, 25 Jun 2010)
New Revision: 2306
Removed:
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/entitlements.xml
Modified:
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/appendix-unsupported-jdbc.xml
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/jdbc-connection.xml
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/jdbc-extensions.xml
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/jdbc-transactions.xml
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/ssl.xml
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/using-hibernate.xml
trunk/documentation/client-developers-guide/src/main/docbook/en-US/main.xml
Log:
TEIID-1037 refining the client guide
Modified:
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/appendix-unsupported-jdbc.xml
===================================================================
---
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/appendix-unsupported-jdbc.xml 2010-06-25
19:35:24 UTC (rev 2305)
+++
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/appendix-unsupported-jdbc.xml 2010-06-26
03:26:50 UTC (rev 2306)
@@ -14,6 +14,15 @@
then only those forms of the method specified are not supported.</para>
<sect1>
+ <title>ResultSet Limitations</title>
+ <itemizedlist>
+ <listitem><para>TYPE_SCROLL_SENSITIVE is not
supported.</para></listitem>
+ <listitem><para><code>UPDATABLE</code> ResultSets are
not supported.</para></listitem>
+ <listitem><para>Returning multiple ResultSets from Procedure
execution is not supported.</para></listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
<title>Unsupported Classes and Methods in "java.sql"</title>
<table frame='all'>
<title>Connection Properties</title>
Deleted:
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/entitlements.xml
===================================================================
---
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/entitlements.xml 2010-06-25
19:35:24 UTC (rev 2305)
+++
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/entitlements.xml 2010-06-26
03:26:50 UTC (rev 2306)
@@ -1,127 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd">
-%CustomDTD;
-]>
-<chapter id="entitlements">
- <title>Entitlements/Data Roles</title>
- <para>Entitlements, also called as Data Roles, are a set of rules and
permissions that are defined
- per VDB that dictate data access (create, read, update, delete) permissions for the
schema defined
- by the VDB. The use of entitlements are controlled system wide with the property in
-
<code><jboss-install>/server/<profile>/deploy/teiid/teiid-jboss-beans.xml</code>
file
- in bean configuration section of <code>RuntimeEngineDeployer</code> with
property <code>useEntitlements</code>.</para>
-
- <para>Once the entitlements are enabled, the access permissions defined in each
VDB will then be enforced by the Teiid Server.
- To process an <code>INSERT</code> statement, the user account requires
the following access rights:</para>
- <orderedlist>
- <listitem> <para><code>CREATE</code> - on the Table being
inserted into.</para></listitem>
- <listitem> <para><code>CREATE</code> - on every column
being inserted on that Table.</para></listitem>
- </orderedlist>
-
- <para>To process an <code>UPDATE</code> statement, the user account
requires the following access rights:</para>
- <orderedlist>
- <listitem> <para><code>UPDATE</code> - on the Table being
updated.</para></listitem>
- <listitem> <para><code>UPDATE</code> - on every column
being updated on that Table.</para></listitem>
- <listitem> <para><code>READ</code> - on every column
referenced in the criteria.</para></listitem>
- </orderedlist>
-
- <para>To process a <code>DELETE</code> statement, the user account
requires the following access rights:</para>
- <orderedlist>
- <listitem> <para><code>DELETE</code> - on the Table being
deleted.</para></listitem>
- <listitem> <para><code>READ</code> - on every column
referenced in the criteria.</para></listitem>
- </orderedlist>
-
- <para>The data roles are defined inside the
<code>META-INF/vdb.xml</code> file, f you used Designer to build your VDB.
- They defined inside the <code>-vdb.xml</code> file defined if you are
using the Dynamic VDBs. The below example will show
- a sample "vdb.xml" file with few simple data rules.</para>
-
- <para>For example, if a VDB schema defined a table below in its model files
named "modelName"</para>
-
- <programlisting><![CDATA[
- modelName.TableA (
- column1 VARCHAR,
- column2 INT
- )
- ]]></programlisting>
-
- <para>and has three (3) users "UserA", "UserB",
"UserC" with following permissions</para>
- <orderedlist>
- <listitem><para>UserA has privileges to read, write access to TableA, but
can not delete.</para></listitem>
- <listitem><para>UserB has no privileges that allow access to
TableA</para></listitem>
- <listitem><para>UserC has privileges that only allow read access to
TableA.column1</para></listitem>
- </orderedlist>
-
- <para>Then the resulting "vdb.xml" file will look like
below.</para>
-
- <programlisting><![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
-<vdb name="sample" version="1">
-
- <model name="modelName">
- <source name="source-name" translator-name="oracle"
connection-jndi-name="java:myDS" />
- </model>
-
- <data-policy name="policy-1">
- <description>Allow all, except Delete</description>
-
- <permission>
- <resource-name>modelName.TableA</resource-name>
- <allow-create />
- <allow-read />
- <allow-update />
- </permission>
-
- <permission>
- <resource-name>modelName.TableA.colum1</resource-name>
- <allow-create />
- <allow-read />
- <allow-update />
- </permission>
-
- <permission>
- <resource-name>modelName.TableA.column2</resource-name>
- <allow-create />
- <allow-read />
- <allow-update />
- </permission>
-
- <mapped-role-name>role1</mapped-role-name>
-
- </data-policy>
-
- <data-policy name="policy-2">
- <description>Allow read only</description>
-
- <permission>
- <resource-name>modelName.TableA</resource-name>
- <allow-read />
- </permission>
-
- <permission>
- <resource-name>modelName.TableA.colum1</resource-name>
- <allow-read />
- </permission>
-
- <mapped-role-name>role2</mapped-role-name>
- </data-policy>
-</vdb>
-
- ]]></programlisting>
-
- <para>The above XML defined two data policies, "policy-1" which allows
everything except delete on the table, "policy-2" that
- allows only read operation on the table. The "mapped-role-name" defines the
"role" to whom these policies are applicable. Each data-policy
- must define a "role" to be enforced by the Teiid Server.</para>
-
- <para>
- The above xml assumes that "UserA" has "role1" role and
"UserC" has "role2" role and
- "UserB" does not have either "role1" or "role2"
roles.</para>
-
- <para>For assigning the roles to your users, in the JBoss AS,
- check out the instructions for the selected Login Module. Check "Admin
Guide" for configuring Login Modules.</para>
-
- <para>"vdb.xml" file is checked against the schema file
<code>vdb-deployer.xsd</code>, check the documents sections of the Teiid kit
- to find a copy of the schema file.</para>
-
- <note><para>Currently there is no GUI tooling support in the Designer or
any other management tool to create this data roles
- permissions xml, however this is in our roadmap for future releases to
provide.</para></note>
-</chapter>
\ No newline at end of file
Modified:
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/jdbc-connection.xml
===================================================================
---
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/jdbc-connection.xml 2010-06-25
19:35:24 UTC (rev 2305)
+++
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/jdbc-connection.xml 2010-06-26
03:26:50 UTC (rev 2306)
@@ -6,20 +6,18 @@
<chapter id="teiid_connection">
<title>Connecting to Teiid Server</title>
- <para>The Teiid JDBC API provides Java Database Connectivity (JDBC) access any
Virtual Database (VDB) that
- is deployed in the Teiid Server.
- The Teiid JDBC API supports the JDBC 4.0 specification; however, it is not fully JDBC
Compliant.
- It does not support advanced features such as updatable result sets or SQL3 data
types. </para>
+ <para>The Teiid JDBC API provides Java Database Connectivity (JDBC) access to
any Virtual Database (VDB) deployed on a Teiid Server.
+ The Teiid JDBC API is compatible with the JDBC 4.0 specification; however, it does
not fully support all <link
linkend="unsupported_jdbc">methods</link>.
+ Advanced features, such as updatable result sets or SQL3 data types, are not
supported. </para>
- <para>Java client applications connecting to a Teiid Server will need to use
Java 1.6 JDK. Previous versions of Java is
- is not supported.</para>
+ <para>Java client applications connecting to a Teiid Server will need to use
Java 1.6 JDK. Previous versions of Java are not supported.</para>
<para>Before you can connect to the Teiid Server using the Teiid JDBC API,
please do following tasks first.</para>
<orderedlist>
- <listitem> <para>Install the Teiid Server. Check "Admin
Guide" for instructions. </para> </listitem>
+ <listitem> <para>Install the Teiid Server. See the "Admin
Guide" for instructions. </para> </listitem>
<listitem> <para>Build a Virtual Database (VDB). You can either build
a "Dynamic VDB" (Designer not required),
- or you can use Eclipse based GUI tool <ulink
url="http://www.jboss.org/teiiddesigner.html">Designer</u...;.
- Check "Reference Guide" for instructions on how to build a VDB. If you
do not know what VDB is, then start with this
+ or you can use the Eclipse based GUI tool <ulink
url="http://www.jboss.org/teiiddesigner.html">Designer</u...;.
+ Check the "Reference Guide" for instructions on how to build a VDB. If
you do not know what VDB is, then start with this
<ulink
url="http://www.jboss.org/teiid/basics/virtualdatabases.html"&g...
</listitem>
<listitem> <para>Deploy the VDB into Teiid Server. Check "Admin
Guide" for instructions. </para> </listitem>
<listitem> <para>Start the Teiid Server (JBoss AS), if it is not
already running.</para> </listitem>
@@ -27,211 +25,47 @@
<para>Now that you have the VDB deployed in Teiid Server, client applications
can connect to Teiid Server and issue SQL queries against deployed VDB using
Teiid's JDBC API. If you are new to JDBC, learn about
- <ulink
url="http://java.sun.com/docs/books/tutorial/jdbc/index.html"&g...
here. Teiid kit ships with
- <code>teiid-{version}-client.jar</code> in the
<code>"jboss-install/server/<profile>/lib"</code>
directory. This JAR file
- contains Teiid JDBC Driver and DataSource classes. Add this JAR to your Java client
application's classpath.
- </para>
+ <ulink
url="http://java.sun.com/docs/books/tutorial/jdbc/index.html"&g...
here. Teiid ships with
+ <code>teiid-&versionNumber;-client.jar</code> in the
<code>"jboss-install/server/<profile>/lib"</code>
directory.
- <orderedlist numeration="arabic">
- <listitem> <para><code>TeiidDriver</code> - JDBC
connections using
+ <itemizedlist>
+ <para>Main classes in the client JAR:</para>
+ <listitem> <para><code>org.teiid.jdbc.TeiidDriver</code>
- allows JDBC connections using the
<ulink
url="http://java.sun.com/javase/6/docs/api/java/sql/DriverManager.ht...
class.</para> </listitem>
- <listitem> <para><code>TeiidDatasource</code> - JDBC
connections using
- <ulink
url="http://java.sun.com/javase/6/docs/api/javax/sql/DataSource.html...
class. You can use this to create JDBC XA connections. </para> </listitem>
- </orderedlist>
+ <listitem>
<para><code>org.teiid.jdbc.TeiidDatasource</code> - allows JDBC
connections using the
+ <ulink
url="http://java.sun.com/javase/6/docs/api/javax/sql/DataSource.html...
or <ulink
url="http://java.sun.com/javase/6/docs/api/javax/sql/XADataSource.ht...
class. You should use this class to create managed or XA connections.</para>
</listitem>
+ </itemizedlist>
+ </para>
+ <para>Once you have established a connection with the Teiid Server, you can use
standard JDBC API classes, like
+ DatabaseMetadata and ResultSetMetadata, to interrogate metadata and Statement
classes to execute queries.</para>
+
<sect1 id="driver_connection">
- <title>Driver Based Connection</title>
- <para>Add the above jar file in your application's class path and use
<code>org.teiid.jdbc.TeiidDriver</code> as the driver class.
- Use the following URL format for JDBC connections:
- </para>
+ <title>Driver Connection</title>
+ <para>Use <code>org.teiid.jdbc.TeiidDriver</code> as the driver
class.</para>
-
<para><emphasis>jdbc:teiid:<vdb-name>@mm[s]://<host>:<port>;[prop-name=prop-value;]*</emphasis></para>
+ <para>Use the following URL format for JDBC
connections:<synopsis>jdbc:teiid:<vdb-name>@mm[s]://<host>:<port>;[prop-name=prop-value;]*</synopsis></para>
- <para>Where</para>
+ <para>URL Components</para>
<orderedlist>
<listitem><para><vdb-name> - Name of the VDB you
are connecting to</para></listitem>
- <listitem><para>mm - defines Teiid JDBC protocol, mms defines a
secure channel (see how to turn on <link
linkend="ssl">SSL</link>)</para></listitem>
+ <listitem><para>mm - defines Teiid JDBC protocol, mms defines a
secure channel (see the <link linkend="ssl">SSL chapter</link> for
more)</para></listitem>
<listitem><para><host> - defines the server where
the Teiid Server is installed</para></listitem>
<listitem><para><port> - defines the port on which
the Teiid Server is listening for incoming JDBC
connections.</para></listitem>
<listitem><para>[prop-name=prop-value] - additionally you can
supply any number of name value pairs separated by semi-colon
- [;], further refining the connection. All supported URL properties are
defined <link
linkend="connection_properties">here</link>.</para></listitem>
+ [;]. All supported URL properties are defined in the <link
linkend="connection_properties">connection properties section</link>.
Property values should be URL encoded if they contain reserved characters, e.g.
('?', '=', ';', etc.)</para></listitem>
</orderedlist>
-
- <para>Sample Code:</para>
- <programlisting><![CDATA[
- public class TeiidClient {
- public Connection getConnection(String user, String password) throws
Exception {
- String url =
"jdbc:teiid:myVDB@mm://localhost:31000;ApplicationName=myApp";
- Class.forName("org.teiid.jdbc.TeiidDriver");
- return DriverManager.getConnection(url, user, password);
- }
- }
- ]]></programlisting>
-
- </sect1>
-
- <sect1 id="datasource_connection">
- <title>Datasource Based Connection</title>
- <para>To use a data source based connection use
<code>org.teiid.jdbc.TeiidDataSource</code> as the data source class.
- If your JDBC connection needs to participate in an XA transaction, you must use
the
- data source connection. Teiid DataSource class is also Serializable, so it
possible for it to be used with
- JNDI naming services.</para>
- <para>Sample Code:</para>
- <programlisting><![CDATA[
- public class TeiidClient {
- public Connection getConnection(String user, String password) throws
Exception {
- TeiidDataSource ds = new TeiidDataSource();
- ds.setUser(user);
- ds.setPassword(password);
- ds.setServerName("localhost");
- ds.setPortNumber(31000);
- ds.setDatabaseName("myVDB");
- return ds.getConnection();
- }
- }
- ]]></programlisting>
-
- <para>All the Teiid Data Source supported properties are defined <link
linkend="connection_properties">here</link>.</para>
-
- <note><para>Teiid supports the XA protocol, if all sources that Teiid
is integrating
- also support XA and are configured as XA data sources. If one or more sources are
not XA capable, they can be
- marked as read-only and still participate in an XA transaction with the remaining
sources.</para>
- </note>
- </sect1>
-
- <sect1 id="ds_in_jbossas">
- <title>As Data Source in JBoss AS</title>
- <para>Teiid can be configured as a JDBC data source in the JBoss
Application Server and can be accessed
- from the JNDI for your JEE application. Deploying Teiid as data source in JBoss
AS is exactly same as
- deploying any other RDBMS resources like Oracle or DB2. </para>
-
- <para>Defining as data source is not limited to
- JBoss AS, you can also deploy as data source in Glassfish, Tomcat, Websphere,
Weblogic etc servers, however their
- configuration files are different than JBoss AS. Consult the respective
documentation of the environment
- in which you are deploying.</para>
- <orderedlist numeration="arabic">
- <listitem><para>Copy the
<code>teiid-${version}-client.jar</code> into
- <code><jboss-install>/server/default/lib</code>
directory.</para></listitem>
- <listitem><para>Create a "teiid-ds.xml" file in
<code><jboss-install>/server/<profile>/deploy</code>
- directory. Based on the type of deployment the contents of the deployment
file will look like the below
- code fragment.</para></listitem>
- </orderedlist>
- <sect2 id="as_xa_connection">
- <title>DataSource based connection</title>
- <para>The below XML code sample will create an XA data source in the
JBoss AS using the
- Teiid DataSource class
<code>org.teiid.jdbc.TeiidDataSource</code>. Make sure
- you supply the correct DatabaseName, ServerName, Port number and credentials
that are specific
- to your deployment environment. Then deploy this file into the JBoss AS and
access the above data source from
- the JNDI in your JEE application with the specified JNDI name.</para>
-
- <programlisting><![CDATA[
- <datasources>
- <xa-datasource>
- <jndi-name>TEIID-DS</jndi-name>
-
<xa-datasource-class>org.teiid.jdbc.TeiidDataSource</xa-datasource-class>
- <xa-datasource-property
name="DatabaseName">myVDB</xa-datasource-property>
- <xa-datasource-property
name="serverName">localhost</xa-datasource-property>
- <xa-datasource-property
name="portNumber">31000</xa-datasource-property>
- <xa-datasource-property
name="user">admin</xa-datasource-property>
- <xa-datasource-property
name="password">password</xa-datasource-property>
- <track-connection-by-tx>true</track-connection-by-tx>
- <isSameRM-override-value>false</isSameRM-override-value>
- <no-tx-separate-pools />
-
- <!-- pool and other JBoss datasource properties -->
- <min-pool-size>5</min-pool-size>
- <max-pool-size>10</max-pool-size>
- </xa-datasource>
- </datasources>
- ]]></programlisting>
- </sect2>
- <sect2 id="as_driver_connection">
- <title>Driver based connection</title>
- <para>You can also use Teiid's JDBC driver class
<code>org.teiid.jdbc.TeiidDriver</code> to create a data source</para>
- <programlisting><![CDATA[
- <datasources>
- <local-tx-datasource>
- <jndi-name>TEIID-DS</jndi-name>
-
<connection-url>jdbc:metamatrix:myVDB@mm://localhost:31000</connection-url>
- <driver-class>org.teiid.jdbc.TeiidDriver</driver-class>
- <user-name>admin</user-name>
- <password>teiid</password>
-
- <!-- pool and other JBoss datasource properties -->
- <min-pool-size>5</min-pool-size>
- <max-pool-size>10</max-pool-size>
- </local-tx-datasource>
- </datasources>
- ]]></programlisting>
- </sect2>
- <sect2 id="local_connection">
- <title>Local JDBC Connection</title>
- <para>If you are deploying your client application on the same JBoss AS
instance as the Teiid runtime is installed, then
- there is no reason for your client application to open socket based JDBC
connection, as the
- both applications are running in the same Java VM process.
- You can use slightly modified data source configuration to make the
"local" connection, that does not involve socket based
- communication. Here is an example:</para>
- <programlisting><![CDATA[
- <datasources>
- <xa-datasource>
- <jndi-name>TEIID-DS</jndi-name>
-
<xa-datasource-class>org.teiid.jdbc.TeiidDataSource</xa-datasource-class>
- <xa-datasource-property
name="DatabaseName">myVDB</xa-datasource-property>
- <xa-datasource-property
name="user">admin</xa-datasource-property>
- <xa-datasource-property
name="password">password</xa-datasource-property>
- <track-connection-by-tx>true</track-connection-by-tx>
- <isSameRM-override-value>false</isSameRM-override-value>
- <no-tx-separate-pools />
-
- <!-- pool and other JBoss datasource properties -->
- <min-pool-size>5</min-pool-size>
- <max-pool-size>10</max-pool-size>
- </xa-datasource>
- </datasources>
- ]]></programlisting>
- <para>In the absense of the "ServerName" and
"PortNumber", the JDBC API will lookup a local Teiid runtime in
- the same VM.</para>
- </sect2>
-
- </sect1>
-
- <sect1>
- <title>Using Multiple Hosts</title>
- <para>When Teiid Server is deployed on multiple servers for scalbility,
then your application that using
- Teiid JDBC API can automatically use all Teiid Servers in that group. To enable
this feature the client application needs
- to specify all the Teiid Servers connection information (host name and port
number) on the URL connection string. During the
- connection and authentication, client will randomly pick any one the Teiid server
from the list and will have session
- established with that server. In the case of failure of the connected server, the
client will try to automatically failover
- to other available servers, if the "autoFailover" connection property
is set to "true". Here is example URL connection string</para>
-
- <programlisting><![CDATA[
- jdbc:teiid:<vdb-name>@mm://host1:31000, host1:31001,
host2:31000;version=2
- ]]></programlisting>
-
- <para>Currently when the fail over happens, the user is re-authenticated
with the new server. The clustering
- feature coming up in the Teiid 7.1 release will define how the transparent
session fail over will occur with out the
- re-authentication.</para>
-
- <para>You can also use this feature to distribute the query load among
various avaialble Teiid Servers available.
- Load balancing happens automatically, when you are using a data source along with
connection pooling. Each time a connection is
- grabbed from the pool, it will randomly select a Teiid Server to distribute the
load. Note, that load balacing feature
- is not avaialble if you are using Teiid Driver to make your
connection.</para>
-
- <para>If you are using DataSource to connect to Teiid Server, use
"AlternateServers" property/method to define the failover servers.
- Check out the Javadoc on the format of the string.</para>
- </sect1>
-
- <sect1 id="connection_properties">
- <title>JDBC Connection Properties</title>
+ <sect2 id="connection_properties">
+ <title>URL Connection Properties</title>
<para>The following table shows all the supported connection properties
that can used with Teiid
JDBC Driver URL connection string, or on the Teiid JDBC Data Source
class.</para>
<table frame='all'>
<title>Connection Properties</title>
<tgroup cols='3' align='left' colsep='1'
rowsep='1'>
- <colspec colname='c1' colwidth="1*" />
- <colspec colname='c2' colwidth="1*" />
+ <colspec colname='c1' colwidth=".75*" />
+ <colspec colname='c2' colwidth=".5*" />
<colspec colname='c3' colwidth="2*" />
<thead>
<row>
@@ -257,18 +91,18 @@
<entry>
<code>int</code>
</entry>
- <entry>Size of the resultset; The default size if 500.
<=0 indicates that the value is not set</entry>
+ <entry>Size of the resultset; The default size if 500.
<=0 indicates that the default should be used.</entry>
</row>
<row>
<entry>
<code>partialResultsMode</code>
</entry>
<entry>
- <code>String</code>
+ <code>boolean</code>
</entry>
- <entry>Enable/disable support partial results mode. Default
is "off". Allowed values are "on" or "off"</entry>
+ <entry>Enable/disable support partial results mode.
Default false. See the <link linkend="partial_results">partial
results</link> section.</entry>
</row>
- <row>
+ <row id="auto_commit_txn">
<entry>
<code>autoCommitTxn</code>
</entry>
@@ -279,11 +113,12 @@
This determines how a executed command needs to be
transactionally wrapped inside the
Teiid engine to maintain the data integrity.
- <orderedlist>
+ <itemizedlist>
<listitem><para>ON - Always wrap command
in distributed transaction</para></listitem>
<listitem><para>OFF - Never wrap command
in distributed transaction</para></listitem>
<listitem><para>DETECT (default)- If the
executed command is spanning more than one source it automatically uses distributed
transaction.</para></listitem>
- </orderedlist>
+ </itemizedlist>
+ <link
linkend="jdbc_transactions">Transactions with JDBC</link> for more
information.
</entry>
</row>
<row>
@@ -293,7 +128,7 @@
<entry>
<code>boolean</code>
</entry>
- <entry> If "true", the autoCommit setting, commit
and rollback will be ignored for local transactions.</entry>
+ <entry>If "true", the autoCommit setting, commit
and rollback will be ignored for local transactions. Default false.</entry>
</row>
<row>
<entry>
@@ -333,59 +168,70 @@
</entry>
<entry>Version number of the VDB</entry>
</row>
-
- <row>
+ <row>
<entry>
<code>resultSetCacheMode</code>
</entry>
<entry>
<code>boolean</code>
</entry>
- <entry>ResultSet caching is turned on/off; Valid values are
true|false</entry>
+ <entry>ResultSet caching is turned on/off. Default
false.</entry>
</row>
<row>
<entry>
- <code>SHOWPLAN</code>
+ <code>autoFailover</code>
</entry>
<entry>
- <code>String</code>
+ <code>boolean</code>
</entry>
- <entry>Can be one of ON|OFF|DEBUG</entry>
- </row>
+ <entry>If true, will automatically select a new server
instance after a communication exception. Default false.
+ This is typically not needed when connections are managed, as the
connection can be purged from the pool.</entry>
+ </row>
<row>
<entry>
- <code>NoExec</code>
+ <code>SHOWPLAN</code>
</entry>
<entry>
- <code>boolean</code>
+ <code>String</code>
</entry>
- <entry>true|false</entry>
- </row>
+ <entry>(typically not set as a connection property) Can be
ON|OFF|DEBUG; ON returns the query plan along with the results and DEBUG additionally
prints the query planner debug information in the log and returns it with the results.
Both the plan and the log are available through JDBC API extensions. Default
OFF.</entry>
+ </row>
<row>
<entry>
- <code>autoFailover</code>
+ <code>NoExec</code>
</entry>
<entry>
- <code>boolean</code>
+ <code>String</code>
</entry>
- <entry>If true, will automatically select a new server
instance after a communication exception.</entry>
+ <entry>(typically not set as a connection property) Can be
ON|OFF; ON prevents query execution, but parsing and planning will still occur. Default
OFF.</entry>
</row>
+
</tbody>
</tgroup>
- </table>
-
- <para>All the above properties have "set" methods on the
<code>org.teiid.jdbc.TeiidDataSource</code>.
- Some of the the properties that are assumed from the URL string have addtional
"set" methods, those proeprties are described in the
- following table.</para>
-
- <table frame='all'>
+ </table>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="datasource_connection">
+ <title>Datasource Connection</title>
+ <para>To use a data source based connection, use
<code>org.teiid.jdbc.TeiidDataSource</code> as the data source class.
+ The <code>TeiidDataSource</code> is also an XADatasource. Teiid
DataSource class is also Serializable, so it possible for it to be used with
+ JNDI naming services.</para>
+
+ <note><para>Teiid supports the XA protocol, XA transactions will be
extended to Teiid sources that also support XA.</para></note>
+
+ <para>All the properties (except for version, which is known on
TeiidDataSource as DatabaseVersion) defined in the <link
linkend="connection_properties">connection properties</link>have
corresponding "set" methods on the
<code>org.teiid.jdbc.TeiidDataSource</code>.
+ Properties that are assumed from the URL string have addtional "set"
methods, which are described in the following table.</para>
+
+ <table id="ds_methods" frame='all'>
<title>Datasource Properties</title>
<tgroup cols='3' align='left' colsep='1'
rowsep='1'>
- <colspec colname='c1' colwidth="1*" />
- <colspec colname='c2' colwidth="1*" />
+ <colspec colname='c1' colwidth="1.25*" />
+ <colspec colname='c2' colwidth=".7*" />
<colspec colname='c3' colwidth="2*" />
<thead>
<row>
@@ -413,6 +259,24 @@
</entry>
<entry>Server where the Teiid runtime
installed</entry>
</row>
+ <!-- <row>
+ <entry>
+ <code>AlternateServers</code>
+ </entry>
+ <entry>
+ <code>String</code>
+ </entry>
+ <entry>Optional , delimited list of host:port entries. See
the <link linkend="multiple_hosts">multiple hosts</link> section for
more information.</entry>
+ </row> -->
+ <row>
+ <entry>
+ <code>AdditionalProperties</code>
+ </entry>
+ <entry>
+ <code>String</code>
+ </entry>
+ <entry>Optional setting of properties that has the same
format as the property string in a connection URL.</entry>
+ </row>
<row>
<entry>
<code>PortNumber</code>
@@ -429,7 +293,7 @@
<entry>
<code>boolean</code>
</entry>
- <entry>Secure connection. Flag to indicate to use SSH based
connection between client and server</entry>
+ <entry>Secure connection. Flag to indicate to use SSL (mms)
based connection between client and server</entry>
</row>
<row>
<entry>
@@ -451,10 +315,165 @@
</row>
</tbody>
</tgroup>
- </table>
+ </table>
+ </sect1>
+
+ <sect1>
+ <title>Standalone Application</title>
+ <para>To use either Driver or DataSource based connections, add the client JAR to
your Java client application's classpath. See the simple client example in the kit
for a full Java sample of the following.</para>
+
+ <sect2 id="sa_driver_connection">
+ <title>Driver Connection</title>
+
+ <para>Sample Code:</para>
+ <programlisting><![CDATA[public class TeiidClient {
+ public Connection getConnection(String user, String password) throws Exception {
+ String url =
"jdbc:teiid:myVDB@mm://localhost:31000;ApplicationName=myApp";
+ return DriverManager.getConnection(url, user, password);
+ }
+}]]></programlisting>
+
+ </sect2>
+
+ <sect2 id="sa_datasource_connection">
+ <title>Datasource Connection</title>
+
+ <para>Sample Code:</para>
+ <programlisting><![CDATA[public class TeiidClient {
+ public Connection getConnection(String user, String password) throws Exception {
+ TeiidDataSource ds = new TeiidDataSource();
+ ds.setUser(user);
+ ds.setPassword(password);
+ ds.setServerName("localhost");
+ ds.setPortNumber(31000);
+ ds.setDatabaseName("myVDB");
+ return ds.getConnection();
+ }
+}]]></programlisting>
+
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="ds_in_jbossas">
+ <title>JBoss AS Data Source</title>
+ <para>Teiid can be configured as a JDBC data source in the JBoss
Application Server to be accessed
+ from JNDI or injected into your JEE applications. Deploying Teiid as data source
in JBoss AS is exactly same as
+ deploying any other RDBMS resources like Oracle or DB2.</para>
- <para>Once you have established a connection with the Teiid Server, you can
use any standard JDBC API like
- DatabaseMetadata and ResultSetMetadata classes to interrogate metadata of the
deployed VDB. You can also use
- data processing classes and objects and process the results. </para>
+ <para>Defining as data source is not limited to
+ JBoss AS, you can also deploy as data source in Glassfish, Tomcat, Websphere,
Weblogic etc servers, however their
+ configuration files are different than JBoss AS. Consult the respective
documentation of the environment
+ in which you are deploying.</para>
+
+ <orderedlist numeration="arabic">
+ <para>Installation Steps</para>
+ <listitem><para>If Teiid is not installed in the AS instance,
copy the <code>teiid-&versionNumber;-client.jar</code> into
+
<code><jboss-install>/server/<profile>/lib</code>
directory.</para></listitem>
+ <listitem><para>Create a "<datasource
name>-ds.xml" file in
<code><jboss-install>/server/<profile>/deploy</code>
+ directory. Based on the type of deployment (XA, driver, or local), the
contents of the file will be different. See the following sections for
more.</para></listitem>
+ </orderedlist>
+
+ <para>Tje data source will then be accessable through the JNDI name
specified in the -ds.xml file.</para>
+
+ <sect2 id="as_xa_connection">
+ <title>DataSource Connection</title>
+ <para>Make sure you know the correct DatabaseName, ServerName, Port
number and credentials that are specific
+ to your deployment environment. </para>
+ <example>
+ <title>Sample XADataSource in the JBoss AS using the
+ Teiid DataSource class
<code>org.teiid.jdbc.TeiidDataSource</code></title>
+
+ <programlisting><![CDATA[<datasources>
+ <xa-datasource>
+ <jndi-name>TEIID-DS</jndi-name>
+
<xa-datasource-class>org.teiid.jdbc.TeiidDataSource</xa-datasource-class>
+ <xa-datasource-property
name="DatabaseName">myVDB</xa-datasource-property>
+ <xa-datasource-property
name="serverName">localhost</xa-datasource-property>
+ <xa-datasource-property
name="portNumber">31000</xa-datasource-property>
+ <xa-datasource-property
name="user">admin</xa-datasource-property>
+ <xa-datasource-property
name="password">password</xa-datasource-property>
+ <track-connection-by-tx>true</track-connection-by-tx>
+
+ <isSameRM-override-value>false</isSameRM-override-value>
+ <no-tx-separate-pools />
+
+ <!-- pool and other JBoss datasource properties -->
+ <check-valid-connection-sql>SELECT 1</check-valid-connection-sql>
+ <min-pool-size>5</min-pool-size>
+ <max-pool-size>10</max-pool-size>
+ </xa-datasource>
+</datasources>]]></programlisting> </example>
+ </sect2>
+ <sect2 id="as_driver_connection">
+ <title>Driver based connection</title>
+ <para>You can also use Teiid's JDBC driver class
<code>org.teiid.jdbc.TeiidDriver</code> to create a data source</para>
+ <programlisting><![CDATA[<datasources>
+ <local-tx-datasource>
+ <jndi-name>TEIID-DS</jndi-name>
+
<connection-url>jdbc:metamatrix:myVDB@mm://localhost:31000</connection-url>
+ <driver-class>org.teiid.jdbc.TeiidDriver</driver-class>
+ <user-name>admin</user-name>
+ <password>teiid</password>
+
+ <!-- pool and other JBoss datasource properties -->
+ <check-valid-connection-sql>SELECT 1</check-valid-connection-sql>
+ <min-pool-size>5</min-pool-size>
+ <max-pool-size>10</max-pool-size>
+ </local-tx-datasource>
+</datasources>]]></programlisting>
+ </sect2>
+ <sect2 id="local_connection">
+ <title>Local JDBC Connection</title>
+ <para>If you are deploying your client application on the same JBoss AS
instance as the Teiid runtime is installed, then
+ there is no reason for your client application to open socket based JDBC
connection.
+ You can use slightly modified data source configuration to make a
"local" connection, where the JDBC API will lookup a local Teiid runtime in the
same VM.</para>
+ <example>
+ <title>Local data source</title>
+ <programlisting><![CDATA[<datasources>
+ <xa-datasource>
+ <jndi-name>TEIID-DS</jndi-name>
+
<xa-datasource-class>org.teiid.jdbc.TeiidDataSource</xa-datasource-class>
+ <xa-datasource-property
name="DatabaseName">myVDB</xa-datasource-property>
+ <xa-datasource-property
name="user">admin</xa-datasource-property>
+ <xa-datasource-property
name="password">password</xa-datasource-property>
+ <track-connection-by-tx>true</track-connection-by-tx>
+ <isSameRM-override-value>false</isSameRM-override-value>
+ <no-tx-separate-pools />
+
+ <!-- pool and other JBoss datasource properties -->
+ <check-valid-connection-sql>SELECT 1</check-valid-connection-sql>
+ <min-pool-size>5</min-pool-size>
+ <max-pool-size>10</max-pool-size>
+ </xa-datasource>
+</datasources>]]></programlisting>
+</example>
+ <para>This is essentially the same as the XA configuration, but
"ServerName" and "PortNumber" are not specified.</para>
+ </sect2>
+
</sect1>
+
+ <!-- <sect1 id="multiple_hosts">
+ <title>Using Multiple Hosts</title>
+ <para>When Teiid Server is deployed on multiple servers for scalbility,
then your application that using
+ Teiid JDBC API can automatically use all Teiid Servers in that group. To enable
this feature the client needs
+ to specify multiple host name and port number combinations on the URL connection
string. The client will randomly pick any one the Teiid server from the list and will have
session
+ established with that server. If the "autoFailover" connection
property is set to "true", a failure with the connected server will cause the
client to automatically failover
+ to other available servers. Even if autoFailover is not set, when using a
managed DataSource based connection, the connection will randomly select a new server
instance when it is returned to the pool.</para>
+
+ <example><title>Example URL connection
string</title><programlisting><![CDATA[jdbc:teiid:<vdb-name>@mm://host1:31000,
host1:31001, host2:31000;version=2]]></programlisting></example>
+
+ <para>Currently when the fail over happens, the user is re-authenticated
with the new server. The clustering
+ feature coming up in the Teiid 7.1 release will define how the transparent
session fail over will occur with out the
+ re-authentication.</para>
+
+ <para>You can also use this feature to distribute the query load among
various avaialble Teiid Servers available.
+ Load balancing happens automatically, when you are using a data source along with
connection pooling. Each time a connection is
+ grabbed from the pool, it will randomly select a Teiid Server to distribute the
load. Note, that load balacing feature
+ is not avaialble if you are using Teiid Driver to make your
connection.</para>
+
+ <para>If you are using DataSource to connect to Teiid Server, use
"AlternateServers" property/method to define the failover servers.
+ Check out the Javadoc on the format of the string.</para>
+ </sect1> -->
+
</chapter>
\ No newline at end of file
Modified:
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/jdbc-extensions.xml
===================================================================
---
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/jdbc-extensions.xml 2010-06-25
19:35:24 UTC (rev 2305)
+++
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/jdbc-extensions.xml 2010-06-26
03:26:50 UTC (rev 2306)
@@ -6,12 +6,11 @@
<chapter id="jdbc_extensions">
<title>Teiid extensions to the JDBC API</title>
- <sect1>
+ <sect1 id="statement_extensions">
<title>Statement Extensions</title>
- <para>Teiid provides some extensions to the JDBC statement interface. The
Teiid Statement extension interface
- is defined by <code>org.teiid.jdbc.TeiidStatement</code>. To use the
extension interface, simply
- cast or unwap the statement returned by the Connection to the extension
interface.
- The following methods are provided on the extension interface:</para>
+ <para>The Teiid statement extension interface,
+ <code>org.teiid.jdbc.TeiidStatement</code>, provides functionality
beyond the JDBC standard. To use the extension interface, simply
+ cast or unwap the statement returned by the Connection. The following methods
are provided on the extension interface:</para>
<table frame='all'>
<title>Connection Properties</title>
@@ -27,133 +26,79 @@
<tbody>
<row>
<entry>
- <code>getAnnotations()</code>
+ <code>getAnnotations</code>
</entry>
<entry>
- <code>Get the query engine annotations if the
previously executed command used OPTION PLANONLY or OPTION SHOWPLAN</code>
+ <para>Get the query engine annotations if the statement
was last executed with SHOWPLAN ON|DEBUG. Each
<code>org.teiid.client.plan.Annotation</code> contains a description,
+ a category, a severity, and possibly a resolution of notes recorded during query
planning that can be used to understand choices made by the query planner.</para>
</entry>
</row>
<row>
<entry>
- <code>getDebugLog()</code>
+ <code>getDebugLog</code>
</entry>
<entry>
- <code>Get the debug log if the previously executed
command used OPTION DEBUG.</code>
+ <para>Get the debug log if the statement was last
executed with SHOWPLAN DEBUG.</para>
</entry>
</row>
<row>
<entry>
- <code>getExecutionProperty(String)</code>
+ <code>getExecutionProperty</code>
</entry>
<entry>
- <code>Get the current value of an execution property on
this statement object.</code>
+ <para>Get the current value of an execution property on
this statement object.</para>
</entry>
</row>
<row>
<entry>
- <code>getPlanDescription()</code>
+ <code>getPlanDescription</code>
</entry>
<entry>
- <code>Get the query plan description if the previously
executed command used OPTION PLANONLY or OPTION SHOWPLAN.</code>
+ <para>Get the query plan description if the statement
was last executed with SHOWPLAN ON|DEBUG. The plan is a tree made up of
<code>org.teiid.client.plan.PlanNode</code> objects.
+ Typically <code>PlanNode.toString()</code> or
<code>PlanNode.toXml()</code></para> will be used to convert the plan
into a textual form.
</entry>
</row>
-
<row>
<entry>
- <code>getRequestIdentifier()</code>
+ <code>getRequestIdentifier</code>
</entry>
<entry>
- <code>Get an identifier for the last command executed
on this statement. If no command has been executed yet, null is returned.</code>
+ <para>Get an identifier for the last command executed
on this statement. If no command has been executed yet, null is returned.</para>
</entry>
</row>
<row>
<entry>
- <code>setExecutionProperty(String,
String)</code>
+ <code>setExecutionProperty</code>
</entry>
<entry>
- <code>Set the execution property on this statement.
Execution properties are described in more detail below.</code>
+ <para>Set the execution property on this statement.
See the <link linkend="execution_properties">execution
properties</link> section for more information.
+ It is generally preferable to use the <link
linkend="set_statement">SET statement</link> unless the execution
property applies only to the statement being executed.</para>
</entry>
</row>
<row>
<entry>
- <code>setPayload(Serializable)</code>
+ <code>setPayload</code>
</entry>
<entry>
- <code>Set a per-command payload to pass to translators.
Currently
- this only used for sending hints for Oracle
- data source. For security purposes, this is no longer
recommended.</code>
+ <para>Set a per-command payload to pass to translators.
Currently
+ the only built-in use is for sending hints for Oracle
+ data source.</para>
</entry>
</row>
</tbody>
</tgroup>
- </table>
+ </table>
+ </sect1>
- <sect2>
- <title>Debug Information</title>
-
- <para>Debug information is only returned when using query options.
- These options are set on the session using the
- <code>SET</code> keyword. The available options for debugging
purposes are:</para>
-
- <itemizedlist>
- <para>SET Syntax:
- </para>
- <listitem>
- <para>SET parameter value
- </para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <para>Syntax Rules:
- </para>
- <listitem>
- <para>Both parameter and value must be simple literals - they
cannot contain spaces.</para>
- </listitem>
- <listitem>
- <para>The value is also not treated as an expression and will not
be evaluated prior to being set as the parameter value.</para>
- </listitem>
- </itemizedlist>
- <para>The SET command can be used to control planning and execution.
- </para>
- <itemizedlist>
- <listitem>
- <para>SET SHOWPLAN [ON|DEBUG|OFF] - ON returns the query plan along
with the results and DEBUG additionally prints the query planner debug information in the
log and returns it with the results. Both the plan and the log are available through JDBC
API extensions.</para>
- </listitem>
- <listitem>
- <para>SET NOEXEC [ON|OFF] - ON prevents query execution, but
parsing and planning will still occur.</para>
- </listitem>
- </itemizedlist>
-
- <para>Use the Statement object to execute the above command to set the
required options.</para>
-
- <para><emphasis>getDebugLog()</emphasis> - method can be used
to obtain the output from
- the <code>SET SHOWPLAN DEBUG</code> option.</para>
-
- <para><emphasis>getPlanDescription()</emphasis> - method be
used to obtain the query plan from SET SHOWPLAN ON.
- The plan is a tree made up of <code>PlanNode</code> objects. The
<code>PlanNode</code> interface is
- also in the <code>org.teiid.client.plan</code> package. A PlanNode
simply has a set of properties and
- the ability to traverse to a parent node and the child nodes. The property keys
in the
- query plan nodes are dependent on the type of plan and the command
itself.</para>
-
- <para><emphasis>getAnnotations()</emphasis> - method can be
called to obtain any annotations
- objects. Each annotation contains a description,
- a category, a severity, and possibly a resolution of notes recorded during query
planning
- that can be used to understand choices made by the query planner. This is also
available when SET SHOWPLAN is used.</para>
- </sect2>
-
- <sect2 id="execution_properties">
+ <sect1 id="execution_properties">
<title>Execution Properties</title>
- <para>When your application executes queries, it can specify optional
features for each query.
- Your application can use some of these options only in certain contexts. These
execution properties
- share a common interface when they are being set. The execution properties are
defined by
- constants in the <code>org.teiid.jdbc.ExecutionProperties</code>
interface.</para>
- <para>You can get and set the following execution properties to modify the
behavior of query execution by calling
- <code>setExecutionProperty</code> method on the
<code>org.teiid.jdbc.TeiidStatement</code> class.</para>
+ <para>Execution properties may be set on a per statement basis through the
<link
linkend="statement_extensions"><code>TeiidStatement</code></link>
interface or on the connection via the <link linkend="set_statement">SET
statement</link>.
+ For convenience, the property keys are defined by constants on the
<code>org.teiid.jdbc.ExecutionProperties</code> interface.</para>
<table frame='all'>
<title>Execution Properties</title>
@@ -162,74 +107,123 @@
<colspec colname='c2' colwidth="2*" />
<thead>
<row>
- <entry>Property Name</entry>
+ <entry>Property Name/String Constant</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>
- <code>PROP_TXN_AUTO_WRAP</code>
+ <code>PROP_TXN_AUTO_WRAP / autoCommitTxn</code>
</entry>
<entry>
- <para>Determines how transactions are automatically
wrapped used with
- commands when auto commit mode is set to “true”. Does not
affect transaction
- behavior when auto commit mode is set to “false”. See
- <link
linkend="jdbc_transactions">“Transactions with JDBC”</link> for more
information.</para>
+ <para>Same as the connection property.</para>
</entry>
</row>
<row>
<entry>
- <code>PROP_PARTIAL_RESULTS_MODE</code>
+ <code>PROP_PARTIAL_RESULTS_MODE /
partialResultsMode</code>
</entry>
<entry>
- <para>Determines whether partial results mode is used
for this query or not.</para>
+ <para>See the <link
linkend="partial_results">partial results</link> section.</para>
</entry>
</row>
<row>
<entry>
- <code>PROP_XML_FORMAT</code>
+ <code>PROP_XML_FORMAT / XMLFormat</code>
</entry>
<entry>
- <para>Determines the formatting of the returned XML
documents. The two supported
- formats are XML_TREE_FORMAT, which is a formatted tree with
indentation and
- linefeeds or XML_COMPACT_FORMAT which is a compact message
with no extra whitespace.
- If no value is set for this property (the default), then the
formatting mode
- specified in the XML document model is used.</para>
+ <para>Determines the formatting of XML documents
returned by XML document models. See the <link
linkend="document_formatting">document formatting</link>
section.</para>
</entry>
</row>
<row>
<entry>
- <code>PROP_XML_VALIDATION</code>
+ <code>PROP_XML_VALIDATION / XMLValidation</code>
</entry>
<entry>
- <para>Determines whether xml result documents will be
validated
- against their schema before being returned. If schema
validation fails,
- a warning message is returned along with the result
documents.
- Using validation significantly reduces
performance.</para>
+ <para>Determines whether XML documents returned by XML
document models will be validated
+ against their schema after processing. See the <link
linkend="document_validation">document validation</link>
section.</para>
</entry>
</row>
<row>
<entry>
- <code>RESULT_SET_CACHE_MODE</code>
+ <code>RESULT_SET_CACHE_MODE /
resultSetCacheMode</code>
</entry>
<entry>
- <para>Result set caching provides caching of complete
result sets based on exact query matches.
- Result set caching is not enabled by default. Result set
caching needs to enabled on Server too.
- Once result set caching is enabled, all user
- queries will use the result set cache. Additional control is
provided in the JDBC
- driver to turn off use of the result set cache on a per-query
basis.</para>
+ <para>Same as the connection property.</para>
</entry>
- </row>
+ </row>
+ <row>
+ <entry>
+ <code>SQL_OPTION_SHOWPLAN / SHOWPLAN</code>
+ </entry>
+ <entry>
+ <para>Same as the connection property.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <code>NOEXEC / NOEXEC</code>
+ </entry>
+ <entry>
+ <para>Same as the connection property.</para>
+ </entry>
+ </row>
</tbody>
</tgroup>
</table>
- <para>Each of these properties are described in detail in the following
sections.</para>
- </sect2>
+ </sect1>
- <sect2>
+ <sect1 id="set_statement">
+ <title>Set Statement</title>
+
+ <para>Execution properties may also be set on the connection by using the
SET statement.
+ The SET statement is not yet a language feature of Teiid and is handled only in
the JDBC client.</para>
+
+ <itemizedlist>
+ <para>SET Syntax:
+ </para>
+ <listitem>
+ <para>SET parameter value
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <para>Syntax Rules:
+ </para>
+ <listitem>
+ <para>Both parameter and value must be simple literals - they
cannot contain spaces.</para>
+ </listitem>
+ <listitem>
+ <para>The value is also not treated as an expression and will not
be evaluated prior to being set as the parameter value.</para>
+ </listitem>
+ </itemizedlist>
+ <para>The SET statement is most commonly used to control planning and
execution.</para>
+ <itemizedlist>
+ <listitem>
+ <para>SET SHOWPLAN (ON|DEBUG|OFF)</para>
+ </listitem>
+ <listitem>
+ <para>SET NOEXEC (ON|OFF)</para>
+ </listitem>
+ </itemizedlist>
+
+ <example>
+ <title>Enabling Plan Debug</title>
+ <programlisting>Statement s = connection.createStatement();
+s.execute("SET SHOWPLAN DEBUG");
+...
+Statement s1 = connection.createStatement();
+ResultSet rs = s1.executeQuery("select col from table");
+TeiidStatement ts = s1.unwrap(TeiidStatement.class);
+String debugLog = ts.getDebugLog();
+ </programlisting>
+ </example>
+ </sect1>
+
+ <sect1 id="partial_results">
<title>Partial Results Mode</title>
- <para>The Teiid Server supports a “partial results” query mode. This mode
changes the behavior of the
+ <para>The Teiid Server supports a "partial results" query mode.
This mode changes the behavior of the
query processor so the server returns results even when some data sources are
unavailable.</para>
<para>For example, suppose that two data sources exist for different
suppliers and your
@@ -240,7 +234,7 @@
the same query in “partial results” query mode, the server returns data from the
running data source and no data from the data source that is down.</para>
- <para>When using “partial results” mode, if a source throws an exception
during
+ <para>When using "partial results" mode, if a source throws an
exception during
processing it does not cause the user’s query to fail. Rather, that source is
treated
as returning no more rows after the failure point.
Most commonly, that source will return 0 rows. </para>
@@ -253,63 +247,34 @@
<para>For each source that is excluded from the query, a warning will be
generated
describing the source and the failure. These warnings can be obtained from the
<code>ResultSet.getWarnings()</code> method. This method returns a
<code>SQLWarning</code> object but
- in the case of “partial results” warnings, this will be an object of
+ in the case of "partial results" warnings, this will be an object of
type <code>org.teiid.jdbc.PartialResultsWarning</code> class. This
class can be
used to obtain a list of all the failed sources by name and to obtain
the specific exception thrown by each resource adaptor. </para>
<para>Below is an example of printing the list of failed
sources:</para>
- <programlisting><![CDATA[
- statement.setExecutionProperty(PROP_PARTIAL_RESULTS_MODE, “true”);
- ResultSet results = statement.executeQuery(“SELECT Name FROM Accounts”);
- SQLWarning warning = results.getWarnings();
- if(warning instanceof PartialResultsWarning) {
- PartialResultsWarning partialWarning = (PartialResultsWarning) warning;
- Collection failedConnectors = partialWarning.getFailedConnectors();
- Iterator iter = failedConnectors.iterator();
- while(iter.hasNext()) {
- String connectorName = (String) iter.next();
- SQLException connectorException =
partialWarning.getConnectorException(connectorName);
- System.out.println(connectorName + “: “ +ConnectorException.getMessage();
- }
- }
- ]]></programlisting>
- </sect2>
+
<programlisting><![CDATA[statement.setExecutionProperty(ExecutionProperties.PROP_PARTIAL_RESULTS_MODE,
“true”);
+ResultSet results = statement.executeQuery(“SELECT Name FROM Accounts”);
+SQLWarning warning = results.getWarnings();
+if(warning instanceof PartialResultsWarning) {
+ PartialResultsWarning partialWarning = (PartialResultsWarning) warning;
+ Collection failedConnectors = partialWarning.getFailedConnectors();
+ Iterator iter = failedConnectors.iterator();
+ while(iter.hasNext()) {
+ String connectorName = (String) iter.next();
+ SQLException connectorException =
partialWarning.getConnectorException(connectorName);
+ System.out.println(connectorName + “: “ +ConnectorException.getMessage();
+ }
+}]]></programlisting>
+ </sect1>
- <sect2>
+ <sect1>
<title>XML extensions</title>
- <para>Your application can use a statement object to execute queries that
return XML documents.
- The query must specify a valid document in VDB, or should have used SQL XML
functions
- to create a XMl document. When your
- application executes an XML query, the Teiid Server returns a ResultSet
- object that has a single column named xml and often a single row, which
- represents a document. Depending on the XML virtual document model,
- multiple documents may be returned</para>
- <sect3>
- <title>XML Streaming</title>
- <para>XML documents are streamed from Teiid Server to the Teiid JDBC
API.
- Normally, the document never materializes in the server memory, avoiding
potential
- out-of-memory issues and improving the first response time for large
documents.
- When using style sheets, schema validation, or XQuery, the whole document
- must be materialized on the server. Therefore memory issues may occur for
large documents.
- A result document can be obtained from the JDBC resultset using
<code>getSQLXML</code> method.
- </para>
- <para>The document is broken into pieces when being created and
streamed.
- The maximum size of each piece in the stream can be configured with the
- <code>"lobChunkSizeInKB"</code> system property on the
Server. The default value is 100 KB.
- At any given time, this is the maximum amount of memory that can be held by a
particular
- XML query against the system. In heavily loaded or memory-constrained
scenarios,
- this value can decrease the amount of memory used. As a side effect,
streaming will o
- ccur in smaller pieces, reducing initial document response time while
- increasing full response time (as this is less efficient). Conversely,
increasing this value in
- lightly loaded scenarios uses more server memory and increase the initial
- response time but can make the full response time less</para>
- </sect3>
-
- <sect3>
+ <para>The XML extensions apply on to XML resutls from queries to XML
document models, and not to XML produced by SQL/XML or read from some other
source.</para>
+ <sect2 id="document_formatting">
<title>Document formatting</title>
<para>The PROP_XML_FORMAT execution property can be set to modify the
way that
- XML documents are formatted on return. Valid values for the constant
+ XML documents are formatted from XML document models. Valid values for the
constant
are defined in the same ExecutionProperties interface:</para>
<orderedlist>
<listitem><para><code>XML_TREE_FORMAT</code> -
Returns a version of the XML formatted for display.
@@ -319,37 +284,18 @@
optimal performance. The XML is a single long string without any
unnecessary white space. </para></listitem>
<listitem><para>Not Set - If no format is set, the formatting
flag on the
- XML document in the original model is
honored.</para></listitem>
+ XML document in the original model is honored. This may produce either
the “tree” or “compact”
+ form of the document depending on the document
setting.</para></listitem>
</orderedlist>
- <para>The default is to set neither format and to use the formatting
flag specified
- in the document model itself. This may produce either the “tree” or
“compact”
- form of the document depending on the document setting. </para>
- </sect3>
+ </sect2>
- <sect3>
+ <sect2 id="schema_validation">
<title>Schema validation</title>
<para>The <code>PROP_XML_VALIDATION</code> execution
property can be set to indicate that
- the server should validate documents against their schema before returning
them
- to the client. If schema validation is on, then the server will throw
- an exception if the document does not conform to the schema it is associated
with.
+ the server should validate XML document model documents against their schema
before returning them
+ to the client. If schema validation is on, then the server send a SQLWarning
if the document does not conform to the schema it is associated with.
Using schema validation will reduce the performance of your XML queries.
</para>
-
- <note><para>Schema validation must materialize the entire
document on the server to
- validate the schema. Thus, schema validation will prevent streaming of
- XML results and may increase server memory usage.</para></note>
-
- </sect3>
- </sect2>
+ </sect2>
+ </sect1>
- </sect1>
-
- <sect1>
- <title>ResultSet Limitations</title>
- <orderedlist>
- <listitem><para>Supports only
<code>FORWARD_ONLY</code> and <code>SCROLL_INSENSITIVE</code>
scroll modes. </para></listitem>
- <listitem><para>Supports only <code>READ_ONLY</code>
result sets. <code>UPDATABLE</code> ResultSets are not
supported.</para></listitem>
- <listitem><para>Returning multiple ResultSets from Procedure
execution is not supported.</para></listitem>
- <listitem><para>Closing the ResultSet does not close the
Statement object. Statement must be closed to free the resources.</para>
</listitem>
- </orderedlist>
- </sect1>
</chapter>
\ No newline at end of file
Modified:
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/jdbc-transactions.xml
===================================================================
---
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/jdbc-transactions.xml 2010-06-25
19:35:24 UTC (rev 2305)
+++
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/jdbc-transactions.xml 2010-06-26
03:26:50 UTC (rev 2306)
@@ -10,40 +10,34 @@
by the Teiid Server as XA transactions.
See the <ulink
url="http://java.sun.com/javaee/technologies/jta/index.jsp">JTA
specification</ulink> for more on XA Transactions.</para>
- <note><para>Even though in client application, Teiid data source is
viewed as single source, Teiid
- itself may be integrating data from multiple data sources underneath. So, any
transaction under
- Teiid that involves more than single source is performed as a XA transaction. These
- transaction scopes define the user
- application's interaction with Teiid runtime.</para></note>
-
<sect1>
- <title>Using Local Transactions</title>
+ <title>Local Transactions</title>
<para>The Connection class uses the "autoCommit" flag to
explicitly control local transactions. By default, autoCommit
- is set to "true", which indicates request level or implicit transaction
control. Following is an example of
+ is set to "true", which indicates request level or implicit transaction
control. example of
how to use local transactions by setting the autoCommit flag to
false.</para>
-
- <programlisting><![CDATA[
- // Set auto commit to false and start a transaction
- connection.setAutoCommit(false);
-
- try {
- // Execute multiple updates
- Statement statement = connection.createStatement();
- statement.executeUpdate(“INSERT INTO Accounts (ID, Name) VALUES (10,
‘Mike’)”);
- statement.executeUpdate(“INSERT INTO Accounts (ID, Name) VALUES (15,
‘John’)”);
- statement.close();
-
- // Commit the transaction
- connection.commit();
-
- } catch(SQLException e) {
- // If an error occurs, rollback the transaction
- connection.rollback();
- }
- ]]></programlisting>
+ <example>
+ <title>Local transaction control using autoCommit</title>
+ <programlisting><![CDATA[// Set auto commit to false and start a
transaction
+connection.setAutoCommit(false);
+
+try {
+ // Execute multiple updates
+ Statement statement = connection.createStatement();
+ statement.executeUpdate(“INSERT INTO Accounts (ID, Name) VALUES (10, ‘Mike’)”);
+ statement.executeUpdate(“INSERT INTO Accounts (ID, Name) VALUES (15, ‘John’)”);
+ statement.close();
+
+ // Commit the transaction
+ connection.commit();
+
+} catch(SQLException e) {
+ // If an error occurs, rollback the transaction
+ connection.rollback();
+}]]></programlisting>
+ </example>
<para>This example demonstrates several things:</para>
<orderedlist numeration="arabic">
- <listitem> <para>Setting autoCommit flag to false. This will start a
transaction bound to the current JDBC client thread.</para> </listitem>
+ <listitem> <para>Setting autoCommit flag to false. This will start a
transaction bound to the connection.</para> </listitem>
<listitem> <para>Executing multiple updates within the context of the
transaction.</para> </listitem>
<listitem> <para>When the statements are complete, the transaction is
committed by calling commit().</para> </listitem>
<listitem> <para>If an error occurs, the transaction is rolled back
using the rollback() method.</para> </listitem>
@@ -66,20 +60,18 @@
should perform no action regardless of the commands being executed. To turn
off the use of local transactions,
add this property to the JDBC connection URL</para>
- <programlisting><![CDATA[
- disableLocalTxn=true
- ]]></programlisting>
+
<programlisting><![CDATA[disableLocalTxn=true]]></programlisting>
- <note><para>WARNING:Turning off local transactions can be
dangerous and can result in inconsistent
+ <warning><para>Turning off local transactions can be dangerous
and can result in inconsistent
results (if reading data) or inconsistent data in data stores (if writing
data).
For safety, this mode should be used only if you are certain that
- the calling application does not need local
transactions.</para></note>
+ the calling application does not need local
transactions.</para></warning>
</sect2>
</sect1>
<sect1>
- <title>Using Request Level Transactions</title>
- <para>Request level transactions will be implicitly used when the request
is not in the
+ <title>Request Level Transactions</title>
+ <para>Request level transactions are used when the request is not in the
scope of a global or local transaction, which implies "autoCommit" is
"true". In a request
level transaction, your application does not need to explicitly call commit or
rollback,
rather every command is assumed to be its own transaction that will automatically
@@ -98,29 +90,30 @@
wrapping off (completely) to maximize performance.
</para>
- <para>you can set your transaction wrapping to one of the following
modes.</para>
-
- <programlisting><![CDATA[
- autoCommitTxn=ON|OFF|DETECT
- ]]></programlisting>
-
-
<orderedlist>
+ <para>You can set your transaction wrapping to one of the following
modes:</para>
<listitem> <para><emphasis>ON</emphasis>: This mode
always wraps every command in a transaction
without checking whether it is required. This is the safest
mode.</para></listitem>
<listitem> <para><emphasis>OFF</emphasis>: This mode
never automatically wraps a command in a
transaction or check whether it needs to wrap a command. This mode can be
dangerous as it will
- allow multi-source updates outside of a transaction without an error. This
mode has best
+ allow multiple source updates outside of a transaction without an error.
This mode has best
performance for applications that do not use updates or
transactions.</para></listitem>
<listitem> <para> <emphasis>DETECT</emphasis>: This
mode assumes that the user does not know to execute
- multi-source updates in a transaction. The Teiid Server checks every command
to see whether it
- is a multi-source update and wraps it in a transaction. If it is single
source then uses
+ multiple source updates in a transaction. The Teiid Server checks every
command to see whether it
+ is a multiple source update and wraps it in a transaction. If it is single
source then uses
the source level command transaction.</para></listitem>
</orderedlist>
<para>You can set the transaction mode as a property when you establish the
Connection or on a
per-query basis using the execution properties. For more information on
execution
properties, see the section <link
linkend="execution_properties">“Execution
Properties”</link></para>
+
+ <sect2>
+ <title>Multiple Insert Batches</title>
+ <para>When issuing an INSERT with a query expression (or the deprecated
SELECT INTO), multiple insert batches handled by separate source INSERTS may be processed
by the Teiid server.
+ Care should be taken to ensure that targeted sources support XA or that
compensating actions are taken in the event of a failure.</para>
+ </sect2>
+
</sect1>
<sect1>
@@ -132,38 +125,36 @@
such as JBoss, WebSphere, or Weblogic, the resulting connection will already be
associated with the current XA transaction. No additional client JDBC code is
necessary to interact with the XA transaction.</para>
+ <example><title>>Manual Usage of XA transactions</title>
+ <programlisting><![CDATA[XAConnection xaConn = null;
+XAResource xaRes = null;
+Connection conn = null;
+Statement stmt = null;
+
+try {
+ xaConn = <XADataSource instance>.getXAConnection();
+ xaRes = xaConn.getXAResource();
+ Xid xid = <new Xid instance>;
+ conn = xaConn.getConnection();
+ stmt = conn.createStatement();
+
+ xaRes.start(xid, XAResource.TMNOFLAGS);
+ stmt.executeUpdate("insert into …");
+ <other statements on this connection or other resources enlisted in this
transaction>
+ xaRes.end(xid, XAResource.TMSUCCESS);
+
+ if (xaRes.prepare(xid) == XAResource.XA_OK) {
+ xaRes.commit(xid, false);
+ }
+}
+catch (XAException e) {
+ xaRes.rollback(xid);
+}
+finally {
+ <clean up>
+}]]></programlisting>
+ </example>
- <para>Applications may also utilize Teiid JDBC XA transactions manually,
such as shown in the following example:</para>
- <programlisting><![CDATA[
- XAConnection xaConn = null;
- XAResource xaRes = null;
- Connection conn = null;
- Statement stmt = null;
-
- try {
- xaConn = <DataSource instance>.getXAConnection();
- xaRes = xaConn.getXAResource();
- Xid xid = <new Xid instance>;
- conn = xaConn.getConnection();
- stmt = conn.createStatement();
-
- xaRes.start(xid, XAResource.TMNOFLAGS);
- stmt.executeUpdate("insert into …");
- <other statements on this connection or other resources enlisted in this
transaction>
- xaRes.end(xid, XAResource.TMSUCCESS);
-
- if (xaRes.prepare(xid) == XAResource.XA_OK) {
- xaRes.commit(xid, false);
- }
- }
- catch (XAException e) {
- xaRes.rollback(xid);
- }
- finally {
- <clean up>
- }
- ]]></programlisting>
-
<para>With the use of global transactions multiple Teiid XAConnections may
participate in the
same transaction. It is important to note that the Teiid JDBC XAResource
"isSameRM" method only returns
"true", if connections are made to the same server instance in a
cluster. If the Teiid connections are to different
@@ -175,21 +166,7 @@
</sect1>
<sect1>
- <title>SELECT INTO Transaction</title>
- <para>The <code>SELECT INTO</code> command, even against a
single source, requires a transaction.
- Issuing a <code>SELECT INTO</code> command from within a virtual
procedure or from client application requires
- users to do one of the following:</para>
-
- <orderedlist>
- <listitem><para>Use XA connectors with a global, local, or
request level (automatic wrapping set
- to DETECT or ON) transaction.</para></listitem>
- <listitem><para>Do not use s global or local transaction and set
the automatic
- wrapping to OFF to intentionally avoid using a
transaction.</para></listitem>
- </orderedlist>
- </sect1>
-
- <sect1>
- <title>Transaction Restrictions</title>
+ <title>Restrictions</title>
<sect2>
<title>Application Restrictions</title>
<para>The use of global, local, and request level transactions are all
mutually exclusive.
@@ -202,8 +179,7 @@
<para>The underlying resource adaptors that represent the EIS system
and the EIS system itself must support XA transactions
if they want to participate in distributed XA transaction thru Teiid. If
source system do not support the XA, then it can not particilate in the
distributed transaction. However, the source is still
- eligible to participate in data integration usecase with out the XA support,
however it will not be part of the on going
- transaction.</para>
+ eligible to participate in data integration with out the XA
support</para>
<para>The participation in the XA
transaction is automatically determined based on the resource adaptors XA
capability. It is user's repsonsiblity to make sure
Modified:
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/ssl.xml
===================================================================
---
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/ssl.xml 2010-06-25
19:35:24 UTC (rev 2305)
+++
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/ssl.xml 2010-06-26
03:26:50 UTC (rev 2306)
@@ -4,34 +4,24 @@
%CustomDTD;
]>
<chapter id="ssl">
- <title>Secure Client Connections using SSL in Teiid</title>
+ <title>SSL Client Connections</title>
<para>This chapter will shows you various security configurations
that can be used with Teiid in securing your data access. Note that data level
- security (<link linkend="entitlements">data
entitlements</link>) are explained in separate chapter.</para>
+ security (<link linkend="entitlements">data roles</link>) are
explained in separate chapter.</para>
<sect1 id="default_security">
<title>Default Security</title>
- <para>By default, access to Teiid is NOT secure. The login modules are only
- backed by file based authentication, and it also creates well known user
- name and password for easy access for users who want to give a quick try of the
Teiid.
- The same is also true for making the connection to the Admin Console application
that Teiid provides.
- However, we DO NOT recommend leaving the default security profile as defined when
you
- are exposing sensitive data. Check out the "Admin Guide" for
instructions as to how to
- configure different login modules to secure the access.</para>
- <para>This chapter is dedicated to discuss about securing the communication
channels,
- like the socket connection between your client application and Teiid Server. If
you are always using a
- <link linkend="local_connection">local connection</link>,
then you may not need to secure the channels as
- cleint and server are in the same VM process.</para>
+ <para>If you are always using a
+ <link linkend="local_connection">local connection</link>,
then you do need to secure a channels.</para>
<para>By default all sensitive (non-data) messages between client and
server
are encrypted using a <ulink
url="http://en.wikipedia.org/wiki/Diffie-Hellman_key_exchange"&...
key that is negotiated per connection. This
encryption is controlled by <code>clientEncryptionEnabled</code>
property in <code>JdbcSslConfiguration</code> and
<code>AdminSslConfiguration</code> sections
- in
<code><jboss-install>/server/<profile>/deploy/teiid/teiid-jboss-beans.xml</code>
file. So, the
- passwords are never sent in the clear channel during session
establishment.</para>
+ in
<code><jboss-install>/server/<profile>/deploy/teiid/teiid-jboss-beans.xml</code>
file.</para>
</sect1>
<sect1 id="ssl_modes">
@@ -66,198 +56,132 @@
<listitem><para>client.keystore - client's private
key</para></listitem>
<listitem><para>client.truststore - has client's public
key</para></listitem>
</orderedlist>
- <para>or</para>
- <orderedlist>
- <listitem><para>server.keystore - has server's private key,
client's pulic key</para></listitem>
- <listitem><para>client.keystore - client's private key, and
server's public key</para></listitem>
- </orderedlist>
</sect1>
- <sect1 id="connfigure_server">
- <title>Configuring SSL in Teiid Server</title>
- <para>The Teiid's configuration file
-
<code><jboss-install>/server/<profile>/deploy/teiid/teiid-jboss-beans.xml</code>,
- contains the properties to configure SSL. Teiid Server, has two separate
connection profiles. One for the JDBC
- connections and the other for the Admin connections. They both have separate SSL
configuration
- properties, so besure to know which properties that you are
editing.</para>
- <orderedlist>
- <listitem><para>JDBC Connection - The
<code>JdbcSslConfiguration</code> bean configuration defines
this.</para></listitem>
- <listitem><para>Admin Connection - The
<code>AdminSslConfiguration</code> bean configuration defines
this.</para></listitem>
- </orderedlist>
- <para>The configurations look same as below sample.</para>
- <programlisting><![CDATA[
- <bean name="JdbcSslConfiguration"
class="org.teiid.transport.SSLConfiguration">
- <property name="sslEnabled">false</property>
- <property
name="keystoreFilename">cert.keystore</property>
- <property
name="keystorePassword">passwd</property>
- <property name="keystoreType">JKS</property>
- <property name="sslProtocol">SSLv3</property>
- <property
name="keymanagementAlgorithm">false</property>
- <property
name="truststoreFilename">cert.truststore</property>
- <property
name="truststorePassword">passwd</property>
- <!-- 1-way, 2-way, anonymous -->
- <property
name="authenticationMode">1-way</property>
- <property
name="clientEncryptionEnabled">true</property>
- </bean>
- ]]></programlisting>
- <para>The properties are described below.</para>
- <orderedlist>
- <listitem><para>sslEnabled - true|false, SSL usage either turned
ON or OFF </para></listitem>
- <listitem><para>sslProtocol- Type of SSL protocol to be used.
Default is SSLv3</para></listitem>
- <listitem><para>keystoreType - Keystore type created by the
keytool. Default "JKS" is used.</para></listitem>
- <listitem><para>authenticationMode - anonymous|1-way|2-way, Type
of SSL mode, see
- above about different <link linkend="ssl_modes">SSL
modes</link> available.</para></listitem>
- <listitem><para>keymanagementAlgorithm - Type of key algorithm
used. Default
- is based upon the VM, e.g. "SunX509"</para></listitem>
- <listitem><para>keystoreFilename - The file name of the keystore,
which contains the
- private key of the Server. This must be available in the classpath of Teiid
Server</para></listitem>
- <listitem><para>keystorePassword - password for the
keystore.</para></listitem>
- <listitem><para>truststoreFilename - if
"authenticationMode" is chosen
- as "2-way", then this property must be provided. This is the
truststore that contains the
- public key for the client. Depending upon how you created the keystore and
truststores,
- this may be same file as defined under "keystoreFilename"
property.</para></listitem>
- <listitem><para>truststorePassword - password for the truststore.
</para></listitem>
- </orderedlist>
-
- <para>Once all the properties are defined, make sure the certificates
are in the right place, then restart the
- Teiid server to start accepting connections using SSL.</para>
- </sect1>
-
<sect1 id="configure_client">
- <title>Configuring SSL in Teiid's Client</title>
- <para>Configuring any Java client program with SSL involves modifying
scripts that
- launch the client programs to define few Java VM system properties using
"-Dkey=value" format. The
- following sections define the system properties required for each SSL mode. Note
that when
+ <title>Client SSL Settings</title>
+ <para>The
+ following sections define the properties required for each SSL mode. Note that
when
connecting to Teiid Server with SSL enabled, you
<emphasis>MUST</emphasis> use
the <emphasis>"mms"</emphasis> protocol, instead of
"mm" in the JDBC connection URL, for example</para>
- <para>
jdbc:teiid:<myVdb>@<emphasis>mms</emphasis>://<host>:<port></para>
+
<para>jdbc:teiid:<myVdb>@<emphasis>mms</emphasis>://<host>:<port></para>
- <para>There are two different sets of properties that a client can
configure to enable 1-way or 2-way SSL.</para>
+ <para>There are two different sets of properties that a client can
configure to enable 1-way or 2-way SSL.</para>
<sect2>
- <title>Option 1: Java SSL properties (recommended)</title>
+ <title>Option 1: Java SSL properties</title>
<para>These are standard Java defined system properties to configure
the SSL under any JVM, Teiid is not
unique in its use of SSL. Provide the following system properties to the
client VM process.</para>
- <para>1-way SSL</para>
- <programlisting><![CDATA[
- -Djavax.net.ssl.trustStore=<dir>/server.truststore (required)
- -Djavax.net.ssl.trustStorePassword=<password> (optional)
- -Djavax.net.ssl.keyStoreType (optional)
- ]]></programlisting>
+ <example>
+ <title>1-way SSL</title>
+
<programlisting><![CDATA[-Djavax.net.ssl.trustStore=<dir>/server.truststore
(required)
+-Djavax.net.ssl.trustStorePassword=<password> (optional)
+-Djavax.net.ssl.keyStoreType (optional)]]></programlisting>
+ </example>
- <para>2-way SSL</para>
- <programlisting><![CDATA[
- -Djavax.net.ssl.keyStore=<dir>/client.keystore (required)
- -Djavax.net.ssl.keyStrorePassword=<password> (optional)
- -Djavax.net.ssl.trustStore=<dir>/server.truststore (required)
- -Djavax.net.ssl.trustStorePassword=<password> (optioanl)
- -Djavax.net.ssl.keyStroreType=<keystore type> (optional)
- ]]></programlisting>
-
+ <example>
+ <title>2-way SSL</title>
+
<programlisting><![CDATA[-Djavax.net.ssl.keyStore=<dir>/client.keystore
(required)
+-Djavax.net.ssl.keyStrorePassword=<password> (optional)
+-Djavax.net.ssl.trustStore=<dir>/server.truststore (required)
+-Djavax.net.ssl.trustStorePassword=<password> (optioanl)
+-Djavax.net.ssl.keyStroreType=<keystore type>
(optional)]]></programlisting>
+ </example>
</sect2>
<sect2>
<title>Option 2: Teiid Specific Properties</title>
- <para>Use this option for
<emphasis>"anonymous"</emphasis> mode or when the above
"javax" based properties
+ <para>Use this option for <emphasis>anonymous</emphasis>
mode or when the above "javax" based properties
are already in use by the host process. For example if your client
application is a Tomcat
process that is configured for https protocol and the above Java based
properties are
already in use, and importing Teiid-specific certificate keys into those
https
certificate keystores is not allowed.</para>
- <para>In this scenario, a different set of Teiid-specific SSL
properties can be defined inside
- the "teiid-client-settings.properties" file, such that they do not
override the VM specific
- SSL properties specified for host process. The
"teiid-client-settings.properties" file
- can be found inside the "teiid-{version}-client.jar" file at the
root directory location.
+ <para>In this scenario, a different set of Teiid-specific SSL
properties can be set as system properties or defined inside
+ the "teiid-client-settings.properties" file. The
"teiid-client-settings.properties" file
+ can be found inside the "teiid-&versionNumber;-client.jar" file
at the root.
Extract this file, or make a copy, change the property values required for
the chosen SSL mode,
and place this file in the client application's classpath before
- the "teiid-{version}-client.jar" file.</para>
+ the "teiid-&versionNumber;-client.jar" file.</para>
- <para>SSL properties inside
"teiid-client-settings.properties" are shown below
- (read more property comments inline). Provide the following required
properties for different SSL modes.
- </para>
+ <para>SSL properties and definitions inside the
"teiid-client-settings.properties" are shown below.</para>
- <programlisting><![CDATA[
- ########################################
- # SSL Settings
- ########################################
-
- #
- # The key store type. Defaults to JKS
- #
-
- org.teiid.ssl.keyStoreType=JKS
-
- #
- # The key store algorithm, defaults to
- # the system property "ssl.TrustManagerFactory.algorithm"
- #
-
- #org.teiid.ssl.algorithm=
-
- #
- # The classpath or filesystem location of the
- # key store.
- #
- # This property is required only if performing 2-way
- # authentication that requires a specific private
- # key.
- #
-
- #org.teiid.ssl.keyStore=
-
- #
- # The key store password (not required)
- #
-
- #org.teiid.ssl.keyStorePassword=
-
- #
- # The classpath or filesystem location of the
- # trust store.
- #
- # This property is required if performing 1-way
- # authentication that requires trust not provided
- # by the system defaults.
- #
- # Set to NONE for anonymous authentication using
- # the TLS_DH_anon_WITH_AES_128_CBC_SHA cipher suite
- #
-
- #org.teiid.ssl.trustStore=
-
- #
- # The trust store password (not required)
- #
-
- #org.teiid.ssl.trustStorePassword=
-
- #
- # The cipher protocol, defaults to SSLv3
- #
-
- org.teiid.ssl.protocol=SSLv3
+ <programlisting><![CDATA[########################################
+# SSL Settings
+########################################
- ]]></programlisting>
+#
+# The key store type. Defaults to JKS
+#
+
+org.teiid.ssl.keyStoreType=JKS
+
+#
+# The key store algorithm, defaults to
+# the system property "ssl.TrustManagerFactory.algorithm"
+#
+
+#org.teiid.ssl.algorithm=
+
+#
+# The classpath or filesystem location of the
+# key store.
+#
+# This property is required only if performing 2-way
+# authentication that requires a specific private
+# key.
+#
+
+#org.teiid.ssl.keyStore=
+
+#
+# The key store password (not required)
+#
+
+#org.teiid.ssl.keyStorePassword=
+
+#
+# The classpath or filesystem location of the
+# trust store.
+#
+# This property is required if performing 1-way
+# authentication that requires trust not provided
+# by the system defaults.
+#
+# Set to NONE for anonymous authentication using
+# the TLS_DH_anon_WITH_AES_128_CBC_SHA cipher suite
+#
+
+#org.teiid.ssl.trustStore=
+
+#
+# The trust store password (not required)
+#
+
+#org.teiid.ssl.trustStorePassword=
+
+#
+# The cipher protocol, defaults to SSLv3
+#
+
+org.teiid.ssl.protocol=SSLv3]]></programlisting>
- <para>1-way SSL</para>
- <programlisting><![CDATA[
- org.teiid.ssl.trustStore=<dir>/server.truststore (required)
- ]]></programlisting>
+ <example>
+ <title>1-way SSL</title>
+
<programlisting><![CDATA[org.teiid.ssl.trustStore=<dir>/server.truststore
(required)]]></programlisting>
+ </example>
-
- <para>2-way SSL</para>
- <programlisting><![CDATA[
- org.teiid.ssl.keyStore=<dir>/client.keystore (required)
- org.teiid.ssl.trustStore=<dir>/server.truststore (required)
- ]]></programlisting>
-
- <para>Anonymous</para>
- <programlisting><![CDATA[
- org.teiid.ssl.trustStore=NONE
- ]]></programlisting>
-
+ <example>
+ <title>2-way SSL</title>
+
<programlisting><![CDATA[org.teiid.ssl.keyStore=<dir>/client.keystore
(required)
+org.teiid.ssl.trustStore=<dir>/server.truststore
(required)]]></programlisting>
+ </example>
+ <example>
+ <title>Anonymous</title>
+
<programlisting><![CDATA[org.teiid.ssl.trustStore=NONE]]></programlisting>
+ </example>
</sect2>
</sect1>
</chapter>
\ No newline at end of file
Modified:
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/using-hibernate.xml
===================================================================
---
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/using-hibernate.xml 2010-06-25
19:35:24 UTC (rev 2305)
+++
trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/using-hibernate.xml 2010-06-26
03:26:50 UTC (rev 2306)
@@ -10,79 +10,74 @@
<para>Many Hibernate use cases assume a data source has the ability (with
proper user permissions)
to process Data Definition Language (DDL) statements like CREATE TABLE and DROP
TABLE
as well as Data Manipulation Language (DML) statements like SELECT, UPDATE,
INSERT and DELETE.
- Teiid can handle a broad range of DML but does not support DDL.</para>
+ Teiid can handle a broad range of DML, but does not support DDL.</para>
</sect1>
<sect1>
<title>Configuration</title>
- <para>For the most part, interacting with teiid VDBs (Virtual Databases)
from Hibernate is no
+ <para>For the most part, interacting with Teiid VDBs (Virtual Databases)
from Hibernate is no
different from working with any other type of data source.
First you must place Teiid JDBC API client JAR file and Teiid's hibernate
dialect JAR in Hibernate’s classpath.
These files can be found in
<code><jboss-install>/server/<profile>/lib</code>
directory. </para>
- <orderedlist>
-
<listitem><para>teiid-{version}-client.jar</para></listitem>
-
<listitem><para>teiid-hibernate-dialect-{version}.jar</para></listitem>
- </orderedlist>
+ <itemizedlist>
+
<listitem><para>teiid-&versionNumber;-client.jar</para></listitem>
+
<listitem><para>teiid-hibernate-dialect-&versionNumber;.jar</para></listitem>
+ </itemizedlist>
- <para>These JAR files has
<code>org.teiid.dialect.TeiidDialect</code> and
<code>org.teiid.jdbc.TeiidDriver</code> and
+ <para>These JAR files have the
<code>org.teiid.dialect.TeiidDialect</code> and
<code>org.teiid.jdbc.TeiidDriver</code> and
<code>org.teiid.jdbc.TeiidDataSource</code> classes.</para>
- <para>You then configure the Hibernate configuration file
(hibernate.cfg.xml) as follows: Specify the Teiid driver
- class in the "connection.driver_class" property:</para>
+ <orderedlist>
+ <para>You then configure Hibernate (via hibernate.cfg.xml) as
follows:</para>
+ <listitem>
+ <para>Specify the Teiid driver
+ class in the "connection.driver_class" property:
- <programlisting><![CDATA[
- <property name="connection.driver_class">
- org.teiid.jdbc.TeiidDriver
- </property>
- ]]></programlisting>
-
+ <programlisting><![CDATA[<property
name="connection.driver_class">
+ org.teiid.jdbc.TeiidDriver
+</property>]]></programlisting>
+ </para>
+ </listitem>
+ <listitem>
<para>Specify the URL for the VDB in the "connection.url" property
- (replacing terms in angle brackets with the appropriate values):</para>
+ (replacing terms in angle brackets with the appropriate values):
- <programlisting><![CDATA[
- <property name="connection.url">
-
jdbc:metamatrix:<vdb-name>@mm://<host>:<port>;user=<user-name>;password=<password>
- </property>
- ]]></programlisting>
+ <programlisting><![CDATA[<property
name="connection.url">
+ jdbc:metamatrix:<vdb-name>@mm://<host>:<port>;user=<user-name>;password=<password>
+</property>]]></programlisting></para>
+ </listitem>
+ <listitem>
+ <para>Specify the Teiid dialect class in the “dialect” property:
- <para>Specify the Teiid dialect class in the “dialect”
property:</para>
-
- <programlisting><![CDATA[
- <property name="dialect">
- org.teiid.dialect.TeiidDialect
- </property>
- ]]></programlisting>
-
+ <programlisting><![CDATA[<property name="dialect">
+ org.teiid.dialect.TeiidDialect
+</property>]]></programlisting>
+ </para>
<para>Alternatively, if you put your connection properties in
<code>hibernate.properties</code>
instead of <code>hibernate.cfg.xml</code>, they would look like this:
</para>
- <programlisting><![CDATA[
- hibernate.connection.driver_class=org.teiid.jdbc.TeiidDriver
-
hibernate.connection.url=jdbc:teiid:<vdb-name>@mm://<host>:<port>
- hibernate.connection.username=<user-name>
- hibernate.connection.password=<password>
- hibernate.dialect=org.teiid.dialect.TeiidDialect
- ]]></programlisting>
+
<programlisting><![CDATA[hibernate.connection.driver_class=org.teiid.jdbc.TeiidDriver
+hibernate.connection.url=jdbc:teiid:<vdb-name>@mm://<host>:<port>
+hibernate.connection.username=<user-name>
+hibernate.connection.password=<password>
+hibernate.dialect=org.teiid.dialect.TeiidDialect]]></programlisting>
+ </listitem>
+ </orderedlist>
<para>Note also that since your VDBs will likely contain multiple source and
view models
with identical table names, you will need to fully qualify table names
specified in Hibernate mapping files:</para>
- <programlisting><![CDATA[
- <class name="<Class name>" table="<Source/view
model name>.[<Category/schema name>.]<Table name>">
- ...
- </class>
- ]]></programlisting>
+ <programlisting><![CDATA[<class name="<Class name>"
table="<Source/view model name>.[<schema name>.]<Table
name>">
+ ...
+</class>]]></programlisting>
- <para>For Example:</para>
-
- <programlisting><![CDATA[
- <class name="org.teiid.example.Publisher"
table="BOOKS.BOOKS.PUBLISHERS">
- ...
- </class>
- ]]></programlisting>
-
+ <example>
+ <title>Example Mapping</title>
+ <programlisting><![CDATA[<class
name="org.teiid.example.Publisher" table="BOOKS.BOOKS.PUBLISHERS">
+ ...
+</class>]]></programlisting>
+ </example>
</sect1>
-
</chapter>
\ No newline at end of file
Modified: trunk/documentation/client-developers-guide/src/main/docbook/en-US/main.xml
===================================================================
--- trunk/documentation/client-developers-guide/src/main/docbook/en-US/main.xml 2010-06-25
19:35:24 UTC (rev 2305)
+++ trunk/documentation/client-developers-guide/src/main/docbook/en-US/main.xml 2010-06-26
03:26:50 UTC (rev 2306)
@@ -49,7 +49,6 @@
<xi:include href="content/jdbc-extensions.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/jdbc-transactions.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/ssl.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="content/entitlements.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/using-hibernate.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/appendix-unsupported-jdbc.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/appendix-selfcerts.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />