Java ICA Client - Citrix MetaFrame XP

The ICA Java client is the second most popular client platform (second to the Win32 clients).

The ICA Java client is the second most popular client platform (second to the Win32 clients). The ICA Java client will run on any operating system that has a Java Virtual Machine (JVM) installed. There are dozens of different client platforms that can run a JVM, including Win32, UNIX, Macintosh, OS/2, and BeOS. Many people choose to use the Java client because it supports features that might not be supported by the platform's native ICA client, such as Program Neighborhood. Also, if you have a diverse range of client devices, using the ICA Java client means that you only need to support one client platform instead of many.

Advantages of the Java ICA Client

  • Can be used on many different client operating systems.
  • Can be embedded directly into web pages.
  • Supports many advanced client features, such as Program Neighborhood.

Disadvantages of the Java ICA Client

  • Only supports TCP/IP sessions.
  • Requires that a Java Virtual Machine be configured.
  • The security context in which Java applications run sometimes prevents the ICA Java client from behaving properly.

Technical Overview

The Java client comes packaged in a single installation file, setup.class. You can install the ICA client from this file onto web servers to allow users to run ICA sessions directly through web pages. You can also install this file onto each client device, so that the Java ICA client is installed locally, allowing users to access MetaFrame XP servers without having to go to a web page.

The ICA Java client is fully JDK 1.1 compliant. It will run in any environment that is also JDK 1.1 compliant.

Differences between ICA Java Client Modes

The ICA Java client has two modes of operation, depending on how it is installed and used. The same setup.class file is used to install the ICA client for both modes. The two modes are:

  • Applet mode.
  • Application mode.

Applet Mode

In applet mode, the ICA Java client is installed on your web server. Users launch ICA sessions and the ICA client by clicking on hyperlinks in web pages. All ICA client configuration is accomplished through parameters embedded in the web page that are passed to the ICA client when it's launched.

In applet mode, the ICA Java client never gets installed to the users' client devices and users do not have to have a JVM loaded locally. The ICA Java client is executed inside users' web browsers, and the ICA session appears inside their web browsers. When they close their browser, the ICA session is disconnected.

Advantages of Applet Mode

  • You can control what features are used.
  • Easy for users to use.
  • Nothing is installed locally on the client devices for the users to break.

Disadvantages of Applet Mode

  • ICA sessions run in the browser window.
  • The Java runtime files must be downloaded every time a session is launched.

Application Mode

In application mode, the ICA Java client is installed directly on the user's client device. This means that the client device must have a JVM installed locally as well. Once the ICA client is installed, however, users can launch ICA sessions from their local device anytime they want. They do not have to go through a web browser and their ICA session Windows are not embedded into a browser.

Advantages of Application Mode

  • Users can specify parameters when sessions are launched.
  • User settings can be saved in .INI files, just like the 32-bit Windows clients.
  • ICA sessions run in their own Window.

Disadvantages of Application Mode

  • You do not have tight control over what options the users choose.
  • You need to figure out how to deploy the Java client software to all of your users.

ICA Java Client Installation

The installation procedure for the ICA Java client is basically the same for both applet mode and application mode. The only difference is that with applet mode, the ICA Java client is installed onto your web servers, and with application mode, it is installed onto your client devices. To install the ICA Java client, follow these simple steps:

  1. Install a Java Virtual Machine. The ICA Java client requires a JVM that supports JDK 1.1, or JDK 1.3 or newer. For some reason, Citrix does not recommend that you use JDK 1.2, so you need to use 1.1, or 1.3 or newer. A JVM from any vendor can be used. Most people use the JVM that is built into older versions of Windows (jview), or they use the free JVM directly from Sun. Some newer versions of Windows do not have a JVM (due to a little legal problem with Sun) which means that you'll have to download one. If you go to Sun's website (, the JVM download will be listed as a JRE, which stands for Java Runtime Environment. Once you download and install the JRE, you won't notice much difference to your operating system, except that you'll have a directory with some new Java executables.
  2. After you install your JVM, install the ICA Java client. This is done by running the downloaded setup.class file within the JVM environment. (A "class" file is a Java executable file.) The exact command that you use will vary, depending on the JVM you have chosen. With Microsoft's JVM, the command would be jview setup.class. If you have decided to use Sun's JVM, the command would be jre setup.class. On both platforms, you might also need to use the "cp" command line switch to specify the "classpath," which is the path to the setup.class file. Once you use the JVM to run the setup.class file, a GUI setup utility will be launched that graphically steps you through all of the ICA Java client setup options.
  3. Once the ICA Java client is installed, you need to configure it so that it can be used. If you installed the client on your web servers, you configure the client by building a web page that launches the client with certain options. Users launch ICA sessions by accessing the URL to your web page.
  4. If you installed the client directly onto your users' client devices, they can immediately access the Java client to launch ICA sessions. However, because the Java client's command-line environment is complex, you'll need to create batch files that contain the options and parameters your users need to access their ICA sessions. By default, two batch files are created for you, one called jicasession.bat that launches a command-line interface allowing you to specify ICA parameters, and a second batch file called pnsession.bat that launches the Java version of Program Neighborhood. These batch files are covered in detail later in this chapter.
  5. As part of the ICA Java client installation procedure, a file called uninstall.class is created in the client directory. This file can be used to remove the ICA Java client from a computer.

ICA Java Client Files

When you install the ICA Java client, the installation directory will contain dozens of files. In addition to the batch files mentioned previously and some readme text files, most of the remaining files are either JAR or CAB files. A "JAR" file is an archive containing multiple files, just like a CAB file, except that JAR files are used with non-Microsoft platforms.

When you look at the files, you will notice that there are many groups of three files with very similar names. One has a "J" in the name, another has an "M," and the third has an "N." These are just three different types of archives for three different platforms. The "M" files are for use with Internet Explorer on Microsoft platforms, the "N" types are for Netscape browsers, and the "J" types are pure Java archives for use with other browsers or non-Windows environments.

For example, the security Java components are in a file called "cryptoj." If you look in the installation directory on your client device, you will see three files with the "cryptoj" name: cryptojJ.jar,, and cryptojN.jar. The contents of all three J, M, and N type files with the same name are identical, although the "M" type files tend to be about 25% smaller in size. In this case, the contents include Java executable files (class files), properties files, and GIF images for dialog boxes and menus. Also, all of these archives are "signed," which means that a digital signature has been applied by Citrix. This signature allows client devices to open the archives because they trust the creator.

In addition to the J, M, and N type archives, there are three different levels of the ICA client. Each level is a different size and represents different trade-offs. The more functionality an archive provides, the larger the file size and the longer the download time. When bandwidth is crucial, you can choose to use smaller archives that are faster to download but that do not support as many features. Let's look at the three different levels of the Java archives:

  • Full (~800k). This contains all of the Java ICA client functionality.
  • Lite (~400k). This includes most of the functionality. It is similar to the full package, except that it does not include Program Neighborhood, client drive mapping, or SpeedScreen latency reduction components.
  • Core (~360k). The core package contains only the core ICA client functionality with no options. However, you can combine this with individual options for an a la carte customized package.

If you actually look in the ICA Java client installation directory, you will see thirteen different sets of archives, each with three files, the J, M, and N types. Each of these archives contains files that perform a different function. Figure 10.8 describes each archive's role.

Java Archive: Description

  • JICAEng: Complete "full" archive.
  • JICA: Complete "lite" archive.
  • JICA-core: Complete "core" archive.

The following "a la carte" components can be added to the above archives.

  • JICA-audio: Client audio mapping.
  • JICA-cdm: Client device mapping.
  • JICA-clipboard: Client clipboard mapping.
  • JICA-comm: Client COM device mapping.
  • JICA-pn: Program Neighborhood.
  • JICA-printer: Client printing component.
  • JICA-zlc: Zero Latency Windows component.

The following three components are optional, and are NOT included in any of the main archives, including the "full" archive.

  • cryptoj: Encryption component. This is required for SecureICA or SSL.
  • JICA-sica: SecureICA encryption component.
  • ssl: SSL encryption component.

Figure 10.8: The thirteen Java archives

Launching ICA Sessions with the Java Client

When you launch the ICA Java client, it doesn't do anything unless it receives parameters that contain information for the launch. For example, one of the many possible parameters is called "address." When you launch the ICA Java client, you can pass a value for this "address" parameter to the ICA client, which contains the address of the MetaFrame XP server that you want to connect to.

In this section, we'll name some of the most popular parameters. Then, we'll see how these parameters are incorporated into a web page to launch the ICA Java client in applet mode. After that, we'll look at how these parameters can be used with ICA Java clients installed on user workstations operating in application mode.

ICA Java Client Launch Parameters

There are dozens of parameters that you can use when you launch the ICA Java client. We will take a look at the ones that you will most frequently use in the real world. For a complete list of parameters that are available, refer to the ICA Java Client Administrator's Guide, available on the Citrix ICA client download website.

The most popular parameters are as follows:

  • Address. This is the address of the MetaFrame XP server that you will connect to. It can be an IP address, a NetBIOS name, or a DNS name. It can also be the name of a published application.
  • BrowserProtocol. This specifies the protocol that will be used to locate the MetaFrame XP server. Valid values are "UDP" or "HTTPonTCP." The UDP protocol requires that a MetaFrame XP server is listening for ICA browser traffic and that UDP 1604 be open from the ICA client to the server. In the MetaFrame XP world, HTTPonTCP should be used.
  • HTTPBrowserAddress. This is the address of a MetaFrame XP server used when TCP/IP+HTTP or SSL+HTTPS browsing is used. This parameter is only needed when you are connecting to a published application. If you do not specify a parameter for this value, the ICA client will try to connect to the hostname called "ica." If you want to specify more than one address, you can add a number after HTTPBrowserAddress. This number can range from 2 to 15. For example, the second address would be specified as HTTPBrowserAddress2. These 15 addresses are logically broken into three groups of five (primary, first backup, and second backup). These groups of servers behave as outlined in the "Business Recovery" section of this chapter.
  • Username. This allows you to specify the username that will be used to launch the ICA session.
  • Domain. This allows you to specify the domain that will be used to launch the ICA session.
  • Password. This allows you to specify the password that will be used to launch the ICA session. This password will be sent in an unencrypted format and anyone will be able to view this password. If you need to automatically connect users to ICA sessions with a secure password, you will have to use an ICA file or specify an .INI file that contains an encrypted password.
  • InitialProgram. This is the executable of the initial program that will be launched if you are connecting to a MetaFrame XP server. If you are connecting to a published application, then this value needs to be set to the name of the published application, preceded by a pound sign (#).
  • WorkDirectory. This is the working directory for the executable specified in the InitialProgram section. If you are connecting to a published application, this value is ignored.
  • ICAPortNumber. This is the TCP port number that the ICA client will use to connect to the MetaFrame XP server. If no value is specified, then the default port 1494 will be used.
  • UseAlternateAddress. If this is enabled (value set to "1") then the ICA client will request the alternate (external) address from the MetaFrame XP server. Details of alternate address use and configuration are covered in Chapter 15.
  • SSLEnable. When this is enabled (value set to "on") the ICA client will use SSL to encrypt the ICA data stream. This requires that the "crypto" and "ssl" Java archives are loaded, and that the MetaFrame XP server is running Feature Release 1 or newer. See Chapter 15 for details about using SSL.
  • EndSessionTimeout. This specifies the disconnect time in seconds. After no activity, the session will be disconnected. The default value is 300 seconds.
  • Cabinets. This allows you to specify additional Java cabinets. For example, if you decide to use SecureICA encryption, you would use this parameter to add the "cryptoj" and "JICA-sica" Java cabinets to the client execution.
  • IcaFile. This parameter allows you to specify an ICA file that is used to establish the connection to your application. This is specified in the form of a URL.
  • Param. The "param" parameter allows you to pass command-line parameters to the application as it is launched. This often includes options such as a file to open, in the form of p:\personal\report.doc.

In addition to these parameters that have been created specifically for use with the Java ICA client, you can create custom parameters based on the values of any standard appsrv.ini, module.ini, or wfclient.ini configuration files. This allows you to pass any possible parameter to the Java ICA client. To pass parameters based on the standard INI files, you need to create parameter names in the following format: file.section.line. Let's take a look at the three parts of this parameter format.

  • File. This first part of the custom parameter specifies the type of .INI file that usually contains the setting that you are specifying in the parameter. For the appsrv.ini file, set this section to "user," for the module.ini file, set this section to "system," and for the wfclient.ini, set this section to "global."
  • Section. This second part of the parameter specifies the section of the .INI file that you are referencing. The .INI file sections are always enclosed in brackets, for example, [wfclient] is a section of the appsrv.ini file.
  • Line. The last third of the parameter represents the line item that you want to specify in the parameter. For example, "DesiredColor" is one of the many lines in the [wfclient] section of the appsrv.ini file.

For example, the [wfclient] section of the appsrv.ini file has a line called "DisableCtrlAltDel." You can set this value to "on" to prevent users from being able to send CTRL+ALT+DEL to the server. By default, this line does not have a preconfigured parameter that you can pass to the Java ICA client. However, because this line is part of the three main .INI configuration files, you can build a custom parameter to pass to the Java ICA client. In this case, the custom parameter would be called user.wfclient.DisableCtrlAtlDel, and you could set its value to "on."

You don't actually need an appsrv.ini file on your client device or webserver to build custom parameters from one. In fact, specifying the parameters when the Java ICA client is launched gives you the ability to configure any option that you would have otherwise needed an .INI file for.

Creating a Web Page to Launch the Java Client

If you decide to use the ICA Java client in applet mode, you will need to create a web page that contains the information needed to launch it. Figure 10.9 shows at a very basic web page that could meet your needs.


<applet code=com.citrix.JICA.class
width=640 height=480>
<param name=address value=Word>
<param name=BrowserProtocol value=HTTPonTCP>
<param name=HTTPBrowserAddress>
<param name=HTTPBrowserAddress2>
<param name=InitialProgram value=#Word>
<param name=EndSessionTimeout value=1800>
<param name=user.wfclient.DisableCtrlAltDel value=On>

Figure 10.9: A very basic web page for launching the ICA Java client

Let's take a look at how all of this works. As you can see, this is standard HTML. There are only two tags that we need to focus on, the "applet" tag that launches the Java applet and the "param" tags that pass parameters to the Java applet.

The <applet> Tag

The applet tag allows you to imbed a chunk of Java code directly into a web page. In this case, that chunk of Java code is the ICA Java client. The applet tag begins with <applet> and ends with </applet>. The applet tag has several attributes that are included in the initial <applet> tag:

  • Code. This is the name of the class file (Java executable) that starts and runs the applet. On most web servers this name is case sensitive. Figure 10.9 shows this as com.citrix.JICA.class. This will launch the ICA client. Alternately, if you want to launch Program Neighborhood, you can specify
  • Codebase. This is the path to the directory on the web server for the class file specified in the "code" attribute. The codebase attribute does not name the actual class file, just the path to it. This is usually a URL, and it must be in the same directory or a child directory of the web page.
  • Archive. This is the name of the Java archive file that contains the Java executables (class files), including the one specified in the "code" attribute. Notice that in the example web page in Figure 10.9, the "M" version of the archive is specified, meaning that this web page is intended for Internet Explorer users on Microsoft platforms. If visitors to this page will be using Netscape, then you would want the archive attribute to specify the Netscape version of the archive (archive=JICA-coreN.jar). This is where you specify the full, lite, or core archives. If you decide to specify in the code attribute, be sure that you specify the full client in this archive attribute.
  • Width and Height. This is pretty self-explanatory. Remember that this is the size of the applet window inside the web browser. If you make this value too large, then your users will have scroll bars.

The <param> Tag

The "param" tag allows you to specify the parameters and values that are passed to the ICA client. Any of the parameters listed in the previous section are valid. Each parameter consists of a "name" and "value" pair. The name indicates which parameter is being specified, and the value indicates the value that will be passed for that parameter. As you can see, each <param> tag can only hold one parameter name/value pair, but there is no limit to the total number of parameter tags that you can have.

In the example in Figure 10.9, the web page is configured to connect to a published application called "Word." Two server names are listed, one as the primary and one as the secondary. When a user establishes a session, the primary server is contacted (via the Citrix XML service). That server will communicate with the zone data collector to send the address of the least busy MetaFrame XP server to the user. See Chapter 4 for more on how load balancing works.

Notice that the "param" item is a separate tag, meaning that it contains its own "<" and ">" wrapper. The param tag is a subtag of the applet tag, and it is located between the opening <applet> and closing </applet> tags.

Creating Web Pages in the Real World

If you decide to use the ICA Java client in applet mode, and you are not planning on using NFuse, then you will probably have to do some fancy programming. The reason for this is that one unique web page will have to be created for each different option that you would like to use.

For example, if you have users that use both Netscape and Internet Explorer, you would need to create two different web pages, one that specified the "N" version of the Java archive (archive=JICAEngN.jar), and one that specified the "M" version of the Java archive (

Additionally, if you wanted different options, multiple web pages would need to be created, one for each set of options; for example, a page that launched sessions at 640x480 resolution with a width=640 height=480 attribute, and a page that launched sessions at 800x600 resolution with a width=800 height=600 attribute.

Obviously, this would get very complicated very quickly. An easy way around it is to use server side scripting, such as ASP pages with VB Script. For example, you could create a simple web page that detects the client browser platform, and then inserts the appropriate Java archive, so that Netscape users got the "N" archive, and IE users got the "M" archive.

If you are unfamiliar with server side web scripting, a high-level introduction is provided in the next chapter as NFuse is discussed. Additionally, a fantastic online resource for ASP scripting, help, and sample code is located at

Launching the Java Client in Application Mode

If you install the ICA Java client locally onto a client device, you can use the ICA client in "application" mode, which means that the ICA Java client is installed locally on your client device as an application.

Usually, when the ICA Java client is installed locally on a client device, the "full" Java archive is used because you don't need to worry about download times.

After you install the ICA Java client, two launch files are created. The exact names of these files vary depending on the platform, but they are something like "jicasession.bat" and "pnsession.bat."

Jicasession.bat is used to launch ICA sessions, and pnsession.bat is used to launch the Java version of Program Neighborhood. In actuality, these files are simple batch files that call the JRE and load certain classes. Let's look at a sample jicasession.bat:

"C:\Program Files\JavaSoft\JRE\1.1\bin\jre.exe" -cp "c:
\icajava\.;c:\icajava\JICAEngJ.jar;c:\icajava\cryptojJ. jar;c:
\icajava\sslJ.jar" com.citrix.JICA -CDMPromptAlways:false %1 %2 %3
 %4 %5 %6 %7 %8 %9

This sample jicasession.bat is from a Sun JVM environment, installed onto a 32-bit Windows client device. In your environment, the exact executables and path locations might be different, which is why these launch files are not generated until after the Java ICA client is installed.

All of the code in the launch file is actually one single command line. All it does is to launch the JRE (jre.exe in this case), give the location of all the class files (the JARs after the "cp" switch), and specify the Java command to be run (com.citrix.JICA).

The pnsession.bat file is used to launch the Java Program Neighborhood. It is identical to the jicasession.bat file, except that the pnsession.bat file calls the PN class file instead of the ICA client class file. This is done by replacing the com.citrix.JICA section seen in the jicasession.bat file with

Both of the launching files accept parameters as command line options. You can specify these options by adding -parameter:value to the command line after the batch file. You can add multiple parameters. For example, to launch a Java ICA client connection to a MetaFrame XP server called "server1" with a disconnect timeout of 1800 seconds, use the following command:

jicasession.bat -address:server1 -EndSessionTimeout: 1800
It's the "%" values at the end of these command lines in these batch files that allow you to pass the command line parameters to the ICA client. Unfortunately, due to Windows limitations, you will only be able to pass 9 parameters. Any more will not be picked up. Of course you can get around this by modifying the batch files and adding the parameters there, right after the word "false" and before the "%1."

Graphical Command Line

Occasionally, there may be situations in which you want to provide an opportunity for users to manually specify additional parameters. To do this, you can run the jicasession launch script with no parameters, or add the -guicmdline parameter to the list. This will cause a small graphical box to appear that will allow users to manually type in as many parameters as they want, using the familiar -parameter:value syntax. When the user has added all the parameters they need, they can click the "run" button. This graphical command line is especially helpful for troubleshooting purposes and for use with client platforms that do not have command line interfaces (such as Macintosh 9.x and OSX).

Using Existing INI Configuration Files

One advantage that you have when using the ICA Java client in application mode that you do not have when you use it in applet mode is that with application mode you can configure it to use appsrv.ini, module.ini, and wfclient.ini files.

This is very convenient if you have other, non-Java ICA clients that are already configured properly and using these .INI files. This way, instead of having to manually build cumbersome command line launching scripts, you can just point your local Java client to the existing .INI files.

You can specify these .INI files for the ICA Java client just like any other parameter for the Java client running in application mode, as a -parmeter:value command line option.

Parameter: Description

  • Iniappsrv: Specifies the name and location of the appsrv.ini file.
  • Inimodule: Specifies the name and location of the module.ini file.
  • Iniwfclient: Specifies the name and location of the wfclient.ini file.
  • IniDir: Specifies the directory that contains any INI files not explicitly defined as parameters.

Figure 10.10: INI configuration file parameters for use with the Java client

Let's look at how these .INI parameters are used. Consider this command:

pnsession -iniappsrv:c:\somedirectory\appsrv.ini -inimodule:c:
This command will specify appsrv.ini and module.ini files to be used with the Java Program Neighborhood. A Program Neighborhood launched like this will contain all of the connections and information specified in these files.

Additionally, since an appsrv.ini can contain many connections, you can launch a single connection from an appsrv.ini file that contains many connections. Remember from the 32-bit Windows section of this chapter that a single appsrv.ini file can contain multiple connections, each headed with a [connectionname] section. To specify a single connection from an existing appsrv.ini file, add the connection name before the file, like this:

jicasession yourconnection -iniappsrv: c\somedirectory\appsrv.ini
Remember that the only parameter that you must specify is the "address" parameter. However, that address doesn't have to be specified as a command-line option. As in the previous example, the address can be part of an appsrv.ini file, or part of an ICA file that is itself passed as a parameter, such as jicasession -IcaFile:c:\somedirectory\yourapp.ica.

As you can see, there are several different ways to specify many of the options and parameters that the ICA Java client will use. Let's summarize these options and how they relate to each other in terms of precedence:

  1. Any parameter explicitly specified on the command line takes precedence over conflicting parameters set anywhere else. This includes all parameters specified in the -parameter:value format, or the file.section.line:value format.
  2. Next, the options in an ICA file explicitly specified on the command line are applied. These options take precedence over anything below, and includes ICA files specified in the -IcaFile:c:\directory \yourapp.ica format.
  3. Once all of the command line options have been parsed, the Java client looks to see if any .INI files have been explicitly specified on the command line. If they are, the client uses them. This includes files specified in the -iniwfclient:c:\directory\wfclient.ini format.
  4. If the Java client still cannot find one or more of the three .INI configuration files, it will look to the IniDir parameter of the command line. If the IniDir parameter is specified (in the -IniDir:c:\inifilelocation\ format), the client will search the specified directory for the needed .INI files.
  5. If the Java client still cannot find one or more of the three .INI configuration files, it will look for an "\ini" directory off of the current working directory. It will look there for the missing .INI files.
  6. If the Java client still cannot find one or more of the three .INI configuration files, it will give up and use the server defaults.

Saving User Settings

One of the nice things about using the ICA Java client in application mode is that it allows you to store user settings in the three .INI files (appsrv.ini, module.ini, and wfclient.ini), just like the regular 32-bit Windows ICA clients.

The exact location where these files will be stored depends on your platform and the parameters that were passed to the Java ICA client when it was launched. Basically, the .INI files will be updated and stored in the location from which they were pulled when the client was launched. The only exception is if the Java client does not have write-access to that directory. In this case, the Java client will attempt to store the modified .INI files in a \Citrix\ directory in the location specified by the "user.home" JVM environment variable. Depending on your JVM vendor and platform, this user.home path sometimes maps to a logical home drive. Other times, it maps to the system root or the location where the JRE is located.

In the real world, if you want to save user settings to .INI files, you should manually copy the .INI files to the user's home drive. Then, specify that path when the Java ICA client is launched. Since your users have write-access to their home drives, they will be able to save whatever settings they need.


Dig Deeper on Citrix virtual desktops