Author: rareddy Date: 2010-06-23 14:47:52 -0400 (Wed, 23 Jun 2010) New Revision: 2287 Added: trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/appendix-selfcerts.xml 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/entitlements.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/using-hibernate.xml trunk/documentation/client-developers-guide/src/main/docbook/en-US/main.xml Removed: trunk/documentation/assembly/ trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/other_commands.xml Modified: trunk/build/assembly/docs.xml trunk/build/assembly/jboss-container/dist.xml trunk/documentation/client-developers-guide/ trunk/documentation/client-developers-guide/pom.xml trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/ssl.xml trunk/documentation/pom.xml Log: TEIID-1037: Adding the Client Developers Guide. Merged information from WIKI, old MM document and new content. Modified: trunk/build/assembly/docs.xml =================================================================== --- trunk/build/assembly/docs.xml 2010-06-23 17:10:08 UTC (rev 2286) +++ trunk/build/assembly/docs.xml 2010-06-23 18:47:52 UTC (rev 2287) @@ -18,6 +18,7 @@ <include>org.jboss.teiid.documentation:reference</include> <include>org.jboss.teiid.documentation:developer-guide</include> <include>org.jboss.teiid.documentation:quick-start-example</include> + <include>org.jboss.teiid.documentation:client-developers-guide</include> </includes> <sources> Modified: trunk/build/assembly/jboss-container/dist.xml =================================================================== --- trunk/build/assembly/jboss-container/dist.xml 2010-06-23 17:10:08 UTC (rev 2286) +++ trunk/build/assembly/jboss-container/dist.xml 2010-06-23 18:47:52 UTC (rev 2287) @@ -64,6 +64,11 @@ <source>target/distribution/teiid-${version}-docs/developer-guide/en-US/pdf/developer_guide.pdf</source> <outputDirectory>teiid-docs</outputDirectory> </file> + <file> + <source>target/distribution/teiid-${version}-docs/client-developers-guide/en-US/pdf/client_developers_guide.pdf</source> + <outputDirectory>teiid-docs</outputDirectory> + </file> + </files> Property changes on: trunk/documentation/client-developers-guide ___________________________________________________________________ Name: svn:ignore + target .project .settings .classpath Modified: trunk/documentation/client-developers-guide/pom.xml =================================================================== --- trunk/documentation/client-developers-guide/pom.xml 2010-06-23 17:10:08 UTC (rev 2286) +++ trunk/documentation/client-developers-guide/pom.xml 2010-06-23 18:47:52 UTC (rev 2287) @@ -37,7 +37,7 @@ </dependency> </dependencies> <configuration> - <sourceDocumentName>DataCaching.xml</sourceDocumentName> + <sourceDocumentName>main.xml</sourceDocumentName> <imageResource> <directory>${basedir}/src/main/docbook/en-US</directory> <excludes> Added: trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/appendix-selfcerts.xml =================================================================== --- trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/appendix-selfcerts.xml (rev 0) +++ trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/appendix-selfcerts.xml 2010-06-23 18:47:52 UTC (rev 2287) @@ -0,0 +1,73 @@ +<?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; +]> +<appendix id="appendix-selfcerts"> + <title>Generating Self Signed Certificate with Keytool</title> + <para>To generate a self-signed certificate, you need a program called “keytool”, which is + supplied with any version of the Java SDK. The instructions below walk through the creation + of both the key store and the trust store files for a 1-way SSL configuration with + the security keys.</para> + + <sect1> + <title>Creating private/public key pair:</title> + <programlisting><![CDATA[ +keytool -genkey -alias teiid -keyalg RSA -validity 365 –keystore +server.keystore –storetype JKS + + Enter keystore password: <enter password> + What is your first and last name? + [Unknown]: <user’s name> + What is the name of your organizational unit? + [Unknown]: <department name> + What is the name of your organization? + [Unknown]: <company name> + What is the name of your City or Locality? + [Unknown]: <city name> + What is the name of your State or Province? + [Unknown]: <state name> + What is the two-letter country code for this unit? + [Unknown]: <country name> + + Is CN=<user’s name>, OU=<department name>, O="<company name>", + L=<city name>, ST=<state name>, C=<country name> correct? + [no]: yes + Enter key password for <server> + (Return if same as keystore password) + ]]></programlisting> + <para>The "server.keystore" can be used as keystore based upon the newly created private key.</para> + </sect1> + + <sect1> + <title>Extracting the public key</title> + <para>From the "server.keystore" created above we can extract a public key for creating a trust store</para> + <programlisting><![CDATA[ +keytool -export -alias teiid –keystore server.keystore -rfc -file public.cert + Enter keystore password: <enter passsword> + ]]></programlisting> + <para>This creates the "public.cert" file that contains the public key based on the + private key in the "server.keystore"</para> + </sect1> + + <sect1> + <title>Creating the Truststore</title> + + <programlisting><![CDATA[ +keytool -import -alias teiid -file public.cert –storetype JKS -keystore server.truststore +Enter keystore password: <enter password> +Owner: CN=<user's name>, OU=<dept name>, O=<company name>, L=<city>, ST=<state>, C=<country> +Issuer: CN=<user's name>, OU=<dept name>, O=<company name>, L=<city>, ST=<state>, C=<country> +Serial number: 416d8636 +Valid from: Fri Jul 31 14:47:02 CDT 2009 until: Sat Jul 31 14:47:02 CDT 2010 +Certificate fingerprints: + MD5: 22:4C:A4:9D:2E:C8:CA:E8:81:5D:81:35:A1:84:78:2F + SHA1: 05:FE:43:CC:EA:39:DC:1C:1E:40:26:45:B7:12:1C:B9:22:1E:64:63 +Trust this certificate? [no]: yes + ]]></programlisting> + <para>Now this has created "server.truststore". There are many other ways to create self signed certificates, + the above procedure is just one way. If you would like create them + using "openssl", see <ulink url="http://www.akadia.com/services/ssh_test_certificate.html"&... tutorial</ulink>.</para> + </sect1> + +</appendix> \ No newline at end of file Property changes on: trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/appendix-selfcerts.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Added: 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 (rev 0) +++ trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/appendix-unsupported-jdbc.xml 2010-06-23 18:47:52 UTC (rev 2287) @@ -0,0 +1,335 @@ +<?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; +]> +<appendix id="unsupported_jdbc"> + <title>Unsupported JDBC Methods</title> + <para>Based upon the JDBC in JDK 1.6, this appendix details only those JDBC methods + that Teiid does not support. Unless specified below, Teiid supports all other JDBC Methods.</para> + <para>Those methods listed without comments throw a SQLException stating that it is not supported.</para> + + <para>Where specified, some listed methods do not throw an exception, but possibly exhibit unexpected behavior. + If no arguments are specified, then all related (overridden) methods are not supported. If an argument is listed + then only those forms of the method specified are not supported.</para> + + <sect1> + <title>Unsupported Classes and Methods in "java.sql"</title> + <table frame='all'> + <title>Connection Properties</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*" /> + <colspec colname='c2' colwidth="2*" /> + <thead> + <row> + <entry>Class name</entry> + <entry>Methods</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <code>Array</code> + </entry> + <entry> + <code>Not Supported</code> + </entry> + </row> + <row> + <entry> + <code>Blob</code> + </entry> + <entry> + <programlisting><![CDATA[ +getBinaryStream(long, long) - throws SQLFeatureNotSupportedException +setBinaryStream(long) - - throws SQLFeatureNotSupportedException +setBytes - - throws SQLFeatureNotSupportedException +truncate(long) - throws SQLFeatureNotSupportedException + ]]></programlisting> + </entry> + </row> + <row> + <entry> + <code>CallableStatement</code> + </entry> + <entry> + <programlisting><![CDATA[ +getArray - throws SQLFeatureNotSupportedException +getBigDecimal(String parameterName)- throws SQLFeatureNotSupportedException +getBlob(String parameterName)- throws SQLFeatureNotSupportedException +getBoolean(String parameterName)- throws SQLFeatureNotSupportedException +getByte(String parameterName)- throws SQLFeatureNotSupportedException +getBytes(String parameterName)- throws SQLFeatureNotSupportedException +getCharacterStream(String parameterName)- throws SQLFeatureNotSupportedException +getClob(String parameterName)- throws SQLFeatureNotSupportedException +getDate(String parameterName, *)- throws SQLFeatureNotSupportedException +getDouble(String parameterName)- throws SQLFeatureNotSupportedException +getFloat(String parameterName)- throws SQLFeatureNotSupportedException +getInt(String parameterName)- throws SQLFeatureNotSupportedException +getLong(String parameterName)- throws SQLFeatureNotSupportedException +getNCharacterStream - throws SQLFeatureNotSupportedException +getNClob - throws SQLFeatureNotSupportedException +getNString - throws SQLFeatureNotSupportedException +getObject(int parameterIndex, Map&lt;String, Class&lt;?&gt;&gt; map) - throws SQLFeatureNotSupportedException +getObject(String parameterName) - throws SQLFeatureNotSupportedException +getRef - throws SQLFeatureNotSupportedException +getRowId - throws SQLFeatureNotSupportedException +getShort(String parameterName) - throws SQLFeatureNotSupportedException +getSQLXML(String parameterName) - throws SQLFeatureNotSupportedException +getString(String parameterName) - throws SQLFeatureNotSupportedException +getTime(String parameterName, *) - throws SQLFeatureNotSupportedException +getTimestamp(String parameterName, *) - throws SQLFeatureNotSupportedException +getURL(String parameterName) - throws SQLFeatureNotSupportedException +registerOutParameter - ignores +registerOutParameter(String parameterName, *) - throws SQLFeatureNotSupportedException +setAsciiStream - throws SQLFeatureNotSupportedException +setBigDecimal(String parameterName, BigDecimal x)- throws SQLFeatureNotSupportedException +setBinaryStream(String parameterName, *) - throws SQLFeatureNotSupportedException +setBlob(String parameterName, *)- throws SQLFeatureNotSupportedException +setBoolean(String parameterName, boolean x) - throws SQLFeatureNotSupportedException +setByte(String parameterName, byte x) - throws SQLFeatureNotSupportedException +setBytes(String parameterName, byte[] x) - throws SQLFeatureNotSupportedException +setCharacterStream - throws SQLFeatureNotSupportedException +setClob(String parameterName, *) - throws SQLFeatureNotSupportedException +setDate(String parameterName, *) - throws SQLFeatureNotSupportedException +setDouble(String parameterName, double x) - throws SQLFeatureNotSupportedException +setFloat(String parameterName, float x) - throws SQLFeatureNotSupportedException +setLong(String parameterName, long x) - throws SQLFeatureNotSupportedException +setNCharacterStream - throws SQLFeatureNotSupportedException +setNClob - throws SQLFeatureNotSupportedException +setNString - throws SQLFeatureNotSupportedException +setNull - throws SQLFeatureNotSupportedException +setObject(String parameterName, *) - throws SQLFeatureNotSupportedException +setRowId(String parameterName, RowId x) - throws SQLFeatureNotSupportedException +setSQLXML(String parameterName, SQLXML xmlObject) - throws SQLFeatureNotSupportedException +setShort(String parameterName, short x) - throws SQLFeatureNotSupportedException +setString(String parameterName, String x) - throws SQLFeatureNotSupportedException +setTime(String parameterName, *) - throws SQLFeatureNotSupportedException +setTimestamp(String parameterName, *) - throws SQLFeatureNotSupportedException +setURL(String parameterName, URL val) - throws SQLFeatureNotSupportedException + ]]></programlisting> + </entry> + </row> + <row> + <entry> + <code>Clob</code> + </entry> + <entry> + <programlisting><![CDATA[ +getCharacterStream(long arg0, long arg1) - throws SQLFeatureNotSupportedException +setAsciiStream(long arg0) - throws SQLFeatureNotSupportedException +setCharacterStream(long arg0) - throws SQLFeatureNotSupportedException +setString - throws SQLFeatureNotSupportedException +truncate - throws SQLFeatureNotSupportedException + ]]></programlisting> + </entry> + </row> + <row> + <entry> + <code>Connection</code> + </entry> + <entry> + <programlisting><![CDATA[ +createArrayOf - throws SQLFeatureNotSupportedException +createBlob - throws SQLFeatureNotSupportedException +createClob - throws SQLFeatureNotSupportedException +createNClob - throws SQLFeatureNotSupportedException +createSQLXML - throws SQLFeatureNotSupportedException +createStatement(int resultSetType,int resultSetConcurrency, int resultSetHoldability) - throws SQLFeatureNotSupportedException +createStruct(String typeName, Object[] attributes) - throws SQLFeatureNotSupportedException +getClientInfo - throws SQLFeatureNotSupportedException +prepareCall(String sql, int resultSetType,int resultSetConcurrency, int resultSetHoldability) - throws SQLFeatureNotSupportedException +prepareStatement(String sql, int autoGeneratedKeys) - throws SQLFeatureNotSupportedException +prepareStatement(String sql, int[] columnIndexes) - throws SQLFeatureNotSupportedException +prepareStatement(String sql, String[] columnNames) - throws SQLFeatureNotSupportedException +releaseSavepoint - throws SQLFeatureNotSupportedException +rollback(Savepoint savepoint) - throws SQLFeatureNotSupportedException +setHoldability - throws SQLFeatureNotSupportedException +setSavepoint - throws SQLFeatureNotSupportedException +setTypeMap - throws SQLFeatureNotSupportedException + ]]></programlisting> + </entry> + </row> + <row> + <entry> + <code>DatabaseMetaData</code> + </entry> + <entry> + <programlisting><![CDATA[ +getAttributes - throws SQLFeatureNotSupportedException +getClientInfoProperties - throws SQLFeatureNotSupportedException +getFunctionColumns - throws SQLFeatureNotSupportedException +getFunctions - throws SQLFeatureNotSupportedException +getRowIdLifetime - throws SQLFeatureNotSupportedException + ]]></programlisting> + </entry> + </row> + <row> + <entry> + <code>NClob</code> + </entry> + <entry> + <code>Not Supported</code> + </entry> + </row> + <row> + <entry> + <code>PreparedStatement</code> + </entry> + <entry> + <programlisting><![CDATA[ +execute(String sql) - throws SQLException +executeQuery(String sql) - throws SQLException +executeUpdate(String sql) - throws SQLException +setArray - throws SQLFeatureNotSupportedException +setNCharacterStream - throws SQLFeatureNotSupportedException +setNClob - throws SQLFeatureNotSupportedException +setRef - throws SQLFeatureNotSupportedException +setRowId - throws SQLFeatureNotSupportedException +setUnicodeStream - throws SQLFeatureNotSupportedException + ]]></programlisting> + </entry> + </row> + <row> + <entry> + <code>Ref</code> + </entry> + <entry> + <code>Not Implemented</code> + </entry> + </row> + <row> + <entry> + <code>ResultSet</code> + </entry> + <entry> + <programlisting><![CDATA[ +deleteRow - throws SQLFeatureNotSupportedException +getArray - throws SQLFeatureNotSupportedException +getAsciiStream - throws SQLFeatureNotSupportedException +getHoldability - throws SQLFeatureNotSupportedException +getNCharacterStream - throws SQLFeatureNotSupportedException +getNClob - throws SQLFeatureNotSupportedException +getNString - throws SQLFeatureNotSupportedException +getObject(*, Map&lt;String, Class&lt;?&gt;&gt; map) - throws SQLFeatureNotSupportedException +getRef - throws SQLFeatureNotSupportedException +getRowId - throws SQLFeatureNotSupportedException +getUnicodeStream - throws SQLFeatureNotSupportedException +getURL - throws SQLFeatureNotSupportedException +insertRow - throws SQLFeatureNotSupportedException +moveToInsertRow - throws SQLFeatureNotSupportedException +refreshRow - throws SQLFeatureNotSupportedException +rowDeleted - throws SQLFeatureNotSupportedException +rowInserted - throws SQLFeatureNotSupportedException +rowUpdated - throws SQLFeatureNotSupportedException +setFetchDirection - throws SQLFeatureNotSupportedException +update* - throws SQLFeatureNotSupportedException + ]]></programlisting> + </entry> + </row> + <row> + <entry> + <code>RowId</code> + </entry> + <entry> + <code>Not Supported</code> + </entry> + </row> + <row> + <entry> + <code>Savepoint</code> + </entry> + <entry> + <code>not Supported</code> + </entry> + </row> + <row> + <entry> + <code>SQLData</code> + </entry> + <entry> + <code>Not Supported</code> + </entry> + </row> + <row> + <entry> + <code>SQLInput</code> + </entry> + <entry> + <code>not Supported</code> + </entry> + </row> + <row> + <entry> + <code>SQLOutput</code> + </entry> + <entry> + <code>Not Supported</code> + </entry> + </row> + <row> + <entry> + <code>Statement</code> + </entry> + <entry> + <programlisting ><![CDATA[ +execute(String, int) +execute(String, int[]) +execute(String, String[]) +executeUpdate(String, int) +executeUpdate(String, int[]) +executeUpdate(String, String[]) +getGeneratedKeys() +getResultSetHoldability() +setCursorName(String) + ]]></programlisting> + </entry> + </row> + <row> + <entry> + <code>Struct</code> + </entry> + <entry> + <code>Not Supported</code> + </entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> + + <sect1> + <title>Unsupported Classes and Methods in "javax.sql"</title> + <table frame='all'> + <title>Connection Properties</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*" /> + <colspec colname='c2' colwidth="2*" /> + <thead> + <row> + <entry>Class name</entry> + <entry>Methods</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <code>RowSet*</code> + </entry> + <entry> + <code>Not Supported</code> + </entry> + </row> + <row> + <entry> + <code>StatementEventListener</code> + </entry> + <entry> + <code>Not Supported</code> + </entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> +</appendix> \ No newline at end of file Property changes on: trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/appendix-unsupported-jdbc.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Added: 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 (rev 0) +++ trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/entitlements.xml 2010-06-23 18:47:52 UTC (rev 2287) @@ -0,0 +1,127 @@ +<?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 Property changes on: trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/entitlements.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Added: 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 (rev 0) +++ trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/jdbc-connection.xml 2010-06-23 18:47:52 UTC (rev 2287) @@ -0,0 +1,460 @@ +<?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="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>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>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>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 + <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> + </orderedlist> + + <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> + + <orderedlist numeration="arabic"> + <listitem> <para><code>TeiidDriver</code> - JDBC connections using + <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> + + <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> + + <para><emphasis>jdbc:teiid:&lt;vdb-name&gt;@mm[s]://&lt;host&gt;:&lt;port&gt;;[prop-name=prop-value;]*</emphasis></para> + + <para>Where</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>&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> + </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> + <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='c3' colwidth="2*" /> + <thead> + <row> + <entry>Property Name</entry> + <entry>Type</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <code>ApplicationName</code> + </entry> + <entry> + <code>String</code> + </entry> + <entry>Name of the client application; allows the administrator to identify the connections</entry> + </row> + <row> + <entry> + <code>FetchSize</code> + </entry> + <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> + </row> + <row> + <entry> + <code>partialResultsMode</code> + </entry> + <entry> + <code>String</code> + </entry> + <entry>Enable/disable support partial results mode. Default is "off". Allowed values are "on" or "off"</entry> + </row> + <row> + <entry> + <code>autoCommitTxn</code> + </entry> + <entry> + <code>String</code> + </entry> + <entry>Only applies only when "autoCommit" is set to "true". + + This determines how a executed command needs to be transactionally wrapped inside the + Teiid engine to maintain the data integrity. + <orderedlist> + <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> + </entry> + </row> + <row> + <entry> + <code>disableLocalTxn</code> + </entry> + <entry> + <code>boolean</code> + </entry> + <entry> If "true", the autoCommit setting, commit and rollback will be ignored for local transactions.</entry> + </row> + <row> + <entry> + <code>user</code> + </entry> + <entry> + <code>String</code> + </entry> + <entry>User name</entry> + </row> + <row> + <entry> + <code>Password</code> + </entry> + <entry> + <code>String</code> + </entry> + <entry>Credential for user</entry> + </row> + <row> + <entry> + <code>ansiQuotedIdentifiers</code> + </entry> + <entry> + <code>boolean</code> + </entry> + <entry>Sets the parsing behavior for double quoted entries in SQL. The default, true, parses dobuled + quoted entries as identifiers. If set to false, then double quoted values that + are valid string literals will be parsed as string literals.</entry> + </row> + <row> + <entry> + <code>version</code> + </entry> + <entry> + <code>integer</code> + </entry> + <entry>Version number of the VDB</entry> + </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> + </row> + + <row> + <entry> + <code>SHOWPLAN</code> + </entry> + <entry> + <code>String</code> + </entry> + <entry>Can be one of ON|OFF|DEBUG</entry> + </row> + + <row> + <entry> + <code>NoExec</code> + </entry> + <entry> + <code>boolean</code> + </entry> + <entry>true|false</entry> + </row> + + <row> + <entry> + <code>autoFailover</code> + </entry> + <entry> + <code>boolean</code> + </entry> + <entry>If true, will automatically select a new server instance after a communication exception.</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'> + <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='c3' colwidth="2*" /> + <thead> + <row> + <entry>Property Name</entry> + <entry>Type</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <code>DatabaseName</code> + </entry> + <entry> + <code>String</code> + </entry> + <entry>The name of a virtual database (VDB) deployed to Teiid</entry> + </row> + <row> + <entry> + <code>ServerName</code> + </entry> + <entry> + <code>String</code> + </entry> + <entry>Server where the Teiid runtime installed</entry> + </row> + <row> + <entry> + <code>PortNumber</code> + </entry> + <entry> + <code>integer</code> + </entry> + <entry>Port number on which the Server process is listening on.</entry> + </row> + <row> + <entry> + <code>secure</code> + </entry> + <entry> + <code>boolean</code> + </entry> + <entry>Secure connection. Flag to indicate to use SSH based connection between client and server</entry> + </row> + <row> + <entry> + <code>DatabaseVersion</code> + </entry> + <entry> + <code>integer</code> + </entry> + <entry>VDB version</entry> + </row> + <row> + <entry> + <code>DataSourceName</code> + </entry> + <entry> + <code>String</code> + </entry> + <entry>Name given to this data source</entry> + </row> + </tbody> + </tgroup> + </table> + + <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> + </sect1> +</chapter> \ No newline at end of file Property changes on: trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/jdbc-connection.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Added: 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 (rev 0) +++ trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/jdbc-extensions.xml 2010-06-23 18:47:52 UTC (rev 2287) @@ -0,0 +1,355 @@ +<?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="jdbc_extensions"> + <title>Teiid extensions to the JDBC API</title> + + <sect1> + <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> + + <table frame='all'> + <title>Connection Properties</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*" /> + <colspec colname='c2' colwidth="2*" /> + <thead> + <row> + <entry>Method Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <code>getAnnotations()</code> + </entry> + <entry> + <code>Get the query engine annotations if the previously executed command used OPTION PLANONLY or OPTION SHOWPLAN</code> + </entry> + </row> + + <row> + <entry> + <code>getDebugLog()</code> + </entry> + <entry> + <code>Get the debug log if the previously executed command used OPTION DEBUG.</code> + </entry> + </row> + + <row> + <entry> + <code>getExecutionProperty(String)</code> + </entry> + <entry> + <code>Get the current value of an execution property on this statement object.</code> + </entry> + </row> + + <row> + <entry> + <code>getPlanDescription()</code> + </entry> + <entry> + <code>Get the query plan description if the previously executed command used OPTION PLANONLY or OPTION SHOWPLAN.</code> + </entry> + </row> + + <row> + <entry> + <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> + </entry> + </row> + + <row> + <entry> + <code>setExecutionProperty(String, String)</code> + </entry> + <entry> + <code>Set the execution property on this statement. Execution properties are described in more detail below.</code> + </entry> + </row> + + <row> + <entry> + <code>setPayload(Serializable)</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> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <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"> + <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> + + <table frame='all'> + <title>Execution Properties</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*" /> + <colspec colname='c2' colwidth="2*" /> + <thead> + <row> + <entry>Property Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <code>PROP_TXN_AUTO_WRAP</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> + </entry> + </row> + <row> + <entry> + <code>PROP_PARTIAL_RESULTS_MODE</code> + </entry> + <entry> + <para>Determines whether partial results mode is used for this query or not.</para> + </entry> + </row> + <row> + <entry> + <code>PROP_XML_FORMAT</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> + </entry> + </row> + <row> + <entry> + <code>PROP_XML_VALIDATION</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> + </entry> + </row> + <row> + <entry> + <code>RESULT_SET_CACHE_MODE</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> + </entry> + </row> + </tbody> + </tgroup> + </table> + <para>Each of these properties are described in detail in the following sections.</para> + </sect2> + + <sect2> + <title>Partial Results Mode</title> + <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 + data Designers have created a virtual group that creates a union between the information + from the two suppliers. If your application submits a query without using partial + results query mode and one of the suppliers’ databases is down, the query + against the virtual group returns an exception. However, if your application runs + 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 + 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> + + <para>This behavior is most useful when using <code>UNION</code> or <code>OUTER JOIN</code> queries + as these operations handle missing information in a useful way. Most + other kinds of queries will simply return 0 rows to the user + when used in partial results mode and the source is unavailable. </para> + + <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 + 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> + + <sect2> + <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> + <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 + 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. + The XML will use line breaks and tabs as appropriate to format the XML as a tree. + This format is slower due to the formatting time and the larger document size.</para></listitem> + <listitem><para><code>XML_COMPACT_FORMAT</code> - Returns a version of the XML formatted for + 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> + </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> + + <sect3> + <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. + 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> + + </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 Property changes on: trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/jdbc-extensions.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Added: 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 (rev 0) +++ trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/jdbc-transactions.xml 2010-06-23 18:47:52 UTC (rev 2287) @@ -0,0 +1,214 @@ +<?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="jdbc_transactions"> + <title>Transactions with JDBC</title> + <para>The Teiid JDBC API supports three types of transactions from a + client perspective – global, local, and request level. All are implemented + 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> + <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 + 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> + <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>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> + </orderedlist> + <para>Any of the following operations will end a local transaction:</para> + <orderedlist> + <listitem> <para>Connection.setAutoCommit(true) – if previously set to false</para> </listitem> + <listitem> <para>Connection.commit()</para> </listitem> + <listitem> <para>Connection.rollback()</para> </listitem> + <listitem> <para>A transaction will be rolled back automatically if it times out.</para> </listitem> + </orderedlist> + <sect2> + <title>Turning Off Local Transactions</title> + <para>In some cases, tools or frameworks above Teiid will call setAutoCommit(false), commit() and rollback() + even when all access is read-only and no transactions are necessary. + In the scope of a local transaction Teiid will start and attempt to commit an XA transaction, + possibly complicating configuration or causing performance degradation.</para> + + <para>In these cases, you can override the default JDBC behavior to indicate that these methods + 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> + + <note><para>WARNING: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> + </sect2> + </sect1> + + <sect1> + <title>Using Request Level Transactions</title> + <para>Request level transactions will be implicitly 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 + be committed or rolled back by the server.</para> + + <para>The Teiid Server can perform updates through virtual tables. These updates might + result in an update against multiple physical systems, even though the application issues + the update command against a single virtual table. Often, a user might not know whether + the queried tables actually update multiple sources and require a transaction.</para> + + <para>For that reason, the Teiid Server allows your application to automatically wrap commands + in transactions when necessary. Because this wrapping incurs a performance penalty for your queries, + you can choose from a number of available wrapping modes to suit your environment. You need to choose + between the highest degree of integrity and performance your application needs. + For example, if your data sources are not transaction-compliant, you might turn the transaction + 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> + <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 + 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 + 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> + </sect1> + + <sect1> + <title>Using Global Transactions</title> + <para>Global or client XA transactions allow the Teiid JDBC API to participate in transactions that + are beyond the scope of a single client resource. For this use the Teiid DataSource Class for establishing connections.</para> + + <para>When the DataSource is used in the context of a UserTransaction in an application server, + 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> + + <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 + server instances then transactional behavior may not be the same as if they were to the same cluster member. + For example, if the client transaction manager uses the same XID for each connection, duplicate XID exceptions + may arise from the same physical source accessed through different cluster members. + If the client transaction manager uses a different branch identifier for each connection, issues may arise + with sources that lock or isolate changes based upon branch identifiers.</para> + </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> + <sect2> + <title>Application Restrictions</title> + <para>The use of global, local, and request level transactions are all mutually exclusive. + Request level transactions only apply when not in a global or local transaction. Any attempt to + mix global and local transactions concurrently will result in an exception.</para> + </sect2> + + <sect2> + <title>Enterprise Information System Support</title> + <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> + + <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 + that they configure a XA resource when they require them to participate in distributed transaction. + </para> + </sect2> + </sect1> +</chapter> \ No newline at end of file Property changes on: trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/jdbc-transactions.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Deleted: trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/other_commands.xml =================================================================== --- trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/other_commands.xml 2010-06-23 17:10:08 UTC (rev 2286) +++ trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/other_commands.xml 2010-06-23 18:47:52 UTC (rev 2287) @@ -1,37 +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"> -<chapter id="other_commands"> - <title>Other Commands</title> - <sect1 id="set_command"> - <title>SET Command</title> - <para>The SET command is used to set execution property values for the duration of the session.</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> - </sect1> -</chapter> \ No newline at end of file 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-23 17:10:08 UTC (rev 2286) +++ trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/ssl.xml 2010-06-23 18:47:52 UTC (rev 2287) @@ -0,0 +1,263 @@ +<?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="ssl"> + <title>Secure Client Connections using SSL in Teiid</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> + + <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>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> + </sect1> + + <sect1 id="ssl_modes"> + <title>SSL Modes</title> + <para>Teiid supports SSL based channel between the client JDBC application and Teiid Server. Teiid supports the following + SSL modes.</para> + <orderedlist> + <listitem><para>Anonymous – No certificates are required, but all communications are still + encrypted using the TLS_DH_anon_WITH_AES_128_CBC_SHA SSL suite.</para></listitem> + <listitem><para>1-way – Only authenticates the server to the client traffic. Requires a private key keystore to be created + for the server and a truststore at the client that authenticates that key. The SSL suite is negotiated.</para></listitem> + <listitem><para>2-way – Mutual client and server authentication. The server and client applications + each have a keystore for their private keys and each has a truststore that authenticates the other.</para></listitem> + </orderedlist> + + <para>Depending upon the SSL mode, follow the guidelines of your organization around creating/obtaining + private keys. If you have no organizational requirements, then follow this guide to create + <link linkend="appendix-selfcerts">self-signed certificates</link> with their respective keystores and truststores.</para> + <para>The following keystore and truststore combinations are required for different SSL modes. The names of + the files can be chosen by the user. The following files are shown for example purposes only.</para> + + <para><emphasis>1-way</emphasis> </para> + <orderedlist> + <listitem><para>server.keystore - has server's private key</para></listitem> + <listitem><para>server.truststore - has server's public key</para></listitem> + </orderedlist> + + <para><emphasis>2-way</emphasis> </para> + <orderedlist> + <listitem><para>server.keystore - has server's private key</para></listitem> + <listitem><para>server.truststore - has server's public key</para></listitem> + <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 + 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>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> + <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> + + <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> + + </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 + 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. + 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> + + <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> + + <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> + + <para>1-way SSL</para> + <programlisting><![CDATA[ + org.teiid.ssl.trustStore=<dir>/server.truststore (required) + ]]></programlisting> + + + <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> + + </sect2> + </sect1> +</chapter> \ No newline at end of file Added: 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 (rev 0) +++ trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/using-hibernate.xml 2010-06-23 18:47:52 UTC (rev 2287) @@ -0,0 +1,88 @@ +<?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="using_hibernate"> + <title>Using Teiid with Hibernate</title> + <sect1> + <title>Limitations</title> + <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> + </sect1> + + <sect1> + <title>Configuration</title> + <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> + + <para>These JAR files has <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> + + <programlisting><![CDATA[ + <property name="connection.driver_class"> +      org.teiid.jdbc.TeiidDriver + </property> + ]]></programlisting> + + <para>Specify the URL for the VDB in the "connection.url" property + (replacing terms in angle brackets with the appropriate values):</para> + + <programlisting><![CDATA[ +       <property name="connection.url"> +           jdbc:metamatrix:<vdb-name>@mm://<host>:<port>;user=<user-name>;password=<password> +       </property> + ]]></programlisting> + + <para>Specify the Teiid dialect class in the “dialect” property:</para> + + <programlisting><![CDATA[ + <property name="dialect"> +           org.teiid.dialect.TeiidDialect +       </property> + ]]></programlisting> + + <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> + + <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> + + <para>For Example:</para> + + <programlisting><![CDATA[ +            <class name="org.teiid.example.Publisher" table="BOOKS.BOOKS.PUBLISHERS"> +                  ... +            </class> + ]]></programlisting> + + </sect1> + + +</chapter> \ No newline at end of file Property changes on: trunk/documentation/client-developers-guide/src/main/docbook/en-US/content/using-hibernate.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Added: trunk/documentation/client-developers-guide/src/main/docbook/en-US/main.xml =================================================================== --- trunk/documentation/client-developers-guide/src/main/docbook/en-US/main.xml (rev 0) +++ trunk/documentation/client-developers-guide/src/main/docbook/en-US/main.xml 2010-06-23 18:47:52 UTC (rev 2287) @@ -0,0 +1,58 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + + JBoss, Home of Professional Open Source. + Copyright (C) 2008 Red Hat, Inc. + Licensed to Red Hat, Inc. under one or more contributor + license agreements. See the copyright.txt file in the + distribution for a full listing of individual contributors. + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301 USA. + +--> +<!DOCTYPE book 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; +]> + +<book> + + <bookinfo> + <title>Teiid - Scalable Information Integration</title> + <subtitle>Teiid Client Developer's Guide</subtitle> + <releaseinfo>&versionNumber;</releaseinfo> + <productnumber>&versionNumber;</productnumber> + <issuenum>1</issuenum> + <copyright> + <year>&copyrightYear;</year> + <holder>&copyrightHolder;</holder> + </copyright> + <xi:include href="../../../../../docbook/en-US/legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + </bookinfo> + + <toc/> + + <xi:include href="content/jdbc-connection.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <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" /> + +</book> + Property changes on: trunk/documentation/client-developers-guide/src/main/docbook/en-US/main.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Modified: trunk/documentation/pom.xml =================================================================== --- trunk/documentation/pom.xml 2010-06-23 17:10:08 UTC (rev 2286) +++ trunk/documentation/pom.xml 2010-06-23 18:47:52 UTC (rev 2287) @@ -16,32 +16,6 @@ <module>reference</module> <module>developer-guide</module> <module>quick-start-example</module> + <module>client-developers-guide</module> </modules> - <!--<repositories> - <repository> - <id>apiviz.release</id> - <name>APIviz releases</name> - <url>http://apiviz.googlecode.com/svn/site/repo/mvn/release</url> - <releases> - <enabled>true</enabled> - </releases> - <snapshots> - <enabled>false</enabled> - </snapshots> - </repository> - </repositories>--> - <pluginRepositories> - <pluginRepository> - <id>jboss</id> - <url>http://repository.jboss.com/maven2</url> - </pluginRepository> - <pluginRepository> - <id>jboss-org</id> - <url>http://repository.jboss.org/maven2</url> - </pluginRepository> - <pluginRepository> - <id>jboss-snapshot</id> - <url>http://snapshots.jboss.org/maven2</url> - </pluginRepository> - </pluginRepositories> </project> \ No newline at end of file