# IBM 32-bit SDK for AIX platforms, Java Technology Edition

# SDK Guide

Version 6
Note

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

Copyright information

This edition of the user guide applies to the IBM 32-bit SDK for AIX, Java Technology Edition, Version 6, and to all subsequent releases, modifications, and Service Refreshes, until otherwise indicated in new editions.

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

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

# Contents

Preface
Overview
Version compatibility
Migrating from other IBM JVMs
AIX environment
Contents of the SDK and Runtime Environment
Contents of the Runtime Environment
Contents of the SDK
Installation
| |
Relocation
Upgrading the SDK
Verification
Setting the path
Setting the class path
Running Java applications
The java and javaw commands
Obtaining version information
Specifying Java options and system properties
Standard options
Globalization of the java command
Working with the LIBPATH environment variable
Working with the LDR_CNTRL=MAXDATA environment variable
Controlling page sizes with the LDR_CNTRL environment variable
The Just-In-Time (JIT) compiler
Disabling the JIT
Enabling the JIT
Determining whether the JIT is enabled
Specifying garbage collection policy
Garbage collection options
Pause time
Pause time reduction
Environments with very full heaps
Dynamic Logical Partitioning (DLPAR) support
| |
Live application mobility on AIX WPAR
Using the IPv6 extensions
Enhanced BiDirectional support
Euro symbol support
Using Indian and Thai input methods
Scaling support
SDK use of AIX large program support
Automatic LDR_CNTRL=MAXDATA values
Manual LDR_CNTRL=MAXDATA values
AIX Stack Execution Disable
Using the SDK to develop Java applications
Using XML
Migrating to the XL-TXE-J
XML reference information
Debugging Java applications
Java Debugger (JDB)
Determining whether your application is running on a 32-bit or 64-bit JVM
How the JVM processes signals
Signals used by the JVM
Linking a native code driver to the signal-chaining library
Writing JNI applications
JNI compatibility
Example of using AIX shared libraries
Support for thread-level recovery of blocked connectors
CORBA support
System properties for tracing the ORB
System properties for tuning the ORB
Java security permissions for the ORB
ORB implementation classes
RMI over IIOP
Implementing the Connection Handler Pool for RMI
Enhanced BigDecimal
AIX native threads
JNDI
HPROF Performance Profiler and JVMPI
GetCurrentThreadCpuTime
Known restriction
Support for XToolkit
Plug-in, Applet Viewer and Web Start
Using the Java plug-in
Supported browsers
Installing the Java plug-in
Changing the properties of the Java Plug-in
Java Plug-in HTML converter
Common Document Object Model (DOM) support
Using DBCS parameters
Working with applets
Running and debugging applets with the Applet Viewer
Java Applet Viewer and the classpath
Using Web Start
Running Web Start
WebStart Secure Static Versioning
Distributing Java applications
Class data sharing between JVMs
Overview of class data sharing
Class data sharing command-line options
Creating, populating, monitoring, and deleting a cache
Performance and memory consumption
Considerations and limitations of using class data sharing
Cache size limits
Runtime bytecode modification
Operating system limitations
Using SharedClassPermission
Adapting custom classloaders to share classes
Service and support for independent software vendors
Accessibility
Keyboard traversal of JComboBox components in Swing
Web Start accessibility
Any comments on this user guide?
Appendix A. Nonstandard options
Appendix B. Known limitations
Notices
Trademarks

# Preface

This user guide provides general information about the IBM(R) 32-bit SDK for AIX(R), Java(TM) Technology Edition, Version 6 and specific information about any differences in the IBM implementation compared with the Sun implementation.

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

The software that is contained in this release can be used only on AIX Version 5.3 or later. It is not supported, and does not work, on earlier versions of the AIX operating system. See AIX Environment for further details of requirements on the AIX operating system for this release.

Useful Web sites include:

- The Java download site for AIX
- IBM home page for Java

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

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

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

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

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

# Overview

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

## Version compatibility

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

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(R) 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

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

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

- The JVM shared library libjvm.so is now stored in jre/lib/ppc/j9vm and jre/lib/ppc/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 Appendix A. Nonstandard 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, invoked using -verbose:Xclassdep, is not supported. If you specify -verbose:Xclassdep, the JVM will issue an error message and will not start.

## AIX environment

The IBM 32-bit SDK for AIX, v6, runs on AIX v5.3 |Maintenance Package AIX 5300-07 or |later, or AIX v6.1.

To test whether this Java v6 SDK is supported on a specific System p(TM) system, at the system prompt type:

    lscfg -p | fgrep Architecture

You should receive the reply:

    Model Architecture: chrp

Only "Common Hardware Reference Platform" (chrp) systems are supported by this SDK.

The environment variable LDR_CNTRL=MAXDATA is not supported for 64-bit processes. Only use LDR_CNTRL=MAXDATA on 32-bit processes.

If you are using one of the supported non-UTF8 CJK locales, you must install one of the following filesets (the install images are available on the AIX base CDs; updates are available from the AIX fix distribution Web site:

    X11.fnt.ucs.ttf (for ja_JP or Ja_JP)
    X11.fnt.ucs.ttf_CN (for zh_CN or Zh_CN)
    X11.fnt.ucs.ttf_KR (for ko_KR)
    X11.fnt.ucs.ttf_TW (for zh_TW or Zh_TW)

# Contents of the SDK and Runtime Environment

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

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

The documentation package is designed to be extracted into the SDK software installation directory. If you download the compressed version, be sure to preserve the path names when you extract the files from the archive.

## Contents of the Runtime Environment

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

- Core Classes - These are the compiled class files for the platform and must remain zipped for the compiler and interpreter to access them. Do not modify these classes; instead, create subclasses and override where you need to.
- 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 will be removed for Version 7 of the SDK. See http://www.ibm.com/support/docview.wss?uid=swg21225464 for more information.
- JRE tools - The following tools are part of the Runtime Environment and are in the /usr/java6/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://download.boulder.ibm.com/ibmdl/pub/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.
  javaws (Java Web Start)
    Enables the deployment and automatic maintenance of Java applications. For more information, see Running Web Start.
  jcontrol (Java Control Panel)
    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

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

The following tools are part of the SDK and are located in the /usr/java6/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)
    Configures your Runtime Environment.
  extcheck (Extcheck utility)
    Detects version conflicts between a target jar file and currently-installed extension jar files.
  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.
  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 WSDL file.
  xjc
    Compiles XML Schema files.
Include Files
  C headers for JNI programs.
User Guide
  This file.
copyright
  The copyright notice for the SDK for AIX software.
License

  The License file, /usr/swlag/<locale>/Java6.la, contains the license agreement for the SDK for AIX 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.

# Installation

The IBM 32-bit SDK for AIX, v6 complete release consists of several installp image files (packages). Each installp image file or package contains one or more related filesets. You can install the packages using the smit or smitty system management tools. Alternatively, you can use the installp command.

This package is required:

- Java 6.sdk (license, base SDK, Web Start, and dt.jar)

These packages are optional:

- Java6.samples (demos)
- Java6.source (src.jar)
- Java6.msg.$LANG (Localized messages)

$LANG is one of the following locales. These packages do not include any files but pull in required Unicode TrueType fonts, if not already installed, for these locales:

- Zh_CN
- zh_CN
- ko_KR
- Ja_JP
- ja_JP
- Zh_TW
- zh_TW

The SDK is installed in the directory:

    /usr/java6/

The following user-configurable files are installed to /etc/java6/ to support a configuration where the files are not shared:

- jre/lib/jaxp.properties
- jre/lib/logging.properties
- jre/lib/management/jmxremote.access
- jre/lib/management/jmxremote.password.template
- jre/lib/management/management.properties
- jre/lib/management/snmp.acl
- jre/lib/management/snmp.acl.template
- jre/lib/security/java.policy
- jre/lib/security/java.security
- jre/lib/security/javaws.policy
- jre/lib/xalan.properties
- jre/lib/xerces.properties

There are symbolic links in /usr/java6/ pointing to the files in /etc/java6/.

| | |

## Relocation

|
|

By default, the SDK is installed in /usr/java6/. |To install the SDK in another directory, use the AIX relocation commands.

|

Delete any .toc files in the directory containing |your installp images or PTFs before using the AIX relocation commands.

|

| |

### Commands

|

See the AIX man pages for more information |about the command-line options for these commands.

|

|
installp_r
|
  Install command. To install the SDK: |

      installp_r -a -Y -R /<Install Path>/ -d '.' Java6.sdk

  To |remove the SDK: |

      installp_r -u  -R /<Install Path>/ Java6.sdk

  |
|
lsutil
|
  List the user-defined installation paths. |

      lsutil

  |
|
lslpp_r
|
  Find details of installed products. |

      lslpp_r -R /<Install Path>/ -S [A|O]

  |
|
rmusil
|
  Remove existing user-defined installation paths. |

      rmusil -R /<Install Path>/

  |
|

## Upgrading the SDK

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

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

## Verification

To help ensure that the verification process behaves consistently, first:

    unset LIBPATH
    unset CLASSPATH
    unset JAVA_COMPILER
    unset JAVA_HOME
    export PATH=/usr/java6/jre/bin:/usr/java6/bin:$PATH

Remember: JAVA_HOME is used in V1.1.x releases. It is not required to set JAVA_HOME in this release.

If you issue the command:

    java -version

you should see:

    java version "1.6.0-internal" Java(TM) SE Runtime Environment (build 20070405_01)
    IBM J9 VM (build 2.4, J2RE 1.6.0 IBM J9 2.4 AIX ppc-32 jvmap3260-20070326_12091
    (JIT enabled) J9VM - 20070326_12091_BHdSMR JIT  - dev_20070326_1800 GC   -
    20070319_AA)

where dates, times, and specific build numbers may be different.

When verification is complete, log on again and review for possible conflicts any values that you might have assigned to these variables.

Unless .hotjava already existed, executing the applet viewer creates a directory called .hotjava in your home directory. Issuing the command:

    ls -a ~

should confirm that the directory has been created.

## Setting the path

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

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

    echo $PATH

To add the Java launchers to your path:

1. 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=/usr/java6/bin:/usr/java6/jre/bin:$PATH

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

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

    javac Myfile.Java

## Setting the class path

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

You need to set the class path explicitly only if:

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

To display the current value of your CLASSPATH environment variable, type the following command at a 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.

# Running Java applications

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

## The java and javaw commands

An overview of the java and javaw commands.

### Purpose

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

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

### Usage

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

The java and javaw commands have the following syntax:

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

### Parameters

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

### Obtaining version information

You obtain The IBM build and version number for your Java installation using the -version option. You can also obtain version information for all jar files on the class path by using the -Xjarversion option.

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 pap3260-20070913_01)
       IBM J9 VM (build 2.4, J2RE 1.6.0 IBM J9 2.4 AIX ppc-32 jvmap3260-20070905_13799 (JIT enabled)
       J9VM - 20070905_013799_bHdSMR
       JIT  - r9_20070903_1330
       GC   - 20070830_AA)

   Exact build dates and versions will change.

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:

    ...
    /usr/java6/jre/lib/ext/ibmpkcs11impl.jar  VERSION: 1.0 build_20070125
    /usr/java6/jre/lib/ext/dtfjview.jar
    /usr/java6/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

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

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

1. By specifying the option or property on the command line. For example:

       java -Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump MyJavaClass

2. By creating a file that contains the options, and specifying it on the command line using -Xoptionsfile=<file>.
3. By creating an environment variable called IBM_JAVA_OPTIONS containing the options. For example:

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

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

    java -Xint -Xjit myClass

The -Xjit option takes precedence.

### Standard options

The definitions for the standard options.

See Appendix A. Nonstandard 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>
  Enables verbose output. The available options are:
  class
    Writes an entry to stderr for each class that is loaded.
  gc
    Writes verbose garbage collection information to stderr. Use -Xverbosegclog to control the output. See the Diagnostics Guide for more information.
  jni
    Writes information to stderr describing the JNI services called by the application and JVM.
  sizes
    Writes information to stderr describing the active memory usage settings.
  stack
    Writes information to stderr describing the Java and C stack usage for each thread.
-version
  Prints product version.
-version:<value>
  Requires the specified version to run, for example "1.5".
-X
  Prints help on nonstandard options.

### Globalization of the java command

The java and javaw launchers accept arguments and class names containing any character that is in the character set of the current locale. You can also specify any Unicode character in the class name and arguments by using Java escape sequences.

To do this, use the -Xargencoding command-line option.

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

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

    java -Xargencoding '\u0048ello\u0057orld'

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

## Working with the LIBPATH environment variable

The LIBPATH environment variable tells AIX applications, such as the JVM, where to find shared libraries when they are located in a different directory from the directory that is specified in the header section of the program.

For example, the header section of the java command is as follows:

    > dump -H /usr/java6/jre/bin/java
    /usr/java6/jre/bin/java:

                            ***Loader Section***
                          Loader Header Information
    VERSION#         #SYMtableENT     #RELOCent        LENidSTR
    0x00000001       0x0000003f       0x0000006d       0x00000090

    #IMPfilID        OFFidSTR         LENstrTBL        OFFstrTBL
    0x00000006       0x00000b24       0x00000099       0x00000bb4

                            ***Import File Strings***
    INDEX  PATH                          BASE            MEMBER
    0     /usr/lib:/lib

    1                                    libc.a          shr.o
    2                                    libC.a          shr.o
    3                                    libpthreads.a   shr_comm.o
    4                                    libpthreads.a   shr_xpg5.o
    5                                    libbsd.a        shr.o

Index 0 (in bold above) contains the list of directories that are searched for shared objects if LIBPATH is not specified. If LIBPATH is set, the specified directories are searched for shared objects before those listed in Index 0 of the header.

The shared libraries for the SDK are in /usr/java6/jre/lib/ppc/ and /usr/java6/jre/lib/ppc/j9vm. The SDK's Java launcher programs (for example, java, javac, jar) automatically search these directories. If Java is installed as an AIX file set, the parent directory is /usr/java6/, but packages that bundle Java might use different directories. This path is already set by the Java launcher programs such as java, javac, or jar.

Set the LIBPATH if either of the following conditions applies:

- You are using other shared libraries (including JNI native libraries you use or develop). Set the LIBPATH to include the directory or directories that contain your libraries.
- You are using the JNI Invocation API to call Java code from you C/C++ application. Set the LIBPATH to include the directories that contain the JVM libraries in addition to those that contain your own libraries.

## Working with the LDR_CNTRL=MAXDATA environment variable

The LDR_CNTRL=MAXDATA environment variable controls the way AIX handles the memory space available to a 32-bit program.

The SDK normally sets appropriate LDR_CNTRL=MAXDATA settings automatically for the size of the Java heap. However, if you explicitly set the LDR_CNTRL=MAXDATA environment variable the SDK will not override the value you have specified. Do not override the automatic settings unless you have a complete understanding of the AIX memory models. For more information about the AIX memory models and the automatic settings used by the SDK, see SDK use of AIX large program support.

## Controlling page sizes with the LDR_CNTRL environment variable

The POWER4(TM) and later PowerPC(R) processors support the use of 16 MB large pages in addition to the default 4 KB pages. The POWER5+(TM) and later PowerPC processors add support for two new page sizes, 64 KB and 16 GB.

AIX v5.2 and later operating systems support 16 MB pages. AIX v5.3 maintenance package 5300-04 and later operating systems add support for the 64 KB and 16 GB page sizes. The 16 MB and 16 GB pages require AIX system configuration changes. For information on using 16MB pages with AIX, see http://www.ibm.com/servers/aix/whitepapers/large_page.html. For information about using either 64 KB or 16 GB pages with AIX , see http://www.ibm.com/servers/aix/whitepapers/multiple_page.pdf. Note that the default AIX page size is 4 KB.

The LDR_CNTRL=LARGE_PAGE_DATA environment variable can be used under the AIX v5.2 and later operating systems to control the use of 16 MB pages for the native data area and native heap of a program. The native data/heap normally uses 4 KB pages. You can override that default and use 16 MB large pages, if they are available, by setting LDR_CNTRL=LARGE_PAGE_DATA=Y. Using large pages for the native data/heap might improve the performance of Java applications that require a large amount of native heap space. In particular, the native heap is used for machine code generated by the just-in-time compiler and Java applications with a large number of compiled methods might benefit from using 16 MB pages for the native heap.

AIX v5.3 maintenance package 5300-04 adds new LDR_CNTRL variants that independently control the use of different page sizes for the text (TEXTPSIZE), stack (STACKPSIZE) and native data/heap (DATAPSIZE) areas. An example of the use of these variants is:

    LDR_CNTRL=TEXTPSIZE=4K@STACKPSIZE=64K@DATAPSIZE=64K

This example uses 4 KB pages for text, 64 KB pages for stack and 64 KB pages for the native data and native heap areas. A DATAPSIZE setting will override any LARGE_PAGE_DATA setting.

The new 64 KB pages are general-purpose and most workloads will see a benefit by using 64 KB pages for text, stack, native data, and the Java heap. The 16 GB pages are intended only for use in very high performance environments.

Note: Use the -Xlp option variants to request that the JVM allocates the Java heap with a specific size of pages.

For more information about using the LDR_CNTRL environment variables and on configuring AIX support for large pages, see http://www.ibm.com/servers/aix/whitepapers/large_page.html for AIX v5.2 information on 16 MB pages, and http://www.ibm.com/servers/aix/whitepapers/multiple_page.pdf for information on AIX v5.3 support of 64 KB and 16 GB pages.

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

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

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

The Stack Execution Disable (SED) feature in the AIX 5300-03 Recommended Maintenance package stops code from executing in data areas (Power4 and later). For more information about this feature and how it affects the SDK, see AIX Stack Execution Disable.

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

### Disabling the JIT

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

Turning off the JIT is a temporary measure 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

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

- Set the JAVA_COMPILER environment variable to `jitc` before running the Java application. At 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 shell prompt, enter:

      unset JAVA_COMPILER

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

      java -Xjit <class>

### Determining whether the JIT is enabled

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

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

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

## Specifying garbage collection policy

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

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

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

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

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

### Garbage collection options

The -Xgcpolicy options control the behavior of the Garbage Collector. They make trade-offs between throughput of the application and overall system, and the pause times that are caused by garbage collection.

The format of the option and its values is:

-Xgcpolicy:optthruput
  (Default and recommended value.) Delivers very high throughput to applications, but at the cost of occasional pauses.
-Xgcpolicy: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
  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.

### Pause time

When an application's attempt to create an object cannot be satisfied immediately from the available space in the heap, the Garbage Collector is responsible for identifying unreferenced objects (garbage), deleting them, and returning the heap to a state in which the immediate and subsequent allocation requests can be satisfied quickly.

Such garbage collection cycles introduce occasional unexpected pauses in the execution of application code. Because applications grow in size and complexity, and heaps become correspondingly larger, this garbage collection pause time tends to grow in size and significance.

The default garbage collection value, -Xgcpolicy:optthruput, delivers very high throughput to applications, but at the cost of these occasional pauses, which can vary from a few milliseconds to many seconds, depending on the size of the heap and the quantity of garbage.

The subpool option of -Xgcpolicy provides additional throughput optimization for large SMP systems (24- to 64-way).

### Pause time reduction

The JVM uses two techniques to reduce pause times: concurrent garbage collection and generational garbage collection.

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

During concurrent garbage collection, a significant amount of time is wasted identifying relatively long-lasting objects that cannot then be collected. If garbage collection concentrates on only the objects that are most likely to be recyclable, you can further reduce pause times for some applications. Generational GC reduces pause times by dividing the heap into two generations: the "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 Java heap becomes nearly full, and very little garbage can be reclaimed, requests for new objects might not be satisfied quickly because no space is immediately available.

If the heap is operated at near-full capacity, application performance might suffer regardless of which garbage collection options are used; and, if requests for more heap space continue to be made, the application might receive an OutOfMemoryError, which results in JVM termination if the exception is not caught and handled. At this point, the JVM produces a Javadump file for use during diagnostics. In these conditions, you are recommended either to increase the heap size by using the -Xmx option or to reduce the number of objects in use.

For more information, see the Diagnostics Guide.

## Dynamic Logical Partitioning (DLPAR) support

System resources, for instance memory and CPUs, can be dynamically added to or removed from a logical partition (LPAR) running AIX. Java applications can take advantage of any new resources. Java applications can also respond to DLPAR events using extensions to the java.lang.management API.

If you run Java applications on a single CPU LPAR and never dynamically add a CPU to that LPAR while those Java applications are running, you can improve the performance (results vary depending on the execution characteristics of your application) by exporting the following environment variable: `export NO_LPAR_RECONFIGURATION=1`. Do not export this environment variable unless you can guarantee all of the following:

- You are running in an LPAR
- The LPAR has 1 CPU
- The LPAR will never be dynamically reconfigured to add more CPUs while Java applications are running.

Resource changes are effective immediately, so AIX does not have to be rebooted. If an administrator decreases the number of CPUs or memory allocated to an LPAR, the performance of any running SDK application might degrade.

For more information, see http://www.ibm.com/servers/eserver/pseries/hardware/whitepapers/dlpar.html and the article: Dynamic reconfiguration: Basic building blocks for autonomic computing on IBM pSeries(R) servers in the following IBM Systems Journal issue: http://www.research.ibm.com/journal/sj42-1.html.

To enable applications to respond to DLPAR events, the Java v6 SDK includes IBM-specific extensions to java.lang.management that provide a Java interface to query various LPAR-specific information and listen for events indicating that the JVM's logical partition has been dynamically altered. The Javadoc for this API is provided with the SDK in the docs/content/apidoc directory.

The launcher option, -Xsoftmx, is also available with the Java 6 SDK. The -Xmx option specifies the maximum size (hard limit) of the Java heap. The -Xsoftmx option specifies a lower initial maximum heap size (a "soft" limit). You can change the value of -Xsoftmx at runtime using the java.lang.management API. The valid range of values is between the minimum heap size (-Xms) and the hard limit (-Xmx).

For example, if the JVM is running in an LPAR with 2 GB of memory available for the heap, but the amount of memory might be changed to as low as 1 GB or as high as 8 GB during the run, a suitable set of command-line options would be:

    -Xms1g -Xsoftmx2g -Xmx8g

The value of -Xms must be less than or equal the value of -Xsoftmx. If unspecified, -Xsoftmx defaults to the value of -Xmx.

| | |

## Live application mobility on AIX WPAR

|
|

IBM AIX Workload |Partitions (WPARs) are software-created, virtualized operating system environments |within a single instance of the AIX operating system. To most applications, |the workload partition appears to be a separate instance of AIX. Applications |within workload partitions have a private execution environment.

|

Applications within workload partitions are isolated in terms of process |and signal, and can be isolated in file system space. Workload partitions |can have their own unique users and groups. Workload partitions have dedicated |network addresses and interprocess communication (IPC) is restricted to processes |running in the same workload partition.

|

There are two forms of workload partitions: |

|

|
System WPAR
|
  A System WPAR presents an environment similar to a stand-alone AIX system. A |System WPAR runs most of the system services that would be found in a stand-alone |system and does not share writable file systems with any other WPAR or the |global system. |
|
Application WPAR
|
  An Application WPAR has all the process isolation that a System WPAR provides, |except that it shares file system name space with the global system and any |other Application WPAR defined within the system. Other than the application |itself, a typical Application WPAR runs an additional light-weight init process |within the WPAR. |
|

|

Either WPAR type can be configured for mobility, which allows you to move |running WPAR instances between physical systems using the AIX Workload Manager.

|

From Version 6 Service Refresh 1, the IBM SDK for Java supports WPAR mobility. The IBM SDK for Java can |also respond to WPAR mobility events and make use of system environment changes |in the same way as when a DLPAR is reconfigured. See Dynamic Logical Partitioning (DLPAR) support for |more information.

|

For more information about WPAR, see http://www.ibm.com/servers/eserver/pseries/hardware/whitepapers/dlpar.html.

## Using the IPv6 extensions

The IBM 32-bit SDK for AIX, v6 uses the IPv6 extensions to the TCP/IP protocol by default.

If you do not want to use IPv6 protocols, you can set the property java.net.preferIPv4Stack to force the use of IPv4 protocols.

## Enhanced BiDirectional support

The IBM SDK includes enhanced BiDirectional support.

For more information, see http://www.ibm.com/developerworks/java/jdk/additional/JAVABIDI.html.

The Javadoc for the BiDirectional package is provided with the SDK in the docs/content/apidoc directory.

## Euro symbol support

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

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

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

## Using Indian and Thai input methods

From Version 6, the Indian and Thai input methods are not available by default. You must manually include the input method jar files in your Java extensions path to use the Indian and Thai input methods.

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. Use one of the following 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=/usr/java6/jre/lib/ext:/usr/java6/jre/lib/im <class>

If you installed the SDK or Runtime Environment in a different directory, replace /usr/java6/ with the directory in which you installed the SDK or Runtime Environment.

## Scaling support

To increase the maximum number of threads your system can support, lower the maximum native stack size using the -Xss<size> option.

The default native stack size is 512 KB. A smaller setting allows for a larger number of threads. For example:

    java -Xss<size> <other params>

To increase the maximum number of file descriptors your system can support, use the ulimit or chuser commands, for example:

    ulimit -n 3000

or

    chuser nofiles=3000 <user_id>

Use `ulimit -a` to show the current limit.

## SDK use of AIX large program support

The memory space available to a 32-bit program is broken up by AIX into 16 segments of 256 MB each. The AIX memory model being used by a program determines how those segments can be used by the program. In particular, the memory model determines how many segments are available to the native heap and how many segments are available for other purposes.

The AIX memory model is controlled by the LDR_CNTRL=MAXDATA environment variable. For more details on the AIX memory models, see the "Large Program Support" section of the AIX 5.2 "General Programming Concepts: Writing and Debugging Programs" manual available at:

http://publib16.boulder.ibm.com/pseries/en_US/aixprggd/genprogc/genprogctfrm.htm

The document linked above provides information about using the address-space models to accommodate programs requiring data areas that are larger than conventional segmentation can handle. The SDK uses AIX's large program support by automatically setting the LDR_CNTRL=MAXDATA environment variable as appropriate for allocating the Java heap.

The SDK needs space in both the native heap (for non-object allocations such as for thread stacks or JIT buffers), and space that can be used for the Java heap. In almost all instances, the automatic settings of LDR_CNTRL=MAXDATA will be adequate. In certain instances a user might want to override the automatic settings and manually use an explicit LDR_CNTRL=MAXDATA setting. If an explicit setting is used, the SDK does not attempt to change it. Suboptimal settings for a particular Java application can result in out of memory errors when you run the application, and would normally indicate that you should change the automatic or manual setting in use.

### Automatic LDR_CNTRL=MAXDATA values

The automatic setting of the LDR_CNTRL=MAXDATA environment variable value is linked to the size of the Java heap used by the SDK. To simplify the setting of LDR_CNTRL=MAXDATA, the SDK sets an appropriate value that is based on the maximum size of the heap.

If LDR_CNTRL=MAXDATA is set before you start the SDK, the SDK uses the specified value. Otherwise, the SDK uses the following algorithm to set LDR_CNTRL=MAXDATA:

- If the heap size is greater than 3 GB, LDR_CNTRL=MAXDATA=0@DSA is set.
- If the heap size is greater than 2.25 GB but no more than 3 GB, LDR_CNTR=MAXDATA=0XB0000000@DSA is set.
- Otherwise, LDR_CNTR=MAXDATA=0XA0000000@DSA is set.

Here is a picture of the memory layout with MAXDATA=0xA0000000@DSA, used for Java heaps up to 2.25 GB:

Table 1. The default Java virtual memory model
Segment | Contents
--- | ---
0 | AIX kernel
1 | Java program
2 | Primordial Stack (main program thread stack)
3 | Native Heap (malloc'ed space)
4-C | Native Heap (malloc'ed space) or Memory Mapped space (mmap/shmat)
D | Shared library code
E | Memory Mapped space (mmap/shmat)
F | Shared library data

Segments 0 and 1 have a fixed usage; segment 0 is always used for the AIX kernel and segment 1 is always used for the application program code. In this case, the application program code is generally the java executable.

The setting of MAXDATA=0xA0000000@DSA has determined the usage of the other segments as follows:

- Segment 2 is used for the stack of the application program.
- Segment 3 to segment C are available to the native heap, although initially only segment 3 is reserved for the native heap. Because the JVM and JIT allocate space from the native heap, it can expand to consume additional contiguous segments.
- The Java heap is allocated in contiguous space in segment E, or from segment C and lower segments. That is, a Java heap of 256 MB or smaller uses just segment E. A Java heap of more than 256 MB uses segments C, B, ... as necessary, up to a maximum size of 2.25 GB using all of C-4. At the maximum size of 2.25 GB, the native heap can not grow beyond segment 3.
- Segment D has been allocated by the operating system for shared library code, segment F is used for shared library data. The JVM and JIT are mostly contained in shared libraries which are loaded into these segments.

The Java heap is actually allocated by the JVM using the AIX mmap or shmget/shmat functions. The mmap function is used when the Java heap is allocated in normal 4 KB pages, shmget/shmat is used when the -Xlp option specifies that large pages are to be used.

It is clear from this memory layout that some Java applications can have problems when using large Java heaps. If a Java heap of 2.25 GB is used, the native heap is restricted to a single 256 MB segment. If the Java application created many threads, for example, it might consume a large fraction of the native heap for thread stacks, which can make the JVM or JIT run out of native heap space. Such a situation would require more careful consideration of what size of Java heap should be used, and might motivate the use of an explicit MAXDATA setting.

For a Java heap larger than 2.25 GB, a different MAXDATA setting is needed to free up additional segments for a contiguous area big enough for the heap. With the MAXDATA=0xB0000000@DSA automatic setting, the memory layout changes to:

Table 2. Memory model with MAXDATA=0xB0000000@DSA
Segment | Contents
--- | ---
0 | AIX Kernel
1 | Java program
2 | Primordial stack (main program thread stack)
3 | Native Heap (malloc'ed space)
4-D | Native Heap (malloc'ed space) or Memory Mapped space (mmap/shmat)
E-F | Memory Mapped space (mmap/shmat)

Segments 0 and 1 are fixed in their usage. The setting of MAXDATA=0xB0000000@DSA has determined the usage of the other segments as follows:

- Segment 2 is used for the stack of the application program.
- Segment 3 to segment D are available to the native heap, although initially only segment 3 is reserved for the native heap. Because the JVM and JIT allocate space from the native heap, it can expand to consume additional contiguous segments. Shared libraries must also be privately loaded into this range of segments because segments D and F are not reserved for shared libraries.
- The Java heap is allocated in contiguous space from segment F and lower segments, up to a maximum size of 3 GB using all of F-4.

Using a maximum sized 3 GB heap places restrictions on the native heap memory available to the JVM and JIT. In this case, there is the additional restriction that the shared libraries must coexist with the native heap.

For a Java heap larger than 3 GB, the only option is to use MAXDATA=0@DSA, resulting in a memory layout as follows:

Table 3. Memory model with MAXDATA=0@DSA
Segment | Contents
--- | ---
0 | AIX kernel
1 | Java program
2 | Native Heap (malloc'ed space) and Primordial Stack (main invocation stack)
3-F | Memory Mapped space (mmap/shmat)

The Java heap in this case consumes all of segments 3 through F, for a maximum size of 3.25 GB. The primordial stack, native heap, and shared libraries are all packed into segment 2. It is doubtful that many Java applications could successfully run in this configuration.

### Manual LDR_CNTRL=MAXDATA values

Use the LDR_CNTRL=MAXDATA environment variable to enable memory layouts that are different from the automatic settings.

One interesting setting is MAXDATA=0:

Table 4. Memory model with MAXDATA=0
Segment | Contents
--- | ---
0 | AIX kernel
1 | Java program
2 | Primordial Stack (main program thread stack) and Native Heap
3-C | Memory Mapped space (mmap/shmat)
D | Shared library code
E | Memory Mapped space (mmap/shmat)
F | Shared library data

The setting of MAXDATA=0 has determined the usage of the segments as follows:

- Segment 2 is used for the stack of the application program, and for the native heap.
- The Java heap is allocated in contiguous space in segment 3 and higher segments. That is, a Java heap of 256 MB or smaller uses just segment 3. A Java heap of more than 256 MB uses segments 3, 4, ... as necessary, up to a maximum size of 2.5 GB using all of 3-C.
- Segment D has been allocated by the operating system for shared library code. Segment F is used for shared library data. The JVM and JIT are mostly contained in shared libraries, which are loaded into these segments.

## AIX Stack Execution Disable

AIX 5300-03 implements Buffer Overflow Protection (BOP) using Stack/heap Execution Disable (SED). SED prevents buffer overflow attacks by not executing code in data areas of memory. AIX system administrators control the way SED is used. Java JIT implementations generate machine code in C heap memory; therefore, Java launchers must be exempt from SED.

You make programs exempt from SED by setting the XCOFF executable file header flag DEP_EXEMPT. All Java launchers have the appropriate bit set to exempt them from the SED feature.

Applications that use their own Java launchers and create JVM instances using JNI must be explicitly patched to exempt them from SED. Use the sedmgr utility and verify the change using the dump or sedmgr utility.

The syntax for using these utilities is:

    sedmgr -c exempt <launcher>
    dump -ov <launcher>

For more details on SED, see http://publib.boulder.ibm.com/infocenter/pseries/index.jsp.

# Using the SDK to develop Java applications

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

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

## Using XML

The IBM SDK contains the XML4J and XL XP-J parsers, the XL TXE-J 1.0 XSLT compiler, and the XSLT4J XSLT interpreter. These tools allow you to parse, validate, transform, and serialize XML documents independently from any given XML processing implementation.

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 /etc/java6/jre/lib/stax.properties.
   - For other factories. The value of the service provider in the file /etc/java6/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

The XL TXE-J compiler has replaced the XSLT4J interpreter as the default XSLT processor. Follow these steps to prepare your application for the new library.

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 of the compilation and optimization overhead.

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 these steps:

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

The XL XP-J and XL TXE-J XML libraries are new for Version 6 of the SDK. This reference information describes the features supported by these libraries.

#### XL XP-J reference information

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.

##### 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: http://java.sun.com/javase/6/docs/api/javax/xml/stream/XMLInputFactory.html.

Table 6.
Property name | Supported?
--- | ---
javax.xml.stream.isValidating | No. The XL XP-J scanner does not support validation.
javax.xml.stream.isNamespaceAware | Yes, supports true and false. For XMLStreamReaders created from DOMSources, namespace processing depends on the methods that were used to create the DOM tree, and this value has no effect.
javax.xml.stream.isCoalescing | Yes
javax.xml.stream.isReplacingEntityReferences | Yes. For XMLStreamReaders created from DOMSources, if entities have already been replaced in the DOM tree, setting this parameter has no effect.
javax.xml.stream.isSupportingExternalEntities | Yes
javax.xml.stream.supportDTD | No. DTDs are always supported. Setting the value to false has no effect.
javax.xml.stream.reporter | Yes
javax.xml.stream.resolver | Yes

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.

Table 7.
Property name | Supported?
--- | ---
javax.xml.stream.entities | Yes
javax.xml.stream.notations | Yes

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.

Table 8.
Property name | Supported?
--- | ---
javax.xml.stream.isRepairingNamespaces | Yes

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.

Table 9.
Property name | Supported?
--- | ---
javax.xml.stream.isRepairingNamespaces | Yes

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

XL TXE-J is an XSLT library containing the XSLT4J 2.7.8 interpreter and a XSLT compiler.

##### Feature comparison table

Table 10. Comparison of the features in the XSLT4J interpreter, the XSLT4J compiler, and the XL TXE-J compiler.
Feature | XSLT4J interpreter (included) | XSLT4J compiler (not included) | XL TXE-J compiler (included)
--- | --- | --- | ---
http://javax.xml.transform.stream.StreamSource/feature feature | Yes | Yes | Yes
http://javax.xml.transform.stream.StreamResult/feature feature | Yes | Yes | Yes
http://javax.xml.transform.dom.DOMSource/feature feature | Yes | Yes | Yes
http://javax.xml.transform.dom.DOMResult/feature feature | Yes | Yes | Yes
http://javax.xml.transform.sax.SAXSource/feature feature | Yes | Yes | Yes
http://javax.xml.transform.sax.SAXResult/feature feature | Yes | Yes | Yes
http://javax.xml.transform.stax.StAXSource/feature feature | Yes | No | Yes
http://javax.xml.transform.stax.StAXResult/feature feature | Yes | No | Yes
http://javax.xml.transform.sax.SAXTransformerFactory/feature feature | Yes | Yes | Yes
http://javax.xml.transform.sax.SAXTransformerFactory/feature/xmlfilter feature | Yes | Yes | Yes
http://javax.xml.XMLConstants/feature/secure-processing feature | Yes | Yes | Yes
http://xml.apache.org/xalan/features/incremental attribute | Yes | No | No
http://xml.apache.org/xalan/features/optimize attribute | Yes | No | No
http://xml.apache.org/xalan/properties/source-location attribute | Yes | No | No
translet-name attribute | N/A | Yes | Yes (with new name)
destination-directory attribute | N/A | Yes | Yes (with new name)
package-name attribute | N/A | Yes | Yes (with new name)
jar-name attribute | N/A | Yes | Yes (with new name)
generate-translet attribute | N/A | Yes | Yes (with new name)
auto-translet attribute | N/A | Yes | Yes (with new name)
use-classpath attribute | N/A | Yes | Yes (with new name)
enable-inlining attribute | No | Yes | No (obsolete in TL TXE-J)
indent-number attribute | No | Yes | Yes (with new name)
debug attribute | No | Yes | Yes (with new name)
Java extensions | Yes | Yes (abbreviated syntax only, xalan:component/xalan:script constructs not supported)
JavaScript extensions | Yes | No | No
Extension elements | Yes | No | No
EXSLT extension functions | Yes | Yes (excluding dynamic) | Yes (excluding dynamic)
redirect extension | Yes | Yes (excluding redirect:open and redirect:close) | Yes
output extension | No | Yes | Yes
nodeset extension | Yes | Yes | Yes
NodeInfo extension functions | Yes | No | No
SQL library extension | Yes | No | No
pipeDocument extension | Yes | No | No
evaluate extension | Yes | No | No
tokenize extension | Yes | No | No
XML 1.1 | Yes | Yes | Yes

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

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

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

- Upgrade to a newer version of the application that implements the latest Java API for XML Programming (JAXP) specification (http://java.sun.com/xml/jaxp/index.html).
- Remove the jaxp.properties file from /etc/java6/jre/lib.
- Uncomment the entries in the jaxp.properties file in /etc/java6/jre/lib.
- Copy the jaxp.properties.sample file to jaxp.properties in /etc/java6/jre/lib. Uncomment the entries in the jaxp.properties file. Create a symbolic link to the jaxp.properties file from the /usr/java6/jre/lib directory.
- 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

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

The SDK includes a Plug-in for the AIX debugger DBX. Although the DBX Plug-in is supplied as part of the SDK, it is not supported. However, IBM will accept bug reports.

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

### Java Debugger (JDB)

The Java Debugger (JDB) is included in the SDK for AIX. The debugger is invoked by the jdb command; it attaches to the JVM using JPDA.

To debug a Java application:

1. Start the JVM with the following options:

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

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

       jdb -attach <port>

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

For more information about JDB options, type:

    jdb -help

For more information about JDB commands:

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

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

1. Start the JVM with the following options:

       java -Xdebug -Xrunjdwp:transport=dt_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

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

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

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

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

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

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

## How the JVM processes signals

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

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

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

For exception and error signals, the JVM either:

- Handles the condition and recovers, or
- Enters a controlled shutdown sequence where it:
  1. Produces dumps, to describe the JVM state at the point of failure
  2. Calls your application's signal handler for that signal
  3. Performs the necessary JVM cleanup

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

1. Calls your application's signal handler for that signal
2. Performs the necessary JVM cleanup

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

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

### Signals used by the JVM

The types of signals are Exceptions, Errors, Interrupts, and Controls.

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

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

Table 11. Signals used by the JVM
Signal Name | Signal type | Description | Disabled by -Xrs
--- | --- | --- | ---
SIGBUS (7) | Exception | Incorrect access to memory (data misalignment) | Yes
SIGSEGV (11) | Exception | Incorrect access to memory (write to inaccessible memory) | Yes
SIGILL (4) | Exception | Illegal instruction (attempt to invoke an unknown machine instruction) | Yes
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 | By default, this triggers a Javadump. | Yes
No Name (40) | Control | An AIX reserved signal. Used by the AIX JVM for internal control purposes. | Yes
SIGRECONFIG (58) | Control | Reserved to detect any change in the number of CPUs, processing capacity, or physical memory. | Yes
SIGTRAP (5) | Control | Used by the JIT. | Yes
SIGMAX - 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.

Do not use the -qflttrap C compiler setting because it provides the possibility of SIGTRAPs being generated, which might then impact the JIT. If you want to have floating point exceptions generated, include this call in your code so that it generates a SIGFPE signal:

    fp_trap( FP_TRAP_SYNC)

If you install a signal handler for signal numbers 5 (SIGTRAP) or 58 (SIGRECONFIG), you impact JVM performance because these signals are used for internal control purposes.

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

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

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

The libjsig.a 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_RESTART - This is always set.

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

The environment variable JAVA_HOME should be set to the location of the SDK, for example,/usr/java6/.

To use libjsig.a:

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

      cc_r  <other compile/link parameter> -L/usr/java6/jre/bin -ljsig
      -L/usr/java6/jre/bin/j9vm -ljvm java_application.c

  Note: Use `xlc_r` or `xlC_r` in place of `cc_r` if that is how you normally invoke the compiler or linker.

## Writing JNI applications

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

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

This version number determines only the level of the JNI native interface to use. The actual level of the JVM that is created is specified by the JSE libraries (that is, v6). The JNI interface API does not affect the language specification that is implemented by the JVM, the class library APIs, or any other area of JVM behavior. For more information, see http://java.sun.com/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.

### JNI compatibility

There is a README file and example programs in the /usr/java6/demo/jni directory. The demos can be optionally installed with the Java6.samples package.

If you are writing a C or C++ program that uses the JNI Invocation API (that is, the program creates a Java Virtual Machine and calls Java code), you might want to ensure that the following variables are set to the values specified below. By default, all the Java launchers that are shipped with the SDK (for example, java, jar) set up these environment variables to the values that are specified below.

- `export AIXTHREAD_SCOPE=S`
- `export AIXTHREAD_MUTEX_DEBUG=OFF`
- `export AIXTHREAD_RWLOCK_DEBUG=OFF`
- `export AIXTHREAD_COND_DEBUG=OFF`

When you build a C or C++ program that uses the invocation API, your LIBPATH must include the directories containing the JVM's shared libraries, /usr/java6/jre/lib/ppc/ and /usr/java6/jre/lib/ppc/j9vm, as well as the directories that contain the application's shared libraries.

You must build:

- 32-bit executables and shared objects with the -qarch=ppc option
- JNI executables and shared objects as a 32-bit executable or shared object

The SDK does not support runtime linking (using the -brtl loader option). Any applications that are built for use with the SDK must not rely on runtime linking functionality.

You are recommended to compile your native methods (C or C++ functions called by Java) into AIX shared objects (dynamically loaded libraries). For example, if your native methods are stored in the file nm.c, you could create the shared object with the following command:

    cc_r -qmkshrobj -qarch=ppc  -I /usr/java6/include -o libnm.a nm.c

The `-qmkshrobj` option disables runtime linking. For more details about shared object files, runtime linking, and the use of `cc` and `ld` command-line options, see:

- Developing and Porting C and C++ Applications on AIX at http://www.redbooks.ibm.com/abstracts/sg245674.html
- The C and C++ compiler documentation Web site at http://www.ibm.com/software/awdtools/xlcpp/library
- The AIX online documentation at http://www16.boulder.ibm.com/pseries/en_US/infocenter/base/aix.htm

Before running a Java program that uses native methods, ensure that LIBPATH contains the list of directories that are holding the native methods' shared objects. For more information about building AIX shared objects, see C and C++ Application Development on AIX. Go to http://www.ibm.com/redbooks and search for "SG245674".

If you set the setuid or setgid attribute on JNI native code programs, that setting changes the effective LIBPATH environment variable. This change might cause unexpected or incorrect behavior with those programs. For more details about this usage, see Developing and Porting C and C++ Applications on AIX at http://www.redbooks.ibm.com/abstracts/sg245674.html, section 2.3.3.

When building a C or C++ program that uses the JNI Invocation API to create a Java virtual machine and calls Java code, use the:

- -L option to add /usr/lib and /lib to the list of directories that are searched for shared objects. All programs need shared objects stored in these directories.
- -L option to add /usr/java6/jre/lib/ppc/ and /usr/java6/jre/lib/ppc/j9vm to the list of directories that are searched for shared objects. These directories contain the Java SDK shared libraries. You will also want to link with libjvm.so (using the -ljvm option).

For example, this command builds a C program (invAPITest.c) that uses the JNI Invocation API:

    cc_r -qarch=ppc  -I/usr/java6/include
    -o invAPITest
    -L/usr/lib
    -L/lib
    -L/usr/java6/jre/lib/ppc/j9vm
    -L/usr/java6/jre/lib/ppc/
    -ljvm invAPITest.c

When executing a C or C++ program that uses the JNI Invocation API to run Java classes, ensure that the class path is set up correctly to enable the Java Virtual Machine (JVM) to find your class files. If you modify Java's boot class path, include the SDK files that are necessary to run your applications.

To determine whether a C or C++ program that is using the JNI Invocation API was built with the -bM:UR option, use the command:

    >dump -ov <program name>
                            ***Object Module Header***
    # Sections    Symbol Ptr    # Symbols     Opt Hdr Len   Flags
             4    0x00000d4e          155              72   0x1002
    Flags=( EXEC DYNLOAD )
    Timestamp = "Sep 11 13:09:13 2002"
    Magic = 0x1df  (32-bit XCOFF)
                            ***Optional Header***
    Tsize        Dsize       Bsize       Tstart      Dstart
    0x000004b8  0x000001a8  0x00000004  0x10000128  0x200005e0

    SNloader     SNentry     SNtext      SNtoc       SNdata
    0x0004      0x0002      0x0001      0x0002      0x0002

    TXTalign     DATAalign   TOC         vstamp      entry
    0x0002      0x0003      0x20000724  0x0001      0x20000704

    maxSTACK     maxDATA     SNbss       magic       modtype
    0x00000000  0x00000000  0x0003      0x010b        UR

If the modtype is not UR, you can use the LDR_CNTRL environment variable to make programs behave as though they were compiled with the `-bM:UR` binder option. For example:

    export LDR_CNTRL=USERREGS

If you need to specify multiple options with LDR_CNTRL, separate those options with the "@" symbol.

Java threads that are created by the SDK use the POSIX pthreads model that is supported on AIX. Currently, this is on a 1-to-1 mapping with the kernel threads. When developing a JNI program, you must run with a 1-to-1 thread model and system contention scope if creating pthreads in your own program. You can control this by using the following environment setting:

    export AIXTHREAD_SCOPE=S

Another option is to preset the thread's scope attribute to PTHREAD_SCOPE_SYSTEM using the AIX pthread_attr_setscope function when the thread is created. For more details on thread model and system contention scope, see:

http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixprggd/genprogc/understanding_threads.htm#D3A446E559manu

http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixprggd/genprogc/threads_sched.htm#D3A44A4324manu

From Java V5.0, you can store native methods in these ways:

Shared object
  A shared object is a single object file that has the SRE (Shared REusable) bit set in the XCOFF header. The SRE bit tells the linker that this file is linked dynamically. These files normally have a name of the form <filename>.o, but they can also be named lib<name>.a to allow the linker to search for them with the -lname option; but these are not archive library files.
Shared library
  A shared library is an "ar" format archive library in which one or more of the archive members is a shared object. Note that this library can also contain non-shared object files that are statically linked. A shared library has the name in the form lib<name>.a. This form allows the linker to search for libraries with the -lname option.

Programs can also link dynamically to AIX shared libraries and shared objects using the dlopen() family of subroutines. The SDK links in this way when it loads native libraries (for example, System.load(), System.loadLibrary(), Runtime.getRuntime().load(), Runtime.getRuntime().loadLibrary()).

For information about dlopen, see:

http://publib.boulder.ibm.com/infocenter/pseries/index.jsp?topic=/com.ibm.aix.doc/libs/basetrf1/dlopen.htm

For information about AIX loading and linking mechanisms, see: http://download.boulder.ibm.com/ibmdl/pub/software/dw/aix/es-aix_ll.pdf

To load an AIX shared library, make a call to:

    System.loadLibrary("<library>(<member>)")

where <library> is the name of the shared library archive and <member> is the name of an archive member. For example:

    System.loadLibrary("libShared.a(libSample.o)")

### Example of using AIX shared libraries

This example takes you through the process of using native shared libraries with a Java application on AIX.

1. Create a sample application, Sample.java.

       public class Sample
       {
          public native void printFromNative( );

          public static void main( String[] args )
          {
             Sample sample = new Sample( );
             sample.printFromNative( );
          }

          static
          {
             String sharedLibrary = "libShared.a(libSample.o)";
             try
             {
                System.loadLibrary( sharedLibrary );
             }
             catch ( Exception e )
             {
                System.out.println( "ERROR: Unable to load " + sharedLibrary );
                e.printStackTrace( );
             }
          }
       }

2. Compile Sample.java.

       javac Sample.java

3. Use javah to create a header file for the native code.

       javah Sample

4. Create a file called Sample.c.

       #include <stdio.h>
       #include "Sample.h"

       JNIEXPORT void JNICALL Java_Sample_printFromNative( JNIEnv * env, jobject obj )
       {
          printf( "Printing from native\n" );
       }

5. Compile Sample.c into libSample.o.

       cc_r -bM:SRE -bnoentry -bexpall -I/usr/java6/include Sample.c -o libSample.o

6. Create an archive shared library libShared.a.

       ar -X32 -v -q libShared.a libSample.o

7. Run the Sample class.

       LIBPATH=. java Sample

   The program will output:

   `Printing from native`

You should now be able to use the same framework to access native shared libraries from Java applications.

## Support for thread-level recovery of blocked connectors

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

These classes allow you to unblock threads that have become blocked on networking or 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 for these classes is provided with the SDK in the docs/content/apidoc directory.

## CORBA support

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

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 need to register a service in the current version must invoke this method on the IBM internal ORB implementation class. For example, to register a service "MyService":

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

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

### System properties for tracing the ORB

A runtime debug feature provides improved serviceability. You might find it useful for problem diagnosis or it might be requested by IBM service personnel.

#### Tracing Properties

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

#### Example of ORB tracing

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

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

#### Limitations

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

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

### System properties for tuning the ORB

The ORB can be tuned to work well with your specific network. The properties required to tune the ORB are described here.

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

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

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

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

### Java security permissions for the ORB

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

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

### ORB implementation classes

A list of the ORB implementation classes.

The ORB implementation classes in this release are:

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

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

## RMI over IIOP

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

The following documentation is available:

- The RMI-IIOP Programmer's Guide is an introduction to writing RMI-IIOP programs.
- The 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

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

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

    -Dsun.rmi.transport.tcp.connectionPool=true

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

## Enhanced BigDecimal

From Java 5.0, the IBM BigDecimal class has been adopted by Sun as java.math.BigDecimal. The com.ibm.math.BigDecimal class is reserved for possible future use by IBM and is currently deprecated. Migrate existing Java code to use java.math.BigDecimal.

The new java.math.BigDecimal uses the same methods as both the previous java.math.BigDecimal and com.ibm.math.BigDecimal. Existing code using java.math.BigDecimal continues to work correctly. The two classes do not serialize.

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

## AIX native threads

From AIX 5.3 onwards, programs can set the priority of system contention scope threads. Calls to java.lang.Thread.setPriority() will change the priority of Java threads running on AIX 5.3.

For more information about AIX dynamic thread scheduling, see:

http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixprggd/genprogc/threads_sched.htm

For more information about AIX 5.3 thread scheduling, see:

http://publib.boulder.ibm.com/infocenter/pseries/index.jsp?topic=/com.ibm.aix.doc/libs/basetrf1/pthread_setschedparam.htm and http://publib.boulder.ibm.com/infocenter/pseries/index.jsp?topic=/com.ibm.aix.doc/aixprggd/genprogc/threads_sched.htm.

## JNDI

The IBM 32-bit SDK for AIX, v6 provides a unified interface, the Java Naming and Directory Interface (JNDI), to the naming and directory services.

These naming and directory services are supported by JNDI:

- Lightweight Directory Access Protocol (LDAP)
- Corba Object Services (COS) Naming Service
- RMI Registry
- File system
- Domain Name Service (DNS)

## HPROF Performance Profiler and JVMPI

The Java Virtual Machine Profiling Interface (JVMPI) has been extended to include profiling in the IBM JIT. These additional definitions are listed in jvmpi.h.

### GetCurrentThreadCpuTime

To enable the JVMPI function GetCurrentThreadCPUTime, you must enable AIX resource collection by setting the environment variable AIXTHREAD_ENRUSG.

When the resource collection is enabled, the HPROF profiling agent, invoked with -Xrunhprof:cpu=times provides meaningful data in the HPROF output.

Type the following command at the shell prompt:

    export AIXTHREAD_ENRUSG=ON

You will get the following message when performance profiling is switched on:

    Warning: Performance profiling is enabled and can cause
    performance degradation.
    Warning: You can unset AIXTHREAD_ENRUSG to disable
    performance profiling.

Make sure that the resource collection is disabled after your profiling session because the overhead for tracking CPU time for individual threads affects performance. Resource collection should never be enabled in a production environment. To disable the resource collection, do one of the following:

    unset AIXTHREAD_ENRUSG
    export AIXTHREAD_ENRUSG=OFF

By default, resource collection is disabled.

### Known restriction

The JVMPI_EVENT_INSTRUCTION_START event is not currently supported in the IBM 32-bit SDK for AIX, v6. It might be added in a future release.

## Support for XToolkit

The IBM 32-bit SDK for AIX, v6 includes XToolkit by default. You need XToolkit when using the Eclipse's SWT_AWT bridge to build an application that uses both SWT and Swing.

Restriction: Motif is no longer supported and will be removed in a later release.

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

# Plug-in, Applet Viewer and Web Start

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

## Using the Java plug-in

The Java plug-in is a Web browser plug-in. You use the Java plug-in to run applets in the browser.

You must allow applets to finish loading to prevent your browser from 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

The Java plug-in supports Mozilla.

Table 13. Browsers supported by the Java plug-in
Browser | Supported Versions
--- | ---
Mozilla | 1.7.13 Available at http://www.ibm.com/servers/aix/browsers/ and the Mozilla for AIX CD.

### Installing the Java plug-in

To install the Java plug-in, symbolically link it to the plug-in directory for your browser.

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 it can locate the JVM.

#### Mozilla

Symbolically link the Java plug-in to the plug-ins directory for the Mozilla Web browser. Use the "about" information in Mozilla to verify the Java plug-in is correctly installed.

The Mozilla for AIX Web browser is available from:

- The Mozilla for AIX CD, which you can order as part of AIX, or
- The AIX browser download Web site http://www.ibm.com/servers/aix/browsers.

To install the plug-in on Mozilla:

1. Log in as root.
2. Change to your Mozilla plug-ins directory.
   - To make the plug-in available to all users:

          cd /usr/mozilla/base/plugins/

   - To make the plug-in available to the current user only:

         cd $HOME/.mozilla/plugins

3. Create a symbolic link to the plug-in.

        ln -s /usr/java6/jre/plugin/ppc/ns7/libjavaplugin_oji.so .

To verify that the Java plug-in is available and enabled, select Help -> About plug-ins in Mozilla.

This Java plug-in supports Mozilla 1.7.13 and backward-compatible newer versions shipped as an option of the AIX operating system, although some compatibility problems exist. To work around some of the incompatibilities, add /usr/java6/jre/lib/ppc/ and /usr/java6/jre/lib/ppc/j9vm to your LIBPATH environment variable.

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

Restriction: You can have only one Java plug-in shared library in /usr/mozilla/base/plugins/. Mozilla attempts to load anything that is in that directory, (or subdirectories underneath it), as a plug-in, and results are unpredictable if two versions of the Java plug-in are loaded.

### Changing the properties of the Java Plug-in

You can change the properties of the Java Plug-in from the control panel, which can be run as a standalone Java application.

To launch this Java application, run the script:

    /usr/java6/jre/bin/ControlPanel

### Java Plug-in HTML converter

Information about the Java Plug-in HTML converter, HtmlConverter.

#### Purpose

The Java Plug-in HTML converter allows you to convert any HTML page that contains applets to a format that will use the Java Plug-in.

#### Location

The tool is in the /usr/java6/bin directory with a jar file in the /usr/java6/lib directory.

#### Usage

For more information about the Java Plug-in HTML Converter, see the Sun Web site: http://java.sun.com/javase/6/docs/technotes/guides/plugin/developer_guide/html_converter.html.

### Common Document Object Model (DOM) support

Because of limitations in particular browsers, you might not be able to implement all the functions of the org.w3c.dom.html package.

One of the following errors is thrown:

- sun.plugin.dom.exception.InvalidStateException
- sun.plugin.dom.exception.NotSupportedException

### Using DBCS parameters

The Java plug-in supports double-byte characters (for example, Chinese Traditional BIG-5, Korean, and Japanese) as parameters for the tags <APPLET>, <OBJECT>, and <EMBED>. You must select the correct character encoding for your HTML document so that the Java plug-in can parse the parameter.

Specify character encoding for your HTML document by using the `<META>` tag in the `<HEAD>` section like this:

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

This example tells the browser to use the Chinese BIG-5 character encoding to parse the HTML file.

## Working with applets

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

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

### Running and debugging applets with the Applet Viewer

Use the following commands to run and debug an applet with the Applet Viewer.

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

      appletviewer $HOME/<filename>.html

Where filename is the name of the HTML file.

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

### Java Applet Viewer and the classpath

If you use the Applet Viewer to run an applet that is in the CLASSPATH, you might get an AccessControlException in Swing. Because the CLASSPATH implicitly contains the current directory ".", this exception might occur if you run the Java Plug-in in the same directory that the applet class itself is in.

To work around this problem, ensure that:

- No CLASSPATH references exist to the applet that you are attempting to run in the Java Plug-in or the appletviewer.
- You are not running the applet from the same directory that the class is in.

## Using Web Start

Java Web Start is used for Java application deployment.

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

Web Start supports these java-vm-args documented at http://java.sun.com/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 information about the browsers that support Web Start, see Supported browsers.

For more information about Web Start, see:

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

- http://java.sun.com/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

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

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

- Select a link on a Web page that refers to a .jnlp file.
- At a 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:

      /usr/java6/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.

### WebStart Secure Static Versioning

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

With SSV, the user 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 normal.

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

## Distributing Java applications

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

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

- Your own class, resource, and data files
- AIX Runtime Environment (optional)
- An installation procedure or program

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

Your application can either make the SDK for AIX a prerequisite or include a version of the SDK that is specifically for the purpose of redistribution. The SDK for AIX license does not allow you to redistribute any of the SDK files installed in /usr/java6/ by installp. You can redistribute the SDK files in the j632redist.tar or j632redist.tar.gz file (after viewing and agreeing to the associated online license) available from the AIX Java Web site: http://www.ibm.com/developerworks/java/jdk/aix. Click on the Download and service information link near the bottom of the page and follow the links to the Java download page.

# Class data sharing between JVMs

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

The Java Virtual Machine (JVM) allows you to share class data between JVMs by storing it in a memory-mapped cache file on disk. Sharing reduces the overall virtual memory consumption when more than one JVM shares a cache. Sharing also reduces the startup time for a JVM after the cache has been created. The shared class cache is independent of any active JVM and persists 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

Class data sharing provides a transparent method of reducing memory footprint and improving JVM start-up time. Java 6 provides new and improved features in cache management, isolation, and performance.

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

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

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

-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 directory must not be on an NFS mount for persistent caches.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
    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. |You must always use |the persistent suboption when running utilities such |as destroy on a persistent cache. |You must set the CORE_MMAP environment |variable to `yes` when using a persistent |cache.
  nonpersistent (default)
    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.
  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 normal to see many failed requests; this behavior is expected for the classloader hierarchy.
  verboseHelper
    Enables verbose output for the Java Helper API. This output shows you how the Helper API is used by your ClassLoader.
  silent
    Turns off all shared classes messages, including error messages. Unrecoverable error messages, which prevent the JVM from initializing, 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

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

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

The JVM 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 impact 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

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

The overhead to create and populate a new cache is minimal. The JVM startup cost in time for a single JVM is typically between 0 and 5% slower compared with a system not using class data sharing, depending on how many classes are loaded. JVM startup time improvement with a populated cache is typically between 10% and 40% faster compared with a system not using class data sharing, depending on the operating system and the number of classes loaded. Multiple JVMs running concurrently 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 memory consumption.

## Considerations and limitations of using class data sharing

Consider these factors when deploying class data sharing in a product and using class data sharing in a development environment.

### Cache size limits

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

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

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.

The virtual address space available to the process is 3.25 GB, depending on your system configuration. See SDK use of AIX large program support.

### Runtime bytecode modification

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

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

This partitioning allows JVMs that are not using modified bytecode to safely share a cache with those that are using modified bytecode. All JVMs using a given modified context must modify bytecode in a predictable, repeatable manner for each class, so that the modified classes stored in the cache have the expected modifications when they are loaded by another JVM. Any modification must be predictable because classes loaded from the shared class cache cannot be modified again by the agent.

If a JVMTI agent is used without a modification context, classes are still safely shared by the JVM, but with a small impact on performance. Using a modification context with a JVMTI agent avoids the need for extra checks and therefore has no impact on performance. A custom ClassLoader that extends java.net.URLClassLoader and modifies bytecode at load time without using JVMTI automatically stores that modified bytecode in the cache, but the cache does not treat the bytecode as modified. Any other VM sharing that cache loads the modified classes. 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

You cannot share classes between 32-bit and 64-bit JVMs. Temporary disk space must be available to hold cache information. The operating system enforces cache permissions.

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

If a SecurityManager is being used with class data sharing and the running application uses its own class loaders, you must grant these class loaders shared class permissions before they can share classes.

You add shared class permissions to the java.policy file using the ClassLoader class name (wildcards are permitted) and either "read", "write", or "read,write" to determine the access granted. For example:

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

If a ClassLoader does not have the correct permissions, it is prevented from sharing classes. You cannot change the permissions of the default bootstrap, application, or extension class loaders.

## Adapting custom classloaders to share classes

Any classloader that extends java.net.URLClassLoader can share classes without modification. You must adopt classloaders that do not extend java.net.URLClassLoader to share class data.

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

# Service and support for independent software vendors

Contact points for service:

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

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

# Accessibility

The user guides that are supplied with this SDK and the Runtime Environment have been tested using screen readers.

To change the font sizes in the user guides, use the function that is supplied with your browser, typically found under the View menu option.

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

## Keyboard traversal of JComboBox components in Swing

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

## Web Start accessibility

From Version 5.0, Java Web Start contains several accessibility and usability improvements, including better support for screen readers and improved keyboard navigation.

You can use the command line to launch a Java application that is enabled for Web Start. To change preference options, you must edit a configuration file, .java/.deployment/.deployment.properties in the user's home directory. Take a backup before you edit this file. Not all 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?

If you have any comments about this user guide, contact us through one of the following channels. Note that these channels are not set up to answer technical queries, but are for comments about the documentation only.

Send your comments:

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

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

# Appendix A. Nonstandard options

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

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

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

-Xargencoding
  Allows you to put Unicode escape sequences in the argument list. This option is set to off by default.
-Xbootclasspath:<directories and zip or jar files separated by :>
  Sets the search path for bootstrap classes and resources. The default is to search for bootstrap classes and resources within the internal VM directories and .jar files.
-Xbootclasspath/a:<directories and zip or jar files separated by :>
  Appends the specified directories, zip, or jar files to the end of bootstrap class path. The default is to search for bootstrap classes and resources within the internal VM directories and .jar files.
-Xbootclasspath/p:<directories and zip or jar files separated by :>
  Prepends the specified directories, zip, or jar files to the front of the bootstrap class path. Do not deploy applications that use the -Xbootclasspath: or -Xbootclasspath/p: option to override a class in the standard API, because such a deployment would contravene the Java Runtime Environment binary code license. The default is to search for bootstrap classes and resources within the internal VM directories and .jar files.
-Xcheck: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
  Performs additional checks for JNI functions. 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. See the output of -Xcheck:memory:help or the Diagnostics Guide for more information.
-Xcheck:nabounds
  Performs additional checks for JNI functions. By default, no checking is performed.
-Xclassgc
  Enables collection of class objects at every garbage collection. See also -Xnoclassgc. By default, this option is enabled.
-Xcodecache<size>
  Sets the unit size of which memory blocks are allocated to store native code of compiled Java methods. An appropriate size can be chosen for the application being run. By default, this is selected internally according to the CPU architecture and the capability of your system.
-Xcompactexplicitgc
  Performs a compaction for every call to `System.gc()`. See also -Xnocompactexplicitgc. By default, compaction occurs only when triggered internally.
-Xcompactgc
  Performs a compaction for every garbage collection. See also -Xnocompactgc. By default, compaction occurs only when triggered internally.
-Xconcurrentbackground<number>
  Specifies the number of low priority background threads attached to assist the mutator threads in concurrent mark. The default is 1.
-Xconcurrentlevel<number>
  Specifies the allocation "tax" rate. It indicates the ratio between the amount of heap allocated and the amount of heap marked. The default is 8.
-Xconmeter:<soa|loa|dynamic>
  Determines which area's usage, LOA (Large Object Area) or SOA (Small Object Area), is metered and hence which allocations are taxed during concurrent mark. The allocation tax is applied to the selected area. If -Xconmeter:dynamic is specified, the collector dynamically determines the area to meter based on which area is exhausted first. By default, the option is set to -Xconmeter:soa.
-Xdbg:<options>
  Loads debugging libraries to support the remote debugging of applications. See Debugging Java applications for more information. Specifying -Xrunjdwp provides the same support.
-Xdebug
  Starts the JVM with the debugger enabled. By default, the debugger is disabled.
-Xdisableexcessivegc
  Disables the throwing of an OutOfMemoryError if excessive time is spent in the GC. By default, this option is off.
-Xdisableexplicitgc
  Signals to the VM that calls to System.gc() should have no effect. By default, calls to System.gc() trigger a garbage collection.
-Xdisablestringconstantgc
  Prevents strings in the string intern table from being collected. By default, this option is disabled.
-Xdisablejavadump
  Turns off Javadump generation on errors and signals. By default, Javadump generation is enabled.
-Xenableexcessivegc
  If excessive time is spent in the GC, this option returns NULL for an allocate request and thus causes an OutOfMemoryError to be thrown. This action occurs only when the heap has been fully expanded and GC is taking 95% of the available time. This behavior is the default.
-Xenableexplicitgc
  Signals to the VM that calls to System.gc() should trigger a garbage collection. This is the default.
-Xenablestringconstantgc
  Enables strings from the string intern table to be collected. By default, this option is enabled.
-Xfuture
  Turns on strict class-file format checks. Use this flag when you are developing new code because stricter checks will become the default in future releases. By default, strict format checks are disabled.
-Xgcpolicy:<optthruput|optavgpause|gencon|subpool>
  Controls the behavior of the Garbage Collector. See Garbage collection options for more information.
-Xgcthreads<number of threads>
  Sets the number of helper threads that are used for parallel operations during garbage collection. By default, the number of threads is set to the number of physical CPUs present -1, with a minimum of 1.
-Xgcworkpackets<number>
  Specifies the total number of work packets available in the global collector. If not specified, the collector allocates a number of packets based on the maximum heap size.
-Xint
  Makes the JVM use only the Interpreter, disabling the Just-In-Time (JIT) compiler. By default, the JIT compiler is enabled.
-Xiss<size>
  Sets the initial Java thread stack size. 2 KB by default. Use the -verbose:sizes option to output the value that the VM is using.
-Xjarversion
  See Obtaining version information.
-Xjit[:<suboption>,<suboption>...]
  Enables the JIT. For details of the sub-options, see the Diagnostics Guide. See also -Xnojit. By default, the JIT is enabled.
-Xlinenumbers
  Displays line numbers in stack traces, for debugging. See also -Xnolinenumbers. By default, line numbers are on.
-Xloa
  Allocates a large object area (LOA). Objects will be allocated in this LOA rather than the SOA. By default, the LOA is enabled for all GC policies except for subpool, where the LOA is not available. See also -Xnoloa.
-Xloainitial<percentage>
  <percentage> is between 0 and 0.95, which specifies the initial percentage of the current tenure space allocated to the large object area (LOA). The default is 0.05 or 5%.
-Xloamaximum<percentage>
  <percentage> is between 0 and 0.95, which specifies the maximum percentage of the current tenure space allocated to the large object area (LOA). The default is 0.5 or 50%.
-Xlp<size>
  Requests the JVM to allocate the Java heap (the heap from which Java objects are allocated) with 16 MB large pages, if a size is not specified. If large pages are not available, the Java heap is allocated with AIX's standard 4 KB pages. AIX requires special configuration to enable large pages. For more information on configuring AIX support for large pages, see http://www.ibm.com/servers/aix/whitepapers/large_page.html. The SDK uses shmget() with the SHM_LGPG and SHM_PIN flags to allocate large pages. By default, large pages are not used.

  The options available for <size> are:

  - -Xlp4K
  - -Xlp64K
  - -Xlp16M
  - -Xlp16G
-Xmaxe<size>
  Sets the maximum amount by which the garbage collector expands the heap. Typically, the garbage collector expands the heap when the amount of free space falls below 30% (or the amount specified using -Xminf), by the amount required to restore the free space to 30%. The -Xmaxe option limits the expansion to the specified value; for example `-Xmaxe10M` limits the expansion to 10 MB. By default, there is no maximum expansion size.
-Xmaxf<percentage>
  Specifies the maximum percentage of heap that must be free after a garbage collection. If the free space exceeds this amount, the JVM attempts to shrink the heap. The default value is 0.6 (60%).
-Xmca<size>
  Sets the expansion step for the memory allocated to store the RAM portion of loaded classes. Each time more memory is required to store classes in RAM, the allocated memory is increased by this amount. By default, the expansion step is 32 KB. Use the -verbose:sizes option to output the value that the VM is using.
-Xmco<size>
  Sets the expansion step for the memory allocated to store the ROM portion of loaded classes. Each time more memory is required to store classes in ROM, the allocated memory is increased by this amount. By default, the expansion step is 128 KB. Use the -verbose:sizes option to output the value that the VM is using.
-Xmine<size>
  Sets the minimum amount by which the Garbage Collector expands the heap. Typically, the garbage collector expands the heap by the amount required to restore the free space to 30% (or the amount specified using -Xminf). The -Xmine option sets the expansion to be at least the specified value; for example, `-Xmine50M` sets the expansion size to a minimum of 50 MB. By default, the minimum expansion size is 1 MB.
-Xminf<percentage>
  Specifies the minimum percentage of heap that should be free after a garbage collection. If the free space falls below this amount, the JVM attempts to expand the heap. By default, the minimum value is 0.3 (30%).
-Xmn<size>
  Sets the initial and maximum size of the new area to the specified value when using -Xgcpolicy:gencon. Setting -Xmn is equivalent to setting -Xmns and -Xmnx. If you set either -Xmns or -Xmnx, you cannot set -Xmn. If you attempt to set -Xmn with either -Xmns or -Xmnx, the VM will not start, returning an error. By default, -Xmn is selected internally according to your system's capability. Use the -verbose:sizes option to output the value that the VM is using.
-Xmns<size>
  Sets the initial size of the new area to the specified value when using -Xgcpolicy:gencon. By default, this option is selected internally according to your system's capability. This option will return an error if you try to use it with -Xmn. Use the -verbose:sizes option to output the value that the VM is using.
-Xmnx<size>
  Sets the maximum size of the new area to the specified value when using -Xgcpolicy:gencon. By default, this option is selected internally according to your system's capability. This option will return an error if you try to use it with -Xmn. Use the -verbose:sizes option to output the value that the VM is using.
-Xmo<size>
  Sets the initial and maximum size of the old (tenured) heap to the specified value when using -Xgcpolicy:gencon. Equivalent to setting both -Xmos and -Xmox. If you set either -Xmos or -Xmox, you cannot set -Xmo. If you attempt to set -Xmo with either -Xmos or -Xmox, the VM will not start, returning an error. By default, -Xmo is selected internally according to your system's capability. Use the -verbose:sizes option to output the value that the VM is using.
-Xmoi<size>
  Sets the amount the Java heap is incremented when using -Xgcpolicy:gencon. If set to zero, no expansion is allowed. By default, the increment size is calculated on the expansion size, -Xmine and -Xminf.
-Xmos<size>
  Sets the initial size of the old (tenure) heap to the specified value when using -Xgcpolicy:gencon. By default, this option is selected internally according to your system's capability. This option will return an error if you try to use it with -Xmo. Use the -verbose:sizes option to output the value that the VM is using.
-Xmox<size>
  Sets the maximum size of the old (tenure) heap to the specified value when using -Xgcpolicy:gencon. By default, this option is selected internally according to your system's capability. This option will return an error if you try to use it with -Xmo. Use the -verbose:sizes option to output the value that the VM is using.
-Xmr<size>
  Sets the size of the Garbage Collection "remembered set" when using -Xgcpolicy:gencon. This is a list of objects in the old (tenured) heap that have references to objects in the new area heap. By default, this option is set to 16 kilobytes. Use the -verbose:sizes option to output the value that the VM is using.
-Xmrx<size>
  Sets the remembered maximum size setting.
-Xms<size>
  Sets the initial Java heap size. The default is 64 MB. You can also use -Xmo. Use the -verbose:sizes option to output the value that the VM is using.
-Xmso<size>
  Sets the C stack size for forked Java threads. By default, this option is set to 32 KB on 32-bit platforms and 256 KB on 64-bit platforms. Use the -verbose:sizes option to output the value that the VM is using.
-Xmx<size>
  Sets maximum Java heap size. The default is 64 MB. Use the -verbose:sizes option to output the value that the VM is using.
-Xnoclassgc
  Disables class garbage collection. This option switches off garbage collection of storage associated with Java classes that are no longer being used by the JVM. See also -Xclassgc. By default, class garbage collection is performed.
-Xnocompactexplicitgc
  Disables compaction on a call to `System.gc()`. See also -Xcompactexplicitgc. By default, compaction is enabled on calls to `System.gc()`.
-Xnocompactgc
  Disables compaction for the Garbage Collector. See also -Xcompactgc. By default, compaction is enabled.
-Xnojit
  Disables the JIT compiler. See also -Xjit. By default, the JIT compiler is enabled.
-Xnolinenumbers
  Disables the line numbers for debugging. See also -Xlinenumbers. By default, line number are on.
-Xnoloa
  Prevents allocation of a large object area (LOA). All objects will be allocated in the SOA. By default, the LOA is enabled for all GC policies except for subpool, where the LOA is not available. See also -Xloa.
-Xnopartialcompactgc
  Disables incremental compaction. See also -Xpartialcompactgc.
-Xnosigcatch
  Disables JVM signal handling code. See also -Xsigcatch. By default, signal handling is enabled.
-Xnosigchain
  Disables signal handler chaining. See also -Xsigchain. By default, the signal handler chaining is enabled.
-Xoptionsfile=<file>
  Specifies a file that contains JVM options and defines. By default, no option file is used.
-Xoss<size>
  Sets the Java stack size and C stack size for any thread. This option is provided for compatibility and is equivalent to setting both -Xss and -Xmso to the specified value.The default is 400 KB.
-Xpartialcompactgc
  Enables partial compaction. By default, this option is not set, so all compactions are full. See also -Xnopartialcompactgc.
-Xquickstart
  Improves startup time by delaying JIT compilation and optimizations. By default, quickstart is disabled and there is no delay in JIT compilation.
-Xrdbginfo:<host>:<port>
  Loads and passes options to the remote debug information server. By default, the remote debug information server is disabled.
-Xrs
  Reduces the use of operating system signals. By default, the VM makes full use of operating system signals, see Signals used by the JVM.
-Xrun<library name>[:<options>]
  Loads helper libraries. To load multiple libraries, specify it more than once on the command line. Examples of these libraries are:
  -Xrunhprof[:help] | [:<option>=<value>, ...]
    Performs heap, CPU, or monitor profiling. For more information, see the Diagnostics Guide.
  -Xrunjdwp[:help] | [:<option>=< value>, ...]
    Loads debugging libraries to support the remote debugging of applications. See -Xdbg for more information.
  -Xrunjnichk[:help] | [:<option>=<value>, ...]
    Deprecated, use -Xcheck:jni.
-Xscmx<size>
  For details of -Xscmx, see Class data sharing command-line options.
-Xshareclasses:<options>
  For details of the -Xshareclasses options, see Class data sharing command-line options.
-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.
-Xsoftmx<size>
  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 this soft heap size limit between -Xms and -Xmx at runtime. By default, this option is set to the same value as -Xmx.
-Xsoftrefthreshold<number>
  |Sets the hint used by the |GC to determine the number of GCs after which a soft reference will be cleared |if its referent has not been marked. The default is 32, meaning that the soft |reference will be cleared after 32*(percent of free heap space) GC cycles |where its referent was not marked.
-Xss<size>
  Sets the maximum Java stack size for any thread. The default is 512 KB. Use the -verbose:sizes option to output the value that the VM is using.
-Xthr:<options>
  Sets the threading options.
-Xverbosegclog:<path to file>[X,Y]

  Causes verbose garbage collection (GC) output to be written to the specified file. If the file exists, it is overwritten. Otherwise, if an existing file cannot be opened or a new file cannot be created, the output is redirected to stderr. If you specify the arguments X and Y (both are integers) the verbose GC output is redirected to X number of files, each containing Y number of gc cycles worth of verbose GC output. These files have the form filename1, filename2, and so on. By default, no verbose GC logging occurs.

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

-Xverify
  Enables strict class checking for every class that is loaded. By default, strict class checking is disabled.
-Xverify:none
  Disables strict class checking. By default, strict class checking is disabled.

# Appendix B. Known limitations

Known limitations on the SDK and Runtime Environment for AIX.

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

## -verbose with more than one suboption where one suboption is jni

If you specify more than one suboption with -verbose and one of the suboptions is jni, you receive an error message.

An example of this follows:

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

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

## JConsole monitoring tool Local tab

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

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

## 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 within 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 32-bit SDK for AIX, v6 Web |Start does not support launching Java 1.3 applications.

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

## XIM and the Java Plug-in

AIX 5.3 only

For Japanese, Chinese, and Korean language users, you cannot use XIM to input your own characters into text components on a Java applet in a Web browser. 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. Input -Dsun.awt.noxembed=true in the Java Runtime Parameters and click OK.
4. Click Apply.
5. Start a browser.

This limitation is resolved in APAR IY77834 (AIX5.3).

## Printing

If you have difficulty with print operations, try increasing the size of the default file system that is used for print spooling to be larger than the printed postscript file size.

## Font quality in AWT

Text rendering for Java AWT TextField and TextArea components is performed by the AIX rasterizer for X/Motif text widgets. Currently, you might experience text dropouts at small font sizes for some fonts. This will be addressed in a future AIX release. To avoid the problem, use a font size that is greater than 12 points for AWT TextField and TextArea components.

## CapsLock in Chinese and Japanese locales

Chinese and Japanese locales only.

The CapsLock key does not work properly. On Chinese locales, you cannot input uppercase characters using the keyboard. To resolve the problem, see APAR IY98336.

## Java Desktop API

To use the Java Desktop API you must install the GNOME window manager. See http://java.sun.com/javase/technologies/desktop/ for more information about the Desktop API.

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

## Switching input methods

You must close the candidate window and commit pre-edited strings before you switch the Input Method (IM) using the IM selection menu. If you open the IM selection menu without either closing the candidate window or committing a pre-edited string, cancel the menu, close the candidate window, and commit the pre-edited string, then try to switch the IM again.

## Displaying DBCS characters in a JFrame

DBCS characters might not display correctly in the title of a JFrame. To avoid this problem, set the language in the console login screen instead of in a console prompt after you have logged in.

## Unicode Shift_JIS codepage alias

Japanese users only

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

# Notices

This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area.

Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 and AIX are trademarks or registered trademarks of International Business Machines Corporation in the United States, or other countries, or both.

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

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