<?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 to any Virtual Database (VDB) deployed on a Teiid Server. 
    The Teiid JDBC API is compatible with the JDBC 4.0 specification; however, it does not fully support all <link linkend="unsupported_jdbc">methods</link>.
    Advanced features, such as updatable result sets or SQL3 data types, are not supported. </para>
    
    <para>Java client applications connecting to a Teiid Server will need to use Java 1.6 JDK. Previous versions of Java are not supported.</para>
    
    <para>Before you can connect to the Teiid Server using the Teiid JDBC API, please do following tasks first.</para>
    <orderedlist>
        <listitem> <para>Install the Teiid Server. See the "Admin Guide" for instructions. </para> </listitem>
        <listitem> <para>Build a Virtual Database (VDB). You can either build a "Dynamic VDB" (Designer not required), 
        or you can use the Eclipse based GUI tool <ulink url="http://www.jboss.org/teiiddesigner.html">Designer</ulink>.          
        Check the "Reference Guide" for instructions on how to build a VDB. If you do not know what VDB is, then start with this 
        <ulink url="http://www.jboss.org/teiid/basics/virtualdatabases.html">document</ulink>.</para> </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 the Teiid Server, client applications 
    can connect to the Teiid Server and issue SQL queries against deployed VDB using Teiid's JDBC API. If you are new to JDBC, see Java's documentation about 
    <ulink url="http://java.sun.com/docs/books/tutorial/jdbc/index.html">JDBC</ulink>. Teiid ships with
    <code>teiid-&versionNumber;-client.jar</code> in the <code>"jboss-install/server/&lt;profile&gt;/lib"</code> directory. 
    
    <itemizedlist>
    	<para>Main classes in the client JAR:</para>
        <listitem> <para><code>org.teiid.jdbc.TeiidDriver</code> - allows JDBC connections using the
        <ulink url="http://java.sun.com/javase/6/docs/api/java/sql/DriverManager.html">DriverManager</ulink> class.</para> </listitem>
        <listitem> <para><code>org.teiid.jdbc.TeiidDatasource</code> - allows JDBC connections using the
        <ulink url="http://java.sun.com/javase/6/docs/api/javax/sql/DataSource.html">DataSource</ulink> or <ulink url="http://java.sun.com/javase/6/docs/api/javax/sql/XADataSource.html">XADataSource</ulink> class. You should use this class to create managed or XA connections.</para> </listitem>
    </itemizedlist>
    </para>
    
    <para>Once you have established a connection with the Teiid Server, you can use standard JDBC API classes to interrogate metadata and execute queries.</para>
    
    <section id="driver_connection">
		<title>Driver Connection</title>
        <para>Use <code>org.teiid.jdbc.TeiidDriver</code> as the driver class.</para>
        
        <para>Use the following URL format for JDBC connections:<synopsis>jdbc:teiid:&lt;vdb-name&gt;@mm[s]://&lt;host&gt;:&lt;port&gt;;[prop-name=prop-value;]*</synopsis></para>

        <para>URL Components</para>
        <orderedlist>
            <listitem><para>&lt;vdb-name&gt; - Name of the VDB you are connecting to. Optionally VDB 
            name can also contain version information inside it. For example: "myvdb.2", this is equivalent to supplying the 
            "version=2" connection property defined below. However, use of vdb name in this format and 
            the "version" property at the same time is not allowed.
             </para></listitem>
            <listitem><para>mm - defines Teiid JDBC protocol, mms defines a secure channel (see the <link linkend="ssl">SSL chapter</link> for more)</para></listitem>
            <listitem><para>&lt;host&gt; - defines the server where the Teiid Server is installed. If you are using IPv6 binding address as the host name, place it in square brackets. ex:[::1]</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 
            [;]. All supported URL properties are defined in the <link linkend="connection_properties">connection properties section</link>.  Property values should be URL encoded if they contain reserved characters, e.g. ('?', '=', ';', etc.)</para></listitem>
        </orderedlist>
        
	    <section id="connection_properties">
        <title>URL Connection Properties</title>
        <para>The following table shows all the supported connection properties that can used with Teiid 
        JDBC Driver URL connection string, or on the Teiid JDBC Data Source class.</para>

        <table frame='all'>
            <title>Connection Properties</title>
            <tgroup cols='3' align='left' colsep='1' rowsep='1'>
                <colspec colname='c1' colwidth=".75*" />
                <colspec colname='c2' colwidth=".5*" />
                <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 default should be used.</entry>
                    </row>
                      <row>
                        <entry>
                            <code>partialResultsMode</code>
                        </entry>
                        <entry>
                            <code>boolean</code>
                        </entry>
                        <entry>Enable/disable support partial results mode.  Default false.  See the <link linkend="partial_results">partial results</link> section.</entry>
                    </row>
                    <row id="auto_commit_txn">
                        <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.
                                <itemizedlist>
                                    <listitem><para>ON  - Always wrap command in distributed transaction</para></listitem>
                                    <listitem><para>OFF - Never wrap command in distributed transaction</para></listitem>
                                    <listitem><para>DETECT (default)- If the executed command is spanning more than one source it automatically uses distributed transaction.</para></listitem>
                                </itemizedlist>
                                <link linkend="jdbc_transactions">Transactions with JDBC</link> for more information.
                        </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.  Default false.</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. Default 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.  Default false.  
                        This is typically not needed when connections are managed, as the connection can be purged from the pool.</entry>
                    </row>                    
                    
                    <row>
                        <entry>
                            <code>SHOWPLAN</code>
                        </entry>
                        <entry>
                            <code>String</code>
                        </entry>
                        <entry>(typically not set as a connection property) Can be ON|OFF|DEBUG; ON returns the query plan along with the results and DEBUG additionally prints the query planner debug information in the log and returns it with the results.  Both the plan and the log are available through JDBC API extensions.  Default OFF.</entry>
                    </row>
                    
                    <row>
                        <entry>
                            <code>NoExec</code>
                        </entry>
                        <entry>
                            <code>String</code>
                        </entry>
                        <entry>(typically not set as a connection property) Can be ON|OFF; ON prevents query execution, but parsing and planning will still occur.  Default OFF.</entry>
                    </row>                    
                    <row id="PassthroughAuthentication">
                        <entry>
                            <code>PassthroughAuthentication</code>
                        </entry>
                        <entry>
                            <code>boolean</code>
                        </entry>
                        <entry>Only applies to "local" connections. When this option is set to "true", then Teiid looks for 
                        already authenticated security context on the calling thread. If one found it uses that users credentials 
                        to create session. Teiid also verifies that the same user is using this connection during the life of the connection.
                        if it finds a different security context on the calling thread, it switches the identity on the connection,
                        if the new user is also eligible to log in to Teiid otherwise connection fails to execute.</entry>
                    </row>
                    <row id="useCallingThread">
                        <entry>
                            <code>useCallingThread</code>
                        </entry>
                        <entry>
                            <code>boolean</code>
                        </entry>
                        <entry>Only applies to "local" connections. When this option is set to "true" (the default), then the calling thread will be used to process the query.  If false, then an engine thread will be used.</entry>
                    </row>                        
                    <row>
                    	<entry>
                            <code>QueryTimeout</code>
                        </entry>
                        <entry>
                            <code>integer</code>
                        </entry>
                        <entry>Default query timeout in seconds. Must be >= 0. 0 indicates no timeout. Can be overriden by <code>Statement.setQueryTimeout</code>. Default 0.</entry>
                    </row>
                    <row>
                        <entry>
                            <code>useJDBC4ColumnNameAndLabelSemantics</code>
                        </entry>
                        <entry>
                            <code>boolean</code>
                        </entry>						
                        <entry>
                           <para>A change was made in JDBC4 to return unaliased column names as the ResultSetMetadata column name. 
                            Prior to this, if a column alias were used it was returned as the column name.   Setting this property to false will enable
							backwards compatibility when JDBC3 and older support is still required.  Defaults to true.
							</para>
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <code>jaasName</code>
                        </entry>
                        <entry>
                            <code>String</code>
                        </entry>                        
                        <entry>
                           <para>JAAS configuration name. Only applies when configuring a GSS authentication.
                           See the Admin Guide for configuration required for GSS.</para>
                        </entry>
                    </row>                      
                    <row>
                        <entry>
                            <code>kerberosServicePrincipleName</code>
                        </entry>
                        <entry>
                            <code>String</code>
                        </entry>                        
                        <entry>
                           <para>Kerberos authenticated principle name. Only applies when configuring a GSS authentication.
                           See the Admin Guide for configuration required for GSS</para>
                        </entry>
                    </row>                      
                    						
                </tbody>
            </tgroup>
        </table> 
        </section>
 
	</section>

	<section id="datasource_connection">
        <title>Datasource Connection</title>
        <para>To use a data source based connection, use <code>org.teiid.jdbc.TeiidDataSource</code> as the data source class. 
        The <code>TeiidDataSource</code> is also an XADatasource. Teiid DataSource class is also Serializable, so it possible for it to be used with
        JNDI naming services.</para>
       
       <note><para>Teiid supports the XA protocol, XA transactions will be extended to Teiid sources that also support XA.</para></note> 
               
        <para>All the properties (except for version, which is known on TeiidDataSource as DatabaseVersion) defined in the <link linkend="connection_properties">connection properties</link>have corresponding "set" methods on the <code>org.teiid.jdbc.TeiidDataSource</code>. 
        Properties that are assumed from the URL string have addtional "set" methods, which are described in the following table.</para>
               
        <table id="ds_methods" frame='all'>
            <title>Datasource Properties</title>
            <tgroup cols='3' align='left' colsep='1' rowsep='1'>
                <colspec colname='c1' colwidth="1.25*" />
                <colspec colname='c2' colwidth=".7*" />
                <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. Optionally Database 
            name can also contain "DatabaseVersion" information inside it. For example: "myvdb.2", this is equivalent to supplying the 
            "DatabaseVersion" property set to value of 2. However, use of Database name in this format and use of 
            DatabaseVersion property at the same time is not allowed.</entry>
                    </row>
                    <row>
                        <entry>
                            <code>ServerName</code>
                        </entry>
                        <entry>
                            <code>String</code>
                        </entry>
                        <entry>Server hostname where the Teiid runtime installed. If you are using IPv6 binding address as the host name, 
                        place it in square brackets. ex:[::1]</entry>
                    </row>
                    <row>
                        <entry>
                            <code>AlternateServers</code>
                        </entry>
                        <entry>
                            <code>String</code>
                        </entry>
                        <entry>Optional delimited list of host:port entries.  See the <link linkend="multiple_hosts">multiple hosts</link> 
                        section for more information. If you are using IPv6 binding address as the host name, 
                        place them in square brackets. ex:[::1]</entry>
                    </row>
                    <row>
                        <entry>
                            <code>AdditionalProperties</code>
                        </entry>
                        <entry>
                            <code>String</code>
                        </entry>
                        <entry>Optional setting of properties that has the same format as the property string in a connection URL.</entry>
                    </row>
                   <row>
                        <entry>
                            <code>PortNumber</code>
                        </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 SSL (mms) 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>  
    </section>
    
    <section>
    	<title>Standalone Application</title>
		<para>To use either Driver or DataSource based connections, add the client JAR to your Java client application's classpath.  See the simple client example in the kit for a full Java sample of the following.</para>    	
		
		<section id="sa_driver_connection">
	        <title>Driver Connection</title>
	       
	       <para>Sample Code:</para>
	       <programlisting><![CDATA[public class TeiidClient {
    public Connection getConnection(String user, String password) throws Exception {
        String url = "jdbc:teiid:myVDB@mm://localhost:31000;ApplicationName=myApp";
        return DriverManager.getConnection(url, user, password);
    }
}]]></programlisting>       
 
	    </section>
	    
	    <section id="sa_datasource_connection">
	        <title>Datasource Connection</title>
	        
	       <para>Sample Code:</para>
	       <programlisting><![CDATA[public class TeiidClient {
    public Connection getConnection(String user, String password) throws Exception {
        TeiidDataSource ds = new TeiidDataSource();
        ds.setUser(user);
        ds.setPassword(password);
        ds.setServerName("localhost");
        ds.setPortNumber(31000);
        ds.setDatabaseName("myVDB");
        return ds.getConnection();
    }
}]]></programlisting>        
	       
	    </section>
		
    </section>
    
    <section id="ds_in_jbossas">
        <title>JBoss AS Data Source</title>
        <para>Teiid can be configured as a JDBC data source in the JBoss Application Server to be accessed 
        from JNDI or injected into your JEE applications.  Deploying Teiid as data source in JBoss AS is exactly same as  
        deploying any other RDBMS resources like Oracle or DB2.</para>
        
        <para>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>

	<para>A special case is if the Teiid instance you are connecting to is in the same VM as the JBoss AS instance.  If that matches you deployment, then follow the <xref linkend="local_connection"/> instructions</para>
        
        <orderedlist numeration="arabic">
        	<para>Installation Steps</para>
            <listitem><para>If Teiid is not installed in the AS instance, copy the <code>teiid-&versionNumber;-client.jar</code>  into 
            <code>&lt;jboss-install&gt;/server/&lt;profile&gt;/lib</code> directory.</para></listitem>
            <listitem><para>Create a "&lt;datasource name&gt;-ds.xml" file in <code>&lt;jboss-install&gt;/server/&lt;profile&gt;/deploy</code> 
            directory.  Based on the type of deployment (XA, driver, or local), the contents of the file will be different.  See the following sections for more.</para></listitem>
        </orderedlist>
        
        <para>The data source will then be accessable through the JNDI name specified in the -ds.xml file.</para>
        
        <section id="as_xa_connection">
           <title>DataSource Connection</title>
           <para>Make sure you know the correct DatabaseName, ServerName, Port number and credentials that are specific 
           to your deployment environment. </para>        
           <example>
           <title>Sample XADataSource in the JBoss AS using the 
           Teiid DataSource class <code>org.teiid.jdbc.TeiidDataSource</code></title>
            
           <programlisting><![CDATA[<datasources>
  <xa-datasource>
    <jndi-name>TEIID-DS</jndi-name>
    <xa-datasource-class>org.teiid.jdbc.TeiidDataSource</xa-datasource-class>
    <xa-datasource-property name="DatabaseName">myVDB</xa-datasource-property>
    <xa-datasource-property name="serverName">localhost</xa-datasource-property> 
    <xa-datasource-property name="portNumber">31000</xa-datasource-property> 
    <xa-datasource-property name="user">admin</xa-datasource-property> 
    <xa-datasource-property name="password">password</xa-datasource-property> 

    <!-- pool and other JBoss datasource properties -->
    <check-valid-connection-sql>SELECT 1</check-valid-connection-sql>
    <min-pool-size>5</min-pool-size> 
    <max-pool-size>10</max-pool-size>                
  </xa-datasource>        
</datasources>]]></programlisting> </example>         
       </section>
       <section 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:teiid:myVDB@mm://localhost:31000</connection-url> 
    <driver-class>org.teiid.jdbc.TeiidDriver</driver-class>              
    <user-name>admin</user-name>
    <password>teiid</password>
     
    <!-- pool and other JBoss datasource properties -->
    <check-valid-connection-sql>SELECT 1</check-valid-connection-sql>
    <min-pool-size>5</min-pool-size> 
    <max-pool-size>10</max-pool-size>
  </local-tx-datasource> 
</datasources>]]></programlisting>   
        </section>
        <section 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 a way to make connections that by-pass making a socket based JDBC connection.
           You can use slightly modified data source configuration to make a "local" connection, where the JDBC API will lookup a local Teiid runtime in the same VM.</para>
           <warning><para>Since DataSources start before before Teiid VDBs are deployed, leave the min pool size of local connections as the default of 0.  Otherwise errors will occur on the startup of the Teiid DataSource.</para></warning>
           <note><para>By default local connections use their calling thread to perform processing operations rather than using an engine thread while the calling thread is blocked.
            To disable this behavior set the connection property useCallingThreads=false.</para></note>
           <example>
           <title>Local data source</title>
           <programlisting><![CDATA[<datasources>
  <xa-datasource>
    <jndi-name>TEIID-DS</jndi-name>
    <xa-datasource-class>org.teiid.jdbc.TeiidDataSource</xa-datasource-class>
    <xa-datasource-property name="DatabaseName">myVDB</xa-datasource-property>
    <xa-datasource-property name="user">admin</xa-datasource-property> 
    <xa-datasource-property name="password">password</xa-datasource-property> 

    <!-- pool and other JBoss datasource properties -->
    <max-pool-size>10</max-pool-size>                
  </xa-datasource>        
</datasources>]]></programlisting>
</example>
           <para>This is essentially the same as the XA configuration, but "ServerName" and "PortNumber" are not specified.  Local connections have additional features such as using <xref linkend="PassthroughAuthentication"/> </para>            
        </section>
              
    </section>
    
    <section id="multiple_hosts">
        <title>Using Multiple Hosts</title>
        <para>A group of Teiid Servers in the same JBoss AS cluster may be connected using failover and load-balancing features.
        To enable theses features in their simplest form, the client needs to specify multiple host name and port number combinations on the URL connection string. 
        <example><title>Example URL connection string</title><programlisting><![CDATA[jdbc:teiid:&lt;vdb-name&gt;@mm://host1:31000,host1:31001,host2:31000;version=2]]></programlisting></example>
        </para>
        <para>If you are using a DataSource to connect to Teiid Server, use the "AlternateServers" property/method to define the failover servers.  The format is also a comma separated list of host:port combinations.</para> 
		<para>The client will randomly pick one the Teiid server from the list and establish a session with that server.  
        If that server cannot be contacted, then a connection will be attempted to each of the remaining servers in random order.  
        This allows for both connection time fail-over and random server selection load balancing.                
        </para>
        <section id="failover">
        	<title>Fail Over</title>
        	<para>Post connection fail over will be used, if you're using an admin connection (such as what is used by AdminShell) or if the <emphasis>autoFailover</emphasis> connection property on JDBC URL is set to true. 
        	Post connection failover works by sending a ping, at most every second, to test the connection prior to use.  If the ping fails, a new instance will be selected prior to the operation being attempted.  
        	This is not true "transparent application failover" as the client will not restart the transaction/query/recreate session scoped temp tables, etc.  So this feature should be used with caution by non-admin connections.</para>
        </section>
        <section id="loadbalancing">
        	<title>Load Balancing</title>
        	<para>Post connection load balancing can be utilized in one of two ways.  First if you are using <code>TeiidDataSource</code> and the Connections returned by 
        	Teiid <code>PooledConnections</code> have their <code>close</code> method called, then a new server instance will be selected automatically. 
        	However when using driver based connections or even when using <code>TeiidDataSource</code> in a connection pool (such as JBoss AS), the automatic load balancing will not happen.  
        	Second you can explicitly trigger load balancing through the use of the set statement: <programlisting>SET NEWINSTANCE TRUE</programlisting>
        	Typically you will not need want to issue this statement manually, but instead use it as the connection test query on your DataSource configuration.
        	<example>
        		<title>JBoss AS DataSource With Post Connection Load Balancing</title>
        	<programlisting><![CDATA[<datasources> 
  <local-tx-datasource> 
    <jndi-name>TEIID-DS</jndi-name> 
    <connection-url>jdbc:teiid:myVDB@mm://localhost:31000,mm://localhost:32000</connection-url> 
    <driver-class>org.teiid.jdbc.TeiidDriver</driver-class>              
    <user-name>admin</user-name>
    <password>teiid</password>
     
    <!-- pool and other JBoss datasource properties -->
    <check-valid-connection-sql>SET NEWINSTANCE TRUE</check-valid-connection-sql>
    <min-pool-size>5</min-pool-size> 
    <max-pool-size>10</max-pool-size>
  </local-tx-datasource> 
</datasources>]]></programlisting>
</example>
        	</para>
        	<para>Teiid by default maintians a pool of extra socket connections that are reused.  For load balancing, this reduces the potential cost of switching a connection to another server instance.  
        	The default setting is to maintain 16 connections (see <code>org.teiid.sockets.maxCachedInstances</code> in the client jar's teiid-client-settings.properties file.  
        	If you're client is connecting to large numbers of Teiid instances and you're using post connection time load balancing, then consider increasing the number of cached instances.  
        	You may either set an analogous system property or create another version of teiid-client-settings.properties file and place it into the classpath ahead of the client jar.</para>
        	<note><para>Session level temporary tables, currently running transactions, session level cache entries, and PreparedPlans for a given session will not be available on other cluster members.  
        	Therefore, it is recommended that post connection time load balancing is only used when the logical connection could have been closed, but the actual connection is reused (the typical connection pool pattern).</para></note>
        </section>
        <section id="advancedconfig">
        	<title>Advanced Configuration</title>
        	<para>Server discovery, load balancing, fail over, retry, retry delay, etc. may be customize if the default policy is not sufficient.  
        	See the <code>org.teiid.net.socket.ServerDiscovery</code> interface and default implementaion <code>org.teiid.net.socket.UrlServerDiscovery</code> for how to start with your customization.
        	The <code>UrlServerDiscovery</code> implemenation provides the following: discovery of servers from the URL hosts (DataSource server/alternativeServers), random selection for load balancing and failover, 1 connection attempt per host, no biasing, black listing, or other advanced features.  
        	Typically you'll want to extend the <code>UrlServerDiscovery</code> so that it can be used as the fallback strategy and to only implement the necessary changed methods.  
        	It's important to consider that 1 <code>ServerDiscovery</code> instance will be created for each connection.  Any sharing of information between instances should be done through static state or some other shared lookup.       	
        	</para>
        	<para>Your customized server discovery class will then need to be referenced by the discoveryStategy connection/DataSource property by its full class name.</para>
        	<para>You may also choose to use an external tcp load balancer, such as <ulink url="http://haproxy.1wt.eu/">haproxy</ulink>.  
        	The Teiid driver/DataSource should then typically be configured to just use the single host/port of your load balancer.</para>
        </section>
    </section>
    <section id="reauthentication">
    	<title>Reauthentication</title>
    	<para>Teiid connections (defined by the <code>org.teiid.jdbc.TeiidConnection</code> interface) support the changeUser method to reauthenticate a given connection.  
    	If the reauthentication is successful the current connection my be used with the given identity.  
    	Existing statements/result sets are still available for use under the old identity.  See the JBossAS issue <ulink url="https://issues.jboss.org/browse/JBAS-1429">JBAS-1429</ulink> for more on using reauthentication support with JCA.</para>
    </section>
</chapter>