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>&lt;jboss-install&gt;/server/&lt;profile&gt;/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/&lt;profile&gt;/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/&lt;profile&gt;/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:&lt;vdb-name&gt;@mm[s]://&lt;host&gt;:&lt;port&gt;;[prop-name=prop-value;]*</emphasis></para> + <para>Use the following URL format for JDBC connections:<synopsis>jdbc:teiid:&lt;vdb-name&gt;@mm[s]://&lt;host&gt;:&lt;port&gt;;[prop-name=prop-value;]*</synopsis></para> - <para>Where</para> + <para>URL Components</para> <orderedlist> <listitem><para>&lt;vdb-name&gt; - 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>&lt;host&gt; - defines the server where the Teiid Server is installed</para></listitem> <listitem><para>&lt;port&gt; - 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>&lt;jboss-install&gt;/server/default/lib</code> directory.</para></listitem> - <listitem><para>Create a "teiid-ds.xml" file in <code>&lt;jboss-install&gt;/server/&lt;profile&gt;/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:&lt;vdb-name&gt;@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. &lt;=0 indicates that the value is not set</entry> + <entry>Size of the resultset; The default size if 500. &lt;=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>&lt;jboss-install&gt;/server/&lt;profile&gt;/lib</code> directory.</para></listitem> + <listitem><para>Create a "&lt;datasource name&gt;-ds.xml" file in <code>&lt;jboss-install&gt;/server/&lt;profile&gt;/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:&lt;vdb-name&gt;@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>&lt;jboss-install&gt;/server/&lt;profile&gt;/deploy/teiid/teiid-jboss-beans.xml</code> file. So, the - passwords are never sent in the clear channel during session establishment.</para> + in <code>&lt;jboss-install&gt;/server/&lt;profile&gt;/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>&lt;jboss-install&gt;/server/&lt;profile&gt;/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:&lt;myVdb&gt;@<emphasis>mms</emphasis>://&lt;host&gt;:&lt;port&gt;</para> + <para>jdbc:teiid:&lt;myVdb&gt;@<emphasis>mms</emphasis>://&lt;host&gt;:&lt;port&gt;</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>&lt;jboss-install&gt;/server/&lt;profile&gt;/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" />