Date: 2004-09-01

# IBM SDK for Linux platforms, Java 2 Technology Edition, Version 1.4.2, Service Refresh 1

# 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 these platforms as they become available:

- IBM 32-bit SDK for Linux on Intel(TM) architecture, Java 2 Technology Edition, Version 1.4.2, Service Refresh 1
- IBM 64-bit SDK for Linux on Intel architecture, Java 2 Technology Edition, Version 1.4.2, Service Refresh 1
- IBM 32-bit SDK for Linux on iSeries(TM) and pSeries(R), Java 2 Technology Edition, Version 1.4.2, Service Refresh 1
- IBM 64-bit SDK for Linux on iSeries and pSeries, Java 2 Technology Edition, Version 1.4.2, Service Refresh 1
- IBM 31-bit SDK for Linux on zSeries(R), Java 2 Technology Edition, Version 1.4.2, Service Refresh 1
- IBM 64-bit SDK for Linux on zSeries, Java 2 Technology Edition, Version 1.4.2, Service Refresh 1

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

This User Guide describes the IBM(R) SDK (Software Developer Kit) for all Linux platforms. Platform-specific information is clearly marked as such. Ensure that you are reading material relevant to your platform. In particular, Web Start and the Plug-in are specific to the 32-bit SDK for Linux on Intel architecture.

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

Read this User Guide if you want to use the SDK to write Sun Microsystems Java applications and applets. The User Guide provides general information about the SDK and specific information about any differences in the IBM(R) implementation of the SDK. Read this User Guide in conjunction with the more extensive documentation on the Sun Web site: http://java.sun.com.

The IBM JVM Diagnostics Guide provides more detailed information about the IBM JVM.

For the list of distributions against which the SDK for Linux has been tested, see: http://www-106.ibm.com/developerworks/java/jdk/linux/tested.html

Note that the Runtime Environment for Linux is a subset of the SDK and enables you only to run Java applications. If you have installed the SDK, the Runtime Environment is included.

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

Technical changes made to this User Guide for Version 1.4.2 and for Version 1.4.2, Service Refresh 1, 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.

# Contents

Copyright information
Preface
Overview
| |
Conventions
Version compatibility
Upgrading to v1.4.2
| |
Information for Linux PPC64 users
Contents of the SDK
Runtime Environment
SDK tools
Tools not included in the IBM SDK
Configuring the SDK for Linux
Uninstalling the SDK for Linux
Uninstalling the installable Red Hat Package Manager (RPM) package
Uninstalling the compressed Tape Archive (TAR) package
Using the SDK
Obtaining the IBM build and version number
The just-in-time (JIT) compiler
PATH considerations
CLASSPATH considerations
| |
Determining whether your application is running on a 32-bit or 64-bit JVM
Debugging Java applications
Java Debugger (JDB)
Working with applets
Running applets with the Applet Viewer
Debugging applets with the Applet Viewer
Working with floating stacks
Switching the input method in DBCS languages
CORBA support
Support for GIOP 1.2
Support for Portable Interceptors
Support for Interoperable Naming Service
System properties for tracing the ORB
System properties for tuning the ORB
Java 2 security permissions for the ORB
ORB implementation classes
RMI over IIOP
| |
Implementing the Connection Handler Pool for RMI
(Linux IA 32-bit only) Using the Java Plug-in
Installing and configuring the Java Plug-in for Netscape 6 and Mozilla
Installing and configuring the Java Plug-in for Netscape 4
Common Document Object Model (DOM) support
Using the Java Plug-in with gcc3.2.x compiled Mozilla browsers
Enhanced BigDecimal
Enhanced BiDirectional support
Euro symbol support
| |
(Linux IA 32-bit and zSeries only)Support for new locales
Transforming XML documents
| |
Using an older version of Xerces or Xalan
Shipping Java applications
Service and support for independent software vendors
Accessibility
iKeyman accessibility
Large Swing menu accessibility
Keyboard traversal of JComboBox components in Swing
(Linux IA 32-bit only) Web Start accessibility
Troubleshooting
Reporting problems
Known limitations
Limitations that apply to all Linux platforms except where indicated
Linux IA 32-bit limitations
Linux PPC 32-bit and 64-bit limitations
Linux PPC 32-bit limitations
Linux zSeries 64-bit limitations
Linux zSeries 32-bit and 64-bit limitations
Notices
Trademarks

# Overview

The SDK for Linux is a development environment for writing applets and applications that conform to Sun's Java 1.4.2 Core Application Programming Interface (API).

| | |

## Conventions

|

Throughout this User Guide the default installation directory of the SDK |is referred to as /opt/IBMJava2-142/. The platforms listed below have the following |default installation directories; use the appropriate directory |for your platform when you see /opt/IBMJava2-142/:

|

|
- Linux IA 32-bit: /opt/IBMJava2-142/
|
- Linux IA 64-bit: /opt/IBMJava2-142/
|
- Linux PPC 32-bit: /opt/IBMJava2-ppc-142/
|
- Linux PPC 64-bit: /opt/IBMJava2-ppc64-142/
|
- Linux zSeries 31-bit: /opt/IBMJava2-s390-142/
|
- Linux zSeries 64-bit: /opt/IBMJava2-s390x-142/

## Version compatibility

In general, any applet or application that runs in Version 1.1.8, 1.2.2 or 1.3.1 of the SDK for Linux should run correctly in this version. Applets that depend on Sun's Java 1.4.2 APIs work only on browsers that support Java 1.4.2 APIs.

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

There is no guarantee that 1.4.2-compiled classes work on pre-1.4.0 SDK releases.

To read Sun's documentation on compatibility, search for it on the Sun Web site at http://java.sun.com.

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

| | |

## Information for Linux PPC64 users

|

Unlike PPC32, the SDK v1.4.2 is not supported on SLES 8.

## 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 /opt/IBMJava2-142/jre/bin directory. (Where /opt/IBMJava2-142/ is the directory in which you installed the SDK.)
  - 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.
    - Allows you to manage keys, certificates, and certificate requests. For more information see the Security Guide and http://www.ibm.com/developerworks/java/jdk/security. The SDK also provides a command-line version of this utility called iKeyman accessibility.
  - Dump extractor (jextract)
    - Converts a system-produced dump into a common format that can be used by jformat. For more information see the relevant chapter in the IBM JVM Diagnostics Guide that is located at: http://www.ibm.com/developerworks/java/jdk/diagnosis/index.html
  - (Linux IA 32-bit only) Java Web Start (javaws)
    - Enables the deployment and automatic maintenance of Java applications.

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 /opt/IBMJava2-142/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)
    - A dump analysis tool that allows you to analyze dumps. For more information see the relevant chapter in the IBM JVM Diagnostics Guide that is located at: http://www.ibm.com/developerworks/java/jdk/diagnosis/index.html
  - (Linux IA 32-bit only) Java Plug-in HTML Converter (HtmlConverter)
    - Converts an HTML page that contains applets to a format that can use the Java Plug-in.
- INCLUDE FILES
  - C headers for JNI programs.
- JAVA DOCUMENTATION AND DEMOS
  - The demo directory contains a number of subdirectories containing sample source code, demos, applications, and applets, that you can use.
- USER GUIDE
  - This file.
- COPYRIGHT
  - Copyright notice for the SDK for Linux software.
- LICENSE
  - The LICENSE file, /usr/swlag/<locale>/Java14.la, contains the license agreement for the SDK for Linux 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.

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

### Tools not included in the IBM SDK

The following tools are not included in the IBM SDK:

- MIF doclet
- orbd
- servertool

# Configuring the SDK for Linux

After you install the SDK for Linux, edit your shell login script and add this directory to your PATH statement:

/opt/IBMJava2-142/bin

If you installed the SDK for Linux in a different directory, replace /opt/IBMJava2-142/ with the directory in which you installed the SDK .

Note:
(For Linux IA 32-bit Chinese users only) Because of inconsistencies in the font encodings on RedHat Advanced Server, when you install for an environment in which you want Chinese to be the default language, it is better to install with a default language of English and then change to Chinese after the installation is complete. Otherwise, you might find that the Chinese fonts do not display.

# Uninstalling the SDK for Linux

The way you remove the SDK depends on whether you installed the installable Red Hat Package Manager (RPM) package or the compressed Tape Archive (TAR) package. See Uninstalling the installable Red Hat Package Manager (RPM) package or Uninstalling the compressed Tape Archive (TAR) package for instructions.

## Uninstalling the installable Red Hat Package Manager (RPM) package

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

1. At a shell script, type:

   -         rpm -e IBMJava2-SDK-1.4.2

   - For Linux PPC 32-bit:

         rpm -e IBMJava2-SDK-ppc-1.4.2

   - For Linux PPC 64-bit:

         rpm -e IBMJava2-SDK-ppc64-1.4.2

   Alternatively, you can use a graphical tool such as kpackage or yast2
2. Remove from your PATH statement the directory in which you installed the SDK .
3. (Linux IA 32-bit only) If you installed the Java Plug-in, remove the Java Plug-in files from the web browser directory.

## Uninstalling the compressed Tape Archive (TAR) package

To uninstall the SDK for Linux if you installed the compressed TAR package:

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

# Using the SDK

The Java tools are programs that are run from a shell prompt; they do not have a Graphical User Interface (GUI).

The following sections give information about using the SDK for Linux.

## Obtaining the IBM build and version number

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

`java -version`

## The just-in-time (JIT) compiler

The just-in-time (JIT) compiler (libjitc.so) dynamically generates machine code for frequently used bytecode sequences in Java applications and applets while they are running.

The SDK for Linux includes the JIT (libjitc.so), which is enabled by default. You can disable the JIT to help isolate a problem with a Java application, an applet, or the compiler itself.

To disable the JIT, at a shell prompt in the window where you will run the application, type:

        export JAVA_COMPILER=NONE

To enable the JIT, type at a shell prompt:

        export JAVA_COMPILER=jitc

To verify whether or not the JIT is enabled, type at a shell prompt:

        java -version

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

    (JIT enabled: jitc)

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

    (JIT disabled)

## PATH considerations

After installing the SDK for Linux, you can run a tool by typing its name at a shell prompt with a filename as an argument.

You can specify the path to a tool by typing the path before the name of the tool each time. For example, if the SDK for Linux software is installed in /opt/IBMJava2-142/bin, you can compile a file named myfile.java by typing the following at a shell prompt:

      /opt/IBMJava2-142/bin/javac myfile.java

To avoid typing the full path each time:

1. Add the following directories to the PATH environment variable:
   - /opt/IBMJava2-142/bin
   - /opt/IBMJava2-142/jre/bin
2. Compile the file with the javac tool. For example, compile the file myfile.java by typing the following at a shell prompt:

         javac myfile.java

   The PATH environment variable enables Linux to find executable files, such as javac, java, and javadoc, from any current directory. To display the current value of your PATH, type the following at a shell prompt:

         echo $PATH

To change the PATH environment variable:

1. Edit your shell startup file (usually .bash_profile, .profile, or .login depending on the shell) and add the absolute paths to the PATH environment variable as follows:
   - /opt/IBMJava2-142/bin
   - /opt/IBMJava2-142/jre/bin
2. Log on again or run the updated shell script to activate the new PATH setting.

## CLASSPATH considerations

The CLASSPATH tells the SDK for Linux tools, such as java, javac, and javadoc, where to find the Java class libraries. If you keep the bin and lib directories under the same parent directory level, the executable files can find the classes.

You need to set the CLASSPATH explicitly only if one of the following applies:

- You require a different library, such as one that you develop.
- You change the location of the bin and lib directories so that they no longer have the same common parent directory.
- You plan to develop or run applications that are using different runtime environments on the same system.

To display the current value of your CLASSPATH, type the following at a shell prompt:

      echo $CLASSPATH

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

If you want to run only one version of Java at a time, you can use a shell script to switch between the different runtime environments.

| | |

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

|

Some Java applications must be able to determine whether they are running |on a 32-bit JVM or on a 64-bit JVM. The system property com.ibm.vm.bitmode allows you to determine the mode in which your JVM |is running. It takes the following values:

|

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

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

|

    System.setProperty("com.ibm.vm.bitmode", "64");

Otherwise, you can set the property when you start the JVM:

|

    java -Dcom.ibm.vm.bitmode=64 MyApplication

## Debugging Java applications

To debug Java programs, you can use the Java Debugger (JDB) application. This debugger communicates with the Java Platform Debugger Architecture (JPDA) that is provided by the SDK for Linux.

Sun's documentation for using jdb assumes that the JVM that is to be debugged is a HotSpot JVM. However, IBM implementations of the Java Virtual Machine (JVM) always run as a Classic JVM. When using IBM's jdb therefore, always assume that the -classic option has been implicitly specified and follow the guidance for debugging a Classic JVM. Specify the -Xnoagent option, unless the agent class is required in which case specify the -Xbootclasspath option to locate it explicitly.

### Java Debugger (JDB)

A Java Debugger is included in the SDK for Linux. The JDB application runs the class com.sun.tools.example.debug.tty.TTY. The Java Virtual Machine Debugging Interface (JVMDI) is not supported.

The new JDB application uses the JPDA and enables 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 and can be used in the same way as the oldjdb was.

You can use the JDB application to debug remote Java applications, including Java applications that are running on remote machines over a TCP/IP link. To debug a remote Java program, start the java program as follows:

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

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

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

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

For more information on JDB and JPDA and their usage see the following Web sites:

- http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/jdb.html
- http://java.sun.com/j2se/1.4.2/docs/guide/jpda/

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

## Working with floating stacks

On a nonfloating stack Linux system, regardless of what is set for -Xss, a minimum native stack size of 256 KB for each thread is provided. On a floating stack Linux system, the -Xss values are honored. Therefore, if you are migrating from a non floating stack Linux system, you must ensure that any -Xss values are large enough and are not relying on a minimum of 256 KB.

(Linux IA 32-bit only) Particular Linux distributions - Red Hat, for example - have enabled a GLIBC feature called 'floating stacks'. Because of Linux kernel limitations, the JVM does not run on SMP hardware with floating stacks enabled if the kernel level is less than 2.4.10. In this environment, floating stacks must be disabled before the JVM, or any application that starts the JVM, is started. On Red Hat, use this command to disable floating stacks by exporting an environment variable:

    export LD_ASSUME_KERNEL=2.2.5

## Switching the input method in DBCS languages

On double-byte character set (DBCS) systems, if you want to switch the input method, you should use java.util.prefs.Preferences class instead of IBMJAVA_INPUTMETHOD_SWITCHKEY and IBMJAVA_INPUTMETHOD_SWITCHKEY_MODIFIERS environment variables. See Sun's Input Method Framework Specification in detail.

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

| | |

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

## (Linux IA 32-bit only) 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/.

The Java Plug-in is supported on Netscape 4, Netscape 6, and Mozilla, as provided by your distribution.

### Installing and configuring the Java Plug-in for Netscape 6 and Mozilla

To install and configure the Java Plug-in for Netscape 6 or Mozilla, make a symbolic link from the library file /opt/IBMJava2-142/jre/bin/libjavaplugin_oji.so to your browser's plugins directory (/brower-install-path/plugins).

To make the Java Plug-in available to all users:

1. Log in as root.
2. Put a symbolic link to the library file /opt/IBMJava2-142/jre/bin/libjavaplugin_oji.so into the Mozilla or Netscape plugin directory (usually /usr/local/mozilla/plugins/ (or netscape), although this might vary on some distributions).

       ln -s /opt/IBMJava2-142/jre/bin/libjavaplugin_oji.so \
          /usr/local/mozilla/plugins/

Note:
libjavaplugin_oji.so should be symbolically linked instead of copied; otherwise, it will not be able to find the location of the JVM.

### Installing and configuring the Java Plug-in for Netscape 4

To install and configure the Java Plug-in for Netscape 4, make a symbolic link from the library file /opt/IBMJava2-142/jre/bin/javaplugin.so to your browser's plugins directory (/brower-install-path/plugins).

To make the Java Plug-in available to the current user:

1. Create a directory called plugins under the $HOME/.netscape directory if it does not already exist.
2. Make a symbolic link from the library file /opt/IBMJava2-142/jre/bin/javaplugin.so to /$HOME/.netscape/plugins.

To make the Java Plug-in available to all users:

1. Log in as root.
2. Put a symbolic link to the library file /opt/IBMJava2-142/jre/bin/javaplugin.so into the plugin directory (usually /usr/local/netscape/plugins/, although this might vary on some distributions).

       ln -s /opt/IBMJava2-142/jre/bin/javaplugin.so \
          /usr/local/netscape/plugins/

Note:
javaplugin.so should be symbolically linked instead of copied; otherwise, it will not be able to find the location of the JVM.

### 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 the Java Plug-in with gcc3.2.x compiled Mozilla browsers

If you are using a distribution that ships with a gcc3.2.x compiled Mozilla browser (SLES8, Suse8.1), you must use gcc3 compiled plug-in libraries that are shipped with the IBM SDK for Linux, v1.4.2 SR1: libjavaplugin_ojigcc3.so and libjavaplugin_jnigcc3.so. To use these libraries, create a symbolic link to libjavaplugin_ojigcc3.so under <mozilla_installation_dir>/plugins directory:

    ln -s <sdkdir>/jre/bin/libjavaplugin_ojigcc3.so libjavaplugin_ojigcc3.so

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

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

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

| | |

# (Linux IA 32-bit and zSeries only)Support |for new locales

|

The IBM SDK for Linux, v1.4.2 SR1 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.

|

Note that even though the SDK supports these locales, the |Linux operating system does not have the fonts for them.

# 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 /opt/IBMJava2-142/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 /opt/IBMJava2-142/. 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. Check the value of the property org.apache.xalan.xsltc.dom.XSLTCDTMManager |in the file /opt/IBMJava2-142//lib/xalan.properties.
|
3. Check the contents of the file META-INF/services/org.apache.xalan.xsltc.dom.XSLTCDTMManager |for a class name.
|
4. Use the default service provider, org.apache.xalan.xsltc.dom.XSLTCDTMManager.

The XSLT Compiling processor detects the service provider for the org.apache.xalan.xsltc.dom.XSLTCDTMManager |service when a javax.xml.transform.TransformerFactory object is created. |Any javax.xml.transform.Transformer or javax.xml.transform.sax.TransformerHandler |objects that are created by using that TransformerFactory object will use |the same service provider. You can change service providers 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 /opt/IBMJava2-142/jre/lib.
|
- Uncomment the entries in the jaxp.properties file in /opt/IBMJava2-142/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
- A Runtime Environment
- An installation procedure or program

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

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

# Service and support for independent software vendors

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

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

# Accessibility

The User Guides that are supplied with this SDK and the Runtime Environment have been tested 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 SDK for Linux, v1.4.2 SR1 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.

## (Linux IA 32-bit only) 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.

# Troubleshooting

If you find a problem after you install the SDK for Linux, check the following list.

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

- Exception when running applets
  - If you use the Applet Viewer to run an applet that is in the CLASSPATH, you might get an AccessControlException in Swing.
  - To work around this problem, be sure of the following:
    - No CLASSPATH references exist to the applet that you are attempting to run in the Applet Viewer.
    - You are not running the applet from the directory that contains the class.
  (Linux IA 32-bit only) Because the CLASSPATH implicitly contains the current directory (.), this exception might also occur if you run the Java Plug-in in the same directory as the applet class itself.
- Sound does not work in Java applications
  - If sound does not work in your Java applications your user ID might not have the correct permissions to access the audio device. Change the ownership and permissions of the audio device so that your user ID has the correct permissions.
- `Unable to load libjava.so library` message.
  - If you receive a message indicating that the libjava.so library could not be loaded because of a symbol not found, you might have a down-level version of the C Runtime Library, libc, installed. The Developer Kit for Linux thread implementation requires libc version 2.1.3-176 or later.
- Applet Viewer does not load applets.
  - If the Applet Viewer does not load applets, type the following at a shell prompt:

            java -verbose sun.applet.AppletViewer

  - This command lists the classes that are being loaded. From this output, you can determine which class the Applet Viewer is trying to load and from where it is trying to load it. Check to ensure that the class exists and is not damaged.
- Application does not handle EINTR return code correctly.
  - If you are writing a Java application, particularly a Java Native Interface (JNI) application, ensure that the application handles the EINTR return code correctly; otherwise the application will fail.

# Reporting problems

The SDK is provided as is, with no support unless you are entitled by means of an IBM support contract. For information on known problems and FAQs, refer to: http://www.ibm.com/developerworks.

You can report problems to the ibm.software.java.linux news group. This news group is monitored, but solutions to specific reports are not guaranteed. The newsgroup is available from the news server news://news.software.ibm.com.

When you report a problem, provide the following information:

1. Describe in detail:
   - What you are doing
   - What you expect to happen
   - What is actually happening
2. Give details of which operating system level and version you are using, window manager name and version, and the output from `java -version`.

       uname -a
       java -version

3. Describe precisely how to reproduce the problem.
4. Include a javadump either from the application that fails, or if this is not possible, from any Java application. (A javadump is generated automatically when a failure occurs. You can generate a javadump by sending a SIGQUIT to the java process. Send a SIGQUIT with CTRL+\ from the command shell, or `kill -3 <pid>` from the command line.)
5. Make a test case available. (The simpler the test case, the faster the problem can be addressed.)
6. If your e-mail address is different from the one that is given in the newsgroup, provide your e-mail address.

# Known limitations

The following sections explain known limitations of the SDK and Runtime Environment for Linux.

## Limitations that apply to all Linux platforms except where indicated

- You might not be able to use the system clipboard with double-byte character set (DBCS) to copy information between Linux applications and Java applications if you are running the K Desktop Environment (KDE).
- The SDK implements Java threads as native threads, which results in each thread being a separate Linux process. If the number of Java threads exceeds the maximum number of processes allowed, your program might get an error message, a SIGSEGV error, or your system might hang.

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

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

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

- If you terminated a Java application with a Ctrl-C, several processes might be left orphaned.
- An attempt to display dialog boxes that are created with Swing might cause a delay of a few seconds before those boxes are displayed in the window.
- KeyEvent results that include the ALT key differ between using different window managers in Linux. They also differ from results of other operating systems. In the Enlightenment window manager, Alt+A and Shift+Alt+A produce different modifiers, and Ctrl+Alt+A produces no key event at all. However, using the WindowMaker window manager, Ctrl+Alt+A produces a key event.
- On the Linux X Window System, the keymap is set to: 64 0xffe9 (Alt_L) 0xffe7 (Meta_L), and 113 0xffea (Alt_R) 0xffe8 (Meta_R). You can check this by typing the following at a shell prompt:

      xmodmap -pk

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

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

  Note:
  This workaround might affect other X-Window applications that are running on the same display if they use the Meta-key that was removed.
- Creating DSA key pairs of unusual lengths can take a significant amount of time on slow machines. Do not interpret this delay as a hang because the process will complete if you allow enough time. The DSA key generation algorithm has been optimized to generate standard key lengths (for instance, 512, 1024) more quickly than others.
- 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.

- For users of Traditional Chinese only, function keys Enter, Space, Backspace, and ESC do not work as expected when using the LinYi ZhuYin, YiTian ZhuYin, and Bosham IMEs to input the TCH characters. The Enter key inserts a new line, the ESC key is used to cancel the preedit strings or the candidate window, and the Space bar inserts a space. The candidate window should disappear after the commit key has been pressed and it should not appear when you press the Backspace key while using the LinYi ZhuYin, YiTian ZhuYin, and Bosham IMEs to input the Traditional Chinese characters.
- If you are running with a lot of concurrent threads, you might get a warning message: `java.lang.OutOfMemoryError`. This is an indication that your machine is running out of system resources and messages can be caused by the following reasons:
  1. New threads cannot be created because:
     - The number of processes created exceeds your user limit.
     - Not enough system resources are available to create new threads. In this case, you might see also other Java exceptions, depending on what your application is running.
  2. Kernel memory is either running out or is fragmented. You can see corresponding Out of Memory kernel messages in /var/log/messages that have the killed process id.
  Try tuning your system to increase the corresponding system resources.
- During installation, if you have already installed an earlier version of this product that was distributed by Red Hat, the Red Hat Package Manager (RPM) will report that the IBM package is older than any versions of the product that Red Hat has distributed. This condition occurs because Red Hat adds to the RPM package a "serial number" that overrides the versioning scheme of the product in the package, and, by default, the RPM refuses to install a package that seems to be older than one already installed. The --oldpackage option of the rpm command enables you to install the new IBM package.
- In SDK Version 1.4.2, applications that run on symmetric multiprocessor machines (SMP) on SLES 8 perform better with a changed IBM JVM implementation of Java monitors. Because most applications will have either benefits or no change to performance, the new algorithm is now the default behavior. If, on the other hand, the new default setting reduces the performance of your JVM, you can restore the old algorithm by setting the environment variable: `export IBM_JVM_MONITOR_OLD=<any value>`.

  For more information, see the Diagnostics Guide for v1.4.2.

- When running a java awt/swing application on a Linux machine and exporting the display to a second machine, you might experience problems displaying some dialogs if the set of fonts loaded on the X client machine is different from the set loaded on the X server machine. This problem is noticeable particularly with SLES8 in Chinese locales, where the default installation of the server version installs arphic fonts, but the default installation of the client does not. To avoid this problem, install the same fonts on both machines.
- |If your system locale is using a UTF-8 encoding, some SDK |tools might throw a sun.io.MalformedInputException. To find out whether your |system is using a UTF-8 encoding, examine the locale-specific environment |variables such as LANG or LC_ALL to |see if they end with the suffix ".UTF-8". If you get this sun.io.MalformedInputException, |change characters that are not within the 7-bit ASCII range (0x00 - 0x7f) |and are not represented as Java Unicode character literals to Java Unicode |character literals (for example: '\u0080'). You can also work around this |problem by removing the ".UTF-8" suffix from the locale-specific environment |variables; for example, if your machine has default locale of "en_US.UTF-8", |set LANG to "en_US". | |
  Note:
  |
  Some distributions |of RedHat, including Redhat9 and RHEL3, use UTF-8 encoding by default.
  |
  |
- |If you are using AMI and xcin in a cross-platform environment |(for example, if you try to export the display between a 32-bit and a 64-bit |system, or between a big-endian and a little-endian system) there might be |some problems. If you have this kind of problem, contact your Linux distributor. |
  |
- |On Redhat Enterprise Linux 3.0, Chinese characters might |not be displayed in AWT text components except for GB2312 characters in the |Chinese GB18030 locale. |
  |

| |
- (Linux IA 32-but and zSeries only) Although the |SDK supports the Bengali (bn_IN), Kannada (kn_IN), Malayalam (ml_IN), Oriya |(or_IN), and Punjabi (pa_IN) locales, the fonts from these locales do not |work on AWT components. Also note that the fonts from these |locales are not present on the Linux operating system. |
  |

## Linux IA 32-bit limitations

- SLES 8 for Korean might not display Korean characters. To fix this, install the "baekmuk-ttf" rpm package and run `SUSEconfig`:

        # touch /usr/X11R6/lib/X11/fonts/truetype/fonts.scale.baekmuk
        # SUSEconfig

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

## Linux PPC 32-bit and 64-bit limitations

- If you are running XFree86 version 3.x, you might receive a SIGSEGV error. To avoid this problem, it is recommended that you use XFree86 version 4.x.
- If you download and install the Java Cryptography Extensions (JCE) security extensions, remove the Java Cryptography Architecture (JCA) jar file (jre/lib/ext/ibmjcaprovider.jar) during the installation process. Because JCA functionality is a subset of JCE, the JDK might not function correctly when both are installed.
- If the date is set to a date before 1970, you get an exception error when you try to start Java. To work around this problem, manually set your machine to the current date.

## Linux PPC 32-bit limitations

- The SLES 8.0 install CDs for PowerPC do not include adequate TrueType Chinese fonts for Java to display Chinese correctly. Install the ttf-hanyi-20021016-0.noarch.rpm package from United Linux 1.0 to improve the display of Chinese fonts.
- If your Java code uses JNI calls, and any specific call has more than eight float or double parameters, your C code must be compiled with the gcc-2.95.3 Free Software Foundation (FSF) level of GNU C Compiler (GCC).

## Linux zSeries 64-bit limitations

The following limitations apply to users of Chinese, Taiwanese, and Korean on Linux zSeries 64-bit:

- The Chinese and Taiwanese input method server (xcin) has not been tested with Version 1.4.2.
- For users of Simplified Chinese only, some Chinese characters might not be displayed. To avoid the problem, download the following TrueType font onto SLES8 for your zSeries 64-bit system:
  - ttf-hanyi-20021016-0
  The font is available from the SUSE web site at: http://www.suse.com/index_us.html.
- For users of Traditional Chinese only, some Chinese characters might not be displayed. To avoid the problem, download the following TrueType fonts onto SLES8, which works as a graphical client:
  - ttf-arphic-bkai00mp-20001125-103
  - ttf-arphic-gbsn00lp-20001125-103
  - ttf-arphic-gkai00mp-20001125-103
  - ttf-arphic-bsmi00lp-20001125-103
  - ttf-arphic-20001125-323
  The fonts are available from the SUSE web site at: http://www.suse.com/index_us.html.

## Linux zSeries 32-bit and 64-bit limitations

- If you use audio on a machine without a sound card, you might get an error message stating that you are out of memory when Java tries to play a sound. The message is displayed in the console, but it does not affect your Java application.
- Although the Linux kernel in the current distributions provides support for Internet Protocol version 6 (IP6), you might encounter problems using it. Support for IP6 from Java is included in this release, but you are advised to turn off the support with the -Djava.net.preferIPv4Stack=true option on the Java command. If you install a kernel that fully supports IP6, you do not need this option.

# 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, iSeries, pSeries, and zSeries 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/.