COMPAQ

Release Notes
Compaq Software Development Kit (SDK) v 1.3.1-3
for the Tru64™ UNIX® Operating System
for the Java™ Platform

Contents

Introduction

Thank you for downloading the Compaq Software Development Kit (SDK) v 1.3.1-3 for the Tru64™ UNIX® Operating System for the Java™ Platform (hereafter called the Compaq SDK or, simply, the SDK). These release notes contain installation instructions, new features, known issues, fixed problems, usage documentation, and other information specific to the Tru64 UNIX port of Sun Microsystems' Java 2 SDK, Standard Edition (J2SDK).

The Compaq SDK v 1.3.1-3 kit implements the J2SDK v 1.3.1, and is based on Sun’s J2SDK 1.3.1_03 Solaris Reference Release. It passes all the tests in Sun's Java Compatibility Kit test suite (JCK V1.3a). Use the java -version command to check the version of the SDK that you are using.

This kit can be used to develop and run Java applets and programs on systems installed with Tru64 UNIX V4.0F, V4.0G, or V5.0A and higher. If you need to upgrade your version of Tru64 UNIX, please refer to the Compaq Tru64 UNIX web site for additional information.

This kit contains two virtual machines:

IMPORTANT: Please make sure you understand the Copyright (COPYRIGHT, installed file) and License (LICENSE, installed file) information before using this release.

New Features

The following sections briefly describe the new features Compaq has included in SDK v 1.3.1. Compaq recommends that you read Sun's Java 2 SDK, Standard Edition, version 1.3 Summary of New Features and Enhancements for a thorough description of all new features and enhancements available in the J2SDK v 1.3.

Compaq SDK v 1.3.1-3 New Features

This kit installs Compaq SDK v 1.3.1-3, which contains the following new features.

Reduced Fast VM Memory Requirements

The Fast VM is optimized for large, long-running programs running on server systems. Many users would like to use the Fast VM on their workstations for client-side applications; however, some of these systems do not have the resources to start up the Fast VM with its default configuration. A -client switch has been added to address these needs. For more information, refer to Reducing Fast VM Memory Requirements for Workstations and Client-side Applications.

Compaq SDK v 1.3.1-2 New Features

Compaq SDK v 1.3.1-2 was a maintenance release with no new features.

Compaq SDK v 1.3.1-1 New Features

Compaq Fast Virtual Machine (Fast VM) v 1.3.1 is now the default VM for the SDK

The Compaq Fast Virtual Machine (Fast VM) is the default SDK VM. Because it is installed transparently as a part of the SDK v 1.3.1 kit, you no longer need to download and install the Compaq Fast VM kit separately.

Benefit: The Compaq Fast VM provides optimal runtime performance on Tru64 UNIX systems and offers significant performance advantages over the classic VM.

The classic VM is still provided with the Compaq SDK, via the -classic command line option. For more information on VM options, see Selecting the VM and Compatibility.

Precompiled Standard Class files

This release of the Compaq SDK provides precompiled versions of the rt.jar file that contain highly optimized native code compiled from the standard rt.jar classes. The Fast VM will automatically load the optimized versions of these classes when your application references them, provided you have installed the optional Java enhanced environment subset.

Benefit: This will improve performance of your application, depending on how heavily you rely on these classes. For more information, refer to Additional Compaq Options, specifically, -Xnoprecompiledsys.

Compacting garbage collector

This version of the Fast VM supports an alternative compacting garbage collector, which compacts live data in-place, rather than copying it as the default collector does. This collector is a hybrid mark-sweep/mark-compact collector, which will avoid moving data when it is not necessary.

Benefit: This collection scheme can have better performance characteristics and lower heap size requirements for applications in which the heap contains a high percentage of long-lived data. This collector can also perform minor collections, rather than collecting the entire heap, when the percentage of live data is moderate. It can also perform sweeps, which free space without moving any data at all. Thus, it may also provide performance advantages for certain applications with a moderate amount of long-lived data, but a high rate of short-lived object turnover.

To use the compacting collector, specify the  -Xgc:compacting  option on the command line. The  -Xgc:copying  option causes the Fast VM to use the default "copying" collector.

Plug-in

SDK v 1.3.1 includes the Compaq Plug-in for the Tru64 UNIX Operating System (hereafter called the Compaq Plug-in or, simply, the Plug-in) that enables users to run Java applets and JavaBeans™ components on web pages using the Compaq Run Time Environment (RTE) for the Tru64 UNIX Operating System (hereafter called the Compaq RTE or, simply, the RTE) as an alternative to using the default Virtual Machine for Java 2 that comes with the web browser. Based on the Java Plug-in 1.3.1 provided by Sun Microsystems, the Compaq Plug-in contains similar functionality.  The Open JVM Interface (OJI) Plug-in is now supported. For more information, refer to Using the Compaq Plug-in.

Benefit: The SDK v 1.3.1 kit provides the Plug-in so a separate download is not required.

Fixed Problems

The following sections provide important information about problems that Compaq has fixed in SDK v 1.3.1. Compaq recommends that you also review Sun's Java 2 SDK and Runtime Environment Important Bug Fixes and Changes documentation for information concerning bug fixes that Sun has made for this release.

Problems Fixed in Compaq SDK v 1.3.1-3

This kit installs SDK v 1.3.1-3, based on Sun’s J2SDK 1.3.1_03 Solaris Reference Release.

Problems Fixed in Compaq SDK v 1.3.1-2

This release was based on Sun’s J2SDK 1.3.1_01 Solaris Reference Release.

Problems Fixed in Compaq SDK v 1.3.1-1

This release was based on Sun’s J2SDK 1.3.1_01 Solaris Reference Release.

Compatibility

Compaq SDK v 1.3.1 is compatible with previous versions of the Compaq SDK. Most existing programs will run on the SDK v 1.3.1 platform. However, some important incompatibilities do exist and are thoroughly discussed in Sun's Java 2 Platform Compatibility with Previous Releases document. For specific J2SDK v 1.3.1 incompatibilities refer to the section, Incompatibilities in the Java 2 Platform, Standard Edition, v1.3.

The default VM, the Compaq Fast VM, uses more memory than the classic VM; therefore, in SDK v 1.3.1, you might need to adjust your quotas or heap size. Refer to Memory Usage for more information.

The Compaq Fast VM does not support the Java Platform Debugger Architecture (JPDA). If you try to debug an application with any debugger that uses the JPDA interface such as jdb, you will see a message stating that the Fast VM does not support JPDA and debugging will continue using the classic VM.

Installation

The following sections describe how to install the SDK v 1.3.1-3 kit on your Tru64 UNIX system.

Tru64 UNIX Patches

This kit requires Tru64 UNIX V4.0F, V4.0G, or V5.0A and higher.

Presently, the SDK v 1.3.1 release does not require any operating system patches; however, the need for patches may be discovered after this release becomes available. Therefore, we recommend that you check our patch installation page for Compaq Tru64 UNIX for the latest information.

Installing the Kit

With SDK v 1.1.7B and previous versions, you could install only one SDK version on a system. With later versions, you can install and use multiple versions on one system. In addition, you can change the default system Java environment version, which is the version located in /usr/bin.

When you install the SDK v 1.3.1-3 kit on your system, all files are installed in directories under /usr/opt/java131. In most cases, SDK v 1.3.1 is not installed as the default system Java environment version, and you need to take special actions to use SDK v 1.3.1 after it is installed. See Using Compaq SDK v 1.3.1. If you want to change the default system Java environment version, see Making the Compaq SDK v 1.3.1 the Default System Java environment version.

NOTE

SDK v 1.3.1 is available from our Software Download page and is also bundled with some versions of the Compaq Tru64 UNIX operating system. However, the Java subset names are different. Kits downloaded from our Software Download page begin with the subset name "JAVA." In contrast, Java subsets included with the Tru64 UNIX operating system begin with the name "OSF."

For a description of both Java subsets, see Step 4. For additional information about installing the SDK during the Compaq Tru64 UNIX installation, see the Compaq Tru64 UNIX Installation Guide.

To install, perform the following steps as superuser:

  1. If you want to deinstall prior versions, see Deinstalling Other Versions.
     
     
  2. Download the following binary kit: 
       java131-3.tar
  3. Untar it into a scratch directory, /tmp/java, for example: 
    
   cd /tmp/java 
   tar xf /tmp/java/java131-3.tar

    The scratch directory now contains the kit plus the following files: 

       COPYRIGHT 
   LICENSE 
   release_notes.html
  4. Use the setld command to load from that scratch directory: 
       setld -l /tmp/java

    There are three subsets that you can install:
     

    Compaq recommends installing all three subsets if you intend to use the SDK in a development capacity.

    Compaq Tru64 UNIX Subset Names

    The Software Download page uses the subset names listed in Step 4. However, if SDK v 1.3.1 has been installed as part of the Compaq Tru64 UNIX operating system installation, it will have the following subset names:

    • OSFJAVAnnn - The mandatory subset that provides support for running Java programs and applets.
       
    • OSFJAVADEVnnn - The development environment, which allows you to compile and debug Java code.
       
    • OSFJAVADOCnnn - The documentation subset.

    where nnn refers to the base operating system version number.

    Note that if you are updating to a later version of SDK v 1.3.1, you must first deinstall these subsets. See Deinstalling Other Versions for instructions.

     

  5. Once you have installed the desired subsets, you can delete the scratch directory unless you also download the Optional Enhanced Environment or API reference documentation.

Installing the Optional Enhanced Environment

The Compaq SDK provides precompiled versions of the rt.jar file that contain highly optimized native code compiled from the standard rt.jar classes. The Fast VM will automatically load the optimized versions of these classes when your application references them, provided you have installed the optional Java enhanced environment subset. You can download and install the optional enhanced environment for SDK v 1.3.1 to improve performance of your application. Allow 30 MB of disk space for the installed precompiled rt.jar files. Note: If you elect not to install the enhanced environment, you will not receive the performance benefits of the precompiled files, and the version string will not display the precompiled rt.jar indicator. Before installing the enhanced environment, you must first install the mandatory subset JAVA131, as described in Installing the Kit.

To install, perform the following steps as superuser:

  1. Download the following binary kit:
    2.    javaenh131-3.tar
  2. Untar the kit into a different scratch directory from the one you used above, for example, /tmp/java/enh: 
       cd /tmp/java/enh
   tar xf /tmp/java/enh/javaenh131-3.tar

    The scratch directory now contains the kit plus the following files:

       COPYRIGHT
       LICENSE
       release_notes.html

  3. Use the setld command to load from that scratch directory:

    4.    setld -l /tmp/java/enh

         There is only one subset that you can install:

        JAVAENH131 - The enhanced environment

  4. Once you have installed the desired subsets, you can delete the scratch directory.

Installing the API Reference Documentation

You can also download and install the API reference documentation for SDK v 1.3.1. Allow 105 MB of disk space for the installed API reference files.

To install, perform the following steps as superuser:

  1. Download the following binary kit: 
       javaapidoc131-3.tar
  2. Untar it into a different scratch directory from the one you used for the software kit, for example /tmp/java/api: 
       cd /tmp/java/api
   tar xf /tmp/java/api/javaapidoc131-3.tar
  3. Use the setld command to load from that scratch directory: 
       setld -l  /tmp/java/api

    There is only one subset that you can install:

         JAVAAPIDOC131 - The API documentation

    Browse the documentation using the following location:

       /usr/opt/java131/docs/api/index.html
  4. Once you have installed the desired subsets, you can delete the scratch directory.

Determining Your Installed Version

After you have installed SDK v 1.3.1, the /usr/opt/java131/bin/java -version command should display the following for this kit: 

  % /usr/opt/java131/bin/java -version 
    java version "1.3.1" 
    Java(TM) 2 Runtime Environment, Standard Edition 
    Fast VM (build 1.3.1-3, native threads, mixed mode, precompiled rt.jar, ...)

Deinstalling the Compaq SDK v 1.3.1-3 Kit

If you want to deinstall this kit in the future, perform the following steps as superuser:

  1. Use the setld -i command to determine which SDK v 1.3.1 subsets are installed. For example: 
       setld -i | grep JAVA | grep 131 | grep installed
  2. To delete subsets, enter the setld -d command. For example, 
       setld -d JAVA131 JAVADEV131 JAVADOC131 JAVAAPIDOC131

Deinstalling Other Versions

To deinstall other versions, perform the following steps as superuser:

  1. Use the setld -i command to determine what Java subsets are installed and which you want to delete.
  2. Use the setld -d command to delete the Java subsets.

For example:

   % setld -i | grep JAVA | grep installed 
   JAVA122     installed     Java 1.2.2-12  Environment (General Applications) 
   JAVADEV122  installed     Java 1.2.2-12  Development Environment 
   JAVADOC122  installed     Java 1.2.2-12  Online Documentation 
 
   % setld -d JAVA122 JAVADEV122 JAVADOC122

Making Compaq SDK v 1.3.1 the Default System Java Environment Version

Note: Use caution when changing the default system Java environment to SDK v 1.3.1 for the following reasons:

See Using Compaq SDK v 1.3.1 for more information on using SDK v 1.3.1 when it is not the default system Java environment version.

When you make SDK v 1.3.1 the default system Java environment version, system files such as /usr/bin/java are modified so that SDK v 1.3.1 is used whenever Java commands are entered. If a default system Java environment version is not found during installation, SDK v 1.3.1 is installed as the default system Java environment version. Otherwise, perform the following steps as superuser to make SDK v 1.3.1 the default system Java environment version:

  1. Determine what the default system Java environment version is on your system by using the following command: 
        
   /usr/bin/java -version   # Note: Use /usr/bin/java to insure that the
                            #       default system Java environment version is executed.
  2. Unset the default system Java environment version:
     
  3. Set the default system Java environment version to SDK v 1.3.1:
  1. Verify that SDK v 1.3.1 is now the default version: 
      % /usr/bin/java  -version 
    java version "1.3.1" 
    Java(TM) 2 Runtime Environment, Standard Edition 
    Fast VM (build 1.3.1-3, native threads, mixed mode, precompiled rt.jar, ...)

To switch the default system Java environment version from SDK v 1.3.1 back to SDK v 1.1.8, use the following commands: 

   /usr/opt/java131/bin/unset_java_default.sh

   /usr/opt/java118/bin/set_java_default.sh

Troubleshooting Multiple Versions

If you have multiple Java environment versions installed on your system and have trouble running Java applications, first check what Java environment version you are using and what the default Java environment version is on the system: 

   % java -version                  # Check version being used 
   % /usr/bin/java -version         # Check default Java on system

Then check your definitions of PATH and CLASSPATH: 

   printenv PATH 
   printenv CLASSPATH

If you encounter the error "java: Permission denied", check to insure that PATH is set properly. See Changing Your PATH to Use Compaq SDK v 1.3.1.

Contents of the Compaq SDK

This section provides a general summary of the files and directories contained in the Compaq SDK once it has been installed on your system.

Development Tools

(In the bin subdirectory.) Programs that will help you develop, execute, debug, and document programs written in the Java programming language. For further information, see Sun's Tools and Utilities page.

Compaq Run Time Environment (RTE)

(In the jre subdirectory.) An implementation of the Compaq Run Time Environment (RTE) for use by the SDK. The runtime environment includes a virtual machine for Java 2, class libraries, and other files that support the execution of programs written in the Java programming language.

Additional libraries

(In the lib subdirectory.) Additional class libraries and support files required by the development tools.

Demo Applets and Applications

(In the demo subdirectory.) Examples, with source code, of programming for the Java platform. These include examples that use Swing and other Java Foundation Classes. The demos are installed in the following directory: 

   /usr/opt/java131/demo

C header Files

(In the include subdirectory.) Header files that support native-code programming using the Java Native Interface and the Java Virtual Machine Debugger Interface, as described on the Sun site.

Source Code

(In src.jar archive file.) Java programming language source files for all classes that make up the Java 2 core API (that is, source files for the java.*, javax.* and org.omg.* packages, but not for com.sun.* packages). This source code is provided for informational purposes only, to help developers learn and use the Java programming language. These files do not include platform-specific implementation code and cannot be used to rebuild the class libraries. To extract these files, use this command: 

   jar xvf src.jar

Do not modify core API source files. To extend the behavior of the core API, write subclasses of the core API classes.

For core API documentation, refer to the following sources:

Known Issues

This section provides descriptions of the known issues and limitations in the the SDK; they include the following:

With Java 2, Sun changed the underlying architecture of the graphics subsystem. In Sun's JDK V1.1.n, more of the graphics operations were done using native code. For example, the drawLine() method would result in a call to XDrawLine. With Java 2, the rendering of graphics has been moved to Java code, which computes the image and sends the pixels out to the display. As a result, the performance of graphical operations can be slower with J2SDK v 1.3.1, particularly when displaying to a remote machine.

Consequently, the slow performance that you see with some graphics operations is not specific to the Compaq SDK, but is inherent in the architecture of Java 2.

Sun has received a number of bug reports on this performance problem. For example, see the following list of bug reports in the Bug Database at Sun's Java Developer Connection web site: 4204845, 4185726, 4217446, and 4210230. Once you have logged in (you must register, but it is free), follow the link to the Bug Database.

Using the Compaq SDK on Tru64 UNIX Systems

The following sections provide useful information and tips for using the Compaq SDK on Tru64 UNIX systems.

Using Compaq SDK v 1.3.1

In most cases, SDK v 1.3.1 is not installed as the default system Java environment version (See Installing the Kit.). As a result, you must do one of the following to use SDK v 1.3.1:

Changing Your PATH to Use Compaq SDK v 1.3.1

If SDK v 1.3.1 is not the default system Java environment version, you can conveniently use SDK v 1.3.1 by changing the PATH environment variable as follows:

  1. Place the directory, /usr/opt/java131/bin, first in your PATH so that it is searched before the system directories. Directory /usr/opt/java131/bin contains the SDK v 1.3.1 executables. For example, using csh(1): 
       setenv PATH /usr/opt/java131/bin:$PATH
  2. Verify that you are using SDK version 1.3.1: 
      % java  -version
    java version "1.3.1"
    Java(TM) 2 Runtime Environment, Standard Edition
    Fast VM (build 1.3.1-3, native threads, mixed mode, precompiled rt.jar, ...)

To stop using SDK v 1.3.1, remove /usr/opt/java131/bin from your PATH.

Note: If you are using Tru64 UNIX 5.0A, you must remove /usr/opt/java131/bin from your PATH when using some Java-based tools that ship with the operating system. These tools, including the SysMan Station, the SysMan Station authentication daemon, and the Logical Storage Manager (LSM) Storage Administrator, depend on the Java environment version that ships with the operating system and is installed in /usr/bin. These tools will not work correctly if a different Java environment version is used due to your PATH definition.

Selecting the VM

As noted in the Introduction, this kit contains two virtual machines. The following sections describe how to control which virtual machine your application uses.

VM Options

SDK v 1.3.1 lets you control which virtual machine your application uses, based on the following options:

Option Function
-fast, -fast32 -fast and -fast32 perform the same operation. This is the default option and instructs the java command to use the Fast VM, using 32-bits to store pointers into objects.
-fast64 Instructs the Fast VM to use 64-bits for pointers.
-classic Directs the java command to use the classic virtual machine (classic VM, the virtual machine shipped with prior releases). The classic VM is based on Sun's reference implementation.

Using the Classic VM with Java 2 Development Tools

By default, the Fast VM is used when running the Java 2 development tools (for example, javac, javadoc, javap, jar, appletviewer, and so on). You can also use the classic VM by specifying the -classic option when you invoke the tool. For example, the following command uses the classic VM when running the appletviewer: 

appletviewer -classic runtest.html

The Classic VM Environment Variable

You can also use the classic VM by defining the environment variable JAVA_CLASSIC_VM. If this environment variable is defined, the classic VM is always used when the java command or the Java tools are invoked even if -classic is not specified.

The Fast VM 64-bit Addressing Environment Variable

To use the Fast VM (with 64-bit pointers), you can define the new environment variable JAVA_FAST64_VM. If you do not define this environment variable, by default the Fast VM is invoked in 32-bit mode.

Setting both environment variables, JAVA_CLASSIC_VM and JAVA_FAST64_VM, invokes the Fast VM in 64-bit mode. Note that using  a 'java' command line option overrides the setting of a Java virtual machine environment variable.

If you neither set an environment variable nor specify a command line option, the Fast VM with 32-bit pointers is invoked by default.

Command Line Options

Standard Options

The java command supports all standard options, as described on Sun's site. SDK v 1.3.1 includes the Fast VM, which is designed for high performance on Tru64 UNIX Alpha systems rather than Sun's HotSpot virtual machine. The -hotspot standard option is silently ignored. For more information, refer to Restrictions.

Non-Standard Options

By default, the java command supports most non-standard options, as described on Sun's site. The following options are supported by the classic VM and not by the Fast VM: -Xdebug, -Xnoclassgc, and -Xrunhprof. If your application uses one of these options, you must use the classic VM by specifying the -classic option. -Xprof is not supported; however, -Xrunhprof is available for classic VM profiling.

Additional Compaq Options

In addition to Sun's options, the Compaq java command supports the following options:

Option Function
-fast, -fast32 -fast and -fast32 perform the same operation. This is the default option and instructs the java command to use the Fast VM, using 32-bits to store pointers into objects.
-fast64 Instructs the Fast VM to use 64-bits for pointers.
-taso Load the executable in 31-bit addressable address range.
-client Initializes the Fast VM with a maximum heap size of 64 MB, a maximum global region size of 128 MB and the compacting collector. Refer to Reducing Fast VM Memory Requirements for Workstations and Client-side Applications for more information.
-Xglobal<size> Specifies the global region maximum allocation size. The global region contains class definitions, string constants, and other data internal to the VM. -Xglobal can be used to override the default size of 240 MB or the -client setting of 128 MB. Refer to Reducing Fast VM Memory Requirements for Workstations and Client-side Applications for more information.
-Xnoprecompiledsys Directs the Fast VM to not automatically load the optimized version of rt.jar.

The classes that make up the Java platform's core API reside in the file rt.jar. This release of the SDK provides three additional versions of this file that contain highly optimized native code compiled from the standard rt.jar classes. Three versions are required to support 32-bit pointers, 32-bit unsigned pointers, and 64-bit pointers. The Fast VM will automatically load the optimized versions of these classes when they are referenced by your application.

You can avoid using these precompiled versions by specifying the -Xnoprecompiledsys option on the command line.
-Xprecompiledsys

Directs the Fast VM to load the optimized version of rt.jar.
-Xgc:compacting Instructs the Fast VM to use the alternative compacting garbage collector, which compacts live data in-place, rather than copying it as the default collector does. This collector is a hybrid mark-sweep/mark-compact collector, which will avoid moving data when it is not necessary. (See also Dynamic Heap Management.)
-Xgc:copying Instructs the Fast VM to use the default "copying" garbage collector.
-Xmp When used with the compacting garbage collector, this specifies the minimum percentage of heap space that the collector should try to free for new objects. Thus, it dictates when a full compaction must occur, rather than a sweep or minor compaction. Values from 0 to 100 may be specified in the form -Xmpnn, for example, -Xmp25. The default value is 25.

Precompiled Standard Class files

The Compaq SDK provides precompiled versions of the rt.jar file that contain highly optimized native code compiled from the standard rt.jar classes. The Fast VM will automatically load the optimized versions of these classes when your application references them, provided you have installed the optional Java enhanced environment subset. This will improve performance of your application, depending on how heavily you rely on these classes. For more information, refer to -Xnoprecompiledsys.

Tuning and Performance

Refer to the following sections (Memory Usage, Reducing Fast VM Memory Requirements for Workstations and Client-side Applications, Dynamic Heap Management, Controlling Stack Size, Using the Fast VM for Applications Requiring a Large Virtual Address Space, Applications Using a Large Number of Threads, and Swap Space Problems) for specific tuning and performance information.

Memory Usage

The Fast VM has been tuned for large memory systems and, in addition, a number of tradeoffs have been made that favor speed of execution over memory usage. As a result, the Fast VM uses more physical and virtual memory for the same application, often as much as 50% more. This can lead to excessive paging and degraded performance if the system is not tuned correctly or if there is insufficient physical memory on the system. If you notice that your application runs more slowly with the Fast VM than with the classic JIT, you should do the following:

Note that a smaller heap that results in more garbage collections is preferable to allowing your application to page fault too often due to a large heap size. For more information on system tuning and resource limits, see the following:

Reducing Fast VM Memory Requirements for Workstations and Client-side Applications

The Fast VM is optimized for large, long-running programs running on server systems. Many users would like to use the Fast VM on their workstations for client-side applications; however, some of these systems do not have the resources to start up the Fast VM with its default configuration. A -client switch addresses these needs.

The client configuration significantly reduces the Fast VM memory footprint. It also bypasses the precompiled rt.jar files, which can add to VM startup time.

The -client switch is a convenience switch, analogous to setting the following switches on a command line:

java -Xmx64m -Xglobal28m -Xgc:compacting -Xnoprecompiledsys

The individual switch settings that make up the -client switch can be overridden. For example:

java -client -Xmx256m -Xprecompiledsys

will initialize the Fast VM with a maximum heap size of 256 MB, with a maximum global region size of 128 MB, with the compacting collector, and with precompiled rt.jar support active.

Dynamic Heap Management

Rather than use fixed values for the default settings for the memory allocation pool (Java heap), the Fast VM determines the defaults for the initial heap size (-Xms) and the maximum heap size (-Xmx) dynamically based on the environment in which it is executing as shown below: 

max_memory = min ( physical memory on machine, total memory available
to the process)
  
default initial heap size = 10% of max_memory
  
default maximum heap size = 60% of max_memory

By setting heap size defaults automatically, the Fast VM adjusts the heap size based on the available amount of memory. This generally produces better results than specifying fixed -Xmx and -Xms values, especially for an application that is executed on different systems with varying amounts of memory. It is sometimes possible to obtain better results by specifying -Xmx and -Xms rather than letting the Fast VM pick the defaults. To determine what values to use you should use the -verbosegc command line option to monitor your application's heap activity. If you notice that many garbage collections are occurring, increase the heap size as much as possible without causing excessive page faults. See Memory Usage for additional information.

-Xgc:compacting

The Fast VM supports an alternative compacting garbage collector, which compacts live data in-place, rather than copying it as the default collector does. This collector is a hybrid mark-sweep/mark-compact collector, which will avoid moving data when it is not necessary. You can use the -Xgc:compacting switch to enable the compacting garbage collector. This can significantly improve performance characteristics for applications with long-lived data. This is also a multi-threaded collector, so it can scale very well on multiprocessors.

Benefit: This collection scheme can have better performance characteristics and lower heap size requirements for applications in which the heap contains a high percentage of long-lived data. This collector can also perform minor collections, rather than collecting the entire heap, when the percentage of live data is moderate. It can also perform sweeps, which free space without moving any data at all. Thus, it may also provide performance advantages for certain applications with a moderate amount of long-lived data, but a high rate of short-lived object turnover.

To use the compacting collector, specify the  -Xgc:compacting  option on the command line. The  -Xgc:copying  option causes the Fast VM to use the default "copying" collector.

Controlling Stack Size

By default, the native stack size for Java threads on Tru64 UNIX Version 4.0 systems is about 128 KB. You can increase or decrease the native stack size using the  -Xssn  command line switch. Note that decreasing the native thread stack size can save memory but can also result in stack overflow exceptions if the native thread stacks are too small.

Example: 

   java -Xss512k MyApp

On Tru64 UNIX 5.0A and higher, the default native stack size is 1 MB, allocated as needed.

Using the Fast VM for Applications Requiring a Large Virtual Address Space

By default, the Fast VM uses 32-bits to store pointers in objects, which limits the amount of virtual memory available to Java applications. With the default, the memory allocation pool (Java heap) is limited to about 3 GB. The Fast VM provides an option to use 64-bits for pointers, which significantly increases the amount of memory available to Java applications. To use the 64-bit option, specify java -fast64 or define the new environment variable JAVA_FAST64_VM.

Applications Using a Large Number of Threads

If you experience a "java.lang.OutOfMemoryError" when attempting to create a large number of threads, consider increasing the proc subsystem attribute, max_threads_per_user. This attribute allows you to increase the maximum number of threads that can be allocated at any one time to each user, except superuser.

The Compaq Tru64 UNIX Best Practice guide recommends the following:

The default value of the max_threads_per_user attribute is based on the value of the maxusers attribute, so you can increase the maximum number of threads by increasing the maxusers attribute. You can also explicitly increase the maximum number of threads by increasing the max_threads_per_user attribute.

Use a value that is equal to or greater than the maximum number of threads that are allocated at one time on the system. For example, you could increase the value of the max_threads_per_user attribute to 512. On a busy server with sufficient memory or an Internet server, increase the value of the max_threads_per_user attribute to 4096. If the value of the max_threads_per_user attribute is 0 (zero), there is no limit on threads; this is not recommended.

You must reboot the system to use the new value of max_threads_per_user.

Swap Space Problems

If you see one of the following messages:

"Unable to obtain requested swap space"
"swap space below 10 percent free"

your machine may be low on swap space and require some system tuning to correct the problem. Note that the Fast VM, which is now the default, requires more memory than the classic VM, so you might not have received these messages in the past. You can reduce the Fast VM's memory requirements by using the -client option (see Reducing Fast VM Memory Requirements for Workstations and Client-side Applications), by using the -Xglobal<size> option to specify a smaller global region size, or by using the -Xmx<size> option to specify a smaller heap size. Another option is to use the classic VM by specifying -classic, which runs slower but requires less memory. Please see the System Configuration and Tuning Manual. For Tru64 UNIX V5.1 systems, the following sections may be helpful (similar sections would apply for other versions):

Creating a VM in C/C++ Programs Using the Invocation API

By default, this release supports the ability to create and invoke the Fast VM in C/C++ programs using the Invocation API. The Invocation API is an integral part of the Java Native Interface (JNI) that allows you to initialize virtual machine arguments, create, and load a virtual machine into your application, and then unload or destroy the virtual machine. For additional information about the Invocation API and how to use it, refer to the Sun JNI specification on Sun's site.

To take advantage of the Invocation API functionality, your C/C++ program (new and existing programs) must first create the virtual machine so that the Java code can be executed. Once the virtual machine is embedded into the program, the program can then load Java classes and execute Java methods. Assume that you have a C++ program called invokejvm.cxx: This program creates a virtual machine and then calls a Java method. The following is an example of a C++ command line that compiles and links a C++ program that invokes the Fast VM: 


cxx -pthread \
  -I/usr/opt/java131/include \
  -I/usr/opt/java131/include/alpha \
    invokejvm.cxx \
    /usr/opt/java131/jre/lib/alpha/fast64/libjvm.so \
  -o invokejvm

Note that all C/C++ code compiled for use with JNI must be built (compiled and linked) with the C/C++ -pthread  flag. Otherwise, your application will encounter severe multithreading problems, even if your Java and C/C++ code does not explicitly use threads. For more information about the  -pthread  flag, please see the C/C++ manpages.

Before running the resulting invokejvm, you must define LD_LIBRARY_PATH so that the following shared library directories are searched when loading the executable: 


/usr/opt/java131/jre/lib/alpha/
/usr/opt/java131/jre/lib/alpha/fast64
/usr/opt/java131/jre/lib/alpha/native_threads

For example, you can do this using the following csh commands: 


setenv JLIB /usr/opt/java131/jre/lib/alpha
setenv LD_LIBRARY_PATH ${JLIB}:${JLIB}/fast64:${JLIB}/native_threads

If your C or C++ main program is built with the -xtaso or -xtaso_short option to use 32-bit pointers, you should substitute fast32 for fast64 in the above cxx command line and LD_LIBRARY_PATH definition.

Using the Compaq Plug-in

Compaq Plug-in v 1.3.1-3 enables users to run Java applets and JavaBeans components on web pages using the RTE as an alternative to using the default Virtual Machine for Java 2 that comes with the web browser. It is based on the Java Plug-in 1.3.1 provided by Sun Microsystems and contains similar functionality.

For additional information on topics such as Java Plug-in security, using Signed Applets, JNI and the Java Plug-in, using the Java Plug-in in Intranet Environments, and how Proxy Configuration works in the Java Plug-in, please see the Sun Microsystems Java Plug-in 1.3 Documentation web site; the documentation is the same for Java Plug-in 1.3.1.

Note: You must be running Netscape Communicator 4.51 or higher, or Mozilla 0.7 or higher.

Installing the Compaq Plug-in

For Netscape 4.x browsers:

Set the NPX_PLUGIN_PATH environment variable to the location of the Plug-in (the directory in which the javaplugin.so file is located): 

NPX_PLUGIN_PATH=/usr/opt/java131/jre/plugin/alpha/ns4

Note: When setting the NPX_PLUGIN_PATH environment variable, do not include a trailing slash ('/'). If you include the trailing slash, the Plug-in will fail to load.

For Mozilla and Netscape 6.x browsers:

Create a symbolic link in the browser's plugins directory to the path of the libjavaplugin_oji.so file. This file is located at /usr/opt/java131/jre/plugin/alpha/ns600/libjavaplugin_oji.so.

For example:

cd ${MOZILLA}/plugins

ln -s /usr/opt/java131/jre/plugin/alpha/ns600/libjavaplugin_oji.so

Start your browser, or restart it if it is already running.

Restart your browser a second time. (This is a workaround to a browser bug.)

Converting Your HTML Pages

The Plug-in does not replace Navigator's underlying Virtual Machine for Java 2. Rather, it enables you to specify the use of the RTE instead of the default Navigator Virtual Machine for Java 2.

To use the Plug-in (instead of the browser's default Java environment version) when Netscape Navigator® browses a web page, you need to modify your web page source file(s). You can do this manually, using the OBJECT tag and the EMBED tag in your HTML specification. Alternatively, you can use the HTML Converter to automate modifications of your web page source files. For more information on HTML web page changes required by the Plug-in, see Sun's Java Plug-in HTML Specification.

The Plug-in HTML Converter

The HTML Converter easily and automatically modifies HTML pages to specify the use of the Compaq Plug-in rather than the browser's default Java runtime. The SDK v 1.3.1 kit provides the Plug-in HTML Converter so that a separate download is not required.

To run the GUI version of the HTML Converter, invoke the following command:

/usr/opt/java131/bin/HtmlConverter -gui

To run the command line version of the HTML converter, invoke the HTML Converter and specify the file to convert. For example:

/usr/opt/java131/bin/HtmlConverter file.html

For more information about the HTML Converter, see Sun's Java Plug-in HTML Converter Features and Sun's Plug-in HTML Converter Installation and Use web pages.

The Plug-in Control Panel

A Plug-in Control Panel lets you change Plug-in options such as proxies and enabling of the console window. It also allows you to switch the RTE version you want to run with your Plug-in. To run the Control Panel, enter the following command:


/usr/opt/java131/jre/bin/ControlPanel

Or you can use the Netscape Navigator browser to visit the Control Panel applet page that was installed as /usr/opt/java131/jre/bin/ControlPanel. For example: 


netscape /usr/opt/java131/jre/ControlPanel.html

Some of the Control Panel features are discussed below. Please refer to Sun's Java Plug-In Control Panel web page for information about additional features and uses of the Java Plug-in Control Panel.

Selecting the VM to Use in the Compaq Plug-in

By default, the Fast VM is used when running the Plug-in. You can have the Plug-in use the classic VM by defining the environment variable JAVA_PLUGIN_CLASSIC_VM prior to running your web browser.

To use the Fast VM (with 64-bit pointers), you can define the environment variable JAVA_PLUGIN_FAST64_VM. If you do not define this environment variable, by default the Fast VM is invoked in 32-bit mode.

Setting both environment variables, JAVA_PLUGIN_CLASSIC_VM and JAVA_PLUGIN_FAST64_VM, invokes the Fast VM in 64-bit mode.

If you don't set an environment variable, the Fast VM with 32-bit pointers is invoked by default.

Viewing Tracing Information

You can view a moderate amount of Plug-in tracing information in Netscape Alert Panels by setting the JAVA_PLUGIN_TRACE environment variable. If you set JAVA_PLUGIN_TRACE and want the output to go to the standard output/error (usually your terminal window), edit the following lines in your .Xdefaults or .Xresources file in your home directory.

Change "True" to "False": 


*useStderrDialog:  False
*useStdoutDIalog:  False

Then reload resources by typing the following command: 


xrdb -merge .Xdefaults

Displaying Java Error Messages

To see Java error messages:

  1. Use the Plug-in Control Panel to enable the console window.
  2. Exit Netscape Navigator and then restart it.

With the console window enabled, when you next visit a Plug-in enabled page, a separate window will come up to display error messages.

Font Support

The SDK includes the following font support.

Role of the font.properties File

Starting with SDK v 1.2.1, Java applications require a font property file to properly display the application's AWT windowing and Java2D components. This file contains mappings of Java logical font names to physical fonts on the X server. With SDK v 1.3.1, a font.properties file is installed by this kit in jre/lib/font.properties, which identifies fonts that should be available on your X server.

If you prefer to use fonts other than those that have been predefined by the property file for your use, copy the file installed by this kit from jre/lib/font.properties to your $HOME directory and modify it. When a Java application is run, it will use your local font property file instead of the one installed by this kit.

Multiple font.properties Files Provided

It is difficult to supply a font.properties file that is ideal for use in all environments. As a result, this kit contains two font.properties files:

Both of the font property files shipped with SDK v 1.3.1 kit reside in /usr/opt/java131/jre/lib/. The one actually named font.properties is the one that will be used. This file is a system-wide file and is used for the display of all Java programs that are run on that system. The SDK supports local customizations of the font property file which can take affect on a user or system-wide basis. When the Java runtime needs to find a font.properties file, it starts its search in $HOME. A local version of the font.properties file takes precedence over a system-wide version. Therefore, you can make either of these two files your user local font.properties by copying the font.properties file of your choice to a file named font.properties in $HOME.

Alternatively, if you want to use the font.properties.rotation file as a system-wide file for use by all users on the system (thus overriding the default font.properties file), perform the following steps:

   % cp /usr/opt/java131/jre/lib/font.properties \ 
        /usr/opt/java131/jre/lib/font.properties.orig  
   
   % cp /usr/opt/java131/jre/lib/font.properties.rotation \ 
        /usr/opt/java131/jre/lib/font.properties

If later you wish to revert to the original file that shipped with SDK v 1.3.1, you would copy font.properties.orig to font.properties.

If you prefer to use fonts other than those that have been predefined by the font properties file for your use, copy the file installed by this kit from /usr/opt/java131/jre/lib/font.properties to your $HOME directory and modify it. When a Java application is run, it will use your local font properties file instead of the one installed by this kit.

Retired Fonts

Starting with Compaq Tru64 UNIX Version 4.0F, all Adobe fonts under /usr/lib/X11/fonts/Type1Adobe are retired and no longer ship with the operating system.

If your Java application used the retired Type1Adobe outline fonts, it might be affected. For example, when characters are displayed on the screen, they might not scale as expected. If you customized your font.properties file to use these outline fonts, you might need to modify it to use alternative fonts that are available on your operating system. No replacements are being provided by the operating system. However, a smaller set of outline fonts is still available in /usr/lib/X11/fonts/Type1 and /usr/lib/X11/fonts/Speedo for your use.

Troubleshooting Font Problems

If you encounter one of the following warnings, you are probably referencing a font in your font.properties file that is not available on your system. Check your font path by issuing the UNIX command xset -q. If your display is not what you expect, you might need to change the search order. Also, make sure that the font property file does reference fonts that are installed on your system; you may be attempting to use a font that is not available. 

   "Font specified in font.properties not found [-*-helvetica-bold-r-normal...]"

If you are having problems with fonts when you display remotely to a PC using eXcursion™, you might need to upgrade to a newer version of the eXcursion software and install additional fonts. Also, make sure that the font property file references fonts that are installed on your PC.

Screen Resolution Display Problems

Font display problems can occur when running Java applications and displaying to systems that use certain graphics cards. Specifically, the fonts will appear jagged due to improper scaling. This problem is typically seen on graphics cards that default to a screen resolution of 1024x768. For example, the PowerStorm 4D10T (also known as the ELSA Gloria Synergy) card has the problem. These cards typically support higher screen resolutions but default to a lower resolution to support smaller monitors.

There are two workarounds to this font scaling problem. Both involve editing the X Server configuration file /usr/var/X11/Xserver.conf, which contains startup information for the X Server. Note that on a Tru64 UNIX V5.x system, this file is a context-dependent symbolic link (CDSL). In a cluster environment, there exists one version of this file per cluster member. Be sure to make the edits on the appropriate cluster member or using an explicit path such as:

/usr/var/cluster/members/memberN/X11/Xserver.conf

where N is the appropropriate member number.

The two workarounds are:

  1. If the system has a monitor that supports a higher resolution such as 1280x1024, configure the X Server for this higher screen resolution as follows:

Note that the -screen option can be specified as -screenN for multiheaded systems.

  1. Tell the X Server to use either 100 dpi or 75 dpi fonts explicitly. For example, by default, a 1024x768 monitor is configured to use 75 dpi fonts. Tell the X Server to operate at 75 explicitly:

Typically, 75 dpi is a good choice for monitors with a resolution of 1024x768. If you would like the fonts to be uniformly larger, use 100 dpi fonts by specifying -dpi 100.

For more detailed information on changing X Server screen settings, refer to section "Adjusting Your Screen Settings" of the Compaq Tru64 UNIX Best Practice guide.

Window Managers Supported by the Compaq SDK

The CDE desktop window manager (dtwm), and the Motif window manager (mwm), are fully supported. You may also use the DIGITAL eXcursion™ window manager when running your Java application on a Compaq Tru64 UNIX system and redirecting the display back to a PC.

Non-standard window managers such as fvwm and twm are not supported. Therefore, you may experience some unusual behavior when using them.

Restrictions

Documentation and Other Information

Documentation

If the optional documentation subset (JAVADOC131) is installed, then the SDK documentation tree begins at the following location on the system where the SDK is installed: 

   /usr/opt/java131/docs/index.html

The installed documentation is in HTML format and includes this release notes file (which describes SDK information specific to Compaq Tru64 UNIX systems) and a readme.html file (which contains a brief summary of important instructions you should perform before you install this kit).

Note: The documentation in JAVADOC131 does not include the API reference documentation. If you want to use the API reference documentation locally, download and install the separate javaapidoc131-3.tar file as described in the Installation section. Browse the API documentation using the following location:

   /usr/opt/java131/docs/api/index.html

Also, you can browse the Software Documentation page on our web site.

There is also a java manpage that describes the java command and points to the installed documentation. The java manpage ships with the operating system and describes the Java environment version that was shipped; the manpage is not updated by this kit.

More Information

For more information on this release, refer to the Release Notes for the J2SDK v 1.3.1 software from Sun Microsystems, and our Frequently Asked Questions (FAQ) web page.

If you are new to the Java programming language, you will want to browse or download the Java Tutorial at http://java.sun.com/docs/books/tutorial/ on Sun's site.

Problem Reporting

To report bugs or feature requests, refer to our Contact Us web page.

© 2002 Compaq Information Technologies Group, L.P.
Compaq Registered in U.S. Patent and Trademark Office.
Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.
Metro-X, ConfigX, Motif Complete!, Essential Elements for Linux and the Metro Link logo are trademarks of Metro Link in the United States and/or other countries.
Metro Motif Complete!, Essential Elements for Linux and the Metro Link logo are trademarks of Metro Link in the United States and/or other countries. Motif, UNIX, and The Open Group are trademarks of The Open Group.
Netscape and Netscape Navigator are registered trademarks of Netscape Communications Corporation in the United States and other countries.
All other product names mentioned herein may be trademarks or registered trademarks of their respective companies.
Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is subject to change without notice.