IBM(R) Developer Kit for Linux, JavaTM 2 Technology Edition, Version 1.3.1, 64-bit version

- README -


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 Developer Kit for Linux, Java 2 Technology Edition, Version 1.3.1, 64-bit version, and to all subsequent releases and modifications until otherwise indicated in new editions.

(c) Copyright IBM 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 IBM(R) Developer Kit for Linux, JavaTM 2 Technology Edition, Version 1.3.1, 64-bit version.

The Developer Kit for Linux enables you to write and then run Java applications and applets. Note that the Runtime Environment for Linux is a subset of this Developer Kit and enables you only to run Java applications. If you have installed the Developer Kit for Linux, you do not need the Runtime Environment.

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


Contents

  • Overview
  • Version compatibility
  • Contents of the Developer Kit for Linux
  • The just-in-time (JIT) compiler
  • Configuring the Developer Kit for Linux
  • Installing on Red Hat
  • Installing if using BEA Weblogic
  • Uninstalling the Developer Kit for Linux
  • Uninstalling the RPM package
  • Uninstalling the compressed TAR package
  • Using the Developer Kit
  • PATH considerations
  • CLASSPATH considerations
  • Running applets with the Applet Viewer
  • Debugging applets with the Applet Viewer
  • Working with floating stacks
  • Obtaining the IBM build and version number
  • Working with floating stacks
  • Debugging Java applications
  • JPDA
  • JDB
  • Switching the input method in DBCS languages
  • Devanagari fonts
  • Enhanced 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
  • System properties for vendor ORB Compatibilty
  • Java 2 security permissions for the ORB
  • ORB implementation classes
  • Implementing the Connection Handler Pool for RMI
  • RMI over IIOP
  • Enhanced BigDecimal
  • Shipping Java applications
  • Troubleshooting
  • Known limitations
  • Information for Japanese users
  • Reporting problems
  • Service and support for independent software vendors
  • Accessibility
  • Java console accessibility
  • Policy Tool and accessibility
  • Notices
  • Trademarks

  • Overview

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


    Version compatibility

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

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

    Contents of the Developer Kit for Linux

    The following list describes the contents of the Developer Kit package.

    Note: This README file and the accompanying license, copyright files, and demo directory are the only documentation included in this Developer Kit 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.

    The documentation package is designed to be extracted into the Developer Kit for Linux software installation directory. If you download the zip file archive version, be sure to preserve the file path names when you extract the files from the archive. If you use pkunzip, specify the -d option.


    The just-in-time (JIT) compiler

    The Developer Kit for Linux includes the IBM just-in-time (JIT) compiler (libjitc.so). The JIT compiler dynamically generates machine code for frequently used bytecode sequences in a Java application or applet while it is running.

    All Developer Kit for Linux tools use the JIT 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:

        export JAVA_COMPILER=libjitc.so
    

    To determine if the JIT is enabled, type the following at a shell prompt:

    If a JIT is in use, one of the following messages is displayed:

    If no JIT is in use, one of the following messages is displayed:


    Configuring the Developer Kit for Linux

    After you install the Developer Kit for Linux, edit your shell script and add to your PATH statement the directory where you installed the Developer Kit. For more information about the PATH statement, see PATH considerations.


    Installing on Red Hat

    When you are installing on a Red Hat system, to allow the font server to find the Java TrueType fonts, run:

    su root /usr/sbin/chkfontpath --add /opt/IBMJava2-131/jre/lib/fonts

    You must do this at install time and you must be root to run the command.

    The Developer Kit requires the packages libgcc and libstdc++3 to be installed. Their rpm's will have names similar to "libgcc-3.0.1-3-1.ia64.rpm" and "libstdc++3-3.0.1-3-1.ia64.rpm".

    Installing if using BEA Weblogic

    If you intend to use the BEA Weblogic server, when you install the Developer Kit for Linux packages you must not install the IBMJava2-JAAS-*.rpm. The BEA Weblogic server contains its own implementation of JAAS.


    Uninstalling the Developer Kit for Linux

    The process you use to remove the Developer Kit 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.

    Uninstalling the RPM package

    To uninstall the Developer Kit for Linux if you installed the RPM package:

    1. At a prompt, type the following:
          rpm -qa | grep IBM
      
      The name of the package is displayed.

    2. Use the rpm command, as follows:
          rpm -e pkgname
      
      where pkgname is the name of the package that was displayed.

    3. Remove from your PATH statement the directory where you installed the Developer Kit.

    Uninstalling the compressed TAR package

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

    1. Remove the Developer Kit files from the directory where you installed the Developer Kit.

    2. Remove from your PATH statement the directory where you installed the Developer Kit.

    Using the Developer Kit

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


    PATH considerations

    After installing the Developer Kit for Linux software, 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 Developer Kit for Linux software is installed in /opt/IBMJava2-131/bin, you can compile a file named myfile.java by typing the following at a shell prompt:

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

    To avoid typing the full path each time:

    1. Add these directories to the PATH environment variable:

    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 to the PATH environment variable the absolute paths to the directories:
    2. Log on again or run the updated shell script to activate the new PATH setting.

    CLASSPATH considerations

    The CLASSPATH tells the Developer Kit 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 explicitly set the CLASSPATH only if one of the following applies:

    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 using different runtime environments, including other versions that you have installed separately, you need to explicitly set the CLASSPATH (and PATH) appropriately for each application. If you plan to simultaneously run multiple applications using different runtime environments, be sure each application is run in its own shell.

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


    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) 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 an entire Web page that contains numerous HTML tags. It parses only the APPLET tag 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:

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

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

      Debugging applets with the Applet Viewer

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

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

      You might find documentation on the debugger and its API at the following Sun Web site:


      Obtaining the IBM build and version number

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


      Working with floating stacks

      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.


      Debugging Java applications

      To debug Java programs, you can use the Java Debugger (JDB). This debugger interfaces with the Java Platform Debugger Architecture (JPDA) provided by the Developer Kit for Linux. For native JNI binary programs, you can still use gdb for debugging.

      JPDA

      The JPDA classes are included in the tools.jar file, which must be included in the CLASSPATH when running Java programs that use the JPDA (for example, JDB). Only socket communication is supported on Linux.

      JDB

      A new JDB debugger is included in the Developer Kit for Linux. The JDB starts com.sun.tools.example.debug.tty.TTY. The Java Virtual Machine Debugging Interface (JVMDI) is now fully supported. The jdb tool included in earlier versions is now included as oldjdb.

      The new 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 and can be used in the same way that oldjdb works.

      You can use the JDB to debug remote Java applications, including Java applications 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 the following:

      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 actually free to use.


      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 some 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 pop-up menu with selectable input methods is displayed.


      Devanagari fonts

      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.


      Enhanced CORBA support

      IBM Developer Kit for Linux, Java 2 Technology Edition, Version 1.3.1, 64-bit version adds support for these CORBA specifications:

      Support for GIOP 1.2

      This Developer Kit 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

      Bi-directional GIOP is not supported.

      Support for Portable Interceptors

      This Developer Kit supports Portable Interceptors, as defined by the OMG in the document formal/01-09-58, which you can obtain from:

      http://www.omg.org/cgi-bin/doc?formal/01-09-58

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

      Several new classes are introduced in the API to support Portable Interceptors. These are:

      These classes are not part of the Sun Java 1.3 Core API, and could change in future versions of the IBM Developer Kit.

      Support for Interoperable Naming Service

      This Developer Kit has added support for 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 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 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.

      Several new classes are introduced in the API to support the Interoperable Naming Service:

      These classes are not part of the Sun Java 1.3 Core API, and could change in future versions of the IBM Developer Kit.

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

      The ORB supports the -ORBInitRef and -ORBDefaultInitRef parameters defined by the Interoperable Naming Service specification, and the ORB::string_to_object operation now supports the ObjectURL string formats (corbaloc: and corbaname:) 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.3.1. 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, returned from ORB.init(), and serviceRef is a CORBA Object, 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 new 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. Set com.ibm.CORBA.Debug=true to turn on tracing. To format and add to the trace GIOP messages sent and received, set com.ibm.CORBA.CommTrace=true. By default, ORB tracing goes to the standard error stream, java.lang.System.err. To direct it to a file, set com.ibm.CORBA.Debug.Output. For example, to trace events and formatted GIOP messages to a file:

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

      The trace will be sent to the files orbtrc.DDMMYYYY.HHmm.SS.txt and orbmsg.DDMMYYYY.HHmm.SS.txt.

      Do not turn on tracing for normal operation, because it might cause performance degradation.

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

      System properties for tuning the ORB

      The following properties help you to tune the ORB:

      System properties for vendor ORB Compatibilty

      The following properties may be necessary to enable non-standard behaviour for some vendor ORBs:

      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 could result in a SecurityException. Affected methods include the following:

      Class/Interface

      Method

      Required permission

      org.omg.CORBA.ORB

      init

      java.net.SocketPermission resolve

      org.omg.CORBA.ORB

      connect

      java.net.SocketPermission listen

      org.omg.CORBA.ORB

      resolve_initial_references

      java.net.SocketPermission connect

      org.omg.CORBA.portable.ObjectImpl

      _is_a

      java.net.SocketPermission connect

      org.omg.CORBA.portable.ObjectImpl

      _non_existent

      java.net.SocketPermission connect

      org.omg.CORBA.portable.ObjectImpl

      OutputStream _request (String, boolean)

      java.net.SocketPermission connect

      org.omg.CORBA.portable.ObjectImpl

      _get_interface_def

      java.net.SocketPermission connect

      org.omg.CORBA.Request

      invoke

      java.net.SocketPermission connect

      org.omg.CORBA.Request

      send_deferred

      java.net.SocketPermission connect

      org.omg.CORBA.Request

      send_oneway

      java.net.SocketPermission connect

      javax.rmi.PortableRemoteObject

      narrow

      java.net.SocketPermission connect

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

      ORB implementation classes

      The ORB implementation classes in this release are:

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


      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.


      RMI over IIOP

      Java Remote Method Invocation (RMI) provides a simple mechanism to do distributed Java programming. RMI over IIOP (RMI-IIOP) extends the base Java RMI to perform communication using the Common Object Request Broker Architecture (CORBA) standard Internet Inter-ORB Protocol (IIOP protocol). 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:


      Enhanced BigDecimal

      The Runtime Environment 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 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.


      Using the Java Debugger (jdb) with IBM's Java

      Sun's documentation for using jdb assumes that the JVM 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. This requires that the -Xnoagent option be specified, unless the agent class is required in which case the -Xbootclasspath option should be specified to explicitly locate it.


      Shipping Java applications

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

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

      Your Developer Kit for Linux software license does not allow you to redistribute the Developer Kit for Linux software files. The Runtime Environment for Linux is available for redistribution as a separate package. You can download the Runtime Environment for Linux package from the Web site where you obtained the Developer Kit for Linux package.


      Troubleshooting

      If you encounter a problem after you install the Developer Kit for Linux, check the following list:


      Known limitations


      Information for Japanese users