IBM®
Skip to main content
    Country/region [select]      Terms of use
 
 
      
     Home      Products      Services & solutions      Support & downloads      My account     
[an error occurred while processing this directive]
 
developerWorks  >  Java technology  >  IBM developer kits  > AIX developerWorks

IBM 32-bit SDK for AIX, Java 2 Technology Edition, Version 1.4 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 1.4, and to all subsequent releases and modifications until otherwise indicated in new editions.

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

(c) Copyright International Business Machines Corporation, 1999, 2004. 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 download site, http://www.ibm.com/developerworks/java/jdk/aix.

The software that is contained in this release can be used only on AIX(R) Version 5.1 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. Ensure that you have the User Guide appropriate to the release you are using.

Useful Web sites include:

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

|Note that the Java14.debug fileset which contained the debug |builds (such as java_g, jdb_g, and so on) is not provided |in this release.

Technical changes for this Version 1.4.2 User Guide, other than minor or obvious ones such as updating "1.4.1" to "1.4.2", 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

| | | | | | | | | | | || || || || || || || || || |

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 1.4 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/1.4/compatibility.html

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

There is no guarantee that v1.4.2-compiled classes work on pre-1.4.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.

|If you are using the SDK as part of another |product, for example WAS, and you upgrade from a previous version of the | SDK to v142 SR1, if you serialized the classes with a previous version, |classes from SDK 1.4.2 are compatible with SDK 1.4.2 SR 1 (while other SDK |levels might not be compatible).

Features

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

  • Fully compatible with the Java 2 Version 1.4.2 language, enabling "Write Once Run Anywhere"
  • A comprehensive Diagnostics Guide for Java v1.4.2 at http://www.ibm.com/developerworks/java/jdk/diagnosis/index.html.
  • Performance enhancements to make Java programs run faster
  • The latest version of the IBM optimizing Just In Time (JIT) compiler version 5.0 with Mixed Mode Interpreter (MMI - for selective compilation of frequently executed code)
  • Concurrent garbage collection option, which can significantly reduce maximum application pause times
  • Incremental compaction, which significantly decreases the chance of a full heap compaction (important for multi-gigabyte heaps)
  • Support of AIX Large Pages
  • Support of AIX's Very Large Address Space Model
  • |A DBX plug-in that allows you to use DBX to debug your Java |programs more effectively. For more information, see DBX Plug-in for the SDK.
  • Support for "Headless" configurations. For more information, see http://java.sun.com/j2se/1.4.2/docs/guide/awt/AWTChanges.html.
  • Java 3D Version 1.3
  • JavaHelp Version 1.1.2
  • A new Reliability, Accessibility, and Serviceability interface, to help the IBM Service team debug any problems
  • Efficient exploitation of AIX native threads
  • "Handle-less" object model
  • Fast, lightweight monitors
  • Efficient management of large Java heaps through optimized object allocation and efficient garbage collection with JVM runtime parameters for specifying garbage collection policy
  • Thread-local heap
  • Support for the European Union currency, the Euro
  • Robust networking supporting a large number of concurrent connections
  • Better scaling support for large numbers of threads and large numbers of file handles
  • Java Communications API Version 2.0
  • IBM Big Decimal Extension

AIX environment

The IBM 32-bit SDK for AIX, v1.4, runs on AIX v5.1 (|Recommended Maintenance |Package AIX 5100-06), AIX v5.2 (|Recommended Maintenance |Package AIX 5200-03) and any later compatible level. The supported version of AIX v5.3 is 5.3.0.1 (APAR IY58143) or later.

To test whether this Java v1.4.2 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.

If you are using one of the supported non-UTF8 CKJ locales, you must install one of the following filesets (the install images are available on AIX v5.1/5.2 base CDs; updates are available from the AIX fix distribution Web site, https://techsupport.services.ibm.com/server/fixes):

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

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

  • Core Classes -- These are the compiled class files for the platform and must remain zipped for the compiler and interpreter to access them. Do not modify these classes; instead, create subclasses and override where you need to.
  • JRE tools -- The following tools are part of the Runtime Environment and are in the /usr/java14/jre/bin directory.
    • Java Interpreter (java)
      • Executes Java bytecodes. The Java Interpreter runs programs that are written in the Java programming language.

    • Java Interpreter (javaw)
      • Executes Java bytecodes in the same way as the java command does, but does not use a console window.

    • Key and Certificate Management Tool (keytool)
      • Manages a keystore (database) of private keys and their associated X.509 certificate chains that authenticate the corresponding public keys.

    • Policy File Creation and Management Tool (policytool)
      • Creates and modifies the external policy configuration files that define your installation's Java security policy.

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

    • Common Object Request Broker Architecture (CORBA) Naming Service (tnameserv)
      • Starts the CORBA transient naming service.

    • Java Remote Object Registry (rmiregistry)
      • Creates and starts a remote object registry on the specified port of the current host.

    • iKeyman GUI utility.
    • Dump extractor (jextract)

Earlier versions of the IBM JRE shipped with a file called rt.jar in the jre/lib directory. From Java V1.4 onwards, this file has been replaced by multiple JAR files that reside in the jre/lib directory. Examples of these JAR files are:

  • core.jar, which contains the majority of the class libraries, including the system, IO, and net class libraries
  • graphics.jar, which contains the awt and swing class libraries
  • |security.jar, which contains the security framework code. |For maintenance reasons, security.jar has been split up into smaller JAR files |for this release.
  • server.jar, which contains the RMI class libraries
  • xml.jar, which contains the xml and html class libraries

This change should be completely transparent to the application. If an error is received about a missing rt.jar file in CLASSPATH, this error points to a setting that was used in Java V1.1.8 and was made obsolete in subsequent versions of Java. You can safely remove references to rt.jar in CLASSPATH.

SDK tools

  • The following tools are part of the SDK and are located in the /usr/java14/bin directory:
    • Java Compiler (javac)
      • Compiles programs that are written in the Java programming language into bytecodes (compiled Java code).

    • Java Applet Viewer (appletviewer)
      • Tests and runs applets outside a Web browser.

    • Java Debugger (jdb)
      • Helps debug your Java programs.

    • Class File Disassembler (javap)
      • Disassembles compiled files and can print a representation of the bytecodes.

    • Java Documentation Generator (javadoc)
      • Generates HTML pages of API documentation from Java source files.

    • C Header and Stub File Generator (javah)
      • Enables you to associate native methods with code written in the Java programming language.

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

    • JAR Signing and Verification Tool (jarsigner)
      • Generates signatures for JAR files, and verifies the signatures of signed JAR files.

    • Native-To-ASCII Converter (native2ascii)
      • Converts a native encoding file to an ASCII file that contains characters encoded in either Latin-1 or Unicode, or both.

    • Java Remote Method Invocation (RMI) Stub Converter (rmic)
      • Generates stubs, skeletons, and ties for remote objects. Includes RMI over Internet Inter-ORB Protocol (RMI-IIOP) support.

    • IDL to Java Compiler (idlj)
      • Generates Java bindings from a given IDL file.

    • Serial Version Command (serialver)
      • Returns the serialVersionUID for one or more classes in a format that is suitable for copying into an evolving class.

    • Extcheck utility (extcheck)
      • Detects version conflicts between a target jar file and currently-installed extension jar files.

    • Cross-platform dump formatter (jformat)
    • Java Plug-in HTML Converter (HtmlConverter)
      • Converts an HTML page that contains applets to a format that can use the Java Plug-in.

    • Java Web Start (webstart_install_sdk.sh)
      • Enables the deployment and automatic maintenance of Java applications. For more information, see Installing Web Start.

  • INCLUDE FILES
    • C headers for JNI programs.

  • USER GUIDE
    • This file.

  • COPYRIGHT
    • Copyright notice for the SDK for AIX software.

  • LICENSE
    • The LICENSE file, /usr/swlag/<locale>/Java14.la, contains the license agreement for the SDK for AIX software (where <locale> is the name of your locale, for example En_US). To view or print the license agreement, open the file in a Web browser.
  • FIXES.LST
    • A text file that describes any defects that are fixed after the initial release of this version.

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.

Tools not included in the IBM SDK

The following tools are not included in the IBM SDK:

  • MIF doclet
  • orbd
  • servertool

Installation

The IBM 32-bit SDK for AIX, v1.4 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.

These packages are required:

  • Java14.license (license)
  • Java14.sdk (base SDK, WebStart, and dt.jar)

These packages are optional:

  • Java14.ext (Comm API, Java 3D, and JavaHelp)
  • Java14.samples (demos)
  • Java14.source (src.jar)
  • Java14.msg.$LANG

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

  • Zh_CN
  • zh_CN
  • ko_KR
  • Ja_JP
  • ja_JP
  • Zh_TW
  • zh_TW

The SDK is installed in the directory:

/usr/java14/

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

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

Note: These elements of PATH changed, at Version 1.3.0, from the previous SDK releases. The v1.4.2 SDK does not use a java wrapper as Version 1.1.x and 1.2.2 did. When you install the v1.4.2 SDK in the /usr/java14/ directory, if you have symbolic links created by the V1.1.8 SDK and you don't set up the PATH environment variable, the V1.1.8 SDK is picked up as the default. You are not recommended to remove the old links in case you have applications that require the V1.1.8 SDK.

Upgrading to v1.4.2

If you are upgrading to SDK v1.4.2 from a previous release, back up all the configuration files and security policy files before you go ahead with the upgrade.

Verification

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

  • unset LIBPATH
  • unset CLASSPATH
  • unset JAVA_COMPILER
  • unset JAVA_HOME*
  • export PATH=/usr/java14/jre/bin:/usr/java14/bin:$PATH

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

If you issue the command:

  • java -version

you should see:

  • java version "1.4.2"
    Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2)
    Classic VM (build 1.4.2, J2RE 1.4.2 IBM AIX build ca142-20040917 (JIT enabled: jitc))

When verification is complete, log on again and review any values that you might have assigned to these variables with the new installation for possible conflicts. Unless .hotjava already existed, executing the applet viewer creates a directory called .hotjava in your home directory. Issuing the command:

  • ls -a ~

should confirm this.

The Just-In-Time (JIT) compiler

The IBM JIT compiler (libjitc.a) dynamically generates machine code for frequently-used bytecode sequences in a Java application or applet during execution. The JIT V5.0 compiler delivers dynamic compiler technology, including:

  • Improvements to optimizations that were implemented in previous versions of the JIT
  • Optimizations that were added to JIT v5.0
  • Stack allocation of objects
  • Improved hardware exploitation

The JIT is enabled by default. To explicitly enable the JIT, set the |JAVA_COMPILER environment variable to the value "jitc".

All SDK tools use the JIT by default. After installation, you can specify whether or not the JIT will be used. You can disable the JIT to help in the isolation of a problem with a Java application, an applet, or the compiler itself.

Disabling the JIT

There are two ways to disable the JIT:

  • Type the following at a command prompt:
    1. For the Korn shell:
      • export JAVA_COMPILER=NONE

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

    2. For the Bourne shell:
      • JAVA_COMPILER=NONE
      • export JAVA_COMPILER
    3. For the C shell:
      • setenv JAVA_COMPILER NONE
  • Use the -D option on the java command to set java.compiler to NONE to override the default or the environment variable settings:
    java -Djava.compiler=NONE <myapp>

Enabling the JIT

To enable the JIT, set the JAVA_COMPILER environment variable to "jitc" or switch on the JIT compiler through the command line:

java -Djava.compiler=jitc <myapp>

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

Note:

If JAVA_COMPILER="" or -Djava.compiler="" , the JIT compiler is disabled. If JAVA_COMPILER is unset, as in:

unset JAVA_COMPILER

the default JIT compiler is enabled. The default JIT compiler is always the latest version.

Using the SDK and Runtime Environment

The following sections provide information about using the SDK.

Obtaining the IBM build and version number

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

java -version

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. For example, if the javac compiler is in /usr/java14/bin, you can compile a file named myfile.java by typing the following at a command prompt:

 /usr/java14/bin/javac myfile.java

Alternatively, you can add the string /usr/java14/bin to your PATH environment variable. 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

Note:

Like the 1.3.0 and 1.3.1 versions, the IBM 32-bit SDK for AIX, v1.4 ships the java tools as binary executables instead of the shell scripts that were shipped in previous versions up to Version 1.2.2. The PATH environment variable must point to the bin directories instead of sh directories as follows:

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

Launching a Java application

The java tool launches a Java application.

It does this by starting a Java Runtime Environment, loading a specified class, and invoking that class's main method. The method declaration must have the signature:

public static void main(String args[])  

The method must be declared public and static, it must not return any value, and it must accept a String array as a parameter. By default, the first non-option argument is the name of the class to be invoked. Use a fully-qualified class name.

The JVM searches for the startup class, and other classes that are used, in three sets of locations: the bootstrap classpath, the installed extensions, and the user classpath. Arguments 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.

Summary of commands

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.
argument
Argument passed to the main function.

If the -jar option is specified, the named JAR file contains 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.

Standard options

  • -D<property_name>=<value>
    • Sets a system property.
  • -assert
    • Prints help on assert-related options.
  • -cp or -classpath <directories and zip or jar files separated by :>
    • Set search path for application classes and resources. If -classpath and -cp are not used, and CLASSPATH is not set, the user classpath is, by default, the current directory (.). Also see Working with classpaths.
  • -help or -?
    • Prints a usage message.
  • -showversion
    • Prints product version and continues.
  • -verbose:[class | gc | jni]
    • Enables verbose output.
  • -version
    • Prints product version.
  • -X
    • Prints help on non-standard options.

Non-standard options

The -X options listed below are a subset of the available ones. They are nonstandard and subject to change without notice.

  • -Xargencoding
    • Allows the options on the java command to use Unicode escape sequences to represent characters that are not in the character set of the locale. Unicode escape sequences are of the form \u#### where # is a hexadecimal digit.
  • -Xbootclasspath:<directories and zip or jar files separated by ;>
  • -Xbootclasspath/a:<directories and zip or jar files separated by ;>
    • Appends to end of bootstrap class path.
  • -Xbootclasspath/p:<directories and zip or jar files separated by ;>
  • -Xcheck:jni
    • Performs additional checks for JNI functions.
  • -Xcheck:nabounds
    • Performs additional checks for JNI array operations.
  • -Xdebug
    • Starts the JVM with the debugger enabled.
  • -Xdisableexplicitgc
    • Changes calls to System.gc() into no-ops.
  • -Xdisablejavadump
    • Disables the java dump facility for abnormal process termination. When the java dump is disabled, the system process termination dump is run. The java dump is useful when the problem occurs within the java code.
  • -Xgcpolicy:{optthruput | optavgpause | subpool}
  • -Xlp
    • Requests the SDK to allocate the Java heap (the heap from which Java objects are allocated) with 16 MB large pages. If large pages are not available, the Java heap will be allocated with AIX's standard 4 KB pages. AIX requires special configuration to enable large pages. For more information on configuring AIX support for large pages, see http://www.ibm.com/servers/aix/whitepapers/large_page.html. The SDK supports the use of large pages only to back the Java heap's share memory segments (the SDK uses shmget() with the SHM_LGPG and SHM_PIN flags to allocate large pages). The use of the LDR_CNTRL=LARGE_PAGE_DATA environment variable is not supported. The -Xlp option replaces the environment variable IBM_JAVA_LARGE_PAGE_SIZE, which is now ignored if set.
  • -Xms<size>
    • Sets initial Java heap size. The default is 4 MB.
  • -Xmx<size>
    • Sets maximum Java heap size. The default is 64 MB.
  • -Xnoclassgc
    • Disables class garbage collection.
  • -Xoss<size>
    • Sets maximum Java stack size for any thread. The default is 400 KB.
  • |-Xpd |
      |
    • Loads the Problem Determination (PD) runtime libraries. Use this option |only when IBM service requests it. The PD libraries are not shipped, so this |option normally fails.
  • -Xquickstart
    • Improves the startup time of applications. If you do not specify this option, the initial compilation of methods is done at high optmization (that is, the JIT does not recompile "hot" methods because the methods are initially compiled with high optimization).
  • -Xrs
    • Reduces the use of operating system signals.
  • -Xrunlibrary_name[:options]
    • Loads helper libraries. To load multiple libraries, specify it more than once on the command line. Examples of these libraries are:
      • -Xrunhprof[:help] | [:<option>=<value>, ...]
        • Performs heap, CPU, or monitor profiling.
      • -Xrunjdwp[:help] | [:<option>=<value>, ...]
        • Loads debugging libraries to support the remote debugging of applications.
  • -Xss<size>
    • Sets maximum native stack size for any thread. The default is 512 KB.
  • -Xverbosegclog:<path to file><filename>[X, Y]
    • Causes verboseGC output to be written to the specified file. If the file exists, it is overwritten. Otherwise, if an existing file cannot be opened or a new file cannot be created, the output is redirected to stderr. If you specify the arguments X and Y (both are integers) the verboseGC output is redirected to X number of files, each containing Y number of gc cycles worth of verboseGC output. These files have the form filename1, filename2, and so on.
      Note:
      The environment variable IBM_JVM_ST_VERBOSEGC_LOG has been removed.
  • -Xverify
    • Enables strictest checks, anticipating future default.

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 Unicode character that is in the character set of the current locale.

You can 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).

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

In the Runtime Environment, if you are using a non-English locale, the java and javaw commands give translated output messages. These messages are different from those that were in the 1.3.1 version and also differ based on the locale in which Java is running. The detailed error descriptions and other debug information that is returned by java is in English. Debug information that is returned during initialization is shown in brackets.

Working with classpaths

In the Runtime Environment, you can specify a class name as a complete file name including a full path and the .class extension. In previous versions of the SDK, you could specify only the class that was relative to the CLASSPATH, and the .class extension was not allowed. Use of the complete file name permits you to launch a java application from your desktop or file launcher. If you specify a .class file with path and extension, the specified path is put into the CLASSPATH. For example, the command java ~/myapp/thisapp.class is equivalent to specifying java -classpath ~/myapp thisapp.

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/java14/jre/bin/java

/usr/java14/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/java14/jre/bin and/usr/java14/jre/bin/classic. 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/java14/, 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:

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

The LD_LIBRARY_PATH environment variable is not used by Java. If your application needs to search specific directories when looking for shared libraries, the only variable to set is LIBPATH.

| | |

Working with the LDR_CNTRL=MAXDATA environment variable

|

The LDR_CNTRL=MAXDATA environment variable controls |Java's memory model (for more information, see AIX Large Address-Space Model support and AIX Very Large Address-Space Model support). If you do not set LDR_CNTRL=MAXDATA explicitly |to a value, the SDK selects an appropriate value automatically. This value |is based on the maximum size of the Java heap. For more information, see Default LDR_CNTRL=MAXDATA values.

Working with the bootclasspath

You can set the system property ibm.jvm.bootclasspath by using the -D option that is described in Launching a Java application. The value of this property is used as an additional search path, which is inserted between any value that is defined by -Xbootclasspath/p: and the bootstrap classpath. The bootstrap classpath is either the default, or that is defined using the -Xbootclasspath: option.

Do not deploy applications that use the -Xbootclasspath: or -Xbootclasspath/p: option to override a class in core.jar, graphics.jar, server.jar, security.jar, xml.jar, tools.jar, or charsets.jar, because such a deployment would contravene the Java 2 Runtime Environment binary code license.

Specifying garbage collection policy

The -Xgcpolicy JVM runtime option specifies garbage collection policy.

-Xgcpolicy takes the values optthruput (the default), optavgpause, or subpool. The option controls garbage collector behavior, making tradeoffs between throughput of the application and overall system and the pause times that are caused by garbage collection.

The format of the option and its values is:

-Xgcpolicy:optthruput

-Xgcpolicy:optavgpause

-Xgcpolicy:subpool

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, 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 might provide additional throughput optimization because it can improve the efficiency of object allocation by reducing lock contention on large SMP systems.

Pause time reduction

The optavgpause option substantially reduces the time that is spent in these garbage collection pauses, in addition to limiting the effect of increasing heap size on the length of the garbage collection pause. This option is particularly relevant to configurations that have large heaps. (Consider a heap as large when it is at least 1 GB.) The pause times are reduced by performing some garbage collection activities that are concurrent with normal program execution. With the reduced pause time, you might experience some reduction of application throughput, which varies from application to application.

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 OutofMemory exception, which results in JVM termination if the exception is not caught and handled. At this point the JVM will produce two diagnostic files: a Heapdump and a Javadump. These are detailed in the Diagnostics Guide for Java v1.4.2 and can be used to determine what caused the high occupancy of the Java heap. The Diagnostics Guide is on developerWorks, at: http://www-106.ibm.com/developerworks/java/jdk/diagnosis/. 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.

Further information about garbage collection

For more detailed information about garbage collection, see:

http://www.ibm.com/developerworks/ibm/library/i-garbage1/

http://www.ibm.com/developerworks/ibm/library/i-garbage2/

http://www.ibm.com/developerworks/ibm/library/i-garbage3/

Dynamic Logical Partitioning (DLPAR) Support

When the SDK runs in an AIX v5.2 or later logical partition (LPAR), you can move partition resources from one AIX v5.2 or later partition to another without requiring a reboot of the system of the affected partitions. Note that if you decrease the number of CPUs or real memory allocated to an LPAR, the performance of SDK applications might degrade.

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

  • You are running in a LPAR
  • The LPAR has 1 CPU
  • The LPAR will never be dynamically reconfigured to add more CPUs while SDK applications are running.

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.

Working with applets

Running applets with the Applet Viewer

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.

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

   appletviewer name

where name is one of the following:

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

For example, to invoke the Applet Viewer on an HTML file that calls an applet, type at a 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 attribute of the <META> tag. If the file that appletviewer 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 the debugger and its API at the Sun Web site: http://java.sun.com.


Java Plug-in/Appletviewer

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

To work around this problem, ensure that:

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

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/java14/jre/bin/libjavaplugin_oji.so
|		/usr/mozilla/base/plugins/libjavaplugin_oji.so

or:

|
ln -s /usr/java14/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.4 and backward-compatible newer versions |shipped as an option of the AIX operating system.

|

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.

| |
Visual Age C/C++ compiler object model
|

The Mozilla Java Plug-in is compiled with the Visual Age compiler compat |object model -qobjmodel=compat. Only versions of Mozilla that |were compiled with the same compiler object model work with the Mozilla Java |Plug-in.

| |
Checking the compile option with which Mozilla was compiled
|

To find out the compiler object model with which your Mozilla has been |compiled, type about:buildconfig in the URL field of Mozilla. If |Mozilla was compiled with the ibm object model, the text -qobjmodel=ibm will appear in the "Compiler Flags" section of the build configuration |options; if Mozilla was compiled with the compat object model, the "Compiler |Flags" section will not display any objmodel information..

Java Plug-in for AIX Communicator V4

|To use the Java Plug-in, ensure that the following link exists:

|
 ln -s /usr/java14/jre/bin/javaplugin.so
|	  /usr/netscape/communicator/plugins/javaplugin.so

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

To work around problems that you might have with Netscape's version of the C runtime (libc.a), any LIBPATH entries that contain "netscape/communicator" are ignored in the LIBPATH that is passed to the Plug-in's JVM. The Plug-in's JVM should load the system C runtime (/lib/libc.a) only. The side effect of this is that LIBPATH dependent JVM calls (such as System.loadLibrary()) return an UnsatisifiedLinkError exception if you attempt to load a shared library from a "netscape/communicator" path from within the Plug-in.

This Java Plug-in supports Netscape 4.8 and will not load with earlier versions of the Netscape browser that shipped with the AIX operating system.

Note that you can have only one Java Plug-in shared library in the directory /usr/netscape/communicator/plugins for Netscape 4. Netscape 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/java14/jre/bin/JavaPluginControlPanel

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 use instead a Runtime Environment for running applets or beans in the browser.

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

Supported browsers

Table 1. Browsers supported by the Java Plug-in
Operating System Supported Browsers
AIX V5.1
Netscape 4.8 on the AIX V5.1 Expansion Pack, and latest updates available from http://www.ibm.com/servers/aix/browsers/
Mozilla 1.4, available at  http://www.ibm.com/servers/aix/browsers/ and the Mozilla for AIX CD.
AIX V5.2
Netscape 4.8 on the AIX V5.2 Expansion Pack,  and latest updates available from http://www.ibm.com/servers/aix/browsers/

Mozilla 1.4, available at http://www.ibm.com/servers/aix/browsers/ and the Mozilla for AIX CD.
|AIX v5.3 |Mozilla 1.4, available at http://www.ibm.com/servers/aix/browsers/ and the Mozilla for AIX CD.
Notes:
  1. Netscape 4 can fail if you click the Back button while a v1.4.2 applet is running through the Plug-in (a problem not unique to the Java Plug-in).
  2. The <APPLET> tag does not invoke the Plug-in on Netscape 4. In Mozilla, the <APPLET>, <OBJECT>, and <EMBED> tags invoke the Plug-in. In Netscape 4, only <OBJECT> and <EMBED> invoke the Plug-in.
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.

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

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

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

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

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

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

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

For more information about the Java Plug-in HTML Converter, see the Sun Web site: http://java.sun.com/products/plugin/1.3/features.html

The StringTokenizer class

Consider the following string of tokens:

opcode:attributeName:attributeValue\t

In Version 1.2.2, you set the delimiter to ":", and through the nextToken() method of StringTokenizer obtain the token's "opcode" and "attributeName". Then the delimiter is changed to "\t", and token "attributeValue" is returned with StringTokenizer.nextToken().

In Version 1.3 and 1.4, if the delimiter is changed midway through tokenizing, the next token starts with the old delimiter. The token returned is ":attributeValue". Your application must check to see whether the next token is prepended with the previous delimiter when the delimiter has been changed, and remove it if it is.

Using the IPv6 extensions

The IBM 32-bit SDK for AIX, v1.4 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.

However, all levels of AIX v5.1 currently do not support IPv4-mapped Multicast addresses. If you are using an IPv4 Multicast address, you cannot join a Multicast group whether or not you are switching your application to IPv6. You must change the default of your application by setting the java.net.preferIPv4Stack to true:

java -Djava.net.preferIPv4Stack=true <classname>

where <classname> is the file name of your .class file.

| | |

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.

CORBA support

The Java 2 Platform, Standard Edition (J2SE) supports, at a minimum, the specifications that are defined in the Official Specifications for CORBA support in J2SE V1.4 at http://java.sun.com/j2se/1.4.2/docs/api/org/omg/CORBA/doc-files/compliance.html. 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 1.4.2. Programs that need to register a service in the current version must invoke this method on the IBM internal ORB implementation class. For example, to register a service "MyService":

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

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

System properties for tracing the ORB

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

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

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

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

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

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

System properties for tuning the ORB

The following properties help you to tune the ORB:

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

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

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

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

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

    By default, the ORB waits indefinitely for a response. Do not set the timeout too low, or connections might be ended unnecessarily.

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

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

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

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

Java 2 security permissions for the ORB

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

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

init

java.net.SocketPermission resolve

org.omg.CORBA.ORB

connect

java.net.SocketPermission listen

org.omg.CORBA.ORB

resolve_initial_references

java.net.SocketPermission connect

org.omg.CORBA.
portable.ObjectImpl

_is_a

java.net.SocketPermission connect

org.omg.CORBA.
portable.ObjectImpl

_non_existent

java.net.SocketPermission connect

org.omg.CORBA.
portable.ObjectImpl

OutputStream _request (String, boolean)

java.net.SocketPermission connect

org.omg.CORBA.
portable.ObjectImpl

_get_interface_def

java.net.SocketPermission connect

org.omg.CORBA.
Request

invoke

java.net.SocketPermission connect

org.omg.CORBA.
Request

send_deferred

java.net.SocketPermission connect

org.omg.CORBA.
Request

send_oneway

java.net.SocketPermission connect

javax.rmi.
PortableRemoteObject

narrow

java.net.SocketPermission connect

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

ORB implementation classes

The ORB implementation classes in this release are:

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

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

RMI over IIOP

Java Remote Method Invocation (RMI) provides a simple mechanism to do 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.

For information about IBM and RMI-IIOP, see this IBM Web site:

http://www.ibm.com/developerworks/java/rmi-iiop

The following documentation is available:

  • The RMI-IIOP Programmer's Guide is an introduction to writing RMI-IIOP programs. The guide is installed when you install this documentation. You can also find the guide on the Web site above under Supporting documentation (on the right-hand side).
  • The demo directory (in /usr/java14/) contains:
    • A "Hello World" example that can switch between the Java Remote Method Protocol (JRMP) and IIOP protocols (demo/rmi-iiop/hello)
    • A "Hello World" example that interacts with a standard IDL program (demo/rmi-iiop/idl)
  • The Java Language to IDL Mapping document is a detailed technical specification of RMI-IIOP and can be found at:

http://www.omg.org/cgi-bin/doc?ptc/00-01-06.pdf

AIX native threads

Java runs with system contention scope threads (AIXTHREAD_SCOPE=S). Among other things, this way of running means that a Java thread is mapped one-to-one to each AIX kernel thread and that these 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.

For more details on AIX thread scheduling, see:

http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/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 512KB. A smaller setting allows for a larger number of threads. For example:

java -Xss<size> <other params>

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

ulimit -n 3000

or chuser; for example:

chuser nofiles=3000 <user_id>

to increase the limit. (ulimit -a shows the current limit.)

AIX Large Address-Space Model support

The IBM 32-bit SDK for AIX, v1.4 supports AIX's Large Address-Space model. For more details on the large program model, see:

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

in the AIX General Programming Concepts: Writing and Debugging Programs, which provides information about using the large address-space model to accommodate programs requiring data areas that are larger than conventional segmentation can handle.

For a further description of the way that 32-bit Java allocates its heap in AIX, an explanation of how to distinguish between various memory areas of a Java process under AIX, and how to tweak their sizes, see:

http://www-106.ibm.com/developerworks/eserver/articles/aix4java1.html

By default, Java reserves eight data segments (MAXDATA=0x80000000); this is the maximum number of data segments that is allowed; each segment is 256 MB. You can see this by running dump -o on the java executable. Here is a picture of Java's default virtual memory model:

Table 3. Java's default virtual memory model
Segment Contents
0 AIX kernel
1 Java program
2 Primordial Stack (main program stack)
3 Data (r/w)
4 Data (r/w)
5 Data (r/w)
6 Data (r/w)
7 Data (r/w)
8 Data (r/w)
9 Data (r/w)
10 Data (r/w)
11 mmap/shmat
12 mmap/shmat
13 Shared library code
14 mmap/shmat
15 Shared library data

Segments 3 through 10 are used for storing, among other things, the Java heap, thread stack frames, and JIT buffers. You can monitor Java's use of these segments with the svmon command: svmon -P <java_process_id> -m -i <interval>. See

http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/cmds/aixcmds5/svmon.htm#HDRC013820260JOY

for more information about svmon.

Java uses mmap to allocate heaps that are larger than 1 GB. Because only two segments are available for mmap with Java's default memory model (segment 14 cannot be used because the heap must be contiguous), you must change Java's default memory model to make more segments available for mmap. You do this by exporting the LDR_CNTRL environment variable:

export LDR_CNTRL=MAXDATA=0xn0000000

where n is the number of data segments that will be allocated to the process. For example, if you set LDR_CNTRL=MAXDATA=0x30000000, Java's memory model will look as follows:

Table 4. Java's virtual memory model after setting MAXDATA
Segment Contents
0 AIX kernel
1 Java program
2 Primordial Stack (main program stack)
3 Data (r/w)
4 Data (r/w)
5 Data (r/w)
6 mmap/shmat
7 mmap/shmat
8 mmap/shmat
9 mmap/shmat
10 mmap/shmat
11 mmap/shmat
12 mmap/shmat
13 Shared library code
14 mmap/shmat
15 Shared library data

Segments 6 through 12 are available for Java's heap. So you could specify a heap size of up to 7x256 MB or 1.75 GB. Note that you can force java to mmap its heap, regardless of heap size, by exporting the environment variable IBM_JAVA_MMAP_JAVA_HEAP=true. If you are writing a JNI program that makes extensive use of mmap/shmat, you probably need to use LDR_CNTRL to reduce MAXDATA. Specifying LDR_CNTRL=MAXDATA=0x00000000 gives interesting results:

Table 5. Java's virtual memory model after setting MAXDATA to zero
Segment Contents
0 AIX kernel
1 Java program
2 Data (r/w) + Primordial Stack (main program stack)
3 mmap/shmat
4 mmap/shmat
5 mmap/shmat
6 mmap/shmat
7 mmap/shmat
8 mmap/shmat
9 mmap/shmat
10 mmap/shmat
11 mmap/shmat
12 mmap/shmat
13 Shared library code
14 mmap/shmat
15 Shared library data

In this case, Java's data area and stack both share segment 2. Segments 3 through 12 are available for the mmap, which means that the Java heap could be as large as 2.5 GB. However, because non-object memory allocations (thread stacks or JIT buffers, for example) must now fit in less than one segment, you might see Out of Memory exceptions (depending on the execution characteristics of your program). Consequently, you are not advised to run with LDR_CNTRL=MAXDATA=0x00000000.

AIX Very Large Address-Space Model support

On AIX V5.2 and above, the SDK supports AIX's Very Large Address-Space Model. The Very Large Address-Space Model is also available on AIX V5.1, but the implementation differs. Consequently, the SDK does not support the use of the Very Large Address-Space Model on AIX V5.1.

With the very large address-space model, the SDK's Java heap can span up to 13 segments (3.25 GB). This is possible because the program's shared library code and data are loaded privately (making segments 13 and 15 available to the SDK). The SDK automatically handles the LDR_CNTRL environment variable to activate the Very Large Address-Space Model. To override the automatic setting, set the DSA keyword in the LDR_CNTRL environment variable as follows:

LDR_CNTRL=MAXDATA=0xn0000000@DSA, where n is either 0, B, C or D.

For example, with LDR_CNTRL=MAXDATA=0x00000000@DSA the memory model looks like this (each segment maps 256 MB of virtual address space):

Table 6. Memory model with LDR_CNTRL=MAXDATA=0x00000000@DSA
Segment Contents
0 AIX Kernel
1 Java program
2 Java native (C) heap and Primordial stack (main program stack)
3 mmap/shmat
4 mmap/shmat
5 mmap/shmat
6 mmap/shmat
7 mmap/shmat
8 mmap/shmat
9 mmap/shmat
10 mmap/shmat
11 mmap/shmat
12 mmap/shmat
13 mmap/shmat
14 mmap/shmat
15 mmap/shmat

In this case, the native heap is in segment 2 and segments 3 through 15 are available for the Java heap (allocated using shmat/mmap). Note that the mmap/shmat segments are allocated to start at segment 15 and grow up (toward lower numbered segments). While this configuration permits the largest possible Java heap (3.25 GB), Java's non-object memory allocations (for example, thread stacks, JIT buffers, privately loaded shared library code/data, incremental compaction buffers) must all be able to be contained in segment 2. This might result in OutofMemory exceptions when you run your application.

With LDR_CNTRL=MAXDATA=0xB0000000@DSA the memory model looks like this:

Table 7. Memory model with LDR_CNTRL=MAXDATA=0xB0000000@DSA
Segment Contents
0 AIX Kernel
1 Java program Primordial stack (main program stack)
2 Primordial stack (main program stack)
3 Java native (C) heap or mmap/shmat
4 Java native (C) heap or mmap/shmat
5 Java native (C) heap or mmap/shmat
6 Java native (C) heap or mmap/shmat
7 Java native (C) heap or mmap/shmat
8 Java native (C) heap or mmap/shmat
9 Java native (C) heap or mmap/shmat
10 Java native (C) heap or mmap/shmat
11 Java native (C) heap or mmap/shmat
12 Java native (C) heap or mmap/shmat
13 Java native (C) heap or mmap/shmat
14 mmap/shmat
15 mmap/shmat

This configuration allows you to run with a Java heap of up to 3 GB (which would be allocated in segments 4 through 15). If you specify a 3 GB heap, only one segment would be available for Java's non-object memory allocations. As mentioned in the previous example, this could result in OutofMemory exceptions. If you see these exceptions, try running with a smaller Java heap. A smaller heap leaves more space for Java's native heap (the native C heap starts in segment 3 and dynamically grows down (toward higher-numbered segments); mmap/shmat allocations return an address in the highest available segment).

For more information about the AIX V5.2 Very Large Programming Model, see the AIX V5.2 General Programming Concepts manual that is located at http://publib16.boulder.ibm.com/pseries/en_US/infocenter/base/aix52.htm. Select General Programming Concepts -> Large Program Support -> Understanding the Very Large Address-Space Model.

Default LDR_CNTRL=MAXDATA values

The setting of the LDR_CNTRL=MAXDATA environment variable value is linked to the size of the 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:

  • On AIX v5.2 or later:
    • If the heap size is 3 GB or greater, LDR_CNTRL=MAXDATA=0@DSA is set.
    • If the heap size is between 2.3 GB and 3 GB, LDR_CNTR=MAXDATA=0XB0000000@DSA is set
    • If the heap size is less than 2.3GB, LDR_CNTR=MAXDATA=0XA0000000@DSA is set
  • On AIX v5.1:
    • If the heap size is greater than 1 GB, LDR_CNTRL=MAXDATA is set to an appropriate value. Note that this is an inverse relationship because as the the heap size increases, fewer segments are reserved through the LD_CNTRL=MAXDATA value. For example for a 1 GB heap LDR_CNTRL=MAXDATA is set to 0X60000000, while for a 1.5 GB heap, the LDR_CNTRL=MAXDATA value is 0X40000000.
    • If the heap sizes is smaller than 1 GB, LDR_CNTRL=MAXDATA is set to 0X80000000.
    .

JNI compatibility

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

  • export AIXTHREAD_SCOPE=S
  • export AIXTHREAD_MUTEX_DEBUG=OFF
  • export AIXTHREAD_RWLOCK_DEBUG=OFF
  • export AIXTHREAD_COND_DEBUG=OFF

The C/C++ compiler on AIX V5.1 is installed in /usr/vacpp. Because of incompatibility between the IBM 32-bit SDK for AIX, v1.4 and some system-defined types, compilation of JNI code requires that the compiler uses the flag _AIX43. This flag is defined by default in /etc/vacpp.cfg on AIX V5.1. Ensure that you are building while in the correct SDK environment.

You must build:

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

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

You are recommended to compile your native methods (C/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/java14/include -o libnm.a nm.c
|The -qmkshrobj option disables runtime |linking. For more details about shared object files, runtime linking, and |the use of cc and ld command-line options, see Developing and Porting C and C++ Applications on AIX at http://www.redbooks.ibm.com/abstracts/sg245674.html, the C and C++ compiler |documentation Web site at http://www.ibm.com/software/awdtools/xlcpp/library., and the AIX online documentation at http://www16.boulder.ibm.com/pseries/en_US/infocenter/base/aix.htm.

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

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

  • -L option to add /usr/lib and /lib to the list of directories that are searched for shared objects. All programs need shared objects stored in these directories.
  • -L option to add /usr/java14/jre/bin/classic and /usr/java14/jre/bin to the list of directories that are searched for shared objects. These directories contain the Java SDK shared libraries. You will also want to link with libjvm.a (using the -ljvm option).
  • -bM:UR option to tell AIX to save all general-purpose user registers across system calls that are made by an application. This option is required to ensure correct operation of Java's garbage collector. Note that this option can be used only for C/C++ programs that have a main executable. It must NOT be used to build shared objects. (It could introduce errors if used to build a shared object.)

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/java14/include 
-o invAPITest 
-bM:UR 
-L/usr/lib 
-L/lib 
-L/usr/java14/jre/bin/classic 
-L/usr/java14/jre/bin 
-ljvm invAPITest.c

When executing a C/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/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

AIX sets default value of the AIXTHREAD_MUTEX_DEBUG, AIXTHREAD_RWLOCK_DEBUG and AIX_THREAD_COND_DEBUG environment variables ON. A JNI program that creates and attaches to a JVM must set these environment variables OFF. See http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixbman/prftungd/2365a81.htm#HDRI34490 (for AIX 5.1).

Note: The old-style native interface is no longer supported.

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

|Java v1.4.2 allows you to store native methods in either |AIX shared objects or AIX shared libraries:

|
|
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. (They can also be named <libname>.a to allow the linker |to search for them with the -lname option, even though |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 linked statically. A shared library |has the name in the form <libname.a>. This 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()). The SDK handles AIX shared |objects and AIX new-style shared objects.

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

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 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, the signal is ignored (whether or not this is not the signal's default action).

For exception and error signals the JVM either:

  • Handles the condition and recovers (when the exception is caused by your application code), or
  • Enters a controlled shutdown sequence where it:
    1. Calls your application's signal handler for that signal
    2. Outputs a Javadump, to describe the JVM state at the point of failure
    3. Performs the necessary cleanup to give a clean shutdown

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

  • Calls your application's signal handler for that signal
  • Performs the necessary JVM cleanup

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

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

Signals used by the JVM

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

  • Exceptions: The operating system synchronously raises an appropriate exception signal whenever a fatal condition occurs.
  • Errors: The JVM raises a SIGABRT if it detects a condition from which it cannot recover.
  • Interrupts: Interrupt signals are raised asynchronously, from outside a JVM process, to request shutdown.
  • Controls: Other signals that are used by the JVM for control purposes.
Table 8. Signals used by the JVM
Signal Name Signal type Description Disabled by -Xrs
SIGSEGV Exception Incorrect access to memory (write to inaccessible memory) No
SIGILL Exception Illegal instruction (attempt to invoke an unknown machine instruction) No
SIGFPE Exception Floating point exception (divide by zero) No
SIGBUS Exception Bus error (attempt to address nonexistent memory location) Yes
SIGSYS Exception Bad system call issued Yes
SIGXCPU Exception CPU time limit exceeded (you have been running too long) Yes
SIGXFSZ Exception File size limit exceeded Yes
SIGEMT Exception EMT instruction (AIX specific) Yes
SIGABRT Error Abnormal termination. The JVM raises this signal whenever it detects a JVM fault. Yes
SIGINT Interrupt Interactive attention (CTRL-C). JVM exits normally. Yes
SIGTERM Interrupt Termination request. JVM will exit normally. Yes
SIGHUP Interrupt Hang up. JVM exits normally. Yes
SIGQUIT Control A quit signal for a terminal. JVM uses this for taking Javadumps. Yes
SIGTRAP Control Internal for use by DBX or ptrace. Used by some JVMs for internal control purposes. No
SIGPIPE Control A write to a pipe that is not being read. JVM ignores this. No
No Name (40)   An AIX reserved signal. Used by the AIX JVM for internal control purposes. 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 at http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/java.html.

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 40, you impact JVM performance because these signals are used for internal control purposes.

Signals 1 (SIGHUP), 2 (SIGINT), 4 (SIGILL), 6 (SIGABRT), 7 (SIGEMT), 8 (SIGFPE), 10 (SIGBUS), 11 (SIGSEGV), 12 (SIGSYS), 15 (SIGTERM), 24 (SIGXCPU) , and 25 (SIGXFSZ) cause the JVM to shut down; therefore, an application signal handler must not attempt to recover from these unless it no longer requires the services of the JVM.

Linking a native code driver to the signal-chaining library

The Runtime Environment contains a signal-chaining facility. 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 link libjsig with an application, in this case invAPITest, that uses the JNI Invocation API to create a JVM:

cc_r  -qarch=ppc  -I/usr/java14/include 
  -o invAPITest 
  -bM:UR 
  -L/usr/lib 
  -L/lib 
  -L/usr/java14/jre/bin/classic 
  -L/usr/java14/jre/bin 
  -ljsig
  -ljvm invAPITest.c

To link libjsig when you are creating a shared library of native methods (held in the file nm.c):

cc_r  -qmkshrobj -qarch=ppc  -I /usr/java14/include -L 
/usr/java14/jre/bin -ljsig -o libnm.a nm.c

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

  • SA_RESTART - This is always set.

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

Using Web Start

Java Web Start is a way of deploying Java technology-based applications. It connects the computer and the Internet and allows the user to launch and manage applications directly from the Web. Java Web Start provides one-click activation of applications, and ensures that you are always running the latest version, eliminating installation or upgrade procedures. Often, distributing software across the Web requires you to find the installer on the Web, download the installer, locate the installer, and execute the installer. After the installer is executed, it prompts for installation directories and installation options such as full, typical, or minimum. This can be a time-consuming and complicated task that must be repeated for each new version of the software.

In contrast, Web-deployed applications, such as your HTML-based e-mail client and calendar, are straightforward to install and use. The Web browser has automated the process. There are no complicated download, setup, and configuration steps, and you are guaranteed to be running the latest version. Java Web Start provides the same benefits to full-featured applications.

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

For more information about Web Start, see: http://java.sun.com/products/javawebstart and for more documentation, see: http://java.sun.com/j2se/1.4.2/docs/guide/jws/index.html.

Installing Web Start

The Web Start installation script is /usr/java14/jre/bin/webstart_install_sdk.sh. To install Web Start, run the script. The installation process creates a subdirectory called javaws in your current working directory.

The installation process also updates the mime-types that are used by Mozilla and other browsers.

The Web Start installation script is installed with the JRE for Java v1.4.2.

You can invoke Web Start in three ways:

  1. Select a link on a Web page that is a reference to a .jnlp file.
  2. Start javaws from the javaws directory that was created above, therefore starting the Web Start dialog from which applications can be selected.
  3. At a shell script, type javaws <URL>, where <URL> is the location of a .jnlp file.

All these actions cause Web Start to start the selected application. The application is downloaded if this is the first time it is being used. On later invocations, the original Web site is checked to see whether any updates are available. Web Start downloads these updates before the application is started.

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

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, Denmark, or Sweden locales and want to use the Euro, specify -Duser.variant=EURO on the Java command line.

| | |

Support |for new locales

|

The IBM 32-bit SDK for AIX, v1.4 supports the following new locales:

|
    |
  • Bengali (bn_IN)
  • |
  • Kannada (kn_IN)
  • |
  • Malayalam (ml_IN)
  • |
  • Oriya (or_IN)
  • |
  • Punjabi (pa_IN)

The fonts from these locales do not work on AWT |components.

Enhanced BiDirectional support

The IBM SDK includes enhanced BiDirectional support. For more information, see http://www-106.ibm.com/developerworks/java/jdk/bidirectional/index.html.

Enhanced BigDecimal

The SDK includes an enhanced BigDecimal class (com.ibm.math.BigDecimal) for Java programming. It is provided (with its supporting class MathContext) as an alternative to the java.math.BigDecimal class.

If you are using the java.math.BigDecimal class in a Java program, and you want to access the enhanced BigDecimal class, you must change the import statement in your source code as shown:

Change import java.math.*; to import com.ibm.math.*;

You do not need to change any other code.

JNDI

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

  • Lightweight Directory Access Protocol (LDAP)
  • Corba Object Services (COS) Naming Service
  • RMI Registry
  • filesystem
  • Domain Name Service (DNS)

HPROF Performance Profiler and JVMPI

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

GetCurrentThreadCpuTime

To enable the JVMPI function GetCurrentThreadCPUTime, switch on AIX resource collection by setting the environment variable AIXTHREAD_ENRUSG:

export AIXTHREAD_ENRUSG=ON

When performance profiling is switched on, you see the message:

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

Disable the resource collection after your profiling session because the overhead for tracking cpu time for individual threads will affect performance. Do not enable resource collection in a production environment. To disable the resource collection either:

unset AIXTHREAD_ENRUSG

or:

export AIXTHREAD_ENRUSG=OFF

The default for the Java environment is AIXTHREAD_ENRUSG=OFF.

When the resource collection is enabled, the HPROF profiling agent that is 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, v1.4. It might be added in a future release.

Debugging environment

In the event of a core dump in your application when using the IBM SDK, you get a javacore text file in addition to the core file. The javacore file has a filename of the format of javacore<process id>.<time>.txt. The <time> is the return value from the time subroutine at the time of the core dump, so each javacore file is not overwritten as for core file.

You can determine the location of the javacore file as follows:

  1. If the environment variable IBM_JAVACOREDIR refers to a writable directory, the javacore file is written to that directory.
  2. Otherwise, if the current working directory is writable, the javacore file is written there.
  3. Otherwise, if the environment variable TMPDIR refers to a writable directory, the javacore file is written to that directory.
  4. Otherwise, the javacore file is written to the "/tmp" directory.

The location of the javacore file is written to standard error as a full pathname and is also appended, with a date/time stamp to the file "/tmp/javacore_locations". Basic file locking is used to avoid buried updates of this file.

If the javacore cannot be opened for some reason, the information is written to standard error.

The javacore file provides information of the java program at the time of the core dump. To study JNI native code, you still need to use the core file.

To debug java programs, you can use JPDA or JDB. For native JNI binary programs, you can still use DBX for debugging. Before you start working with DBX, you must set the $java variable. To set the $java variable, start DBX and use the dbx set subcommand. Setting this variable causes DBX to ignore the non-breakpoint traps generated by the JIT. You can also use a pre-edited command file by launching DBX with the -c option to specify the command file:

dbx -c .dbxinit

The default DBX command file is .dbxinit. Note that the $java variable was added to DBX with bos.adt.debug 5.1.0.50.

For more information about JPDA and JDB and their usage, see:

JPDA

The Java Platform Debugger Architecture (JPDA) is supported in this release. The JPDA classes are shipped in tools.jar, which you must include when developing any java programs that intend to use JPDA. The JPDA can be used only with the JIT disabled. Only socket communication is supported on AIX.

JDB

As in Versions 1.3.0 and 1.3.1 of the SDK, the JDB debugger starts up com.sun.tools.example.debug.tty.TTY. This version fully supports the Java Virtual Machine Debugging Interface (JVMDI).

JDB uses the JPDA and allows the jdb example tool to attach to a listening Virtual Machine (VM) or to start a new debug session. It is invoked by the jdb command.

The JDB can debug remote java applications, including java applications that are running on remote machines over a TCP/IP link. To debug a remote java program, the java program should start as follows:

java -Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,
suspend=y -Djava.compiler=NONE <other args> <myapp> <myapp class args>

Specify the port number by the "address" sub-option.

The port on which the JPDA is listening is displayed. At the remote debugging machine, enter:

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

When launching a debug session by using the dt_socket transport, ensure that the specified ports are free to use.

Note: Sun's documentation for using JDB assumes that the JVM to be debugged is a HotSpot JVM. However, IBM implementations of the JVM always run as a Classic JVM. So, when using IBM's JDB, always assume that the -classic option has been implicitly specified and follow the guidance for debugging a Classic JVM. This requires that the -Xnoagent option is specified unless the agent class is required, in which case specify the -Xbootclasspath option to locate it explicitly.

| | |

DBX Plug-in for the SDK

|

The IBM SDK, v1.4.2 includes a Plug-in for the AIX DBX debugger that gives |DBX users enhanced features when working on Java processes or core files |generated by Java processes.

|

The Plug-in requires a version of DBX that supports the Plug-in interface. |Use the DBX command pluginload to find out whether |your version of DBX has this support. AIX v5.3 includes this support. AIX |v5.2 includes this support in Recommended Maintenance Package 5200-03.

|

To enable the Plug-in, use the DBX command pluginload:

|
pluginload /usr/java14/jre/bin/libdbx_java.so

You |can also set up the DBX_PLUGIN_PATH environment variable | to point to the /usr/java14/jre/bin directory. DBX now loads automatically |any Plug-ins found in the directory pointed to by this environment variable. | After the Plug-in is loaded, you can use it with the commands that are |listed by:

|
plugin java help

from the DBX prompt.

|

You can also use DBX to debug your native JNI code by specifying the full |path to the java program as follows:

|
dbx /usr/java14/jre/bin/java

|

Under DBX, issue the command:

|
(dbx) run <MyAppClass>
|

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

|

Before you start working with DBX, you must set the $java variable. To |set the $java variable, start DBX and use the dbx set subcommand. |Setting this variable causes DBX to ignore the non-breakpoint traps generated |by the JIT. You can also use a pre-edited command file by launching DBX with |the -c option to specify the command file:

|
dbx -c .dbxinit

where .dbxinit is the default command file.

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 Java14.ext.commapi fileset (optionally installable) and supports 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/.

JavaHelp

This release includes JavaHelp 1.1.2. The fileset, Java14.ext.javahelp, is optionally installable. For more information, see the Readme in /usr/java14/javahelp (after installing the fileset) and http://www.javasoft.com/products/javahelp/.

Java security

For information about Java security, see the Java Security User Guide for AIX 32-bit Version for POWER.

Java 3D for AIX

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

Transforming XML documents

The IBM SDK contains the XSLT4J 2.6 processor and the XML4J 4.3 parser that conform to the JAXP 1.2 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 XSLT4J 2.6 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 stylesheet. This approach separates the interpretation of stylesheet instructions from their runtime application to XML data.

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

  • Change the entry in the jaxp.properties file (located in /usr/java14/jre/lib), or
  • Set the system property for the javax.xml.transform.TransformerFactory key to org.apache.xalan.xsltc.trax.TransformerFactoryImpl.

To implement properties in the jaxp.properties file, copy jaxp.properties.sample to jaxp.properties in /usr/java14/. 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 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. |
  3. Check the value of the property org.apache.xalan.xsltc.dom.XSLTCDTMManager |in the file /usr/java14//lib/xalan.properties.
  4. |
  5. Check the contents of the file META-INF/services/org.apache.xalan.xsltc.dom.XSLTCDTMManager |for a class name.
  6. |
  7. 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 only 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 or Xalan in the endorsed override, |you might get a null pointer exception when you start up your application. |This exception occurs because these older versions do not handle the jaxp.properties |file correctly.

|

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

|
    |
  • Upgrade to a newer version of the application that implements the latest |Java API for XML Programming (JAXP) specification (http://java.sun.com/xml/jaxp/index.html).
  • |
  • Remove the jaxp.properties file from /usr/java14/jre/lib.
  • |
  • Uncomment the entries in the jaxp.properties file in /usr/java14/jre/lib.
  • |
  • Explicitly set the SAX Parser, DocumentBuilder, or Transformer factory |using the IBM_JAVA_OPTIONS environment variable. For |example: |
    set IBM_JAVA_OPTIONS=-Djavax.xml.parsers.SAXParserFactory=org.
    |			apache.xerces.jaxp.SAXParserFactoryImpl 
    or |
    set IBM_JAVA_OPTIONS=-Djavax.xml.parsers.DocumentBuilderFactory=org.
    |			apache.xerces.jaxp.DocumentBuilderFactoryImpl
    or |
    set IBM_JAVA_OPTIONS=-Djavax.xml.transform.TransformerFactory=org.
    |			apache.xalan.processor.TransformerFactoryImpl  
  • |
  • Set the system property for javax.xml.parsers.SAXParserFactory, javax.xml.parsers.DocumentBuilderFactory, |or javax.xml.transform.TransformerFactory from within your application's code. |For an example, see the JAXP 1.2 specification.

Shipping Java applications

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

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

Your application can either pre-req the AIX SDK or ship with a AIX Runtime Environment. Note that the AIX SDK license does not allow you to redistribute any of the SDK's files with your application. You can redistribute the AIX Runtime Environment with your application. The AIX Runtime Environment is available from the AIX Java Web site: http://www.ibm.com/developerworks/java/jdk/aix). Click on the Download link on the right-hand side of the page and follow the links to the Java 1.4 download page.

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 Component Keystroke Assignments" at http://java.sun.com/j2se/1.4/docs/api/javax/swing/doc-files/Key-Index.html

iKeyman accessibility

The iKeyman tool has a GUI only; however, the IBM 32-bit SDK for AIX, v1.4 provides the command-line tool IKEYCMD, which has the same functions that iKeyman 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)
-version
Displays version information for IKEYCMD
<action>
The specific action that is to be taken on the object. This action is one of the following:
-cert
Actions that are to be taken on a certificate
-certreq
Actions that are to be taken on a certificate request
-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.
-help
Displays help for the IKEYCMD invocations.
Note:
The object and action keywords are positional and 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.

Large Swing menu accessibility

If you have a Swing JMenu that has more entries than can be displayed on the screen, you can navigate through the menu items by using the down or up arrow keys.

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

The IBM Java Web Start application can be used in three modes:

  • With links to .jnlp files on html pages in your browser
  • With the Java Web Start Application Manager
  • With the command javaws/opt/IBMJava2-142/jre/javaws/javaws

Most Web Start use is from Web sites that contain .jnlp files, and is therefore accessible.

IBM Java Webstart v1.4.2 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 the file with an accessible editor. Note that not all the preferences that can be set in the Web Start Application Manager can be set from the configuration file.

| | |

Known problems and limitations

| |

Length of the user and group names

|

AIX v5.3 supports long user and group names (up to 256 characters, including |the terminating NULL). The IBM SDK v1.4.2 supports user names of up to 8 |characters only. If you try to run the JVM or the appletviewer with a user |name that is longer than 8 characters, it will fail. This limitation will |be fixed in a future release of the SDK.

|

Before running the java or appletviewer commands, ensure that you are logged in with a user name of up to 8 |characters.

| |

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.

|

Printing of Java applets when run using the Netscape plug-in is not supported. |Use the applet viewer for printing.

| |

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.

| |

Japanese Input Method

|

On AIX V5.1, use the short locale name for Japanese UTF-8, LANG=JA_JP, instead of LANG=JA_JP.UTF-8.

|

For the specified font limitation for the TextArea or TextField component, |the IM status might not be displayed completely on the IM status area which |is at the bottom of the window. For AIX IM, you might see the whole IM status |string if you resize that window, but this function is not effective for Wnn6 |andWnn7.

|

If you are using Wnn7, you need jkit.Wnn7.base 2.3.0.4 (APAR IY34699, PTF |U484621) or later. When you are using Yosoku-kouho (predict conversion) on |a TextArea or TextField component, complete Kana-Kanji conversion before changing |the window focus. If the changed window's IM is activated, the Yosoku-kouho |window might not work properly.

|

|If you are using Wnn7 prediction input, when you press the |Tab key (or Ctrl + Tab), component focus change and Wnn7 prediction selection |happen at the same time. To avoid this problem, change the Wnn7 keybind configuration |using the Wnn7 configuration panel.|

|

When you are using Wnn6 or Wnn7, you may not turn off Root IM window. If |you see this situation, select Restart on xwnmo's system |menu. For Wnn7, you must change the window focus to another window and the |focus should be backed to an input window.

|

|When using an Input Method, to avoid unexpected behaviors, |commit preedited strings before changing focus.|

| | |

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.

| | |

Creating a JVM

|
    |
  • |Native programs cannot create a 1.1 JVM. You |cannot call JNI_CreateJavaVM() and pass it a version of JNI_VERSION_1_1(0x00010001). |The versions that can be passed are: |
      |
    • JNI_VERSION_1_2(0x00010002)
    • |
    • JNI_VERSION_1_4(0x00010004)
    |

    The JVM created in every case is the one specified by the libraries |(that is, 1.2.2, 1.3.x, 1.4.x), not the one that is implied by the JNI interface. |The interface API does not affect the language specification that is implemented |by the JVM, the class library APIs, or any other area of JVM behavior. The |interface API specifies only how native code can invoke the required behavior.

| |

Stopping an applet while using Netscape 4

|

Stopping an applet running with the Java Plug-in by using Back or Go->Back on Netscape 4 might cause the |browser to fail. The workaround is to use Mozilla instead, because Mozilla |does not have this problem.

| | |

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.

| | |

Any comments on this User Guide?

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

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

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

Notices

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Trademarks

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

  Contents
AIX overview
AIX FAQs
Download and service information
Security
Diagnosis documentation

 
    About IBM Privacy Contact