# IBM 32-bit SDK for Windows platforms, Java Technology Edition, Version 5.0

# SDK and Runtime Guide

Note

Before using this information and the product it supports, read the information in Notices.

Copyright information

This edition of the user guide applies to the IBM 32-bit SDK and Runtime Environment for Windows, Java 2 Technology Edition, Version 5.0, and to all subsequent releases, modifications, and Service Refreshes, 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.

Copyright International Business Machines Corporation 2003, 2007. All rights reserved.
US Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

# Contents

Preface
Overview
Version compatibility
Migrating from other IBM JVMs
Contents of the SDK and Runtime Environment
Runtime Environment classes and tools
SDK tools and reference information
Installing and configuring the SDK and Runtime Environment
Before you install
Installing the packages
Attended (interactive) installation
Installing the Runtime Environment as the system Java Virtual Machine
Unattended installation
Enabling the IBM Accessibility Bridge
Disabling Java Accessibility support
Information for European language users
Setting the path
Setting the class path
Uninstallation
Running Java applications
The java and javaw commands
Obtaining version information
Specifying Java options and system properties
Standard options
Globalization of the java command
Executing a Java file automatically
Running Java applications with native assistive technologies
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
Euro symbol support
Support for Serbian locale
Using the SDK to develop Java applications
Transforming XML documents
Using an older version of Xerces or Xalan
Debugging Java applications
Java Debugger (JDB)
Determining whether your application is running on a 32-bit or 64-bit JVM
How the JVM processes signals
Signals used by the JVM
Linking a native code driver to the signal-chaining library
Writing JNI applications
Configuring large page memory allocation
CORBA support
System properties for tracing the ORB
System properties for tuning the ORB
Java security permissions for the ORB
ORB implementation classes
RMI over IIOP
Implementing the Connection Handler Pool for RMI
Enhanced BigDecimal
Plug-in, Applet Viewer and Web Start
Using the Java Plug-in
Supported browsers
Secure Static Versioning (SSV) support
Common Document Object Model (DOM) support
Using DBCS parameters
Working with applets
Running applets with the Applet Viewer
Unique CLSIDs
Debugging applets with the Applet Viewer
Using Web Start
Running Web Start
WebStart Secure Static Versioning
Shipping Java applications
Class data sharing between JVMs
Overview of class data sharing
Enabling and configuring class data sharing
Creating, populating, monitoring, and deleting a cache
Performance and memory consumption
Considerations and limitations of using class data sharing
Cache size limits
Runtime bytecode modification
Operating system limitations
Using SharedClassPermission
Adapting custom classloaders to share classes
Using Java Communications API (JavaComm)
Installing Java Communications API from a compressed file
Configuring Java Communications API
Specifying devices in the javax.comm.properties file
Printing limitation with the Java Communications API
Uninstalling Java Communications API
Java Communications API documentation
Service and support for independent software vendors
Accessibility
Keyboard traversal of JComboBox components in Swing
Web Start accessibility
JConsole accessibility
General note about security
Any comments on this user guide?
Appendix A. Nonstandard options
Appendix B. Known limitations
Notices
Trademarks

# Preface

This user guide provides general information about the IBM(R) 32-bit SDK and Runtime Environment for Windows(R), 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.

The SDK and Runtime Environment is supported on the following products:

- Windows 2000
- Windows XP
- Windows Server 2003
- Windows Vista

From Version 5.0, Service Refresh 5, these Virtualized Environments are supported:

- VMWare
- Xen
- Microsoft(R) Virtual Server

Note that IPv6 is supported only on Windows XP and Windows Server 2003.

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

This user guide is part of a release and is applicable only to that particular release. Make sure that you have the user guide appropriate to the release you are using.

The terms "Runtime Environment" and "Java Virtual Machine" are used interchangeably throughout this user guide.

|Technical changes made for this version of the user |guide, other than minor or obvious ones, are indicated by blue chevrons when |viewing in an Information Center, in red with vertical bars to the left of |the changes when viewing in HTML or in a color-printed copy, or by vertical |bars to the left of the changes when viewing as a PDF.

The Program Code is not designed or intended for use in real-time applications such as (but not limited to) the online control of aircraft, air traffic, aircraft navigation, or aircraft communications; or in the design, construction, operation, or maintenance of any nuclear facility.

# Overview

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

The SDK includes the Runtime Environment for Windows, 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 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 provide compilation of Java programs. The Runtime Environment for Windows does not include any of the development tools, for example appletviewer.exe or the Java compiler (javac.exe), or classes that are only for development systems.

In addition, the Java Communications application programming interface (API) package is provided for use with the Runtime Environment for Windows. You can find information about it in Using Java Communications API (JavaComm).

## Version compatibility

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

The IBM 32-bit SDK for Windows, v5.0, is built with Microsoft Visual Studio .NET 2003.

For information about compatibility issues between releases, see the Sun web site at:

http://java.sun.com/j2se/5.0/compatibility.html

http://java.sun.com/j2se/1.4/compatibility.html

http://java.sun.com/j2se/1.3/compatibility.html

If you are using the SDK as part of another product (for example, IBM WebSphere(R) Application Server), and you upgrade from a previous level of the SDK, perhaps v1.4.2, serialized classes might not be compatible. However, classes are compatible between service refreshes.

## Migrating from other IBM JVMs

From Version 5.0, the IBM Runtime Environment for Windows contains a new version of the IBM Virtual Machine for Java and the Just-In-Time (JIT) compiler.

If you are migrating from an older IBM Runtime Environment, note that:

- To remain compatible with Version 1.4.2, the JVM dynamic link library jvm.dll is installed in both jre\bin\j9vm and jre\bin\classic. Set the LIBPATH environment variable to use the JVM dynamic link library in jre\bin\classic when writing native applications using the JNI invocation interface.
- 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 Appendix A. 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 produced have changed. You must change any programs that process the verbose GC data to make them 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 included JVM specific classes in a file called core.jar. From Java 5.0 onwards, these are included in a file called vm.jar.
- Earlier versions of the IBM JRE included a file called rt.jar in the jre/lib directory. From Java v1.4 onwards, this file has been replaced by multiple JAR files 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.

# 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 must 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) might result in application portability problems. Java Native Interface (JNI) applications will have some minor dependencies.

The user guides, Javadoc, and the accompanying license, copyright files, javadoc, and demo directory are the only documentation included in this SDK for Windows. 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.

## Runtime Environment classes and tools

A list of classes and tools that you can use with the standard Runtime Environment.

- 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 C:\Program Files\IBM\Java50\jre\bin directory unless otherwise specified.
  ikeyman.exe (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.
  jaaslogon.exe
    A Windows service that enables Jaas Active Login to change their effective user at runtime using the Jaas Active Login api.
  java.exe (Java Interpreter)
    Runs Java classes. The Java Interpreter runs programs that are written in the Java programming language.
  javaw.exe (Java Interpreter)
    Runs Java classes in the same way as the java command does, but does not use a console window.
  javaws.exe (Java Web Start)
    Enables the deployment and automatic maintenance of Java applications. For more information, see Running Web Start.
  jextract.exe (Dump extractor)
    Converts a system-produced dump into a common format that can be used by jdmpview. For more information, see jdmpview.
  keytool.exe (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.exe (Policy File Creation and Management Tool)
    Creates and modifies the external policy configuration files that define your installation's Java security policy.
  rmid.exe (RMI activation system daemon)
    Starts the activation system daemon so that objects can be registered and activated in a Java virtual machine (JVM).
  rmiregistry.exe (Java remote object registry)
    Creates and starts a remote object registry on the specified port of the current host.
  tnameserv.exe (Common Object Request Broker Architecture (CORBA) transient naming service)
    Starts the CORBA transient naming service.

## SDK tools and reference information

A list of tools and reference information that is included with the standard SDK.

The following tools are part of the SDK and are located in the C:\Program Files\IBM\Java50\bin directory:
  appletviewer.exe (Java Applet Viewer)
    Tests and runs applets outside a Web browser.
  apt.exe (Annotation Processing Tool)
    Finds and executes annotation processors based on the annotations present in the set of specified source files being examined.
  extcheck.exe (Extcheck utility)
    Detects version conflicts between a target jar file and currently-installed extension jar files.
  HtmlConverter.exe (Java Plug-in HTML Converter)
    Converts an HTML page that contains applets to a format that can use the Java Plug-in.
  idlj.exe (IDL to Java Compiler)
    Generates Java bindings from a given IDL file.
  jar.exe (Java Archive Tool)
    Combines multiple files into a single Java Archive (JAR) file.
  jarsigner.exe (JAR Signing and Verification Tool)
    Generates signatures for JAR files and verifies the signatures of signed JAR files.
  javac.exe (Java Compiler)
    Compiles programs that are written in the Java programming language into bytecodes (compiled Java code).
  javadoc.exe (Java Documentation Generator)
    Generates HTML pages of API documentation from Java source files.
  javah.exe (C Header and Stub File Generator)
    Enables you to associate native methods with code written in the Java programming language.
  javap.exe (Class File Disassembler)
    Disassembles compiled files and can print a representation of the bytecodes.
  jconsole.exe (JConsole Monitoring and Management Tool)
    Experimental (unsupported). Monitors local and remote JVMs using a GUI. JMX-compliant.
  jdb.exe (Java Debugger)
    Helps debug your Java programs.
  jdmpview.exe (Cross-platform dump formatter)
    Analyzes dumps. For more information, see the Diagnostics Guide.
  native2ascii.exe (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.exe (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.
  serialver.exe (Serial Version Command)
    Returns the serialVersionUID for one or more classes in a format that is suitable for copying into an evolving class.
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
  The copyright notice for the SDK for Windows software.
License

  The License file, C:\Program Files\IBM\Java50\license, contains the license agreement for the SDK for Windows software. 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.

# Installing and configuring the SDK and Runtime Environment

Use the installation wizard or the compressed file to install the SDK. Configure the SDK using environment variables, command-line options, and properties files.

## Before you install

To install the SDK or the Runtime Environment package, download the relevant installation package. Ensure that you download all packages to the same directory and that there is enough space in your temporary directory.

The packages and their file names are listed in Installing the packages; do not change the packages' file names.

Before you begin to install, ensure that there is enough space in your C:\WINDOWS\TEMP directory to use during installation. The amount of temporary space required in the TEMP directory during installation is:

- SDK installable package: 130 MB
- Runtime Environment installable package: 85 MB

If you do not have enough temporary space, the installation program generates an error and terminates the installation. If you do have enough temporary space but still see this message, verify that the packages you are attempting to install were downloaded completely. You can do this by comparing the file sizes of your packages to the file sizes shown on the Web pages from which you downloaded the packages.

## Installing the packages

There are many packages you can install independently, including the SDK, the Runtime Environment, Javacomm, documentation, and demos.

The packages you can install are:

- SDK installable package: ibm-java2-sdk-50-win-i386.exe
- Runtime Environment installable package: ibm-java2-jre-50-win-i386.exe
- Runtime Environment installable package (IBM hardware only): ibm-java2-jre-50-ibmpc-win-i386.exe

Other packages are provided as compressed files:

- Runtime Environment package: ibm-java2-jre-50-win-i386.zip
- SDK package: ibm-java2-sdk-50-win-i386.zip
- Java Communications Application Programming Interface (API) for Windows package: ibm-java2-javacomm-50-win-i386.zip. See the section Installing Java Communications API from a compressed file for installation instructions.
- Documentation package: ibm-java2-docs-50-win-i386.zip
- Demos package: ibm-java2-demos-50-win-i386.zip

If you install the SDK or Runtime Environment from the compressed package, you will not be able to use Web Start or the Java plug-in, and the control panel will contain an Update tab which does not work.

### Attended (interactive) installation

Use the attended installation to install the SDK or JRE on a single client.

1. Launch ibm-java2-sdk-60-win-i386.exe (for the SDK) or ibm-java2-jre-60-win-i386.exe (for the Runtime Environment only).
2. Follow the instructions in the installation wizard.

   The Runtime Environment is installed by default in the directory C:\Program Files\IBM\Java50\jre.

   If you downloaded the SDK installable package, you can choose which components to install:

   - The SDK development tools (for example, the Java compiler).
   - The Runtime Environment.
   - The source code for the class libraries, used by some tools to debug applications.

   In the installation wizard, you are presented with the following options:

   - Typical - this option installs all three components.
   - Compact - this option installs the Runtime Environment only.
   - Custom - this option lets you choose which components to install.

   On Windows Vista, there might be a delay after selecting the installation language.

   If the installation fails with the error message "Error applying transform", the Windows Installer configuration information has become corrupted. To fix the error, use the Windows Installer Cleanup Utility from http://support.microsoft.com/kb/290301 to remove the corrupted Windows Installer configuration information.

### Installing the Runtime Environment as the system Java Virtual Machine

When you install the Runtime Environment (either as part of the SDK installable package or from the Runtime Environment installable package), you are asked whether you want to install the Runtime Environment as the system Java Virtual Machine (JVM). If you do install it as the system JVM, the installation program copies the java.exe and javaw.exe launchers into the Windows system directory.

If a version of java.exe or javaw.exe currently exists in the Windows system directory, you are prompted to overwrite the existing version with the current version. Installing these files into the Windows system directory makes this Runtime Environment the default JVM for the system. In addition, the "Current Version" registry key is set to match this installation.

Note: Installing the Runtime Environment as the system JVM copies only java.exe and javaw.exe into the Windows system directory. No other programs (such as javac.exe or appletviewer.exe) are copied.

### Unattended installation

Use the unattended installation to install the SDK or JRE on multiple clients.

To create an unattended installation, you must first complete an attended installation and create a response file (setup.iss) that records the choices you made during installation. The response file you create must be correct for the computers on which you plan to use it. If necessary, create several response files to use for installing the packages on computers that have different configurations.

To create a response file while running the installation, at a command prompt type:

    ibm-java2-sdk-50-win-i386 /r

or

    ibm-java2-jre-50-win-i386 /r

Depending on your Windows product, a response file (setup.iss) is created in either the C:\Windows or C:\Winnt directory.

The following message might occur during an interactive installation:

    Another Java Runtime Environment is currently
    installed as the System JVM. Select Yes to
    overwrite this version or No to exit this
    installation.

If this message is displayed, click No and exit from the installation. Go to the Windows system directory and delete the following two files:

- java.exe
- javaw.exe

After you have deleted the files, restart the interactive installation using the command shown at the beginning of this section.

On the system on which you will run the unattended installation, copy the setup.iss response file to the C:\Windows directory. After you have copied the file, at a command prompt type:

    ibm-java2-sdk-50-win-i386 /s /f1c:\Windows\setup.iss /f2c:\setup.log
    ibm-java2-jre-50-win-i386 /s /f1c:\Windows\setup.iss /f2c:\setup.log

Note:

1. There are no spaces after `/f1` or `/f2`.
2. The `/f1` flag specifies the name and location of the response file. The `/f2` flag specifies the name and location of the log file.

If the installation is successful, the log file contains the string `ResultCode=0`. If the installation is not successful, the log file will contain a different result code.

## Enabling the IBM Accessibility Bridge

The IBM Accessibility Bridge is installed but disabled by default. To enable the IBM Accessibility Bridge, uncomment the assistive_technologies entry in the Accessibility.properties file.

The Accessibility.properties file is in the jre/lib directory. Delete the # from the beginning of the following line:

    #assistive_technologies=JawBridge

This Web site tells you more about the Accessibility Utilities:

http://java.sun.com/products/jfc/accessibility.html

## Disabling Java Accessibility support

You can disable Java Accessibility support to improve the JVM loading performance of Java applications that do not provide Java assistive technology support, especially over network links. To disable Java Accessibility support, set the JAVA_ASSISTIVE environment variable to OFF.

An assistive technology, such as JawBridge, is not available if this environment variable is set to OFF, even if the technology is enabled in the Accessibility.properties file.

## Information for European language users

In Windows, a process has two codepages: the ANSI (or Windows) code page and the OEM (or DOS) code page. The javaw command always uses the ANSI code page unless the console.encoding system property is set.

The command window normally uses the OEM code page. Java console output uses the code page of the command window from which Java is started. However, the javaw command always uses the ANSI code page. You specify the code page to use for console output with the -Dconsole.encoding option on the java or javaw launcher. For example, -Dconsole.encoding=Cp1252 causes all console output to be in the Windows ANSI Latin1 code page (1252).

## Setting the path

If you alter the PATH environment variable, you will override any existing Java launchers in your path.

The PATH environment variable enables Windows to find programs and utilities, such as javac, java, and javadoc, from any current directory. To display the current value of your PATH, type the following at a command prompt:

    echo %PATH%

To add the Java launchers to your path:

1. If you installed the SDK or Runtime Environment in C:\Program Files\IBM\Java50\ add the following directories to the PATH environment variable:
   - C:\Program Files\IBM\Java50\bin (SDK only)
   - C:\Program Files\IBM\Java50\jre\bin (SDK and Runtime Environment)
2. Close and reopen any command prompt windows to activate the new PATH environment variable.

After setting the path, you can run a tool by typing its name at a command prompt from any directory. For example, to compile the file Myfile.Java, at a command prompt, type:

    javac Myfile.Java

## Setting the class path

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

You need to set the class path explicitly only if:

- 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 environment variable, type the following command at a command 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 command prompt.

## Uninstallation

Use the Windows Add/Remove programs utility to uninstall the SDK or Runtime Environment.

To uninstall the SDK, whether you installed using attended or unattended installation:

1. Double-click My Computer on the Windows desktop.
2. Double-click Control Panel.
3. Double-click Add/Remove Programs.
4. Click IBM 32-bit SDK for Java 2 v5.0 in the list, and then click Change/Remove.
5. Click OK.

This procedure removes all of the packages that are installed with the Installer. It does not remove the Java Communications API package (see Uninstalling Java Communications API) or any additional files that have been extracted from the compressed packages.

Note: Warning messages might be displayed notifying you that not all files, or registry entries, or both, were removed. These warnings are issued because Windows believes that certain files are still in use; these files, or registry entries, or both, will be removed during the next reboot.

When you maintain multiple installations between the IBM 32-bit SDK for Windows, v5.0, and versions at V1.3.1 or earlier, if you uninstall the earlier version while a version v5.0 is still installed on the system, the V1.3.1 uninstaller removes the following registry keys, and all the subkeys, that are required by the v5.0 version, thereby corrupting the v5.0 installation:

- HKEY_LOCAL_MACHINE/Software/IBM/Java2 Runtime Environment
- HKEY_LOCAL_MACHINE/Software/IBM/Java Development Kit

Therefore, reinstall v5.0 after uninstalling the V1.3.1 version. This uninstaller limitation has been fixed for V1.4.0 and any subsequent release.

# Running Java applications

Java applications can be started using the java launcher or through JNI. Settings are passed to a Java application using command-line arguments, environment variables, and properties files.

## The java and javaw commands

A brief overview of the java and javaw commands.

### Purpose

The java and javaw tools launch a Java application by starting a Java Runtime Environment and loading a specified class.

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 be displayed. The javaw launcher displays a dialog box with error information if a launch fails.

### Usage

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

The java and javaw commands have the following syntax:

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

### Parameters

[options]
  Command-line options to be passed to the runtime environment.
<class>
  Startup class. The class must contain a main() method.
<file.jar>
  Name of the jar file to invoke. It is used only with the -jar option. The named jar file must contain class and resource files for the application, with the startup class indicated by the Main-Class manifest header.
[arguments ...]
  Command-line arguments to be passed to the main() function of the startup class.

### Obtaining version information

The IBM build and version number for your Java installation is obtained using the -version option.

1. Open a command prompt.
2. Type the following command:

       java -version

   You will see information similar to:

       java version "1.5.0"
       Java(TM) 2 Runtime Environment, Standard Edition (build pxi32dev-20051104)
       IBM J9 VM (build 2.3, J2RE 1.5.0 IBM J9 2.3 Linux x86-32 j9vmxi3223-20051103 (JIT enabled)
       J9VM - 20051027_03723_lHdSMR
       JIT  - 20051027_1437_r8
       GC   - 20051020_AA)
       JCL  - 20051102

   Exact build dates and versions will change.

### Specifying Java options and system properties

You can specify Java options and system properties on the command line, by using an options file, or by using an environment variable.

These methods of specifying Java options are listed in order of precedence:

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=<file>.
3. By creating an environment variable called IBM_JAVA_OPTIONS containing the options. For example:

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

Rightmost options on the command line have precedence over leftmost options; for example, if you specify:

    java -Xint -Xjit myClass

The -Xjit option takes precedence.

### Standard options

The definitions for the standard options.

-agentlib:<libname>[=<options>]
  Loads a 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>]
  Loads a native agent library by full path name.
-assert
  Prints help on assert-related options.
-cp <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 the CLASSPATH environment variable is not set, the user class path is, by default, the current directory (.).
-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 the CLASSPATH environment variable is not set, the user class path is, by default, the current directory (.).
-D<property name>=<value>
  Sets a system property.
-help or -?
  Prints a usage message.
-javaagent:<jarpath>[=<options>]
  Load a 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:<option>
  Enables verbose output. The available options are:
  class
    Writes an entry to stderr for each class that is loaded.
  gc
    Writes verbose garbage collection information to stderr. Use -Xverbosegclog to control the output. See the Diagnostics Guide for more information.
  jni
    Writes information to stderr describing the JNI services called by the application and JVM.
  sizes
    Writes information to stderr describing the active memory usage settings.
  stack
    Writes information to stderr describing the Java and C stack usage for each thread.
-version
  Prints product version.
-version:<value>
  Requires the specified version to run, for example "1.5".
-X
  Prints help on nonstandard options.

### Globalization of the java command

The java and javaw launchers accept arguments and class names containing 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, use the -Xargencoding command-line option.

-Xargencoding
  Use argument encoding. To specify a Unicode character, use escape sequences in the form `\u####`, where # is a hexadecimal digit (0 to 9, A to F).
-Xargencoding:utf8
  Use UTF8 encoding.
-Xargencoding:latin
  Use ISO8859_1 encoding.

For example, 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 provide translated 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 is in English.

## Executing a Java file automatically

To set a Java class or jar file to start automatically from the Windows explorer, use the Tools -> Folder Options -> File Type option of Windows Explorer.

Alternatively, at a command prompt type:

    assoc .class=javaclass
    ftype javaclass=C:\Program Files\IBM\Java50\jre\bin\java.exe''%l''%*'

Note:

1. The `%l` is the number 1 and not the letter l.
2. If your Java is installed in a directory other than C:\Program Files\IBM\Java50\, substitute your installation directory.

## Running Java applications with native assistive technologies

Sun provides the Java Access Bridge to give native Windows assistive technologies, such as screen readers, access to the Java Accessibility support in a Java application. These native Windows assistive technologies must support calls to the Java Access Bridge.

The Java Access Bridge available from Sun includes an installer, which places five files in the correct directories: access-bridge.jar, jaccess.jar, accessibility.properties, JavaAccessBridge.dll and WindowsAccessBridge.dll. IBM ships a copy of jaccess.jar in the appropriate directory for use with JawBridge.

If you have already enabled the IBM Accessibility Bridge (JawBridge), which allows the Windows 2000 Magnifier to function with Swing applications, and you want to enable JawBridge at the same time as the Java Access Bridge, edit the line in the accessibility.properties file to read:

    assistive_technologies=com.sun.java.accessibility.AccessBridge,JawBridge

Comment out the line by inserting a leading `#` to deactivate both bridges. This Web site tells you how to how to download the Java Access Bridge:

http://java.sun.com/products/jfc/accessibility.html.

## 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.

Both the IBM SDK and Runtime Environment include the JIT, which is enabled by default in user applications and SDK tools. Normally, you do not invoke the JIT explicitly; the compilation of Java bytecode to machine code occurs transparently. You can disable the JIT to help isolate a problem. If a problem occurs when executing a Java application or an applet, you can disable the JIT to help isolate the problem. Disabling the JIT is a temporary measure only; the JIT is required to optimize performance.

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

### Disabling the JIT

The JIT can be disabled in a number of different ways. Both command-line options override the JAVA_COMPILER environment variable.

Turning off the JIT is a temporary measure which can help isolate problems when debugging Java applications.

- Set the JAVA_COMPILER environment variable to `NONE` or the empty string before running the java application. At the command prompt where the application is run, type:

      set JAVA_COMPILER=NONE

  You can also permanently set JAVA_COMPILER by using the graphical user interface. Open Control Panel, select System, and on the Advanced tab, select Environment Variables.
- Use the -D option on the JVM command line to set the java.compiler property to `NONE` or the empty string. Type the following at a command prompt:

      java -Djava.compiler=NONE <class>

- Use the -Xint option on the JVM command line. Type the following at a command prompt:

      java -Xint <class>

### Enabling the JIT

The JIT is enabled by default. You can explicitly enable the JIT in a number of different ways. Both command-line options override the JAVA_COMPILER environment variable.

- Set the JAVA_COMPILER environment variable to `jitc` before running the Java application. At the command prompt where the application is run, enter:

      set JAVA_COMPILER=jitc

  You can also permanently set JAVA_COMPILER by using the graphical user interface. Open Control Panel, select System, and on the Advanced tab, select Environment Variables. If the JAVA_COMPILER environment variable is an empty string, the JIT remains disabled. To disable the environment variable, at the command prompt, enter:

      set JAVA_COMPILER=

- Use the -D option on the JVM command line to set the java.compiler property to `jitc`. At a command prompt, enter:

      java -Djava.compiler=jitc <class>

- Use the -Xjit option on the JVM command line. Do not specify the -Xint option at the same time. At a command prompt, enter:

      java -Xjit <class>

### Determining whether the JIT is enabled

You can determine the status of the JIT using the -version option.

Run the java launcher with the -version option. Enter 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 JVM.

When the Garbage Collector receives a request for storage, unused memory in the heap is set aside in a process called "allocation". The Garbage Collector also checks for areas of memory that are no longer referenced, and releases them for reuse. This is known as "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 optimizing the way garbage collection is carried out, potentially reducing the effect on your application.

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

### Garbage collection options

The -Xgcpolicy options control the behavior of the Garbage Collector. They make trade-offs 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.) Delivers very high throughput to applications, but at the cost of occasional pauses.
-Xgcpolicy:optavgpause
  Reduces the time spent in 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.
-Xgcpolicy:gencon
  Requests the combined use of concurrent and generational GC to help minimize the time that is spent in any garbage collection pause.

### 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 and 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 garbage collection concentrates on only the objects that are most likely to be recyclable, you can further reduce pause times for some applications. Generational GC reduces pause times 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 can 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 garbage collection options are used; and, if requests for more heap space continue to be made, the application might receive an OutOfMemoryError, which results in JVM termination if the exception is not caught and handled. At this point, the JVM produces a Javadump file for use during diagnostics. In these conditions, you are recommended either to increase the heap size by using the -Xmx option or to reduce the number of objects in use.

For more information, see the Diagnostics Guide.

## 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. |From |1 January 2008, Cyprus and Malta also have the Euro as the default |currency.

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.

## Support for Serbian locale

From Service Refresh 5, the following new locale is added: Serbia (SE), with three new locale variations.

The locale variations are:

- sr_RS
- sr_Cyrl_RS
- sr_Latn_RS

The existing locale variations for the former Serbia and Montenegro are maintained as before. The 3-letter country code SRB, corresponding to the 2-letter country code RC, is also added.

# Using the SDK to develop Java applications

The SDK for Windows contains many tools and libraries required for Java software development.

See SDK tools and reference information for details of the tools available.

## Transforming XML documents

The IBM SDK contains the XSLT4J processor and the XML4J parser. 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 IBM SDK contains the XSLT4J processor and the XML4J parser that conform to the JAXP 1.3 specification.

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 use the XSLT Compiling processor, you can either:

- Change the entry in the jaxp.properties file (located in C:\Program Files\IBM\Java50\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 C:\Program Files\IBM\Java50\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 C:\Program Files\IBM\Java50\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 Xerces (before 2.0) or Xalan (before 2.3) in the endorsed override, you might get a NullPointerException when you start 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 C:\Program Files\IBM\Java50\jre\lib.
- Uncomment the entries in the jaxp.properties file in C:\Program Files\IBM\Java50\jre\lib.
- Set the system property for javax.xml.parsers.SAXParserFactory, javax.xml.parsers.DocumentBuilderFactory, or javax.xml.transform.TransformerFactory using the -D command-line option.
- 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.
- Explicitly set the SAX parser, Document builder, or Transformer factory using the IBM_JAVA_OPTIONS environment variable. For example:

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

  or

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

  or

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

## 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 Windows.

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

### Java Debugger (JDB)

The Java Debugger (JDB) is included in the SDK for Windows. 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_shmem,server=y,address=<port> <class>

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

       jdb -attach <port>

   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 start.

For more information about JDB options, type:

    jdb -help

For more information 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 with the following options:

       java -Xdebug -Xrunjdwp:transport=dt_shmem,server=y,address=<port> <class>

   The JVM starts up, but suspends execution before it starts the Java application.
2. Attach the debugger to the remote JVM:

       jdb -connect com.sun.jdi.SocketAttach:hostname=<host>,port=<port>

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 about 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 property from within your application code using the call:

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

## 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.

Where a signal is generated externally (for example, when you enter CTRL-BREAK), a new thread is created for the signal handler. In this case, the JVM signal handler performs its processing and 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.

For exception and error signals, the JVM either:

- Handles the condition and recovers, or
- Enters a controlled shutdown sequence where it:
  1. Produces dumps, 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 for a clean shutdown

For information about writing a launcher that specifies the above hooks, see: http://www.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:

1. Calls your application's signal handler for that signal.
2. Runs all application shutdown hooks.
3. Calls any application-installed exit hook.
4. 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 SIGBREAK, which causes a Javadump to be generated.

### Signals used by the JVM

The types of signals are Interrupts, and Controls.

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
--- | --- | --- | ---
SIGINT (2) | Interrupt | Interactive attention (CTRL-C). JVM exits normally. | Yes
SIGTERM (15) | Interrupt | Termination request. JVM will exit normally. | Yes
SIGBREAK | Control | A break signal from a terminal. By default, this triggers a Javadump. | Yes

The IBM JVM uses structured exception handling and the SetConsoleCtrlHandler() API. These are disabled with -Xrs. -Xnosigchain is ignored on Windows.

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.

The signals 2 (SIGINT) and 15 (SIGTERM) on JVM threads causes the JVM to shut down; therefore, an application signal handler should not attempt to recover from this signal 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 jsig.dll before msvcrt.dll. The jsig.dll library ensures that calls to signal() 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.

The libjsig.dll 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.

The environment variable JAVA_HOME should be set to the location of the SDK, for example,C:\Program Files\IBM\Java50\.

To use jsig.dll, link it with the application that creates or embeds a JVM.

## Writing JNI applications

Valid JNI version numbers that native programs can specify on the JNI_CreateJavaVM() API call are: JNI_VERSION_1_2(0x00010002) and JNI_VERSION_1_4(0x00010004).

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

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 JSE 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.

## 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.

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.

Large page allocations will only succeed if the local administrative policy for the JVM user is configured to allow "Lock pages in memory".

## CORBA support

The Java Platform, Standard Edition (J2SE) supports, at a minimum, the specifications that are defined in the compliance document from Sun. In some cases, the IBM J2SE ORB supports more recent versions of the specifications.

The minimum specifications supported are defined in the Official Specifications for CORBA support in J2SE.

### 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.

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 that ORB services can use to 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 Properties

com.ibm.CORBA.Debug=true
  Turns on ORB tracing.
com.ibm.CORBA.CommTrace=true
  Adds GIOP messages (sent and received) to the trace.
com.ibm.CORBA.Debug.Output=<file>
  Specify the trace output file. By default, this is of the form orbtrc.DDMMYYYY.HHmm.SS.txt.

#### Example of ORB tracing

For example, to trace events and formatted GIOP messages from the command line, type:

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

#### Limitations

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 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 ORB can be tuned to work well with your specific network. The properties required to tune the ORB are described here.

com.ibm.CORBA.FragmentSize=<size in bytes>
  Used to control GIOP 1.2 fragmentation. The default size is 1024 bytes.

  To disable fragmentation, set the fragment size to 0 bytes:

      java -Dcom.ibm.CORBA.FragmentSize=0 <myapp>

com.ibm.CORBA.RequestTimeout=<time in seconds>
  Sets the maximum time to wait for a CORBA Request. By default the ORB waits indefinitely. Do not set the timeout too low to avoid connections ending unnecessarily.
com.ibm.CORBA.LocateRequestTimeout=<time in seconds>
  Set the maximum time to wait for a CORBA LocateRequest. By default the ORB waits indefinitely.
com.ibm.CORBA.ListenerPort=<port number>
  Set the port for the ORB to read incoming requests on. If this property is set, the ORB starts listening as soon as it is initialized. Otherwise, it starts listening only when required.

### Java security permissions for the ORB

When running with a Java SecurityManager, invocation of some methods in the CORBA API classes might cause permission checks to be made, which might result in a SecurityException. If your program uses any of these methods, ensure that it is granted the necessary permissions.

Table 2. Methods affected when running with Java 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

### ORB implementation classes

A list of the 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 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 Interface Description Language (IDL) program (demo\rmi-iiop\idl)
- The Java Language to IDL Mapping document is a detailed technical specification of RMI-IIOP.

## 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

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

## Enhanced BigDecimal

From Java 5.0, the IBM BigDecimal class has been adopted by Sun as java.math.BigDecimal. The com.ibm.math.BigDecimal class is reserved for possible future use by IBM and is currently deprecated. 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. The two classes do not serialize.

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.*;`.

# Plug-in, Applet Viewer and Web Start

The Java plug-in is used to run Java applications within the browser. The appletviewer is used to test applications designed to be run in a browser. Java Web Start is used to deploy desktop Java applications over a network, and provides a mechanism for keeping them up-to-date.

## Using the Java Plug-in

The Java Plug-in is a Web browser Plug-in. You use the Java Plug-in, to run applets 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

The Java plug-in supports Internet Explorer, Netscape, Mozilla, and Mozilla Firefox.

|

| |

Table 3. Browsers supported by the Java plug-in
|Browser | | Supported Versions |
--- | ---
|Internet Explorer | | 6.0 SP1, 7.0 |
|Netscape | | 7.2 |
|Mozilla | | 1.7, 1.8 |
|Firefox | | 2.0 |
|

|

Later minor releases of browsers are also supported.

|

Internet |Explorer 5.01, the default browser on Windows 2000, is not supported.

### Secure Static Versioning (SSV) support

Static versioning allows applets to request a specific JVM version to be run under. Because this capability also allows applets to exploit old security vulnerabilities on systems that have been upgraded to a new JVM, Secure Static Versioning is now used on Internet Explorer.

By default, all applets are run under the latest installed JVM. To disable SSV, set the following registry key to 0:

HKEY_LOCAL_MACHINE\Software\IBM\Java Deployment\Policy\EnableSecureStaticVersioning

If the registry key does not exist, SSV is enabled.

SSV will not function if third-party browser extensions are disabled in Internet Explorer. To enable third-party browser extensions:

1. Open Internet Explorer.
2. Click Tools -> Internet Options.
3. Click the Advanced tab.
4. Select the Enable third-party browser extensions check box.

If third-party browser extensions are disabled after SSV has been used, SSV will continue to function.

To provide protection for the Mozilla and Firefox browsers, the Plug-in for Internet Explorer will automatically remove all Java Plug-ins from the Mozilla and Firefox Plug-in directories. This happens each time an applet is run under Internet Explorer.

To reinstall a Java Plug-in for Mozilla or Firefox, use the Java Control Panel.

### 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.InvalidStateException is thrown for some of these functions.
- A sun.plugin.dom.exception.NotSupportedException 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.

Some 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. To manually specify which encoding you want to use to parse the HTML file:

Internet Explorer 5/6
  View Menu -> Encoding
Netscape 4
  View Menu -> Character Set
Netscape 6
  View Menu -> Character Coding

## 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

Use the following command to run an applet with the Applet Viewer.

From a command prompt, enter:

       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 command prompt:

    appletviewer <demo>\GraphLayout\example1.html

Where <demo> is replaced by the full path into which you unzipped the demo package.

To invoke the Applet Viewer on a Web page, type at a command 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

### Unique CLSIDs

A unique set of CLSIDs have been added to the IBM JVM from Version 5.0 Service Refresh 1.

The following are the new CLSIDs:

    1ACECAFE-0015-0000-0000-ABCDEFFEDCBA
    1ACECAFE-0015-0000-0000-ABCDEFFEDCBB

You can refer to the above CLSIDs in the OBJECT Tag for your applets.

In addition, the following existing CLSIDs are also supported for compatibility purposes:

    CAFEEFAC-0015-0000-0000-ABCDEFFEDCBA
    CAFEEFAC-0015-0000-0000-ABCDEFFEDCBB

### Debugging applets with the Applet Viewer

You can debug applets by using the -debug option of the Applet Viewer.

For example:

    cd <demo>\TicTacToe
    appletviewer -debug example1.html

Where <demo> is replaced by the full path into which you unzipped the demo package.

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

## Using Web Start

Java Web Start is used for Java application deployment.

Web Start allows you to launch and manage applications directly from the Web. Applications are cached to minimize installation times. Applications are automatically upgraded when new versions become available.

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 about 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

Web Start can be run from a Web page or the command line. Web Start applications are stored in the Java Application Cache.

You can invoke Web Start in a number of different ways.

- Select a link on a Web page that refers to a .jnlp file.
- At a command prompt, type:

      javaws <URL>

  Where <URL> is the location of a .jnlp file.
- If you have used Java Web Start to open the application in the past, you can use the Java Application Cache Viewer. At a command prompt, type:

      C:\Program Files\IBM\Java50\jre\bin\javaws

  All Java Web Start applications are stored in the Java Application Cache. An application is only downloaded if the latest version is not in the cache.

### WebStart Secure Static Versioning

Static versioning allows Web Start applications to request a specific JVM version to be run under. Because this capability also allows applications to exploit old security vulnerabilities on systems which have been upgraded to a new JVM, Secure Static Versioning (SSV) is now used by default.

With SSV, the user will be warned before running any unsigned Web Start application that requests a specific JVM be used. Signed applications and applications which request the latest version of the JVM run as normal.

You can disable SSV by setting the deployment.javaws.ssv.enabled property in the deployment.properties file to false.

## Shipping Java applications

Java applications typically consist of class, resource, and data files.

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 Windows. The SDK for Windows software contains a Runtime Environment. However, you cannot assume that your users have the SDK for Windows software installed.

Your SDK for Windows 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 Windows is installed on the target machine.

# Class data sharing between JVMs

Class data sharing allows multiple JVMs to share a single space in memory.

The Java Virtual Machine (JVM) allows you to share data between JVMs by storing it in a cache in shared memory. Sharing reduces the overall virtual memory consumption when more than one JVM shares a cache. Sharing also reduces the startup time for a JVM after the cache has been created. The shared class cache is independent of any active JVM and persists beyond the lifetime of the JVM that created the cache.

A shared cache can contain:

- Bootstrap classes
- Application classes
- Metadata that describes the classes

## Overview of class data sharing

Class data sharing provides a transparent method of reducing memory footprint and improving JVM start-up time.

### Enabling class data sharing

Enable class data sharing by using the -Xshareclasses option when starting a JVM. The JVM will connect to an existing cache or create a new cache if one does not exist.

All bootstrap and application classes loaded by the JVM are shared by default. Custom classloaders share classes automatically if they extend the application classloader; otherwise, they must use the Java Helper API provided with the JVM to access the cache. (See Adapting custom classloaders to share classes.)

### Cache access

Any JVM connected to a cache can update the cache. Any number of JVMs can concurrently read from the cache, even while another JVM is writing to it.

You must take care if runtime bytecode modification is being used. See Runtime bytecode modification for more information.

### Dynamic updating of the cache

Because the shared class cache persists beyond the lifetime of any JVM, 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.

### Cache security

Access to the shared class cache is limited by operating system permissions and Java security permissions. Only a classloader that has registered to share class data can update the shared class cache.

If a Java SecurityManager is installed, classloaders, excluding the default bootstrap, application, and extension classloaders, 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 JVM can connect to only one cache at any one time.

You may override the default cache size on startup using -Xscmx<n><size>, 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. See Enabling and configuring class data sharing, or use -Xshareclasses:help to see a list of available suboptions.

## Enabling and configuring class data sharing

Class data sharing and the cache management utilities are controlled using command-line options to the java launcher.

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

-Xscmx<size>
  Specifies cache size. This option applies only if a cache is being created and no cache of the same name exists. The default cache size is platform-dependent. You can find out the size value being used by adding -verbose:sizes as a command-line argument. The minimum cache size is 4 KB. The maximum cache size is also platform-dependent. (See Cache size limits.)
-Xshareclasses:<suboption>[,<suboption>...]
  Enables class data 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. When running cache utilities, the message "Could not create the Java virtual machine" is expected. Cache utilities do not create the virtual machine.

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

  help
    Lists all the command-line suboptions.
  name=<name>
    Connects to a cache of a given name, creating the cache if it does not already exist. Also used to indicate the cache that is to be modified by cache utilities, for example, destroy. Use the listAllCaches utility to show which named caches are currently available. If you do not specify a name, the default name "sharedcc_%u" is used. %u in the cache name will insert the current user name.
  verbose
    Enables verbose output, which provides overall status on the shared class cache and more detailed error messages.
  verboseIO
    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.
  verboseHelper
    Enables verbose output for the Java Helper API. This output shows you how the Helper API is used by your ClassLoader.
  silent
    Turns off all shared classes messages, including error messages. Unrecoverable error messages, which prevent the JVM from initializing, will be displayed.
  nonfatal
    Allows the JVM to start even if class data sharing fails. Normal behavior for the JVM is to refuse to start if class data sharing fails. If nonfatal is selected and the shared classes cache fails to initialize, the JVM starts without class data sharing.
  none
    Can be added to the end of a command line to disable class data sharing. This suboption overrides class sharing arguments found earlier on the command line.
  modified=<modified context>
    Used when a JVMTI agent is installed that might modify bytecode at runtime. If you do not specify this suboption and a bytecode modification agent is installed, classes will be safely shared with an extra performance cost. 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. See Runtime bytecode modification for more information.
  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>
    Destroys all caches that have been unused for the time specified before loading shared classes. This is not a utility option because it does not cause the JVM to exit. On NTFS file systems, the expire option is accurate to the nearest hour.
  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. 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 and can be reused. See the Diagnostics Guide for more information.
  printAllStats (Utility option)

    Displays detailed information for the cache specified by the name, cacheDir, and nonpersistent suboptions. Every class is listed in chronological order along with a reference to the location from which it was loaded. AOT code for class methods is also listed.

    See the Diagnostics Guide for more information.

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

An overview of the lifecycle of a shared class data cache including examples of the cache management utilities.

To enable class data sharing, add -Xshareclasses[:name=<name>] to your application command line.

The JVM 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 JVMs 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 JVM has terminated or in another command window.)

For more feedback on cache usage while the JVM is running, use the verbose suboption. For example, `java -Xshareclasses:[name=<name>],verbose`.

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

To delete the cache created, run `java -Xshareclasses:[name=<name>],destroy`. 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 JVM, it is best to 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 JVMs 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 any JVMs using the verbose suboption. All JVMs sharing the full cache will then 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 data sharing is particularly useful on systems that use more than one JVM running similar code; the system benefits from reduced virtual memory consumption. It is also useful on systems that frequently start up and shut down JVMs, which benefit from the improvement in startup time.

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

Duplicate classes are consolidated within the shared class cache. For example, class A loaded from myClasses.jar and class A loaded from myOtherClasses.jar (with identical content) is stored only once in the cache. The printAllStats utility shows multiple entries for duplicated classes, with each entry pointing to the same class.

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

## Considerations and limitations of using class data sharing

Factors to consider when deploying class data sharing in a product and using class data sharing in a development environment.

### Cache size limits

The maximum theoretical cache size is 2 GB. The size of the cache you can specify is limited by the amount of available disk space and available virtual address space.

The cache is limited by the following factors:

- Available disk space. A file is created to store the class data in a directory called javasharedresources. This directory is created in the user's profile directory, so by default it will be in C:\Documents and Settings\<username>\Local Settings\Application Data\javasharedresources\. The shared file is deleted every time Windows is restarted.
- Available virtual address space. 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 reduces the size of the shared classes cache you can create.

### Runtime bytecode modification

Any JVM using a JVM Tool Interface (JVMTI) agent that can modify bytecode data should use the modified=<modified_context> suboption if it wants to share the modified classes with another JVM.

The modified context is a user-specified descriptor that describes the type of modification being performed. The modified context partitions the cache so that all JVMs running under the same context share a partition.

This partitioning allows JVMs that are not using modified bytecode to safely share a cache with those that are using modified bytecode. All JVMs 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 JVM. Any modification must be predictable because classes loaded from the shared class cache cannot be modified again by the agent.

If a JVMTI agent is used without a modification context, classes are still safely shared by the JVM, but with a small impact on performance. Using a modification context with a JVMTI agent avoids the need for extra checks and therefore has no impact on performance. A custom ClassLoader that extends java.net.URLClassLoader and modifies bytecode at load time without using JVMTI automatically stores that modified bytecode in the cache, but the cache does not treat the bytecode as modified. Any other VM sharing that cache loads the modified classes. The modified=<modification_context> suboption can be used in the same way as with JVMTI agents to partition modified bytecode in the cache. If a custom ClassLoader needs to make unpredictable load-time modifications to classes, that ClassLoader must not attempt to use class data sharing.

See the Diagnostics Guide for more detail on this topic.

### Operating system limitations

You cannot share classes between 32- and 64-bit JVMs. There must be temporary disk space available to hold cache information. Cache permissions are enforced by the operating system.

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

The shared class cache requires disk space to store identification information about the caches that exist on the system. This information is in the user profile directory. If the identification information directory is deleted, the JVM cannot identify the shared classes on the system and must re-create the cache.

The permissions for accessing a shared class 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 data sharing and the running application uses its own class loaders, these class loaders 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, it is prevented from sharing classes. You cannot change the permissions of the default bootstrap, application, or extension class loaders.

## Adapting custom classloaders to share classes

Any classloader that extends java.net.URLClassLoader can share classes without modification. Classloaders that do not extend java.net.URLClassLoader need to be adapted to share class data.

All custom classloaders 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 docs/apidoc.zip file.

See the Diagnostics Guide for more information about how to use these interfaces.

# Using Java Communications API (JavaComm)

The Java Communications (API) package (JavaComm) is an optional package provided for use with the Runtime Environment for Windows. 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.

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 using event notification
- Receive bean-style events describing state changes on the port

## Installing Java Communications API from a compressed file

Make sure that the SDK or Runtime Environment is installed before you install the Java Communications API.

To install the Java Communications API from a compressed file:

1. Put the Java Communications API compressed file, ibm-java2-javacomm-50-win-i386.zip, in the directory where the SDK or Runtime Environment is installed. If you installed to the default directory, this is C:\Program Files\IBM\Java50\.
2. Extract the compressed file. The Java Communications API is extracted into subdirectories within the existing directory.

## Configuring Java Communications API

To use the Java Communications API, you must change the access mode of serial and parallel ports, and set the PATH if you did not set it when you installed Java.

See Setting the path.

### 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.

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.

## Printing limitation with the Java Communications API

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

## Uninstalling Java Communications API

To uninstall the Java Communications API, delete the following files from the directory where you installed the Runtime Environment:

- jre\lib\ext\comm.jar
- jre\bin\ibmcomm.dll
- jre\lib\javax.comm.properties
- docs\javacomm\License.html

By default, the Runtime Environment is installed in the C:\Program Files\IBM\Java50\ directory.

## Java Communications API documentation

You can find API documentation and samples for Java Communications API at the Sun Web site.

http://java.sun.com/products/javacomm/.

# Service and support for independent software vendors

Contact points for service:

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.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 using screen readers.

To change the font sizes in the user guides, use the function that is supplied with your browser, typically 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.ibm.com/developerworks/java/jdk/additional/.

## 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 JComboBox does not change value until an item is selected. This is the correct behavior for this release and improves accessibility and usability by ensuring that the keyboard traversal behavior is consistent with mouse traversal behavior.

## Web Start accessibility

From Version 5.0, Java Web Start contains several accessibility and usability improvements, 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, Application Data\IBM\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.

## JConsole accessibility

To enable JConsole to run on Windows with the Windows look and feel, set the swing.defaultlaf system property.

    JConsole -J-Dswing.defaultlaf=com.sun.java.swing.plaf.windows.WindowsLookAndFeel

This will enable the High Contrast color schemes available in Windows to be adopted by JConsole.

# General note about security

You can obtain JCE unrestricted jurisdiction policy files from http://www.ibm.com/developerworks/java/jdk/security/index.html. Documentation about the IBM security packages JCE, JCEFIPS, JSSE2, JSSEFIPS, JGSS, JAAS and hardware cryptography is also available at this Web site.

# Any comments on this user guide?

If you have any comments about this user guide, contact us through one of the following channels. 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: +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.

# Appendix A. Nonstandard options

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

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

For options that take a <percentage> parameter, use a number from 0 to 1. For example, 50% is 0.5.

-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 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. By default, no checking is performed.
-Xcheck:nabounds
  Performs additional checks for JNI functions. By default, no checking is performed.
-Xclassgc
  Enables collection of class objects at every garbage collection. See also -Xnoclassgc. By default, this option is enabled.
-Xcodecache<size>
  Sets the unit size of which memory blocks are allocated to store native code of compiled Java methods. An appropriate size can be chosen for the application being run. By default, this is selected internally according to the CPU architecture and the capability of your system.
-Xcompactexplicitgc
  Performs a compaction for every call to `System.gc()`. See also -Xnocompactexplicitgc. By default, compaction occurs only when triggered internally.
-Xcompactgc
  Performs a compaction for every garbage collection. 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. See Debugging Java applications for more information. Specifying -Xrunjdwp provides the same support.
-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 GC is taking 95% of the available time. This behavior is the default.
-Xenableexplicitgc
  Signals to the VM that calls to System.gc() should trigger a garbage collection. This 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>
  Controls the behavior of the Garbage Collector. See Garbage collection options for more information.
-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. Use the -verbose:sizes option to output the value that the VM is using.
-Xjit[:<suboption>,<suboption>...]
  Enables the JIT. For details of the sub-options, 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<percentage>
  <percentage> 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<percentage>
  <percentage> 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 (Windows 2003)
  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'`. Large pages are supported by systems running Windows 2003, where the operating system has been set up to use large pages. 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<percentage>
  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. 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. Use the -verbose:sizes option to output the value that the VM is using.
-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. Use the -verbose:sizes option to output the value that the VM is using.
-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<percentage>
  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. By default, the minimum value is 0.3 (30%).
-Xmn<size>
  Sets the initial and maximum size of the new (nursery) heap to the specified value when using -Xgcpolicy:gencon. Setting -Xmn is equivalent to setting -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. Use the -verbose:sizes option to output the value that the VM is 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. Use the -verbose:sizes option to output the value that the VM is using.
-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. Use the -verbose:sizes option to output the value that the VM is using.
-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. Use the -verbose:sizes option to output the value that the VM is using.
-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.
-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. Use the -verbose:sizes option to output the value that the VM is using.
-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. Use the -verbose:sizes option to output the value that the VM is using.
-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. Use the -verbose:sizes option to output the value that the VM is using.
-Xmrx<size>
  Sets the remembered maximum size setting.
-Xms<size>
  Sets the initial Java heap size. You can also use -Xmo. The default is set internally according to your system's capability. Use the -verbose:sizes option to output the value that the VM is using.
-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. Use the -verbose:sizes option to output the value that the VM is using.
-Xmx<size>
  Sets maximum Java heap size. By default, this option is set internally according to your system's capability. Use the -verbose:sizes option to output the value that the VM is using.
-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. See also -Xclassgc. By default, class garbage collection is performed.
-Xnocompactexplicitgc
  Disables compaction on a call to `System.gc()`. See also -Xcompactexplicitgc. By default, compaction is enabled on calls to `System.gc()`.
-Xnocompactgc
  Disables compaction for the Garbage Collector. See also -Xcompactgc. By default, compaction is enabled.
-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.
-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. By default, this option is not set, so all compactions are full. See also -Xnopartialcompactgc.
-Xquickstart
  Improves startup time by delaying JIT compilation and optimizations. 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. See -Xdbg for more information.
  -Xrunjnichk[:help] | [:<option>=<value>, ...]
    Deprecated, use -Xcheck:jni.
-Xscmx<size>
  For details of -Xscmx, see Enabling and configuring class data sharing.
-Xshareclasses:<options>
  For details of the -Xshareclasses options, see Enabling and configuring class data 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. Use the -verbose:sizes option to output the value that the VM is using.
-Xthr:<options>
  Sets the threading options.
-Xverbosegclog:<path to file>[X,Y]

  Causes verbose garbage collection (GC) 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 verbose GC output is redirected to X number of files, each containing Y number of gc cycles worth of verbose GC output. These files have the form filename1, filename2, and so on. By default, no verbose GC logging occurs.

  See the Diagnostics Guide for more information about verbose GC output.

-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.

# Appendix B. Known limitations

Known limitations on the SDK and Runtime Environment for Windows.

You can find more help with problem diagnosis in the Diagnostics Guide at http://www.ibm.com/developerworks/java/jdk/diagnosis/index.html.

| | |

## XSLT |namespace and Netbeans 5.0 problems

|

If the input to your transformation is a DOM that you have created programmatically, |such as in the example below, the XSLT interpreter processor has problems |with implicit namespaces that might cause incorrect namespace declarations |or the omission of namespace declarations from the resulting document. An |example Java fragment follows:

|

     // Example of an explicit namespace - an attribute node will be created in the DOM for xmlns='ht tp://my.org/project'
    |  String data = "<projectxmins='http://my.org/project/>";
    |  Document doc = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(new InputSource(n ew StringReader(data)));
    |
    | // Example of an implicit namespace - no attribute node is created for the implicit namespace xm lns='http://your.org/project
    |  Element typeElem = doc.createElementNS("http://your.org/project", "type");
    |  doc.getDocumentElement().appendChild(typeElem);

To work around |this you can use the XSLT compiler processor (XSLTC). The compiler processor |can be specified by using the -XSLTC option with the Process command |or by setting the javax.xml.transform.TransformerFactory service |provider to org.apache.xalan.xsltc.trax.TransformerFactoryImpl.

|

Netbeans |5.0 does not run under the JVM with default settings. To enable Netbeans to |run, set the javax.xml.transform.TransformerFactory=org.apache.xalan.xsltc.trax.TransformerFactoryImpl property |in jre/lib/jaxp.properties.

| | |

## -verbose with more than one sub-option where |one sub-option is jni

|

If |you specify more than one-suboption with -verbose and |one of the sub-options is jni there is an |error message.

|

An example of this follows:

|

    java -verbose:jni,class hello.class
    |JVMJ9VM015W Initialization error for library j9vrb23(3): unrecognised option for -verbose<opt>:
    |Could not create the Java virtual machine.

|

To |work around this limitation, you must create multiple invocations of -verbose on |the Java command line for multiple sub-options. For example, enter -verbose:gc,class |-verbose:jni rather than -verbose:gc,class,jni.

## Font problems in supported locales

The IBM 32-bit SDK for Windows, v5.0 supports the following locales:

- Bengali (bn_IN)
- Malayalam (ml_IN)
- Oriya (or_IN)

However the fonts from these locales might not work on AWT components.

## Use of sockets with IPv6

The IBM 32-bit SDK for Windows, v5.0 supports IPv6. However, because the current IPv6 support in Windows is not dual-stack, the SDK emulates dual-stack behavior on an IPv6 enabled system. Your Java application might use up to twice as many sockets because of the nature of the emulation. To disable this emulation, disable IPv6 support in the SDK by setting the system property java.net.preferIPv4Stack to `true`.

## JConsole monitoring tool Local tab

In IBM's JConsole tool, the Local tab, which allows you to connect to other Virtual Machines on the same system, is not available. Also, the corresponding command-line pid option is not supported. Instead, use the Remote tab in JConsole to connect to the Virtual Machine that you want to monitor. Alternatively, use the connection command-line option, specifying a host of `localhost` and a port number. When you launch the application that you want to monitor, set these command-line options:

-Dcom.sun.management.jmxremote.port=<value>
  Specifies the port the management agent should listen on.
-Dcom.sun.management.jmxremote.authenticate=false
  Disables authentication unless you have created a username file.
-Dcom.sun.management.jmxremote.ssl=false
  Disables SSL encryption.

| | |

## JConsole |monitoring tool when the JIT is disabled

|

IBM's |JConsole tool has the following limitations when the JIT is disabled: |

|

|
- The Summary tab is not available.
|
- The VM tab is not available.
|
- The chart accessed from the Memory tab is not updated.
|
- The chart accessed from the Threads tab is not |updated.
|
- You cannot determine if the Perform GC button accessed |from the Memory tab has an effect.

## Input Method Editor (IME)

When working with an Input Method Editor (IME), you are advised that character composition should be completed and the candidate selected before using the workspace for any other operation.

When a user types text in an AWT TextArea while using an Input Method Editor (IME), and then resizes the application's window before committing the text, the text is committed automatically.

## Slow DSA key pair generation

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

## Personal firewalls

Personal firewalls can cause problems for the Windows NIO code, causing particular operations to fail. For example, the method call Selector.open() can throw a "java.io.IOException: Unable to establish loopback connection" with a cause of "java.net.ConnectException: Connection refused: connect". The exception is caused by the operating system connecting on a port that is being blocked by the firewall. The JVM will retry the connect operation, asking the operating system to choose a different port number. If it still cannot connect after several retries, a ConnectException is thrown.

If you see this exception, you can set the system property java.nio.debug=pipe to see which port numbers are being blocked.

## File handle exhaustion

On Windows 2000 and XP, the default value of the number of files that you can have simultaneously opened is too low and will cause problems to applications that are I/O intensive. To fix this limitation, edit the file <windows>\system32\CONFIG.NT and set the following values:

    files=200
    buffers=60

where <windows> is the directory where Windows is installed.

## DirectDraw and mouse pointer problems

On Windows 2000, with a 32-bit color depth, the DirectDraw mechanism of the JVM does not repaint the region under the mouse pointer. The effect is that gray or black squares appear on menus after the mouse has been there. The workround is either to switch off direct draw (-Dsun.java2d.noddraw), or to change your screen color resolution to some other value, such as 256 color.

## NIO connection problems

The NIO SocketChannel finishConnect() call can return `true` (the channel is connected) or `false` (the connection process is not yet complete), or can throw an exception. On Windows 2000, when using non-blocking connections, `false` might be returned even after a previous Java select() call has implied that a channel is ready for processing.

## Stack range of the main thread

You cannot alter the stack range of the Java main thread (also known as the primordial thread) at run time. The main thread has a fixed size of 256 KB, determined as the optimum value for performance reasons. You can use the -Xss option to modify the stack range only on threads other than the main one. Do not use the main thread for heavily recursive calculations because the main thread is more prone to stack overflow than other threads.

## DBCS characters

If you are typing DBCS characters in a JTextArea, JTextField, or JFileChooser, switching from some Chinese IMEs (in particular, Chinese Internal Code and Zhengma) to Intelligent ABC IME might cause a core dump to be produced.

## Czech language installation

For Czech users, note that the language selection panel of InstallShield offers one translated entry in an install that is otherwise untranslated. This limitation is caused by InstallShield. The string is picked up from the operating system based on the codepage. Because Polish (for which the install is translated) and Czech both have codepage 1250, InstallShield attempts to retrieve a language list from the system for both languages, resulting in this string in the language list.

## Traditional Chinese and the more command

If you use Traditional Chinese, do not pipe the output from your Java application directly into the more command. Instead, direct the output to a temporary file and view the file separately.

## Accent corruption for Catalan users

For Catalan users, the Lucida Console font should be used to avoid corruption of accented capital letters. This affects users of Windows 2000 only.

## NullPointerException with the GTK Look and Feel

DBCS environments only

If your application fails with a NullPointerException using the GTK Look and Feel, unset the GNOME_DESKTOP_SESSION_ID environment variable.

# 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, AIX, developerWorks, eServer, iSeries, MVS, POWER4, POWER5+, PowerPC, pSeries, System i, System p, System z, WebSphere, System z9, z/OS, 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.

Microsoft, Windows and the Windows logo are trademarks of Microsoft Corporation 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.