<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
 -  
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2018 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  
-->
<chapter label="accessinterfaces.xml" id="accessinterfaces">
  <title>Data Access Interfaces</title>
  <abstract>
    <para>This chapter covers installation, configuration, and utilization of the data
access drivers / providers (ODBC, JDBC, OLE-DB, and ADO.NET ) that comprise the Virtuoso
Client Connectivity kit.
    </para>
  </abstract>

&virtclientref;

&isql;

&odbcimplementation;

<sect1 id="VirtuosoDriverJDBC"><title>Virtuoso Driver for JDBC</title>
				<para>The Virtuoso Drivers for JDBC are available in
   &quot;jar&quot; file formats for JDBC 1.x,  JDBC 2.x and JDBC 3.x specifications. These
    are Type 4 Drivers implying that utilization is simply a case of adding the relevant
    &quot;jar&quot; file to your CLASSPATH and then providing an appropriate JDBC URL format
    in order to establish a JDBC session with a local or remote Virtuoso server. It is
    important to note that when you make a JDBC connection to a Virtuoso Server, you do also
    have access to Native and External Virtuoso tables. Thus, you actually have a type 4 JDBC
    Driver for any number of different database types that have been linked into Virtuoso.</para>
    <para>The JDBC 2 and JDBC 3 drivers also incorporate SSL encryption to enable very secure connections
    to the Virtuoso database.</para>
				<sect2 id="VirtuosoDriverPackaging">
					<title>Virtuoso Drivers for JDBC Packaging</title>
					<para>These drivers are installed alongside the Virtuoso Server
    or as part of a Virtuoso Client components only installation.
    They are packaged as follows:</para>
					<table colsep="1" frame="all" rowsep="0" shortentry="0" tocentry="1" tabstyle="decimalstyle" orient="land" pgwide="0" id="JavaCompatibilityTable">
						<title>Features Comparison</title>
						<tgroup align="char" charoff="50" char="." cols="5">
							<colspec align="left" colnum="1" colsep="0" colwidth="20pc"/>
							<thead>
								<row>
									<entry>Driver Name</entry>
									<entry>Java Package</entry>
									<entry>&quot;jar&quot; File Archive</entry>
									<entry>Default Location</entry>
									<entry>Java  Version</entry>
								</row>
							</thead>
							<tbody>
								<row>
									<entry>virtuoso.jdbc.Driver</entry>
									<entry>virtuoso.jdbc</entry>
									<entry>virtjdbc.jar</entry>
									<entry>&lt;virtuoso installation directory&gt;\jdk11</entry>
									<entry>Java 1.1.x</entry>
								</row>
								<row>
									<entry>virtuoso.jdbc2.Driver</entry>
									<entry>virtuoso.jdbc2</entry>
									<entry>virtjdbc2.jar</entry>
									<entry>&lt;virtuoso installation directory&gt;\jdk12</entry>
									<entry>Java 1.2/1.3</entry>
								</row>
								<row>
									<entry>virtuoso.jdbc3.Driver used for Java 1.4 and Java 1.5</entry>
									<entry>virtuoso.jdbc3</entry>
									<entry>virtjdbc3.jar</entry>
									<entry>&lt;virtuoso installation directory&gt;\jdk13</entry>
									<entry>Java 1.4</entry>
								</row>
								<row>
									<entry>virtuoso.jdbc4.Driver used for Java 1.6</entry>
									<entry>virtuoso.jdbc4</entry>
									<entry>virtjdbc4.jar</entry>
									<entry>&lt;virtuoso installation directory&gt;\jdk14</entry>
									<entry>Java 1.6</entry>
								</row>

							</tbody>
						</tgroup>
					</table>
				</sect2>
				<sect2 id="jdbcurl4mat">
					<title>Virtuoso Driver For JDBC URL Format</title>
					<para>JDBC compliant applications and applets connect to JDBC
    Drivers using JDBC Uniform Resource Locators (URLs). Although there are two Virtuoso
    Drivers for JDBC, both share the same JDBC URL format. </para>
					<para>The Virtuoso Driver for JDBC URL format takes the
    following form:</para>
					<programlisting>
jdbc:virtuoso://&lt;Hostname&gt;:&lt;Port#&gt;/DATABASE=&lt;dbname&gt;/UID=&lt;user name&gt;/PWD=&lt;password&gt;/
  CERT=&lt;certificate_alias&gt;/KPATH=&lt;keystore_path&gt;/PASS=&lt;keystore_password&gt;/
  PROVIDER=&lt;ssl_provider_classname&gt;/SSL/CHARSET=&lt;character set&gt;/
  TIMEOUT=&lt;timeout_secs&gt;/PWDTYPE=&lt;authentication_type&gt;/log_enable=&lt;integer&gt;
</programlisting>
<para>
Also is supported Host:Port list in connection string:
</para>
<programlisting><![CDATA[
jdbc:virtuoso://<Hostname>:<Port#>,<Hostname1>:<Port1#>,<Hostname2>:<Port2#>/
]]></programlisting>
<para>
If Port is omitted, the default port 1111 is used.
</para>

					<para>Each part of the URL is explained
       					below:</para> <formalpara>
						<title>Protocol Identifiers</title>
   					<para>this is a constant value of
   					&quot;jdbc&quot; since JDBC is the
      					protocol in question</para>
 					</formalpara> <formalpara> <title>Sub
 					Protocol Identifier</title> <para>this
  					is a constant value that identifies
 					&quot;virtuoso&quot; as a sub protocol
      					of JDBC</para> </formalpara>
  					<formalpara> <title>Hostname</title>
						<para>this identifies the machine
					hosting a server process that speaks the
					&quot;virtuoso&quot; sub dialect of the
    &quot;jdbc&quot; protocol</para>
 					</formalpara> <formalpara> <title>Port
					Number</title> <para>this identifies the
 					port number on the machine from which
      					the server which speaks the
  					&quot;virtuoso&quot; sub dialect of
					&quot;jdbc&quot; listening for incoming
  					client connections The default port
    					number for a Virtuoso server is
 					&quot;1111&quot;.</para> </formalpara>
 					<formalpara> <title>/DATABASE</title>
						<para>this identifies the database
  					(Qualifier or Catalog) that you are
      					connecting to via a Virtuoso
					server</para> </formalpara> <formalpara>
 					<title>/UID</title> <para>a valid user
					name for the Virtuoso database that you
   					are connecting to via JDBC</para>
       					</formalpara> <formalpara>
   					<title>/PWD</title> <para>a valid
   					password for the user name </para>
             					</formalpara>
					<formalpara><title>/CERT=&lt;certificate
  					_alias&gt;</title> <para>name of the
     					certificate to use for the SSL
					connection stored in the keystore. This
    					is a required option for an SSL
    					authenticated connection</para>
             					</formalpara>
					<formalpara><title>/KPATH=&lt;keystore_p
  					ath&gt;</title> <para>This optional
					parameter lets you specify the keystore
 					file name (default: $HOME/.keystore).
 					The path separator is \, and which is
 					then replaced during the connection by
        					the right platform path
    					separator.</para> </formalpara>
					<formalpara><title>/PASS=&lt;keystore_pa
   					ssword&gt;</title> <para>password
  					required for accessing the keystore
  					file.  This is required for the SSL
    					authenticated connection.</para>
             					</formalpara>
					<formalpara><title>/PROVIDER=&lt;ssl_pro
 					vider_classname&gt;</title> <para>The
  					class name of the SSL Provider (e.g.
 					com.sun.ssl.net.internal.ssl.Provider)
 					to use for the SSL cryptography.  This
     					parameter is required for SSL
   					connections.</para> </formalpara>
  <formalpara><title>/SSL</title>
 					<para>The SSL option is used only for
      					SSL connection without user
  					authentication</para> </formalpara>
					<formalpara><title>/CHARSET=&lt;characte
					r set&gt;</title> <para>This allows the
 					client to specify a character set for
 					data encoding. When this option is set
					then all Java strings, natively Unicode,
   					are converted to the character set
  					specified here.</para> </formalpara>
					<formalpara><title>/TIMEOUT=&lt;timeout_
  					secs&gt;</title> <para>Specifies the
					maximum amount of time (in seconds) that
					the driver will wait for a response to a
  					query.  When this time is exceeded a
					time-out error will be reported and the
					network connection closed, assumed to be
      					broken.</para> </formalpara>
					<formalpara><title>/PWDCLEAR=&lt;authent
					ication_type&gt;</title> <para>Specifies
 					the authentication mode; how the user
 					credentials may be transmitted to the
 					server.  This option can be one of the
 					following 3 types: cleartext, encrypt,
 					digest. The default is digest.</para>
                                        <para>"cleartext" will transfer the
       					password to the server in
 					cleartext</para> <para>"encrypt" will
  					transfer the password to the server
 					using Virtuoso's symmetric encryption
 					technique.</para> <para>"digest" will
					calculate an MD5 digest of the password
					(and some additional session variables)
 					that will be sent to the server to be
   					compared with the value calculated
          					server-side.</para>
             					</formalpara>
					<formalpara><title>/log_enable=&lt;integ
					er&gt;</title> <para>Set log_enable=2 in
 					order to auto commit on every changed
 					row. Out of memory cannot be caused as
 					with this setting there is no image in
    					the memory for rollback.</para>
             					</formalpara>
 					<formalpara><title>/roundrobin</title>
 					<para>boolean attribute  1 -  for use
					RoundRobin; 0 -  do not use . (used only
					if more than one host:post values are in
					connection string)</para> </formalpara>
    					<formalpara><title>/fbs</title>
					<para>integer attribute, prefetch buffer
      					size (default is 100)</para>
             					</formalpara>
   					<formalpara><title>/sendbs</title>
  					<para>integer attribute, socket send
     					buffer size (default is 32768
      					bytes)</para> </formalpara>
   					<formalpara><title>/recvbs</title>
					<para>integer attribute, socket receive
     					buffer size (default is 32768
      					bytes)</para> </formalpara>
					<formalpara><title>/usepstmtpool</title>
 					<para>boolean attribute  1 -  for use
					PreparedStatement pool; 0 -  do not use
  					(Only for Java 1.6 and above)</para>
             					</formalpara>
					<formalpara><title>/pstmtpoolsize</title>
        					<para>integer attribute,
					PreparedStatement pool size (default is
        					25)</para> </formalpara>


<note><title>Note:</title>
<para>Since JSSE has only incorporated SSL support for JDK 1.2 and above,
SSL has only been implemented for the JDBC 2.x, JDBC 3.x and JDBC 4.x drivers for Virtuoso.</para>
</note>

				</sect2>
    <sect2 id="jdbc3features"><title>Virtuoso Driver JDBC 3.0 features</title>
				<sect3 id="jdbc3dsprops">
					<title>Virtuoso Driver For JDBC 3.0 javax.sql.DataSource</title>
					<para>JDBC 3.0 compliant applications and applets may connect to a JDBC
    data source using JDBC <computeroutput>javax.sql.DataSource</computeroutput> instances. 
    The Virtuoso JDBC 3.0 driver provides an implementation of the 
    <computeroutput>javax.sql.DataSource</computeroutput> interface in the 
    <computeroutput>virtuoso.jdbc3.VirtuosoDataSource</computeroutput> class, 
    supporting the following properties:</para>

					<table colsep="1" frame="all" rowsep="0" shortentry="0" tocentry="1" tabstyle="decimalstyle" orient="land" pgwide="0" id="JDBCDataSourceProps">
						<title>JDBC 3.0 VirtuosoDataSource properties</title>
						<tgroup align="char" charoff="50" char="." cols="5">
							<colspec align="left" colnum="1" colsep="0" colwidth="20pc"/>
							<thead>
								<row>
									<entry>Name</entry>
									<entry>Type</entry>
									<entry>URL Option Equivalent</entry>
									<entry>Description</entry>
								</row>
							</thead>
							<tbody>
								<row>
									<entry>dataSourceName</entry>
									<entry>java.lang.String</entry>
									<entry></entry>
									<entry>used in connection pooling</entry>
								</row>
								<row>
									<entry>description</entry>
									<entry>java.lang.String</entry>
									<entry></entry>
									<entry>string to describe the data source (free form)</entry>
								</row>
								<row>
									<entry>serverName</entry>
									<entry>java.lang.String</entry>
									<entry></entry>
									<entry>The host name of the remote host to connect to</entry>
								</row>
								<row>
									<entry>portNumber</entry>
									<entry>int</entry>
									<entry></entry>
									<entry>The port on the remote host to connect to</entry>
								</row>
								<row>
									<entry>user</entry>
									<entry>java.lang.String</entry>
									<entry>/UID</entry>
									<entry>username to use for the session</entry>
								</row>
								<row>
									<entry>password</entry>
									<entry>java.lang.String</entry>
									<entry>/PWD</entry>
									<entry>password to use for the session</entry>
								</row>
								<row>
									<entry>databaseName</entry>
									<entry>java.lang.String</entry>
									<entry>/DATABASE</entry>
									<entry>Initial catalog qualifier for the session</entry>
								</row>
								<row>
									<entry>charset</entry>
									<entry>java.lang.String</entry>
									<entry>/CHARSET</entry>
									<entry>Charset used in wide&lt;-&gt;narrow translations</entry>
								</row>
								<row>
									<entry>pwdClear</entry>
									<entry>java.lang.String</entry>
									<entry>/PWDTYPE</entry>
									<entry>authentication method</entry>
								</row>
							</tbody>
						</tgroup>
					</table>
				</sect3>
				<sect3 id="jdbcdspool">
					<title>Virtuoso Driver For JDBC 3.0 &amp; Connection Pooling</title>
					<para>The Virtuoso JDBC 3.0 driver supports connection pooling.</para>
  <para>The virtuoso.jdbc3.VirtuosoDataSource implements the 
  <computeroutput>javax.sql.ConnectionPoolDataSource</computeroutput> 
  interface.  In order to use the connection pooling the administrator must deploy 
  one instance of the <computeroutput>virtuoso.jdbc3.VirtuosoDriver</computeroutput> 
  in the JNDI repository and set all of it's properties except <computeroutput>dataSourceName</computeroutput>. 
  This is the "main" connection pooling data source. Then the administrator should 
  deploy a second instance of the <computeroutput>virtuoso.jdbc3.VirtuosoDataSource</computeroutput> 
  class and set only it's <computeroutput>dataSourceName</computeroutput> property.</para>
  <para>Applications will use the second <computeroutput>virtuoso.jdbc3.VirtuosoDataSource</computeroutput> 
  instance to get a connection. It will in turn call the first one to obtain all connect 
  info and return the <computeroutput>java.sql.Connection</computeroutput> 
  instance.</para>
				</sect3>
				<sect3 id="jdbcxa">
					<title>Virtuoso Driver For JDBC 3.0 &amp; Distributed Transactions</title>
					<para>Virtuoso supports the industry
standard XA specification for distributed transaction processing. The XA
specification defines an interface between the transaction manager (TM) and
resource manager (RM) in a distributed transaction system. This is a generic
interface and it does not directly address the use of distributed transactions
from Java. The Java mapping of the XA interface is defined in Sun Microsystems
Java Transaction API (JTA) and JDBC 3.0 specifications. The Virtuoso JDBC 3.0
driver supports the JTA architecture by providing the implementation of JTA
resource manager interfaces.</para>
					<para>The Virtuoso JDBC 3.0 driver
provides the <computeroutput>virtuoso.java3.VirtuosoXid</computeroutput>,
<computeroutput>virtuoso.java3.VirtuosoXADataSource</computeroutput>,
<computeroutput>virtuoso.java3.VirtuosoXAConnection</computeroutput>, and
<computeroutput>virtuoso.java3.VirtuosoXAResource</computeroutput> classes
which implement the interfaces
<computeroutput>javax.transaction.xa.Xid</computeroutput>,
<computeroutput>javax.transaction.xa.XADataSource</computeroutput>,
<computeroutput>javax.sql.XAConnection</computeroutput>, and
<computeroutput>javax.sql.XAResource</computeroutput> respectively.
The use if these interfaces is usually transparent for applications and the
application developer shouldn't bother with them. They are used only by
the JTS transaction manager which normally runs as a part of the J2EE
server.</para>
					<para>The task of the J2EE server
administrator is to setup the necessary Virtuoso XA datasources. The exact
procedure of this depends on the J2EE server in use (such as BEA WebLogic,
IBM WebSphere, etc). Generally, this includes two steps:</para>
					<orderedlist>
					    <listitem>
						<para>Include the JDBC driver's
jar file into J2EE server's class path.</para>
					    </listitem>
					    <listitem>
						<para>Deploy an instance of
<computeroutput>javax.transaction.xa.XADataSource</computeroutput> with
appropriately set properties into the J2EE server's JNDI repository.</para>
					    </listitem>
					</orderedlist>
					<para>
The <computeroutput>virtuoso.java3.VirtuosoXADataSource</computeroutput> class
is derived from <computeroutput>virtuoso.java3.VirtuosoDataSource</computeroutput>
and inherits all of its properties. These properties has to be set as described
in the section <link linkend="jdbc3dsprops">Virtuoso Driver For JDBC 3.0 javax.sql.DataSource</link>.</para>
					<para>For example, the following has to
be done in case of Sun's J2EE Reference Implementation.</para>
					<orderedlist>
					    <listitem>
						<para>Add the path of
virtjdbc3.jar to the J2EE_CLASSPATH variable in the file
$(J2EE_HOME)/bin/userconfig.bat on Windows or $(J2EE_HOME)/bin/userconfig.sh on
Unix/Linux:</para>
<programlisting>
    set J2EE_CLASSPATH=C:/Virtuoso/lib/virtjdbc3.jar
</programlisting>
or
<programlisting>
    J2EE_CLASSPATH=/home/login/virtuoso/lib/virtjdbc3.jar
    export J2EE_CLASSPATH
</programlisting>
					    </listitem>
					    <listitem>
						<para>Using the following
command add the XA datasource with JNDI name "jdbc/Virtuoso" which refers to
the Virtuoso server running on the same computer on port 1111:</para>
<programlisting>
    j2eeadmin -addJdbcXADatasource jdbc/Virtuoso virtuoso.jdbc3.VirtuosoXADataSource -props serverName=localhost portNumber=1111
</programlisting>
					    </listitem>
					</orderedlist>
				</sect3>
				<sect3 id="jdbcrs">
					<title>JDBC 3.0 javax.sql.RowSet Driver Implementation</title>
					<para>The Virtuoso JDBC 3.0 driver has two implementations of the 
          <computeroutput>javax.sql.RowSet</computeroutput> interface - 
          <computeroutput>virtuoso.javax.OPLCachedRowSet</computeroutput> and 
          <computeroutput>virtuoso.javax.OPLJdbcRowSet</computeroutput>.</para>
          <para>The <computeroutput>virtuoso.javax.OPLCachedRowSet</computeroutput> 
          class implements a totally disconnected, memory cached rowset and the 
          <computeroutput>virtuoso.javax.OPLJdbcRowset</computeroutput> class 
          spans the rest of the JDBC API to implement it's methods.</para>
				</sect3>
  <sect3 id="jdbcrdf">
      <title>Extension datatype for RDF</title>
      <para>The IRIs and RDF literals, kept in the Virtuoso RDF store are represented by a strings and structures. Thus accessing RDF objects needs special datatypes in order to distinguish strings from IRIs and to get language and datatype of the RDF literals.</para>
      <para>Therefore Virtuoso JDBC driver provides following classes for accessing RDF store: <computeroutput>virtuoso.jdbc3.VirtuosoExtendedString</computeroutput> for IRIs and <computeroutput>virtuoso.jdbc3.VirtuosoRdfBox</computeroutput> for RDF literal objects.</para>
      <para>
	  The class <computeroutput>virtuoso.jdbc3.VirtuosoExtendedString</computeroutput> will be returned when a string representing an IRI is returned to the client. It has two members "str" and "iriType", the "str" member keeps string representation of the IRI, "iriType" denote regular IRI or blank node with enum values VirtuosoExtendedString.IRI and VirtuosoExtendedString.BNODE. 
      </para>
      <para>
	  If the RDF literal object have language or datatype specified then <computeroutput>virtuoso.jdbc3.VirtuosoRdfBox</computeroutput> will be returned. The following methods could be used :
      </para>
      <programlisting>
	  String toString () : returns string representation of the literal
	  String getType () : returns string containing the datatype  of the literal
	  String getLang () : returns language code for the literal
      </programlisting>
      <para>
	  The following code snippet demonstrates how to use extension datatypes for RDF
      </para>
      <programlisting><![CDATA[
    ... initialization etc. skipped for brevity 
    boolean more = stmt.execute("sparql select * from <gr> where { ?x ?y ?z }");
    ResultSetMetaData data = stmt.getResultSet().getMetaData();
    while(more)
    {
	rs = stmt.getResultSet();
	while(rs.next())
	{
	    for(int i = 1;i <= data.getColumnCount();i++)
	    {
		String s = rs.getString(i);
		Object o = ((VirtuosoResultSet)rs).getObject(i);
		if (o instanceof VirtuosoExtendedString) // String representing an IRI
		  {
		    VirtuosoExtendedString vs = (VirtuosoExtendedString) o;
                    if (vs.iriType == VirtuosoExtendedString.IRI && (vs.strType & 0x01) == 0x01)
			System.out.println ("<" + vs.str +">");  
		    else if (vs.iriType == VirtuosoExtendedString.BNODE)
			System.out.println ("<" + vs.str +">");  
		  }  
		else if (o instanceof VirtuosoRdfBox) // Typed literal
		  { 
		    VirtuosoRdfBox rb = (VirtuosoRdfBox) o;
		    System.out.println (rb.rb_box + " lang=" + rb.getLang() + " type=" + rb.getType());
		    
		  }	      
		else if(stmt.getResultSet().wasNull())
		    System.out.println("NULL");
		else //  
		{
		    System.out.println(s);
		}
		    
	    }
	}
	more = stmt.getMoreResults();
    }
    ...
	    ]]></programlisting>
  </sect3>
                                </sect2>
<sect2 id="jdbc4features"><title>Virtuoso Driver JDBC 4.0 features</title>
				<sect3 id="jdbc4dsprops">
					<title>Virtuoso Driver For JDBC 4.0 javax.sql.DataSource</title>
					<para>JDBC 4.0 compliant applications and applets may connect to a JDBC
    data source using JDBC <computeroutput>javax.sql.DataSource</computeroutput> instances.
    The Virtuoso JDBC 4.0 driver provides an implementation of the
    <computeroutput>javax.sql.DataSource</computeroutput> interface in the
    <computeroutput>virtuoso.jdbc4.VirtuosoDataSource</computeroutput> class,
    supporting the following properties:</para>

					<table colsep="1" frame="all" rowsep="0" shortentry="0" tocentry="1" tabstyle="decimalstyle" orient="land" pgwide="0" id="JDBCDataSourceProps">
						<title>JDBC 4.0 VirtuosoDataSource properties</title>
						<tgroup align="char" charoff="50" char="." cols="5">
							<colspec align="left" colnum="1" colsep="0" colwidth="20pc"/>
							<thead>
								<row>
									<entry>Name</entry>
									<entry>Type</entry>
									<entry>URL Option Equivalent</entry>
									<entry>Description</entry>
								</row>
							</thead>
							<tbody>
								<row>
									<entry>dataSourceName</entry>
									<entry>java.lang.String</entry>
									<entry></entry>
									<entry>used in connection pooling</entry>
								</row>
								<row>
									<entry>description</entry>
									<entry>java.lang.String</entry>
									<entry></entry>
									<entry>string to describe the data source (free form)</entry>
								</row>
								<row>
									<entry>serverName</entry>
									<entry>java.lang.String</entry>
									<entry></entry>
									<entry>The host name of the remote host to connect to</entry>
								</row>
								<row>
									<entry>portNumber</entry>
									<entry>int</entry>
									<entry></entry>
									<entry>The port on the remote host to connect to</entry>
								</row>
								<row>
									<entry>user</entry>
									<entry>java.lang.String</entry>
									<entry>/UID</entry>
									<entry>username to use for the session</entry>
								</row>
								<row>
									<entry>password</entry>
									<entry>java.lang.String</entry>
									<entry>/PWD</entry>
									<entry>password to use for the session</entry>
								</row>
								<row>
									<entry>databaseName</entry>
									<entry>java.lang.String</entry>
									<entry>/DATABASE</entry>
									<entry>Initial catalog qualifier for the session</entry>
								</row>
								<row>
									<entry>charset</entry>
									<entry>java.lang.String</entry>
									<entry>/CHARSET</entry>
									<entry>Charset used in wide&lt;-&gt;narrow translations</entry>
								</row>
								<row>
									<entry>pwdClear</entry>
									<entry>java.lang.String</entry>
									<entry>/PWDTYPE</entry>
									<entry>authentication method</entry>
								</row>
							</tbody>
						</tgroup>
					</table>
<para>Additionally, the following attributres are supported:</para>
<programlisting><![CDATA[

--- for SSL enabled ---
   public void setCertificate (String value);
   public String getCertificate ();

   public void setKeystorepass (String value);
   public String getKeystorepass ();

   public void setKeystorepath (String value);
   public String getKeystorepath ();

   public void setProvider (String value);
   public String getProvider ();

----------------------

   public void setFbs (int value);
   public int getFbs ();

   public void setSendbs (int value);
   public int getSendbs ();

   public void setRecvbs (int value);
   public int getRecvbs ();

   public void setRoundrobin (boolean value);
   public boolean getRoundrobin ();

-- For Java 1.6 and above
   public void setUsepstmtpool (boolean value);
   public boolean getUsepstmtpool ();

   public void setPstmtpoolsize (int value);
   public int getPstmtpoolsize ();

]]></programlisting>
				</sect3>
				<sect3 id="jdbcdspool4">
					<title>Virtuoso Driver For JDBC 4.0 &amp; Connection Pooling</title>
					<para>The Virtuoso JDBC 4.0 driver supports connection pooling.</para>
  <para>The virtuoso.jdbc4.VirtuosoDataSource implements the
  <computeroutput>javax.sql.ConnectionPoolDataSource</computeroutput>
  interface.  In order to use the connection pooling the administrator must deploy
  one instance of the <computeroutput>virtuoso.jdbc4.VirtuosoDriver</computeroutput>
  in the JNDI repository and set all of it's properties except <computeroutput>dataSourceName</computeroutput>.
  This is the "main" connection pooling data source. Then the administrator should
  deploy a second instance of the <computeroutput>virtuoso.jdbc4.VirtuosoDataSource</computeroutput>
  class and set only it's <computeroutput>dataSourceName</computeroutput> property.</para>
  <para>Applications will use the second <computeroutput>virtuoso.jdbc4.VirtuosoDataSource</computeroutput>
  instance to get a connection. It will in turn call the first one to obtain all connect
  info and return the <computeroutput>java.sql.Connection</computeroutput>
  instance.</para>
  <para>VirtuosoConnectionPoolDataSource.class has the following connection pooling attributes:</para>
<programlisting><![CDATA[
/**
 * Get the minimum number of physical connections
 * the pool will keep available at all times. Zero ( 0 ) indicates that
 * connections will be created as needed.
 *
 * @return   the minimum number of physical connections
 *
**/
public int getMinPoolSize();

/**
 * Set the number of physical connections the pool should keep available
 * at all times. Zero ( 0 ) indicates that connections should be created
 * as needed
 * The default value is 0 .
 *
 * @param   parm a minimum number of physical connections
 *
 * @exception  java.sql.SQLException if an error occurs
 *
**/

public void setMinPoolSize(int parm);



/**
 * Get the maximum number of physical connections
 * the pool will be able contain. Zero ( 0 ) indicates no maximum size.
 *
 * @return   the maximum number of physical connections
 *
**/
public int getMaxPoolSize();

/**
 * Set the maximum number of physical conections that the pool should contain.
 * Zero ( 0 ) indicates no maximum size.
 * The default value is 0 .
 *
 * @param   parm a maximum number of physical connections
 *
 * @exception  java.sql.SQLException if an error occurs
 *
**/
public void setMaxPoolSize(int parm);


/**
 * Get the number of physical connections the pool
 * will contain when it is created
 *
 * @return   the number of physical connections
 *
**/
public int getInitialPoolSize();

/**
 * Set the number of physical connections the pool
 * should contain when it is created
 *
 * @param   parm a number of physical connections
 *
 * @exception  java.sql.SQLException if an error occurs
 *
**/
public void setInitialPoolSize(int parm);

/**
 * Get the number of seconds that a physical connection
 * will remain unused in the pool before the
 * connection is closed. Zero ( 0 ) indicates no limit.
 *
 * @return   the number of seconds
**/
public int getMaxIdleTime();

/**
 * Set the number of seconds that a physical connection
 * should remain unused in the pool before the
 * connection is closed. Zero ( 0 ) indicates no limit.
 *
 * @param  parm a number of seconds
 *
 * @exception  java.sql.SQLException if an error occurs
 *
**/
public void setMaxIdleTime(int parm);

/**
 * Get the interval, in seconds, that the pool will wait
 * before enforcing the current policy defined by the
 * values of the above connection pool properties
 *
 * @return  the interval (in seconds)
**/
public int getPropertyCycle();

/**
 * Set the interval, in seconds, that the pool should wait
 * before enforcing the current policy defined by the
 * values of the above connection pool properties
 *
 * @param  parm an interval (in seconds)
**/
public void setPropertyCycle(int parm);


/**
 * Get the total number of statements that the pool will
 * keep open. Zero ( 0 ) indicates that caching of
 * statements is disabled.
 *
 * @return  the total number of statements
**/
public int getMaxStatements();

/**
 * Set the total number of statements that the pool should
 * keep open. Zero ( 0 ) indicates that caching of
 * statements is disabled.
 *
 * @param  parm a total number of statements
 *
 * @exception  java.sql.SQLException if an error occurs
 *
**/
public void setMaxStatements(int parm);

]]></programlisting>

				</sect3>
				<sect3 id="jdbcxa4">
					<title>Virtuoso Driver For JDBC 4.0 &amp; Distributed Transactions</title>
					<para>Virtuoso supports the industry
standard XA specification for distributed transaction processing. The XA
specification defines an interface between the transaction manager (TM) and
resource manager (RM) in a distributed transaction system. This is a generic
interface and it does not directly address the use of distributed transactions
from Java. The Java mapping of the XA interface is defined in Sun Microsystems
Java Transaction API (JTA) and JDBC 4.0 specifications. The Virtuoso JDBC 4.0
driver supports the JTA architecture by providing the implementation of JTA
resource manager interfaces.</para>
					<para>The Virtuoso JDBC 4.0 driver
provides the <computeroutput>virtuoso.java3.VirtuosoXid</computeroutput>,
<computeroutput>virtuoso.java3.VirtuosoXADataSource</computeroutput>,
<computeroutput>virtuoso.java3.VirtuosoXAConnection</computeroutput>, and
<computeroutput>virtuoso.java3.VirtuosoXAResource</computeroutput> classes
which implement the interfaces
<computeroutput>javax.transaction.xa.Xid</computeroutput>,
<computeroutput>javax.transaction.xa.XADataSource</computeroutput>,
<computeroutput>javax.sql.XAConnection</computeroutput>, and
<computeroutput>javax.sql.XAResource</computeroutput> respectively.
The use if these interfaces is usually transparent for applications and the
application developer shouldn't bother with them. They are used only by
the JTS transaction manager which normally runs as a part of the J2EE
server.</para>
					<para>The task of the J2EE server
administrator is to setup the necessary Virtuoso XA datasources. The exact
procedure of this depends on the J2EE server in use (such as BEA WebLogic,
IBM WebSphere, etc). Generally, this includes two steps:</para>
					<orderedlist>
					    <listitem>
						<para>Include the JDBC driver's
jar file into J2EE server's class path.</para>
					    </listitem>
					    <listitem>
						<para>Deploy an instance of
<computeroutput>javax.transaction.xa.XADataSource</computeroutput> with
appropriately set properties into the J2EE server's JNDI repository.</para>
					    </listitem>
					</orderedlist>
					<para>
The <computeroutput>virtuoso.java3.VirtuosoXADataSource</computeroutput> class
is derived from <computeroutput>virtuoso.java3.VirtuosoDataSource</computeroutput>
and inherits all of its properties. These properties has to be set as described
in the section <link linkend="jdbc4dsprops">Virtuoso Driver For JDBC 4.0 javax.sql.DataSource</link>.</para>
					<para>For example, the following has to
be done in case of Sun's J2EE Reference Implementation.</para>
					<orderedlist>
					    <listitem>
						<para>Add the path of
virtjdbc4.jar to the J2EE_CLASSPATH variable in the file
$(J2EE_HOME)/bin/userconfig.bat on Windows or $(J2EE_HOME)/bin/userconfig.sh on
Unix/Linux:</para>
<programlisting>
    set J2EE_CLASSPATH=C:/Virtuoso/lib/virtjdbc4.jar
</programlisting>
or
<programlisting>
    J2EE_CLASSPATH=/home/login/virtuoso/lib/virtjdbc4.jar
    export J2EE_CLASSPATH
</programlisting>
					    </listitem>
					    <listitem>
						<para>Using the following
command add the XA datasource with JNDI name "jdbc/Virtuoso" which refers to
the Virtuoso server running on the same computer on port 1111:</para>
<programlisting>
    j2eeadmin -addJdbcXADatasource jdbc/Virtuoso virtuoso.jdbc4.VirtuosoXADataSource -props serverName=localhost portNumber=1111
</programlisting>
					    </listitem>
					</orderedlist>
				</sect3>
				<sect3 id="jdbcrs4">
					<title>JDBC 4.0 javax.sql.RowSet Driver Implementation</title>
					<para>The Virtuoso JDBC 4.0 driver has two implementations of the
          <computeroutput>javax.sql.RowSet</computeroutput> interface -
          <computeroutput>virtuoso.javax.OPLCachedRowSet</computeroutput> and
          <computeroutput>virtuoso.javax.OPLJdbcRowSet</computeroutput>.</para>
          <para>The <computeroutput>virtuoso.javax.OPLCachedRowSet</computeroutput>
          class implements a totally disconnected, memory cached rowset and the
          <computeroutput>virtuoso.javax.OPLJdbcRowset</computeroutput> class
          spans the rest of the JDBC API to implement it's methods.</para>
  </sect3>
  <sect3 id="jdbcrdf4">
      <title>Extension datatype for RDF</title>
      <para>The IRIs and RDF literals, kept in the Virtuoso RDF store are represented by a strings and structures. Thus accessing RDF objects needs special datatypes in order to distinguish strings from IRIs and to get language and datatype of the RDF literals.</para>
      <para>Therefore Virtuoso JDBC driver provides following classes for accessing RDF store: <computeroutput>virtuoso.jdbc4.VirtuosoExtendedString</computeroutput> for IRIs and <computeroutput>virtuoso.jdbc4.VirtuosoRdfBox</computeroutput> for RDF literal objects.</para>
      <para>
	  The class <computeroutput>virtuoso.jdbc4.VirtuosoExtendedString</computeroutput> will be returned when a string representing an IRI is returned to the client. It has two members "str" and "iriType", the "str" member keeps string representation of the IRI, "iriType" denote regular IRI or blank node with enum values VirtuosoExtendedString.IRI and VirtuosoExtendedString.BNODE.
      </para>
      <para>
	  If the RDF literal object have language or datatype specified then <computeroutput>virtuoso.jdbc4.VirtuosoRdfBox</computeroutput> will be returned. The following methods could be used :
      </para>
      <programlisting>
	  String toString () : returns string representation of the literal
	  String getType () : returns string containing the datatype  of the literal
	  String getLang () : returns language code for the literal
      </programlisting>
      <para>
	  The following code snippet demonstrates how to use extension datatypes for RDF
      </para>
      <programlisting><![CDATA[
    ... initialization etc. skipped for brevity
    boolean more = stmt.execute("sparql select * from <gr> where { ?x ?y ?z }");
    ResultSetMetaData data = stmt.getResultSet().getMetaData();
    while(more)
    {
	rs = stmt.getResultSet();
	while(rs.next())
	{
	    for(int i = 1;i <= data.getColumnCount();i++)
	    {
		String s = rs.getString(i);
		Object o = ((VirtuosoResultSet)rs).getObject(i);
		if (o instanceof VirtuosoExtendedString) // String representing an IRI
		  {
		    VirtuosoExtendedString vs = (VirtuosoExtendedString) o;
                    if (vs.iriType == VirtuosoExtendedString.IRI && (vs.strType & 0x01) == 0x01)
			System.out.println ("<" + vs.str +">");
		    else if (vs.iriType == VirtuosoExtendedString.BNODE)
			System.out.println ("<" + vs.str +">");
		  }
		else if (o instanceof VirtuosoRdfBox) // Typed literal
		  {
		    VirtuosoRdfBox rb = (VirtuosoRdfBox) o;
		    System.out.println (rb.rb_box + " lang=" + rb.getLang() + " type=" + rb.getType());

		  }
		else if(stmt.getResultSet().wasNull())
		    System.out.println("NULL");
		else //
		{
		    System.out.println(s);
		}

	    }
	}
	more = stmt.getMoreResults();
    }
    ...
	    ]]></programlisting>
  </sect3>
                                </sect2>
				<sect2 id="JDBCDriverInstallConfig">
					<title>Installation &amp; Configuration Steps</title>
					<para>Perform the following steps in order to make use of your
    Virtuoso Drivers for JDBC:</para>
					<note>
						<title>Note:</title>
						<para>You only have to perform these steps if a first attempt to use the
    Virtuoso Drivers for JDBC fails, the Virtuoso installer will attempt to configure these
    settings for you at installation time.</para>
					</note>
					<orderedlist>
						<listitem>
							<para>Ensure your PATH environment variable is pointing to a
        version of the Java Virtual Machine (JVM) that is compatible with the version of the JDBC
        Driver Manager installed on your machine.  Consult the <link linkend="VirtuosoDriverPackaging">section 
        above</link> to double check.  You can also type the following command to verify Java
        versions:</para>

              <programlisting>java -version</programlisting>

						</listitem>
						<listitem>
							<para>Add the appropriate Virtuoso for JDBC &quot;jar&quot; file
        to your CLASSPATH environment variable.</para>
						</listitem>
						<listitem>
							<para>Attempt to make a connection using one of the
		sample JDBC Applications or Applets provided with your Virtuoso installation.</para>
						</listitem>
					</orderedlist>

  <note><title>Note:</title>
  <para>If you have problems using the virtuoso JDBC driver despite your CLASSPATH being defined correctly, you
  may force the Java Virtual Machine to load a specific JDBC driver using: 
  <computeroutput>-D</computeroutput> on the java command line: e.g:</para> 
  <para><computeroutput>-Djdbc.drivers=virtuoso.jdbc.Driver</computeroutput>.</para>
  <para>You can check the Virtuoso JDBC driver version from the command line using: 
  <computeroutput>java virtuoso.jdbc.Driver</computeroutput></para>
  </note>


				</sect2>
  <sect2 id="JDBCDriverhibernate"><title>Virtuoso JDBC Driver Hibernate Support</title>
    <sect3 id="JDBCDriverhibernateintro"><title>Introduction</title>
      <para><emphasis>What</emphasis></para>
      <para>Hibernate is a powerful, open source, high performance object/relational persistence and query service. Hibernate lets
you develop persistent classes following object-oriented idiom - including association, inheritance, polymorphism, composition, and
collections. Hibernate allows you to express queries in its own portable SQL extension (HQL), as well as in native SQL, or with an
object-oriented Criteria and Example API.
      </para>
      <para><emphasis>Why</emphasis></para>
      <para>Hibernate employs very aggressive, and very intelligent first and second level caching strategy, providing a high
performance and scalable development framework for Java. Greater cross portability and productivity can also be achieve using
hibernate as the same techniques can be employed across multiple databases.
      </para>
      <para><emphasis>How</emphasis></para>
      <para>Hibernate uses JDBC for accessing databases and may require a given database has a custom SQL dialect file that informs
Hibernate what SQL dialects are to be use for performing certain operations against the target database. Although not strictly
required, it should be used to ensure Hibernate Query Language (HQL) statements are correctly converted into the proper SQL
dialect for the underlying database. Virtuoso includes a new jar file called virt_dialect.jar containing the SQL dialect mappings
required between hibernate and Virtuoso and is used in conjunction to the Virtuoso JDBC Drivers (virtjdbc3.jar or virtjdbc4.jar).
      </para>
    </sect3>
    <sect3 id="JDBCDriverhibernatesetupandtesting"><title>Setup and Testing</title>
<para>Three <ulink url="http://virtuoso.openlinksw.com/dataspace/dav/wiki/Main/VirtJdbcHibernate/Hibernate_Examples.zip">sample programs</ulink> are
provided to test Virtuoso hibernate support. Extract the contents of the zip file to a location of choice.
</para>
      <sect4 id="JDBCDriverhibernatesetupandtestingreq"><title>Requirements</title>
<itemizedlist mark="bullet">
  <listitem><ulink url="https://www.hibernate.org/">Hibernate</ulink> 3.3 or higher</listitem>
  <listitem>JDK 5.0 or higher on any operating system</listitem>
  <listitem>Ant 1.6</listitem>
  <listitem><ulink url="http://virtuoso.openlinksw.com/dataspace/dav/wiki/Main/VirtJdbcHibernate/virt_dialect.jar">Virtuoso SQL Dialect jar file</ulink> (virt_dialect.jar)</listitem>
  <listitem><ulink url="http://virtuoso.openlinksw.com/dataspace/dav/wiki/Main/VirtJdbcHibernate/virtjdbc4.jar">Virtuoso JDBC Driver</ulink> (virtjdbc4.jar)</listitem>
</itemizedlist>
      </sect4>
      <sect4 id="JDBCDriverhibernatesetupandtesting"><title>Building and running the example</title>
        <para>The following Ant targets are available:</para>
<programlisting><![CDATA[
clean         Clean the build directory
compile       Build example
run           Build and run example
]]></programlisting>
      </sect4>
      <sect4 id="JDBCDriverhibernateconstr"><title>Hibernate connection string</title>
<para>Edit the file <code>hibernate.cfg.xml</code> in the "bin" and "src" directories of the hibernate application directory
with the correct connection attributes for the Virtuoso Server instance:</para>
<programlisting><![CDATA[
$ more hibernate.cfg.xml
<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
        "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
        "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">

<hibernate-configuration>

    <session-factory>

        <!-- Database connection settings -->
        <property name="connection.driver_class">virtuoso.jdbc4.Driver</property>
        <property name="connection.url">jdbc:virtuoso://localhost:1111/</property>
        <property name="connection.username">dba</property>
        <property name="connection.password">dba</property>

        <!-- JDBC connection pool (use the built-in) -->
        <property name="connection.pool_size">1</property>

        <!-- SQL dialect -->
        <property name="dialect">virtuoso.hibernate.VirtuosoDialect</property>

        <!-- Enable Hibernate's current session context -->
        <property name="current_session_context_class">thread</property>

        <!-- Disable the second-level cache  -->
        <property name="cache.provider_class">org.hibernate.cache.NoCacheProvider</property>

        <!-- Echo all executed SQL to stdout -->
        <property name="show_sql">true</property>

        <!-- Drop and re-create the database schema on startup -->
        <property name="hbm2ddl.auto">create</property>

        <mapping resource="events/Event.hbm.xml"/>

    </session-factory>

</hibernate-configuration>
]]></programlisting>
<para>The key attributes being</para>
<itemizedlist mark="bullet">
  <listitem><emphasis>connection.driver_class</emphasis> - Virtuoso JDBC Driver class name, typically virtuoso.jdbc4.Driver</listitem>
  <listitem><emphasis>connection.url</emphasis> - Virtuoso JDBC Driver connect string for target Virtuoso server instance, of the
form <code>jdbc:virtuoso://hostname:portno</code></listitem>
  <listitem><emphasis>connection.username</emphasis> - Virtuoso Server username</listitem>
  <listitem><emphasis>connection.password</emphasis> - Virtuoso Server password</listitem>
</itemizedlist>
      </sect4>
      <sect4 id="JDBCDriverhibernatesetupandtestingexmp"><title>Examples</title>
      <sect5 id="JDBCDriverhibernatesetupandtestingexmp1"><title>Example 1</title>
<para>This sample performs a simple insert and retrieval of data against the Virtuoso database.
</para>
<orderedlist>
  <listitem>Open your command shell and change to the "ex1" directory</listitem>
  <listitem>The following required files need to be placed in the ./lib directory:
<programlisting><![CDATA[
antlr-2.7.6.jar
commons-collections-3.1.jar
commons-logging-1.0.4.jar
dom4j-1.6.1.jar
hibernate3.jar
javassist-3.4.GA.jar
jta-1.1.jar
lib.lst
log4j-1.2.15.jar
slf4j-api-1.5.10.jar
slf4j-api-1.5.2.jar
slf4j-jcl-1.5.10.jar
virtjdbc4.jar
virt_dialect.jar
]]></programlisting>
</listitem>
  <listitem>Run the example with "ant run" and read the log output on the console:
<programlisting><![CDATA[
$ ant run
Buildfile: build.xml

clean:
   [delete] Deleting directory /Users/hughwilliams/hibernate/ex1/bin
    [mkdir] Created dir: /Users/hughwilliams/hibernate/ex1/bin

copy-resources:
     [copy] Copying 3 files to /Users/hughwilliams/hibernate/ex1/bin
     [copy] Copied 2 empty directories to 1 empty directory under /Users/hughwilliams/hibernate/ex1/bin

compile:
    [javac] Compiling 3 source files to /Users/hughwilliams/hibernate/ex1/bin

run:
     [java] Hibernate: insert into Event (EVENT_DATE, title) values (?, ?)
     [java] Hibernate: select identity_value()
     [java] Hibernate: insert into Event (EVENT_DATE, title) values (?, ?)
     [java] Hibernate: select identity_value()
     [java] Hibernate: select event0_.EVENT_ID as EVENT1_0_, event0_.EVENT_DATE as EVENT2_0_, event0_.title as title0_ from Event event0_
     [java] Event: My Event1 Time: 2010-03-14 03:27:51.0
     [java] Event: My Event2 Time: 2010-03-14 03:27:53.0

BUILD SUCCESSFUL
Total time: 3 seconds
]]></programlisting>
</listitem>
  <listitem>Hibernate logging levels can be varied by changing the settings in the src/hibernate.cfg.xml and src/log4j.properties files.</listitem>
</orderedlist>
      </sect5>
      <sect5 id="JDBCDriverhibernatesetupandtestingexmp2"><title>Example 2</title>
<para>Hello World with Java Persistence</para>
<orderedlist>
  <listitem>Open your command shell and change to the "ex2" directory</listitem>
  <listitem>The following required files need to be placed in the ./lib directory:
<programlisting><![CDATA[

antlr-2.7.6.jar
asm-attrs.jar
asm.jar
c3p0-0.9.0.jar
cglib-2.1.3.jar
commons-collections-2.1.1.jar
commons-logging-1.0.4.jar
dom4j-1.6.1.jar
ejb3-persistence.jar
freemarker.jar
hibernate-annotations.jar
hibernate-commons-annotations.jar
hibernate-entitymanager.jar
hibernate-tools.jar
hibernate3.jar
javassist.jar
jboss-archive-browsing.jar
jta.jar
log4j-1.2.13.jar
virtjdbc4.jar
virt_dialect.jar
]]></programlisting>
</listitem>
  <listitem>Use "ant schemaexport" to export a database schema automatically to the database. Ignore any errors about failing
ALTER TABLE statements, they are thrown because there are no tables when you run this for the first time.
<programlisting><![CDATA[
$ ant schemaexport
Buildfile: build.xml

compile:

copymetafiles:

schemaexport:
[hibernatetool] Executing Hibernate Tool with a JPA Configuration
[hibernatetool] 1. task: hbm2ddl (Generates database schema)
[hibernatetool]
[hibernatetool]     drop table MESSAGES;
[hibernatetool]
[hibernatetool]     create table MESSAGES (
[hibernatetool]         MESSAGE_ID decimal(20,0)  identity,
[hibernatetool]         MESSAGE_TEXT varchar(255) null,
[hibernatetool]         NEXT_MESSAGE_ID decimal(20,0) null,
[hibernatetool]         primary key (MESSAGE_ID)
[hibernatetool]     );
[hibernatetool]
[hibernatetool]     alter table MESSAGES
[hibernatetool]         add
[hibernatetool]         foreign key (NEXT_MESSAGE_ID)
[hibernatetool]         references MESSAGES;

BUILD SUCCESSFUL
Total time: 2 seconds
]]></programlisting>
</listitem>
  <listitem>Check the DDL that was also exported to the file helloworld-ddl.sql
<programlisting><![CDATA[
$ more helloworld-ddl.sql

    drop table MESSAGES;

    create table MESSAGES (
        MESSAGE_ID decimal(20,0)  identity,
        MESSAGE_TEXT varchar(255) null,
        NEXT_MESSAGE_ID decimal(20,0) null,
        primary key (MESSAGE_ID)
    );

    alter table MESSAGES
        add
        foreign key (NEXT_MESSAGE_ID)
        references MESSAGES;
]]></programlisting>
</listitem>
  <listitem>Run the example with "ant run" and read the log output on the console
<programlisting><![CDATA[
$ ant run
Buildfile: build.xml

compile:

copymetafiles:

run:
     [java] 1 message(s) found:
     [java] Hello World with JPA

BUILD SUCCESSFUL
Total time: 2 seconds
]]></programlisting>
</listitem>
  <listitem>Call ant run again
<programlisting><![CDATA[
$ ant run
Buildfile: build.xml

compile:

copymetafiles:

run:
     [java] 2 message(s) found:
     [java] Hello World with JPA
     [java] Hello World with JPA

BUILD SUCCESSFUL
Total time: 2 seconds
]]></programlisting>
</listitem>
  <listitem>If you call ant schemaexport again, all tables will be re-created </listitem>
  <listitem>Hibernate logging levels can be varied by changing the settings in the
src/etc/log4j.properties and src/etc/META-INF/persistence.xml files</listitem>
</orderedlist>
      </sect5>
      <sect5 id="JDBCDriverhibernatesetupandtestingexmp3"><title>Example 3</title>
<para>This sample performs more complex insert and retrieval of data against the Virtuoso database.</para>
<orderedlist>
  <listitem>Open your command shell and change to the "ex3" directory</listitem>
  <listitem>The following required files need to be placed in the ./lib directory:
<programlisting><![CDATA[
]]></programlisting>
antlr-2.7.6.jar
commons-collections-3.1.jar
commons-logging-1.0.4.jar
dom4j-1.6.1.jar
hibernate3.jar
javassist-3.4.GA.jar
jta-1.1.jar
libs.lst
log4j-1.2.15.jar
slf4j-api-1.5.10.jar
slf4j-api-1.5.2.jar
slf4j-jcl-1.5.10.jar
virtjdbc4.jar
virt_dialect.jar
</listitem>
  <listitem>Run the example with "ant run" and read the log output on the console:
<programlisting><![CDATA[
$ ant run
Buildfile: build.xml

clean:
   [delete] Deleting directory /Users/hughwilliams/hibernate/ex3/bin
    [mkdir] Created dir: /Users/hughwilliams/hibernate/ex3/bin

copy-resources:
     [copy] Copying 4 files to /Users/hughwilliams/hibernate/ex3/bin
     [copy] Copied 2 empty directories to 1 empty directory under /Users/hughwilliams/hibernate/ex3/bin

compile:
    [javac] Compiling 4 source files to /Users/hughwilliams/hibernate/ex3/bin
    [javac] Note: Some input files use unchecked or unsafe operations.
    [javac] Note: Recompile with -Xlint:unchecked for details.

run:
     [java] Hibernate: insert into EVENTS (EVENT_DATE, title) values (?, ?)
     [java] Hibernate: select identity_value()
     [java] Hibernate: insert into EVENTS (EVENT_DATE, title) values (?, ?)
     [java] Hibernate: select identity_value()
     [java] Hibernate: insert into PERSON (age, firstname, lastname) values (?, ?, ?)
     [java] Hibernate: select identity_value()
     [java] Hibernate: select person0_.PERSON_ID as PERSON1_2_0_, event2_.EVENT_ID as EVENT1_0_1_, person0_.age as age2_0_, person0_.firstname as firstname2_0_, person0_.lastname as lastname2_0_, event2_.EVENT_DATE as EVENT2_0_1_, event2_.title as title0_1_, events1_.PERSON_ID as PERSON2_0__, events1_.EVENT_ID as EVENT1_0__ from PERSON person0_ left outer join PERSON_EVENT events1_ on person0_.PERSON_ID=events1_.PERSON_ID left outer join EVENTS event2_ on events1_.EVENT_ID=event2_.EVENT_ID where person0_.PERSON_ID=?
     [java] Hibernate: select event0_.EVENT_ID as EVENT1_0_0_, event0_.EVENT_DATE as EVENT2_0_0_, event0_.title as title0_0_ from EVENTS event0_ where event0_.EVENT_ID=?
     [java] Hibernate: select participan0_.EVENT_ID as EVENT1_1_, participan0_.PERSON_ID as PERSON2_1_, person1_.PERSON_ID as PERSON1_2_0_, person1_.age as age2_0_, person1_.firstname as firstname2_0_, person1_.lastname as lastname2_0_ from PERSON_EVENT participan0_ left outer join PERSON person1_ on participan0_.PERSON_ID=person1_.PERSON_ID where participan0_.EVENT_ID=?
     [java] Hibernate: insert into PERSON_EVENT (PERSON_ID, EVENT_ID) values (?, ?)
     [java] Hibernate: update PERSON set age=?, firstname=?, lastname=? where PERSON_ID=?
     [java] Added person 1 to event 2
     [java] Hibernate: insert into PERSON (age, firstname, lastname) values (?, ?, ?)
     [java] Hibernate: select identity_value()
     [java] Hibernate: select person0_.PERSON_ID as PERSON1_2_0_, person0_.age as age2_0_, person0_.firstname as firstname2_0_, person0_.lastname as lastname2_0_ from PERSON person0_ where person0_.PERSON_ID=?
     [java] Hibernate: select emailaddre0_.PERSON_ID as PERSON1_0_, emailaddre0_.EMAIL_ADDR as EMAIL2_0_ from PERSON_EMAIL_ADDR emailaddre0_ where emailaddre0_.PERSON_ID=?
     [java] Hibernate: insert into PERSON_EMAIL_ADDR (PERSON_ID, EMAIL_ADDR) values (?, ?)
     [java] Hibernate: select person0_.PERSON_ID as PERSON1_2_0_, person0_.age as age2_0_, person0_.firstname as firstname2_0_, person0_.lastname as lastname2_0_ from PERSON person0_ where person0_.PERSON_ID=?
     [java] Hibernate: select emailaddre0_.PERSON_ID as PERSON1_0_, emailaddre0_.EMAIL_ADDR as EMAIL2_0_ from PERSON_EMAIL_ADDR emailaddre0_ where emailaddre0_.PERSON_ID=?
     [java] Hibernate: insert into PERSON_EMAIL_ADDR (PERSON_ID, EMAIL_ADDR) values (?, ?)
     [java] Added two email addresses (value typed objects) to person entity : 1
     [java] Hibernate: select event0_.EVENT_ID as EVENT1_0_, event0_.EVENT_DATE as EVENT2_0_, event0_.title as title0_ from EVENTS event0_
     [java] Event: My Event Time: 2010-03-14 03:30:02.0
     [java] Event: My Event Time: 2010-03-14 03:30:06.0

BUILD SUCCESSFUL
Total time: 5 seconds
]]></programlisting>
</listitem>
  <listitem>Hibernate logging levels can be varied by changing the settings in the src/hibernate.cfg.xml and src/log4j.properties files.</listitem>
</orderedlist>
      </sect5>
      <sect5 id="JDBCDriverhibernatesetupandtestingexmp4"><title>Example 4</title>
      <para>This example demonstrates how to make Multi Thread Virtuoso connection using JDBC.</para>
      <para>It starts 3 threads: one thread executes SPARQL select and two threads execute SPARQL inserts:</para>
<programlisting><![CDATA[
import java.util.*;
import java.sql.*;
import java.math.*;

public class MTtest extends Thread {

  int mode = 0;
  int startId = 0;

  static  String urlDB = "jdbc:virtuoso://localhost:1111";

 
 public MTtest(int _mode, int _init) {
   mode = _mode;
   startId = _init;
 }



 void prnRs(ResultSet rs)
 {
   try {
     ResultSetMetaData rsmd;

     System.out.println(">>>>>>>>");
     rsmd = rs.getMetaData();
     int cnt = rsmd.getColumnCount();

       while(rs.next()) {
         Object o;

         System.out.print("Thread:"+Thread.currentThread().getId()+"  ");
         for (int i = 1; i <= cnt; i++) {
           o = rs.getObject(i);
           if (rs.wasNull())
             System.out.print("<NULL> ");
           else
             System.out.print("["+ o + "] ");
         }
         System.out.println();
       }

   } catch (Exception e) {
     System.out.println(e);
     e.printStackTrace();
   }
   System.out.println(">>>>>>>>");
 }




 public static void main(String argv[])
 {
  try {

    Class.forName("virtuoso.jdbc3.Driver");

    Connection conn = DriverManager.getConnection(urlDB,"dba","dba");
    Statement st = conn.createStatement();

    st.execute("sparql clear graph <mttest>");
    st.execute("sparql insert into graph <mttest> { <xxx> <P01> \"test1\" }");
    st.execute("sparql insert into graph <mttest> { <xxx> <P01> \"test2\" }");
    st.execute("sparql insert into graph <mttest> { <xxx> <P01> \"test3\" }");
    st.execute("sparql insert into graph <mttest> { <xxx> <P01> \"test4\" }");
    st.execute("sparql insert into graph <mttest> { <xxx> <P01> \"test5\" }");
    conn.close();


    int init = 0;

    for(int i=0; i < 2; i++) {
      MTtest thr1 = new MTtest(1, init);
      init+=10;

      MTtest thr2 = new MTtest(0, init);
      init+=10;

      MTtest thr3 = new MTtest(0, init);
      init+=10;

      thr1.start();
      thr2.start();
      thr3.start();

      thr1.join();
      thr2.join();
      thr3.join();
    }

    System.out.println("===End===");

  } catch (Exception e) {
    System.out.print(e);
    e.printStackTrace();
  }
 }


 public void run( ) 
 {
  try {

    Connection conn = DriverManager.getConnection(urlDB,"dba","dba");
    Statement st;

    st = conn.createStatement();

    if (mode == 1) 
    {
      String query = "sparql SELECT * from <mttest> WHERE {?s ?p ?o}";
      ResultSet rs = st.executeQuery(query);
      prnRs(rs);
    }
    else
    {
      long id = Thread.currentThread().getId();
      for (int i =0; i < 5; i++)
        st.execute("sparql insert into graph <mttest> { <xxx"+startId+"> <P"+id+"> \"test"+i+"\" }");

      System.out.println("\nThread:"+Thread.currentThread().getId()+"  ===Rows Inserted===");
    }


    conn.close();
  
  } catch (SQLException e) {
        System.out.println("===========================================================");
        System.out.println(">>["+e.getMessage()+"]");
        System.out.println(">>["+e.getErrorCode()+"]");
        System.out.println(">>["+e.getSQLState()+"]");
        System.out.println(e);
        System.out.println("===========================================================");
        e.printStackTrace();
        System.exit(-1);
  } catch (Exception e) {
        System.out.println("===========================================================");
        System.out.println(e);
        System.out.println("===========================================================");
        e.printStackTrace();
        System.exit(-1);
  }
 } // run( )





}	
]]></programlisting>      
      </sect5>      
      </sect4>
    </sect3>
  </sect2>
			</sect1>

&oledbimplementation;

&inprocess;

<sect1 id="accintudsockets"><title>Unix Domain Socket Connections</title>

  <para>Client connections to Virtuoso servers running on the same Unix or Linux 
  server host can benefit from faster connections utilizing Unix Domain Sockets.  
  This does not apply to Windows platforms.</para>

 <para>By default Virtuoso will open a Unix Domain listen socket in addition 
 to the TCP listen socket.  The name of the UD socket will be:</para>

<programlisting><![CDATA[
/tmp/virt-<tcp-listen-port>
]]></programlisting>

  <para>When a client attempts to connect to the Virtuoso server using the 
  specific address <computeroutput>localhost</computeroutput> it will 
  first try connecting to the UD socket, failing that it will silently revert 
  to the TCP socket.</para>

    <para>Unix Domain Socket connections only work if 
	<computeroutput>localhost</computeroutput> is explicitly specified or the 
	host is unspecified which defaults to a localhost connection.  
	UD socket connections will <emphasis>not</emphasis> work to any other address 
	such as:</para>

<programlisting><![CDATA[
virt.mydomain.com:1111
127.0.0.1:1111
]]></programlisting>

  <para>regardless of whether that is the localhost or not.</para>

  <para>Unix Domain sockets can be disabled using the 
  <computeroutput>DisableUnixSocket</computeroutput> parameter in the 
  Parameters section of the Virtuoso INI file.</para>

  <para>The <link linkend="fn_sys_connected_server_address"><function>sys_connected_server_address()</function></link>
  function can be used to check the connection type.  It will return </para>
  <programlisting><![CDATA[
/tmp/virt-<tcp-listen-port>
]]></programlisting>
<para>for connections using UD sockets.</para>

</sect1>

<sect1 id="dataccessclientsconfailandbalance"><title>Virtuoso Data Access Clients Connection Fail over and Load Balancing Support</title>
  <para>The Virtuoso Data Access Clients ODBC, JDBC, ADO.Net, OLE DB, Sesame, Jena and Redland as of Release 6.1 and above support round
robin connections to Virtuoso server instances enabling server fail over, load balancing and fault tolerant connections to be performed
across multiple server instances configured in a cluster or as separate server instances.
  </para>
  <para>Fail over connections are enabled by specifying a comma delimited list of servers to failover to, in the "Host" or 'Server"
connect string attribute, with the list being worked through in the order presented to determine which Virtuoso Server instance is
used. A Round robin (load balanced) connection can be configured by adding the connect string attribute "RoundRobin" = [True | Yes |
False | No], in which case the server for the connection is chosen at random from the comma delimited provided as for a Failover
connection above.
  </para>
  <para>Example connect strings for Virtuoso ODBC, JDBC, ADO.Net and OLE DB driver/providers are provided below. The Virtuoso Sesame
and Jena providers which make use of the JDBC driver and Redland Provider which makes use of the ODBC driver, would simply make use
of a suitably configured JDBC or ODBC connect string to enable Failover or Round Robin connections to be made with them.
  </para>
  <sect2 id="dataccessclientsconfailandbalanceodbc"><title>ODBC</title>
    <sect3 id="dataccessclientsconfailandbalanceodbcf"><title>Failover Connect String format</title>
<programlisting><![CDATA[
Driver={OpenLink Virtuoso};Host=server1:port1,server2:port2,server3:port3;UID=dba;PWD=dba;
]]></programlisting>
    </sect3>
    <sect3 id="dataccessclientsconfailandbalanceodbcr"><title>Round Robin Connect String format</title>
<programlisting><![CDATA[
Driver={OpenLink Virtuoso};Host=server1:port1,server2:port2,server3:port3;UID=dba;PWD=dba;RoundRobin=Yes"
]]></programlisting>
      <para>Or alternatively ensure the "use Round Robin for failover connection" check box in the setup dialog.</para>
      <figure id="adf1" float="1">
        <title>ODBC Round Robin Connect String format</title>
        <graphic fileref="ui/adf1.png"/>
      </figure>
    </sect3>
  </sect2>
  <sect2 id="dataccessclientsconfailandbalanceado"><title>ADO.Net</title>
    <sect3 id="dataccessclientsconfailandbalanceadof"><title>Failover Connect String format</title>
<programlisting><![CDATA[
Server=server1:port1,server2:port2,server3;UserId=dba;Password=dba;
]]></programlisting>
    </sect3>
    <sect3 id="dataccessclientsconfailandbalanceador"><title>Round Robin Connect String format</title>
<programlisting><![CDATA[
Server=server1:port1,server2:port2,server3;UserId=dba;Password=dba;Round Robin=true;Pooling=false;
]]></programlisting>
    </sect3>
  </sect2>
  <sect2 id="dataccessclientsconfailandbalancejdbc"><title>JDBC</title>
    <sect3 id="dataccessclientsconfailandbalancejdbcf"><title>Failover Connect String format</title>
<programlisting><![CDATA[
jdbc:virtuoso://server1:port1,server2:port2,server3/UID=dba/PWD=dba/;
]]></programlisting>
    </sect3>
    <sect3 id="dataccessclientsconfailandbalancejdbcr"><title>Round Robin Connect String format</title>
<programlisting><![CDATA[
jdbc:virtuoso://server1:port1,server2:port2,server3:1111/UID=dba/PWD=dba/ROUNDROBIN=yes;
]]></programlisting>
    </sect3>
  </sect2>
  <sect2 id="dataccessclientsconfailandbalanceole"><title>OLE DB</title>
    <sect3 id="dataccessclientsconfailandbalanceolef"><title>Failover Connect String format</title>
<programlisting><![CDATA[
Provider=VIRTOLEDB;Data Source=server1:port1,server2:port2,server3;User Id=dba;Password=dba;Initial Catalog=Demo;Prompt=NoPrompt;
]]></programlisting>
    </sect3>
    <sect3 id="dataccessclientsconfailandbalanceoler"><title>Round Robin Connect String format</title>
<programlisting><![CDATA[
  Provider=VIRTOLEDB;Data Source=server1:port1,server2:port2,server3;User Id=dba;
Password=dba;Initial Catalog=Demo;Prompt=NoPrompt;Round Robin=true
]]></programlisting>
    </sect3>
  </sect2>
  <sect2 id="dataccessclientsconfailandbalancesesm"><title>Sesame</title>
    <sect3 id="dataccessclientsconfailandbalancesesmf"><title>Failover Connect String format</title>
<programlisting><![CDATA[
VirtuosoRepository("server1:port1,server2:port2,server3", "uid", "pwd");
]]></programlisting>
    </sect3>
    <sect3 id="dataccessclientsconfailandbalancesesmr"><title>Round Robin Connect String format</title>
<programlisting><![CDATA[
VirtuosoRepository("server1:port1,server2:port2,server3", "uid", "pwd");
((VirtuosoRepository)repository).setRoundrobin(true);
]]></programlisting>
    </sect3>
    <sect3 id="dataccessclientsconfailandbalancesesms"><title>Sample program</title>
<programlisting><![CDATA[
/*
 *  $Id$
 *
 *  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 *  project.
 *
 *  Copyright (C) 1998-2018 OpenLink Software
 *
 *  This project is free software; you can redistribute it and/or modify it
 *  under the terms of the GNU General Public License as published by the
 *  Free Software Foundation; only version 2 of the License, dated June 1991.
 *
 *  This program is distributed in the hope that it will be useful, but
 *  WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 *  General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License along
 *  with this program; if not, write to the Free Software Foundation, Inc.,
 *  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 */

import java.sql.*;
import java.util.*;
import java.lang.*;

import org.openrdf.model.*;
import org.openrdf.query.*;
import org.openrdf.repository.*;
import org.openrdf.rio.*;
import virtuoso.jdbc4.*;

import virtuoso.sesame2.driver.*;

public class TestSesame2 {

  public static void main(String[] args) {

      Repository repository = new
	VirtuosoRepository("localhost:1111,localhost:1311,localhost:1312,localhost:1313", "dba", "dba");
      ((VirtuosoRepository)repository).setRoundrobin(true);

      RepositoryConnection con = null;
      Random rnd = new Random();
      for (int i = 0; i < 1000000; ) {
	  try {
	      if (null == con) {
		  System.out.println("New connection");
		  con = repository.getConnection();
	      }

	      TupleQuery query = con.prepareTupleQuery(
		      QueryLanguage.SPARQL, "INSERT INTO <test_g> { <sub" + i + "> <pred> <obj" + i+ "> . " +
		      " <r" + Math.abs (rnd.nextInt()) + "> <rndpred> <r" + Math.abs (rnd.nextInt ()) + "> . }");
	      TupleQueryResult queryResult = query.evaluate();
	      /*long count = 0;
	      while (queryResult.hasNext())
	      {
		  queryResult.next();
		  count++;
		  if (count % 1000 == 0)
		  {
		      System.out.println("Passed " + count + " results...");
		  }
	      }
	      */
	      queryResult.close();
	      i++;
	      try { Thread.sleep(100); } catch (InterruptedException ie) { }

	  } catch (Exception e) {
	      String state = "";
	      if (e.getCause() instanceof SQLException) {
		  state = ((SQLException)e.getCause()).getSQLState();
	      }
	      System.out.println("ERROR:" + state + " " + e.getCause());
	      try { Thread.sleep(2000); } catch (InterruptedException ie) { }
	      System.out.println("ERROR:" + e.toString ());
	      if (state == "")
	        e.printStackTrace();
	      try {
		  if (con != null /*&& (state == "08U01" || state == "S2801")*/) {
		      System.out.println("Closing Connection.");
		      con.close();
		      con = null;
		  }
	      } catch (RepositoryException re) {
		  System.out.println("Test Failed.");
		  re.printStackTrace();
		  System.exit (1);
	      }
	  } finally {
	  }
      }
  }
}
]]></programlisting>
    </sect3>
  </sect2>
</sect1>

</chapter>