Date: 2005-10-25

# IBM SDK and Runtime Environment for Linux platforms, Java 2 Technology Edition, Version 5.0

# User Guide

# Copyright information

Note: Before using this information and the product it supports, be sure to read the general information under Notices.

This edition of the User Guide applies to the:

- IBM 32-bit SDK and Runtime Environment for Linux on Intel architecture, Java 2 Technology Edition, Version 5.0
- IBM 64-bit SDK and Runtime Environment for Linux on AMD64/EM64T architecture, Java 2 Technology Edition, Version 5.0
- IBM 32-bit SDK and Runtime Environment for Linux on iSeries and pSeries architecture, Java 2 Technology Edition, Version 5.0
- IBM 64-bit SDK and Runtime Environment for Linux on iSeries and pSeries architecture, Java 2 Technology Edition, Version 5.0
- IBM 31-bit SDK and Runtime Environment for Linux on zSeries architecture, Java 2 Technology Edition, Version 5.0
- IBM 64-bit SDK and Runtime Environment for Linux on zSeries architecture, Java 2 Technology Edition, Version 5.0

and to all subsequent releases and modifications until otherwise indicated in new editions.

(c) Copyright Sun Microsystems, Inc. 1997, 2004, 901 San Antonio Rd., Palo Alto, CA 94303 USA. All rights reserved.

(c) Copyright International Business Machines Corporation, 1999, 2005. All rights reserved.

U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

# Preface

This User Guide provides general information about the IBM(R) SDK and Runtime Environment for Linux(TM) platforms, Java(TM) 2 Technology Edition, Version 5.0 and specific information about any differences in the IBM implementation compared with the Sun implementation. Read this User Guide in conjunction with the more extensive documentation on the Sun Web site: http://java.sun.com.

For the list of distributions against which the SDK and Runtime Environment for Linux have been tested, see: http://www-106.ibm.com/developerworks/java/jdk/linux/tested.html.

The Diagnostics Guide provides more detailed information about the IBM Virtual Machine for Java.

The terms "Runtime Environment" and "Java Virtual Machine" are used interchangeably throughout this User Guide.

Technical changes made to this User Guide for Version 5.0, other than minor or obvious ones such as updating "1.4.2" to "5.0", are indicated in red when viewing in HTML or in a color-printed copy and by vertical bars to the left of the changes.

For this release, the Simplified Chinese IBM SDK and Runtime Environment for Linux User Guide is provided in English.

# Contents

Copyright information
Preface
Overview
Conventions
Version compatibility
Upgrading the SDK
Migrating from other IBM JVMs
| |
Supported hardware for zSeries
Contents of the SDK and Runtime Environment
Runtime Environment tools
SDK tools
Installing and configuring the SDK and Runtime Environment
Installing on Red Hat Enterprise Linux (RHEL) 4
| |
Installing a 32-bit SDK on 64-bit architecture
Installing from an RPM file
Installing from a .tgz file
Configuring the SDK and Runtime Environment for Linux
Setting the PATH
Setting the CLASSPATH
Uninstalling the SDK and Runtime Environment for Linux
Uninstalling the Red Hat Package Manager (RPM) package
Uninstalling the compressed Tape Archive (TAR) package
Using the Runtime Environment
Options
Specifying Java options and system properties
Standard options
Nonstandard options
Obtaining the IBM build and version number
Globalization of the java command
The Just-In-Time (JIT) compiler
Disabling the JIT
Enabling the JIT
Determining whether the JIT is enabled
Specifying garbage collection policy
Garbage collection options
Pause time
Pause time reduction
Environments with very full heaps
How the JVM processes signals
Signals used by the JVM
Linking a native code driver to the signal-chaining library
Working with floating stacks
Transforming XML documents
Using an older version of Xerces or Xalan
Using the SDK to develop Java applications
Debugging Java applications
Java Debugger (JDB)
Determining whether your application is running on a 32-bit or 64-bit JVM
Writing JNI applications
| |
Support for thread-level recovery of blocked connectors
Working with applets
Running applets with the Applet Viewer
Debugging applets with the Applet Viewer
| |
Configuring large page memory allocation
CORBA support
Support for GIOP 1.2
Support for Portable Interceptors
Support for Interoperable Naming Service
System properties for tracing the ORB
System properties for tuning the ORB
Java 2 security permissions for the ORB
ORB implementation classes
RMI over IIOP
Implementing the Connection Handler Pool for RMI
Enhanced BigDecimal
Euro symbol support
Using the Java Communications API (JavaComm)
Installing Java Communications API
Location of Java Communications API files
Configuring Java Communications API
Changing the access mode of serial and parallel ports
Enabling serial ports on IBM ThinkPads
Printing limitation with the Java Communications API
Uninstalling Java Communications API
Uninstalling the installable Red Hat Package Manager (RPM) package
Uninstalling the compressed Tape Archive (TAR) package
Java Communications API documentation
Deploying Java applications
(Linux IA 32-bit and PPC32 only) Using the Java Plug-in
Supported browsers
Installing and configuring the Java Plug-in
Common Document Object Model (DOM) support
Using DBCS parameters
(Linux IA 32-bit, PPC32, and PPC64 only) Using Web Start
Running Web Start
Shipping Java applications
| |
Class data sharing between JVMs
| |
Overview of class sharing
| |
Cache contents
| |
Dynamic updating of the cache
| |
Enabling class sharing
| |
Cache security
| |
Cache lifespan
| |
Cache utilities
| |
Using command-line options for class sharing
| |
Creating, populating, monitoring, and deleting a cache
| |
Performance and memory consumption
| |
Limitations and considerations of using class sharing
| |
Cache size limits
| |
Runtime bytecode modification
| |
Operating system limitations
| |
Using SharedClassPermission
| |
Adapting custom classloaders to share classes
Service and support for independent software vendors
Accessibility
iKeyman accessibility
Keyboard traversal of JComboBox components in Swing
(Linux IA 32-bit, PPC32, and PPC64 only) Web Start accessibility
Known limitations
Limitations that apply to all Linux platforms except where indicated
Linux IA 32-bit limitations
Linux AMD64 limitations
Linux PPC 32-bit and 64-bit limitations
Linux PPC 64-bit limitations
Linux zSeries 64-bit limitations
Linux zSeries 31-bit and 64-bit limitations
Any comments on this User Guide?
Notices
Trademarks

# Overview

The IBM SDK is a development environment for writing and running applets and applications that conform to the IBM Java 5.0 Core Application Program Interface (API).

The SDK includes the Runtime Environment for Linux, which enables you only to run Java applications. If you have installed the SDK, the Runtime Environment is included.

The Runtime Environment contains the Java Virtual Machine and supporting files including non-debuggable .so files and class files. The Runtime Environment contains only a subset of the classes that are found in the SDK and allows you to support a Java program at runtime but does not allow you to compile Java programs. The Runtime Environment for Linux does not include any of the development tools, such as appletviewer or the Java compiler (javac), or classes that are only for development systems.

In addition, for IA32, PPC32, and AMD64/EM64T platforms, the Java Communications application programming interface (API) package is provided for use with the Runtime Environment for Linux. You can find information about it in Using the Java Communications API (JavaComm).

The license_xx.html file contains the license agreement for the Runtime Environment for Linux software. (xx is an abbreviation for the language.) To view or print the license agreement, open the file in a Web browser.

## Conventions

Throughout this User Guide the default installation directory of the SDK is referred to as /opt/ibm/java2-i386-50/. The platforms listed below have different default installation directories; replace the directory for the platform you are using when you see /opt/ibm/java2-i386-50/:

- Linux IA 32-bit: /opt/ibm/java2-i386-50/
- Linux AMD 64-bit: /opt/ibm/java2-x86_64-50/
- Linux PPC 32-bit: /opt/ibm/java2-ppc-50/
- Linux PPC 64-bit: /opt/ibm/java2-ppc64-50/
- Linux zSeries 31-bit: /opt/ibm/java2-s390-50/
- Linux zSeries 64-bit: /opt/ibm/java2-s390x-50/

## Version compatibility

In general, any applet or application that ran with a previous version of the SDK should run correctly with the IBM SDK for Linux, v5.0. Classes compiled with this release are not guaranteed to work on previous releases.

To read Sun's documentation on compatibility, see the Sun Web site at http://java.sun.com.

## Upgrading the SDK

If you are upgrading the SDK from a previous release, back up all the configuration files and security policy files before you start the upgrade.

After the upgrade, you might have to restore or reconfigure these files because they might have been overwritten during the upgrade process. Check the syntax of the new files before restoring the original files because the format or options for the files might have changed.

## Migrating from other IBM JVMs

From Version 1.4.2 for AMD64/EM64T and Version 5 for the other Linux platforms, the IBM Runtime Environment for Linux contains new versions of the IBM Java Virtual Machine and the Just-In-Time (JIT) compiler. If you are migrating from an older IBM Runtime Environment, note that:

- The JVM shared library libjvm.so is installed in directory jre/bin/j9vm. This directory is different, for example, from the Runtime Environment for Linux for Version 1.4.2 (for all platforms other than AMD64/EM64T), where it is installed in jre//bin/classic. Native applications using the JNI invocation interface might need to add the new directory path to their LIBPATH environment variable or variables in order to locate the JVM shared library.
- |The JVM Monitoring Interface (JVMMI) is no longer available. |You must rewrite applications that used that API. You are recommended to use |the JVM Tool Interface (JVMTI) instead. The JVMTI is not functionally the |equivalent of JVMMI. For information about JVMTI, see http://java.sun.com/j2se/1.5.0/docs/guide/jvmti/ and the Diagnostics Guide.
- |The new implementation of JNI conforms to the JNI specification, |but differs from the old implementation. It returns copies of objects rather |than pinning the objects. This difference can expose errors in JNI application |code. For information about debugging JNI code, see -Xcheck:jni in Nonstandard options.
- |The format and content of garbage collector verbose logs obtained |using -verbose:gc have changed. The data is now formatted |as XML. The data content reflects the changes to the implementation of garbage |collection in the JVM, and most of the statistics that are output have changed. |You must change any programs that process the verbose GC output so that they |will work with the new format and data. See the Diagnostics Guide for an example of the new verbose GC data.
- |SDK 1.4 versions of the IBM JRE shipped with JVM specific |classes in a file called core.jar. From Java 5.0 onwards, these are shipped |in a file called vm.jar.
- Earlier versions of the IBM JRE shipped with a file called rt.jar in the jre/lib directory. From Java v1.4 onwards, this file has been replaced by multiple JAR files that reside in the jre/lib directory.
- |For additional industry compatibility and deprecated API information, |see Sun's Java 5 Compatibility Documentation and Sun's Java 5 Deprecated API List
- |Tracing class dependencies, invoked using -verbose:Xclassdep, is not supported. If you specify -verbose:Xclassdep, the JVM will issue an error message and will not |start.

| | |

## Supported hardware for zSeries

|

The zSeries 31-bit |and 64-bit SDKs and Runtime Environments run on the |following System z9 and zSeries servers or equivalents:

|

|
- z9-109
|
- z990
|
- z900
|
- z890
|
- z800

# Contents of the SDK and Runtime Environment

The SDK contains several development tools and a Java Runtime Environment (JRE). This section describes the contents of the SDK tools and the Runtime Environment.

Applications written entirely in Java should have no dependencies on the IBM SDK's directory structure (or files in those directories). Any dependency on the SDK's directory structure (or the files in those directories) could result in application portability problems.

## Runtime Environment tools

- Core Classes -- These are the compiled class files for the platform and must remain zipped for the compiler and interpreter to access them. Do not modify these classes; instead, create subclasses and override where you need to.
- JRE tools -- The following tools are part of the Runtime Environment and are in the /opt/ibm/java2-i386-50/jre/bin directory unless otherwise specified.
  - java (Java Interpreter)
    - Runs Java classes. The Java Interpreter runs programs that are written in the Java programming language.
  - javaw (Java Interpreter)
    - Runs Java classes in the same way as the java command does, but does not use a console window.
  - keytool (Key and Certificate Management Tool)
    - Manages a keystore (database) of private keys and their associated X.509 certificate chains that authenticate the corresponding public keys.
  - policytool (Policy File Creation and Management Tool)
    - Creates and modifies the external policy configuration files that define your installation's Java security policy.
  - rmid (RMI activation system daemon)
    - Starts the activation system daemon so that objects can be registered and activated in a Java virtual machine (JVM).
  - tnameserv (Common Object Request Broker Architecture (CORBA) Naming Service)
    - Starts the CORBA transient naming service.
  - rmiregistry (Java Remote Object Registry)
    - Creates and starts a remote object registry on the specified port of the current host.
  - ikeyman (iKeyman GUI utility)
    - Allows you to manage keys, certificates, and certificate requests. For more information see the accompanying Security Guide and http://www.ibm.com/developerworks/java/jdk/security. The SDK also provides a command-line version of this utility. See iKeyman accessibility for details.
  - jextract (Dump extractor)
    - Converts a system-produced dump into a common format that can be used by jdmpview. For more information, see the Diagnostics Guide.
  - (Linux IA 32-bit, PPC32, and PPC64 only) javaws (Java Web Start)
    - Enables the deployment and automatic maintenance of Java applications.
  - (Linux IA 32-bit, PPC32, and PPC64 only) |updateSettings.sh (Java Web Start settings)
    - Configures your system to use web start with your browser. For more information, see Running Web Start. This file is installed in the jre/lib/javaws directory.

## SDK tools

- The following tools are part of the SDK and are located in the /opt/ibm/java2-i386-50/bin directory:
  - javac (Java Compiler)
    - Compiles programs that are written in the Java programming language into bytecodes (compiled Java code).
  - appletviewer (Java Applet Viewer)
    - Tests and runs applets outside a Web browser.
  - jdb (Java Debugger)
    - Helps debug your Java programs.
  - javap (Class File Disassembler)
    - Disassembles compiled files and can print a representation of the bytecodes.
  - javadoc (Java Documentation Generator)
    - Generates HTML pages of API documentation from Java source files.
  - javah (C Header and Stub File Generator)
    - Enables you to associate native methods with code written in the Java programming language.
  - jar (Java Archive Tool)
    - Combines multiple files into a single Java Archive (JAR) file.
  - jarsigner (JAR Signing and Verification Tool)
    - Generates signatures for JAR files and verifies the signatures of signed JAR files.
  - jconsole (JConsole Monitoring and Management Tool - experimental)
    - Experimental (unsupported) JMX-compliant graphical tool for monitoring local and remote JVMs.
  - native2ascii (Native-To-ASCII Converter)
    - Converts a native encoding file to an ASCII file that contains characters encoded in either Latin-1 or Unicode, or both.
  - rmic (Java Remote Method Invocation (RMI) Stub Converter)
    - Generates stubs, skeletons, and ties for remote objects. Includes RMI over Internet Inter-ORB Protocol (RMI-IIOP) support.
  - java-rmi.cgi (HTTP-to-CGI request forward tool)
    - Accepts RMI-over-HTTP requests and forwards them to an RMI server listening on any port.
  - idlj (IDL to Java Compiler)
    - Generates Java bindings from a given IDL file.
  - serialver (Serial Version Command)
    - Returns the serialVersionUID for one or more classes in a format that is suitable for copying into an evolving class.
  - extcheck (Extcheck utility)
    - Detects version conflicts between a target jar file and currently-installed extension jar files.
  - jdmpview (Cross-platform dump formatter)
    - A tool that allows you to analyze dumps. For more information, see the Diagnostics Guide.
  - (Linux IA 32-bit, PPC32, and PPC64 only) HtmlConverter (Java Plug-in HTML Converter)
    - Converts an HTML page that contains applets to a format that can use the Java Plug-in.
- Include Files
  - C headers for JNI programs.
- Demos
  - The demo directory contains a number of subdirectories containing sample source code, demos, applications, and applets that you can use.
- COPYRIGHT
  - Copyright notice for the SDK for Linux software.
- License
  - The License file, /opt/ibm/java2-i386-50/docs/<locale>/license_<locale>.html, contains the license agreement for the SDK for Linux software (where <locale> is the name of your locale, for example En_US). To view or print the license agreement, open the file in a Web browser.
- fixes.lst
  - A text file that describes any defects that are fixed after the initial release of this version.

Note: The User Guides, Javadoc, and the accompanying license, copyright files, javadoc, and demo directory are the only documentation included in this SDK for Linux. You can view Sun's software documentation by visiting the Sun Web site, or you can download Sun's software documentation package from the Sun Web site: http://java.sun.com.

# Installing and configuring the SDK and Runtime Environment

You can install the IBM Java SDK and Runtime Environment from either an RPM or a .tgz file. Unless you want to allow all the users on the machine to access this Java installation, use .tgz installation method. If you do not have root access, use the .tgz file.

If you install using an RPM file, the Java files are installed in /opt/ibm/java2-i386-50/. The examples in this guide assume that you have installed Java in this directory.

## Installing on Red Hat Enterprise Linux (RHEL) 4

The SDK depends on shared libraries that are not installed by default for Red Hat Enterprise Linux (RHEL) 4.0.

The RPMs that contain these libraries are:

- `compat-libstdc++-33-3.2.3` and `xorg-x11-deprecated-libs-6.8.1` (Intel Architecture, PPC, and PPC64)
- `compat-libstdc++-295-2.95.3` and `xorg-x11-deprecated-libs-6.8.1` (zSeries)

To include these libraries during RHEL 4 installation:

1. When you reach the Package Defaults screen, select Customize the set of packages to be installed.
2. At the Package Group Selection screen, under X Windows System, choose Details and make sure that you have selected `xorg-x11-deprecated-libs`.
3. Under the Development options, select Legacy Software Development.

| | |

## Installing a 32-bit SDK on 64-bit architecture

|

To run the SDK, you must install the correct versions of all libraries |required by the SDK, either 32- or 64-bit.

|

In RHEL4, the 64-bit versions of the packages are available in the Compatibility Arch Support package group.

|

You can use the RPM tool to check which versions of the packages you have |installed by adding the option `--queryformat "%{NAME}.%{ARCH}\n"` to |your RPM command. For example:

|

    /home/username : rpm --queryformat "%{NAME}.%{ARCH}\n" -q libstdc++
    |libstdc++.x86_64
    |libstdc++.i386

## Installing from an RPM file

1. Open a shell prompt, making sure you are root.
2. At a shell prompt, type `rpm -ivh <RPM file>`. For example:

       |rpm -ivh ibm-java2-<arch>-sdk-5.0-0.0.<arch>.rpm

   or

       |rpm -ivh ibm-java2-<arch>-jre-5.0-0.0.<arch>.rpm

   |Where `<arch>` represents your architecture: |i386, x86_64, ppc, ppc64, s390, or s390x.

## Installing from a .tgz file

1. Create a directory to store the Java package files. The examples in this guide assume that you have installed in /opt/ibm/java2-i386-50/. In the rest of the guide, replace /opt/ibm/java2-i386-50/ with the directory in which you installed Java.
2. At a shell prompt, type `tar -zxvf <.tgz file>`. For example:

       |tar -zxvf ibm-java2-sdk-50-linux-<arch>.tgz

   or

       |tar -zxvf ibm-java2-jre-50-linux-<arch>.tgz

   |Where `<arch>` represents your architecture: i386, x86_64, ppc, |ppc64, s390, or s390x.

## Configuring the SDK and Runtime Environment for Linux

### Setting the PATH

Note that, if you alter the PATH environment variable as described below, you will override any existing Java executables in your path.

After setting the path, you can run a tool by typing its name at a shell prompt with a filename as an argument.

You can specify the path to a tool by typing the path before the name of the tool each time. For example, if the SDK is installed in /opt/ibm/java2-i386-50/bin, you can compile a file named myfile.java by typing the following at a shell prompt:

      "/opt/ibm/java2-i386-50/bin/javac" myfile.java

To change the PATH environment variable:

1. Edit the shell startup file in your home directory (usually .bashrc, depending on your shell) and add the absolute paths to the PATH environment variable; for example:

       export PATH=/opt/ibm/java2-i386-50/bin:/opt/ibm/java2-i386-50/jre/bin:$PATH

2. Log on again or run the updated shell script to activate the new PATH setting.

### Setting the CLASSPATH

The CLASSPATH tells the SDK tools, such as java, javac, and javadoc, where to find the Java class libraries.

You need to set the CLASSPATH explicitly only if one of the following applies:

- You require a different library or class file, such as one that you develop, and it is not in the current directory.
- You change the location of the bin and lib directories and they no longer have the same parent directory.
- You plan to develop or run applications using different runtime environments on the same system.

To display the current value of your CLASSPATH, type the following at a shell prompt:

      echo $CLASSPATH

If you develop and run applications that use different runtime environments, including other versions that you have installed separately, you must set the CLASSPATH (and PATH) explicitly for each application. If you run multiple applications simultaneously and use different runtime environments, each application must run in its own shell.

If you run only one version of Java at a time, you can use a shell script to switch between the different runtime environments.

Note:
(For Linux IA 32-bit Chinese users only) Because of inconsistencies in the font encodings on Red Hat Advanced Server, when you install for an environment in which you want Chinese to be the default language, it is better to install with a default language of English and then change to Chinese after the installation is complete. Otherwise, you might find that the Chinese fonts do not display.

## Uninstalling the SDK and Runtime Environment for Linux

The process that you use to remove the SDK and Runtime Environment for Linux depends on what type of installation you used. See Uninstalling the Red Hat Package Manager (RPM) package or Uninstalling the compressed Tape Archive (TAR) package for instructions.

### Uninstalling the Red Hat Package Manager (RPM) package

To uninstall the SDK or Runtime Environment for Linux if you installed the installable RPM package:

1. At a shell prompt,
   1. To check which RPM packages you have installed, type:

          rpm -qa | grep -i java

   2. You will see a list of any IBM Java packages that you have installed; for example:

          ibm-java2-<arch>-jre-5.0-0.0.<arch>
          ibm-java2-<arch>-sdk-5.0-0.0.<arch>

   3. This output tells you which packages you can uninstall, using the `rpm -e` command; for example:

          rpm -e ibm-java2-<arch>-jre-5.0-0.0.<arch>
          rpm -e ibm-java2-<arch>-sdk-5.0-0.0.<arch>

   Alternatively, you can use a graphical tool such as kpackage or yast2
2. Remove from your PATH statement the directory in which you installed the SDK and Runtime Environment.
3. (Linux IA 32-bit and PPC32 only) If you installed the Java Plug-in, remove the Java Plug-in files from the web browser directory.

### Uninstalling the compressed Tape Archive (TAR) package

To uninstall the SDK or Runtime Environment for Linux if you extracted the compressed TAR package:

1. Remove the SDK or Runtime Environment files from the directory in which you installed the SDK or Runtime Environment.
2. Remove from your PATH statement the directory in which you installed the SDK or Runtime Environment.
3. Log on again or run the updated shell script to activate the new PATH setting.
4. (Linux IA 32-bit and AMD64/EM64T only) If you installed the Java Plug-in, remove the Java Plug-in files from the web browser directory.

# Using the Runtime Environment

The java tool launches a Java application by starting a Java Runtime Environment and loading a specified class.

The JVM searches for the initial class (and other classes that are used) in three sets of locations: the bootstrap classpath, the installed extensions, and the user classpath. The arguments that you specify after the class name or JAR file name are passed to the main function.

The javaw command is identical to java, except that javaw has no associated console window. Use javaw when you do not want a command prompt window to appear. The javaw launcher displays a dialog box with error information if a launch fails.

The java and javaw command have the following syntax:

    java [ options ] class [ arguments ... ]
    java [ options ] -jar file.jar [ arguments ... ]
    javaw [ options ] class [ arguments ... ]
    javaw [ options ] -jar file.jar [ arguments ... ]

Items that are within brackets are optional.

options
  Command-line options.
class
  Name of the class to invoke.
file.jar
  Name of the jar file to invoke. It is used only with -jar.
arguments
  Arguments passed to the main function.

If the -jar option is specified, the named JAR file must contain class and resource files for the application, with the startup class indicated by the Main-Class manifest header.

## Options

The launcher has a set of standard options that are supported on the current runtime environment and will be supported in future releases. In addition, there is a set of nonstandard options. The default options have been chosen for best general use. Plan carefully before making changes.

### Specifying Java options and system properties

You can specify Java options and system properties in these ways. In order of precedence, they are:

1. By specifying the option or property on the command line. For example, `java -Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump MyJavaClass`.
2. By creating a file that contains the options, and specifying it on the command line using -Xoptionsfile=<filename>.
3. By creating an environment variable called IBM_JAVA_OPTIONS containing the options. For example:

       export IBM_JAVA_OPTIONS="-Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump"

Rightmost options on the command line have precedence over leftmost options; for example, if you specify the options `-Xint -Xjit myClass`, `-Xjit` takes precedence.

### Standard options

- -agentlib:<libname>[=<options>]
  - Load native agent library <libname>; for example -agentlib:hprof. For more information, specify -agentlib:jdwp=help and -agentlib:hprof=help on the command line.
- -agentpath: libname[=<options>]
  - Load native agent library by full pathname.
- -assert
  - Prints help on assert-related options.
- -cp or -classpath <directories and zip or jar files separated by :>
  - Sets the search path for application classes and resources. If -classpath and -cp are not used and CLASSPATH is not set, the user classpath is, by default, the current directory (.).
- -D<property_name>=<value>
  - Sets a system property.
- -help or -?
  - Prints a usage message.
- -javaagent:<jarpath>[=<options>]
  - Load Java programming language agent. For more information, see the java.lang.instrument API documentation.
- -jre-restrict-search
  - Include user private JREs in the version search.
- -no-jre-restrict-search
  - Exclude user private JREs in the version search.
- -showversion
  - Prints product version and continues.
- -verbose:[class,gcterse,gc,dynload,stackwalk,sizes,stack,debug,jni]
  - Enables verbose output.
- -version
  - Prints product version.
- -version:<value>
  - Require the specified version to run.
- -X
  - Prints help on nonstandard options.

### Nonstandard options

The -X options listed below are nonstandard and subject to change without notice.

For options that take <size> parameter, you should suffix the number with "k" or "K" to indicate kilobytes, "m" or "M" to indicate megabytes, or "g" or "G" to indicate gigabytes.

- -Xargencoding
  - Allows you to put Unicode escape sequences in the argument list. This option is set to off by default.
- -Xbootclasspath:<directories and zip or jar files separated by ;>
  - Sets the search path for bootstrap classes and resources. The default is to search for bootstrap classes and resources within the internal VM directories and .jar files.
- -Xbootclasspath/a:<directories and zip or jar files separated by ;>
  - Appends the specified directories, zip, or jar files to the end of bootstrap class path. The default is to search for bootstrap classes and resources within the internal VM directories and .jar files.
- -Xbootclasspath/p:<directories and zip or jar files separated by ;>
  - Prepends the specified directories, zip, or jar files to the front of the bootstrap class path. Do not deploy applications that use the -Xbootclasspath: or -Xbootclasspath/p: option to override a class in the standard API, because such a deployment would contravene the Java 2 Runtime Environment binary code license. The default is to search for bootstrap classes and resources within the internal VM directories and .jar files.
- -Xcheck:jni
  - Performs additional checks for JNI functions. You can also use -Xrunjnichk. By default, no checking is performed.
- -Xcheck:nabounds
  - Performs additional checks for JNI array operations. You can also use -Xrunjnichk. By default, no checking is performed.
- |-Xclassgc |
  |
  - Enables collection of class objects at every garbage collection. By default, |this option is enabled.
- -Xcompactexplicitgc
  - Compact on every call to `System.gc()`. See also -Xnocompactexplicitgc. By default, compaction occurs only when triggered internally.
- -Xcompactgc
  - Compact every Garbage Collector cycle. See also -Xnocompactgc. By default, compaction occurs only when triggered internally.
- |-Xconcurrentbackground <number> |
  |
  - Specifies the number of low priority background threads attached to assist |the mutator threads in concurrent mark. The default is 1.
- |-Xconcurrentlevel <number> |
  |
  - Specifies the allocation "tax" rate. It indicates the ratio between the |amount of heap allocated and the amount of heap marked. The default is 8.
- |-Xconmeter:<soa | loa | dynamic> |
  |
  - Determines which area's usage, LOA (Large Object Area) or SOA (Small Object |Area), is metered and hence which allocations are taxed during concurrent |mark. The allocation tax is applied to the selected area. If -Xconmeter:dynamic is specified, the collector dynamically determines |the area to meter based on which area is exhausted first. By default, the |option is set to -Xconmeter:soa.
- -Xdbg:<options>
  - Loads debugging libraries to support the remote debugging of applications. Specifying -Xrunjdwp provides the same support. By default, the debugging libraries are not loaded, and the VM instance is not enabled for debug.
- -Xdbginfo:<path to symbol file>
  - Loads and passes options to the debug information server. By default, the debug information server is disabled.
- -Xdebug
  - Starts the JVM with the debugger enabled. By default, the debugger is disabled.
- |-Xdisableexcessivegc |
  |
  - Disables the throwing of an OutOfMemoryError if excessive time is spent |in the GC. By default, this option is off.
- -Xdisableexplicitgc
  - Signals to the VM that calls to `System.gc()` should have no effect. By default, calls to `System.gc()` trigger a garbage collection.
- |-Xdisablestringconstantgc |
  |
  - Prevents strings in the string intern table from being collected. By default, |this option is disabled.
- -Xdisablejavadump
  - Turns off javadump generation on errors and signals. By default, javadump generation is enabled.
- |-Xenableexcessivegc |
  |
  - If excessive time is spent in the GC, this option returns NULL for an |allocate request and thus causes an OutOfMemoryError to be thrown. This action |occurs only when the heap has been fully expanded and the time spent is making |up at least 95%. This behavior is the default.
- |-Xenablestringconstantgc |
  |
  - Enables strings from the string intern table to be collected. By default, |this option is enabled.
- -Xfuture
  - Turns on strict class-file format checks. Use this flag when you are developing new code because stricter checks will become the default in future releases. By default, strict format checks are disabled.
- -Xgcpolicy:[optthruput]|[optavgpause]|[gencon]||[subpool] (subpool on PPC and zSeries)
  - Controls the behavior of the Garbage Collector.
    - The optthruput option is the default and delivers very high throughput to applications, but at the cost of occasional pauses.
    - The optavgpause option reduces the time that is spent in these garbage collection pauses and limits the effect of increasing heap size on the length of the garbage collection pause. Use optavgpause if your configuration has a very large heap.
    - The gencon option requests the combined use of concurrent and generational GC to help minimize the time that is spent in any garbage collection pause.
    - |The subpool option uses an improved object allocation algorithm to achieve better |performance when allocating objects on the heap. This option might improve |performance on large SMP systems.
    For more information, see Specifying garbage collection policy.
- -Xgcthreads<number of threads>
  - Sets the number of helper threads that are used for parallel operations during garbage collection. By default, the number of threads is set to the number of physical CPUs present -1, with a minimum of 1.
- |-Xgcworkpackets <number> |
  |
  - Specifies the total number of work packets available in the global collector. |If not specified, the collector allocates a number of packets based on the |maximum heap size.
- -Xint
  - Makes the JVM use only the Interpreter, disabling the Just-In-Time (JIT) compiler. By default, the JIT compiler is enabled.
- -Xiss<size>
  - Sets the initial Java thread stack size. 2 KB by default.
- -Xjit[:<suboption>,<suboption>,...]
  - Enables the JIT. For details of the suboptions, see the Diagnostics Guide. See also -Xnojit. By default, the JIT is enabled.
- -Xlinenumbers
  - Displays line numbers in stack traces, for debugging. See also -Xnolinenumbers. By default, line numbers are on.
- |-Xloa |
  |
  - Allocates a large object area (LOA). Objects will be allocated in this |LOA rather than the SOA. By default, the LOA is enabled for all GC policies |except for subpool, where the LOA is not available. See also -Xnoloa.
- |-Xloainitial <number> |
  |
  - <number> is between 0 and 0.95, which specifies the initial percentage |of the current tenure space allocated to the large object area (LOA). The |default is 0.05 or 5%.
- |-Xloamaximum <number> |
  |
  - <number> is between 0 and 0.95, which specifies the maximum percentage |of the current tenure space allocated to the large object area(LOA). The default |is 0.5 or 50%.
- -Xlp
  - Requests the JVM to allocate the Java heap with large pages. If large pages are not available, the JVM will not start, displaying the error message `GC: system configuration does not support option --> '-Xlp'`. The JVM uses shmget() to allocate large pages for the heap. Large pages are supported by systems running Linux kernels v2.6 or higher, or earlier kernels where large page support has been backported by the distribution. By default, large pages are not used. See Configuring large page memory allocation.
- -Xmaxe<size>
  - Sets the maximum amount by which the garbage collector expands the heap. Typically, the garbage collector expands the heap when the amount of free space falls below 30% (or the amount specified using -Xminf), by the amount required to restore the free space to 30%. The -Xmaxe option limits the expansion to the specified value; for example `-Xmaxe10M` limits the expansion to 10 MB. By default, there is no maximum expansion size.
- -Xmaxf<size>
  - Specifies the maximum percentage of heap that must be free after a garbage collection. If the free space exceeds this amount, the JVM attempts to shrink the heap. Specify the size as a decimal value in the range 0-1, for example `-Xmaxf0.5` sets the maximum free space to 50%. The default value is 0.6 (60%).
- -Xmca<size>
  - Sets the expansion step for the memory allocated to store the RAM portion of loaded classes. Each time more memory is required to store classes in RAM, the allocated memory is increased by this amount. By default, the expansion step is 32 KB.
- -Xmco<size>
  - Sets the expansion step for the memory allocated to store the ROM portion of loaded classes. Each time more memory is required to store classes in ROM, the allocated memory is increased by this amount. By default, the expansion step is 128 KB.
- -Xmine<size>
  - Sets the minimum amount by which the Garbage Collector expands the heap. Typically, the garbage collector expands the heap by the amount required to restore the free space to 30% (or the amount specified using -Xminf). The -Xmine option sets the expansion to be at least the specified value; for example, `-Xmine50M` sets the expansion size to a minimum of 50 MB. By default, the minimum expansion size is 1 MB.
- -Xminf<size>
  - Specifies the minimum percentage of heap that should be free after a garbage collection. If the free space falls below this amount, the JVM attempts to expand the heap. Specify the size as a decimal value in the range 0-1; for example, a value of `-Xminf0.3` requests the minimum free space to be 30% of the heap. By default, the minimum value is 0.3.
- -Xmn<size>
  - Sets the initial and maximum size of the new (nursery) heap to the specified value when using -Xgcpolicy:gencon. Equivalent to setting both -Xmns and -Xmnx. |If you set either -Xmns or -Xmnx, |you cannot set -Xmn. If you attempt to set -Xmn with either -Xmns or -Xmnx, the VM will not start, returning an error. By default, -Xmn is selected internally according to your system's capability. You can use the -verbose:sizes option to find out the values that the VM is currently using.
- -Xmns<size>
  - Sets the initial size of the new (nursery) heap to the specified value when using -Xgcpolicy:gencon. By default, this option is selected internally according to your system's capability. |This option will return an error if you try to use it with -Xmn.
- -Xmnx<size>
  - Sets the maximum size of the new (nursery) heap to the specified value when using -Xgcpolicy:gencon. By default, this option is selected internally according to your system's capability. |This option will return an error if you try to use it with -Xmn.
- -Xmo<size>
  - Sets the initial and maximum size of the old (tenured) heap to the specified value when using -Xgcpolicy:gencon. Equivalent to setting both -Xmos and -Xmox. |If you set either -Xmos or -Xmox, |you cannot set -Xmo. If you attempt to set -Xmo with either -Xmos or -Xmox, the VM will not start, returning an error. By default, -Xmo is selected internally according to your system's capability. You can use the -verbose:sizes option to find out the values that the VM is currently using.
- -Xmos<size>
  - Sets the initial size of the old (tenure) heap to the specified value when using -Xgcpolicy:gencon. By default, this option is selected internally according to your system's capability. |This option will return an error if you try to use it with -Xmo.
- -Xmox<size>
  - Sets the maximum size of the old (tenure) heap to the specified value when using -Xgcpolicy:gencon. By default, this option is selected internally according to your system's capability. |This option will return an error if you try to use it with -Xmo.
- -Xmoi<size>
  - Sets the amount the Java heap is incremented when using -Xgcpolicy:gencon. If set to zero, no expansion is allowed. By default, the increment size is calculated on the expansion size, -Xmine and -Xminf.
- -Xmr<size>
  - Sets the size of the Garbage Collection "remembered set" when using -Xgcpolicy:gencon. This is a list of objects in the old (tenured) heap that have references to objects in the new (nursery) heap. By default, this option is set to 16 kilobytes.
- -Xms<size>
  - Sets the initial Java heap size. You can also use -Xmo. The default is set internally according to your system's capability.
- -Xmso<size>
  - Sets the C stack size for forked Java threads. By default, this option is set to 32 KB on 32-bit platforms and 256 KB on 64-bit platforms.
- -Xmx<size>
  - Sets maximum Java heap size. By default, this option is set internally according to your system's capability.
- -Xnoclassgc
  - Disables class garbage collection. This option switches off garbage collection of storage associated with Java classes that are no longer being used by the JVM. The default behavior is -Xclassgc.
- -Xnocompactgc
  - Disables compaction for the Garbage Collector. See also -Xcompactgc. By default, compaction is enabled.
- -Xnocompactexplicitgc
  - Disables compaction on a call to `System.gc()`. See also -Xcompactexplicitgc. By default, compaction is enabled on calls to `System.gc()`.
- -Xnojit
  - Disables the JIT compiler. See also -Xjit. By default, the JIT compiler is enabled.
- -Xnolinenumbers
  - Disables the line numbers for debugging. See also -Xlinenumbers. By default, line number are on.
- |-Xnoloa |
  |
  - Prevents allocation of a large object area (LOA). All objects will be |allocated in the SOA. By default, the LOA is enabled for all GC policies except |for subpool, where the LOA is not available. See also -Xloa.
- -Xnopartialcompactgc
  - Disables incremental compaction. See also -Xpartialcompactgc. By default, this option is not set, so all compactions are full.
- -Xnosigcatch
  - Disables JVM signal handling code. See also -Xsigcatch. By default, signal handling is enabled.
- -Xnosigchain
  - Disables signal handler chaining. See also -Xsigchain. By default, the signal handler chaining is enabled.
- -Xoptionsfile=<file>
  - Specifies a file that contains JVM options and defines. By default, no option file is used.
- -Xoss<size>
  - Sets the Java stack size and C stack size for any thread. This option is provided for compatibility and is equivalent to setting both -Xss and -Xmso to the specified value.
- -Xpartialcompactgc
  - Enables partial compaction. See also -Xnopartialcompactgc.
- -Xquickstart
  - Improves startup time by delaying JIT compilation and optimisations. By default, quickstart is disabled and there is no delay in JIT compilation.
- -Xrdbginfo:<host>:<port>
  - Loads and passes options to the remote debug information server. By default, the remote debug information server is disabled.
- -Xrs
  - Reduces the use of operating system signals. By default, the VM makes full use of operating system signals, see Signals used by the JVM.
- -Xrun<library name>[:options]
  - Loads helper libraries. To load multiple libraries, specify it more than once on the command line. Examples of these libraries are:
    - -Xrunhprof[:help] | [:<option>=<value>, ...]
      - Performs heap, CPU, or monitor profiling. For more information, see the Diagnostics Guide.
    - -Xrunjdwp[:help] | [:<option>=<value>, ...]
      - Loads debugging libraries to support the remote debugging of applications. This is the same as -Xdbg. For more information, see Debugging Java applications.
    - -Xrunjnichk[:help] | [:<option>=<value>, ...]
      - Performs additional checks for JNI functions, to trace errors in native programs that access the JVM using JNI. For more information, see the Diagnostics Guide.
- |-Xscmx<size>[k|m|g] |
  |
  - For details of -Xscmx, see Using command-line options for class sharing.
- |-Xshareclasses:<suboptions> |
  |
  - For details of the -Xshareclasses suboptions, see Using command-line options for class sharing.
- -Xsigcatch
  - Enables VM signal handling code. See also -Xnosigcatch. By default, signal handling is enabled
- -Xsigchain
  - Enables signal handler chaining. See also -Xnosigchain. By default, signal handler chaining is enabled.
- |-Xsoftrefthreshold<number> |
  |
  - Sets the number of GCs after which a soft reference will be cleared if | its referent has not been marked. The default is 3, meaning that on the |third GC where the referent is not marked the soft reference will be cleared.
- -Xss<size>
  - Sets the maximum Java stack size for any thread. By default, this option is set to 256 KB. For more information, see Working with floating stacks.
- -Xthr:<options>
  - Sets the threading options.
- -Xverbosegclog:<path to file><filename>[X, Y]
  - Causes verboseGC output to be written to the specified file. If the file exists, it is overwritten. Otherwise, if an existing file cannot be opened or a new file cannot be created, the output is redirected to stderr. If you specify the arguments X and Y (both are integers) the verboseGC output is redirected to X number of files, each containing Y number of gc cycles worth of verboseGC output. These files have the form filename1, filename2, and so on. By default, no verbose garbage collection logging occurs.
- -Xverify
  - Enables strict class checking for every class that is loaded. By default, strict class checking is disabled.
- -Xverify:none
  - Disables strict class checking. By default, strict class checking is disabled.

## Obtaining the IBM build and version number

To obtain the IBM build and version number, at a shell prompt type:

    java -version

## Globalization of the java command

The java command and other java launcher commands (such as javaw) allow a class name to be specified as any character that is in the character set of the current locale.

You can also specify any Unicode character in the class name and arguments by using Java escape sequences. To do this, you must specify -Xargencoding. To specify a Unicode character, use escape sequences in the form `\u####`, where # is a hexadecimal digit (0 through 9, A through F).

Alternatively, to specify that the class name and command arguments are in UTF8 encoding, use -Xargencoding:utf8, or in ISO8859_1 encoding use -Xargencoding:latin.

For instance, to specify a class called "HelloWorld" using Unicode encoding for both capital letters, use this command:

    java -Xargencoding '\u0048ello\u0057orld'

The java and javaw commands give translated output messages. These messages differ based on the locale in which Java is running. The detailed error descriptions and other debug information that is returned by java are in English.

## The Just-In-Time (JIT) compiler

The IBM Just-In-Time (JIT) compiler dynamically generates machine code for frequently used bytecode sequences in Java applications and applets during their execution. |The JIT V5.0 compiler delivers new optimizations |as a result of compiler research, improves optimizations implemented in previous |versions of the JIT, and provides better hardware exploitation.

The IBM SDK and Runtime Environment include the JIT, which is enabled by default in user applications as well as SDK tools. Normally, there is no need to invoke the JIT explicitly; the compilation of Java bytecode to machine code occurs transparently. However, if you encounter a problem with the Runtime Environment while executing a Java application or an applet, you can disable the JIT to help isolate the problem. Disabling the JIT should be a temporary measure only; the JIT is required for adequate performance.

### Disabling the JIT

There are three ways to disable the JIT:

- Set the JAVA_COMPILER environment variable to "NONE" or the empty string before running the Java application.

  Type the following at a command prompt:

  1. For the Korn shell:

     -     export JAVA_COMPILER=NONE

       (Korn shell commands are used for the remainder of this User Guide.)

  2. For the Bourne shell:

     -     JAVA_COMPILER=NONE

     -     export JAVA_COMPILER

  3. For the C shell:

     -     setenv JAVA_COMPILER NONE

- Use the -D option on the JVM command line to set the java.compiler property to "NONE" or the empty string:

      java -Djava.compiler=NONE MyApp

- Use the -Xint option on the JVM command line. For example:

      java -Xint MyApp

Both command-line options override the JAVA_COMPILER environment variable.

### Enabling the JIT

To enable the JIT explicitly, set the JAVA_COMPILER environment variable to "jitc", or use the -D option to set the java.compiler property to "jitc". Alternatively, use the -Xjit option (and omit the -Xint option) on the JVM command line to turn on the JIT.

If the JAVA_COMPILER environment variable or the java.compiler property is set to "" (the empty string), the JIT remains disabled. To unset the environment variable properly, type `unset JAVA_COMPILER` at the shell prompt.

### Determining whether the JIT is enabled

To determine whether the JIT is enabled, type the following at a command prompt:

    java -version

If the JIT is not in use, a message is displayed that includes the following:

    (JIT disabled)

If the JIT is in use, a message is displayed that includes the following:

    (JIT enabled)

For more information about the JIT, see the Diagnostics Guide.

## Specifying garbage collection policy

The Garbage Collector manages the memory used by Java and by applications running within the VM.

When the Garbage Collector receives a request for storage, unused memory in the heap is set aside - "allocation". The Garbage Collector also checks for areas of memory are no longer referenced, and releases them for reuse - "collection".

The collection phase can be triggered by a memory allocation fault, which occurs when no space is left for a storage request, or by an explicit System.gc() call.

Garbage collection can significantly affect application performance, so the IBM virtual machine provides various methods of optimising the way garbage collection is carried out, thus reducing the effect on your application.

For more detailed information on garbage collection, see the Diagnostics Guide.

### Garbage collection options

The -Xgcpolicy option controls garbage collector behavior, making tradeoffs between throughput of the application and overall system and the pause times that are caused by garbage collection.

The format of the option and its values is:

> -Xgcpolicy:optthruput (Default and recommended value)

> -Xgcpolicy:optavgpause

> -Xgcpolicy:gencon

|

> -Xgcpolicy:subpool (PPC and zSeries only)

### Pause time

When an application's attempt to create an object cannot be satisfied immediately from the available space in the heap, the garbage collector is responsible for identifying unreferenced objects (garbage), deleting them, and returning the heap to a state in which the immediate and subsequent allocation requests can be satisfied quickly. Such garbage collection cycles introduce occasional unexpected pauses in the execution of application code. Because applications grow in size and complexity, and heaps become correspondingly larger, this garbage collection pause time tends to grow in size and significance. The default garbage collection value, -Xgcpolicy:optthruput, delivers very high throughput to applications, but at the cost of these occasional pauses, which can vary from a few milliseconds to many seconds, depending on the size of the heap and the quantity of garbage.

### Pause time reduction

The JVM uses two techniques to reduce pause times:

- Concurrent garbage collection
- Generational garbage collection

The -Xgcpolicy:optavgpause command-line option requests the use of concurrent garbage collection to reduce significantly the time that is spent in garbage collection pauses. Concurrent GC reduces the pause time by performing some garbage collection activities concurrently with normal program execution to minimize the disruption caused by the collection of the heap. The -Xgcpolicy:optavgpause option also limits the effect of increasing the heap size on the length of the garbage collection pause. The -Xgcpolicy:optavgpause option is most useful for configurations that have large heaps. With the reduced pause time, you might experience some reduction of throughput to your applications.

During concurrent garbage collection a significant amount of time is wasted identifying relatively long-lasting objects that cannot then be collected. If the GC concentrates on just those objects that are most likely to be recyclable, you can further reduce pause times for some applications. Generational GC achieves this by dividing the heap into two "generations", the "nursery" and the "tenure" areas. Objects are placed in one of these areas depending on their age. The nursery is the smaller of the two and contains younger objects; the tenure is larger and contains older objects. Objects are first allocated to the nursery; if they survive long enough they are promoted to the tenure area eventually.

Generational GC depends on most objects not lasting long. Generational GC reduces pause times by concentrating the effort to reclaim storage on the nursery because it has the most recyclable space. Rather than occasional but lengthy pause times to collect the entire heap, the nursery is collected more frequently and, if the nursery is small enough, pause times are comparatively short. However, generational GC has the drawback that, over time, the tenure area might become full if too many objects last too long. To minimize the pause time when this situation occurs, use a combination of concurrent GC and generational GC. The -Xgcpolicy:gencon option requests the combined use of concurrent and generational GC to help minimize the time that is spent in any garbage collection pause.

### Environments with very full heaps

If the Java heap becomes nearly full, and very little garbage is to be reclaimed, requests for new objects might not be satisfied quickly because no space is immediately available. If the heap is operated at near-full capacity, application performance might suffer regardless of which of the above options is used; and, if requests for more heap space continue to be made, the application receives an OutOfMemoryError, which results in JVM termination if the exception is not caught and handled. At this point the JVM produces a "javadump" diagnostic file. In these conditions, you are recommended either to increase the heap size by using the -Xmx option, or to reduce the number of application objects in use. For more information, see the Diagnostics Guide.

## How the JVM processes signals

When a signal is raised that is of interest to the JVM, a signal handler is called. This signal handler determines whether it has been called for a Java or non-Java thread.

If the signal is for a Java thread, the JVM takes control of the signal handling. If an application handler for this signal is installed and you did not specify the -Xnosigchain command-line option, the application handler for this signal is called after the JVM has finished processing.

If the signal is for a non-Java thread, and the application that installed the JVM had previously installed its own handler for the signal, control is given to that handler. Otherwise, if the signal is requested by the JVM or Java application, the signal is ignored or the default action is taken.

For exception and error signals, the JVM either:

- Handles the condition and recovers, or
- Enters a controlled shutdown sequence where it:
  1. Outputs a Javadump, to describe the JVM state at the point of failure
  2. Calls your application's signal handler for that signal
  3. Calls any application-installed abort hook
  4. Performs the necessary cleanup to give a clean shutdown

For information about writing a launcher that specifies the above hooks, see: http://www-106.ibm.com/developerworks/java/library/i-signalhandling/. This item was written for Java V1.3.1, but still applies to later versions.

For interrupt signals, the JVM also enters a controlled shutdown sequence, but this time it is treated as a normal termination that:

- Calls your application's signal handler for that signal
- Runs all application shutdown hooks
- Calls any application-installed exit hook
- Performs the necessary JVM cleanup

The shutdown is identical to the shutdown initiated by a call to the Java method `System.exit()`.

Other signals that are used by the JVM are for internal control purposes and do not cause it to terminate. The only control signal of interest is SIGQUIT, which causes a Javadump to be generated.

### Signals used by the JVM

Table 1 below shows the signals that are used by the JVM. The signals are grouped in the table by type or use, as follows:

- Exceptions: The operating system synchronously raises an appropriate exception signal whenever a fatal condition occurs.
- Errors: The JVM raises a SIGABRT if it detects a condition from which it cannot recover.
- Interrupts: Interrupt signals are raised asynchronously, from outside a JVM process, to request shutdown.
- Controls: Other signals that are used by the JVM for control purposes.

Table 1. Signals used by the JVM
Signal Name | Signal type | Description | Disabled by -Xrs
--- | --- | --- | ---
SIGBUS (7) | Exception | Incorrect access to memory (data misalignment) | Yes
SIGSEGV (11) | Exception | Incorrect access to memory (write to inaccessible memory) | Yes
SIGILL (4) | Exception | Illegal instruction (attempt to invoke an unknown machine instruction) | No
SIGFPE (8) | Exception | Floating point exception (divide by zero) | Yes
SIGABRT | Error | Abnormal termination. The JVM raises this signal whenever it detects a JVM fault. | Yes
SIGINT (2) | Interrupt | Interactive attention (CTRL-C). JVM exits normally. | Yes
SIGTERM (15) | Interrupt | Termination request. JVM will exit normally. | Yes
SIGHUP (1) | Interrupt | Hang up. JVM exits normally. | Yes
SIGQUIT | Control | A quit signal for a terminal. JVM uses this for taking Javadumps. | Yes
|SIGTRAP (5) | |Control | |Used by the JIT. | |Yes
|__SIGRTMAX - 2 | |Control | |Used by the SDK. | |No
|SIGCHLD | |Control | |Used by the SDK for internal control. | |No

Use the -Xrs (reduce signal usage) option to prevent the JVM from handling most signals. For more information, see Sun's Java application launcher page.

Signals `1 (SIGHUP)`, `2 (SIGINT)`, `4 (SIGILL)`, `7 (SIGBUS)`, `8 (SIGFPE)`, `11 (SIGSEGV)`, and `15 (SIGTERM)` on JVM threads cause the JVM to shut down; therefore, an application signal handler should not attempt to recover from these unless it no longer requires the JVM.

### Linking a native code driver to the signal-chaining library

The Runtime Environment contains signal-chaining. Signal-chaining enables the JVM to interoperate more efficiently with native code that installs its own signal handlers.

Signal-chaining enables an application to link and load the shared library libjsig.so before the system libraries. The libjsig.so library ensures that calls such as `signal()`, `sigset()`, and `sigaction()` are intercepted so that their handlers do not replace the JVM's signal handlers. Instead, these calls save the new signal handlers, or "chain" them behind the handlers that are installed by the JVM. Later, when any of these signals are raised and found not to be targeted at the JVM, the preinstalled handlers are invoked.

To use libjsig.so:

- Link it with the application that creates or embeds a JVM:

      gcc -L$JAVA_HOME/bin -ljsig -L$JAVA_HOME/bin/j9vm -ljvm java_application.c

  or
- Use the LD_PRELOAD environment variable:

      export LD_PRELOAD=$JAVA_HOME/bin/libjsig.so; java_application (bash and ksh)

      setenv LD_PRELOAD=$JAVA_HOME/bin/libjsig.so; java_application (csh)

  (Assuming that `JAVA_HOME` is set up; otherwise, use /opt/ibm/java2-i386-50/jre.)

If you install signal handlers that use `sigaction()` , some sa_flags are not observed when the JVM uses the signal. These are:

- SA_NOCLDSTOP - This is always unset.
- SA_NOCLDWAIT - This is always unset.
- SA_RESTART - This is always set.

The libjsig.so library also hides JVM signal handlers from the application. Therefore, calls such as `signal()`, `sigset()`, and `sigaction()` that are made after the JVM has started no longer return a reference to the JVM's signal handler, but instead return any handler that was installed before JVM startup.

## Working with floating stacks

Particular Linux distributions - Red Hat, for example - have enabled a GLIBC feature called 'floating stacks'. Because of Linux kernel limitations, the JVM does not run on SMP hardware with floating stacks enabled if the kernel level is less than 2.4.10. In this environment, floating stacks must be disabled before the JVM, or any application that starts the JVM, is started. On Red Hat, use this command to disable floating stacks by exporting an environment variable:

    export LD_ASSUME_KERNEL=2.2.5

On a nonfloating stack Linux system, regardless of what is set for -Xss, a minimum native stack size of 256 KB for each thread is provided. On a floating stack Linux system, the -Xss values are honored. Therefore, if you are migrating from a non-floating stack Linux system, you must ensure that any -Xss values are large enough and are not relying on a minimum of 256 KB.

## Transforming XML documents

The IBM SDK contains the XSLT4J processor and the XML4J parser that conform to the JAXP 1.3 specification. These tools allow you to parse and transform XML documents independently from any given XML processing implementation. By using "Factory Finders" to locate the SAXParserFactory, DocumentBuilderFactory and TransformerFactory implementations, your application can swap between different implementations without having to change any code.

|The XML technology included with the IBM SDK is similar to |Apache Xerces Java and Apache Xalan Java. See http://xml.apache.org/xerces2-j/ and http://xml.apache.org/xalan-j/ for more information.

The XSLT4J processor allows you to choose between the original XSLT Interpretive processor or the new XSLT Compiling processor. The Interpretive processor is designed for tooling and debugging environments and supports the XSLT extension functions that are not supported by the XSLT Compiling processor. The XSLT Compiling processor is designed for high performance runtime environments; it generates a transformation engine, or translet, from an XSL style sheet. This approach separates the interpretation of style sheet instructions from their runtime application to XML data.

The XSLT Interpretive processor is the default processor. To select the XSLT Compiling processor, you can either:

- Change the entry in the jaxp.properties file (located in /opt/ibm/java2-i386-50/jre/lib).
- Set the system property for the javax.xml.transform.TransformerFactory key to org.apache.xalan.xsltc.trax.TransformerFactoryImpl.

To implement properties in the jaxp.properties file, copy jaxp.properties.sample to jaxp.properties in /opt/ibm/java2-i386-50/jre/lib. This file also contains full details about the procedure used to determine which implementations to use for the TransformerFactory, SAXParserFactory, and the DocumentBuilderFactory.

To improve the performance when you transform a StreamSource object with the XSLT Compiling processor, specify the com.ibm.xslt4j.b2b2dtm.XSLTCB2BDTMManager class as the provider of the service org.apache.xalan.xsltc.dom.XSLTCDTMManager. To determine the service provider, try each step until you find org.apache.xalan.xsltc.dom.XSLTCDTMManager:

1. Check the setting of the system property org.apache.xalan.xsltc.dom.XSLTCDTMManager.
2. Check the value of the property org.apache.xalan.xsltc.dom.XSLTCDTMManager in the file /opt/ibm/java2-i386-50/jre/lib/xalan.properties.
3. Check the contents of the file META-INF/services/org.apache.xalan.xsltc.dom.XSLTCDTMManager for a class name.
4. Use the default service provider, org.apache.xalan.xsltc.dom.XSLTCDTMManager.

The XSLT Compiling processor detects the service provider for the org.apache.xalan.xsltc.dom.XSLTCDTMManager service when a javax.xml.transform.TransformerFactory object is created. Any javax.xml.transform.Transformer or javax.xml.transform.sax.TransformerHandler objects that are created by using that TransformerFactory object will use the same service provider. You can change service providers by modifying one of the settings described above and then creating a new TransformerFactory object.

### Using an older version of Xerces or Xalan

If you are using an older version of Tomcat, this limitation might apply.

If you are using an older version of Xerces (prior to 2.0) or Xalan (prior to 2.3) in the endorsed override, you might get a null pointer exception when you launch your application. This exception occurs because these older versions do not handle the jaxp.properties file correctly.

To avoid this situation, use one of the following workarounds:

- Upgrade to a newer version of the application that implements the latest Java API for XML Programming (JAXP) specification (http://java.sun.com/xml/jaxp/index.html).
- Remove the jaxp.properties file from /opt/ibm/java2-i386-50/jre/lib.
- Uncomment the entries in the jaxp.properties file in /opt/ibm/java2-i386-50/jre/lib.
- Explicitly set the SAX Parser, DocumentBuilder, or Transformer factory using the IBM_JAVA_OPTIONS environment variable. For example:

      export IBM_JAVA_OPTIONS=-Djavax.xml.parsers.SAXParserFactory=
        org.apache.xerces.jaxp.SAXParserFactoryImpl

  or

      export IBM_JAVA_OPTIONS=-Djavax.xml.parsers.DocumentBuilderFactory=
        org.apache.xerces.jaxp.DocumentBuilderFactoryImpl

  or

      export IBM_JAVA_OPTIONS=-Djavax.xml.transform.TransformerFactory=
        org.apache.xalan.processor.TransformerFactoryImpl

- Set the system property for javax.xml.parsers.SAXParserFactory, javax.xml.parsers.DocumentBuilderFactory, or javax.xml.transform.TransformerFactory from within your application's code. For an example, see the JAXP 1.3 specification.

# Using the SDK to develop Java applications

The following sections give information about using the SDK for Linux to develop Java applications. See SDK tools for details of the tools available.

## Debugging Java applications

To debug Java programs, you can use the Java Debugger (JDB) application or other debuggers that communicate by using the Java Platform Debugger Architecture (JPDA) that is provided by the SDK for Linux.

More information on problem diagnosis using Java can be found in the IBM Java Diagnostics Guide.

### Java Debugger (JDB)

The Java Debugger (JDB) is included in the SDK for Linux. The debugger is invoked by the jdb command; it "attaches" to the JVM using JPDA. To debug a Java application:

1. Start the JVM with the following options:

       java -Xdebug -Xrunjdwp:transport=dt_socket,server=y,address=<port>
            MyApp <MyApp args>

2. The JVM starts up, but suspends execution before it starts the Java application. In a separate session, you can attach the debugger to the JVM:

       jdb -attach <port number>

   The debugger will attach to the JVM, and you can now issue a range of commands to examine and control the Java application; for example, type `run` to allow the Java application to execute.

To find out more about JDB options, type:

    jdb -help

To find out more about JDB commands:

1. Type `jdb`
2. At the jdb prompt, type `help`

You can also use JDB to debug Java applications running on remote machines. JPDA uses a TCP/IP socket to connect to the remote JVM.

1. Start the JVM as before.
2. Attach the debugger to the remote machine:

       jdb -attach <machine name or ip address>:<port number>

When you launch a debug session using the dt_socket transport, be sure that the specified ports are free to use.

|The Java Virtual Machine Debugging Interface (JVMDI) is not supported in this release. It has been replaced by |the Java Virtual Machine Tool Interface (JVMTI).

For more information on JDB and JPDA and their usage, see these Web sites:

- http://java.sun.com/products/jpda/
- http://java.sun.com/j2se/1.5.0/docs/guide/jpda/
- http://java.sun.com/j2se/1.5.0/docs/guide/jpda/jdb.html

## Determining whether your application is running on a 32-bit or 64-bit JVM

Some Java applications must be able to determine whether they are running on a 32-bit JVM or on a 64-bit JVM. For example, if your application has a native code library, the library must be compiled separately in 32- and 64-bit forms for platforms that support both 32- and 64-bit modes of operation. In this case, your application must load the correct library at runtime, because it is not possible to mix 32- and 64-bit code.

The system property com.ibm.vm.bitmode allows applications to determine the mode in which your JVM is running. It returns the following values:

- 32 - the JVM is running in 32-bit mode
- 64 - the JVM is running in 64-bit mode

You can inspect the com.ibm.vm.bitmode from within your application code using the call:

    System.getProperty("com.ibm.vm.bitmode");

## Writing JNI applications

Valid JNI version numbers that native programs can specify on the JNI_CreateJavaVM() API call are:

- JNI_VERSION_1_2(0x00010002)
- JNI_VERSION_1_4(0x00010004)

This version number determines only the level of the JNI native interface to use. The actual level of the JVM that is created is specified by the J2SE libraries (that is, v5.0). The JNI interface API does not affect the language specification that is implemented by the JVM, the class library APIs, or any other area of JVM behavior. For more information, see http://java.sun.com/j2se/1.5.0/docs/guide/jni.

If your application needs two JNI libraries, one built for 32- and the other for 64-bit, use the com.ibm.vm.bitmode system property to determine if you are running with a 32- or 64-bit JVM and choose the appropriate library.

To compile and link a native application with the IBM 5.0 SDK, use the following command:

    gcc -I/opt/ibm/java2-i386-50/include -L/opt/ibm/java2-i386-50/jre/bin/j9vm
    -ljvm -ldl -lpthread <JNI program filename>

The -ljvm option specifies that libjvm.so is the shared library that implements the JVM. The -lpthread option indicates that you are using native pthread support; if you do not link with the pthread library, a segmentation fault (signal SIGSEGV) might be caused when you run the JNI program.

Note:
Version 1.1 of the Java Native Interface (JNI) is not supported.
| | |

## Support for thread-level recovery of blocked connectors

|

Four new IBM-specific SDK classes have been added to the com.ibm.jvm package |to support the thread-level recovery of blocked connectors. The new classes |are packaged in core.jar.

|

These classes allow you to unblock threads that have become blocked on |networking or synchronisation calls. If an application does not use these |classes, it must end the whole process, rather than interrupting an individual |blocked thread.

|

The classes are:

|

|
public Interface InterruptibleContext()
|
  Defines two methods, isblocked() and unblock(). The other three classes |implement InterruptibleContext. |
|
public class InterruptibleLockContext()
|
  Is a utility class for interrupting synchronization calls. |
|
public class InterruptibleIOContext()
|
  Is a utility class for interrupting network calls. |
|
public class InterruptibleThread()
|
  Is a utility class that extends java.lang.Thread, to allow wrapping |of interruptible runnable methods. It uses instances of InterruptibleLockContext |and InterruptibleIOContext to perform the required isblocked() and unblock() |methods depending on whether a synchronization or networking operation is |blocking the thread. |
|

|

Both InterruptibleLockContext and InterruptibleIOContext work by referencing |the current thread. Therefore if you do not use InterruptibleThread, you must |provide your own class that extends java.lang.Thread, to use these new classes.

|

The Javadoc for these classes is provided with the SDK in the file docs/apidoc.zip.

## Working with applets

With the Applet Viewer, you can run one or more applets that are called by reference in a Web page (HTML file) by using the APPLET tag. The Applet Viewer finds the APPLET tags in the HTML file and runs the applets, in separate windows, as specified by the tags.

Because the Applet Viewer is for viewing applets, it cannot display a whole Web page that contains many HTML tags. It parses only the APPLET tags and no other HTML on the Web page.

### Running applets with the Applet Viewer

To run an applet with the Applet Viewer, type the following at a shell prompt:

       appletviewer name

where name is one of the following:

- The file name of an HTML file that calls an applet
- The URL of a Web page that calls an applet

For example, to invoke the Applet Viewer on an HTML file that calls an applet, type at a shell prompt:

      appletviewer $HOME/filename.html

where filename is the name of the HTML file.

For example, `http://java.sun.com/applets/NervousText/example1.html` is the URL of a Web page that calls an applet. To invoke the Applet Viewer on this Web page, type at a shell prompt:

    appletviewer http://java.sun.com/applets/NervousText/example1.html

The Applet Viewer does not recognize the charset option of the <META> tag. If the file that the Applet Viewer loads is not encoded as the system default, an I/O exception might occur. To avoid the exception, use the -encoding option when you run appletviewer. For example:

    appletviewer -encoding JISAutoDetect sample.html

### Debugging applets with the Applet Viewer

You can debug applets by using the -debug option of the Applet Viewer. When debugging applets, you are advised to invoke the Applet Viewer from the directory that contains the HTML file that calls the applet. For example:

    cd demo/applets/TicTacToe
    ../../bin/appletviewer -debug example1.html

You can find documentation about how to debug applets using the Applet Viewer at the Sun Web site: http://java.sun.com.

| | |

## Configuring large page memory allocation

|

You can enable large page support, on systems that support it, by starting |Java with the -Xlp option.

|

Large page usage is primarily intended to provide performance improvements |to applications that allocate a lot of memory and frequently access that memory. |The large page performance improvements are mainly caused by the reduced number |of misses in the Translation Lookaside Buffer (TLB). The TLB maps a larger |virtual memory range and thus causes this improvement.

|

Large page support must be available in the kernel, and enabled, |to allow Java to use large pages.

|

To configure large page memory allocation, first ensure that |the running kernel supports large pages. Check that the file /proc/meminfo |contains the following lines:

|

    HugePages_Total:     <number of pages>
    |HugePages_Free:      <number of pages>
    |Hugepagesize:        <page size, in kB>

The number of pages available |and their sizes vary between distributions.

|

If large page support is not available in your kernel, these |lines will not exist in the /proc/meminfo file. In this case, you must install |a new kernel containing support for large pages.

|

If large page support is available, but not enabled, `HugePages_Total` will be 0. In this case, your administrator must enable |large page support. Check your operating system manual for more instructions.

|

For the JVM to use large pages, your system must have an adequate number |of contiguous large pages available. If large pages cannot be allocated, even |when enough pages are available, possibly the large pages are not contiguous. Configuring the number of large pages at bootup will create |them contiguously.

|

Large page allocations will only succeed if the JVM has root |access. To use large pages, either run Java as root or set the suid bit of |the Java executable.

## CORBA support

The Java 2 Platform, Standard Edition (J2SE) supports, at a minimum, the specifications that are defined in the Official Specifications for CORBA support in J2SE (V1.5). In some cases, the IBM J2SE ORB supports more recent versions of the specifications.

### Support for GIOP 1.2

This SDK supports all versions of GIOP, as defined by chapters 13 and 15 of the CORBA 2.3.1 specification, OMG document formal/99-10-07, which you can obtain from:

http://www.omg.org/cgi-bin/doc?formal/99-10-07

Bidirectional GIOP is not supported.

### Support for Portable Interceptors

This SDK supports Portable Interceptors, as defined by the OMG in the document ptc/01-03-04, which you can obtain from:

http://www.omg.org/cgi-bin/doc?ptc/01-03-04

Portable Interceptors are hooks into the ORB through which ORB services can intercept the normal flow of execution of the ORB.

### Support for Interoperable Naming Service

This SDK supports the Interoperable Naming Service, as defined by the OMG in the document ptc/00-08-07, which you can obtain from:

http://www.omg.org/cgi-bin/doc?ptc/00-08-07

The default port that is used by the Transient Name Server (the `tnameserv` command), when no ORBInitialPort parameter is given, has changed from 900 to 2809, which is the port number that is registered with the IANA (Internet Assigned Number Authority) for a CORBA Naming Service. Programs that depend on this default might have to be updated to work with this version.

The initial context that is returned from the Transient Name Server is now an `org.omg.CosNaming.NamingContextExt`. Existing programs that narrow the reference to a context `org.omg.CosNaming.NamingContext` still work, and do not need to be recompiled.

The ORB supports the -ORBInitRef and -ORBDefaultInitRef parameters that are defined by the Interoperable Naming Service specification, and the ORB::string_to_object operation now supports the ObjectURL string formats (corbaloc: and corbaname:) that are defined by the Interoperable Naming Service specification.

The OMG specifies a method ORB::register_initial_reference to register a service with the Interoperable Naming Service. However, this method is not available in the Sun Java Core API at Version 5.0. Programs that need to register a service in the current version must invoke this method on the IBM internal ORB implementation class. For example, to register a service "MyService":

    ((com.ibm.CORBA.iiop.ORB)orb).register_initial_reference("MyService",
    serviceRef);

where `orb` is an instance of `org.omg.CORBA.ORB`, which is returned from `ORB.init()`, and `serviceRef` is a CORBA Object, which is connected to the ORB. This mechanism is an interim one, and is not compatible with future versions or portable to non-IBM ORBs.

### System properties for tracing the ORB

A runtime debug feature provides improved serviceability. You might find it useful for problem diagnosis or it might be requested by IBM service personnel. Tracing is controlled by three system properties.

- To turn on tracing, set `com.ibm.CORBA.Debug=true`.
- To format and add to the trace GIOP messages sent and received, set `com.ibm.CORBA.CommTrace=true`. By default, ORB tracing goes to files that have names of the form orbtrc.DDMMYYYY.HHmm.SS.txt.
- To send it to a different file, set `com.ibm.CORBA.Debug.Output=<filename>`.

For example, to trace events and formatted GIOP messages, type:

     java -Dcom.ibm.CORBA.Debug=true
    		-Dcom.ibm.CORBA.CommTrace=true myapp

Do not turn on tracing for normal operation, because it might cause performance degradation. Even if you have switched off tracing, FFDC (First Failure Data Capture) is still working, so that only serious errors are reported. If a debug output file is generated, examine it to check on the problem. For example, the server might have stopped without performing an ORB.shutdown().

The content and format of the trace output might vary from version to version.

### System properties for tuning the ORB

The following properties help you to tune the ORB:

- To control GIOP 1.2 fragmentation, set the system property com.ibm.CORBA.FragmentSize.

  For example, to set the fragment size to 4096 bytes:

      java -Dcom.ibm.CORBA.FragmentSize=4096 myapp

  The default fragment size is 1024 bytes. You can turn off fragmentation by setting the fragment size to 0.

- In a heterogeneous network, the response to a CORBA Request might be delayed or lost. You can set the maximum time to wait by using the system property com.ibm.CORBA.RequestTimeout. Also, you can use com.ibm.CORBA.LocateRequestTimeout to control the timeout for LocateRequests. For example, to restrict both delays to 30 seconds, type:

      java -Dcom.ibm.CORBA.RequestTimeout=30
           -Dcom.ibm.CORBA.LocateRequestTimeout=30 myapp

  By default, the ORB waits indefinitely for a response. Do not set the timeout too low to avoid connections ending unnecessarily.

- If your program is providing a service in the network, you might have to set, to a well-known value, the number of the port from which the ORB reads incoming requests. You can control this by using the system property com.ibm.CORBA.ListenerPort.

  For example, to make the ORB use port 1050, type:

      java -Dcom.ibm.CORBA.ListenerPort=1050 myapp

  If this property is set, the ORB starts listening as soon as it is initialized. Otherwise, it starts listening only when required.

### Java 2 security permissions for the ORB

When running with a Java 2 SecurityManager, invocation of some methods in the CORBA API classes might cause permission checks to be made, which might result in a SecurityException. Affected methods include the following:

Table 2. Methods affected when running with Java 2 SecurityManager
Class/Interface | Method | Required permission
--- | --- | ---
org.omg.CORBA.ORB | init | java.net.SocketPermission resolve
org.omg.CORBA.ORB | connect | java.net.SocketPermission listen
org.omg.CORBA.ORB | resolve_initial_references | java.net.SocketPermission connect
org.omg.CORBA. portable.ObjectImpl | _is_a | java.net.SocketPermission connect
org.omg.CORBA. portable.ObjectImpl | _non_existent | java.net.SocketPermission connect
org.omg.CORBA. portable.ObjectImpl | OutputStream _request (String, boolean) | java.net.SocketPermission connect
org.omg.CORBA. portable.ObjectImpl | _get_interface_def | java.net.SocketPermission connect
org.omg.CORBA. Request | invoke | java.net.SocketPermission connect
org.omg.CORBA. Request | send_deferred | java.net.SocketPermission connect
org.omg.CORBA. Request | send_oneway | java.net.SocketPermission connect
javax.rmi. PortableRemoteObject | narrow | java.net.SocketPermission connect

If your program uses any of these methods, ensure that it is granted the necessary permissions.

### ORB implementation classes

The ORB implementation classes in this release are:

- org.omg.CORBA.ORBClass=com.ibm.CORBA.iiop.ORB
- org.omg.CORBA.ORBSingletonClass=com.ibm.rmi.corba.ORBSingleton
- javax.rmi.CORBA.UtilClass=com.ibm.CORBA.iiop.UtilDelegateImpl
- javax.rmi.CORBA.StubClass=com.ibm.rmi.javax.rmi.CORBA.StubDelegateImpl
- javax.rmi.CORBA.PortableRemoteObjectClass= com.ibm.rmi.javax.rmi.PortableRemoteObject

These are the default values, and you are advised not to set these properties or refer to the implementation classes directly. For portability, make references only to the CORBA API classes, and not to the implementation. These values might be changed in future releases.

## RMI over IIOP

Java Remote Method Invocation (RMI) provides a simple mechanism for distributed Java programming. RMI over IIOP (RMI-IIOP) uses the Common Object Request Broker Architecture (CORBA) standard Internet Inter-ORB Protocol (IIOP protocol) to extend the base Java RMI to perform communication. This allows direct interaction with any other CORBA Object Request Brokers (ORBs), whether they were implemented in Java or another programming language.

The following documentation is available:

- The RMI-IIOP Programmer's Guide is an introduction to writing RMI-IIOP programs. The guide is installed when you install this documentation.
- The demo directory contains:
  - A "Hello World" example that can switch between the Java Remote Method Protocol (JRMP) and IIOP protocols (demo/rmi-iiop/hello)
  - A "Hello World" example that interacts with a standard IDL program (demo/rmi-iiop/idl)
- The Java Language to IDL Mapping document is a detailed technical specification of RMI-IIOP and can be found at:
  http://www.omg.org/cgi-bin/doc?ptc/00-01-06.pdf

## Implementing the Connection Handler Pool for RMI

Thread pooling for RMI Connection Handlers is not enabled by default.

To enable the connection pooling implemented at the RMI TCPTransport level, set the option

    -Dsun.rmi.transport.tcp.connectionPool=true (or any non-null value)

This version of the Runtime Environment does not have any setting that you can use to limit the number of threads in the connection pool.

For more information, see the Sun Java site: http://java.sun.com.

## Enhanced BigDecimal

| |

From Java 5.0, the IBM BigDecimal class has been adopted by Sun as java.math.BigDecimal. | IBM no longer maintains com.ibm.math.BigDecimal and it is flagged as deprecated. | You are recommended to migrate existing Java code to use java.math.BigDecimal.

|

The new java.math.BigDecimal uses the same methods as both the previous |java.math.BigDecimal and com.ibm.math.BigDecimal. Existing code using java.math.BigDecimal |continues to work correctly.

|

To migrate existing Java code to use the java.math.BigDecimal class, change |the import statement at the top of your java file from: `import com.ibm.math.*;` to `import java.math,*;`.

## Euro symbol support

The IBM SDK and Runtime Environment set the Euro as the default currency for those countries in the European Monetary Union (EMU) for dates on or after 1 January, 2002.

To use the old national currency, specify `-Duser.variant=PREEURO` on the Java command line.

If you are running the UK, Danish, or Swedish locales and want to use the Euro, specify `-Duser.variant=EURO` on the Java command line.

# Using the Java Communications API (JavaComm)

The Java Communications application programming interface (API) package (JavaComm) is an optional package provided for use with the Runtime Environment for Linux on the IA32, PPC32/PPC64, and AMD64/EM64T platforms. You install JavaComm independently of the SDK or Runtime Environment.

The JavaComm API gives Java applications a platform-independent way of performing serial and parallel port communications for technologies such as voice mail, fax, and smartcards. After writing serial or parallel port communications for your application, you can then include those files with your application.

The Java Communications API supports Electronic Industries Association (EIA)-232 (RS232) serial ports and Institute of Electrical and Electronics Engineers (IEEE) 1284 parallel ports and is supported on systems with the IBM Version 5.0 Runtime Environment.

Using Java Communications API, you can:

- List ports on a system
- Open and claim ownership of ports
- Resolve port ownership contention among applications that use Java Communications API
- Perform asynchronous and synchronous I/O port-monitoring through event notification
- Receive bean-style events describing state changes on the port

## Installing Java Communications API

You should make sure that a copy of the SDK or Runtime Environment is installed before you install the Java Communications API.

If you used the RPM package to install Java originally, install the Java Communications API from the RPM file. To install the Java Communications API from an RPM package:

1. Open a shell prompt, making sure you are root.
2. Using the `rpm -ivh` command, install the Java Communications API RPM file. For example:

       rpm -ivh ibm-java2-<arch>-javacomm-5.0-0.0.<arch>.rpm

   The Java Communications API is installed within the /opt/ibm/java2-i386-50/ directory structure.

To install the Java Communications API from a .tgz file:

1. Put the Java Communications API archive file, ibm-java2-javacomm-50-linux-<arch>.tgz, in the directory containing the IBMJava2-50 directory.
2. From a shell prompt, in the directory containing the .tgz file, extract the contents:

       tar -xvzf ibm-java2-javacomm-50-linux-<arch>.tgz

   The Java Communications API is extracted into subdirectories within the existing IBMJava2-50 directory.

## Location of Java Communications API files

The Java Communications API files are installed as shown:

- jre/lib/ext/comm.jar
- jre/bin/libibmcomm.so
- jre/lib/javax.comm.properties

If you installed to the default directory, the comm.jar file is in /opt/ibm/java2-i386-50/jre/lib/ext.

If you installed the package in another directory, the files are in the same directory structure, but /opt/ibm/java2-i386-50/ is replaced by the directory where you installed Java Communications API.

## Configuring Java Communications API

After you install Java Communications API, you must:

- Change the access mode of serial and parallel ports.
- Set the PATH, if you did not set it when you installed Java. See Setting the PATH.

### Changing the access mode of serial and parallel ports

After you install Java Communications API, you must change the access mode of serial and parallel ports so that users can access these devices. You must give a user read/write access to the required devices. Log on as root and use the following commands, as applicable:

        chmod 666 /dev/ttyS0    (also known as serial port COM1)
        chmod 666 /dev/lp0      (also known as parallel port LPT1)
        chmod 666 /dev/ttyS1    (also known as serial port COM2)
        chmod 666 /dev/ttyS2    (also known as serial port COM3)
        chmod 666 /dev/ttyS3    (also known as serial port COM4)

These commands give read/write access to everyone on the system.

An alternative method is to make the permissions 660 and add specific users to the group in which the devices reside. On a SUSE system, for example, the devices are in the `uucp` group. Thus, users can be added to the `uucp` group to gain access to the devices.

Change the access mode of any other ports as needed.

#### Specifying devices in the javax.comm.properties file

The file javax.comm.properties allows you to specify the prefixes of the devices that are made available to the Java Communications API and whether they are parallel or serial. Port numbers are allocated sequentially to all devices. For example, if you specify `/dev/ttyS=PORT_SERIAL` and the devices `/dev/ttyS0` and `/dev/ttyS1` exist, they will be allocated COM1 and COM2 respectively.

To use the USB-serial connectors, uncomment the line `/dev/ttyUSB=PORT_SERIAL` in the javax.comm.properties file. If the devices `/dev/ttyUSB0` and `/dev/ttyUSB1` exist and COM1 and COM2 have already been defined, the USB-serial devices are allocated the next sequential ports, COM3 and COM4.

## Enabling serial ports on IBM ThinkPads

Most ThinkPads have their serial ports disabled by default in the BIOS. Currently, there is no way to enable the ports with Linux (the tpctl package does not enable the ports if they are disabled in the BIOS).

To enable the ports in the BIOS, you must use the DOS version of the ThinkPad Configuration Utility that is available from the IBM ThinkPad Download site. To use the ThinkPad Configuration Utility, you need a bootable DOS diskette. Note that the ThinkPad Configuration Utility might have been installed as part of the ThinkPad Utilities under Windows, depending on your installation options, and you can run it from a command prompt in Windows.

The ThinkPad Configuration application provided with Windows has options to enable or disable the serial and parallel ports but this does not also change the settings in the BIOS. So if you use this application with Windows, the ports are available; however, if you reboot your machine with Linux, the ports will not be enabled.

## Printing limitation with the Java Communications API

When printing with the Java Communications API, you might have to press "Form feed" or "Continue" or similar on the printer.

## Uninstalling Java Communications API

The process you use to uninstall the Java Communications API depends on whether you installed the installable Red Hat Package Manager (RPM) package or the compressed Tape Archive (TAR) package.

### Uninstalling the installable Red Hat Package Manager (RPM) package

To uninstall the Java Communications API if you installed the installable RPM package:

1. At a shell prompt, type:

           rpm -e ibm-java2-<arch>-javacomm-5.0-0.0

   Alternatively, you can use a graphical tool such as kpackage or yast2.

2. If the directory where you installed the Java Communications API does not contain any other tools that you require, remove that directory from your PATH statement.

### Uninstalling the compressed Tape Archive (TAR) package

To uninstall the Java Communications API, if you installed the compressed TAR package, delete the following files from the directory where you installed them:

- jre/lib/ext/comm.jar
- jre/bin/libibmcomm.so
- jre/lib/javax.comm.properties

## Java Communications API documentation

You can find API documentation and samples for Java Communications API at the Sun Web site: http://java.sun.com.

# Deploying Java applications

## (Linux IA 32-bit and PPC32 only) Using the Java Plug-in

The Java Plug-in is a Web browser plug-in. If you use the Java Plug-in, you can bypass your Web browser's default JVM and instead use a Runtime Environment of your choice to run applets or beans in the browser.

You must allow applets to finish loading to prevent your browser from 'hanging'. For example, if you use the Back button and then the Forward button while an applet is loading, the HTML pages might be unable to load.

The Java Plug-in is documented by Sun at: http://java.sun.com/j2se/1.5.0/docs/guide/plugin/developer_guide/.

### Supported browsers

|For Linux PPC32, Mozilla 1.6 is the supported |browser.

|For Linux IA32, see Table 3.

|Table 3. Browsers supported by the Java Plug-in on Linux IA32
|Distribution | |Netscape default version | |Netscape supported versions | |Mozilla default version | |Mozilla supported versions
--- | --- | --- | --- | ---
|Red Hat Enterprise Linux 3.0 | |- | |7.x | |1.4.2 | |1.4.1, 1.4.2, 1.7.8, Firefox 1.0.x
|Red Hat Enterprise Linux 4.0 | |4.8 | |7.x | |1.7.3 | |1.4.1, 1.4.2, 1.7.8, Firefox 1.0.x
|SUSE Linux Enterprise Server 9.0 | |- | |7.x | |1.6 | |1.4.1, 1.4.2, 1.6, 1.7.8, Firefox 1.0.x

|

### Installing and configuring the Java Plug-in

|Multiple versions of the Java Plug-in are supplied with |the SDK. You choose the right version for your browser. The most common |are:

| |
libjavaplugin_oji.so
|
  The most common Plug-in. It is based on Mozilla's Open JVM Integration initiative and is used with most Mozilla products |and derivatives, including Firefox. |
|
libjavaplugin_ojigtk2.so
|
  The same Plug-in as above but compiled with the GTK2 toolkit. |

|There are instructions for installing the Plug-in on |some common browsers below.

|You must symbolically link the Plug-in, rather than |copy it, so that it can locate the JVM.

#### Mozilla

|Only Mozilla versions 1.4 and later are supported.

To make the Java Plug-in available to all users:

1. Log in as root.
2. Change to your Mozilla Plug-ins directory (this could be different on some Linux distributions) .

       cd /usr/local/mozilla/plugins/

3. |Create a symbolic link to libjavaplugin_oji.so. |

       ln -s /opt/ibm/java2-i386-50/jre/bin/libjavaplugin_oji.so .

You must symbolically link the Plug-in, rather than copy it, so that it can locate the JVM.

| | |

#### Firefox

|

To make the Java Plug-in available to all users:

|

|
1. Log in as root.
|
2. Change to your Firefox Plug-ins directory (this could be different |on some Linux distributions) . |

       cd /usr/local/mozilla-firefox/plugins/

|
3. |Create a symbolic link to libjavaplugin_oji.so. |

       ln -s /opt/ibm/java2-i386-50/jre/bin/libjavaplugin_oji.so .

   |

You must symbolically link the Plug-in, rather than copy it, so |that it can locate the JVM.

#### Netscape 7.1 and above

To install and configure the Java Plug-in for Netscape, make a symbolic link from the library file /opt/ibm/java2-i386-50/jre/bin/javaplugin_oji.so to your browser's Plug-ins directory (/browser-install-path/plugins).

1. Log in as root.
2. Change to your Netscape Plug-ins directory (this could be different on some Linux distributions).

       cd /usr/local/netscape/plugins/

3. Create a symbolic link to javaplugin_oji.so.

       ln -s /opt/ibm/java2-i386-50/jre/bin/javaplugin_oji.so .

You must symbolically link the Plug-in, rather than copy it, so that it can locate the JVM.

### Common Document Object Model (DOM) support

Because of limitations in particular browsers, you might not be able to implement all the functions of the org.w3c.dom.html package. One of the following errors will be thrown:

- A sun.plugin.dom.exception.NotSupportedException is thrown for some of these functions.
- A sun.plugin.dom.exception.InvalidStateException is thrown when the browser does not support a particular function.

### Using DBCS parameters

The Java Plug-in supports double-byte characters (for example Chinese Traditional BIG-5, Korean, Japanese) as parameters for the tags `<APPLET>`, `<OBJECT>`, and `<EMBED>`. You must select the correct character encoding for your HTML document so that the Java Plug-in can parse the parameter. Specify character encoding for your HTML document by using the `<META>` tag in the `<HEAD>` section like this:

    <meta http-equiv="Content-Type" content="text/html; charset=big5">

This example tells the browser to use the Chinese BIG-5 character encoding to parse the HTML file using. All the parameters are passed to the Java Plug-in correctly. However, some of the older versions of browsers might not understand this tag correctly. In this case, you can force the browser to ignore this tag, but you might have to change the encoding manually.

You can specify which encoding you want to use to parse the HTML file:

- Netscape 4: View Menu -> Character Set
- Mozilla: View Menu -> Character Coding

## (Linux IA 32-bit, PPC32, and PPC64 only) Using Web Start

You can use Java Web Start to deploy Java applications. Web Start allows the user to launch and manage applications directly from the Web. Using Java Web Start, you can start applications easily from the Web, being sure that you are running the latest version, eliminating installation or upgrade procedures. Java Web Start removes the need to download and install software, bypassing lengthy installation options.

|Web start supports these java-vm-args documented at http://java.sun.com/j2se/1.5.0/docs/guide/javaws/developersguide/syntax.html#resources:

|

|
- -verbose
|
- -version
|
- -showversion
|
- -help
|
- -X
|
- -ea
|
- -enableassertions
|
- -da
|
- -disableassertions
|
- -esa
|
- -enablesystemassertions
|
- -dsa
|
- -disablesystemassertions
|
- -Xint
|
- -Xnoclassgc
|
- -Xdebug
|
- -Xfuture
|
- -Xrs
|
- -Xms
|
- -Xmx
|
- -Xss

IBM Web Start also supports -Xgcpolicy to set the garbage collection policy.

For information on the browsers that support Web Start, see Supported browsers.

For more information about Web Start, see: http://java.sun.com/products/javawebstart and http://java.sun.com/j2se/1.5.0/docs/guide/javaws/index.html. For more information about deploying applications, see: http://java.sun.com/j2se/1.5.0/docs/guide/deployment/index.html.

### Running Web Start

Java Web Start v5.0 is installed automatically when you install Java using the .rpm or .tgz packages.

|If you extract Java from the .tgz package, run the jre/lib/javaws/updateSettings.sh |shell script, to update the .mailcap and .mime.types files on your system.

You can invoke Web Start in three ways:

1. Select a link on a Web page that refers to a .jnlp file.
2. At a shell prompt, type `javaws <URL>`, where `<URL>` is the location of a .jnlp file.
3. |If you have already used Java Web Start to open the application, |run /opt/ibm/java2-i386-50/jre/bin/javaws to launch the Java Application |Cache Viewer.

After an application is downloaded, the application is stored in the Java Application Cache. If the application is accessed again, Java Web Start downloads a more recent version of the application, if available, and uses the cached version if not.

If an error occurs in a .jnlp file (such as an invalid tag name), Web Start fails without displaying an error message.

## Shipping Java applications

A Java application, unlike a Java applet, cannot rely on a Web browser for installation and runtime services. When you ship a Java application, your software package probably consists of the following parts:

- Your own class, resource, and data files
- An installation procedure or program

To run your application, a user needs the Runtime Environment for Linux. The SDK for Linux software contains a Runtime Environment. However, you cannot assume that your users have the SDK for Linux software installed.

Your SDK for Linux software license does not allow you to redistribute any of the SDK's files with your application. You should ensure that a licensed version of the SDK for Linux is installed on the target machine.

| | |

# Class data sharing between JVMs

|

The IBM Virtual Machine (VM) allows you to share bootstrap and application |classes between VMs, by storing them in a cache in shared memory. Class sharing |reduces the overall virtual memory consumption when more than one VM shares |a cache. Class sharing also reduces the startup time for a VM after the cache |has been created. The shared class cache is independent of any active VM and |persists beyond the lifetime of the VM that started the cache.

| |

## Overview of class sharing

|

The IBM SDK allows you to share as many classes as possible, while appearing |transparent to the user.

| |

### Cache contents

|

The shared class cache contains read-only static class data and metadata |that describes the classes. Any VM may read or update the cache. The VMs that |are sharing must be at the same release. You must take care if runtime bytecode |modification is being used. (See Runtime bytecode modification.)

| |

### Dynamic updating of the cache

|

Because the shared class cache persists beyond the lifetime of any VM, |the cache is updated dynamically to reflect any modifications that might have |been made to JARs or classes on the file system. The dynamic updating makes |the cache transparent to the application using it.

| |

### Enabling class sharing

|

Enable class sharing by using the -Xshareclasses option |when starting a VM, to make the VM connect to an existing cache or to create |one if it does not exist. All bootstrap and application classes loaded by |the VM are shared by default. Custom classloaders share automatically if they |extend the application classloader; otherwise, they must use the Java Helper |API provided with the VM to access the cache. (See Adapting custom classloaders to share classes.)

| |

### Cache security

|

Access to the shared class cache is limited by operating system permissions |and Java security permissions. The shared class cache |is created with user access by default unless the groupAccess command-line suboption is used. Only a classloader that has registered |to share classes can add classes to the shared class cache. If a Java SecurityManager |is installed, class loaders, excluding the default bootstrap, application, |and extension class loaders, must be granted permission to share classes by |adding SharedClassPermission lines to the java.policy file. (See Using SharedClassPermission.) |The RuntimePermission "createClassLoader" restricts the creation of new ClassLoaders |and therefore also restricts access to the cache.

| |

### Cache lifespan

|

Multiple caches can exist on a system and are specified by name as a suboption |to the -Xshareclasses command. A VM can connect to only |one cache at any one time. You specify cache size on startup using -Xscmx<n>[k|m|g], but this size is then fixed for the lifetime of |the cache. Caches exist until they are explicitly destroyed using a suboption |to the -Xshareclasses command or until the system is |rebooted.

| |

### Cache utilities

|

All cache utilities are suboptions to the -Xshareclasses command. Use -Xshareclasses:help to see a list |of available suboptions.

| |

## Using command-line options for class sharing

|

Class sharing is enabled and configured using the -Xshareclasses and -Xscmx command-line options.

|

|
- -Xscmx<size>[k|m|g] |
  |
  - Specifies cache size. This option applies only if a cache is being created |and no cache of the same name exists. Default cache size is platform-dependent. |You can find out the size value being used by adding -verbose:sizes as a command-line argument. Minimum cache size is 4 KB. Maximum cache |size is also platform-dependent. (See Cache size limits.)
|
- -Xshareclasses:<suboption1>[,<suboption2>...] |
  |
  - Enables class sharing. Can take a number of suboptions, some of which |are cache utilities. Cache utilities perform the required operation on the |specified cache, without starting the VM. You can combine multiple suboptions, |separated by commas, but the cache utilities are mutually exclusive. |

    You |can use the following suboptions with the -Xshareclasses option:

    |
    |
    - help |
      |
      - Lists all the command-line options.
    |
    - name=<name> |
      |
      - Connects to a cache of a given name, creating the cache if it does not |already exist. Use the listAllCaches utility option |to show which caches are currently available. If you do not specify a name, |the default name "sharedcc_" is combined with the current user name appended |to create the cache name.
    |
    - groupAccess |
      |
      - Sets operating system permissions on a new cache to allow group access |to the cache. The default is user access only.
    |
    - verbose |
      |
      - Gives detailed output on the cache I/O activity, listing information on |classes being stored and found. Each classloader is given a unique ID (the |bootstrap loader is always 0) and the output shows the classloader hierarchy |at work, where classloaders must ask their parents for a class before they |can load it themselves. It is normal to see many failed requests; this behavior |is expected for the classloader hierarchy. Note that the standard option -verbose:class also enables class sharing verbose output |if class sharing is enabled.
    |
    - modified=<modified context> |
      |
      - Required if a bytecode agent is installed that might modify bytecode at |runtime. If you do not specify this option and a bytecode agent is installed, |no classes are stored or found in the cache. The <modified |context> is a descriptor chosen by the user; for example "myModification1". |This option partitions the cache, so that only JVMs using context myModification1 |can share the same classes. For instance, if you run "HelloWorld" with a modification |context and then run it again with a different modification context, you will |see all classes stored twice in the cache.
    |
    - destroy (Utility option) |
      |
      - Destroys a cache using the name specified in the name=<name> suboption. If the name is not specified, |the default cache is destroyed. A cache can be destroyed only if all VMs using |it have shut down, and the user has sufficient permissions.
    |
    - destroyAll (Utility option) |
      |
      - Tries to destroy all caches available to the user. A cache can be destroyed |only if all VMs using it have shut down, and the user has sufficient permissions.
    |
    - expire=<time in minutes> |(Utility option) |
      |
      - Destroys all caches that have been unused for the time specified.
    |
    - listAllCaches (Utility option) |
      |
      - Lists all the caches on the system, describing if they are in use and |when they were last used.
    |
    - printStats (Utility option) |
      |
      - Displays summary statistics information about the cache specified in the name=<name> suboption. If the |name is not specified, statistics are displayed about the default cache. The |most useful information displayed is how full the cache is and how many classes |it contains. Note that "stale" classes are classes that have been updated |on the file system and which the cache has therefore marked "stale". Stale |classes are not purged from the cache. See the Diagnostics Guide for more information.
    |
    - printAllStats (Utility option) |
      |
      - Displays detailed information about the contents of the cache specified |in the name=<name> suboption. |If the name is not specified, statistics are displayed about the default cache. |Every class is listed in chronological order along with a reference to the |location from which it was loaded. See the Diagnostics Guide for more information.

| |

## Creating, populating, monitoring, and deleting a cache

|

To enable class sharing, add -Xshareclasses[:name=<name>] to your application command line. The VM will either connect to an existing |cache of the given name, or create a new cache of that name. If a new cache |has been created, it will be populated with all bootstrap and application |classes being loaded until the cache becomes full. If two or more VMs are |started concurrently, they will all populate the cache concurrently.

|

To check that the cache has been created, run `java -Xshareclasses:listAllCaches`. To see how many classes and how much class data is being shared, run `java -Xshareclasses:[name=<name>],printStats`. (These utilities can |be run after the application VM has terminated or in another command window.)

|

To see classes being loaded from the cache or stored in the cache, add `-Xshareclasses:[name=<name>],verbose` to your application command |line.

|

To delete the cache created, run `java -Xshareclasses:[name=<name>],delete`. You should have to delete caches only if they contain many stale |classes or if the cache is full and you want to create a bigger cache.

|

You are recommend to tune the cache size for your specific application, |because the default is unlikely to be the optimum size. The best way to determine |the optimum cache size is to specify a large cache (using -Xscmx), run the application and then use printStats to determine how |much class data has been stored. Add a small amount to the value shown in |printStats for contingency. Note that because classes can be loaded at any |time during the lifetime of the VM, it is best do this analysis after the |application has terminated. However, a full cache does not have a negative |impact on the performance or capability of any VMs connected to it, so it |is quite legitimate to decide on a cache size that is smaller than required.

|

If a cache becomes full, a message is output to the command line of all |VMs using the cache and they will load any further classes into their own |process memory. Classes in a full cache can still be shared, but a full cache |is read-only and cannot be updated with new classes.

| |

## Performance and memory consumption

|

Class sharing is particularly useful on systems that use more than one |VM running similar code; the system benefits from reduced virtual memory consumption. | It is also useful on systems that frequently start up and shut down VMs, |which benefit from the improvement in startup time.

|

The overhead to create and populate a new cache is minimal. The VM startup |cost in time for a single VM is typically between 0 and 5% slower compared |with a system not using class sharing, depending on how many classes are loaded. |VM startup time improvement with a populated cache is typically between 10% |and 40% faster compared with a system not using class sharing, depending on |the operating system and the number of classes loaded. Multiple VMs running |concurrently will show greater overall startup time benefits.

|

When you run your application with class sharing, you can use the operating |system tools to see the reduction in virtual memory consumption.

| |

## Limitations and considerations of using class sharing

| |

### Cache size limits

|

The cache for sharing classes is allocated using System |V IPC Shared memory mechanism.

|

The maximum theoretical cache size is 2 GB. The size of cache |you can specify is limited by the amount of physical memory and paging space available to the system.

|

Because the virtual address space of a process is shared |between the shared classes cache and the Java heap, increasing the maximum |size of the Java heap will reduce the size of the shared classes cache you |can create.

|

Cache size is limited by SHMMAX settings, |which limits the amount of shared memory that can be allocated. You can find |these settings by looking at /proc/sys/kernel/shmmax file. SHMMAX is usually set to 30MB.

| |

### Runtime bytecode modification

|

Any VM using a JVMTI agent that can modify bytecode is not able to share |classes unless the modified=<modified_context> suboption is used on the |command line. (See Using command-line options for class sharing). The modified context |is a user-specified descriptor that describes the type of modification being |performed. All VMs using a given modified context must modify bytecode in |a predictable, repeatable manner for each class, so that the modified classes |stored in the cache have the expected modifications when they are loaded by |another VM. Any modification must be predictable because classes loaded from |the shared class cache cannot be modified again by the agent. Note that modified |and unmodified bytecode can be stored in the same cache. See the Diagnostics Guide for more detail on this topic.

| |

### Operating system limitations

|

For operating systems that can run both 32-bit and 64-bit |applications, class sharing is not permitted between 32-bit and 64-bit VMs. |The listAllCaches suboption lists 32-bit or 64-bit caches, |depending on the address mode of the VM being used.

|

The shared class cache requires disk space to store identification information |about the caches that exist on the system. This information is |stored in /tmp/javasharedresources. If the identification information |directory is deleted, the VM cannot identify the shared classes on the system |and must recreate the cache. Use the `ipcs` command |to view the memory segments used by a VM or application.

|

Users running a JVM must be in the same group to use a |shared class cache. The permissions for accessing a shared classes cache |are enforced by the operating system. If a cache name is not specified, the |user name is appended to the default name so that multiple users on the same |system create their own caches by default.

| |

### Using SharedClassPermission

|

If a SecurityManager is being used with class sharing and the running application |uses its own classloaders, these classloaders must be granted shared class |permissions before they can share classes. You add shared class permissions |to the java.policy file using the ClassLoader class name (wildcards are permitted) |and either "read", "write", or "read,write" to determine the access granted. |For example:

|

    permission com.ibm.oti.shared.SharedClassPermission
    |        "com.abc.customclassloaders.*", "read,write";

If a ClassLoader |does not have the correct permissions and attempts to share classes, an AccessControlException |is thrown. You cannot change or reduce the permissions of the default bootstrap, |application, or extension classloaders.

| |

## Adapting custom classloaders to share classes

|

Most Java applications use the VM's own classloaders or have custom classloaders |that extend java/net/URLClassLoader. Applications using these classloaders |can automatically share bootstrap and application classes. Custom classloaders |that do not extend java/net/URLClassLoader will require modifications to make |use of class sharing. All custom class loaders must be granted shared class |permissions if a SecurityManager is being used, see Using SharedClassPermission. |IBM provides several Java interfaces for various types of custom classloaders, |which allow the classloaders to find and store classes in the shared class |cache. These classes are in the com.ibm.oti.shared package. The Javadoc for |this package is provided with the SDK in the file docs/apidoc.zip. See the Diagnostics Guide for more information on |how to use these interfaces.

# Service and support for independent software vendors

If you are entitled to services for the Program code pursuant to the IBM Solutions Developer Program, contact the IBM Solutions Developer Program through your normal method of access or on the Web at: http://www-1.ibm.com/partnerworld/.

If you have purchased a service contract (that is, IBM's Personal Systems Support Line or equivalent service by country), the terms and conditions of that service contract determine what services, if any, you are entitled to receive with respect to the Program.

# Accessibility

The User Guides that are supplied with this SDK and the Runtime Environment have been tested by using screen readers. You can use a screen reader such as the Home Page Reader or the JAWS screen reader with these User Guides.

To change the font sizes in the User Guides, use the function that is supplied with your browser, usually found under the View menu option.

For users who require keyboard navigation, a description of useful keystrokes for Swing applications is in "Swing Key Bindings" at http://www-128.ibm.com/developerworks/java/jdk/additional/

## iKeyman accessibility

|In addition to the GUI, the iKeyman tool provides the command-line |tool IKEYCMD, which has the same functions that the |iKeyman GUI has. IKEYCMD allows you to manage keys, |certificates, and certificate requests. You can call IKEYCMD from native shell scripts and from programs that are to be used when |applications need to add custom interfaces to certificate and key management |tasks. IKEYCMD can create key database files for all |the types that iKeyman currently supports. IKEYCMD can |also create certificate requests, import CA signed certificates, and manage |self-signed certificates.

To run an IKEYCMD command, enter:

    java [-Dikeycmd.properties=<properties file>] com.ibm.gsk.ikeyman.ikeycmd
    <object> <action> [options]

where:

<object>
  is one of the following:
  -keydb
    Actions that are taken on the key database (either a CMS key database file, a WebDB keyring file, or SSLight class)
  -cert
    Actions that are to be taken on a certificate within a key database
  -certreq
    Actions that are to be taken on a certificate request within a key database
  -version
    Displays version information for IKEYCMD
  -help
    Displays help for the IKEYCMD invocations.
<action>
  |The specific action that is to be taken on the object. To |see the available actions for an object, invoke IKEYCMD passing |only the object as an argument. Context-sensitive help shows the available |actions for that object.
-Dikeycmd.properties
  Specifies the name of an optional properties file to use for this Java invocation. A default properties file, ikeycmd.properties, is provided as a sample file that can be changed and used by any Java application.

Note:
The object and action keywords must be in the specified sequence. However, options are not positional and can be in any sequence, provided that they are specified as an option and operand pair.

For more information, see the iKeyman User Guide at: http://www.ibm.com/developerworks/java/jdk/security/index.html.

## Keyboard traversal of JComboBox components in Swing

If you traverse the drop-down list of a JComboBox component with the cursor keys, the button or editable field of the combo box does not change value until an item is selected. This is the desired behavior for this release and improves accessibility and usability by ensuring that the keyboard traversal behavior is consistent with mouse traversal behavior.

## (Linux IA 32-bit, PPC32, and PPC64 only) Web Start accessibility

IBM Java Web Start v5.0 contains several accessibility and usability improvements over the previous release, including better support for screen readers and improved keyboard navigation.

You can use the command line only to launch a Java application that is enabled for Web Start. To change preference options, you must edit a configuration file, .java/.deployment/.deployment.properties in the user's home directory. Take a backup before you edit this file. Not all the preferences that can be set in the Java Application Cache Viewer are available in the configuration file.

# Known limitations

The following sections explain known limitations of the SDK and Runtime Environment for Linux.

## Limitations that apply to all Linux platforms except where indicated

- |Your window manager might override some of the Java keyboard |shortcuts. If you need to use an overridden Java keyboard shortcut, consult |your operating system manual and change your window manager keyboard shortcuts. |

- |The X Windows System is unable to use file descriptors above |255. Because the JVM holds file descriptors for open jar files, X can run |out of file descriptors. As a workaround, you can set the JAVA_HIGH_ZIPFDS environment variable to tell the JVM to use higher file |descriptors for jar files. |

  To use the JAVA_HIGH_ZIPFDS environment variable, set it to a value between 0 and 512. The JVM will |then open the first jar files using file descriptors up to 1024. For example, |if your program is likely to load 300 jar files:

  `export JAVA_HIGH_ZIPFDS=300` |

  The first 300 jar files will then be loaded using the file descriptors |724 to 1023. Any jar files opened after that will be opened in the normal |range.

- You might not be able to use the system clipboard with double-byte character set (DBCS) to copy information between Linux applications and Java applications if you are running the K Desktop Environment (KDE).

- On RHEL3, SLES9, and newer distributions, the default threading library is NPTL, which implements Java threads as native threads. On earlier distributions, the default threading library is LinuxThreads, which implements threads as new processes. If the number of Java threads exceeds the maximum number of processes allowed, your program might hang.

  The maximum number of threads available is determined by the lowest of:

  - The user processes setting (ulimit -u) in /etc/security/limits.conf
  - The limit that is defined in /proc/sys/kernel/threads_max
  - The limit PTHREAD_THREADS_MAX that is defined in libpthreads.so (changing this value requires glibc to be recompiled)

  However, you might run out of virtual storage before you reach the maximum number of threads.

- If you terminated a Java application with a Ctrl-C, several processes might be left orphaned.

- KeyEvent results that include the ALT key differ between using different window managers in Linux. They also differ from results of other operating systems. In the Enlightenment window manager, Alt+A and Shift+Alt+A produce different modifiers, and Ctrl+Alt+A produces no key event at all. However, using the WindowMaker window manager, Ctrl+Alt+A produces a key event.

- On the Linux X Window System, the keymap is set to: 64 0xffe9 (Alt_L) 0xffe7 (Meta_L), and 113 0xffea (Alt_R) 0xffe8 (Meta_R). You can check this by typing the following at a shell prompt:

      xmodmap -pk

  This is why the SDK considers that Meta + Alt are being pressed together. As a workaround, you can remove the Meta_x mapping by typing the following at a shell prompt:

      xmodmap -e "keysym Alt_L = Alt_L" -e "keysym Alt_R = Alt_R"

  Note:
  This workaround might affect other X-Window applications that are running on the same display if they use the Meta-key that was removed.

- Creating DSA key pairs of unusual lengths can take a significant amount of time on slow machines. Do not interpret this delay as a hang because the process will complete if you allow enough time. The DSA key generation algorithm has been optimized to generate standard key lengths (for instance, 512, 1024) more quickly than others.

- Native programs cannot create a VM with JNI_VERSION_1_1(0x00010001) interfaces. You cannot call JNI_CreateJavaVM() and pass it a version of JNI_VERSION_1_1(0x00010001). The versions that can be passed are:
  - JNI_VERSION_1_2(0x00010002)
  - JNI_VERSION_1_4(0x00010004)

  The VM created is determined by the Java libraries present (that is, 1.2.2, 1.3.x, 1.4.x, 5.x), not the one that is implied by the JNI interface version passed.

  The interface version does not affect any area of VM behavior other than the functions available to native code.

- A call to JNI_CreateJavaVM() from a JNI application might cause a segmentation fault (signal SIGSEGV); to avoid this fault, rebuild your JNI program specifying the option -lpthread.

- For users of Traditional Chinese only, function keys Enter, Space, Backspace, and ESC do not work as expected when using the LinYi ZhuYin, YiTian ZhuYin, and Bosham IMEs to input the TCH characters. The Enter key inserts a new line, the ESC key is used to cancel the preedit strings or the candidate window, and the Space bar inserts a space. The candidate window should disappear after the commit key has been pressed and it should not appear when you press the Backspace key while using the LinYi ZhuYin, YiTian ZhuYin, and Bosham IMEs to input the Traditional Chinese characters.

- If you are running with a lot of concurrent threads, you might get a warning message: `java.lang.OutOfMemoryError`. This is an indication that your machine is running out of system resources and messages can be caused by the following reasons:
  1. New threads cannot be created because:
     - The number of processes created exceeds your user limit. (If your Linux installation uses LinuxThreads, rather than NPTL.)
     - Not enough system resources are available to create new threads. In this case, you might see also other Java exceptions, depending on what your application is running.
  2. Kernel memory is either running out or is fragmented. You can see corresponding Out of Memory kernel messages in /var/log/messages that have the killed process id.
  Try tuning your system to increase the corresponding system resources.

- During installation, if you have already installed an earlier version of this product that was distributed by Red Hat, the Red Hat Package Manager (RPM) will report that the IBM package is older than any versions of the product that Red Hat has distributed. This condition occurs because Red Hat adds to the RPM package a "serial number" that overrides the versioning scheme of the product in the package, and, by default, the RPM refuses to install a package that seems to be older than one already installed. The --oldpackage option of the rpm command enables you to install the new IBM package.

- When running a Java AWT/Swing application on a Linux machine and exporting the display to a second machine, you might experience problems displaying some dialogs if the set of fonts loaded on the X client machine is different from the set loaded on the X server machine. This problem is noticeable particularly with SLES8 in Chinese locales, where the default installation of the server version installs arphic fonts, but the default installation of the client does not. To avoid this problem, install the same fonts on both machines.

- If your system locale is using a UTF-8 encoding, some SDK tools might throw a sun.io.MalformedInputException. To find out whether your system is using a UTF-8 encoding, examine the locale-specific environment variables such as LANG or LC_ALL to see if they end with the suffix ".UTF-8". If you get this sun.io.MalformedInputException, change characters that are not within the 7-bit ASCII range (0x00 - 0x7f) and are not represented as Java Unicode character literals to Java Unicode character literals (for example: '\u0080'). You can also work around this problem by removing the ".UTF-8" suffix from the locale-specific environment variables; for example, if your machine has default locale of "en_US.UTF-8", set LANG to "en_US".
  Note:
  Some distributions of Red Hat, including Red Hat 9 and RHEL3, use UTF-8 encoding by default.

- If you are using AMI and xcin in a cross-platform environment (for example, if you try to export the display between a 32-bit and a 64-bit system, or between a big-endian and a little-endian system) there might be some problems. If you have this kind of problem, contact your Linux distributor.

- On Red Hat Enterprise Linux 3, Chinese characters might not be displayed in AWT text components except for GB2312 characters in the Chinese GB18030 locale.

- |In IBM's JConsole tool, the Local tab |which allows you to connect to other Virtual Machines on the same system is |not available. Instead, use the Remote tab in JConsole |to connect to the Virtual Machine that you want to monitor. When you launch |the application that you want to monitor, set these command-line options: |
  |
  - -Dcom.sun.management.jmxremote.port=<value> to specify the port the |management agent should listen on.
  |
  - -Dcom.sun.management.jmxremote.authenticate=false to disable authentication |unless you have created a username file.
  |
  - -Dcom.sun.management.jmxremote.ssl=false to disable SSL encryption.
  |

- |For Chinese, Korean, and Japanese language users of Red Hat |Enterprise Linux 4 only, if you are using the Internet/Intranet Input Method |Framework (IIIMF), use IIIMF packages that are included in Red Hat Enterprise |Linux 4 Update 2 or later. Also, note the following problem. If you experience |this problem, contact Red Hat for guidance, at http://www.redhat.com. |
  |
  - On Linux zSeries 64-bit, you might experience IIIMF failures or a failure |to start. See Red Hat Bugzilla number RIT73533 for Japanese users only.
  |

- |For Simplified Chinese language users of Red Hat Enterprise |Linux 4 only. The zh_CN.GB18030 locale is not supported by xlib in RHEL4. |xterm cannot activate Input Method Server to input GB18030 characters. Use |the zh_CN.UTF8 locale instead. If you have legacy programs or data encoded |with GB2312, GBK, or GB18030, and you want to migrate them to RHEL4, you must |preprocess them with iconv to convert them to utf-8 encoding so that the programs |can run and data can be displayed properly in RHEL4 with the zh_CN.UTF8 locale. |

- |On RHEL 3 with miniChinput (Simplified Chinese XIM server) |on 64-bit environments (such as AMD64 or zSeries 64-bit platforms), you might |experience unexpected behavior with Java. Contact Red Hat for guidance, at http://www.redhat.com. See Red Hat Bugzilla number |RIT75701. |

- |On RHEL 3 with ami (Korean XIM server), you might experience |unexpected behavior with Java on 64-bit environments (such as AMD64 or zSeries |64-bit platforms). Contact Red Hat for guidance, at http://www.redhat.com. See Red Hat Bugzilla numbers RIT73605 and RIT75708. |

- |On RHEL 4 with xcin (Traditional Chinese XIM server), you |might experience unexpected behavior such as a segementation fault with Java |on 64-bit environments (such as AMD64 or zSeries 64-bit platforms). Contact |Red Hat for guidance, at http://www.redhat.com. |See Red Hat Bugzilla number RIT78430. |

- |For |Red Hat Enterprise Linux 4, when using IIIMF (Internet Intranet Input Method |Framework) to input DBCS characters, you may encounter focus change problems. |The problem occurs when minimizing active input components. After restoring |the component, the input method will switch back to SBCS. DMCS must then be |manually reactivated. |

  The following components have this focus change problem:

  |
  |
  - java.awt.Canvas
  |
  - java.awt.Button
  |
  - javax.swing.JButton
  |
  - javax.swing.JSplitPane
  |
  - javax.swing.JComboBox
  |
  - javax.swing.JList
- |For |Japanese, Chinese, and Korean language users, you cannot use XIM to input |your own characters into text components on a Java applet in a Web browser. |This limitation occurs because XEmbed requires a fix to the X11 library file. |To avoid this situation, specify the -Dsun.awt.noxembed=true system parameter to disable XEmbed. You can set this option by using |the control panel: |
  |
  1. Open the Java Plug-in control panel and go to the Java tab.
  |
  2. Click the View button in the Java Applet Runtime |Settings.
  |
  3. Input -Dsun.awt.noxembed=true in the Java Runtime |Parameters and click OK.
  |
  4. Click Apply
  |
  5. Start a browser.
  |

## Linux IA 32-bit limitations

- For Arabic text users, when using Linux with a Matrox video card and acceleration enabled, distortion of characters can be seen when using drawString to display large fonts. This problem is caused by the driver for those cards. The suggested workaround is to disable acceleration for the device.

- On SLES 9 NPTL, the parallel port driver causes a kernel crash and brings down a Java thread. The JVM detects this crash when it tries to suspend the thread for Garbage Collection and then crashes producing a core file and the message "JVMLH030: threads are disappearing when trying to suspend all threads".

  SUSE Bugzilla report 47947 is raised against this problem. This bug is fixed in SLES 9 Service Pack 1.

## Linux AMD64 limitations

| |
- Important note about BIOS settings on AMD64 SMP systems: |

  The Node memory interleaving BIOS setting must |be set to `DISABLED`. Otherwise, unpredictable results might occur, |including Java crashes and hangs. This instruction is in accord with AMD's |recommendation.

## Linux PPC 32-bit and 64-bit limitations

- If your Java code uses JNI calls, and any specific call has more than eight float or double parameters, your C code must be compiled with the gcc-2.95.3 Free Software Foundation (FSF) level of GNU C Compiler (GCC).

- If you are running XFree86 version 3.x, you might receive a SIGSEGV error. To avoid this problem, it is recommended that you use XFree86 version 4.x.

- If the date is set to a date before 1970, you get an exception error when you try to start Java. To work around this problem, manually set your machine to the current date.

- The JavaComm package cannot support parallel port operations on the SLES 9 GA and SP1 kernels. This limitation is resolved in the SP2 kernel. The SUSE Bugzilla number is 50028.

- Because of an unimplemented IOCTL function in the 32-bit mode of the 64-bit kernel, JavaComm cannot support serial port operations on SLES 9 and RHEL 4. This limitation is resolved in SLES 9 SP2 (Bugzilla number 49787) and RHEL 4 update 1 (Bugzilla number 144904).

## Linux PPC 64-bit limitations

- The default gcc cross compiler (version 3.2-49) causes several errors. To generate the shared library libFileStat.so, run `/opt/cross/bin/powerpc64-linux-gcc -shared -o libFileStat.so -I<SDK_PATH>/include FileStat.c` where `<SDK_PATH>` is the path to the installed SDK directory.

## Linux zSeries 64-bit limitations

The following limitations apply to Chinese and Taiwanese users on Linux zSeries 64-bit:

- The Chinese and Taiwanese input method server (xcin) has not been tested with Version 5.0.

## Linux zSeries 31-bit and 64-bit limitations

- If you use audio on a machine without a sound card, you might get an error message stating that you are out of memory when Java tries to play a sound. The message is displayed in the console, but it does not affect your Java application.

- Although the Linux kernel in the current distributions provides support for Internet Protocol version 6 (IP6), you might encounter problems using it. Support for IP6 from Java is included in this release, but you are advised to turn off the support with the -Djava.net.preferIPv4Stack=true option on the Java command. If you install a kernel that fully supports IP6, you do not need this option.

- |If you are using Java for zSeries 31-bit or 64-bit with X |windows server using a high resolution setting, font glyphs in an AWT Choice |component with Motif AWT might be clipped. To avoid this situation, lower |the resolution setting or use XAWT instead of Motif AWT. |

# Any comments on this User Guide?

If you have any comments about the usefulness, or otherwise, of this User Guide, we would be pleased to hear from you through one of these channels. Please note that these channels are not set up to answer technical queries, but are for comments about the documentation only. Send your comments:

- By e-mail to idrcf@hursley.ibm.com.
- By fax:
  - From the UK: 01962 842327
  - From elsewhere:<international code>44 1962 842327
- By mail to:
  IBM United Kingdom Ltd
  User Technologies,
  Mail Point 095
  Hursley Park
  Winchester
  Hampshire
  SO21 2JN United Kingdom

The fine print. By choosing to send a message to IBM, you acknowledge that all information contained in your message, including feedback data, such as questions, comments, suggestions, or the like, shall be deemed to be non-confidential and IBM shall have no obligation of any kind with respect to such information and shall be free to reproduce, use, disclose, and distribute the information to others without limitation. Further, IBM shall be free to use any ideas, concepts, know-how or techniques contained in such information for any purpose whatsoever, including, but not limited to, developing, manufacturing and marketing products incorporating such information.

# Notices

This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

- IBM Director of Licensing
  IBM Corporation
  North Castle Drive, Armonk
  NY 10504-1758 U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:

- IBM World Trade Asia Corporation Licensing
  2-31 Roppongi 3-chome, Minato-ku
  Tokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the information. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this information at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of enabling (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

- JIMMAIL@uk.ibm.com
  [Hursley Java Technology Center (JTC) contact]

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurement may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

## Trademarks

IBM, iSeries, pSeries, and zSeries are trademarks or registered trademarks of International Business Machines Corporation in the United States, or other countries, or both.

Intel is a trademark of Intel Corporation in the United States, other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Linux is a trademark of Linus Torvalds in the United States, other countries, or both.

Other company, product, or service names may be trademarks or service marks of others.

This product is also based in part on the work of the FreeType Project. For more information about Freetype, see http://www.freetype.org.

This product includes software developed by the Apache Software Foundation http://www.apache.org/.