IBM 32-bit SDK for AIX, Java 2 Technology Edition, Version 5

User Guide


Copyright information

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

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

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

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

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

Preface

Read this User Guide if you want to use the IBM(R) SDK to write Java(TM) applications and applets or if you want to use the Runtime Environment to run them.

Read this User Guide in conjunction with the more extensive documentation on the Sun Web site, http://java.sun.com, and the AIX(R) download site, http://www.ibm.com/developerworks/java/jdk/aix.

The software that is contained in this release can be used only on AIX Version 5.2 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.

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

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.

Contents

Copyright information
Preface
Contents and features of the SDK and Runtime Environment
Version compatibility
Features
Migrating from other IBM JVMs
AIX environment
Contents of the SDK and Runtime Environment
Runtime Environment tools
SDK tools
Installation
Upgrading the SDK
Verification
Using the SDK and Runtime Environment
Working with the PATH environment variable
Launching a Java application
Options
Obtaining the IBM build and version number
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
Specifying garbage collection policy
How the JVM processes signals
Transforming XML documents
| |
Support for thread-level recovery of blocked connectors
Dynamic Logical Partitioning (DLPAR) support
Working with applets
Running applets with the Applet Viewer
Debugging applets with the Applet Viewer
Java Plug-in/Applet Viewer
Java Plug-in HTML converter
Using the IPv6 extensions
Implementing the Connection Handler Pool for RMI
Enhanced BiDirectional support
Enhanced BigDecimal
Euro symbol support
| |
Support for Serbian locale
CORBA support
Support for GIOP 1.2
Support for Portable Interceptors
Support for Interoperable Naming Service
System properties for tracing the ORB
System properties for tuning the ORB
Java 2 security permissions for the ORB
ORB implementation classes
RMI over IIOP
AIX native threads
Scaling support
| |
SDK use of AIX large program support
| |
Automatic LDR_CNTRL=MAXDATA values
| |
Manual LDR_CNTRL=MAXDATA values
| |
AIX Stack Execution Disable
JNI compatibility
| |
Example of using AIX shared libraries
Using Web Start
Running Web Start
| |
Secure Static Versioning support
JNDI
HPROF Performance Profiler and JVMPI
GetCurrentThreadCpuTime
Known restriction
Debugging Java applications
Java Debugger (JDB)
Java Communications API
Java security
Java 3D for AIX
| |
Class data sharing between JVMs
| |
Overview of class sharing
| |
Cache contents
| |
Dynamic updating of the cache
| |
Enabling class sharing
| |
Cache security
| |
Cache lifespan
| |
Cache utilities
| |
Using command-line options for class sharing
| |
Creating, populating, monitoring, and deleting a cache
| |
Performance and memory consumption
| |
Limitations and considerations of using class sharing
| |
Cache size limits
| |
Runtime bytecode modification
| |
Operating system limitations
| |
Using SharedClassPermission
| |
Adapting custom classloaders to share classes
Shipping Java applications
| |
Support for XToolkit
Accessibility
iKeyman accessibility
Keyboard traversal of JComboBox components in Swing
Web Start accessibility
Known problems and limitations
Printing
Font quality in AWT
| |
Displaying AWT text components in Japanese
Switching Input Methods
| |
JConsole monitoring tool
Creating a JVM using JNI
| |
Java Plug-in limitation
Displaying DBCS characters in a JFrame
| |
ThreadMXBean Thread User CPU Time limitation
| |
JDBC/ODBC limitation
Any comments on this User Guide?
Notices
Trademarks

Contents and features of the SDK and Runtime Environment

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

Version compatibility

An applet or application that ran with earlier versions of the SDK should run with this version, except for the incompatibilities listed in:

|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

There is no guarantee that v5.0-compiled classes work on pre-5.0 SDK releases.

Applets that depend on the Java v1.4 (or later) APIs will not work with browsers that do not support these APIs unless you install the Java Plug-in.

There is a possible compatibility consideration if you are using the SDK as part of another product, for example WAS, and you upgrade from a previous level of the SDK, perhaps v1.4.2, to v5.0. If you serialized the classes with a previous level of the SDK, the classes might not be compatible. However, within v5.0 classes are compatible from service refresh to service refresh.

Features

The IBM 32-bit SDK for AIX, Java 2 Technology Edition, Version 5 has the following features:

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:

AIX environment

The IBM 32-bit SDK for AIX, v5, runs on AIX v5.2 |Recommended Maintenance |Package AIX 5200-07 or later, or v5.3 |Recommended Maintenance |Package AIX 5300-03 or later.

To test whether this Java v5 SDK is supported on a specific pSeries 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, http://www.ibm.com/servers/eserver/support/unixservers/aixfixes.html):

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 should have no dependencies on the IBM SDK's directory structure (or files in those directories). Any dependency on the SDK's directory structure (or the files in those directories) could result in application portability problems.

Runtime Environment tools

SDK tools

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

Installation

The IBM 32-bit SDK for AIX, v5 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:

These packages are optional:

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

The SDK is installed in the directory:

/usr/java5/

Set up your PATH environment variable to refer to the new installation:

export PATH=/usr/java5/jre/bin:/usr/java5/bin:$PATH

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

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

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:

*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:

you should see:

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.

Using the SDK and Runtime Environment

The following sections provide information about using the SDK and Runtime Environment.

Working with the PATH environment variable

The main SDK tools are programs that are run from a command prompt. After installing the SDK software, you run a tool by typing its name at a command prompt with a filename as an argument.

You can specify the path to a tool by typing the path in front of the tool each time, these tools are located in either the /usr/java5/bin or /usr/java5/jre/bin directories. For example, if the javac compiler is in /usr/java5/bin, you can compile a file named myfile.java by typing the following at a command prompt:

 /usr/java5/bin/javac myfile.java

Alternatively, you can add the string /usr/java5/bin to your PATH environment variable:

export PATH=/usr/java5/bin:/usr/java5/jre/bin:$PATH

Then you can compile the myfile.java file by typing the following at a command prompt:

 javac myfile.java

The PATH environment variable enables AIX to find the executable files (such as javac, java, and javadoc) from any directory. To find the current value of your PATH, at a command prompt type:

echo $PATH

Launching a Java application

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

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

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

The java and javaw command have the following syntax:

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

Items that are within brackets are optional.

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

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

Options

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

Specifying Java options and system properties

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

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

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

Standard options

Nonstandard options

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

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

Obtaining the IBM build and version number

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

java -version

Globalization of the java command

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

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

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

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

java -Xargencoding '\u0048ello\u0057orld'

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

Working with the LIBPATH environment variable

The environment variable LIBPATH 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 executable. For example, the header section of the java command is.

>dump -H /usr/java5/jre/bin/java

/usr/java5/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 located in /usr/java5/jre/bin and /usr/java5/jre/bin/ j9vm. These directories are automatically searched by the SDK's java launcher programs (for example, java, javac, jar). If Java is installed as an AIX fileset, the parent directory is /usr/java5/, 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:

| | |

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 on 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 and later PowerPC processors support the use of 16 MB large |pages in addition to the default 4 KB pages. The POWER5+ 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, while 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 |on 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 |may 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 may 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 would use 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 on 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 V5.0 compiler delivers new optimizations |as a result of compiler research, improves optimizations implemented in previous |versions of the JIT, and provides better hardware exploitation.

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

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 on this feature and how it affect the SDK, see AIX Stack Execution Disable.

Disabling the JIT

There are three ways to disable the JIT:

Both command-line options override the JAVA_COMPILER environment variable.

Enabling the JIT

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

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

Determining whether the JIT is enabled

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

java -version

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

(JIT disabled)

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

(JIT enabled)

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

Specifying garbage collection policy

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

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

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

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

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

Garbage collection options

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

The format of the option and its values is:

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:

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

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

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

Environments with very full heaps

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

How the JVM processes signals

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

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

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

For exception and error signals, the JVM either:

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

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

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

Signals used by the JVM

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

Table 1. Signals used by the JVM
Signal Name Signal type Description Disabled by -Xrs
SIGBUS (7) Exception Incorrect access to memory (data misalignment) Yes
SIGSEGV (11) Exception Incorrect access to memory (write to inaccessible memory) Yes
SIGILL (4) Exception Illegal instruction (attempt to invoke an unknown machine instruction) Yes
SIGFPE (8) Exception Floating point exception (divide by zero) Yes
SIGABRT Error Abnormal termination. The JVM raises this signal whenever it detects a JVM fault. Yes
SIGINT (2) Interrupt Interactive attention (CTRL-C). JVM exits normally. Yes
SIGTERM (15) Interrupt Termination request. JVM will exit normally. Yes
SIGHUP (1) Interrupt Hang up. JVM exits normally. Yes
SIGQUIT Control The JVM uses this for taking Java core dumps. 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 |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:

fp_trap( FP_TRAP_SYNC)

so that it generates a SIGFPE signal.

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.

To use libjsig.a:

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

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.

Transforming XML documents

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

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

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

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

To implement properties in the jaxp.properties file, copy jaxp.properties.sample to jaxp.properties in /etc/java5/jre/lib and create a symbolic link to this file from the /usr/java5/jre/lib directory. This file also contains full details about the procedure used to determine which implementations to use for the TransformerFactory, SAXParserFactory, and the DocumentBuilderFactory.

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

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

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

Using an older version of Xerces or Xalan

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

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

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

| | |

Support for thread-level recovery of blocked connectors

|

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

|

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

|

The classes are:

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

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

|

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

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. These 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 may degrade.

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:

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 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 |5 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 file docs/apidoc.zip.

|The launcher option, -Xsoftmx, is also |available with the Java 5 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 could 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.

Working with applets

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

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

Running applets with the Applet Viewer

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

   appletviewer name

where name is one of the following:

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

  appletviewer $HOME/filename.html

where filename is the name of the HTML file.

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

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

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

appletviewer -encoding JISAutoDetect sample.html

Debugging applets with the Applet Viewer

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

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

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

Java Plug-in/Applet Viewer

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:

Java Plug-in for AIX Mozilla

The Mozilla for AIX Web browser is available from:

When the installation is complete, to use the Java Plug-in, create one of the following links:

 ln -s /usr/java5/jre/bin/libjavaplugin_oji.so
		/usr/mozilla/base/plugins/libjavaplugin_oji.so

or:

ln -s /usr/java5/jre/bin/libjavaplugin_oji.so
          $HOME/.mozilla/plugins/libjavaplugin_oji.so

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

|This Java Plug-in supports Mozilla 1.7.12 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/java5/jre/bin and /usr/java5/jre/bin/j9vm to your LIBPATH environment |variable.

Note that 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 shell script:

/usr/java5/jre/bin/ControlPanel

Using the Java Plug-in

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

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

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

Supported browsers
|Table 2. Browsers supported by the Java Plug-in
|Operating System |Supported Browsers
|AIX V5.2 |Mozilla 1.4, 1.7, available at http://www.ibm.com/servers/aix/browsers/ and the Mozilla for AIX CD.
|AIX v5.3 |Mozilla 1.4, 1.7, available at http://www.ibm.com/servers/aix/browsers/ and the Mozilla for AIX CD.
Common Document Object Model (DOM) support

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

Java Plug-in HTML converter

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. The tool is in the /usr/java5/bin directory with a jar file in the /usr/java5/lib directory.

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

Using the IPv6 extensions

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

On AIX v5.2, if your application uses multicast sockets or your application explicitly uses IPv6 format address, you must enable the network interfaces on your machine to handle IPv6 addresses. The network interfaces can be configured for IPv6 with smitty or by using the autoconf6 or ifconfig commands. Alternatively, if you do not want to use IPv6 protocols, you can set the property java.net.preferIPv4Stack to force the use of IPv4 protocols.

Implementing the Connection Handler Pool for RMI

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

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

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

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

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

Enhanced 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 file docs/apidoc.zip.

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, currently, you are recommended to regard |it as deprecated. You are recommended to migrate existing Java code to use |java.math.BigDecimal.|

|

|The new java.math.BigDecimal uses the same methods as both |the previous java.math.BigDecimal and com.ibm.math.BigDecimal. Existing code |using java.math.BigDecimal continues to work correctly. 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.*;.

Euro symbol support

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

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

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

|In V5.0 SR3, the default for the Slovenian locale is set |to the Euro. If you install SR3 before 1 January 2007, you might want to change |the currency to the Tolar.

| | |

Support for Serbian locale

|

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

|

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

CORBA support

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

Support for GIOP 1.2

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

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

Bidirectional GIOP is not supported.

Support for Portable Interceptors

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

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

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

Support for Interoperable Naming Service

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

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

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

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

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

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

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

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

System properties for tracing the ORB

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

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

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

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

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

System properties for tuning the ORB

The following properties help you to tune the ORB:

Java 2 security permissions for the ORB

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

Table 3. Methods affected when running with Java 2 SecurityManager
Class/Interface Method Required permission
org.omg.CORBA.ORB

init

java.net.SocketPermission resolve

org.omg.CORBA.ORB

connect

java.net.SocketPermission listen

org.omg.CORBA.ORB

resolve_initial_references

java.net.SocketPermission connect

org.omg.CORBA.
portable.ObjectImpl

_is_a

java.net.SocketPermission connect

org.omg.CORBA.
portable.ObjectImpl

_non_existent

java.net.SocketPermission connect

org.omg.CORBA.
portable.ObjectImpl

OutputStream _request (String, boolean)

java.net.SocketPermission connect

org.omg.CORBA.
portable.ObjectImpl

_get_interface_def

java.net.SocketPermission connect

org.omg.CORBA.
Request

invoke

java.net.SocketPermission connect

org.omg.CORBA.
Request

send_deferred

java.net.SocketPermission connect

org.omg.CORBA.
Request

send_oneway

java.net.SocketPermission connect

javax.rmi.
PortableRemoteObject

narrow

java.net.SocketPermission connect

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

ORB implementation classes

The ORB implementation classes in this release are:

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

RMI over IIOP

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

The following documentation is available:

AIX native threads

| |

On AIX 5.2, Java runs with system contention scope threads (AIXTHREAD_SCOPE=S). This way of running means that each Java thread |is mapped one-to-one to an AIX kernel thread and that these kernel threads |are scheduled against all other threads in the system. Each thread has an |initial priority that is dynamically modified by the AIX scheduler, according |to the thread's activity; thread execution is time-sliced. As such, the Java |interfaces for setting thread priority have no effect on the thread's actual |priority.

|

From AIX 5.3 onwards, programs can set the priority of system contention |scope threads. Java 5 exploits this new feature; calls to java.lang.Thread.setPriority() |will change the priority of Java threads running on AIX 5.3.

|

For more details on AIX dynamic thread scheduling, see:

|

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

|

For more details on 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.

Scaling support

For maximum threads (with JIT), try setting the command-line parameter with -Xss<size> by specifying the maximum native stack size to be smaller than the default value of 512 KB. A smaller setting allows for a larger number of threads. For example:

java -Xss<size> <other params>

For maximum file descriptors, use the ulimit command, for example:

ulimit -n 3000

or chuser, for example:

chuser nofiles=3000 <user_id>

to increase the limit. (ulimit -a shows 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://www16.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 |could 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:

| |

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

| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Table 4. Java's default 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 Native Heap (malloc'ed space) or Memory Mapped space |(mmap/shmat)
5 Native Heap (malloc'ed space) or Memory Mapped space |(mmap/shmat)
6 Native Heap (malloc'ed space) or Memory Mapped space |(mmap/shmat)
7 Native Heap (malloc'ed space) or Memory Mapped space |(mmap/shmat)
8 Native Heap (malloc'ed space) or Memory Mapped space |(mmap/shmat)
9 Native Heap (malloc'ed space) or Memory Mapped space |(mmap/shmat)
A Native Heap (malloc'ed space) or Memory Mapped space |(mmap/shmat)
B Native Heap (malloc'ed space) or Memory Mapped space |(mmap/shmat)
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:

| |

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, while 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 could 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 could consume a large fraction of the |native heap for thread stacks, which could 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 could 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 5. 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 Native Heap (malloc'ed space) or Memory Mapped space |(mmap/shmat)
5 Native Heap (malloc'ed space) or Memory Mapped space |(mmap/shmat)
6 Native Heap (malloc'ed space) or Memory Mapped space |(mmap/shmat)
7 Native Heap (malloc'ed space) or Memory Mapped space |(mmap/shmat)
8 Native Heap (malloc'ed space) or Memory Mapped space |(mmap/shmat)
9 Native Heap (malloc'ed space) or Memory Mapped space |(mmap/shmat)
A Native Heap (malloc'ed space) or Memory Mapped space |(mmap/shmat)
B Native Heap (malloc'ed space) or Memory Mapped space |(mmap/shmat)
C Native Heap (malloc'ed space) or Memory Mapped space |(mmap/shmat)
D Native Heap (malloc'ed space) or Memory Mapped space |(mmap/shmat)
E Memory Mapped space (mmap/shmat)
F Memory Mapped space (mmap/shmat)
|

As always, 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:

| |

Once again, 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 6. Memory model with MAXDATA=0@DSA
Segment Contents
0 AIX kernel
1 Java program
2 Native Heap (malloc'ed space) and Primordial Stack |(main program stack)
3 Memory Mapped space (mmap/shmat)
4 Memory Mapped space (mmap/shmat)
5 Memory Mapped space (mmap/shmat)
6 Memory Mapped space (mmap/shmat)
7 Memory Mapped space (mmap/shmat)
8 Memory Mapped space (mmap/shmat)
9 Memory Mapped space (mmap/shmat)
A Memory Mapped space (mmap/shmat)
B Memory Mapped space (mmap/shmat)
C Memory Mapped space (mmap/shmat)
D Memory Mapped space (mmap/shmat)
E Memory Mapped space (mmap/shmat)
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

|

Through the use of explicit manual settings of the LDR_CNTRL=MAXDATA environment variable, you can use memory layouts that are different |from the automatic settings. One interesting setting is MAXDATA=0:

| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Table 7. Memory model with MAXDATA=0
Segment Contents
0 AIX kernel
1 Java program
2 Primordial Stack (main program thread stack) and |Native Heap
3 Memory Mapped space (mmap/shmat)
4 Memory Mapped space (mmap/shmat)
5 Memory Mapped space (mmap/shmat)
6 Memory Mapped space (mmap/shmat)
7 Memory Mapped space (mmap/shmat)
8 Memory Mapped space (mmap/shmat)
9 Memory Mapped space (mmap/shmat)
A Memory Mapped space (mmap/shmat)
B Memory Mapped space (mmap/shmat)
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:

||
| | |

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

JNI compatibility

There is a README file and example programs in the /usr/java5/demo/jni directory. The demos can be optionally installed with the Java5.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.

|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/java5/jre/bin and /usr/java5/jre/bin/j9vm, as well as the |directories that contain the application's shared libraries.

You must build:

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/java5/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:

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 executable 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:

For example, you could use this command to build a C program (invAPITest.c) that uses the JNI Invocation API:

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

When executing a C or C++ program that uses the JNI Invocation API to run Java classes, ensure that the CLASSPATH 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

Java v5.0 allows you to 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().loadLibrary(), Runtime.getRuntime().load()).

|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

|
    |
  1. Create a sample application called 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. |
  3. Compile Sample.java: |
    javac Sample.java 
  4. |
  5. Use javah to create a header file for the native code: |
    javah Sample
  6. |
  7. 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");
    |}
  8. |
  9. Compile Sample.c into libSample.o: |
    cc_r -bM:SRE -bnoentry -bexpall -I/usr/java5/include Sample.c -o libSample.o 
  10. |
  11. Create an archive shared library libShared.a: |
    ar -X32 -v -q libShared.a libSample.o
  12. |
  13. Run the Sample class: |
    LIBPATH=. java Sample

Using Web Start

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

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

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

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

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

Running Web Start

|Before using Web Start, you must run the /usr/java5/jre/lib/javaws/updateSettings.sh |script to update your ~/.mailcap and ~/.mime.types files.

You can invoke Web Start in three ways:

  1. Select a link on a Web page that refers to a .jnlp file.
  2. At a shell prompt, type javaws <URL>, where <URL> is the location of a .jnlp file. You must have the Runtime Environment in your path.
  3. |If you have used Java Web Start to open the application in |the past, run /usr/java5/jre/bin/javaws to launch the Java Application |Cache Viewer.

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

| | |

Secure |Static Versioning support

|

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

|

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

|

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

JNDI

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

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 defined in jvmpi.h .

GetCurrentThreadCpuTime

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

export AIXTHREAD_ENRUSG=ON

You will get the following message output 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

The default for the Java environment is AIXTHREAD_ENRUSG=OFF.

When the resource collection is enabled, the HPROF profiling agent, invoked with:

-Xrunhprof:cpu=times

provides meaningful data in the HPROF output.

Known restriction

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

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. Note that, although the DBX Plug-in is supplied as part of the SDK, it is not supported. However, IBM will accept bug reports.

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

Java Debugger (JDB)

The Java Debugger (JDB) is included in the SDK for 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> MyApp <args>
  2. The JVM starts up, but suspends execution before it starts the Java application. In a separate session, you can attach the debugger to the JVM:
    jdb -attach <port number>
    The debugger will attach to the JVM, and you can now issue a range of commands to examine and control the Java application; for example, type run to allow the Java application to execute.

To find out more about JDB options, type:

jdb -help

To find out more about JDB commands:

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

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

  1. Start the JVM as before.
  2. Attach the debugger to the remote machine:
    jdb -attach <machine name or IP address>:<port number>

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

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

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


Java Communications API

This release includes the Java Communications API 2.0 standard extension, which allows Java applications to access RS232 serial ports and IEEE 1284 parallel ports.

The API is shipped in the Java5.ext.commapi fileset (optionally installable) and supports an unlimited number of tty's, with ttyn mapped to COM(n+1) where n is 0 or a positive decimal integer:

/dev/tty0 -> COM1     
/dev/tty1 -> COM2     
...     
/dev/tty9 -> COM10     
/dev/tty10 -> COM11     
...

If a tty is not available, the corresponding COM port is not available. For example, if tty0 and tty2 are available but tty1 is not, COM1 and COM3 can be available but COM2 is not.

For API details, see http://www.javasoft.com/products/javacomm/.

Java security

For information about Java security, see the Java Security User Guide for AIX.

Java 3D for AIX

This release includes Java 3D for AIX, Version 1.3. The fileset, Java5.ext.java3d, is optionally installable. For more information, read /usr/java5/java3d/README.java3d.aix.txt (after installing the fileset).

| | |

Class data sharing between JVMs

|

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

| |

Overview of class sharing

|

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

| |

Cache contents

|

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

| |

Dynamic updating of the cache

|

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

| |

Enabling class sharing

|

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

| |

Cache security

|

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

| |

Cache lifespan

|

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

| |

Cache utilities

|

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

| |

Using command-line options for class sharing

|

Use the -Xshareclasses and -Xscmx command-line options to enable and configure class sharing.

| | |

Creating, populating, monitoring, and deleting a cache

|

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

|

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

|

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

|

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

|

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

|

You are recommend to tune the cache size for your specific application, |because the default is unlikely to be the optimum size. The best way to determine |the optimum cache size is to specify a large cache (using -Xscmx), run the application, and then use printStats to determine how |much class data has been stored. Add a small amount to the value shown in |printStats for contingency. Note that because classes can be loaded at any |time during the lifetime of the VM, 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 VMs connected to it, so it |is quite legitimate to decide on a cache size that is smaller than required.

|

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

| |

Performance and memory consumption

|

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

|

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

|

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

|

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

| |

Limitations and considerations of using class sharing

| |

Cache size limits

|

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

|

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

|

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

|

The virtual address space available to the process is:

| | |

Runtime bytecode modification

|

|Any VM using a JVMTI (JVM Tool Interface) agent that can |modify bytecode data should use the modified=<modified_context> suboption |if it wants to share the modified classes with another VM. (See Using command-line options for class sharing.) |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 VMs running under the same context share a partition. This partitioning |allows VMs that are not using modified bytecode to safely share a cache with |those that are using modified bytecode. All VMs using a given modified context |must modify bytecode in a predictable, repeatable manner for each class, so |that the modified classes stored in the cache have the expected modifications |when they are loaded by another VM. Any modification must be predictable because |classes loaded from the shared class cache cannot be modified again by the |agent.|

|

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

|

See the Diagnostics Guide for more detail |on this topic.

| |

Operating system limitations

|

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

|

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

|

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

| |

Using SharedClassPermission

|

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

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

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

| |

Adapting custom classloaders to share classes

|

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

Shipping Java applications

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

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 AIX SDK a prerequisite or ship with a version of the SDK that is specifically for the purpose of redistribution. The AIX SDK license does not allow you to redistribute any of the SDK files installed in /usr/java5/ by installp. You can redistribute the SDK files in the j532redist.tar or j532redist.tar.gz file (after viewing and agreeing to the associated on-line 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 5 download page.

| | |

Support for XToolkit

|
|

From Service Refresh 4, the IBM 32-bit SDK for AIX, Java 2 Technology Edition, Version 5 supports XToolkit. You need XToolkit |when using the Eclipse's SWT_AWT bridge to build an application that uses |both SWT and Swing. XToolkit is an alternative to the existing use of MToolkit |libraries (which are the default), with the benefit of faster rendering.

|

You need to apply PTFs |to use XToolkit. Refer to these Web pages:

| |

See http://eclipsezone.com/eclipse/forums/t45697.html for an example showing the integration of Swing into Eclipse Rich Client |Applications (RCPs).

|

For reference information, see http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/awt/SWT_AWT.html.

|

For information about setting the toolkit and switching from MToolkit, |see http://java.sun.com/j2se/1.5.0/docs/guide/awt/1.5/xawt.html.

Accessibility

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

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

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

iKeyman accessibility

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

To run an IKEYCMD command, enter:

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

where:

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

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

Keyboard traversal of JComboBox components in Swing

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

Web Start accessibility

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

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

Known problems and limitations

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.

| | |

Displaying AWT text components in Japanese

|

If your system runs slowly when displaying AWT text components on AIX 5.2 |in a Japanese environment (non-UTF-8 locale), apply APAR IY75960.

Switching Input Methods

You must close the candidate window and commit preedited 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 preedited string, cancel the menu, close the candidate window, and commit the preedited string, then try to switch the IM again.

| | |

JConsole monitoring tool

|
|

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 connect command-line |option, specifying a host of local host and a port number. When you launch |the application that you want to monitor, set these command-line options:

|

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:

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

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

| | |

Java Plug-in limitation

|

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 avoid this situation, apply APAR IY77834 (AIX5.3) or APAR IY77820 (AIX5.2). |You can also work around the problem by specifying 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. |
  3. Click the View button in the Java Applet Runtime |Settings.
  4. |
  5. Input -Dsun.awt.noxembed=true in the Java Runtime |Parameters and click OK.
  6. |
  7. Click Apply
  8. |
  9. Start a browser.

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.

| | |

ThreadMXBean Thread User CPU Time limitation

|

In package java.lang.management, the methodsThreadMXBean.getThreadUserTime() |and ThreadMXBean.getCurrentThreadUserTime() are not supported. These methods |always return -1. Note that these methods are not supported even when ThreadMXBean.isThreadCpuTimeSupported() |and ThreadMXBean.isCurrentThreadCpuTimeSupported() return true.

|

This limitation does not affect ThreadMXBean.getThreadCpuTime() or ThreadMXBean.getCurrentThreadCpuTime().

| | |

JDBC/ODBC limitation

|

The JDBC-ODBC bridge driver shipped with this release is unsupported.

Any comments on this User Guide?

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

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

Notices

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

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

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

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:

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

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

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

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

Trademarks

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

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

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