What happens on the client

This section describes what happens on the DSJ client, which may be interesting in its own right, and helpful for diagnosing problems.

Startup

The DSJ client is usually started with either:

• The dsjclient.bat batch file (see The dsjclient.bat file ), or
• A shortcut (see Creating shortcuts).

Both of these start the JRE (Java Runtime Environment) in the \Java\Bin directory, and run the class file borland.jax.client.Jax. When this class is executed, it checks to see if a user name (see DSJUsername) has been specified without a password (see DSJPassword). If so, it displays a password dialog box (see Logging in) for the user to type in their password.

It then attempts to make a TCP/IP connection over the specified port (see DSJServerPort) to the specified DSJ server machine (see DSJServer). If the machine is up and running the DSJ server, and the server is accepting connections, a short-term connection is made with the server.

You can specify an application to run (see DSJApplication), either on the command line, or in the dsj.properties file. For a given application, you can optionally designate a specific version to run (see DSJApplicationVersion). If you donÆt designate a specific version, the latest version of the named application is executed. If you donÆt specify an application, you will get a dialog box displaying a list of those applications that are available to you (see Running the DSJ Client). This list is based on the access rights required for each application, which are determined by your authenticated user name, the IP address of the DSJ client machine, or a combination of both.

Once a specific application is chosen, the primary DSJ server you have been talking to transmits a list of all DSJ servers it knows that serve that application, which often includes itself.

Initial handshake

The DSJ client then attempts to contact each server on the list in term, looking for a server that is up and running and actually does provide the desired application. The server list for that particular application, maintained by the DSJ administrator, may be out-of-date, or some of the servers on the list may be down. Also, because the user name and password must be verified a second time by the server being contacted, access may be denied if the user configuration on that server does not match the primary server.

When contacting the server, the client also transmits the version of the JRE that it is running, and the versions of the JREs that the client has available (that is, the ones that are installed on the client machine). Some applications will require a particular JRE; if that JRE version is on neither the client nor the server, the server will refuse the connection request. If the desired version of the JRE is already installed on the client, then the server will tell the client to restart with that version. If the client does not have the desired version, but that version is installed on the server for downloading, the client will download the JRE from the server, and restart using that version of the JRE.

If the client does not find a connection, an error dialog box is displayed and the attempt to run that application is terminated. See Troubleshooting for more information on the specific problem.

If the client finds a server that provides the desired application, the DSJ client transmits its version number to the server. If they donÆt match, the server instructs the client to download the matching version of the client software from the server, and to restart itself with the now-correct version.

When the client is running the right version of the right software under the right JRE, it commences a long-term connection. The server transmits a list of alternate servers to try if the current connection is lost. Any external files that are needed by the application are sent to the client. Then the process of serving the Java class files begins.

Class download

The client can be configured to either download all the classes that are used by the application before starting, or to download the classes as needed (see DSJCache). Once the required classes are received, the application starts.

If the client loses its connection to the server while the application is running, it attempts to contact the alternate servers that are supposed to provide the application. This happens transparently, although the user may experience a minor delay as the client attempts to contact the other servers. If the client fails to complete the handshake with another server, an error occurs.

Caching

During idle time (when the application is sitting there waiting for you to do something), the downloaded classes for the application are written to a cache file in the designated cache directory (see DSJCacheLocation). The next time the application is executed, the class files can be run from the cache, which is much faster than downloading. If the application is updated and you are not requesting a specific version of the application, the cached classes will be discarded in favor of the newer class files from the server.

Each application is cached separately. If two applications use the same class file, you will cache two copies of that class, one in each applicationÆs cache file.

Restarting

Sometimes the client will restart itself. This will happen when:

• You type in your password in the Enter Password dialog box.
• You choose an application from the Available Applications dialog box; the client is restarted with the application you choose.
• A specific JRE is needed to run the chosen application; the client restarts using that JRE and runs the application.
• The client updates itself to match the DSJ server.

This happens automatically and should be transparent to the user.

Termination

After the Java application terminates, the DSJ client terminates. You can also kill the DSJ client by pressing Ctrl+C in the command prompt window, if you started the DSJ client from the command line.