Connecting to a Host Integrator Server

Use of the Host Integrator JDBC connector is always within the context of the standard java.sql.* classes. Connecting to a Host Integrator session using JDBC is a three step process:

1. Import the java.sql.* classes.

To do so, include the following line at the top of your Java file:

import java.sql.*;

2. Register the Host Integrator driver with the JDBC Driver Manager.

The Host Integrator driver is implemented in com.wrq.apptrieve.jdbc.ApptrieveDriver.class; Include the following Java statement before using the JDBC connector:


3. Connect to the Host Integrator JDBC driver using the standard DriverManager methods.

The java.sql.DriverManager class contains a getConnection method which establishes a connection to a database using the desired driver. There are three forms of this method: one that takes only a URL string which specifies the connection to make, one that takes a URL and a java.util.Properties object, and one that takes a URL and user name and password String parameters.

The key parameter to each of these three variants is the URL string. The syntax for Host Integrator is as follows:


The first part of the URL, 'jdbc:apptrieve:table' indicates that you want to make a connection using the Host Integrator JDBC connector (formerly called Apptrieve).

A connection can be made either directly with the Host Integrator Server or, to use the dynamic load balancing and failover features of the product, indirectly using a domain. To specify a serverID, use the server keyword and include either the hostname of the server or the IP address for the desired server. To specify a domain, include the AADS keyword and the AADS hostname or IP address and the domain keyword, along with the name of the Host Integrator domain that you wish to use. Never include both the server keyword and the AADS/domain keywords because they are mutually exclusive.

A Host Integrator session can either load a model when the connection is established, or it can use an existing session from a session pool. To specify a model-based session, use the database keyword and include the name of the model that you wish to use.

Models and session pools are configured with the Host Integrator Administrative WebStation. Never include both a database keyword and a session keyword in a URL—they are mutually exclusive.

If security is enabled for the domain or Host Integrator Server, you must specify the user name and password for the connection using the user and password keywords. Alternatively, you can use the getConnection() method that includes user and password String parameters—these do exactly the same thing as specifying the user and password in the URL itself. These keywords refer to the user name and password for the Host Integrator Server—not the host that the Host Integrator Server connects to for executing the model or the session pool. If these need to be passed into the session, use the 'variables' part of the URL to set the built-in userid and password model variables. The variables keyword can set any model variable that is included in the model and has write permission as established in the model definition.

The debug keyword enables the JDBC connector debug messages, which are sent to either standard 'out' or standard 'err' output stream. The messages may be useful in debugging your application.

Example URL Strings

The following are example URLs to illustrate the various alternatives of establishing a connection to a Host Integrator session:

  1. Simple connection to a model, no security or model variables:
String url = jdbc:apptrieve:table;serverid=vhi_server;database=CCSDemo
  1. Connection to a domain, security enabled:

String url = jdbc:apptrieve:table;aads=vhi_aads;domain=myDomain;database=CCSDemo;
  1. Connection to a session pool, specifying host user name and password:

String url = jdbc:apptrieve:table;serverid=vhi_server;session=CCSDemoSessionPool;

Examples of using DriverManager.getConnection()

Once you have a suitable URL string, include it in one of the three getConnection methods to establish a connection with the Host Integrator Server. For example, to specify everything using a URL:

Connection myConnection = DriverManager.getConnection(url);

To specify a Host Integrator user name and password in the method call rather than in the URL, use the three parameter form:

	Connection myConnection = DriverManager.getConnection(url, "vhi_user", "login1");

Finally, any of the keywords that can be used in a URL string can alternatively be put into a java.util.Properties object and sent to the JDBC connector using the two parameter form of getConnection():

	java.util.Properties myProps = new java.util.Properties();
	myProps.put("serverid", "vhi_server");
	myProps.put("database", "CCSDemo");
	Connection myConnection = DriverManager.getConnection("jdbc:apptrieve:table", myProps);