Proxy Support

IBM® Toolbox for Java™ includes proxy support for some classes. Proxy support is the processing that IBM Toolbox for Java needs to carry out a task on a Java virtual machine (JVM) when the application is on a different JVM.

The proxy classes reside in jt400Proxy.jar, which ships with the rest of the IBM Toolbox for Java. The proxy classes, like the other classes in the IBM Toolbox for Java, comprise a set of platform independent Java classes that can run on any computer with a Java virtual machine. The proxy classes dispatch all method calls to a server application, or proxy server. The full IBM Toolbox for Java classes are on the proxy server. When a client uses a proxy class, the request is transferred to the proxy server which creates and administers the real IBM Toolbox for Java objects.

Figure 1 shows how the standard and proxy client connect to the server. The proxy server can be the IBM i server that contains the data.

Figure 1: How a standard client and a proxy client connect to a server

Standard and proxy connections

An application that uses proxy support performs more slowly than if it uses standard IBM Toolbox for Java classes due to the extra communication needed to support the smaller proxy classes. Applications that make fewer method calls have less performance degradation.

Before proxy support, the classes containing the public interface, all the classes needed to process a request, and the application itself ran on the same JVM. When using proxy support, the public interface must be with the application, but classes for processing requests can run on a different JVM. Proxy support does not change the public interface. The same program can run with either the proxy version of IBM Toolbox for Java or the standard version.

Using the jt400Proxy.jar file

The goal of the multiple-tier, proxy scenario is to make the public interface JAR file as small as possible, so that downloading it from an applet takes less time. When you use the proxy classes, you don't need to install the entire IBM Toolbox for Java on the client. Instead, use AS400JarMaker on the jt400Proxy.jar file to include only the required components, which makes the JAR file as small as possible.

Figure 2 compares the size of the proxy JAR files with the standard JAR files:

Figure 2: Size comparison of proxy JAR files and standard JAR files

Size comparison of proxy JAR files and standard JAR files

An additional benefit is that proxy support requires you to have fewer ports open through a firewall. With standard IBM Toolbox for Java, you must have multiple ports open. This is because each IBM Toolbox for Java service uses a different port to communicate with the server. For example, Command call uses a different port than JDBC, which uses a different port than print, and so on. You must allow each of these ports through the firewall. However, when using proxy support, all the data flows through the same port.

Standard proxy and HTTP tunneling

Two options are available for running via a proxy: standard proxy and HTTP tunneling:

Standard proxy is where the proxy client and proxy server communicate by using a socket over a port. The default port is 3470. Change the default port by using the setPort() method on the ProxyServer class, or by using the -port option when starting the proxy server. For example:
```
     java com.ibm.as400.access.ProxyServer -port 1234
```
HTTP tunneling is where the proxy client and proxy server communicate by way of the HTTP server. The IBM Toolbox for Java provides a servlet that handles the proxy request. The proxy client calls the servlet by way of the HTTP server. The advantage of tunneling is that you are not required to open an additional port through the firewalls, because communication is by way of the HTTP port. The disadvantage of tunneling is that it is slower than standard proxy.

IBM Toolbox for Java uses the proxy server name to determine if standard proxy or tunneling proxy is being used:

For standard proxy, just use the server name. For example:
```
     com.ibm.as400.access.AS400.proxyServer=myServer
```
For tunneling, use a URL to force the proxy client to use tunneling. For example:
```
     com.ibm.as400.access.AS400.proxyServer=http://myServer
```

When running standard proxy, a socket connection exists between the client and server. If that connection fails, the server cleans up resources associated with that client.

When using HTTP tunneling, using the HTTP protocol makes proxy connectionless. That is, a new connection is made for each data flow. Because the protocol is connectionless, the server does not know if the client application is no longer active. Consequently, the server does not know when to clean up resources. The tunneling server solves this problem by using a thread to clean up resources at a predetermined interval (which is based on a timeout value).

At the end of the predetermined interval, the thread runs and cleans up resources that have not been used lately. Two system properties govern the thread:

com.ibm.as400.access.TunnelProxyServer. clientCleanupInterval is how often, in seconds, the cleanup thread runs. The default is every two hours.
com.ibm.as400.access.TunnelProxyServer. clientLifetime is how long, in seconds, a resource can be idle before it is cleaned up. The default is 30 minutes.

Using proxy server

To use the proxy server implementation of the IBM Toolbox for Java classes, complete the following steps:

Run AS400ToolboxJarMaker on jt400Proxy.jar to discard classes that you do not need. This step is optional but recommended.
Deliver jt400Proxy.jar to the client. For Java applets, you may be able to download the JAR file from the HTML server.
Determine what server you will use for the proxy server.
- For Java applications, the proxy server can be any computer.
- For Java applets, the proxy server must be running on the same computer as the HTTP server.
Ensure that you have put jt400.jar in the CLASSPATH on the server.
Start the proxy server or use the proxy servlet:
- For standard proxy, start the proxy server by using the following command:
```
     java com.ibm.as400.access.ProxyServer
```
- For tunneling proxy, configure your HTTP server to use the proxy servlet. The servlet class name is com.ibm.as400.access.TunnelProxyServer and it is contained in jt400.jar.
On the client, set a system property to identify the proxy server. IBM Toolbox for Java uses this system property to determine if standard proxy or tunneling proxy is being used.
- For standard proxy, the property value is the name of the machine that runs the proxy server. For example:
```
     com.ibm.as400.access.AS400.proxyServer=myServer
```
- For tunneling proxy, use a URL to force the proxy client to use tunneling. For example:
```
     com.ibm.as400.access.AS400.proxyServer=http://myServer
```
Run the client program.

When you want to work with both the proxy classes and classes not in jt400Proxy.jar, you can refer to jt400.jar instead of jt400Proxy.jar. jt400Proxy.jar is a subset of the jt400.jar and, therefore, all of the proxy classes are contained in the jt400.jar file.

Examples: Using proxy servers

The following are three specific examples for using a proxy server with the steps listed above.

Classes enabled to work with proxy server

Some IBM Toolbox for Java classes are enabled to work with the proxy server application. These include the following:

Other classes are not supported at this time by jt400Proxy. Also, integrated file system permissions are not functional using only the proxy JAR file. However, you can use the JarMaker class to include these classes from the jt400.jar file.