Note: Before using this information and the product it supports, be sure to read the general information under Notices.
This edition of the README applies to the IBM Runtime Environment for Linux, Java 2 Technology Edition, Version 1.3.1, 32-bit version, and to all subsequent releases and modifications until otherwise indicated in new editions.
(c) Copyright International Business Machines Corporation, 1999, 2002. All rights reserved.
(c) Copyright Sun Microsystems, Inc. 1997, 2001, 901 San Antonio Rd., Palo Alto, CA 94303 USA. All rights reserved.
U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
This README file provides information about the Runtime Environment for Linux package provided with the IBM(R) Developer Kit for Linux, Java(TM) 2 Technology Edition, Version 1.3.1, 32-bit version (Developer Kit for Linux).
The Runtime Environment allows you only to run Java applications. If you want to write and then run Java applications, you must install the Developer Kit for Linux. If you have installed the Developer Kit for Linux, you do not need the Runtime Environment, which is a subset of the Developer Kit.
For the list of distributions against which the Developer Kit for Linux has been tested, see:
http://www-106.ibm.com/developerworks/java/jdk/linux/tested.html
The Runtime Environment for Linux contains the subset of classes required to create a Java runtime environment and to run Java programs. It also contains the Java Virtual Machine, Java classes, and supporting files. The Runtime Environment for Linux contains only a subset of the classes found in the Java Developer Kit.
Files included with the Runtime Environment for Linux
The Runtime Environment for Linux includes nondebuggable .so files plus class files needed to support a program at runtime. The Runtime Environment for Linux does not include any of the development tools, such as appletviewer or javac, or classes that pertain only to a development system.
In addition, the Java Authentication and Authorization Service (JAAS) and Java Communications application programming interface (API) packages are provided for use with the Runtime Environment for Linux.
The LICENSE_xx.html file contains the license agreement for the Runtime Environment for Linux software. (xx is an abbreviation for the language.)
To view or print the license agreement, open the file in a Web browser.
The just-in-time (JIT) compiler
The just-in-time (JIT) compiler (libjitc.so) dynamically generates machine code for frequently-used bytecode sequences in a Java application or applet while it is running.
The Runtime Environment for Linux includes the JIT compiler (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, type the following at a shell prompt:
export JAVA_COMPILER=NONE
To enable the JIT, type the following at a shell prompt:
unset JAVA_COMPILER
To verify whether or not the JIT is enabled, type the following at a shell prompt:
java -version
If the JIT is in use, a message is displayed that includes the following:
JIT enabled: jitc
If the JIT is not in use, the following message is displayed:
JIT disabled
The Native Method Interface and the Java Native
Interface
IBM does not support the Native Method Interface in this release. Do not use this interface in your applications.
The Java Native Interface (JNI) is included with the Runtime Environment. For information about using the JNI, see the Sun Web site:
Configuring the Runtime Environment for Linux
After you install the Runtime Environment for Linux, edit your shell script and add to your PATH statement the following directories:
If you installed the Runtime Environment for Linux in a directory other
than
Installing and configuring the Java Plug-in
The Java Plug-in is a Web browser plug-in for use with Netscape Communicator for Linux. If you use the Java Plug-in, you can bypass your Web browser's default Java Virtual Machine and use instead a Java Runtime Environment (JRE) for running applets or beans in the browser.
To install and configure the Java Plug-in:
Note: The first time you start Netscape after you have linked the
javaplugin.so file to the netscape/plugins directory, Netscape will
immediately shut down. (If you started Netscape from the command line, a
Bus error
message is displayed.) You can safely ignore this
message because Netscape will not encounter this error after the first
time.
Java is able to display all Unicode characters, but most versions of Linux install only the fonts needed to show your language. You can download fonts from IBM that enable you to see the complete Unicode character set. These fonts are not included in the Developer Kit for Linux package because they are large and not all users need them. The earlier versions of IBM JDK shipped with tnrmt30.ttf, which is discontinued now. IBM supplies two Unicode fonts, and each of them is customized by country. Users in China and Korea must use the country specific versions, and all others must use the Japanese version of these fonts.
You can download fonts from the developerWorks Web site at http://www.ibm.com/developer/java/. Descriptions of the fonts are provided to help you decide which fonts to download.
To install a font, put the file in the /opt/IBMJava2-131/jre/lib/fonts directory.
If you download fonts in parts, you must combine the parts together into one file for each font. To do this, be sure the parts are in the /opt/IBMJava2-131/jre/lib/fonts directory and use the cat command.
For example, if you downloaded the Times New Roman WT J font in parts, type the following command to put it back together:
cat tnrwt_j.t01 tnrwt_j.t02 tnrwt_j.t02 > tnrwt_j.ttf
When you are installing on a Red Hat system, to allow the font server to find the Java TrueType fonts, run:
You must do this at install time and you must be root
to run the command.
If you are running a SuSE system, there may be a version of this Runtime Environment already installed. If this version was supplied by SuSE, it will have been packaged so that it installs under a different directory tree. To avoid unexpected results, you should use YaST2 to remove the SuSE-supplied Runtime Environment .
If you intend to use the BEA Weblogic server, when you install the Developer Kit for Linux packages you must unselect the JAAS optional installation. The BEA Weblogic server contains its own implementation of JAAS.
Uninstalling the Runtime Environment for Linux
The process you use to remove the Runtime Environment for Linux depends on whether you installed the RPM package or the compressed TAR package. See Uninstalling the RPM package or Uninstalling the compressed TAR package for instructions.
To uninstall the Runtime Environment for Linux if you installed the RPM package:
rpm -qa | grep IBMThe name of the package is displayed.
rpm -e pkgnamewhere
pkgname
is the name of the package that was displayed. Uninstalling the compressed TAR package
To uninstall the Runtime Environment for Linux if you installed the compressed TAR package:
Invoking the Java Runtime Interpreter
The Runtime Environment for Linux can be invoked from a shell prompt by using the java tool.
java [-options] classname <args>
The classname
argument is the name of the class file to be
executed. Any arguments to be passed to the class must be placed after
the classname
on the command line.
java -jar [-options] jarfile <args>
The jarfile
argument is the name of the jar file to be
executed. Any arguments to be passed to the jar file must be placed
after the jarfile
on the command line.
Options for the java tool are as follows:
The -X options are nonstandard and subject to change without notice.
The system property ibm.jvm.bootclasspath can be set using the
-D option described in the Invoking the Java Runtime Interpreter
section. The value of this property is used as an additional search path,
inserted between any value defined by
Obtaining the IBM build and version number
To obtain the IBM build and version number, type the following at a shell prompt:
java -version
Certain Linux distributions - RedHat, for example - have enabled a GLIBC feature called 'floating stacks'. Because of Linux kernel limitations, the JVM will 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 RedHat, you disable floating stacks by exporting an environment variable, thus:
On a non-floating stack Linux system, regardless of what is set for -Xss, a minimum native stack size of 256KB for each thread is provided. On a floating stack Linux system, the -Xss values are honored. Thus, 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 256KB.
Switching the input method in DBCS languages
On double-byte character set (DBCS) systems, if you want to switch the input method, you must set an environment variable that represents the keycode you use for switching. Optionally, you can set another environment variable that represents the modifiers of the keycode.
To specify the keycode to use for switching, set the IBMJAVA_INPUTMETHOD_SWITCHKEY environment variable to a keycode definition in the java.awt.event.KeyEvent class, for example, VK_F4.
Optionally, specify modifiers of the keycode. To specify modifiers of the keycode, set the IBMJAVA_INPUTMETHOD_SWITCHKEY_MODIFIERS environment variable to some combination of the following three mask definitions in the java.awt.event.InputEvent class:
Separate the masks by commas.
For example, you might set the IBMJAVA_INPUTMETHOD_SWITCHKEY_MODIFIERS environment variable to ALT_MASK, CTRL_MASK.
During Java initialization, the two environment variables are stored.
To be sure you have set the environment variables correctly, press a key and check it with the key combination you specified. If it matches, a Java popup menu with selectable input methods is displayed.
This Developer Kit does not ship Devanagari fonts (Devamt.ttf and Devamtb.ttf) in the jre/lib/fonts directory. Instead, where appropriate, Java uses the Monotype Unicode fonts (Times New Roman WorldType and Sans Monospace WorldType) shipped with the IBM platform or IBM software product to support Devanagari (Hindi) fonts.
The following Sun Web page contains examples that you can download. The examples demonstrate how to create a simple Java application that runs with the Runtime Environment for Linux. The examples are on the Sun Web site:
The examples show how to make a simple, seamless transition from developing an application with the Developer Kit for Linux, to deploying it with the more lightweight Runtime Environment for Linux.
Installing your application on a user's system
After you develop your product and are ready to ship, you need to install your product onto an individual user's system, configure the user's system to support your software, and configure the runtime environment.
If you use the Runtime Environment for Linux, you must make sure that your installation procedure does not overwrite an existing installation (unless the existing Runtime Environment for Linux is an older version).
To redistribute the Runtime Environment for Linux, you can install it on your own system, then copy the required Runtime Environment files into your installation set. If you choose this approach, you must include all the files provided with the Runtime Environment for Linux. The Runtime Environment for Linux software can only be redistributed if all files are included. In effect, when you ship your application, it has its own copy of the Runtime Environment for Linux.
For specific information about the files that must be redistributed, see the license agreement that accompanies this product.
The IBM Runtime Environment for Linux, Java 2 Technology Edition, V1.3.1 introduces the -Xgcpolicy JVM runtime option for specifying garbage collection policy.
-Xgcpolicy takes two values, optthruput (the default) and optavgpause. The option controls garbage collector behavior, making tradeoffs between throughput of the application and overall system and the pause times caused by garbage collection.
The format of the option and its values is:
-Xgcpolicy:optthruputand
-Xgcpolicy:optavgpause
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. As 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 optavgpause value substantially reduces the time spent in these garbage collection pauses, as well as limiting the effect of increasing heap size on the length of the garbage collection pause. This is particularly relevant to configurations with large heaps. (Consider a heap as large when it is at least 1GB.) The pause times are reduced by overlapping garbage collection activities with normal program execution. This overlapping results in a small reduction to application throughput.
If the Java heap becomes nearly full, and there is very little garbage to be reclaimed, requests for new objects might not be satisfied quickly because there is no space 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 Out of Memory exception, which results in JVM termination if the exception is not caught and handled. In these situations, you are recommended either to increase the heap size using the -Xmx option or to reduce the number of application objects in use.
For information on heap size tuning and the implications of garbage collection for application performance, see:
Runtime Environment for Linux documentation
IBM supplies the following runtime documentation:
export LC_ALL="POSIX"
The maximum number of threads available is determined by the minimum of the following:
However, you might run out of virtual storage prior to reaching the maximum number of threads.
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 Runtime Environment for Linux considers that Meta is being pressed together with Alt. 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 Windows applications running on the same display if it uses the Meta-key that was removed.
fs
to be preserved across JNI calls. The Java Virtual Machine will fail if fs
is not preserved.
Information for Japanese users
If you are using OpenLinux e-Server 2.3, Japanese version, you must reset some environment variables as follows:
export CLASSPATH= export JAVA_HOME=
If you are using Red Hat Linux 6.2, Japanese version, or OpenLinux e-Server 2.3, Japanese version, halfwidth Katakana characters might not be displayed correctly. This is due to the lack of font data for those characters. If you experience this, download IBM TrueType fonts. Halfwidth Katakana characters can then be displayed on any components except Abstract Windows Toolkit (AWT) Components.
If you are running a Java applet using the Java Plug-in with Netscape Communicator and you pass a Japanese string as a parameter value, the parameter value is not passed correctly.
On TurboLinux 6.0J Workstation, you might receive an error message about the libnsfix-ja.so library when using Netscape Communicator.
To fix the problem, rename the file /usr/lib/netscape/libnsfix-ja.so. The new file name is:
On Japanese versions of Linux, you can use a Japanese input method such as Canna, ATOK12 SE, Wnn4, or Wnn6. Use the following sections to avoid problems when using these Japanese input methods.
For all input method editor (IME) users
To bring another window to the top, do one of the following:
Canna users
If you are using the Canna input method with the kinput2 input method server, some visual feedback from the input method is not visible while you are in KIGOU input mode. To avoid the problem, move the focus onto the client window after the Auxiliary Control Window opens.
ATOK12 SE users
Wnn4 users
If you are using Wnn4, the Enter key does not create a new line and a carriage return while the Input Method Editor (IME) is activated. To create a new line and carriage return, deactivate the IME.
Wnn6 users
The xwnmo Input Method server is not supported. Use kinput2 as the Input Method server.
Wnn4, Wnn6, or Canna users
If you are using kinput2 as the Input Method server, do not minimize or maximize the Java window in which the kinput2 lookup window is displayed.
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 users responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:
The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the information. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this information at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurement may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.
IBM is a trademark of International Business Machines Corporation in the U.S., 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. The Java technology is owned and exclusively licensed by Sun Microsystems, Inc.
Other company, product, and service names may be trademarks or service marks of others.