This chapter describes Web server gateways and explains how to use them with jConnect. The chapter is divided into these sections:About Web Server Gateways
If your database server runs on a different host than your Web server, or if you are developing Internet applications that must connect to a secure database server through a firewall, you need a gateway to act as a proxy, providing a path to the database server. To connect to servers using the Secure Sockets Layer (SSL) protocol, jConnect provides a Java servlet that you can install on any Web server that supports the javax.servlet interfaces. This servlet enables jConnect to support encryption using the Web server as the gateway.
jConnect uses TDS to communicate with database servers. HTTP-tunnelled TDS is useful for forwarding requests. Requests from a client to a back-end server that go through the gateway contain TDS in the body of the request. The request header indicates the length of the TDS included in the request packet.TDS is a connection-oriented protocol, whereas HTTP is not. To support security features such as encryption for Internet applications, jConnect uses a TDS-tunnelling servlet to maintain a logical connection across HTTP requests. The servlet generates a session ID during the initial login request, and the session ID is included in the header of every subsequent request. Using session IDs lets you identify active sessions, and even resume a session as long as the servlet has an open connection using that specific session ID.The logical connection provided by the TDS-tunnelling servlet enables jConnect to support encrypted communication between two systems--for example, a jConnect client with the CONNECT_PROTOCOL connection property set to "https" connecting to a Web server running the TDS-tunnelling servlet. jConnect and Gateway Configuration
There are several options for setting up your Web servers and Adaptive Servers. Four common configurations are described below. These examples show where to install the jConnect driver and when to use the Cascade gateway or a gateway with the TDS-tunnelling servlet. Web Server and Adaptive Server on One HostIn this two-tier configuration, the Web server and Adaptive Server are both installed on the same host.
If your database server runs on a different host than the Web server, even if there is no firewall, you need a gateway to act as a proxy, providing a path to the database server. The jConnect installation includes a Cascade gateway, a slightly modified version of the Cascade Web server written in Java by David Wilkerson (email: firstname.lastname@example.org; Web site: http://www.cascade.org.uk/). The Cascade gateway receives and forwards packets, switching from HTTP to TDS when sending a request to the Adaptive Server, and from TDS to HTTP when returning results.
The Cascade gateway is installed when you perform a full jConnect installation, either using the jConnect installer, or using the install.bat or install.sh files. You can also use the jConnect installer to install only the Cascade gateway files, if necessary. See the Sybase JConnect for JDBC Installation Guide and Release Bulletin. Starting the Cascade Gateway
Follow the platform-specific instructions below to test the Cascade gateway. Windows NT and Windows 95
Your JDBC_HOME environment variable should be set to this directory.
If the command executes successfully, you see output from httpd.bat, ending with:
UNIXChange to the directory where you installed jConnect (the JDBC_HOME directory). Type the following command:
sh httpd.sh &
For Windows, go to a DOS prompt and enter:
httpd -Dverbose=1 > filename
For UNIX, enter:
sh httpd.sh -Dverbose=1 > filename &
In these commands, filename is the output file for debug messages.
it means another process is running on the port specified in the www.dos (DOS) or www.template (UNIX) file, located in JDBC_HOME. This error occurs when you start the gateway.
Testing the Cascade Gateway
To check your setup and test the Cascade gateway, you can run a validation program that connects to the Sybase demonstration database.
java sample.SybSample Validate
For jConnect 5.0, type
java sample2.SybSample Validate
If the validation is successful, you see the jConnect version number and the message "Connected successfully" in the Sample output window. TroubleshootingIf you receive a "Bad command or file name" error (Windows 95) or a "Name specified is not recognized as an internal or external command" error (Windows NT), make sure that your path includes the \bin subdirectory of the JDK home directory. Reading the index.html File
Use your Web browser to view the index.html file in your jConnect installation directory. index.html provides links to the jConnect documentation and sample code.
If the browser and the Cascade gateway are running on different hosts, enter:
where host is the name of the host on which the Cascade gateway is running, and port is the listening port.TroubleshootingIf you entered the correct host, port, and file information, but the browser cannot open this link, the Cascade gateway is not running. See "Starting the Cascade Gateway". Running the Sample Isql Applet
After loading the index.html file in your browser:
This takes you to the jConnect Sample Programs page.
For jConnect 4.1
For jConnect 5.0
To define a connection in your application that uses the Cascade gateway, put the name of the host on which the Cascade gateway is running in the URL:
host:portwhere host is the name of the host on which the Cascade gateway is running, and port is the listening port. Using the TDS-Tunnelling Servlet
In order to use the TDS-tunnelling servlet, you need a Web server that supports the javax.servlet interfaces, such as Sun Microsystems, Inc.'s JavaTM Web server. When you install the Web server, include the jConnect TDS-tunnelling servlet in the list of active servlets. You can also set servlet parameters to define connection timeouts and maximum packet size. With the TDS-tunnelling servlet, requests from a client to the back-end server that go through the gateway include a GET or POST command, the TDS session ID (after the initial request), back-end address, and status of the request. TDS is in the body of the request. Two header fields indicate the length of the TDS stream and the session ID assigned by the gateway.When the client sends a request, the Content-Length header field indicates the size of the TDS content, and the request command is POST. If there is no TDS data in the request because the client is either retrieving the next portion of the response data from the server, or closing the connection, the request command is GET.The following example illustrates how information is passed between the client and an HTTPS gateway using the TDS-tunneled HTTPS protocol. This example shows a connection to a back-end server named DBSERVER with a port number "1234."Client to gateway login request. No session ID:
To use the jConnect servlet for TDS-tunneled HTTP, you need:
Your jConnect installation includes a gateway subdirectory (jConnect 4.1) or gateway2 subdirectory (jConnect 5.0) under the classes directory. The subdirectory contains files required for the TDS-tunnelling servlet.Copy the jConnect gateway package to a gateway subdirectory (jConnect 4.1) or gateway2 subdirectory (jConnect 5.0) under your Web server's servlets directory. Once you have copied the servlets, activate the servlets by following the instructions for your Web server. Setting Servlet Arguments When you add the servlet to your Web server, you can enter optional arguments to customize performance:
If you have interactive client programs that may be idle for long periods of time and you don't want the connections broken, increase the TdsSessionIdleTimeout.
You can also set the connection timeout value from the jConnect client using the SESSION_TIMEOUT connection property. This is useful if you have specific applications that may be idle for longer periods. In this case, set a longer timeout for those connections with the SESSION_TIMEOUT connection property, rather than setting it for the servlet.
Refer to your Web server documentation for complete instructions on entering servlet arguments. Invoking the Servlet
jConnect determines when to use the gateway where the TDS-tunnelling servlet is installed based on the path extension of the proxy connection property. jConnect recognizes the servlet path extension to the proxy and invokes the servlet on the designated gateway.Define the connection URL using this format:
jConnect invokes the TDS-tunnelling servlet on the Web server to tunnel TDS through HTTP. The servlet path must be the path you defined in your Web server's servlet alias list. Tracking Active TDS Sessions
You can view information about active TDS sessions, including the server connections for each session. Use your Web browser to open the administrative URL:
For example, if your server is MYSERVER and the TDS servlet path is /tds, you would enter:
This shows you a list of active TDS sessions. You can click on a session to see more information, including the server connection. Terminating TDS SessionsYou can use the URL described above to terminate any active TDS session. Click on an active session from the list of sessions on the first page, then click Terminate This Session. Resuming a TDS Session
You can set the SESSION_ID connection property so that, if necessary, you can resume an existing open connection. When you specify a SESSION_ID, jConnect skips the login phase of the protocol and resumes the connection with the gateway using the designated session ID. If the session ID you specified does not exist on the servlet, jConnect throws a SQL exception the first time you attempt to use the connection. TDS Tunnelling and Netscape Enterprise Server 3.5.1 on Solaris
Netscape Enterprise Server 3.5.1 does not support the javax.servlet.ServletConfig.getInitParameters( ) or javax.servlet.ServletConfig.getInitParameterNames( ) methods. To provide the necessary parameter values, you need to replace calls to getInitParameter( ) and getInitParameterNames( ) with hard-coded parameter values in TDSTunnelServlet.java. To enter the required parameter values in TDSTunnelServlet.java and use TDS tunnelling with Netscape Enterprise Server 3.5.1 on Solaris:
This should result in the following files:
An easy way to do this is to recursively copy everything under $JDBC_HOME/classes to NSE_3.5.1_install_dir/docs, as:
cp -r $JDBC_HOME/classes NSE_3.5.1_install_dir/docs
This copies a number of files and directories that are not under $JDBC_HOME/classes/com/sybase. The extra files and directories are harmless, but take up disk space. You can delete them to reclaim the disk space.
For example, in $JDBC_HOME/sample/gateway.html, you would edit the proxy parameter to appear as follows:
<param name=proxy value="http://hostname/servlet/
Sybase(R) jConnect for JDBC(TM) Programmer's Reference - 29 Jan 1999 Copyright 1999 © Sybase, Inc. All Rights Reserved.