From teiid-commits at lists.jboss.org Fri Jun 25 23:26:51 2010 Content-Type: multipart/mixed; boundary="===============2983462388076593005==" MIME-Version: 1.0 From: teiid-commits at lists.jboss.org To: teiid-commits at lists.jboss.org Subject: [teiid-commits] teiid SVN: r2306 - in trunk/documentation/client-developers-guide/src/main/docbook/en-US: content and 1 other directory. Date: Fri, 25 Jun 2010 23:26:50 -0400 Message-ID: <201006260326.o5Q3QorT004367@svn01.web.mwc.hst.phx2.redhat.com> --===============2983462388076593005== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: shawkins Date: 2010-06-25 23:26:50 -0400 (Fri, 25 Jun 2010) New Revision: 2306 Removed: trunk/documentation/client-developers-guide/src/main/docbook/en-US/conte= nt/entitlements.xml Modified: trunk/documentation/client-developers-guide/src/main/docbook/en-US/conte= nt/appendix-unsupported-jdbc.xml trunk/documentation/client-developers-guide/src/main/docbook/en-US/conte= nt/jdbc-connection.xml trunk/documentation/client-developers-guide/src/main/docbook/en-US/conte= nt/jdbc-extensions.xml trunk/documentation/client-developers-guide/src/main/docbook/en-US/conte= nt/jdbc-transactions.xml trunk/documentation/client-developers-guide/src/main/docbook/en-US/conte= nt/ssl.xml trunk/documentation/client-developers-guide/src/main/docbook/en-US/conte= nt/using-hibernate.xml trunk/documentation/client-developers-guide/src/main/docbook/en-US/main.= xml Log: TEIID-1037 refining the client guide Modified: trunk/documentation/client-developers-guide/src/main/docbook/en-U= S/content/appendix-unsupported-jdbc.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/documentation/client-developers-guide/src/main/docbook/en-US/cont= ent/appendix-unsupported-jdbc.xml 2010-06-25 19:35:24 UTC (rev 2305) +++ trunk/documentation/client-developers-guide/src/main/docbook/en-US/cont= ent/appendix-unsupported-jdbc.xml 2010-06-26 03:26:50 UTC (rev 2306) @@ -14,6 +14,15 @@ then only those forms of the method specified are not supported. = + ResultSet Limitations + + TYPE_SCROLL_SENSITIVE is not supported.= + UPDATABLE ResultSets are not supp= orted. + Returning multiple ResultSets from Procedure e= xecution is not supported. + + = + = + Unsupported Classes and Methods in "java.sql" Connection Properties Deleted: trunk/documentation/client-developers-guide/src/main/docbook/en-US= /content/entitlements.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/documentation/client-developers-guide/src/main/docbook/en-US/cont= ent/entitlements.xml 2010-06-25 19:35:24 UTC (rev 2305) +++ trunk/documentation/client-developers-guide/src/main/docbook/en-US/cont= ent/entitlements.xml 2010-06-26 03:26:50 UTC (rev 2306) @@ -1,127 +0,0 @@ - - -%CustomDTD; -]> - - Entitlements/Data Roles - 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) permi= ssions for the schema defined = - by the VDB. The use of entitlements are controlled system wide with th= e property in = - <jboss-install>/server/<profile>/deploy/teiid/teiid-= jboss-beans.xml file - in bean configuration section of RuntimeEngineDeployer w= ith property useEntitlements. - = - Once the entitlements are enabled, the access permissions define= d in each VDB will then be enforced by the Teiid Server. - To process an INSERT statement, the user account requires= the following access rights: - - CREATE - on the Table being inserted= into. - CREATE - on every column being inser= ted on that Table. - = - = - To process an UPDATE statement, the user account re= quires the following access rights: - - UPDATE - on the Table being updated.= - UPDATE - on every column being updat= ed on that Table. - READ - on every column referenced in= the criteria. - = - = - To process a DELETE statement, the user account req= uires the following access rights: - - DELETE - on the Table being deleted.= - READ - on every column referenced in= the criteria. - = - - The data roles are defined inside the META-INF/vdb.xml file, f you used Designer to build your VDB. = - They defined inside the -vdb.xml file defined if you are = using the Dynamic VDBs. The below example will show - a sample "vdb.xml" file with few simple data rules. - = - For example, if a VDB schema defined a table below in its model = files named "modelName" - = - = - = - and has three (3) users "UserA", "UserB", "UserC" with following = permissions - - UserA has privileges to read, write access to TableA, = but can not delete. - UserB has no privileges that allow access to TableA - UserC has privileges that only allow read access to Ta= bleA.column1 - - - Then the resulting "vdb.xml" file will look like below. - = - - - - - - - - - Allow all, except Delete - - - modelName.TableA - - - - - - - modelName.TableA.colum1 - - - - - - - modelName.TableA.column2 - - - - - - role1 - - - - - Allow read only - - - modelName.TableA - - - - - modelName.TableA.colum1 - - - - role2 - - = - = - ]]> = - = - 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. - = - - The above xml assumes that "UserA" has "role1" role and "UserC" has "ro= le2" role and = - "UserB" does not have either "role1" or "role2" roles. = - = - 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. = - = - "vdb.xml" file is checked against the schema file vdb-deplo= yer.xsd, check the documents sections of the Teiid kit - to find a copy of the schema file. - = - Currently there is no GUI tooling support in the Designer o= r any other management tool to create this data roles = - permissions xml, however this is in our roadmap for future releases to = provide. - \ No newline at end of file Modified: trunk/documentation/client-developers-guide/src/main/docbook/en-U= S/content/jdbc-connection.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/documentation/client-developers-guide/src/main/docbook/en-US/cont= ent/jdbc-connection.xml 2010-06-25 19:35:24 UTC (rev 2305) +++ trunk/documentation/client-developers-guide/src/main/docbook/en-US/cont= ent/jdbc-connection.xml 2010-06-26 03:26:50 UTC (rev 2306) @@ -6,20 +6,18 @@ Connecting to Teiid Server = - The Teiid JDBC API provides Java Database Connectivity (JDBC) ac= cess 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. + The Teiid JDBC API provides Java Database Connectivity (JDBC) ac= cess to any Virtual Database (VDB) deployed on a Teiid Server. = + The Teiid JDBC API is compatible with the JDBC 4.0 specification; howe= ver, it does not fully support all metho= ds. + Advanced features, such as updatable result sets or SQL3 data types, a= re not supported. = - Java client applications connecting to a Teiid Server will need = to use Java 1.6 JDK. Previous versions of Java is - is not supported. + Java client applications connecting to a Teiid Server will need = to use Java 1.6 JDK. Previous versions of Java are not supported. = Before you can connect to the Teiid Server using the Teiid JDBC = API, please do following tasks first. - Install the Teiid Server. Check "Admin Guide" for= instructions. + Install the Teiid Server. See the "Admin Guide" f= or instructions. Build a Virtual Database (VDB). You can either bu= ild a "Dynamic VDB" (Designer not required), = - or you can use Eclipse based GUI tool Designer. = - Check "Reference Guide" for instructions on how to build a VDB. If= you do not know what VDB is, then start with this = + or you can use the Eclipse based GUI tool Designer. = + Check the "Reference Guide" for instructions on how to build a VDB= . If you do not know what VDB is, then start with this = document. Deploy the VDB into Teiid Server. Check "Admin Gu= ide" for instructions. Start the Teiid Server (JBoss AS), if it is not a= lready running. @@ -27,211 +25,47 @@ = Now that you have the VDB deployed in Teiid Server, client appli= cations = 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 = - JDBC here. Teiid kit ships with - teiid-{version}-client.jar in the "jboss-install/se= rver/<profile>/lib" directory. This JAR file = - contains Teiid JDBC Driver and DataSource classes. Add this JAR to you= r Java client application's classpath. - + JDBC here. Teiid ships with + teiid-&versionNumber;-client.jar in the "jboss-inst= all/server/<profile>/lib" directory. = = - - TeiidDriver - JDBC connections using = + + Main classes in the client JAR: + org.teiid.jdbc.TeiidDriver - allows = JDBC connections using the DriverManager class. - TeiidDatasource - JDBC connections u= sing = - DataSource class. You can use this to create JDBC XA c= onnections. - + org.teiid.jdbc.TeiidDatasource - all= ows JDBC connections using the + DataSource or XADataSource class. You sh= ould use this class to create managed or XA connections. + + = + Once you have established a connection with the Teiid Server, yo= u can use standard JDBC API classes, like = + DatabaseMetadata and ResultSetMetadata, to interrogate metadata an= d Statement classes to execute queries. + = - Driver Based Connection - Add the above jar file in your application's class path and = use org.teiid.jdbc.TeiidDriver as the driver class. = - Use the following URL format for JDBC connections: - + Driver Connection + Use org.teiid.jdbc.TeiidDriver as the driver cl= ass. = - jdbc:teiid:<vdb-name>@mm[s]://<host>:&= lt;port>;[prop-name=3Dprop-value;]* + Use the following URL format for JDBC connections:= jdbc:teiid:<vdb-name>@mm[s]://<host>:<port>;[prop-name=3D= prop-value;]* = - Where + URL Components <vdb-name> - Name of the VDB you are con= necting to - mm - defines Teiid JDBC protocol, mms defines = a secure channel (see how to turn on SSL) + mm - defines Teiid JDBC protocol, mms defines = a secure channel (see the SSL chapter for more= ) <host> - defines the server where the Te= iid Server is installed <port> - defines the port on which the T= eiid Server is listening for incoming JDBC connections. [prop-name=3Dprop-value] - additionally you ca= n supply any number of name value pairs separated by semi-colon = - [;], further refining the connection. All supported URL proper= ties are defined here. + [;]. All supported URL properties are defined in the connection properties section. Prope= rty values should be URL encoded if they contain reserved characters, e.g. = ('?', '=3D', ';', etc.) - = - Sample Code: - = - = - - = - - Datasource Based Connection - To use a data source based connection use org.teiid.jd= bc.TeiidDataSource 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 Serializabl= e, so it possible for it to be used with - JNDI naming services. = - Sample Code: - = - = - All the Teiid Data Source supported properties are defined here. - = - Teiid supports the XA protocol, if all sources that Tei= id is integrating = - also support XA and are configured as XA data sources. If one or mo= re sources are not XA capable, they can be = - marked as read-only and still participate in an XA transaction with= the remaining sources. - = - - = - - As Data Source in JBoss AS - Teiid can be configured as a JDBC data source in the JBoss A= pplication Server and can be accessed = - from the JNDI for your JEE application. Deploying Teiid as data s= ource in JBoss AS is exactly same as = - deploying any other RDBMS resources like Oracle or DB2. - = - 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 respe= ctive documentation of the environment = - in which you are deploying. - - Copy the teiid-${version}-client.jar into = - <jboss-install>/server/default/lib director= y. - Create a "teiid-ds.xml" file in <jbos= s-install>/server/<profile>/deploy = - directory. Based on the type of deployment the contents of th= e deployment file will look like the below = - code fragment. - - - DataSource based connection - The below XML code sample will create an XA data source = in the JBoss AS using the = - Teiid DataSource class org.teiid.jdbc.TeiidDataSource. Make sure = - you supply the correct DatabaseName, ServerName, Port number an= d 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> = - = - - - TEIID-DS - org.teiid.jdbc.TeiidDataSource - myVDB - localhost = - 31000 = - admin = - password = - true - false - - = - - 5 = - 10 = - = - = - ]]> = - - - Driver based connection - You can also use Teiid's JDBC driver class org.teii= d.jdbc.TeiidDriver to create a data source - = - = - TEIID-DS = - jdbc:metamatrix:myVDB(a)mm://localhost= :31000 = - org.teiid.jdbc.TeiidDriver = - admin - teiid - = - - 5 = - 10 - = - - ]]> = - - - Local JDBC Connection - 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 b= ased 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: - - - TEIID-DS - org.teiid.jdbc.TeiidDataSource - myVDB - admin = - password = - true - false - - = - - 5 = - 10 = - = - = - ]]> - In the absense of the "ServerName" and "PortNumber", the = JDBC API will lookup a local Teiid runtime in = - the same VM. = - - = - - = - - Using Multiple Hosts - When Teiid Server is deployed on multiple servers for scalbi= lity, then your application that using - Teiid JDBC API can automatically use all Teiid Servers in that gro= up. 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 t= he Teiid server from the list and will have session = - established with that server. In the case of failure of the connec= ted server, the client will try to automatically failover = - to other available servers, if the "autoFailover" connection prope= rty is set to "true". Here is example URL connection string - = - = - = - Currently when the fail over happens, the user is re-authent= icated with the new server. The clustering = - feature coming up in the Teiid 7.1 release will define how the tra= nsparent session fail over will occur with out the = - re-authentication. - = - You can also use this feature to distribute the query load a= mong various avaialble Teiid Servers available. = - Load balancing happens automatically, when you are using a data so= urce along with connection pooling. Each time a connection is = - grabbed from the pool, it will randomly select a Teiid Server to d= istribute the load. Note, that load balacing feature = - is not avaialble if you are using Teiid Driver to make your connec= tion. - = - 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. - - = - - JDBC Connection Properties + + URL Connection Properties The following table shows all the supported connection prope= rties that can used with Teiid = JDBC Driver URL connection string, or on the Teiid JDBC Data Sourc= e class. =
Connection Properties - - + + @@ -257,18 +91,18 @@ int - Size of the resultset; The default size if = 500. <=3D0 indicates that the value is not set + Size of the resultset; The default size if = 500. <=3D0 indicates that the default should be used. partialResultsMode - String + boolean - Enable/disable support partial results mode= . Default is "off". Allowed values are "on" or "off" + Enable/disable support partial results mode= . Default false. See the partial result= s section. - + autoCommitTxn @@ -279,11 +113,12 @@ = This determines how a executed command nee= ds to be transactionally wrapped inside the = Teiid engine to maintain the data integrit= y. - + ON - Always wrap comm= and in distributed transaction OFF - Never wrap comma= nd in distributed transaction DETECT (default)- If t= he executed command is spanning more than one source it automatically uses = distributed transaction. - + + Transa= ctions with JDBC for more information. @@ -293,7 +128,7 @@ boolean - If "true", the autoCommit setting, commit = and rollback will be ignored for local transactions. + If "true", the autoCommit setting, commit a= nd rollback will be ignored for local transactions. Default false. @@ -333,59 +168,70 @@ Version number of the VDB - = - + resultSetCacheMode boolean - ResultSet caching is turned on/off; Valid v= alues are true|false + ResultSet caching is turned on/off. Default= false. = = - SHOWPLAN + autoFailover - String + boolean - Can be one of ON|OFF|DEBUG - + If true, will automatically select a new se= rver instance after a communication exception. Default false. = + This is typically not needed when connections are = managed, as the connection can be purged from the pool. + = = - NoExec + SHOWPLAN - boolean + String - true|false - = + (typically not set as a connection property= ) Can be ON|OFF|DEBUG; ON returns the query plan along with the results and= DEBUG additionally prints the query planner debug information in the log a= nd returns it with the results. Both the plan and the log are available th= rough JDBC API extensions. Default OFF. + = - autoFailover + NoExec - boolean + String - If true, will automatically select a new se= rver instance after a communication exception. + (typically not set as a connection property= ) Can be ON|OFF; ON prevents query execution, but parsing and planning will= still occur. Default OFF. = + = -
= - = - All the above properties have "set" methods on the org= .teiid.jdbc.TeiidDataSource. = - Some of the the properties that are assumed from the URL string ha= ve addtional "set" methods, those proeprties are described in the - following table. = - = - +
= + + = + + + + Datasource Connection + To use a data source based connection, use org.teiid.j= dbc.TeiidDataSource as the data source class. = + The TeiidDataSource is also an XADatasource. Teiid Da= taSource class is also Serializable, so it possible for it to be used with + JNDI naming services. + = + Teiid supports the XA protocol, XA transactions will be= extended to Teiid sources that also support XA. = + = + All the properties (except for version, which is known on Te= iidDataSource as DatabaseVersion) defined in the connection propertieshave corresponding "set" methods = on the org.teiid.jdbc.TeiidDataSource. = + Properties that are assumed from the URL string have addtional "se= t" methods, which are described in the following table. + = + Datasource Properties - - + + @@ -413,6 +259,24 @@ Server where the Teiid runtime installed + + + + AdditionalProperties + + + String + + Optional setting of properties that has the= same format as the property string in a connection URL. + PortNumber @@ -429,7 +293,7 @@ boolean - Secure connection. Flag to indicate to use = SSH based connection between client and server + Secure connection. Flag to indicate to use = SSL (mms) based connection between client and server @@ -451,10 +315,165 @@ = = = -
= + = + + = + + Standalone Application + To use either Driver or DataSource based connections, add the clie= nt JAR to your Java client application's classpath. See the simple client = example in the kit for a full Java sample of the following. = + = + + Driver Connection + = + Sample Code: + = + = + + = + + Datasource Connection + = + Sample Code: + = + = + + = + + = + + JBoss AS Data Source + Teiid can be configured as a JDBC data source in the JBoss A= pplication Server to be accessed = + from JNDI or injected into your JEE applications. Deploying Teiid= as data source in JBoss AS is exactly same as = + deploying any other RDBMS resources like Oracle or DB2. = - Once you have established a connection with the Teiid Server= , you can use any standard JDBC API like = - DatabaseMetadata and ResultSetMetadata classes to interrogate meta= data of the deployed VDB. You can also use = - data processing classes and objects and process the results. = + 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 respe= ctive documentation of the environment = + in which you are deploying. + = + + Installation Steps + If Teiid is not installed in the AS instance, = copy the teiid-&versionNumber;-client.jar into = + <jboss-install>/server/<profile>/lib = directory. + Create a "<datasource name>-ds.xml" file= in <jboss-install>/server/<profile>/deploy = + directory. Based on the type of deployment (XA, driver, or lo= cal), the contents of the file will be different. See the following sectio= ns for more. + + = + Tje data source will then be accessable through the JNDI nam= e specified in the -ds.xml file. + = + + DataSource Connection + Make sure you know the correct DatabaseName, ServerName, = Port number and credentials that are specific = + to your deployment environment. = + + Sample XADataSource in the JBoss AS using the = + Teiid DataSource class <code>org.teiid.jdbc.TeiidDataSource</co= de> + = + + + TEIID-DS + org.teiid.jdbc.TeiidDataSource + myVDB + localhost = + 31000 = + admin = + password = + true + + false + + + + SELECT 1 + 5 = + 10 = + = +]]> = + + + Driver based connection + You can also use Teiid's JDBC driver class org.teii= d.jdbc.TeiidDriver to create a data source + = + = + TEIID-DS = + jdbc:metamatrix:myVDB(a)mm://localhost:31000 = + org.teiid.jdbc.TeiidDriver = + admin + teiid + = + + SELECT 1 + 5 = + 10 + = +]]> = + + + Local JDBC Connection + 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 b= ased JDBC connection. + You can use slightly modified data source configuration to make= a "local" connection, where the JDBC API will lookup a local Teiid runtime= in the same VM. + + Local data source + + + TEIID-DS + org.teiid.jdbc.TeiidDataSource + myVDB + admin = + password = + true + false + + + + SELECT 1 + 5 = + 10 = + = +]]> + + This is essentially the same as the XA configuration, but= "ServerName" and "PortNumber" are not specified. = + + = + = + + = \ No newline at end of file Modified: trunk/documentation/client-developers-guide/src/main/docbook/en-U= S/content/jdbc-extensions.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/documentation/client-developers-guide/src/main/docbook/en-US/cont= ent/jdbc-extensions.xml 2010-06-25 19:35:24 UTC (rev 2305) +++ trunk/documentation/client-developers-guide/src/main/docbook/en-US/cont= ent/jdbc-extensions.xml 2010-06-26 03:26:50 UTC (rev 2306) @@ -6,12 +6,11 @@ Teiid extensions to the JDBC API = - + Statement Extensions - Teiid provides some extensions to the JDBC statement interfa= ce. The Teiid Statement extension interface = - is defined by org.teiid.jdbc.TeiidStatement. To use t= he extension interface, simply = - cast or unwap the statement returned by the Connection to the exte= nsion interface. = - The following methods are provided on the extension interface: + The Teiid statement extension interface, = + org.teiid.jdbc.TeiidStatement, provides functionality= beyond the JDBC standard. To use the extension interface, simply = + cast or unwap the statement returned by the Connection. The follo= wing methods are provided on the extension interface: = Connection Properties @@ -27,133 +26,79 @@ - getAnnotations() + getAnnotations - Get the query engine annotations if the = previously executed command used OPTION PLANONLY or OPTION SHOWPLAN + Get the query engine annotations if the = statement was last executed with SHOWPLAN ON|DEBUG. Each org.teiid.c= lient.plan.Annotation contains a description, = + a category, a severity, and possibly a resolution of notes recorde= d during query planning that can be used to understand choices made by the = query planner. = - getDebugLog() + getDebugLog - Get the debug log if the previously exec= uted command used OPTION DEBUG. + Get the debug log if the statement was l= ast executed with SHOWPLAN DEBUG. = - getExecutionProperty(String) + getExecutionProperty - Get the current value of an execution pr= operty on this statement object. + Get the current value of an execution pr= operty on this statement object. = - getPlanDescription() + getPlanDescription - Get the query plan description if the pr= eviously executed command used OPTION PLANONLY or OPTION SHOWPLAN. + Get the query plan description if the st= atement was last executed with SHOWPLAN ON|DEBUG. The plan is a tree made = up of org.teiid.client.plan.PlanNode objects. = + Typically PlanNode.toString() or = PlanNode.toXml() will be used to convert the plan into = a textual form. - - getRequestIdentifier() + getRequestIdentifier - Get an identifier for the last command e= xecuted on this statement. If no command has been executed yet, null is re= turned. + Get an identifier for the last command e= xecuted on this statement. If no command has been executed yet, null is re= turned. = - setExecutionProperty(String, String) + setExecutionProperty - Set the execution property on this state= ment. Execution properties are described in more detail below. + Set the execution property on this state= ment. See the execution properties<= /link> section for more information. = + It is generally preferable to use the SET statement unless the execution property = applies only to the statement being executed. = - setPayload(Serializable) + setPayload - Set a per-command payload to pass to tra= nslators. Currently = - this only used for sending hints for Oracle = - data source. For security purposes, this is no= longer recommended. + Set a per-command payload to pass to tra= nslators. Currently = + the only built-in use is for sending hints for= Oracle = + data source. -
= + + = - - Debug Information - = - Debug information is only returned when using query options. - These options are set on the session using the = - SET keyword. The available options for debugging pur= poses are: - = - - SET Syntax: - - - SET parameter value - - - - - Syntax Rules: - - - Both parameter and value must be simple literals - t= hey cannot contain spaces. - - - The value is also not treated as an expression and w= ill not be evaluated prior to being set as the parameter value. - - - The SET command can be used to control planning and executio= n. - - - - SET SHOWPLAN [ON|DEBUG|OFF] - ON returns the query p= lan along with the results and DEBUG additionally prints the query planner = debug information in the log and returns it with the results. Both the pla= n and the log are available through JDBC API extensions. - - - SET NOEXEC [ON|OFF] - ON prevents query execution, b= ut parsing and planning will still occur. - - = - = - Use the Statement object to execute the above command to set= the required options. - = - getDebugLog() - method can be used to o= btain the output from = - the SET SHOWPLAN DEBUG option. - = - getPlanDescription() - method be used t= o obtain the query plan from SET SHOWPLAN ON. = - The plan is a tree made up of PlanNode objects. The = PlanNode interface is = - also in the org.teiid.client.plan package. A PlanNod= e 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. - = - getAnnotations() - method can be called= to obtain any annotations = - objects. Each annotation contains a description, = - a category, a severity, and possibly a resolution of notes recorde= d during query planning = - that can be used to understand choices made by the query planner. = This is also available when SET SHOWPLAN is used. - - = - + Execution Properties - When your application executes queries, it can specify optio= nal features for each query. = - Your application can use some of these options only in certain con= texts. These execution properties = - share a common interface when they are being set. The execution p= roperties are defined by = - constants in the org.teiid.jdbc.ExecutionProperties i= nterface. - You can get and set the following execution properties to mo= dify the behavior of query execution by calling - setExecutionProperty method on the org.teiid.jd= bc.TeiidStatement class. + Execution properties may be set on a per statement basis thr= ough the TeiidStatement= interface or on the connection via the SET statement. + For convenience, the property keys are defined by constants on the= org.teiid.jdbc.ExecutionProperties interface. = Execution Properties @@ -162,74 +107,123 @@ - Property Name + Property Name/String Constant Description - PROP_TXN_AUTO_WRAP + PROP_TXN_AUTO_WRAP / autoCommitTxn - Determines how transactions are automati= cally wrapped used with = - commands when auto commit mode is set to =E2= =80=9Ctrue=E2=80=9D. Does not affect transaction = - behavior when auto commit mode is set to =E2= =80=9Cfalse=E2=80=9D. See = - =E2=80=9CT= ransactions with JDBC=E2=80=9D for more information. + Same as the connection property. - PROP_PARTIAL_RESULTS_MODE + PROP_PARTIAL_RESULTS_MODE / partialResul= tsMode - Determines whether partial results mode = is used for this query or not. + See the partial results section. - PROP_XML_FORMAT + PROP_XML_FORMAT / XMLFormat - Determines the formatting of the returne= d XML documents. The two supported = - formats are XML_TREE_FORMAT, which is a format= ted tree with indentation and = - linefeeds or XML_COMPACT_FORMAT which is a com= pact message with no extra whitespace. = - If no value is set for this property (the defa= ult), then the formatting mode = - specified in the XML document model is used. + Determines the formatting of XML documen= ts returned by XML document models. See the document formatting section. = - PROP_XML_VALIDATION + PROP_XML_VALIDATION / XMLValidation - Determines whether xml result documents = will be validated = - against their schema before being returned. I= f schema validation fails, = - a warning message is returned along with the r= esult documents. = - Using validation significantly reduces perform= ance. + Determines whether XML documents returne= d by XML document models will be validated = + against their schema after processing. See th= e document validation section.= = - RESULT_SET_CACHE_MODE + RESULT_SET_CACHE_MODE / resultSetCacheMo= de - Result set caching provides caching of c= omplete 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. Additi= onal control is provided in the JDBC = - driver to turn off use of the result set cache= on a per-query basis. + Same as the connection property. - = = + + + + SQL_OPTION_SHOWPLAN / SHOWPLAN + + + Same as the connection property. + + + + + NOEXEC / NOEXEC + + + Same as the connection property. + +
= - Each of these properties are described in detail in the foll= owing sections. = - + = = - + + Set Statement + = + Execution properties may also be set on the connection by us= ing the SET statement. = + The SET statement is not yet a language feature of Teiid and is ha= ndled only in the JDBC client. + = + + SET Syntax: + + + SET parameter value + + + + + Syntax Rules: + + + Both parameter and value must be simple literals - t= hey cannot contain spaces. + + + The value is also not treated as an expression and w= ill not be evaluated prior to being set as the parameter value. + + + The SET statement is most commonly used to control planning = and execution. + + + SET SHOWPLAN (ON|DEBUG|OFF) + + + SET NOEXEC (ON|OFF) + + = + = + + Enabling Plan Debug + Statement s =3D connection.createStatement(); +s.execute("SET SHOWPLAN DEBUG"); +... +Statement s1 =3D connection.createStatement(); +ResultSet rs =3D s1.executeQuery("select col from table"); +TeiidStatement ts =3D s1.unwrap(TeiidStatement.class); +String debugLog =3D ts.getDebugLog(); = + + + + = + Partial Results Mode - The Teiid Server supports a =E2=80=9Cpartial results=E2=80= =9D query mode. This mode changes the behavior of the = + The Teiid Server supports a "partial results" query mode. T= his mode changes the behavior of the = query processor so the server returns results even when some data = sources are unavailable. = For example, suppose that two data sources exist for differe= nt suppliers and your = @@ -240,7 +234,7 @@ the same query in =E2=80=9Cpartial results=E2=80=9D query mode, th= e server returns data from the = running data source and no data from the data source that is down.= = - When using =E2=80=9Cpartial results=E2=80=9D mode, if a sour= ce throws an exception during = + When using "partial results" mode, if a source throws an exc= eption during = processing it does not cause the user=E2=80=99s query to fail. Ra= ther, that source is treated = as returning no more rows after the failure point. = Most commonly, that source will return 0 rows. @@ -253,63 +247,34 @@ For each source that is excluded from the query, a warning w= ill be generated = describing the source and the failure. These warnings can be obta= ined from the = ResultSet.getWarnings() method. This method returns = a SQLWarning object but = - in the case of =E2=80=9Cpartial results=E2=80=9D warnings, this wi= ll be an object of = + in the case of "partial results" warnings, this will be an object = of = type org.teiid.jdbc.PartialResultsWarning class. Thi= s class can be = used to obtain a list of all the failed sources by name and to obt= ain = the specific exception thrown by each resource adaptor. = Below is an example of printing the list of failed sources:<= /para> - = - + = + = - + XML extensions - Your application can use a statement object to execute queri= es that return XML documents. = - The query must specify a valid document in VDB, or should have use= d SQL XML functions = - to create a XMl document. When your = - application executes an XML query, the Teiid Server returns a Resu= ltSet = - object that has a single column named xml and often a single row, = which = - represents a document. Depending on the XML virtual document mode= l, = - multiple documents may be returned - - XML Streaming - XML documents are streamed from Teiid Server to the Teii= d JDBC API.=C2=A0=C2=A0 = - 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 who= le document = - must be materialized on the server. Therefore memory issues m= ay occur for large documents. = - A result document can be obtained from the JDBC resultset usin= g getSQLXML method. - - The document is broken into pieces when being created an= d streamed.=C2=A0 = - The maximum size of each piece in the stream can be configured= with the = - "lobChunkSizeInKB" system property on the Server.= The default value is 100 KB.=C2=A0 = - At any given time, this is the maximum amount of memory that c= an be held by a particular = - XML query against the system.=C2=A0 In heavily loaded or memor= y-constrained scenarios, = - this value can decrease the amount of memory used.=C2=A0 As a = side effect, streaming will o - ccur in smaller pieces, reducing initial document response tim= e while = - increasing full response time (as this is less efficient).=C2= =A0 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 - - = - + The XML extensions apply on to XML resutls from queries to X= ML document models, and not to XML produced by SQL/XML or read from some ot= her source. + Document formatting The PROP_XML_FORMAT execution property can be set to mod= ify the way that = - XML documents are formatted on return. Valid values for the c= onstant = + XML documents are formatted from XML document models. Valid v= alues for the constant = are defined in the same ExecutionProperties interface: XML_TREE_FORMAT - Returns a v= ersion of the XML formatted for display. = @@ -319,37 +284,18 @@ optimal performance. The XML is a single long string with= out any = unnecessary white space. Not Set - If no format is set, the formatt= ing flag on the = - XML document in the original model is honored. + XML document in the original model is honored. This may p= roduce either the =E2=80=9Ctree=E2=80=9D or =E2=80=9Ccompact=E2=80=9D = + form of the document depending on the document setting.= - The default is to set neither format and to use the form= atting flag specified = - in the document model itself. This may produce either the =E2= =80=9Ctree=E2=80=9D or =E2=80=9Ccompact=E2=80=9D = - form of the document depending on the document setting. - + = - + Schema validation The PROP_XML_VALIDATION execution property = can be set to indicate that = - the server should validate documents against their schema befo= re returning them = - to the client. If schema validation is on, then the server wi= ll throw = - an exception if the document does not conform to the schema it= is associated with. = + the server should validate XML document model documents agains= t their schema before returning them = + to the client. If schema validation is on, then the server se= nd a SQLWarning if the document does not conform to the schema it is associ= ated with. = Using schema validation will reduce the performance of your XM= L queries. - = - Schema validation must materialize the entire docu= ment on the server to = - validate the schema. Thus, schema validation will prevent str= eaming of = - XML results and may increase server memory usage. - = - - + + = - - = - - ResultSet Limitations - - Supports only FORWARD_ONLY and SCROLL_INSENSITIVE scroll modes. - Supports only READ_ONLY result se= ts. UPDATABLE ResultSets are not supported. - Returning multiple ResultSets from Procedure e= xecution is not supported. - Closing the ResultSet does not close the State= ment object. Statement must be closed to free the resources. - - = \ No newline at end of file Modified: trunk/documentation/client-developers-guide/src/main/docbook/en-U= S/content/jdbc-transactions.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/documentation/client-developers-guide/src/main/docbook/en-US/cont= ent/jdbc-transactions.xml 2010-06-25 19:35:24 UTC (rev 2305) +++ trunk/documentation/client-developers-guide/src/main/docbook/en-US/cont= ent/jdbc-transactions.xml 2010-06-26 03:26:50 UTC (rev 2306) @@ -10,40 +10,34 @@ by the Teiid Server as XA transactions. = See the JTA specification for more on XA Transactions. = - Even though in client application, Teiid data source is vi= ewed 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 trans= action. These = - transaction scopes define the user = - application's interaction with Teiid runtime. - = - Using Local Transactions + Local Transactions The Connection class uses the "autoCommit" flag to explicitl= y control local transactions. By default, autoCommit = - is set to "true", which indicates request level or implicit transa= ction control. Following is an example of = + is set to "true", which indicates request level or implicit transa= ction control. example of = how to use local transactions by setting the autoCommit flag to fa= lse. - = - = + + Local transaction control using autoCommit + = + This example demonstrates several things: - Setting autoCommit flag to false. This will star= t a transaction bound to the current JDBC client thread. + Setting autoCommit flag to false. This will star= t a transaction bound to the connection. Executing multiple updates within the context of = the transaction. When the statements are complete, the transaction= is committed by calling commit(). If an error occurs, the transaction is rolled bac= k using the rollback() method. = @@ -66,20 +60,18 @@ should perform no action regardless of the commands being exec= uted. To turn off the use of local transactions, = add this property to the JDBC connection URL = - + = - WARNING:Turning off local transactions can be dang= erous and can result in inconsistent = + 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 t= hat = - the calling application does not need local transactions. + the calling application does not need local transactions. = - Using Request Level Transactions - Request level transactions will be implicitly used when the = request is not in the = + Request Level Transactions + Request level transactions are used when the request is not = in the = scope of a global or local transaction, which implies "autoCommit"= is "true". In a request = level transaction, your application does not need to explicitly ca= ll commit or rollback, = rather every command is assumed to be its own transaction that wil= l automatically = @@ -98,29 +90,30 @@ wrapping off (completely) to maximize performance. = - you can set your transaction wrapping to one of the followin= g modes. - = - - = - = + You can set your transaction wrapping to one of the followi= ng modes: ON: This mode always wra= ps every command in a transaction = without checking whether it is required. This is the safest m= ode. OFF: This mode never aut= omatically wraps a command in a = transaction or check whether it needs to wrap a command. This= mode can be dangerous as it will = - allow multi-source updates outside of a transaction without an= error. This mode has best = + allow multiple source updates outside of a transaction without= an error. This mode has best = performance for applications that do not use updates or transa= ctions. DETECT: This mode assum= es that the user does not know to execute = - multi-source updates in a transaction. The Teiid Server check= s every command to see whether it = - is a multi-source update and wraps it in a transaction. If it = is single source then uses + multiple source updates in a transaction. The Teiid Server ch= ecks every command to see whether it = + is a multiple source update and wraps it in a transaction. If = it is single source then uses the source level command transaction. = You can set the transaction mode as a property when you esta= blish the Connection or on a = per-query basis using the execution properties. For more informat= ion on execution = properties, see the section =E2=80=9CExecution Properties=E2=80=9D + = + + Multiple Insert Batches + When issuing an INSERT with a query expression (or the depre= cated SELECT INTO), multiple insert batches handled by separate source INSE= RTS may be processed by the Teiid server. + Care should be taken to ensure that targeted sources support XA o= r that compensating actions are taken in the event of a failure. = + + = = @@ -132,38 +125,36 @@ such as JBoss, WebSphere, or Weblogic, the resulting connection wi= ll already be = associated with the current XA transaction. No additional client = JDBC code is = necessary to interact with the XA transaction. + >Manual Usage of XA transactions + .getXAConnection(); + xaRes =3D xaConn.getXAResource(); + Xid xid =3D ; + conn =3D xaConn.getConnection(); + stmt =3D conn.createStatement(); + + xaRes.start(xid, XAResource.TMNOFLAGS); + stmt.executeUpdate("insert into =E2=80=A6"); + + xaRes.end(xid, XAResource.TMSUCCESS); + = + if (xaRes.prepare(xid) =3D=3D XAResource.XA_OK) { + xaRes.commit(xid, false); + } +} +catch (XAException e) { + xaRes.rollback(xid); +} = +finally { + +}]]> = + = - Applications may also utilize Teiid JDBC XA transactions man= ually, such as shown in the following example: - .getXAConnection(); - xaRes =3D xaConn.getXAResource(); - Xid xid =3D ; - conn =3D xaConn.getConnection(); - stmt =3D conn.createStatement(); - = - xaRes.start(xid, XAResource.TMNOFLAGS); - stmt.executeUpdate("insert into =E2=80=A6"); - - xaRes.end(xid, XAResource.TMSUCCESS); - = - if (xaRes.prepare(xid) =3D=3D XAResource.XA_OK) { - xaRes.commit(xid, false); - } - } - catch (XAException e) { - xaRes.rollback(xid); - } = - finally { - - } - ]]> = - = With the use of global transactions multiple Teiid XAConnect= ions may participate in the = same transaction. It is important to note that the Teiid JDBC XAR= esource "isSameRM" method only returns = "true", if connections are made to the same server instance in a c= luster. If the Teiid connections are to different = @@ -175,21 +166,7 @@ = - SELECT INTO Transaction - The SELECT INTO command, even against a single = source, requires a transaction. = - Issuing a SELECT INTO command from within a virtual p= rocedure or from client application requires = - users to do one of the following: - = - - Use XA connectors with a global, local, or req= uest level (automatic wrapping set = - to DETECT or ON) transaction. - Do not use s global or local transaction and s= et the automatic = - wrapping to OFF to intentionally avoid using a transaction. - - - = - - Transaction Restrictions + Restrictions Application Restrictions The use of global, local, and request level transactions= are all mutually exclusive. = @@ -202,8 +179,7 @@ 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 thr= u Teiid. If source system do not support the XA, then it can not particila= te in the distributed transaction. However, the source is still - eligible to participate in data integration usecase with out t= he XA support, however it will not be part of the on going = - transaction. = + eligible to participate in data integration with out the XA su= pport = = The participation in the XA = transaction is automatically determined based on the resource = adaptors XA capability. It is user's repsonsiblity to make sure Modified: trunk/documentation/client-developers-guide/src/main/docbook/en-U= S/content/ssl.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/documentation/client-developers-guide/src/main/docbook/en-US/cont= ent/ssl.xml 2010-06-25 19:35:24 UTC (rev 2305) +++ trunk/documentation/client-developers-guide/src/main/docbook/en-US/cont= ent/ssl.xml 2010-06-26 03:26:50 UTC (rev 2306) @@ -4,34 +4,24 @@ %CustomDTD; ]> - Secure Client Connections using SSL in Teiid + SSL Client Connections = This chapter will shows you various security configurations = that can be used with Teiid in securing your data access. Note that da= ta level - security (data entitlements) are= explained in separate chapter. + security (data roles) are explai= ned in separate chapter. = Default Security - By default, access to Teiid is NOT secure. The login modules= are only = - backed by file based authentication, and it also creates well know= n user = - name and password for easy access for users who want to give a qui= ck try of the Teiid. - The same is also true for making the connection to the Admin Conso= le 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 instr= uctions as to how to - configure different login modules to secure the access. = - This chapter is dedicated to discuss about securing the comm= unication channels, = - like the socket connection between your client application and Tei= id Server. If you are always using a = - local connection, then y= ou may not need to secure the channels as - cleint and server are in the same VM process. + If you are always using a = + local connection, then y= ou do need to secure a channels. = By default all sensitive (non-data) messages between client = and server = are encrypted using a Diffy-Hellman = key that is negotiated per connection. This = encryption is controlled by clientEncryptionEnabled p= roperty in JdbcSslConfiguration and = AdminSslConfiguration sections = - in <jboss-install>/server/<profile>/deploy/teiid= /teiid-jboss-beans.xml file. So, the = - passwords are never sent in the clear channel during session estab= lishment. + in <jboss-install>/server/<profile>/deploy/teiid= /teiid-jboss-beans.xml file. = @@ -66,198 +56,132 @@ client.keystore - client's private key<= /listitem> client.truststore - has client's public key - or - - server.keystore - has server's private key, cl= ient's pulic key - client.keystore - client's private key, and se= rver's public key - = - - Configuring SSL in Teiid Server - The Teiid's configuration file = - <jboss-install>/server/<profile>/deploy/teiid/te= iid-jboss-beans.xml, = - contains the properties to configure SSL. Teiid Server, has two se= parate connection profiles. One for the JDBC - connections and the other for the Admin connections. They both hav= e separate SSL configuration - properties, so besure to know which properties that you are editin= g. - - JDBC Connection - The JdbcSslConfigurati= on bean configuration defines this. - Admin Connection - The AdminSslConfigura= tion bean configuration defines this. - - The configurations look same as below sample. - - false - cert.keystore - passwd - JKS - SSLv3 - false - cert.truststore - passwd - - 1-way - true - - ]]> = - The properties are described below. - - sslEnabled - true|false, SSL usage either turn= ed ON or OFF - sslProtocol- Type of SSL protocol to be used. = Default is SSLv3 - keystoreType - Keystore type created by the ke= ytool. Default "JKS" is used. - authenticationMode - anonymous|1-way|2-way, T= ype of SSL mode, see = - above about different SSL modes available. - keymanagementAlgorithm - Type of key algorithm= used. Default = - is based upon the VM, e.g. "SunX509" - keystoreFilename - The file name of the keysto= re, which contains the = - private key of the Server. This must be available in the class= path of Teiid Server - keystorePassword - password for the keystore.<= /para> - truststoreFilename - if "authenticationMode" i= s chosen = - as "2-way", then this property must be provided. This is the t= ruststore 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" pro= perty. - truststorePassword - password for the truststo= re. - = - = - Once all the properties are defined, make sure the certif= icates are in the right place, then restart the = - Teiid server to start accepting connections using SSL. - - = - Configuring SSL in Teiid's Client - Configuring any Java client program with SSL involves modify= ing scripts that = - launch the client programs to define few Java VM system propertie= s using "-Dkey=3Dvalue" format. The = - following sections define the system properties required for each = SSL mode. Note that when = + Client SSL Settings + The = + following sections define the properties required for each SSL mod= e. Note that when = connecting to Teiid Server with SSL enabled, you MUST use = the "mms" protocol, instead of "mm" in the JD= BC connection URL, for example = - jdbc:teiid:<myVdb>@mms://<ho= st>:<port> + jdbc:teiid:<myVdb>@mms://<host= >:<port> = - There are two different sets of properties that a client can= configure to enable 1-way or 2-way SSL. + There are two different sets of properties that a client can= configure to enable 1-way or 2-way SSL. = - Option 1: Java SSL properties (recommended) + Option 1: Java SSL properties These are standard Java defined system properties to con= figure the SSL under any JVM, Teiid is not = unique in its use of SSL. Provide the following system propert= ies to the client VM process. = - 1-way SSL - /server.truststore (required) - -Djavax.net.ssl.trustStorePassword=3D (optional) = - -Djavax.net.ssl.keyStoreType (optional) - ]]> + + 1-way SSL + /ser= ver.truststore (required) +-Djavax.net.ssl.trustStorePassword=3D (optional) = +-Djavax.net.ssl.keyStoreType (optional)]]> + = - 2-way SSL - /client.keystore (required) - -Djavax.net.ssl.keyStrorePassword=3D (optional) - -Djavax.net.ssl.trustStore=3D/server.truststore (requ= ired) - -Djavax.net.ssl.trustStorePassword=3D (optioanl) - -Djavax.net.ssl.keyStroreType=3D (optional) - ]]> = - = + + 2-way SSL + /clien= t.keystore (required) +-Djavax.net.ssl.keyStrorePassword=3D (optional) +-Djavax.net.ssl.trustStore=3D/server.truststore (required) +-Djavax.net.ssl.trustStorePassword=3D (optioanl) +-Djavax.net.ssl.keyStroreType=3D (optional)]]> = + = = Option 2: Teiid Specific Properties - Use this option for "anonymous" mod= e or when the above "javax" based properties = + Use this option for anonymous mode = or when the above "javax" based properties = are already in use by the host process. For example if your cl= ient application is a Tomcat = process that is configured for https protocol and the above Ja= va based properties are = already in use, and importing Teiid-specific certificate keys = into those https = certificate keystores is not allowed. = - 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-s= ettings.properties" file = - can be found inside the "teiid-{version}-client.jar" file at t= he root directory location. = + In this scenario, a different set of Teiid-specific SSL = properties can be set as system properties or defined inside = + the "teiid-client-settings.properties" file. The "teiid-client= -settings.properties" file = + can be found inside the "teiid-&versionNumber;-client.jar" fil= e at the root. = Extract this file, or make a copy, change the property values = required for the chosen SSL mode, = and place this file in the client application's classpath befo= re = - the "teiid-{version}-client.jar" file. + the "teiid-&versionNumber;-client.jar" file. = - SSL properties inside "teiid-client-settings.properties= " are shown below - (read more property comments inline). Provide the following re= quired properties for different SSL modes. - + SSL properties and definitions inside the "teiid-client-= settings.properties" are shown below. = - = +# +# The key store type. Defaults to JKS +# + +org.teiid.ssl.keyStoreType=3DJKS + +# +# The key store algorithm, defaults to = +# the system property "ssl.TrustManagerFactory.algorithm" +# + +#org.teiid.ssl.algorithm=3D + +# +# 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=3D + +# +# The key store password (not required) +# + +#org.teiid.ssl.keyStorePassword=3D + +# +# 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=3D + +# +# The trust store password (not required) +# + +#org.teiid.ssl.trustStorePassword=3D + +# +# The cipher protocol, defaults to SSLv3 +# + +org.teiid.ssl.protocol=3DSSLv3]]> = = - 1-way SSL - /server.truststore (required) = = - ]]> + + 1-way SSL + /serve= r.truststore (required)]]> + = - = - 2-way SSL - /client.keystore (required) - org.teiid.ssl.trustStore=3D/server.truststore (required) = = - ]]> = - - Anonymous - = - = + + 2-way SSL + /client.= keystore (required) +org.teiid.ssl.trustStore=3D/server.truststore (required)]]> = + + + Anonymous + = + = \ No newline at end of file Modified: trunk/documentation/client-developers-guide/src/main/docbook/en-U= S/content/using-hibernate.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/documentation/client-developers-guide/src/main/docbook/en-US/cont= ent/using-hibernate.xml 2010-06-25 19:35:24 UTC (rev 2305) +++ trunk/documentation/client-developers-guide/src/main/docbook/en-US/cont= ent/using-hibernate.xml 2010-06-26 03:26:50 UTC (rev 2306) @@ -10,79 +10,74 @@ Many Hibernate use cases assume a data source has the abilit= y (with proper user permissions) = to process Data Definition Language (DDL) statements like CREATE T= ABLE 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. + Teiid can handle a broad range of DML, but does not support DDL. = Configuration - For the most part, interacting with teiid VDBs (Virtual Data= bases) from Hibernate is no = + For the most part, interacting with Teiid VDBs (Virtual Data= bases) from Hibernate is no = different from working with any other type of data source.=C2=A0 = First you must place Teiid JDBC API client JAR file and Teiid's hi= bernate dialect JAR in Hibernate=E2=80=99s classpath.=C2=A0 = These files can be found in <jboss-install>/server/<= ;profile>/lib directory. - - teiid-{version}-client.jar - teiid-hibernate-dialect-{version}.jar - + + teiid-&versionNumber;-client.jar + teiid-hibernate-dialect-&versionNumber;.jar + = - These JAR files has org.teiid.dialect.TeiidDialect and org.teiid.jdbc.TeiidDriver and = + These JAR files have the org.teiid.dialect.TeiidDialec= t and org.teiid.jdbc.TeiidDriver and = org.teiid.jdbc.TeiidDataSource classes. = - You then configure the Hibernate configuration file (hiberna= te.cfg.xml) as follows: Specify the Teiid driver = - class in the "connection.driver_class" property: + + You then configure Hibernate (via hibernate.cfg.xml) as foll= ows: + + Specify the Teiid driver = + class in the "connection.driver_class" property: = - - =C2=A0=C2=A0=C2=A0=C2=A0 org.teiid.jdbc.TeiidDriver - = - ]]> = - = + +=C2=A0=C2=A0=C2=A0=C2=A0 org.teiid.jdbc.TeiidDriver +]]> = + + + = Specify the URL for the VDB in the "connection.url" property = - (replacing terms in angle brackets with the appropriate values): + (replacing terms in angle brackets with the appropriate values): = - -=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 jdbc:metamatr= ix:@mm://:;user=3D;password=3D -=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 = - ]]> = + + jdbc:metamatrix:@mm://:;user=3D;password= =3D +]]> = + + + Specify the Teiid dialect class in the =E2=80=9Cdialect=E2=80= =9D property: = - Specify the Teiid dialect class in the =E2=80=9Cdialect=E2=80= =9D property: - = - -=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 org.teiid.dia= lect.TeiidDialect -=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 = - ]]> = - = + + org.teiid.dialect.TeiidDialect +]]> = + Alternatively, if you put your connection properties in hibernate.properties = instead of hibernate.cfg.xml, they would look like thi= s: = - @mm://: - hibernate.connection.username=3D - hibernate.connection.password=3D - hibernate.dialect=3Dorg.teiid.dialect.TeiidDialect = - ]]> = + @mm://: +hibernate.connection.username=3D +hibernate.connection.password=3D +hibernate.dialect=3Dorg.teiid.dialect.TeiidDialect]]> = + + = = Note also that since your VDBs will likely contain multiple s= ource and view models = with identical table names, you will need to fully qualify table na= mes = specified in Hibernate mapping files: = = - " table=3D".[= .]"> -=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 =C2=A0= =C2=A0=C2=A0=C2=A0=C2=A0 ... -=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 = = - ]]> + " table=3D".[.]
"> + ... +]]> = - For Example: - = - -=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 =C2=A0= =C2=A0=C2=A0=C2=A0=C2=A0 ... -=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 = = - ]]> - = + + Example Mapping + + ... +]]> + = - = \ No newline at end of file Modified: trunk/documentation/client-developers-guide/src/main/docbook/en-U= S/main.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/documentation/client-developers-guide/src/main/docbook/en-US/main= .xml 2010-06-25 19:35:24 UTC (rev 2305) +++ trunk/documentation/client-developers-guide/src/main/docbook/en-US/main= .xml 2010-06-26 03:26:50 UTC (rev 2306) @@ -49,7 +49,6 @@ - --===============2983462388076593005==--