JDataConnect™ Support

New Features

New Features
System Requirements
Architecture
Technical Features
HTTP Tunneling
HTTP Tunneling
This page explains how firewalls affect JDBC drivers and how JDataConnect allows you to develop applets, servlets and applications without having to worry about the difficult underlying technical issues involved.
JWebServerGateway is included in all JDataConnect editions and operates with the JData2_0, JData1_2 and JDataLite JDBC drivers.
How Firewalls Complicate the Application Environment
A firewall is typically a computer and software that sits between a group of client users and the wider outside Internet or intranet. The firewall is used to protect the internal client network from unauthorized access from outside the firewall. The firewall may also be configured to restrict the types of outside access clients have security to.
Specifically, a firewall will restrict the types of protocols that may travel across the firewall into the internal network. The firewall will also often restrict the ports through which these protocols may pass. Many firewalls will be configured to allow HTTP protocol traffic on port 80 only – this allows users inside the firewall to browse web pages but nothing else. It also blocks outside attempts that access the network inside the firewall.
Network JDBC drivers that cannot traverse firewalls will simply fail any time a user inside a firewall tries to use your applet or application. If your application is web based you must cater for the fact that visitors to your site may be behind a firewall. If your application is intranet based you must cater for the fact that firewalls may exist between the user and the database server.
JDataConnect provides a number of solutions to the firewall challenge. JDataConnect handles firewall access transparently so that developers need not worry about the many difficult technical issues regarding firewall access.
Supported Webservers
Your web server must be be one of the following types in order to operate with JWebServerGateway:
  • A web server that can invoke servlets (e.g. Tomcat, Java Web Server)
  • A web server that is ISAPI compliant (e.g. Microsoft Information Server IIS)
Understanding JWebServerGateway
JWebServerGateway is a software gateway that allows the JDataConnect JDBC drivers to operate reliably when client side users reside within a firewall protected network. Developers using JDataConnect do not have to write extra code to traverse firewalls since the JDataConnect JDBC drivers handle all the details automatically.
When a client runs a Java applet or application inside a firewall the JDataConnect JDBC drivers will first attempt a regular direct connection to JDataServer on the remote server. In a firewall protected environment this connection will usually fail because the firewall blocks this type of connection for two reasons:
  • The connection is not an HTTP connection
  • The JDataServer port (default 1150) is not enabled on the firewall
Many firewalls are configured to allow users to access web pages and nothing else. That is, they are configured to allow only HTTP protocol connections on port 80 – the default web server port. So in order for JDBC connections to succeed for users behind a firewall they too must use HTTP protocol and be routed via port 80.
When the JDataConnect drivers fail to connect via a regular direct connection to JDataServer they automatically retry the connection using HTTP protocol via port 80. This connection will be allowed by the firewall since it is the same way users access web pages. When the request arrives at the remote server the ISAPI web server will receive the request since it is operating on port 80. The web server will then send the request onto JWebServerGateway which in turn routes the request to JDataServer. The response is then routed back to the client side drivers via JWebServerGateway and the web server. In effect, the entire transaction looks to the firewall as a regular HTTP request which it allows through without problem.
HTTP tunneling is the technical name for this approach. Note that simpler forms of HTTP tunneling that do not route via the web server port (default is 80) will still fail since the firewall is typically configured to block access on other ports.
JWebServerGateway Configuration
JWebServerGateway has two implementations. You must install the correct implementation depending on your web server setup. Both gateways are included in the JDataConnect distribution. The following table lists the implementations.
Web Server Type
Gateway
Notes
Connection String
Servlet Capable
JWebServerGateway.class
Implemented as a Servlet
gatewayType = 1
ISAPI
JWebServerGateway.dll
Implemented as an ISAPI dll
gatewayType = 0
Connection Architecture Using JWebServerGateway and JDataConnect
Please visit our architecture page for all architectural diagrams.
How to Setup and Administer the Servlet JWebServerGateway
JWebServerGateway must be installed as a servlet in your web server environment. See your specific web server’s documentation to learn about installing servlets.
You can specify the following properties to customize JWebServerGateway. See your specific web server’s documentation to learn about installing servlet properties. Note that properties are case sensitive.
logging=1 causes JWebServerGateway to log trace information to the console and a trace file called JWebServerGateway.txt
jdataserverPort=nnnn causes JWebServerGateway to look for JDataServer on port nnnn. If you not specify this property the gateway will expect JDataServer to be running on the default port (1150).
System administrators may query the running status of remote JWebServerGateway via a web browser. The status gives information such as when the gateway started, how often it was used and the details of any error conditions that occurred. To query the status of JWebServerGateway use the URL:
http://\JWebServerGateway
where RemoteServer is the name or address of the remote server.
How to Setup and Administer the ISAPI JWebServerGateway
Copy JWebServerGateway.dll into the root directory of your web server.
Ensure that whatever directory you install JwebServerGateway.dll into has execute permission, not just read permission. If that directory has only read permission (the default) then the web server will not execute the DLL, but rather offer to download it. Ensure that your web server software is configured to run on port 80 and is up and running.
JWebServerGateway supports the logging options Log Errors, Log Objects and Log File. These options may be enabled using the administrator JDataAdmin. Note that if you change JWebServerGateway logging options you must stop and restart your web server software for the changes to take affect. e.g. for Internet Information Server IIS stop and start the World Wide Web Publishing Service in NT’s service administrator. If a log file is specified in JDataAdmin JWebServerGateway will create the log file in the web server software’s operating directory. e.g. For IIS that would be \WINNT\SYSTEM32.
System administrators may query the running status of remote JWebServerGateway via a web browser. The status gives information such as when the gateway started, how often it was used and the details of any error conditions that occurred. To query the status of JWebServerGateway use the URL:
http://\JWebServerGateway.dll?query
where RemoteServer is the name or address of the remote server.
Testing Applications Using JWebServerGateway
Many programmers develop applications on a local computer and then deploy the final application to a different server. In this case testing for firewall operation may be difficult. The easiest way to test JDataConnect using JWebServerGateway is: :
  • Install JWebServerGateway as previously described.
  • Use JDataAdmin to set the port for JDataServer to something other than the default, for example 2000.
  • Do not specify a port on your JDBC connect string so that the JDataConnect drivers attempt to connect to JDataServer on the default port. When this connection fails the JDataConnect driver will automatically attempt a HTTP connection on port 80 via JWebServerGateway instead. JWebServerGateway will then route your JDBC calls through to JDataServer on port 2000.