Chapter 6 Web Server Gateways

Using the TDS-tunnelling servlet

To use the TDS-tunnelling servlet, you need a Web server that supports the javax.servlet interfaces, such as Sun Microsystems, Inc.'s Java 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; it shows a connection to a back-end server named DBSERVER with a port number "1234."

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.x) or gateway2 subdirectory (jConnect 5.x) 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.x) or gateway2 subdirectory (jConnect 5.x) 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. If you set 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 do not 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, 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 sessions

You 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.
2. Create .class files from the class declarations in TDSTunnelServlet.java.
   
   This should result in the following files:
   • TDSTunnelServet.class
   • TdsSession.class
   • TdsSessionManager.class
3. 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
   

4. Copy the .class files derived from TDSTunnelServlet.java to the directory you just created.
5. 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.
6. 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"> 
   

Copyright © 2001 Sybase, Inc. All rights reserved.