---

6. Web Server Gateways

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

• Using the Cascade Gateway

• Using the TDS-Tunnelling Servlet

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.

Note	jConnect includes support for SSL on the client system. For information on jConnect's client-side support of SSL, see "Implementing Custom Socket Plug-Ins".

jConnect includes a Cascade gateway, a slightly modified version of the Cascade Web server. The Cascade gateway supports the CONNECT HTTP method, which allows HTTP-tunnelling of Tabular Data Stream (TDS) data. You can use the Cascade gateway to connect to a database server that runs on a different host than the Web server, but that does not need to pass through a firewall. See "Using the Cascade Gateway". TDS Tunnelling

---

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.

• Install jConnect on the Web server host.

• No gateway required.

Dedicated JDBC Web Server and Adaptive Server on One HostWith this configuration, you have a separate host for your main Web server. A second host is shared by a Web server specifically for Adaptive Server access and the Adaptive Server. Links from the main server direct requests requiring SQL access to the dedicated Web server.

• Install jConnect on the second (Adaptive Server) host.

• No gateway required.

Web Server and Adaptive Server on Separate HostsIn this three-tier configuration, the Adaptive Server is on a separate host from the Web server. jConnect requires a gateway to act as a proxy to the Adaptive Server.

• Install jConnect on the Web server host.

• Requires either a TDS-tunnelling servlet or the Cascade gateway.

Connecting to a Server Through a FirewallTo connect to a server protected by a firewall, you must use a Web server with the TDS-tunnelling servlet to support transmission of database request responses over the Internet.

• Install jConnect on the Web server host.

• Requires a Web server that supports the javax.servlet interfaces.

Using the Cascade Gateway

---

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: davidw@cascade.org.uk; 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.

Note	The Cascade gateway does not support encryption, and therefore is not suitable for Internet applications that connect to a back-end server through a firewall.

Usage Requirements

• If you did not install jConnect in the default installation directory, you must edit www.dos (DOS) or www.template (UNIX) and change all default installation directory references to point to the literal path where you installed jConnect.

• The Cascade gateway and your Web server must run on the same host machine. This way, applets connect to the same host as the Web server, but to the port controlled by the Cascade gateway. The gateway routes the request to the appropriate database. To see how this is accomplished, review the code in Isql.java and gateway.html in the sample (jConnect 4.1) or sample2 (jConnect 5.0) subdirectory of the jConnect installation directory. Search for "proxy."

If your database server runs on the same host as your Web server, you do not need the Cascade gateway. Installing the Cascade Gateway

---

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

1. At a DOS prompt, change to the jConnect installation directory.

Your JDBC_HOME environment variable should be set to this directory.

1. Start the Cascade gateway by entering:

httpd

If the command executes successfully, you see output from httpd.bat, ending with:

HTTPDServer www.dos
UNIXChange to the directory where you installed jConnect (the JDBC_HOME directory). Type the following command:
sh httpd.sh &
Troubleshooting

• If you do not see a message after you enter the httpd command, the server is not running. Retry the command in verbose mode.

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.

• If you receive this error message:

HTTPServer: IOException: getRequest() Address already in use

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.

You can:

• Stop the process that is currently running on the specified port. After verifying that the process has terminated, try starting the gateway;

or

• Change the port number in the www.dos or www.template file, then modify the gateway.html file, located in the sample (jConnect 4.1) or sample2 (jConnect 5.0) subdirectory of JDBC_HOME, by changing the proxy parameter to "localhost:new_port."

If your host is not "localhost" (that is, your Cascade HTTP server and browser are on different hosts), make sure that the proxy parameter uses the remote host name rather than "localhost."

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.

Note	The Validate program uses "localhost:8000" to test your gateway.

From the DOS prompt for Windows NT or Windows 95, or at a UNIX prompt, change to the JDBC_HOME directory.For jConnect 4.1, type
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.

Note

If you use Netscape on the same machine where you have installed jConnect, make sure that your browser does not have access to your CLASSPATH environment variable. See "Restrictions on Setting CLASSPATH When You Use Netscape" in Chapter 3 of the Sybase jConnect for JDBC Installation Guide and Release Bulletin.

1. Open your Web browser.

1. Enter the URL that matches your setup. For example, if your browser and the Cascade gateway are running on the same host, enter:

http://localhost:8000/index.html

If the browser and the Cascade gateway are running on different hosts, enter:

http://host:port/index.html

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:

1. Click "Run Sample JDBC Applets."

This takes you to the jConnect Sample Programs page.

1. Move down the Sample Programs page to find the table under "Executable Samples."

1. Locate "Isql.java" in the table and click on "Run" at the end of the row.

The sample Isql.java applet prompts for a simple query on a sample database and displays the results. The applet displays a default Adaptive Server host name, port number, user name (guest), password (sybase), database, and query. Using the default values, the applet connects to the Sybase demonstration database. It returns results after you click Go. TroubleshootingUnder UNIX, if the applet does not appear as expected, you can modify the applet screen dimensions:

1. Use a text editor to edit the following:

For jConnect 4.1

$JDBC_HOME/sample/gateway.html

For jConnect 5.0

$JDBC_HOME/sample2/gateway.html

1. Change the height parameter in line 7 to 650. You can experiment with different height settings.

1. Reload the Web page on your browser.

Defining a Connection to the Cascade Gateway

---

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:port

where 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 Java^TM 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:

Query	POST/tds?ServerHost=dbserver&ServerPort=1234&Operation=more HTTP/1.0
Header	Content-Length: 605
Content (TDS)	Login request

Gateway to client. Header contains session ID assigned by the TDS servlet:

Query	200 SUCCESS HTTP/1.0
Header	Content-Length: 210 TDS-Session: TDS00245817298274292
Content (TDS)	Login acknowledgment EED

Client to gateway. Headers for all subsequent requests contain the session ID:

Query	POST/tds?TDS-Session=TDS00245817298274292&Operation=more HTTP/1.0
Header	Content-Length: 32
Content (TDS)	Query "SELECT * from authors"

Gateway to client. Headers for all subsequent responses contain the session ID:

Query	200 SUCCESS HTTP/1.0
Header	Content-Length: 2048 TDS-Session: TDS00245817298274292
Content (TDS)	Row format and some rows from query response

TDS-tunnelling Servlet System Requirements

---

To use the jConnect servlet for TDS-tunneled HTTP, you need:

• A Web server that supports javax.servlet interfaces. To install the server, follow the instructions that are provided with it.

• A Web browser that supports JDK 1.1, such as Netscape 4.0, Internet Explorer 4.0, or HotJava.

Installing the Servlet

---

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:

• SkipDoneProc [true|false] - Sybase databases often return row count information as intermediate processing steps are performed during the execution of a query. Usually client applications ignore this data. By setting SkipDoneProc to "true," the servlet will remove this extra information from responses "on the fly," which reduces network usage and processing requirements on the client. This is particularly useful when using HTTPS/SSL because the unwanted data does not get encrypted/decrypted before it is ignored.

• TdsResponseSize - Set the maximum TDS packet size for the tunneled HTTPS. A larger TdsResponseSize is more efficient if you have only a few users with a large volume of data. Use a smaller TdsResponseSize if you have many users making smaller transactions.

• TdsSessionIdleTimeout - Define the amount of time (in milliseconds) that the server connection can remain idle before the connection is automatically closed. The default TdsSessionIdleTimeout is 600,000 (10 minutes).

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.

• Debug - Turn on debugging. See "Debugging with jConnect".

Enter the servlet arguments in a comma-delimited string. For example:
TdsResponseSize=[size],TdsSessionIdleTimeout=[timeout],Debug=true
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:
http://host:port/TDS-servlet-path
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:
http://host:port/TDS-servlet-path?Operation=list
For example, if your server is MYSERVER and the TDS servlet path is /tds, you would enter:
http://myserver:8080/tds?Operation=list
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:

1. Hard code parameter values in TDSTunnelServlet.java.

1. Create .class files from the class declarations in TDSTunnelServlet.java.

This should result in the following files:

• TDSTunnelServet.class

• TdsSession.class

• TdsSessionManager.class

1. Create a directory for the .class files under your Netscape Enterprise Server 3.5.1 (NSE_3.5.1) installation directory, as follows:

mkdir NSE_3.5.1_install_dir/plugins/java/servlets/gateway

1. Copy the .class files derived from TDSTunnelServlet.java to the directory you just created.

1. Copy the classes under $JDBC_HOME/classes/com/sybase to NSE_3.5.1_install_dir/docs/com/sybase.

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.

1. Set the proxy URL to the TDS-tunnelling servlet.

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/
gateway_name.TDSTunnel_Servlet_name">