IBM SDK for Linux platforms, Java Technology Edition

SDK and Runtime Guide

Preface

Read this user guide with the more extensive documentation on the Sun Web site: http://java.sun.com.

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

(Intel® 32-bit platforms only) These Virtualized Environments are supported:

• VMWare
• Xen
• Microsoft® Virtual Server

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, by blue chevrons and in red when viewing in HTML, or by vertical bars to the left of the changes when viewing as a PDF file.

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 SDK includes the Runtime Environment for Linux, which enables you only to run Java applications. If you have installed the SDK, the Runtime Environment is included.

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

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

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

Conventions

The default installation directories for the various architectures are listed here; replace the directory for the architecture you are using when you see /opt/ibm/java-<arch>-60/:

• Linux IA 32-bit: /opt/ibm/java-i386-60/
• Linux AMD 64-bit: /opt/ibm/java-x86_64-60/
• Linux PPC 32-bit: /opt/ibm/java-ppc-60/
• Linux PPC 64-bit: /opt/ibm/java-ppc64-60/
• Linux System z® 31-bit: /opt/ibm/java-s390-60/
• Linux System z 64-bit: /opt/ibm/java-s390x-60/

Korn shell commands are used in examples throughout this user guide.

Version compatibility

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

http://java.sun.com/javase/6/webnotes/compatibility.html

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® Application Server), and you upgrade from a previous level of the SDK, perhaps v5.0, serialized classes might not be compatible. However, classes are compatible between service refreshes.

Migrating from other IBM JVMs

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

• The JVM shared library libjvm.so is now stored in jre/lib/<arch>/j9vm and jre/lib/<arch>/classic.
• From Version 5.0 onwards, the JVM Monitoring Interface (JVMMI) is no longer available. You must rewrite JVMMI applications 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/javase/6/docs/technotes/guides/jvmti/ and the Diagnostics Guide.
• From Version 5.0 onwards, the implementation of JNI conforms to the JNI specification, but differs from the Version 1.4.2 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 JVM command-line options.
• From Version 5.0 onwards, the format and content of garbage collector verbose logs obtained using -verbose:gc have changed. The data is now formatted as XML. The data content reflects the changes to the implementation of garbage collection in the JVM, and most of the statistics that are output have changed. You must change any programs that process the verbose GC output so that they will work with the new format and data. See the Diagnostics Guide for an example of the new verbose GC data.
• SDK 1.4 versions of the IBM JRE included JVM specific classes in a file called core.jar. From Version 5.0 onwards, these are included in a file called vm.jar.
• From Version 6, JVM classes are held in multiple JAR files in the jre/lib directory. This replaces the single rt.jar and core.jar from earlier releases.
• For additional industry compatibility information, see Sun's Java 6 Compatibility Documentation: http://java.sun.com/javase/6/webnotes/compatibility.html
• For additional deprecated API information, see Sun's Java 6 Deprecated API List: http://java.sun.com/javase/6/docs/api/deprecated-list.html
• Tracing class dependencies, started using -verbose:Xclassdep, is not supported. If you specify -verbose:Xclassdep, the JVM will issue an error message and will not start.
• The JVM detects the operating system locale and sets the language preferences accordingly. For example, if the locale is set to fr_FR, JVM messages will be printed in French. To avoid seeing JVM messages in the language of the detected locale, remove the file $SDK/jre/bin/java_xx.properties where xx is the locale, such as fr, and the JVM will print messages in English.

Supported hardware for System z

The SDKs and Runtime Environments run on the following servers or equivalents:

• z9-109
• z990
• z900
• z890
• z800

Contents of the SDK and 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.

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

Contents of the Runtime Environment

• Core Classes - These classes are the compiled class files for the platform and must remain compressed for the compiler and interpreter to access them. Do not modify these classes; instead, create subclasses and override where you need to.
• Trusted root certificates from certificate signing authorities - These certificates are used to validate the identity of signed material. The IBM Runtime Environment for Java contains an expired GTE CyberTrust Certificate for compatibility reasons. This certificate may be removed for later versions of the SDK. See Expired GTE Cybertrust Certificate for more information.
• JRE tools - The following tools are part of the Runtime Environment and are in the /opt/ibm/java-<arch>-60/jre/bin directory unless otherwise specified.

  ikeyman (iKeyman GUI utility)

  Allows you to manage keys, certificates, and certificate requests. For more information see the accompanying Security Guide and http://public.dhe.ibm.com/software/dw/jdk/security/50/GSK7c_SSL_IKM_Guide.pdf. The SDK also provides a command-line version of this utility.

  java (Java Interpreter)

  Runs Java classes. The Java Interpreter runs programs that are written in the Java programming language.

  javaw (Java Interpreter)

  Runs Java classes in the same way as the java command does, but does not use a console window.

  (Linux IA 32-bit, PPC32, and PPC64 only) javaws (Java Web Start)

  Enables the deployment and automatic maintenance of Java applications. For more information, see Running Web Start.

  jcontrol (Java Control Panel)

  (Except System z platforms) Configures your Runtime Environment.

  jextract (Dump extractor)

  Converts a system-produced dump into a common format that can be used by jdmpview. For more information, see jdmpview.

  keytool (Key and Certificate Management Tool)

  Manages a keystore (database) of private keys and their associated X.509 certificate chains that authenticate the corresponding public keys.

  kinit

  Obtains and caches Kerberos ticket-granting tickets.

  klist

  Displays entries in the local credentials cache and key table.

  ktab

  Manages the principal names and service keys stored in a local key table.

  pack200

  Transforms a JAR file into a compressed pack200 file using the Java gzip compressor.

  policytool (Policy File Creation and Management Tool)

  Creates and modifies the external policy configuration files that define your installation's Java security policy.

  rmid (RMI activation system daemon)

  Starts the activation system daemon so that objects can be registered and activated in a Java virtual machine (JVM).

  rmiregistry (Java remote object registry)

  Creates and starts a remote object registry on the specified port of the current host.

  tnameserv (Common Object Request Broker Architecture (CORBA) transient naming service)

  Starts the CORBA transient naming service.

  unpack200

  Transforms a packed file produced by pack200 into a JAR file.

Contents of the SDK

The following tools are part of the SDK and are located in the /opt/ibm/java-<arch>-60/bin directory:

appletviewer (Java Applet Viewer)

Tests and runs applets outside a Web browser.

apt (Annotation Processing Tool)

Finds and executes annotation processors based on the annotations present in the set of specified source files being examined.

ControlPanel (Java Control Panel)

(Except System z platforms) Configures your Runtime Environment.

extcheck (Extcheck utility)

Detects version conflicts between a target jar file and currently-installed extension jar files.

(Linux IA 32-bit and PPC32) HtmlConverter (Java Plug-in HTML Converter)

Converts an HTML page that contains applets to a format that can use the Java Plug-in.

idlj (IDL to Java Compiler)

Generates Java bindings from a given IDL file.

ikeycmd (iKeyman command-line utility)

Allows you to manage keys, certificates, and certificate requests from the command line. For more information see the accompanying Security Guide and http://www.ibm.com/developerworks/java/jdk/security/.

jar (Java Archive Tool)

Combines multiple files into a single Java Archive (JAR) file.

jarsigner (JAR Signing and Verification Tool)

Generates signatures for JAR files and verifies the signatures of signed JAR files.

java (Java Interpreter)

Runs Java classes. The Java Interpreter runs programs that are written in the Java programming language.

java-rmi.cgi (HTTP-to-CGI request forward tool)

Accepts RMI-over-HTTP requests and forwards them to an RMI server listening on any port.

javac (Java Compiler)

Compiles programs that are written in the Java programming language into bytecodes (compiled Java code).

javadoc (Java Documentation Generator)

Generates HTML pages of API documentation from Java source files.

javah (C Header and Stub File Generator)

Enables you to associate native methods with code written in the Java programming language.

javap (Class File Disassembler)

Disassembles compiled files and can print a representation of the bytecodes.

javaw (Java Interpreter)

Runs Java classes in the same way as the java command does, but does not use a console window.

(Linux IA 32-bit, PPC32, and PPC64 only) javaws (Java Web Start)

Enables the deployment and automatic maintenance of Java applications. For more information, see Running Web Start.

jconsole (JConsole Monitoring and Management Tool)

Monitors local and remote JVMs using a GUI. JMX-compliant.

jdb (Java Debugger)

Helps debug your Java programs.

jdmpview (Cross-platform dump formatter)

Analyzes dumps. For more information, see the Diagnostics Guide.

keytool (Key and Certificate Management Tool)

Manages a keystore (database) of private keys and their associated X.509 certificate chains that authenticate the corresponding public keys.

native2ascii (Native-To-ASCII Converter)

Converts a native encoding file to an ASCII file that contains characters encoded in either Latin-1 or Unicode, or both.

policytool (Policy File Creation and Management Tool)

Creates and modifies the external policy configuration files that define your installation's Java security policy.

rmic (Java Remote Method Invocation (RMI) Stub Converter)

Generates stubs, skeletons, and ties for remote objects. Includes RMI over Internet Inter-ORB Protocol (RMI-IIOP) support.

rmid (RMI activation system daemon)

Starts the activation system daemon so that objects can be registered and activated in a Java virtual machine (JVM).

rmiregistry (Java remote object registry)

Creates and starts a remote object registry on the specified port of the current host.

schemagen

Creates a schema file for each namespace referenced in your Java classes.

serialver (Serial Version Command)

Returns the serialVersionUID for one or more classes in a format that is suitable for copying into an evolving class.

tnameserv (Common Object Request Broker Architecture (CORBA) transient naming service)

Starts the CORBA transient naming service.

wsgen

Generates JAX-WS portable artifacts used in JAX-WS Web services.

wsimport

Generates JAX-WS portable artifacts from a Web Services Description Language (WSDL) file.

xjc

Compiles XML Schema files.

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. From Version 6, the RMI-IIOP demonstration is not included with the SDK.

copyright

The copyright notice for the SDK for Linux software.

License

The License file, /opt/ibm/java-<arch>-60/docs/content/<locale>/LA_<locale>, contains the license agreement for the SDK for Linux software (where <locale> is the name of your locale, for example en). To view or print the license agreement, open the file in a Web browser.

Installing and configuring the SDK and Runtime Environment

If you install using an RPM file, the Java files are installed in /opt/ibm/java-<arch>-60/. The examples in this guide assume that you have installed Java in this directory.

Upgrading the SDK

What to do next

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

Installing on Red Hat Enterprise Linux (RHEL) 4

About this task

In RHEL 4, the RPMs that contain these libraries are:

• compat-libstdc++-33-3.2.3 and xorg-x11-deprecated-libs-6.8.1 (Platforms other than zSeries)
• compat-libstdc++-295-2.95.3 and xorg-x11-deprecated-libs-6.8.1 (zSeries)

To include these libraries during RHEL 4 installation:

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

Installing on Red Hat Enterprise Linux (RHEL) 5

About this task

In RHEL 5, these RPMs contain the shared libraries:

• compat-libstdc++-33-3.2.3 (Platforms other than zSeries)
• compat-libstdc++-295-2.95.3 (zSeries)

To include these libraries during RHEL 5 installation:

1. At the software selection screen, select Customize now.
2. On the next screen, in the left panel, select Base System; in the right panel, select Legacy Software Support. These selections install the compat-libstdc++ packages.

Running Java with SELinux on RHEL 5

About this task

To enable Java manually on PPC platforms, enter this command:

chcon -R -t texrel_shlib_t <path_of_sdk>

Where <path_of_sdk> is the path where Java is installed.

For more information about SELinux, see Introduction to SELinux in the Red Hat documentation.

Installing on Ubuntu

For information about installing using the .tgz package, see Installing from a .tgz file.

Errors installing using RPM

The following error is displayed if you try to install using RPM :

error: Failed dependencies:
        glibc >= 2.3 is needed by ibm-java-<arch>-sdk-6.0-5.0.<arch>
        libstdc++.so.5 is needed by ibm-java-<arch>-sdk-6.0-5.0.<arch>
        /bin/sh is needed by ibm-java-<arch>-sdk-6.0-5.0.<arch>

You can force RPM installation by using the --nodeps command-line option. For example:

rpm -ivh --nodeps ibm-java-<arch>-sdk-6.0-5.0.<arch>.rpm

Where <arch> is the architecture of your system.

Installing a 32-bit SDK on 64-bit architecture

About this task

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

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

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

Installing from an RPM file

About this task

To upgrade your JVM using the rpm tool, you must uninstall any previous version. To install two versions of the JVM in different locations, use the rpm --force option to ignore the version conflict or install the JVM from the .tgz file.

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

   rpm -ivh ibm-java-<arch>-sdk-6.0-5.0.<arch>.rpm

   or

   rpm -ivh ibm-java-<arch>-jre-6.0-5.0.<arch>.rpm

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

Installing from a .tgz file

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

   tar -zxvf ibm-java-sdk-6.0-5.0-linux-<arch>.tgz

   or

   tar -zxvf ibm-java-jre-6.0-5.0-linux-<arch>.tgz

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

3. If you are running Security-Enhanced Linux (SELinux), you must identify the Java shared libraries to the system. Type:

   chcon -R -t texrel_shlib_t /opt/ibm/java-<arch>-60/jre
   chcon -R -t texrel_shlib_t /opt/ibm/java-<arch>-60/bin
   chcon -R -t texrel_shlib_t /opt/ibm/java-<arch>-60/lib

Using a JPackage compatible format

Before you begin

To simplify managing the SDK, the various components of it are now available as separate RPMs: the base Java Runtime Environment, Development Kit, Plug-in, JDBC, Demo, Sound, Source, and Fonts. "jpackage-utils" RPM (downloadable from http://jpackage.org), which allows managing multiple Java RPMs on a system, is a prerequisite for the IBM SDKs. For more information about the JPackage specification, see http://jpackage.org.

If you install the SDK using JPackage, it is not installed in the default location. See the "Directory Structure" section of the JPackage Java™ infrastructure design and packaging policy for details about the default JPackage installation location: http://www.jpackage.org/cgi-bin/viewvc.cgi/src/jpackage-utils/doc/jpackage-1.5-policy.xhtml?root=jpackage&view=co

jpackage-utils version 1.5.38 or above is required to install the IBM SDK for Linux, v6.

JPackage is not supported on the SLES9, SLES10, or SLES11 platforms.

Configuring the SDK and Runtime Environment for Linux

Setting the path

About this task

The PATH environment variable enables Linux to find programs and utilities, such as javac, java, and javadoc tool, 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. Edit the shell startup file in your home directory (typically .bashrc, depending on your shell) and add the absolute paths to the PATH environment variable; for example:

   export PATH=/opt/ibm/java-<arch>-60/bin:/opt/ibm/java-<arch>-60/jre/bin:$PATH

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

Results

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

About this task

You should 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 shell prompt:

  echo $CLASSPATH

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

Uninstalling the SDK and Runtime Environment for Linux

See Uninstalling the Red Hat Package Manager (RPM) package or Uninstalling the compressed Tape Archive (TAR) package for instructions.

Uninstalling the Red Hat Package Manager (RPM) package

About this task

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

1. To check which RPM packages you have installed, enter: rpm -qa | grep -i java

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

   ibm-java-<arch>-jre-6.0-5.0.<arch>
   ibm-java-<arch>-sdk-6.0-5.0.<arch>

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

   rpm -e ibm-java-<arch>-jre-6.0-5.0.<arch>
   rpm -e ibm-java-<arch>-sdk-6.0-5.0.<arch>

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

2. Remove from your PATH statement the directory in which you installed the SDK and Runtime Environment.
3. (Linux IA 32-bit and PPC32 only) If you installed the Java Plug-in, remove the Java Plug-in files from the Web browser directory.

Uninstalling the compressed Tape Archive (TAR) package

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

Running Java applications

The java and javaw commands

Purpose

The java and javaw tools start 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 window with error information if it 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 start. 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

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

   java -version

   You will see information similar to:

   java version "1.6.0-internal"
   Java(TM) SE Runtime Environment (build 20070329_01)
   IBM J9 VM (build 2.4, J2RE 1.6.0 IBM J9 2.4 Linux x86-32 jvmxi3260-20070326_12091 (JIT enabled)
   J9VM - 20070326_12091_lHdSMR
   JIT  - dev_20070326_1800
   GC   - 20070319_AA)

   Exact build dates and versions will change.

What to do next

You can also list the version information for all available jar files on the class path, the boot class path, and in the extensions directory. Type the following command:

java -Xjarversion

You will see information similar to:

...
/opt/ibm/java-<arch>-60/jre/lib/ext/ibmpkcs11impl.jar  VERSION: 1.0 build_20070125
/opt/ibm/java-<arch>-60/jre/lib/ext/dtfjview.jar
/opt/ibm/java-<arch>-60/jre/lib/ext/xmlencfw.jar  VERSION: 1.00, 20061011  LEVEL: -20061011

...

The information available varies for each jar file and is taken from the Implementation-Version and Build-Level properties in the manifest of the jar file.

Specifying Java options and system properties

About this task

These methods of specifying Java options are listed in order of precedence. 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.

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:

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

Standard options

See JVM command-line options for information about nonstandard (-X) 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.

-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>[,<option>...]

Enables verbose output. Separate multiple options using commas. 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 (see Garbage Collector command-line options for more information) 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

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.

The Just-In-Time (JIT) compiler

The JIT is included in both the IBM SDK and Runtime Environment, which is enabled by default in user applications and SDK tools. Typically, you do not start 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

About this task

Turning off the JIT is a temporary measure that 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. Type the following at a shell prompt:

  export JAVA_COMPILER=NONE

• 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 shell prompt:

  java -Djava.compiler=NONE <class>

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

  java -Xint <class>

Enabling the JIT

• Set the JAVA_COMPILER environment variable to jitc before running the Java application. At a shell prompt, enter:

  export JAVA_COMPILER=jitc

  If the JAVA_COMPILER environment variable is an empty string, the JIT remains disabled. To disable the environment variable, at the prompt, enter:

  unset JAVA_COMPILER

• Use the -D option on the JVM command line to set the java.compiler property to jitc. At a 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 prompt, enter:

  java -Xjit <class>

Determining whether the JIT is enabled

Run the java launcher with the -version option. Enter the following at a shell 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)

What to do next

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

Specifying garbage collection policy

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

-Xgcpolicy:subpool

(PPC and zSeries only.) Uses an improved object allocation algorithm to achieve better performance when allocating objects on the heap. This option might improve performance on large SMP systems.

More effective heap usage using compressed references

The IBM SDK for Java 64-bit stores object references as 64-bit values. The -Xcompressedrefs command-line option causes object references to be stored as 32-bit representation, which reduces the 64-bit object size to be the same as a 32-bit object.

As the 64-bit objects with compressed references are smaller than default 64-bit objects, they occupy a smaller memory footprint in the Java heap and improves data locality. This results in better memory utilization and improved performance.

Use -Xcompressedrefs in any of these situations:

• When your Java applications does not need more than a 25 GB Java heap.
• When your application uses a lot of native memory and needs the JVM to run in a small footprint.

See the Diagnostics Guide for more detailed information and hardware/operating system specific guidance on compressed references. More information is also available on the Websphere white paper on compressed references.

Pause time

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 -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 "new" and the "tenure" areas. Objects are placed in one of these areas depending on their age. The new area is the smaller of the two and contains new objects; the tenure is larger and contains older objects. Objects are first allocated to the new area; if they have active references for long enough, they are promoted to the tenure area.

Generational GC depends on most objects not lasting long. Generational GC reduces pause times by concentrating the effort to reclaim storage on the new area because it has the most recyclable space. Rather than occasional but lengthy pause times to collect the entire heap, the new area is collected more frequently and, if the new area is small enough, pause times are comparatively short. However, generational GC has the drawback that, over time, the tenure area might become full. 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 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

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.

Fallback font configuration files

These files are for your convenience only. Their presence does not imply that the new Linux distribution is a supported platform for the IBM SDK and Runtime Environment for Linux platforms, Java Technology Edition, Version 6.

Using Indian and Thai input methods

About this task

In Version 5.0, the input method jar files were included in the jre/lib/ext directory and were automatically loaded by the JVM. In Version 6, the input method jar files are included in the jre/lib/im directory and you must manually add them to the Java extensions path to enable Indian and Thai input methods.

• Copy the indicim.jar and thaiim.jar files from the jre/lib/im directory to the jre/lib/ext directory.
• Add the jre/lib/im directory to the extension directories system property. Use the following command-line option:

  java -Djava.ext.dirs=/opt/ibm/java-<arch>-60/jre/lib/ext:/opt/ibm/java-<arch>-60/jre/lib/im <class>

What to do next

If you installed the SDK or Runtime Environment in a different directory, replace /opt/ibm/java-<arch>-60/ with the directory in which you installed the SDK or Runtime Environment.

Developing Java applications

See Contents of the SDK for details of the tools available.

Using XML

Use factory finders to locate implementations of the abstract factory classes, as described in Selecting an XML processor. By using factory finders, you can select a different XML library without changing your Java code.

Available XML libraries

The IBM SDK for Java contains the following XML libraries:

XML4J 4.5

XML4J is a validating parser providing support for the following standards:

• XML 1.0 (4th edition)
• Namespaces in XML 1.0 (2nd edition)
• XML 1.1 (2nd edition)
• Namespaces in XML 1.1 (2nd edition)
• W3C XML Schema 1.0 (2nd Edition)
• XInclude 1.0 (2nd Edition)
• OASIS XML Catalogs 1.0
• SAX 2.0.2
• DOM Level 3 Core, Load and Save
• DOM Level 2 Core, Events, Traversal and Range
• JAXP 1.4

XML4J 4.5 is based on Apache Xerces-J 2.9.0. See http://xerces.apache.org/xerces2-j/ for more information.

XL XP-J 1.1

XL XP-J 1.1 is a high-performance non-validating parser that provides support for StAX 1.0 (JSR 173). StAX is a bidirectional API for pull-parsing and streaming serialization of XML 1.0 and XML 1.1 documents. See the XL XP-J reference information section for more details about what is supported by XL XP-J 1.1.

XL TXE-J 1.0.1 Beta

For Version 5.0, the IBM SDK for Java included the XSLT4J compiler and interpreter. The XSLT4J interpreter was used by default.

For Version 6, the IBM SDK for Java includes XL TXE-J. XL TXE-J includes the XSLT4J 2.7.8 interpreter and a new XSLT compiler. The new compiler is used by default. The XSLT4J compiler is no longer included with the IBM SDK for Java. See Migrating to the XL-TXE-J for information about migrating to XL TXE-J.

XL TXE-J provides support for the following standards:

• XSLT 1.0
• XPath 1.0
• JAXP 1.4

Selecting an XML processor

XML processor selection is performed using service providers. When using a factory finder, Java looks in the following places, in this order, to see which service provider to use:

1. The system property with the same name as the service provider.
2. The service provider specified in a properties file.
   • For XMLEventFactory, XMLInputFactory, and XMLOutputFactory only. The value of the service provider in the file /opt/ibm/java-<arch>-60/jre/lib/stax.properties.
   • For other factories. The value of the service provider in the file /opt/ibm/java-<arch>-60/jre/lib/jaxp.properties.
3. The contents of the META-INF/services/<service.provider> file.
4. The default service provider.

The following service providers control the XML processing libraries used by Java:

javax.xml.parsers.SAXParserFactory

Selects the SAX parser. By default, org.apache.xerces.jaxp.SAXParserFactoryImpl from the XML4J library is used.

javax.xml.parsers.DocumentBuilderFactory

Selects the document builder. By default, org.apache.xerces.jaxp.DocumentBuilderFactoryImpl from the XML4J library is used.

javax.xml.datatype.DatatypeFactory

Selects the datatype factory. By default, org.apache.xerces.jaxp.datatype.DatatypeFactoryImpl from the XML4J library is used.

javax.xml.stream.XMLEventFactory

Selects the StAX event factory. By default, com.ibm.xml.xlxp.api.stax.XMLEventFactoryImpl from the XL XP-J library is used.

javax.xml.stream.XMLInputFactory

Selects the StAX parser. By default, com.ibm.xml.xlxp.api.stax.XMLInputFactoryImpl from the XL XP-J library is used.

javax.xml.stream.XMLOutputFactory

Selects the StAX serializer. By default, com.ibm.xml.xlxp.api.stax.XMLOutputFactoryImpl from the XL XP-J library is used.

javax.xml.transform.TransformerFactory

Selects the XSLT processor. Possible values are:

com.ibm.xtq.xslt.jaxp.compiler.TransformerFactoryImpl

Use the XL TXE-J compiler. This value is the default.

org.apache.xalan.processor.TransformerFactoryImpl

Use the XSLT4J interpreter.

javax.xml.validation.SchemaFactory:http://www.w3.org/2001/XMLSchema

Selects the schema factory for the W3C XML Schema language. By default, org.apache.xerces.jaxp.validation.XMLSchemaFactory from the XML4J library is used.

javax.xml.xpath.XPathFactory

Selects the XPath processor. By default, org.apache.xpath.jaxp.XPathFactoryImpl from the XSLT4J library is used.

Migrating to the XL-TXE-J

About this task

The XL TXE-J compiler is faster than the XSLT4J interpreter when you are applying the same transformation more than once. If you perform each individual transformation only once, the XL TXE-J compiler is slower than the XSLT4J interpreter because compilation and optimization reduce performance.

To continue using the XSLT4J interpreter as your XSLT processor, set the javax.xml.transform.TransformerFactory service provider to org.apache.xalan.processor.TransformerFactoryImpl.

To migrate to the XL-TXE-J compiler, follow the instructions in this task.

1. Use com.ibm.xtq.xslt.jaxp.compiler.TransformerFactoryImpl when setting the javax.xml.transform.TransformerFactory service provider.
2. Regenerate class files generated by the XSLT4J compiler. XL TXE-J cannot execute class files generated by the XSLT4J compiler.
3. Some methods generated by the compiler might exceed the JVM method size limit, in which case the compiler attempts to split these methods into smaller methods.
   • If the compiler splits the method successfully, you receive the following warning:

     Some generated functions exceeded the JVM method size limit and were automatically split into smaller functions. You might get better performance by manually splitting very large templates into smaller templates, by using the 'splitlimit' option to the Process or Compile command, or by setting the 'http://www.ibm.com/xmlns/prod/xltxe-j/split-limit' transformer factory attribute.

     You can use the compiled classes, but you might get better performance by controlling the split limit manually.
   • If the compiler does not split the method successfully, you receive one of the following exceptions:

     com.ibm.xtq.bcel.generic.ClassGenException: Branch target offset too large for short

     or

     bytecode array size > 65535 at offset=#####

     Try setting the split limit manually, or using a lower split limit.
   To set the split limit, use the -SPLITLIMIT option when using the Process or Compile commands, or the http://www.ibm.com/xmlns/prod/xltxe-j/split-limit transformer factory attribute when using the transformer factory. The split limit can be between 100 and 2000. When setting the split limit manually, use the highest split limit possible for best performance.
4. XL TXE-J might need more memory than the XSLT4J compiler. If you are running out of memory or performance seems slow, increase the size of the heap using the -Xmx option.
5. Migrate your application to use the new attribute keys. The old transformer factory attribute keys are deprecated. The old names are accepted with a warning.

   Table 1. Changes to attribute keys from the XSL4J compiler to the XL TXE-J compiler

   XSL4J compiler attribute	XL TXE-J compiler attribute
   translet-name	http://www.ibm.com/xmlns/prod/xltxe-j/translet-name
   destination-directory	http://www.ibm.com/xmlns/prod/xltxe-j/destination-directory
   package-name	http://www.ibm.com/xmlns/prod/xltxe-j/package-name
   jar-name	http://www.ibm.com/xmlns/prod/xltxe-j/jar-name
   generate-translet	http://www.ibm.com/xmlns/prod/xltxe-j/generate-translet
   auto-translet	http://www.ibm.com/xmlns/prod/xltxe-j/auto-translet
   use-classpath	http://www.ibm.com/xmlns/prod/xltxe-j/use-classpath
   debug	http://www.ibm.com/xmlns/prod/xltxe-j/debug
   indent-number	http://www.ibm.com/xmlns/prod/xltxe-j/indent-number
   enable-inlining	Obsolete in new compiler

6. Optional: For best performance, ensure that you are not recompiling XSLT transformations that can be reused. Use one of the following methods to reuse compiled transformations:
   • If your stylesheet does not change at runtime, compile the stylesheet as part of your build process and put the compiled classes on your classpath. Use the org.apache.xalan.xsltc.cmdline.Compile command to compile the stylesheet and set the http://www.ibm.com/xmlns/prod/xltxe-j/use-classpath transformer factory attribute to true to load the classes from the classpath.
   • If your application will use the same stylesheet during multiple runs, set the http://www.ibm.com/xmlns/prod/xltxe-j/auto-translet transformer factory attribute to true to automatically save the compiled stylesheet to disk for reuse. The compiler will use a compiled stylesheet if it is available, and compile the stylesheet if it is not available or is out-of-date. Use the http://www.ibm.com/xmlns/prod/xltxe-j/destination-directory transformer factory attribute to set the directory used to store compiled stylesheets. By default, compiled stylesheets are stored in the same directory as the stylesheet.
   • If your application is a long-running application that reuses the same stylesheet, use the transformer factory to compile the stylesheet and create a Templates object. You can use the Templates object to create Transformer objects without recompiling the stylesheet. The Transformer objects can also be reused but are not thread-safe.

XML reference information

XL XP-J reference information

Unsupported features

The following optional StAX features are not supported by XL XP-J:

• DTD validation when using an XMLStreamReader or XMLEventReader. The XL XP-J parser is non-validating.
• When using an XMLStreamReader to read from a character stream (java.io.Reader), the Location.getCharaterOffset() method always returns -1. The Location.getCharaterOffset() returns the byte offset of a Location when using an XMLStreamReader to read from a byte stream (java.io.InputStream).

XMLInputFactory reference

The javax.xml.stream.XMLInputFactory implementation supports the following properties, as described in the XMLInputFactory Javadoc information: http://java.sun.com/javase/6/docs/api/javax/xml/stream/XMLInputFactory.html.

XL XP-J also supports the optional method createXMLStreamReader(javax.xml.transform.Source), which allows StAX readers to be created from DOM and SAX sources.

XL XP-J also supports the javax.xml.stream.isSupportingLocationCoordinates property. If you set this property to true, XMLStreamReaders created by the factory return accurate line, column, and character information using Location objects. If you set this property to false, line, column, and character information is not available. By default, this property is set to false for performance reasons.

XMLStreamReader reference

The javax.xml.stream.XMLStreamReader implementation supports the following properties, as described in the XMLStreamReader Javadoc: http://java.sun.com/javase/6/docs/api/javax/xml/stream/XMLStreamReader.html.

XL XP-J also supports the javax.xml.stream.isInterning property. This property returns a boolean value indicating whether or not XML names and namespace URIs returned by the API calls have been interned by the parser. This property is read-only.

XMLOutputFactory reference

The javax.xml.stream.XMLOutputFactory implementation supports the following properties, as described in the XMLOutputFactory Javadoc: http://java.sun.com/javase/6/docs/api/javax/xml/stream/XMLOutputFactory.html.

XL XP-J also supports the javax.xml.stream.XMLOutputFactory.recycleWritersOnEndDocument property. If you set this property to true, XMLStreamWriters created by this factory are recycled when writeEndDocument() is called. After recycling, some XMLStreamWriter methods, such as getNamespaceContext(), must not be called. By default, XMLStreamWriters are recycled when close() is called. You must call the XMLStreamWriter.close() method when you have finished with an XMLStreamWriter, even if this property is set to true.

XMLStreamWriter reference

The javax.xml.stream.XMLStreamWriter implementation supports the following properties, as described in the XMLStreamWriter Javadoc: http://java.sun.com/javase/6/docs/api/javax/xml/stream/XMLStreamWriter.html.

Properties on XMLStreamWriter objects are read-only.

XL XP-J also supports the javax.xml.stream.XMLStreamWriter.isSetPrefixBeforeStartElement property. This property returns a Boolean indicating whether calls to setPrefix() and setDefaultNamespace() should occur before calls to writeStartElement() or writeEmptyElement() to put a namespace prefix in scope for that element. XL XP-J always returns false; calls to setPrefix() and setDefaultNamespace() should occur after writeStartElement() or writeEmptyElement().

XL TXE-J reference information

Feature comparison table

Notes

1. With the Process command, use -FLAVOR sr2sw to transform using StAX stream processing, and -FLAVOR er2ew for StAX event processing.
2. The new compiler does not look for the org.apache.xalan.xsltc.dom.XSLTCDTMManager service provider. Instead, if StreamSource is used, the compiler switches to a high-performance XML parser.
3. Inlining is obsolete in XL TXE-J.
   • The -XN option to the Process command is silently ignored.
   • The -n option to the Compile command is silently ignored.
   • The enable-inlining transformer factory attribute is silently ignored.
4. The org.apache.xalan.xsltc.trax.SmartTransformerFactoryImpl class is no longer supported.

Using an older version of Xerces or Xalan

About this task

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 (https://jaxp.dev.java.net/).
• Remove the jaxp.properties file from /opt/ibm/java-<arch>-60/jre/lib.
• Uncomment the entries in the jaxp.properties file in /opt/ibm/java-<arch>-60/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 in your application. For an example, see the JAXP 1.4 specification.
• Explicitly set the SAX parser, Document builder, or Transformer factory using the IBM_JAVA_OPTIONS environment variable.

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

  or

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

  or

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

Debugging Java applications

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

Java Debugger (JDB)

To debug a Java application:

1. Start the JVM with the following options:

   java -Xdebug -Xrunjdwp:transport=dt_socket,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 workstations. 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_socket,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 -attach <host>:<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/javase/6/docs/technotes/guides/jpda/
• http://java.sun.com/javase/6/docs/technotes/guides/jpda/jdb.html

Selective debugging

About this task

Selective debugging is useful when Java is being used as a framework for development, for example, as an IDE. The Java code for the IDE is optimized for performance while the user code is debugged.

1. Import the Debuggable annotation from the com.ibm.jvm package.

   import com.ibm.jvm.Debuggable;

2. Decorate methods using the Debuggable annotation.

   @Debuggable
   public int method1() {
     ...
   }

3. Optional: You can also decorate classes using the Debuggable annotation. All methods in the class will remain debuggable.

   @Debuggable
   public class Class1 {
     ...
   }

4. Enable selective debugging at run time using the -XselectiveDebug command-line option.

Results

Applications will run faster while being debugged because the core Java API and any IDE code can be optimized for performance.

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

About this task

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 (31-bit mode for Linux on System z)
• 64 - the JVM is running in 64-bit mode

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

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

How the JVM processes signals

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

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

For exception and error signals, the JVM either:

• Handles the condition and recovers, or
• Enters a controlled shut down 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 unexpected shut down hook
  4. Performs the necessary JVM cleanup

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

1. Calls your application's signal handler for that signal
2. Calls all application shut down hooks
3. Calls any application-installed exit hook
4. Performs the necessary JVM cleanup

The shut down is identical to the shut down 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 stop. The only control signal of interest is SIGQUIT, which causes a Javadump to be generated.

Signals used by the JVM

Table 3 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 an unrecoverable 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 shut down.

Controls

Other signals that are used by the JVM for control purposes.

Table 3. Signals used by the JVM

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

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

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

Linking a native code driver to the signal-chaining library

About this task

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

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

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

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

To use libjsig.so:

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

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

  or
• Use the LD_PRELOAD environment variable:

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

The environment variable JAVA_HOME should be set to the location of the SDK, for example,/opt/ibm/java-<arch>-60/.

To use libjsig.a:

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

  cc_r -q64 <other compile/link parameter> -L/opt/ibm/java-<arch>-60/jre/bin -ljsig 
  -L/opt/ibm/java-<arch>-60/jre/bin/j9vm -ljvm java_application.c

  Note: Use xlc_r or xlC_r in place of cc_r if that is how you usually call the compiler or linker.

Writing JNI applications

This version number determines only the level of the JNI to use. The actual level of the JVM that is created is specified by the JSE libraries (that is, v6). The JNI level 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/javase/6/docs/technotes/guides/jni/.

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

To compile and link a local application with the SDK, use the following command:

gcc -I/opt/ibm/java-<arch>-60/include -L/opt/ibm/java-<arch>-60/jre/lib/<arch>/j9vm 
-ljvm -ldl -lpthread <JNI program filename>

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

Supported compilers

The GNU Compiler Collection (gcc) v3.3.3 is supported for:

• 32-bit linux on PowerPC®
• 64-bit linux on PowerPC
• 32-bit linux on Intel
• 64-bit linux on Intel
• 31-bit linux on S/390®

Support for thread-level recovery of blocked connectors

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

The classes are:

public interface InterruptibleContext

Defines two methods, isBlocked() and unblock(). The other three classes implement InterruptibleContext.

public class InterruptibleLockContext

A utility class for interrupting synchronization calls.

public class InterruptibleIOContext

A utility class for interrupting network calls.

public class InterruptibleThread

A utility class that extends java.lang.Thread, to allow wrapping of interruptible methods. It uses instances of InterruptibleLockContext and InterruptibleIOContext to perform the required isBlocked() and unblock() methods depending on whether a synchronization or networking operation is blocking the thread.

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

The Javadoc information for these classes is provided with the SDK in the docs/content/apidoc directory.

Configuring large page memory allocation

About this task

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

Large page support must be available in the kernel, and enabled, so that Java can use large pages.

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

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

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

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

If large page support is available, but not enabled, HugePages_Total has the value 0. In this case, your administrator must enable large page support. Check your operating system manual for more instructions.

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

Large page allocations only succeed if the user is a member of the group with its gid stored in /proc/sys/vm/hugetlb_shm_group, or if Java is run with root access. See http://devresources.linux-foundation.org/dev/robustmutexes/src/fusyn.hg/Documentation/vm/hugetlbpage.txt for more information.

If a non-root user needs access to large pages, their locked memory limit must be increased. The locked memory limit must be at least as large as the maximum size of the Java heap. The maximum size of the Java heap can be specified using the -Xmx command-line option, or determined by adding -verbose:sizes and inspecting the output for the value -Xmx. If pam is not installed, change the locked memory limit using the ulimit command. If pam is installed, change the locked memory limit by adding the following lines to /etc/security/limits.conf:

@<large group name> soft memlock 2097152
@<large group name> hard memlock 2097152

Where <large group name> is the name of the group with its gid stored in /proc/sys/vm/hugetlb_shm_group.

CORBA support

The minimum specifications supported are defined in the Official Specifications for CORBA support in Java SE 6: http://java.sun.com/javase/6/docs/api/org/omg/CORBA/doc-files/compliance.html.

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 6. Programs that have 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

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

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

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

The following documentation is available:

• The RMI-IIOP Programmer's Guide is an introduction to writing RMI-IIOP programs.
• The Java Language to IDL Mapping document is a detailed technical specification of RMI-IIOP: http://www.omg.org/cgi-bin/doc?ptc/00-01-06.pdf.

Implementing the Connection Handler Pool for RMI

About this task

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

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

Support for XToolkit

Related links:

• An example, Integrating Swing into Eclipse RCPs: http://eclipsezone.com/eclipse/forums/t45697.html
• Reference Information in the Eclipse information center: http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/awt/SWT_AWT.html
• Set up information on the Sun Web site: http://java.sun.com/javase/6/docs/technotes/guides/awt/1.5/xawt.html

Support for the Java Attach API

Code for agent applications, such as JMX agents or JVMTI agents, is normally loaded during virtual machine startup by specifying special startup parameters. Requiring startup parameters might not be convenient for using agents on applications that are already running, such as WebSphere Application Servers. Using the Java Attach API, lets you load an agent at any time by specifying the process ID of the target virtual machine. The Attach API capability is sometimes called "late attach".

The Attach API is enabled by default for Java 6 SR 6 and later.

Security considerations

Security for the Java Attach API is handled by UNIX® user and group file permissions.

The Java Attach API creates files and directories in a common directory. The common directory, subdirectories, and files in it, have UNIX file permissions. It is recommended that you change the ownership of the common directory to ROOT or another privileged user ID, to prevent 'spoofing' attacks.

The key security features of the Java Attach API are:

• A process using the Java Attach API must be owned by the same UNIX userid as the target process. This ensures that only the target process owner can attach other applications to the target process.
• For Java 6 after SR 6, access to the files or directories owned by a process is controlled by user permissions only; group access is disabled.
• The common directory uses the sticky bit to prevent a user from deleting or replacing another user's subdirectory. To preserve the security of this mechanism, set the ownership of the common directory to ROOT.
• The subdirectory for a process is accessible only by members of the same UNIX group as the owner of a process. For Java 6 after SR 6, access is restricted to the owner only.
• Information about the target process can be written only by the owner and read only by the owner or a member of the owner's group. For Java 6 after SR 6, access is restricted to the owner only.

You must secure access to the Java Attach API capability to ensure that only authorized users or processes can connect to another virtual machine. If you do not intend to use the Java Attach API capability, disable this feature using the Java system property. Do this by setting the com.ibm.tools.attach.enable system property to the value no; for example:

-Dcom.ibm.tools.attach.enable=no

Using the Java Attach API

By default, the target virtual machine is identified by its process ID. To use a different target, change the system property com.ibm.tools.attach.id; for example:

-Dcom.ibm.tools.attach.id=<process_ID>

The target process also has a human-readable "display name". By default, the display name is the command line used to launch Java. To change the default display name, use the com.ibm.tools.attach.displayName system property. The ID and display name cannot be changed after the application has started.

The Attach API creates working files in a common directory called .com_ibm_tools_attach, which is created in the system temporary directory. The system property java.io.tmpdir holds the value of the system temporary directory. On non-Windows® systems, the system temporary directory is typically /tmp. To modify the working directory, use the Java system property com.ibm.tools.attach.directory; for example:

-Dcom.ibm.tools.attach.directory=/working

If your Java application ends abnormally, for example, following a crash or a SIGKILL signal, the process subdirectory is not deleted. The Java VM detects and removes obsolete subdirectories where possible. The subdirectory can also be deleted by the owning userid.

On heavily loaded system, applications might experience timeouts when attempting to connect to target applications. The default timeout is 120 seconds. Use the com.ibm.tools.attach.timeout system property to specify a different timeout value in seconds; for example, to timeout after 60 seconds:

-Dcom.ibm.tools.attach.timeout=60

A timeout value of zero indicates an indefinite wait.

For JMX applications, you might need to disable authentication by editing the <JAVA_HOME>/jre/lib/management/management.properties file. Set the following properties to disable authentication in JMX:

com.sun.management.jmxremote.authenticate=false
com.sun.management.jmxremote.ssl=false

An unsuccessful attempt to invoke the Attach API results in one of the following exceptions:

• com.sun.tools.attach.AgentLoadException
• com.sun.tools.attach.AgentInitializationException
• java.io.IOException

Related links:

• The Attach API: http://java.sun.com/javase/6/docs/technotes/guides/attach/index.html.

Plug-in, Applet Viewer and Web Start

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

You must allow applets to finish loading to prevent your browser from stopping. 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/javase/6/docs/technotes/guides/plugin/developer_guide/.

Supported browsers

Later minor releases of these browsers are also supported.

Installing the Java plug-in

The Java plug-in is based on Mozilla's Open JVM Integration initiative, which is used with most Mozilla products and derivatives, including Firefox.

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

Firefox

1. Log in as root.
2. Change to your Firefox plug-ins directory (which differs, depending on the Linux distributions).

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

3. Create a symbolic link to the plug-in. To link with an old style plug-in:

    ln -s /opt/ibm/java-<arch>-60/jre/plugin/<arch>/ns7/libjavaplugin_oji.so .

   To link with a Next-Generation plug-in, which is available only with IA32:

    ln -s /opt/ibm/java-<arch>-60/jre/lib/<arch>/libnpjp2.so .

   Where <arch> is the architecture of your system.

What to do next

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

Common Document Object Model (DOM) support

One of the following errors is thrown:

• sun.plugin.dom.exception.InvalidStateException
• sun.plugin.dom.exception.NotSupportedException

Using DBCS parameters

About this task

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.

Working with applets

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 and debugging applets with the Applet Viewer

About this task

Running applets with the Applet Viewer:

From a shell 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 start the Applet Viewer on an HTML file that calls an applet, type at a shell prompt:

  appletviewer $HOME/<filename>.html

Where filename is the name of the HTML file.

To start the Applet Viewer on a Web page, type at a shell prompt:

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

The Applet Viewer does not recognize the charset option of the <

META

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

appletviewer -encoding JISAutoDetect sample.html

Debugging applets with the Applet Viewer:

For example:

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

You can find documentation about how to debug applets using the Applet Viewer at the Sun Web site: http://java.sun.com/javase/6/docs/technotes/guides/plugin/developer_guide/debugger.html.

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

With Web Start, you can start 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 command-line arguments documented at http://java.sun.com/javase/6/docs/technotes/guides/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

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

For more information about Web Start, see:

• http://java.sun.com/products/javawebstart and

• http://java.sun.com/javase/6/docs/technotes/guides/javaws/index.html.

For more information about deploying applications, see:

• http://java.sun.com/javase/6/docs/technotes/guides/deployment/index.html.

Running Web Start

About this task

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

• Select a link on a Web page that refers to a .jnlp file. If your browser does not have the correct association to run Web Start applications, select the /opt/ibm/java-<arch>-60/jre/bin/javaws command from the Open/Save window to start the Web Start application.
• At a shell 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, use the Java Application Cache Viewer. At a shell prompt, type:

  /opt/ibm/java-<arch>-60/jre/bin/javaws -viewer

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

(Linux IA 32-bit only) WebStart Secure Static Versioning

With SSV, the user is warned before running any unsigned Web Start application that requests a specific JVM, if the requested JVM is installed. Signed applications and applications that request the latest version of the JVM run as usual.

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

Distributing Java applications

When you distribute a Java application, your software package probably consists of the following parts:

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

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

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

Class data sharing between JVMs

The Java Virtual Machine (JVM) allows you to share class data between JVMs by storing it in a memory-mapped cache file on disk. Sharing reduces the overall virtual storage 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 running JVM and persists until it is destroyed.

A shared cache can contain:

• Bootstrap classes
• Application classes
• Metadata that describes the classes
• Ahead-of-time (AOT) compiled code

Overview of class data sharing

Enabling class data sharing

Enable class data sharing by using the -Xshareclasses option when starting a JVM. The JVM connects to an existing cache or creates 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.

The JVM can also store ahead-of-time (AOT) compiled code in the cache for certain methods to improve the startup time of subsequent JVMs. The AOT compiled code is not shared between JVMs, but is cached to reduce compilation time when the JVM starts up. The amount of AOT code stored in the cache is determined heuristically. You cannot control which methods get stored in the cache, but you can set upper and lower limits on the amount of cache space used for AOT code, or you can choose to disable AOT caching completely. See Class data sharing command-line options for more information.

Cache access

A JVM can access a cache with either read-write or read-only access. Any JVM connected to a cache with read-write access 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. The shared class cache is created with user access by default unless the groupAccess command-line suboption is used. Only a classloader that has registered to share class data can update the shared class cache.

The cache memory is protected against accidental or deliberate corruption using memory page protection. This protection is not an absolute guarantee against corruption because the JVM must unprotect pages to write to them. The only way to guarantee that a cache cannot be modified is to open it read-only.

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 you specify them by name as a suboption to the -Xshareclasses command. A JVM can connect to only one cache at any one time.

You can 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 the cache file is deleted manually.

Cache utilities

All cache utilities are suboptions to the -Xshareclasses command. See Class data sharing command-line options or use -Xshareclasses:help to see a list of available suboptions.

Class data sharing command-line options

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.

-Xscmaxaot<size>

Sets the maximum number of bytes in the cache that can be used for AOT data. Use this option to ensure a certain amount of cache space is available for non-AOT data. By default, the maximum limit for AOT data is the amount of free space in the cache. The value of this option should not be smaller than the value of -Xscminaot and must not be larger than the value of -Xscmx.

-Xscminaot<size>

Sets the minimum number of bytes in the cache to reserve for AOT data. By default, no space is reserved for AOT data, although AOT data is written to the cache until the cache is full or the -Xscmaxaot limit is reached. The value of this option must not exceed the value of -Xscmx or -Xscmaxaot. The value of -Xscminaot must always be considerably less than the total cache size because AOT data can be created only for cached classes. If the value of -Xscminaot is equal to the value of -Xscmx, no class data or AOT data is stored because AOT data must be associated with a class in the cache.

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

Some cache utilities can work with caches from previous Java versions or caches created by JVMs with different bit-widths. These caches are referred to as "incompatible" caches.

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 inserts the current user name. You can specify "%g" in the cache name to insert the current group name.

cacheDir=<directory>

Sets the directory in which cache data is read and written. By default, <directory> is /tmp/javasharedresources. The user must have sufficient permissions in <directory>. The JVM writes persistent cache files directly into the directory specified. Persistent cache files can be safely moved and deleted from the file system. Non-persistent caches are stored in shared memory and have control files that describe the location of the memory. Control files are stored in a javasharedresources subdirectory of the cacheDir specified. Do not move or delete control files in this directory. The listAllCaches utility, the destroyAll utility, and the expire suboption work only in the scope of a given cacheDir.

readonly

Opens an existing cache with read-only permissions. The JVM does not create a new cache with this suboption. Opening a cache read-only prevents the JVM from making any updates to the cache. It also allows the JVM to connect to caches created by other users or groups without requiring write access. By default, this suboption is not specified.

persistent (default)

Uses a persistent cache. The cache is created on disk, which persists beyond operating system restarts. Non-persistent and persistent caches can have the same name.

nonpersistent

Uses a non-persistent cache. The cache is created in shared memory, which is lost when the operating system shuts down. Non-persistent and persistent caches can have the same name. You must always use the nonpersistent suboption when running utilities such as destroy on a non-persistent cache.

groupAccess

Sets operating system permissions on a new cache to allow group access to the cache. The default is user access only.

verbose

Enables verbose output, which provides overall status on the shared class cache and more detailed error messages.

verboseAOT

Enables verbose output when compiled AOT code is being found or stored in the cache. AOT code is generated heuristically. You might not see any AOT code generated at all for a small application. You can disable AOT caching using the noaot suboption.

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 usual 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, are 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 you select nonfatal and the shared classes cache fails to initialize, the JVM attempts to connect to the cache in read-only mode. If this attempt fails, 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 are 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, all classes are stored twice in the cache. See Runtime bytecode modification for more information.

reset

Causes a cache to be destroyed and then recreated when the JVM starts up. Can be added to the end of a command line as -Xshareclasses:reset.

destroy (Utility option)

Destroys a cache specified by the name, cacheDir, and nonpersistent suboptions. A cache can be destroyed only if all JVMs using it have shut down, and the user has sufficient permissions.

destroyAll (Utility option)

Tries to destroy all caches available using the specified cacheDir and nonpersistent suboptions. A cache can be destroyed only if all JVMs 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 option is not a utility option because it does not cause the JVM to exit.

listAllCaches (Utility option)

Lists all the compatible and incompatible caches that exist in the specified cache directory. If you do not specify cacheDir, the default directory is used. Summary information, such as Java version and current usage is displayed for each cache.

printStats (Utility option)

Displays summary information for the cache specified by the name, cacheDir, and nonpersistent suboptions. 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, 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.

mprotect=[ all | default | none ]

By default, the memory pages containing the cache are protected at all times, unless a specific page is being updated. This protection helps prevent accidental or deliberate corruption to the cache. The cache header is not protected by default because this protection has a small performance cost. Specifying all ensures that all the cache pages are protected, including the header. Specifying none disables the page protection.

noBootclasspath

Prevents storage of classes loaded by the bootstrap classloader in the shared classes cache. Can be used with the SharedClassURLFilter API to control exactly which classes get cached. See the Diagnostics Guide for more information about shared class filtering.

cacheRetransformed

Enables caching of classes that have been transformed using the JVMTI RetransformClasses function.

noaot

Disables caching of AOT code. AOT code already in the shared data cache can be loaded.

Creating, populating, monitoring, and deleting a cache

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

The JVM either connects to an existing cache of the given name or creates a new cache of that name. If a new cache is created, it is populated with all bootstrap and application classes being loaded until the cache becomes full. If two or more JVMs are started concurrently, they 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. You can run these utilities 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, run java -Xshareclasses:[name=<name>],destroy. You usually delete caches only if they contain many stale classes or if the cache is full and you want to create a bigger cache.

You should tune the cache size for your specific application, because the default is unlikely to be the optimum size. To determine the optimum cache size, 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. 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 affect on the performance or capability of any JVMs connected to it, so it is acceptable to decide on a cache size that is smaller than required.

If a cache becomes full, a message is displayed on the command line of any JVMs using the verbose suboption. All JVMs sharing the full cache then loads 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

The processor and memory usage required 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 show greater overall startup time benefits.

Duplicate classes are consolidated in 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 storage consumption.

Considerations and limitations of using class data sharing

Cache size limits

The shared class cache consists of memory mapped files that are created on disk and remain when the operating system is restarted. If you change the default behavior using the -Xshareclasses:nonpersistent option, so that the cache is not retained on restart, the cache for sharing classes is allocated using the System V IPC shared memory mechanism. In this case, cache size is limited by SHMMAX settings, which limits the amount of shared memory that can be allocated. You can find these settings by looking at the/proc/sys/kernel/shmmax file. SHMMAX is typically set to 30 MB.

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

JVMTI RetransformClasses() is unsupported

The JVM might throw the exception UnmodifiableClassException if you attempt to run RetransformClasses(). It does not work because class file bytes are not available for classes loaded from the shared class cache. If you must use RetransformClasses(), ensure that the classes to be transformed are not loaded from the shared class cache, or disable the shared class cache feature.

Runtime bytecode modification

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 affect on performance. Using a modification context with a JVMTI agent avoids the need for extra checks and therefore has no affect 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. You can use the modified=<modification_context> suboption 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

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 stored in /tmp/javasharedresources. If the identification information directory is deleted, the JVM cannot identify the shared classes on the system and must re-create the cache. Use the ipcs command to view the memory segments used by a JVM or application.

Users running a JVM must be in the same group to use a shared class cache. The operating system enforces the permissions for accessing a shared class cache. If you do not specify a cache name, 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

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

You must grant all custom classloaders 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 document for this package is provided with the SDK in the docs/content/apidoc directory.

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

Java Communications API (JavaComm)

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 6 Runtime Environment.

Using the 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

About this task

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

To install the Java Communications API from a compressed file:

1. Download the Java Communications API compressed file from http://www.ibm.com/developerworks/java/jdk/linux/download.html.
2. Put the Java Communications API compressed file, ibm-java-javacomm-3.0-0.0-<plat>-<arch>.tar.gz, in the directory where the SDK or Runtime Environment is installed. If you installed to the default directory, this is /opt/ibm/java-<arch>-60/.
3. From a shell prompt, in the directory containing the compressed file, extract the contents:

   tar -xvzf ibm-java-javacomm-3.0-0.0-<plat>-<arch>.tar.gz

   Where <arch> represents your architecture: i386, x86_64, ppc, or ppc64.

4. Copy the Java Communications API files into the correct directories in your SDK.
   1. Copy lib/libLinuxSerialParallel.so to your jre/lib/<arch>/ directory. Where <arch> is the architecture of your platform.
   2. Copy jar/comm.jar to your jre/lib/ext/ directory.
   3. Copy lib/javax.comm.properties to your jre/lib/ directory.
   By default, the SDK is installed in the /opt/ibm/java-<arch>-60/ directory.

Installing the Java Communications API from an RPM file

About this task

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

1. Download the Java Communications API RPM package from http://www.ibm.com/developerworks/java/jdk/linux/download.html.
2. Open a shell prompt, making sure you are root.
3. Use the rpm -ivh command to install the Java Communications API RPM file. For example:

   rpm -ivh ibm-java-<arch>-javacomm-3.0-0.0.rpm

   The Java Communications API is installed in the /opt/ibm/java-<arch>-60/ directory structure.
4. Copy the javacomm files into the correct directories in your SDK.
   1. Copy lib/libLinuxSerialParallel.so to your jre/lib/<arch>/ directory. Where <arch> is the architecture of your platform.
   2. Copy jar/comm.jar to your jre/lib/ext/ directory.
   3. Copy lib/javax.comm.properties to your jre/lib/ directory.
   By default, the SDK is installed in the /opt/ibm/java-<arch>-60/ directory.

Location of the Java Communications API files

The files and their structure are:

• jar/comm.jar
• jar/commtest.jar
• jar/tools/BlackBox.jar
• jar/tools/ParallelBlackBox.jar
• lib/javax.comm.properties
• lib/libLinuxSerialParallel.so

Configuring the Java Communications API

About this task

See Setting the path.

Changing the access mode of serial and parallel ports

About this task

You must give a user read and write access to the required devices. Log on as root and use the following commands, as applicable:

    chmod 660 /dev/ttyS0    (serial port COM1)
    chmod 660 /dev/ttyS1    (serial port COM2)
    chmod 660 /dev/ttyS2    (serial port COM3)
    chmod 660 /dev/ttyS3    (serial port COM4)
    chmod 660 /dev/parport0 (raw parallel ports)
    chmod 660 /dev/parport1 (raw parallel ports)

Add specific users to the same group that the devices are in. On a SUSE system, for example, the devices are in the uucp group. Thus, users can be added to the uucp group to gain access to the devices.

Change the access mode of any other ports as needed.

Specifying devices in the javax.comm.properties file

About this task

The following properties must be defined:

driver=<driver_name>
serpath0=<serial_port_device>


parpath0=<parallel_port_device>

For example:

# Implementation specific driver
driver=com.sun.comm.LinuxDriver

# Paths to server-side serial port devices
serpath0 = /dev/ttyS0
serpath1 = /dev/ttyS1

# Paths to server-side parallel port devices
parpath0 = /dev/parport0
parpath1 = /dev/parport1

For parallel port access, use /dev/parport<n>. /dev/lp<n> is not supported in Javacomm version 3.0.

Enabling serial ports on IBM ThinkPads

About this task

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

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

Printing limitation with the Java Communications API

Uninstalling Java Communications API

About this task

Uninstalling the Red Hat Package Manager (RPM) package

About this task

1. Use the rpm tool to uninstall the package. Enter the following command at a shell prompt:

   rpm -e ibm-java-<arch>-javacomm-3.0-0.0

   Where <arch> is the architecture of your platform.

   Alternatively, you can use a graphical tool such as kpackage or yast2.
2. If the directory where you installed the Java Communications API does not contain any other tools that you require, remove that directory from your PATH statement.
3. If you copied the Java communications API libraries into the SDK directory, delete the following files from the SDK directory.
   • jre/lib/<arch>/libLinuxSerialParallel.so
   • jre/lib/ext/comm.jar
   • jre/lib/javax.comm.properties

   Where <arch> is the architecture of your platform.

   By default, the SDK is installed in the /opt/ibm/java-<arch>-60/ directory.

Uninstalling the compressed Tape Archive (TAR) package

About this task

Delete the following files from the directory where you installed them:

• jre/lib/<arch>/libLinuxSerialParallel.so
• jre/lib/ext/comm.jar
• jre/lib/javax.comm.properties

Where <arch> is the architecture of your platform.

The Java Communications API documentation

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

Service and support for independent software vendors

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

If you have purchased a service contract (that is, the IBM 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

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

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

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

Any comments on this user guide?

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. Command-line options

This chapter provides the following information:

• Specifying command-line options
• General command-line options
• System property command-line options
• JVM command-line options
• -XX command-line options
• JIT and AOT command-line options
• Garbage Collector command-line options

Specifying command-line options

Use only single or double quotation marks for command-line options when explicitly directed to do so for the option in question. Single and double quotation marks have different meanings on different platforms, operating systems, and shells. Do not use '-X<option>' or "-X<option>". Instead, you must use -X<option>. For example, do not use '-Xmx500m' and "-Xmx500m". Write this option as -Xmx500m.

These precedence rules (in descending order) apply to specifying options:

1. Command line.

   For example, java -X<option> MyClass

2. A file containing a list of options, specified using the -Xoptionsfile option on the command line. For example, java -Xoptionsfile=myoptionfile.txt MyClass

   In the options file, specify each option on a new line; you can use the '\' character as a continuation character if you want a single option to span multiple lines. Use the '#' character to define comment lines. You cannot specify -classpath in an options file. Here is an example of an options file:

   #My options file
   -X<option1>
   -X<option2>=\
   <value1>,\
   <value2>
   -D<sysprop1>=<value1>

3. IBM_JAVA_OPTIONS environment variable. You can set command-line options using this environment variable. The options that you specify with this environment variable are added to the command line when a JVM starts in that environment.

   For example, set IBM_JAVA_OPTIONS=-X<option1> -X<option2>=<value1>

General command-line options

-cp, -classpath <directories and compressed or jar files separated by : (; on Windows)>

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 classpath is, by default, the current directory (.).

-help, -?

Prints a usage message.

-showversion

Prints product version and continues.

-verbose:<option>[,<option>...]

Enables verbose output. Separate multiple options using commas. These options are available:

class

Writes an entry to stderr for each class that is loaded.

dynload

Provides detailed information as each bootstrap class is loaded by the JVM:

• The class name and package
• For class files that were in a .jar file, the name and directory path of the .jar
• Details of the size of the class and the time taken to load the class

The data is written out to stderr. An example of the output on a Windows platform follows:

<Loaded java/lang/String from C:\sdk\jre\lib\vm.jar>
<Class size 17258; ROM size 21080; debug size 0>
<Read time 27368 usec; Load time 782 usec; Translate time 927 usec>

gc

Provide verbose garbage collection information.

init

Writes information to stderr describing JVM initialisation and termination.

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.

System property command-line options

-D<name>=<value>

Sets a system property.

-Dcom.ibm.lang.management.verbose

Enables verbose information from java.lang.management operations to be written to the console during VM operation.

-Dcom.ibm.tools.attach.enable=yes

Enable the Attach API for this application. The Attach API allows your application to connect to a virtual machine. Your application can then load an agent application into the virtual machine. The agent can be used to perform tasks such as monitoring the virtual machine status.

-Dibm.jvm.bootclasspath

The value of this property is used as an additional search path, which is inserted between any value that is defined by -Xbootclasspath/p: and the bootclass path. The bootclass path is either the default or the one that you defined by using the -Xbootclasspath: option.

-Dibm.stream.nio=[true | false]

From v1.4.1 onwards, by default the IO converters are used. This option addresses the ordering of IO and NIO converters. When this option is set to true, the NIO converters are used instead of the IO converters.

-Djava.compiler=[ NONE | j9jit24 ]

Disables the Java compiler by setting to NONE. Enable JIT compilation by setting to j9jit24 (Equivalent to -Xjit).

-Djava.net.connectiontimeout=[n]

'n' is the number of seconds to wait for the connection to be established with the server. If this option is not specified in the command line, the default value of 0 (infinity) is used. The value can be used as a timeout limit when an asynchronous java-net application is trying to establish a connection with its server. If this value is not set, a java-net application waits until the default connection timeout value is met. For instance, java -Djava.net.connectiontimeout=2 TestConnect causes the java-net client application to wait only 2 seconds to establish a connection with its server.

-Dsun.net.client.defaultConnectTimeout=<value in milliseconds>

Specifies the default value for the connect timeout for the protocol handlers used by the java.net.URLConnection class. The default value set by the protocol handlers is -1, which means that no timeout is set.

When a connection is made by an applet to a server and the server does not respond properly, the applet might seem to hang and might also cause the browser to hang. This apparent hang occurs because there is no network connection timeout. To avoid this problem, the Java Plug-in has added a default value to the network timeout of 2 minutes for all HTTP connections. You can override the default by setting this property.

-Dsun.net.client.defaultReadTimeout=<value in milliseconds>

Specifies the default value for the read timeout for the protocol handlers used by the java.net.URLConnection class when reading from an input stream when a connection is established to a resource. The default value set by the protocol handlers is -1, which means that no timeout is set.

-Dsun.nio.MaxDirectMemorySize=<value in bytes>

Limits the native memory size for nio Direct Byte Buffer objects to the value specified.

-Dsun.rmi.transport.tcp.connectionPool=[true | any non-null value]

Enables thread pooling for the RMI ConnectionHandlers in the TCP transport layer implementation.

-Dswing.useSystemFontSettings=[false]

From v1.4.1 onwards, by default, Swing programs running with the Windows Look and Feel render with the system font set by the user instead of a Java-defined font. As a result, fonts for v1.4.1 differ from those in earlier releases. This option addresses compatibility problems like these for programs that depend on the old behavior. By setting this option, v1.4.1 fonts and those of earlier releases are the same for Swing programs running with the Windows Look and Feel.

JVM command-line options

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.

Options that relate to the JIT are listed under JIT and AOT command-line options. Options that relate to the Garbage Collector are listed under Garbage Collector command-line options.

-X

Displays help on nonstandard options.

-Xaggressive

(Linux PPC32 only) Enables performance optimizations that are expected to be the default in future releases.

-Xargencoding

You can put Unicode escape sequences in the argument list. This option is set to off by default.

-Xbootclasspath:<directories and compressed or Java archive files separated by : (; on Windows)>

Sets the search path for bootstrap classes and resources. The default is to search for bootstrap classes and resources in the internal VM directories and .jar files.

-Xbootclasspath/a:<directories and compressed or Java archive files separated by : (; on Windows)>

Appends the specified directories, compressed files, or jar files to the end of the bootstrap class path. The default is to search for bootstrap classes and resources in the internal VM directories and .jar files.

-Xbootclasspath/p:<directories and compressed or Java archive files separated by : (; on Windows)>

Adds a prefix of the specified directories, compressed files, or Java archive files to the front of the bootstrap class path. Do not deploy applications that use the -Xbootclasspath: or the -Xbootclasspath/p: option to override a class in the standard API. This is because such a deployment contravenes the Java 2 Runtime Environment binary code license. The default is to search for bootstrap classes and resources in the internal VM directories and .jar files.

-Xcheck:classpath

Displays a warning message if an error is discovered in the class path; for example, a missing directory or JAR file.

-Xcheck:gc[:<scan options>][:<verify options>][:<misc options>]

Performs additional checks on garbage collection. By default, no checking is performed. See the output of -Xcheck:gc:help for more information.

-Xcheck:jni[:help][:<option>=<value>]

Performs additional checks for JNI functions. This option is equivalent to -Xrunjnichk. By default, no checking is performed.

-Xcheck:memory[:<option>]

Identifies memory leaks inside the JVM using strict checks that cause the JVM to exit on failure. If no option is specified, all is used by default. The available options are as follows:

all

Enables checking of all allocated and freed blocks on every free and allocate call. This check of the heap is the most thorough. It typically causes the JVM to exit on nearly all memory-related problems soon after they are caused. This option has the greatest affect on performance.

callsite=<number of allocations>

Displays callsite information every <number of allocations>. Deallocations are not counted. Callsite information is presented in a table with separate information for each callsite. Statistics include the number and size of allocation and free requests since the last report, and the number of the allocation request responsible for the largest allocation from each site. Callsites are presented as sourcefile:linenumber for C code and assembly function name for assembler code.

Callsites that do not provide callsite information are accumulated into an "unknown" entry.

failat=<number of allocations>

Causes memory allocation to fail (return NULL) after <number of allocations>. Setting <number of allocations> to 13 causes the 14th allocation to return NULL. Deallocations are not counted. Use this option to ensure that JVM code reliably handles allocation failures. This option is useful for checking allocation site behavior rather than setting a specific allocation limit.

ignoreUnknownBlocks

Ignores attempts to free memory that was not allocated using the -Xcheck:memory tool. Instead, the -Xcheck:memory statistics printed out at the end of a run indicates the number of "unknown" blocks that were freed.

mprotect=<top|bottom>

Locks pages of memory on supported platforms, causing the program to stop if padding before or after the allocated block is accessed for reads or writes. An extra page is locked on each side of the block returned to the user.

If you do not request an exact multiple of one page of memory, a region on one side of your memory is not locked. The top and bottom options control which side of the memory area is locked. top aligns your memory blocks to the top of the page, so buffer underruns result in an application failure. bottom aligns your memory blocks to the bottom of the page so buffer overruns result in an application failure.

Standard padding scans detect buffer underruns when using top and buffer overruns when using bottom.

nofree

Keeps a list of blocks already used instead of freeing memory. This list is checked, as well as currently allocated blocks, for memory corruption on every allocation and deallocation. Use this option to detect a dangling pointer (a pointer that is "dereferenced" after its target memory is freed). This option cannot be reliably used with long-running applications (such as WebSphere Application Server), because "freed" memory is never reused or released by the JVM.

noscan

Checks for blocks that are not freed. This option has little effect on performance, but memory corruption is not detected. This option is compatible only with subAllocator, callsite, and callsitesmall.

quick

Enables block padding only and is used to detect basic heap corruption. Every allocated block is padded with sentinel bytes, which are verified on every allocate and free. Block padding is faster than the default of checking every block, but is not as effective.

skipto=<number of allocations>

Causes the program to check only on allocations that occur after <number of allocations>. Deallocations are not counted. Use this option to speed up JVM startup when early allocations are not causing the memory problem. The JVM performs approximately 250+ allocations during startup.

subAllocator[=<size in MB>]

Allocates a dedicated and contiguous region of memory for all JVM allocations. This option helps to determine if user JNI code or the JVM is responsible for memory corruption. Corruption in the JVM subAllocator heap suggests that the JVM is causing the problem; corruption in the user-allocated memory suggests that user code is corrupting memory. Typically, user and JVM allocated memory are interleaved.

zero

Newly allocated blocks are set to 0 instead of being filled with the 0xE7E7xxxxxxxxE7E7 pattern. Setting these blocks to 0 helps you to determine whether a callsite is expecting zeroed memory, in which case the allocation request is followed by memset(pointer, 0, size).

-Xclassgc

Enables dynamic unloading of classes by the JVM. This is the default behavior. To disable dynamic class unloading, use the -Xnoclassgc option.

-Xcompressedrefs

(64-bit only) Uses 32-bit values for references. See the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/60.html) section on "Compressed references" for more information. By default, references are 64-bit.

-Xdbg:<options>

Loads debugging libraries to support the remote debugging of applications. This option is equivalent to -Xrunjdwp. By default, the debugging libraries are not loaded, and the VM instance is not enabled for debug.

-Xdebug

This option is deprecated. Use -Xdbg for debugging.

-Xdiagnosticscollector[:settings=<filename>]

Enables the Diagnostics Collector. See the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/60.html) section on "The Diagnostics Collector" for more information. The settings option allows you to specify a different Diagnostics Collector settings file to use instead of the default dc.properties file in the JRE.

-Xdisablejavadump

Turns off Javadump generation on errors and signals. By default, Javadump generation is enabled.

-Xdump

See the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/60.html) section on "Using dump agents" for more information.

-Xenableexplicitgc

Signals to the VM that calls to System.gc() trigger a garbage collection. This option is enabled by default.

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

-Xiss<size>

Sets the initial stack size for Java threads. By default, the stack size is set to 2 KB. Use the -verbose:sizes option to output the value that the VM is using.

-Xjarversion

Produces output information about the version of each jar file in the class path, the boot class path, and the extensions directory. Version information is taken from the Implementation-Version and Build-Level properties in the manifest of the jar.

-Xjni:<suboptions>

Sets JNI options. You can use the following suboption with the -Xjni option:

-Xjni:arrayCacheMax=[<size in bytes>|unlimited]

Sets the maximum size of the array cache. The default size is 8096 bytes.

-Xlinenumbers

Displays line numbers in stack traces for debugging. See also -Xnolinenumbers. By default, line numbers are on.

-Xlog

Enables message logging. To prevent message logging, use the -Xlog:none option. By default, logging is enabled. This option is available from Java 6 SR5. See Messages.

-Xlp<size>

Linux: Requests the JVM to allocate the Java heap with large pages. If large pages are not available, the JVM does not start, displaying the error message GC: system configuration does not support option --> '-Xlp'. The JVM uses shmget() to allocate large pages for the heap. Large pages are supported by systems running Linux kernels v2.6 or higher. By default, large pages are not used.

AIX®, Linux, and Windows only: If a <size> is specified, the JVM attempts to allocate the JIT code cache memory using pages of that size. If unsuccessful, or if executable pages of that size are not supported, the JIT code cache memory is allocated using the smallest available executable page size.

-Xmso<size>

Sets the initial stack size for operating system threads. By default, this option is set to 256 KB, except for Windows 32-bit, which is set to 32 KB.

-Xnoagent

Disables support for the old JDB debugger.

-Xnoclassgc

Disables dynamic class unloading. This option disables the release of native and Java heap storage associated with Java class loaders and classes that are no longer being used by the JVM. The default behavior is as defined by -Xclassgc. Enabling this option is not recommended except under the direction of the IBM Java support team. This is because the option can cause unlimited native memory growth, leading to out-of-memory errors.

-Xnolinenumbers

Disables the line numbers for debugging. See also -Xlinenumbers. By default, line number are on.

-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 definitions. By default, no option file is used.

The options file does not support these options:

• -version
• -showversion
• -fullversion
• -Xjarversion
• -memorycheck
• -assert
• -help

<file> contains options that are processed as if they had been entered directly as command-line options. For example, the options file might contain:

-DuserString=ABC123
-Xmx256MB

Some options use quoted strings as parameters. Do not split quoted strings over multiple lines using the line continuation character '\'. The '¥' character is not supported as a line continuation character. For example, the following example is not valid in an options file:

-Xevents=vmstop,exec="cmd /c \
echo %pid has finished."

The following example is valid in an options file:

-Xevents=vmstop, \
exec="cmd /c echo %pid has finished."

-Xoss<size>

Recognized but deprecated. Use -Xss and -Xmso. Sets the maximum Java stack size for any thread. The default for AIX is 400 KB.

-Xrdbginfo:<host>:<port>

Loads the remote debug information server with the specified host and port. By default, the remote debug information server is disabled.

-Xrs

Disables signal handling in the JVM. Setting -Xrs prevents the Java runtime from handling any internally or externally generated signals such as SIGSEGV and SIGABRT. Any signals raised are handled by the default operating system handlers.

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

-Xrunjdwp[:help] | [:<option>=<value>, ...]

Loads debugging libraries to support the remote debugging of applications. This option is the same as -Xdbg.

-Xrunjnichk[:help] | [:<option>=<value>, ...]

Deprecated. Use -Xcheck:jni instead.

-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. Minimum cache size is 4 KB. Maximum cache size is platform-dependent. The size of cache that you can specify is limited by the amount of physical memory and paging space available to the system. 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 that you can create.

-XselectiveDebug

Enables selective debugging. Use the com.ibm.jvm.Debuggable annotation to mark classes and methods that must be available for debugging. The JVM optimizes methods that do not need debugging to provide better performance in a debugging environment. See the User Guide for your platform for more information.

-Xshareclasses:<suboptions>

Enables class sharing. This option can take a number of suboptions, some of which are cache utilities. Cache utilities perform the required operation on the specified cache, without starting the VM. You can combine multiple suboptions, separated by commas, but the cache utilities are mutually exclusive.

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

cacheDir=<directory>

Sets the directory in which cache data is read and written. By default, <directory> is /tmp/javasharedresources on Linux, AIX, z/OS®, and IBM i. You must have sufficient permissions in <directory>. The JVM writes persistent cache files directly into the directory specified. Persistent cache files can be safely moved and deleted from the file system. Nonpersistent caches are stored in shared memory and have control files that describe the location of the memory. Control files are stored in a javasharedresources subdirectory of the cacheDir specified. Do not move or delete control files in this directory. The listAllCaches utility, the destroyAll utility, and the expire suboption work only in the scope of a given cacheDir.

cacheRetransformed

Enables caching of classes that have been transformed using the JVMTI RetransformClasses function. See the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/60.html) section on the "JVMTI redefinition and retransformation of classes" for more information.

destroy (Utility option)

Destroys a cache specified by the name, cacheDir, and nonpersistent suboptions. A cache can be destroyed only if all JVMs using it have shut down and the user has sufficient permissions.

destroyAll (Utility option)

Tries to destroy all caches available using the specified cacheDir and nonpersistent suboptions. A cache can be destroyed only if all JVMs using it have shut down and the user has sufficient permissions.

expire=<time in minutes> (Utility option)

Destroys all caches that have been unused for the time specified before loading shared classes. This option is not a utility option because it does not cause the JVM to exit.

groupAccess

Sets operating system permissions on a new cache to allow group access to the cache. The default is user access only.

help

Lists all the command-line options.

listAllCaches (Utility option)

Lists all the compatible and incompatible caches that exist in the specified cache directory. If you do not specify cacheDir, the default directory is used. Summary information, such as Java version and current usage, is displayed for each cache.

mprotect=[all | default | none]

By default, the memory pages containing the cache are protected at all times, unless a specific page is being updated. This protection helps prevent accidental or deliberate corruption to the cache. The cache header is not protected by default because this protection has a small performance cost. Specifying all ensures that all the cache pages are protected, including the header. Specifying none disables the page protection.

modified=<modified context>

Used when a JVMTI agent is installed that might modify bytecode at run time. If you do not specify this suboption and a bytecode modification agent is installed, classes are 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 an application with a modification context and then run it again with a different modification context, all classes are stored twice in the cache. See the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/60.html) section "Dealing with runtime bytecode modification" for more information.

name=<name>

Connects to a cache of a given name, creating the cache if it does not exist. This option is 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 inserts the current user name. You can specify "%g" in the cache name to insert the current group name.

noaot

Disables caching and loading of AOT code.

noBootclasspath

Disables the storage of classes loaded by the bootstrap class loader in the shared classes cache. Often used with the SharedClassURLFilter API to control exactly which classes are cached. See the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/60.html) section on the "SharedClassHelper API" for more information about shared class filtering.

none

Added to the end of a command line, disables class data sharing. This suboption overrides class sharing arguments found earlier on the command line.

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 you select nonfatal and the shared classes cache fails to initialize, the JVM attempts to connect to the cache in read-only mode. If this attempt fails, the JVM starts without class data sharing.

nonpersistent

Uses a nonpersistent cache. The cache is lost when the operating system shuts down. Nonpersistent and persistent caches can have the same name. You must always use the nonpersistent suboption when running utilities such as destroy on a nonpersistent cache.

persistent (default for Windows and Linux platforms)

Uses a persistent cache. The cache is created on disk, which persists beyond operating system restarts. Nonpersistent and persistent caches can have the same name.

printAllStats (Utility option)

Displays detailed information about the contents of the cache specified in the name=<name> suboption. If the name is not specified, statistics are displayed about the default cache. Every class is listed in chronological order with a reference to the location from which it was loaded. See the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/60.html) section on the "printAllStats utility" for more information.

printStats (Utility option)

Displays summary information for the cache specified by the name, cacheDir, and nonpersistent suboptions. 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 (http://www.ibm.com/developerworks/java/jdk/diagnosis/60.html) section on the "printStats utility" for more information.

readonly

Opens an existing cache with read-only permissions. The JVM does not create a new cache with this suboption. Opening a cache read-only prevents the JVM from making any updates to the cache. It also allows the JVM to connect to caches created by other users or groups without requiring write access. By default, this suboption is not specified.

reset

Causes a cache to be destroyed and then re-created when the JVM starts up. This option can be added to the end of a command line as -Xshareclasses:reset.

safemode

Forces the JVM to load all classes from disk and apply the modifications to those classes (if applicable). See the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/60.html) section on "Using the safemode option" for more information.

silent

Disables all shared class messages, including error messages. Unrecoverable error messages, which prevent the JVM from initializing, are displayed.

verbose

Gives detailed output on the cache I/O activity, listing information about classes being stored and found. Each class loader is given a unique ID (the bootstrap loader is always 0) and the output shows the class loader hierarchy at work, where class loaders must ask their parents for a class before they can load it themselves. It is typical to see many failed requests; this behavior is expected for the class loader hierarchy. The standard option -verbose:class also enables class sharing verbose output if class sharing is enabled.

verboseAOT

Enables verbose output when compiled AOT code is being found or stored in the cache. AOT code is generated heuristically. You might not see any AOT code generated at all for a small application. You can disable AOT caching using the noaot suboption. See the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/60.html) section on "JITM messages" for a list of the messages produced.

verboseHelper

Enables verbose output for the Java Helper API. This output shows you how the Helper API is used by your ClassLoader.

verboseIO

Gives detailed output on the cache I/O activity, listing information about classes being stored and found. Each class loader is given a unique ID (the bootstrap loader is always 0) and the output shows the class loader hierarchy at work, where class loaders must ask their parents for a class before they can load it themselves. It is typical to see many failed requests; this behavior is expected for the class loader hierarchy.

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

-Xss<size>

Sets the maximum stack size for Java threads. The default is 256 KB for 32-bit JVMs and 512 KB for 64-bit JVMs.

-Xssi<size>

Sets the stack size increment for Java threads. When the stack for a Java thread becomes full it is increased in size by this value until the maximum size (-Xss) is reached. The default is 16 KB.

-Xthr:minimizeUserCPU

Minimizes user-mode CPU usage in thread synchronization where possible. The reduction in CPU usage might be a trade-off in exchange for lower performance.

-Xtrace[:help] | [:<option>=<value>, ...]

See the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/60.html) section on the "Controlling the trace" for more information.

-Xverify[:<option>]

With no parameters, enables the verifier, which is the default. Therefore, if used on its own with no parameters, for example, -Xverify, this option does nothing. Optional parameters are as follows:

• all - enable maximum verification
• none - disable the verifier
• remote - enables strict class-loading checks on remotely loaded classes

The verifier is on by default and must be enabled for all production servers. Running with the verifier off is not a supported configuration. If you encounter problems and the verifier was turned off using -Xverify:none, remove this option and try to reproduce the problem.

-Xzero[:<option>]

Enables reduction of the memory footprint of Java when concurrently running multiple Java invocations. -Xzero might not be appropriate for all types of applications because it changes the implementation of java.util.ZipFile, which might cause extra memory usage. -Xzero includes the optional parameters:

• j9zip - enables the j9zip suboption
• noj9zip - disables the j9zip suboption
• sharezip - enables the sharezip suboption
• nosharezip - disables the sharezip suboption
• none - disables all suboptions
• describe - prints the suboptions in effect

Because future versions might include more default options, -Xzero options are used to specify the suboptions that you want to disable. By default, -Xzero enables j9zip and sharezip. A combination of j9zip and sharezip enables all jar files to have shared caches:

• j9zip - uses a new java.util.ZipFile implementation. This suboption is not a requirement for sharezip; however, if j9zip is not enabled, only the bootstrap jars have shared caches.
• sharezip - puts the j9zip cache into shared memory. The j9zip cache is a map of names to file positions used by the compression implementation to quickly find compressed entries. You must enable -Xshareclasses to avoid a warning message. When using the sharezip suboption, note that this suboption allows every opened .zip file and .jar file to store the j9zip cache in shared memory, so you might fill the shared memory when opening multiple new .zip files and .jar files. The affected API is java.util.zip.ZipFile (superclass of java.util.jar.JarFile). The .zip and .jar files do not have to be on a class path.

-Xzero is available only in Java 6 SR1 and beyond. When enabled, the system property com.ibm.zero.version is defined, and has a current value of 1. For Java 6 SR1 and Java 6 SR2, the -Xzero option is accepted only on Windows x86-32 and Linux x86-32 platforms. From Java 6 SR3, -Xzero is accepted on all platforms; however, it is enabled only on Windows x86-32 and Linux x86-32 platforms.

-XX command-line options

These options are subject to change without notice.

-XXallowvmshutdown:[false|true]

This option is provided as a workaround for customer applications that cannot shut down cleanly, as described in APAR IZ59734. Customers who need this workaround should use -XXallowvmshutdown:false. The default option is -XXallowvmshutdown:true forJava 6 SR5 onwards.

-XX:MaxDirectMemorySize=<size>

Sets the maximum size for an nio direct buffer. By default, the maximum size is 64 MB.

-XX:-StackTraceInThrowable

This option removes stack traces from exceptions. By default, stack traces are available in exceptions. Including a stack trace in exceptions requires walking the stack and that can affect performance. Removing stack traces from exceptions can improve performance but can also make problems harder to debug.

When this option is enabled, Throwable.getStackTrace() returns an empty array and the stack trace is displayed when an uncaught exception occurs. Thread.getStackTrace() and Thread.getAllStackTraces() are not affected by this option.

-XX:+UseCompressedOops

(64-bit only) This option enables compressed references in 64-bit JVMs and is provided to help when porting applications from the Sun JVM to the IBM JVM. This option might not be supported in subsequent releases. The -XX:+UseCompressedOops option is similar to specifying -Xcompressedrefs, which is detailed in the topic JVM command-line options .

-XX:-UseCompressedOops

(64-bit only) This option prevents the use of compressed references in 64-bit JVMs. The option is provided to help when porting applications from the Sun JVM to the IBM JVM, and might not be supported in subsequent releases.

JIT and AOT command-line options

You might need to read the section on JIT and AOT problems in the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/60.html) to understand some of the references that are given here.

-Xaot[:<parameter>=<value>, ...]

With no parameters, enables the AOT compiler. The AOT compiler is enabled by default but is not active unless shared classes are enabled. Using this option on its own has no effect. Use this option to control the behavior of the AOT compiler. These parameters are useful:

count=<n>

Where <n> is the number of times a method is called before it is compiled. For example, setting count=0 forces the AOT compiler to compile everything on first execution.

limitFile=(<filename>,<m>,<n>)

Compile only the methods listed on lines <m> to <n> in the specified limit file. Methods not listed in the limit file and methods listed on lines outside the range are not compiled.

loadExclude=<methods>

Do not load methods beginning with <methods>.

loadLimit=<methods>

Load methods beginning with <methods> only.

loadLimitFile=(<filename>,<m>,<n>)

Compile only the methods listed on lines <m> to <n> in the specified limit file. Methods not listed in the limit file and methods listed on lines outside the range are not compiled.

verbose

Displays information about the AOT and JIT compiler configuration and method compilation.

-Xcodecache<size>

Sets the size of each block of memory that is allocated to store native code of compiled Java methods. By default, this size is selected internally according to the CPU architecture and the capability of your system. If profiling tools show significant costs in trampolines (JVMTI identifies trampolines in a methodLoad2 event), that is a good prompt to change the size until the costs are reduced. Changing the size does not mean always increasing the size. The option provides the mechanism to tune for the right size until hot interblock calls are eliminated. A reasonable starting point to tune for the optimal size is (totalNumberByteOfCompiledMethods * 1.1). This option is used to tune performance.

-Xint

Makes the JVM use the Interpreter only, disabling the Just-In-Time (JIT) and Ahead-Of-Time (AOT) compilers. By default, the JIT compiler is enabled. By default, the AOT compiler is enabled, but is not used by the JVM unless shared classes are also enabled.

-Xjit[:<parameter>=<value>, ...]

With no parameters, enables the JIT compiler. The JIT compiler is enabled by default, so using this option on its own has no effect. Use this option to control the behavior of the JIT compiler. Useful parameters are:

count=<n>

Where <n> is the number of times a method is called before it is compiled. For example, setting count=0 forces the JIT compiler to compile everything on first execution.

limitFile=(<filename>, <m>, <n>)

Compile only the methods listed on lines <m> to <n> in the specified limit file. Methods not listed in the limit file and methods listed on lines outside the range are not compiled.

optlevel=[ noOpt | cold | warm | hot | veryHot | scorching ]

Forces the JIT compiler to compile all methods at a specific optimization level. Specifying optlevel might have an unexpected effect on performance, including lower overall performance.

verbose

Displays information about the JIT and AOT compiler configuration and method compilation.

-Xnoaot

Turns off the AOT compiler and disables the use of AOT-compiled code. By default, the AOT compiler is enabled but is active only when shared classes are also enabled. Using this option does not affect the JIT compiler.

-Xnojit

Turns off the JIT compiler. By default, the JIT compiler is enabled. This option does not affect the AOT compiler. java -Xnojit -version displays JIT enabled if the AOT compiler is enabled.

-Xquickstart

Causes the JIT compiler to run with a subset of optimizations. This quicker compilation allows for improved startup time. When the AOT compiler is active (both shared classes and AOT compilation enabled), -Xquickstart causes all methods to be AOT compiled, which improves the startup time of subsequent runs. -Xquickstart can degrade performance if it is used with long-running applications that contain hot methods. The implementation of -Xquickstart is subject to change in future releases. By default, quickstart is disabled and JIT compilation is not delayed.

-XsamplingExpirationTime<time>

Disables the JIT sampling thread after <time> seconds. When the JIT sampling thread is disabled, no CPU cycles are consumed by an idle JVM.

-Xscmaxaot<size>

Optionally applies a maximum number of bytes in the class cache that can be used for AOT data. This option is useful if you want a certain amount of cache space guaranteed for non-AOT data. If this option is not specified, the maximum limit for AOT data is the amount of free space in the cache. The value of this option must not be smaller than the value of -Xscminaot and must not be larger than the value of -Xscmx.

-Xscminaot<size>

Optionally applies a minimum number of bytes in the class cache to reserve for AOT data. If this option is not specified, no space is specifically reserved for AOT data, although AOT data is still written to the cache until the cache is full or the -Xscmaxaot limit is reached. The value of this option must not exceed the value of -Xscmx or -Xscmaxaot. The value of -Xscminaot must always be considerably less than the total cache size, because AOT data can be created only for cached classes. If the value of -Xscminaot equals the value of -Xscmx, no class data or AOT data can be stored.

Garbage Collector command-line options

You might need to read the section on "Memory management" in the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/60.html) to understand some of the references that are given here.

The -verbose:gc option detailed in the section on "-verbose:gc logging" in the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/60.html) is the main diagnostic aid that is available for runtime analysis of the Garbage Collector. However, additional command-line options are available that affect the behavior of the Garbage Collector and might aid diagnostics.

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, you should use a number from 0 to 1, for example, 50% is 0.5.

-Xalwaysclassgc

Always perform dynamic class unloading checks during global collection. The default behavior is as defined by -Xclassgc.

-Xclassgc

Enables the collection of class objects only on class loader changes. This behavior is the default.

-Xcompactexplicitgc

Enables full compaction each time System.gc() is called.

-Xcompactgc

Compacts on all garbage collections (system and global).

The default (no compaction option specified) makes the GC compact based on a series of triggers that attempt to compact only when it is beneficial to the future performance of the JVM.

-Xconcurrentbackground<number>

Specifies the number of low-priority background threads attached to assist the mutator threads in concurrent mark. The default is 0 on Linux zSeries and 1 on all other platforms.

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

-Xconcurrentslack<size>

Attempts to keep the specified amount of the heap space free in concurrent collectors by starting the concurrent operations earlier. This behavior can sometimes alleviate pause time problems in concurrent collectors at the cost of longer concurrent cycles, affecting total throughput. The default is 0, which is optimal for most applications.

-Xconmeter:<soa | loa | dynamic>

This option determines the usage of which area, LOA (Large Object Area) or SOA (Small Object Area), is metered and hence which allocations are taxed during concurrent mark. Using -Xconmeter:soa (the default) applies the allocation tax to allocations from the small object area (SOA). Using -Xconmeter:loa applies the allocation tax to allocations from the large object area (LOA). If -Xconmeter:dynamic is specified , the collector dynamically determines which area to meter based on which area is exhausted first, whether it is the SOA or the LOA.

-Xdisableexcessivegc

Disables the throwing of an OutOfMemory exception if excessive time is spent in the GC.

-Xdisableexplicitgc

Disables System.gc() calls.

Many applications still make an excessive number of explicit calls to System.gc() to request garbage collection. In many cases, these calls degrade performance through premature garbage collection and compactions. However, you cannot always remove the calls from the application.

The -Xdisableexplicitgc parameter allows the JVM to ignore these garbage collection suggestions. Typically, system administrators use this parameter in applications that show some benefit from its use.

By default, calls to System.gc() trigger a garbage collection.

-Xdisablestringconstantgc

Prevents strings in the string intern table from being collected.

-Xenableexcessivegc

If excessive time is spent in the GC, this option returns null for an allocate request and thus causes an OutOfMemory exception to be thrown. This action occurs only when the heap has been fully expanded and the time spent is making up at least 95%. This behavior is the default.

-Xenablestringconstantgc

Enables strings from the string intern table to be collected. This behavior is the default.

-Xgc:<options>

Passes options such as verbose, compact, and nocompact to the Garbage Collector.

-Xgc:splitheap

Allocates the new and old areas of the generational Java heap in separate areas of memory. Using a split heap forces the Garbage Collector to use the gencon policy and disables resizing of the new and old memory areas. See the section on the "Split heap" in the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/60.html) for more information. By default, the Java heap is allocated in a single contiguous area of memory.

-Xgcpolicy:<optthruput | optavgpause | gencon | subpool (AIX, Linux and IBM i on IBM POWER® architecture, Linux and z/OS on zSeries) >

Controls the behavior of the Garbage Collector.

The optthruput option is the default and delivers very high throughput to applications, but at the cost of occasional pauses. Disables concurrent mark.

The optavgpause option reduces the time that is spent in these garbage collection pauses and limits the effect of increasing heap size on the length of the garbage collection pause. Use optavgpause if your configuration has a very large heap. Enables concurrent mark.

The gencon option requests the combined use of concurrent and generational GC to help minimize the time that is spent in any garbage collection pause.

The subpool option (AIX, Linux and IBM i on IBM POWER architecture, and z/OS) uses an improved object allocation algorithm to achieve better performance when allocating objects on the heap. This option might improve performance on large SMP systems.

-Xgcthreads<number>

Sets the number of threads that the Garbage Collector uses for parallel operations. This total number of GC threads is composed of one application thread with the remainder being dedicated GC threads. By default, the number is set to the number of physical CPUs present. To set it to a different number (for example 4), use -Xgcthreads4. The minimum valid value is 1, which disables parallel operations, at the cost of performance. No advantage is gained if you increase the number of threads above the default setting; you are recommended not to do so.

On systems running multiple JVMs or in LPAR environments where multiple JVMs can share the same physical CPUs, you might want to restrict the number of GC threads used by each JVM so that, if multiple JVMs perform garbage collection at the same time, the total number of parallel operation GC threads for all JVMs does not exceed the number of physical CPUs present.

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

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

-Xloainitial<percentage>

Specifies the initial percentage (between 0 and 0.95) of the current tenure space allocated to the large object area (LOA). The default is 0.05 or 5%.

-Xloamaximum<percentage>

Specifies the maximum percentage (between 0 and 0.95) of the current tenure space allocated to the large object area (LOA). The default is 0.5 or 50%.

-Xloaminimum<percentage>

Specifies the minimum percentage (between 0 and 0.95) of the current tenure space allocated to the large object area (LOA). The LOA will not shrink below this value. The default is 0 or 0%.

-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 by 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 10MB. 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 tries to shrink the heap. The default value is 0.6 (60%).

-Xmaxt<percentage>

Specifies the maximum percentage of time to be spent in Garbage Collection. If the percentage of time rises above this value, the JVM tries to expand the heap. The default value is 13%.

-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 produce 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 produce 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. The default value is 30%.

-Xmint<percentage>

Specifies the minimum percentage of time which should be spent in Garbage Collection. If the percentage of time drops below this value, the JVM tries to shrink the heap. The default value is 5%.

-Xmn<size>

Sets the initial and maximum size of the new area to the specified value when using -Xgcpolicy:gencon. Equivalent to setting both -Xmns and -Xmnx. If you set either -Xmns or -Xmnx, you cannot set -Xmn. If you try to set -Xmn with either -Xmns or -Xmnx, the VM does not start, returning an error. By default, -Xmn is not set. If the scavenger is disabled, this option is ignored.

-Xmns<size>

Sets the initial size of the new area to the specified value when using -Xgcpolicy:gencon. By default, this option is set to 25% of the value of the -Xms option. This option returns an error if you try to use it with -Xmn. You can use the -verbose:sizes option to find out the values that the VM is currently using. If the scavenger is disabled, this option is ignored.

-Xmnx<size>

Sets the maximum size of the new area to the specified value when using -Xgcpolicy:gencon. By default, this option is set to 25% of the value of the -Xmx option. This option returns an error if you try to use it with -Xmn. You can use the -verbose:sizes option to find out the values that the VM is currently using. If the scavenger is disabled, this option is ignored.

-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 try to set -Xmo with either -Xmos or -Xmox, the VM does not start, returning an error. By default, -Xmo is not set.

-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, set by -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 set to 75% of the value of the -Xms option. This option returns an error if you try to use it with -Xmo. You can use the -verbose:sizes option to find out the values that the VM is currently 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 set to the same value as the -Xmx option. This option returns an error if you try to use it with -Xmo. You can use the -verbose:sizes option to find out the values that the VM is currently using.

-Xmr<size>

Sets the size of the Garbage Collection "remembered set". This set is a list of objects in the old (tenured) heap that have references to objects in the new area. By default, this option is set to 16K.

-Xmrx<size>

Sets the remembered maximum size setting.

-Xms<size>

Sets the initial Java heap size. You can also use the -Xmo option detailed above. The minimum size is 1 MB.

If scavenger is enabled, -Xms >= -Xmn + -Xmo.

If scavenger is disabled, -Xms >= -Xmo.

-Xmx<size>

Sets the maximum memory size (-Xmx >= -Xms)

Examples of the use of -Xms and -Xmx:

-Xms2m -Xmx64m

Heap starts at 2 MB and grows to a maximum of 64 MB.

-Xms100m -Xmx100m

Heap starts at 100 MB and never grows.

-Xms20m -Xmx1024m

Heap starts at 20 MB and grows to a maximum of 1 GB.

-Xms50m

Heap starts at 50 MB and grows to the default maximum.

-Xmx256m

Heap starts at default initial value and grows to a maximum of 256 MB.

-Xnoclassgc

Disables class garbage collection. This option switches off garbage collection of storage associated with Java classes that are no longer being used by the JVM. The default behavior is as defined by -Xclassgc. By default, class garbage collection is performed.

-Xnocompactexplicitgc

Disables compaction on System.gc() calls. Compaction takes place on global garbage collections if you specify -Xcompactgc or if compaction triggers are met. By default, compaction is enabled on calls to System.gc().

-Xnocompactgc

Disables compaction on all garbage collections (system or global). By default, compaction is enabled.

-Xnoloa

Prevents allocation of a large object area; all objects will be allocated in the SOA. See also -Xloa.

-Xnopartialcompactgc

Disables incremental compaction. See also -Xpartialcompactgc.

-Xpartialcompactgc

Enables incremental compaction. See also -Xnopartialcompactgc. By default, this option is not set, so all compactions are full.

-Xsoftmx<size> (AIX only)

This option sets the initial maximum size of the Java heap. Use the -Xmx option to set the maximum heap size. Use the AIX DLPAR API in your application to alter the heap size limit between -Xms and -Xmx at run time. By default, this option is set to the same value as -Xmx.

-Xsoftrefthreshold<number>

Sets the value used by the GC to determine the number of GCs after which a soft reference is cleared if its referent has not been marked. The default is 32, meaning that the soft reference is cleared after 32 * (percentage of free heap space) GC cycles where its referent was not marked.

-Xtgc:<arguments>

Provides GC tracing options, where <arguments> is a comma-separated list containing one or more of the following arguments:

backtrace

Before a garbage collection, a single line is printed containing the name of the master thread for garbage collection, as well as the value of the osThread slot in its J9VMThread structure.

compaction

Prints extra information showing the relative time spent by threads in the "move" and "fixup" phases of compaction

concurrent

Prints extra information showing the activity of the concurrent mark background thread

dump

Prints a line of output for every free chunk of memory in the system, including "dark matter" (free chunks that are not on the free list for some reason, typically because they are too small). Each line contains the base address and the size in bytes of the chunk. If the chunk is followed in the heap by an object, the size and class name of the object is also printed. Similar to terse.

freeList

Before a garbage collection, prints information about the free list and allocation statistics since the last GC. Prints the number of items on the free list, including "deferred" entries (with the scavenger, the unused space is a deferred free list entry). For TLH and non-TLH allocations, prints the total number of allocations, the average allocation size, and the total number of bytes discarded during allocation. For non-TLH allocations, also included is the average number of entries that were searched before a sufficiently large entry was found.

parallel

Produces statistics on the activity of the parallel threads during the mark and sweep phases of a global GC.

references

Prints extra information every time that a reference object is enqueued for finalization, showing the reference type, reference address, and referent address.

scavenger

Prints extra information after each scavenger collection. A histogram is produced showing the number of instances of each class, and their relative ages, present in the survivor space. The space is linearly walked to achieve this.

terse

Dumps the contents of the entire heap before and after a garbage collection. For each object or free chunk in the heap, a line of trace output is produced. Each line contains the base address, "a" if it is an allocated object, and "f" if it is a free chunk, the size of the chunk in bytes, and, if it is an object, its class name.

-Xverbosegclog[:<file>[,<X>,<Y>]]

Causes -verbose:gc output to be written to the specified file. If the file cannot be found, -verbose:gc tries to create the file, and then continues as normal if it is successful. If it cannot create the file (for example, if an invalid filename is passed into the command), it redirects the output to stderr.

If you specify <X> and <Y> the -verbose:gc output is redirected to X files, each containing Y GC cycles.

The dump agent tokens can be used in the filename. See the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/60.html) section on the "Dump agent tokens" for more information. If you do not specify <file>, verbosegc.%Y%m%d.%H%M%S.%pid.txt is used.

By default, no verbose GC logging occurs.

Appendix B. Known limitations

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

CUPS support

The IBM SDK for Java does not support printing using the CUPS interface.

BIOS settings on AMD64 SMP systems

The Node memory interleaving BIOS setting must be set to DISABLED. Otherwise, unpredictable results might occur, including Java crashes and hangs. This instruction is in accordance with recommendations from AMD.

JConsole monitoring tool Local tab

In the IBM 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 start the application that you want to monitor, set these command-line options:

-Dcom.sun.management.jmxremote.port=<value>

Specifies the port the management agent listens on.

-Dcom.sun.management.jmxremote.authenticate=false

Disables authentication unless you have created a user name file.

-Dcom.sun.management.jmxremote.ssl=false

Disables SSL encryption.

GUI applications, such as the JConsole monitoring tool, on 64-bit Ubuntu with a 32-bit JVM

When running a 32-bit JVM on a 64-bit Ubuntu system, GUI applications do not start because some AWT libraries are missing. To fix the problem, install the 32-bit libraries using the ia32-libs package:

sudo apt-get install ia32-libs

The following exception is thrown if the libraries are not available:

Exception in thread "main" java.lang.UnsatisfiedLinkError: awt (An exception was pending after running JNI_OnLoad)
        at java.lang.ClassLoader.loadLibraryWithPath(ClassLoader.java:993)
        at java.lang.ClassLoader.loadLibraryWithClassLoader(ClassLoader.java:962)
        at java.lang.System.loadLibrary(System.java:465)
        ... lines removed for clarity ...

If problems are encountered with DNS name resolution, install the package lib32nss-mdns.

Incorrect stack traces when loading new classes after an Exception is caught

If new classes are loaded after an Exception has been caught, the stack trace contained in the Exception might become incorrect. The stack trace becomes incorrect if classes in the stack trace are unloaded, and new classes are loaded into their memory segments.

Web Start and Java 1.3 applications

The IBM SDK for Linux, v6 Web Start does not support launching Java 1.3 applications.

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 stop or endless loop, because the process finishes 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.

Creating a JVM using JNI

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

• JNI_VERSION_1_2(0x00010002)
• JNI_VERSION_1_4(0x00010004)

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

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

Window managers and keyboard shortcuts

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

X Window System file descriptors

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

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

export JAVA_HIGH_ZIPFDS=300

The first 300 jar files are then loaded using the file descriptors 724 - 1023. Any jar files opened after that are opened in the typical range.

DBCS and the KDE clipboard

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

Limit on threads using the LinuxThreads library

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

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

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

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

ThreadMXBean Thread User CPU Time limitation

There is no way to distinguish between user mode CPU time and system mode CPU time on this platform. ThreadMXBean.getThreadUserTime(), ThreadMXBean.getThreadCpuTime(), ThreadMXBean.getCurrentThreadUserTime(), and ThreadMXBean.getCurrentThreadCpuTime() all return the total CPU time for the required thread.

KeyEvents and window managers

KeyEvent results that include the Alt key might differ between window managers in Linux. They also differ from results of other operating systems. When using the default settings, Ctrl+Alt+A in the KWin window manager produces a KeyEvent, whereas Ctrl+Alt+A in the Metacity window manager does not produce a key event.

The X Window System and the Meta key

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

xmodmap -pk  

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

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

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

SIGSEGV when creating a JVM using JNI

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

Lack of resources with highly threaded applications

If you are running with many concurrent threads, you might get a warning message:

java.lang.OutOfMemoryError

The message is an indication that your machine is running out of system resources and messages can be caused by the following reasons:

• If your Linux installation uses LinuxThreads, rather than NPTL, the number of processes created exceeds your user limit.
• Not enough system resources are available to create new threads. In this case, you might also see other Java exceptions, depending on what your application is running.
• Kernel memory is either running out or is fragmented. You can see corresponding Out of Memory kernel messages in /var/log/messages. The messages are associated with the ID of the killed process.

Try tuning your system to increase the corresponding system resources.

Globalization on Ubuntu

For Chinese, Korean, and Japanese language users of Ubuntu only.

Chinese, Korean, and Japanese locales do not display the correct fonts if CJK fonts are not installed.

X Server and client font problems

When running a Java AWT or Swing application on a Linux machine and exporting the display to a second machine, you might experience problems displaying some dialogs if the set of fonts loaded on the X client machine is different from the set loaded on the X server machine. To avoid this problem, install the same fonts on both machines.

UTF-8 encoding and MalformedInputExceptions

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

AMI and xcin problems when exporting displays

If you are using AMI and xcin in a cross-platform environment, there might be a problem if you try to export the display between a 32-bit and a 64-bit system, or between a big-endian and a little-endian system. If you have this problem, upgrade to the latest version of AMI and xcin.

RHEL4 and XIM

For Chinese, Korean and Japanese language users of RHEL4 only.

No XIM server is installed by default. To enter DBCS characters to a Java application, install a XIM server package such as iiimf-x or kinput2.

RHEL4 and IIIMF

For Chinese, Korean, and Japanese language users of RHEL4 only.

If you are using the Internet/Intranet Input Method Framework (IIIMF), use IIIMF packages that are included in Red Hat Enterprise Linux 4 Update 2 or later. Contact Red Hat for guidance, at http://www.redhat.com.

(zSeries 64-bit only) You might experience IIIMF failures or a failure to start. To resolve the problem, upgrade to the latest IIIMF packages.

(Traditional Chinese on PPC, s390, or s390x only) IIIMF might not work. To resolve the problem, use iiimf-le-xcin-0.1.7-13.EL4 or later.

(Simplified Chinese on PPC, s390, or s390x only) IIIMF might not work correctly. To resolve the problem, use IIMF packages included in RHEL4 Update 5 or later.

RHEL4 and the zh_CN.GB18030 locale

Simplified Chinese language users of RHEL4 only.

The zh_CN.GB18030 locale is not supported by xlib in RHEL4. xterm cannot activate Input Method Server to enter GB18030 characters. Use the zh_CN.UTF8 locale instead. If you have existing programs or data encoded with GB2312, GBK, or GB18030, and you want to migrate them to RHEL4, you must preprocess them with iconv to convert them to UTF-8 encoding so that the programs can run and data can be displayed properly in RHEL4 with the zh_CN.UTF8 locale.

This limitation is resolved in RHEL4 U3.

RHEL4 and xcin

You might experience hangs with xcin on RHEL4. To resolve the problem, set ICCHECK_DISABLE to YES in the /etc/chinese/xcin/xcinrc file.

64-bit environments only

On RHEL4 with xcin (Traditional Chinese XIM server), you might experience unexpected behavior such as a segmentation fault with Java on 64-bit environments (such as AMD64 or zSeries 64-bit platforms). To resolve the problem, upgrade to the latest xcin package.

RHEL4 and IIIMF focus change problems

RHEL4 only.

When using IIIMF (Internet Intranet Input Method Framework) to enter DBCS characters, you might encounter focus change problems. The problem occurs when minimizing active input components. After restoring the component, the input method will switch back to SBCS. DBCS must then be manually reactivated.

The following components have this focus change problem:

• java.awt.Canvas
• java.awt.Button
• javax.swing.JButton
• javax.swing.JSplitPane
• javax.swing.JComboBox
• javax.swing.JList

XIM and the Java Plug-in

RHEL4, and SLES9 only

For Japanese, Chinese, and Korean language users, you cannot use XIM to enter your own characters into text components on a Java applet in a Web browser. This limitation occurs because XEmbed requires a fix to the X11 library file. To work around this situation, specify the -Dsun.awt.noxembed=true system parameter to disable XEmbed. You can set this option by using the control panel:

1. Open the Java Plug-in control panel and go to the Java tab.
2. Click the View button in the Java Applet Runtime Settings.
3. Enter -Dsun.awt.noxembed=true in the Java Runtime Parameters and click OK.
4. Click Apply.
5. Start a browser.

This limitation is resolved in RHEL4 U3 and SLES9 SP3.

Arabic characters and Matrox video cards

Intel 32-bit platforms only

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

SLES9 NPTL and the parallel port driver

Intel 32-bit platforms only

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

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

JNI calls with more than eight parameters on PPC platforms

PPC platforms only

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

Parallel port operations on SLES9 before SP2

PPC platforms only

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

Compiling libFileStat.so on PPC 64-bit platforms

PPC 64-bit platforms only

The default gcc cross compiler (version 3.2-49) causes several errors. To generate the shared library libFileStat.so, run:

/opt/cross/bin/powerpc64-linux-gcc -shared -o libFileStat.so -I<SDK_PATH>/include FileStat.c

where <SDK_PATH> is the path to the installed SDK directory.

IPv6 on zSeries platforms

zSeries platforms only

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

xcin on 64-bit zSeries platforms

zSeries 64-bit platforms only

The Chinese and Taiwanese input method server (xcin) has not been tested.

Java Desktop API

The Java Desktop API might not work because one or more GNOME libraries are not available.

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.

Unicode Shift_JIS code page alias

Japanese users only

The Unicode code page alias "\u30b7\u30d5\u30c8\u7b26\u53f7\u5316\u8868\u73fe" for Shift_JIS has been removed. If you use this code page in your applications, replace it with Shift_JIS.

Unreadable characters on Swing components on Ubuntu

On Ubuntu systems configured for Chinese, Japanese, or Korean globalization, some characters on Java Swing components might not be readable because the font is unclear when anti-aliasing is not used. To improve the readability of the characters, set the swing.aatext property in the java or javaw command as follows:

-Dswing.aatext=true

Alternatively, use the IBM_JAVA_OPTIONS environment variable to specify this property.

-Xshareclasses:<options>

Shared classes cache and control files are not compatible between Java 6 SR4 and previous releases.

Java Kernel installation

The Java kernel aims to reduce the startup time imposed by an application when it finds that the installed JRE needs an update. When this situation occurs, the Java kernel automatically downloads only the Java components that are needed directly from the Sun Web site. This automated download is currently not possible with the IBM implementation of this Sun Java update.

Java Deployment Toolkit

The toolkit implements the JavaScript™ DeployJava.js, which can be used to automatically generate any HTML needed to deploy applets and Java Web Start applications. However, the automatic generation is not possible with the IBM release of Java, because the process involves downloading and running the specific JRE from a public site, using public functions.

Supported browsers for Java plug-ins

Next-generation Java plug-ins are supported only on the Firefox 3 and Firefox 3.5 browsers on Linux. These plug-ins do not work with the SeaMonkey browser on Linux PPC32 systems. More information can be found at: http://java.sun.com/javase/6/webnotes/6u10/plugin2/index.html#SUPPORTED_PLATFORMS

Supported platforms for Java plug-ins

Support for Java plug-ins and Java Web Start on Linux AMD64 systems is not available at this time.

Linux Completely Fair Scheduler affects Java performance

Java applications that use synchronization extensively might perform poorly on Linux distributions that include the Completely Fair Scheduler. The Completely Fair Scheduler (CFS) is a scheduler that was adopted into the mainline Linux kernel as of release 2.6.23. The CFS algorithm is different from the scheduling algorithms for previous Linux releases. It might change the performance properties of some applications. In particular, CFS implements sched_yield() differently, making it more likely that a yielding thread is given CPU time regardless.

If you encounter this problem, you might observe high CPU usage by your Java application, and slow progress through synchronized blocks. The application might appear to stop because of the slow progress.

There are two possible workarounds:

• Invoke the JVM with the additional argument -Xthr:minimizeUserCPU.
• Configure the Linux kernel to use a heuristic for sched_yield() that is more compatible with earlier versions, by setting the sched_compat_yield tunable kernel property to 1. For example:

  echo "1" > /proc/sys/kernel/sched_compat_yield

Do not use these workarounds unless you are experiencing poor performance.

This problem might affect IBM Developer Kit and Runtime Environment for Linux 5.0 (all versions) and 6.0 (all versions up to and including SR 4) running on Linux kernels that include the Completely Fair Scheduler. For IBM Developer Kit and Runtime Environment for Linux version 6.0 after SR 4, the use of CFS in the kernel is detected and the option -Xthr:minimizeUserCPU enabled automatically. Some Linux distributions that include the Completely Fair Scheduler are Ubuntu 8.04 and SUSE Linux Enterprise Server 11.

More information about CFS can be found at Multiprocessing with the Completely Fair Scheduler.

Expired GTE Cybertrust Certificate

The IBM Runtime Environment for Java contains an expired GTE CyberTrust Certificate in the CACERTS file for compatibility reasons. The CACERTS file is provided as a default truststore. Some common public certificates are provided as a convenience.

If no applications require the certificate, it can be left in the CACERTS file. Alternatively, the certificate can be deleted. If applications do require the certificate, modify them to use the newer GTE CyberTrust Global root certificate that expires in 2018.

This certificate might be removed for later versions of the SDK.

Using Web Start to launch a JNLP application

When using Web Start to launch a Java Network Launching Protocol (JNLP) application that requires an older version of Java, you might see an error containing the following message:

java.lang.NoClassDefFoundError: com/sun/deploy/util/BlackList

This results from a check controlled by the deployment configuration property deployment.security.blacklist.check The property is enabled using the Enable blacklist revocation check option in the Java Control Panel.

To work around the problem:

1. Launch the Java Control Panel.
2. Select Advanced tab -> Security.
3. Clear the Enable blacklist revocation check option.

Using -Xshareclasses:destroy during JVM startup

When running the command java -Xshareclasses:destroy on a shared cache that is being used by a second JVM during startup, you might have the following issues:

• The second JVM fails.
• The shared cache is deleted.

Notices

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:

• Intellectual Property Licensing
• Legal and Intellectual Property Law
• IBM Japan Ltd.
• 1623-14, Shimotsuruma, Yamato-shi
• Kanagawa 242-8502 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.

All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.

Trademarks

IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. If these and other IBM trademarked terms are marked on their first occurrence in this information with a trademark symbol (® or ™), these symbols indicate U.S. registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the Web at "Copyright and trademark information" at http://www.ibm.com/legal/copytrade.shtml.

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

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

UNIX is a registered trademark of The Open Group in the United States and other countries.

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.

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