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

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

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

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


Preface

The IBM(R) 32-bit Runtime Environment for Windows(R), Java(TM) 2 Technology Edition, Version 1.4.1 contains the Java Virtual Machine (JVM), core Sun Microsystems Java classes, and supporting files. The Runtime Environment does not contain all the classes that are found in the SDK package.

The User Guide provides general information about the Runtime Environment and specific information about any differences in the IBM implementation of the Runtime Environment compared with the Sun implementation. Read this User Guide in conjunction with the more extensive documentation on the Sun Web site: http://java.sun.com.

The Runtime Environment is supported on the following products:

Note that the Runtime Environment for Windows 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 for this 1.4.1 User Guide, other than minor or obvious ones such as updating "1.4.0" to "1.4.1", 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

Using the Runtime Environment

  • Obtaining the IBM build and version number
  • Launching a Java application
  • Summary of commands
  • Options
  • Globalization of the java command
  • Working with classpaths
  • Executing a Java file automatically
  • |How the JVM processes signals
  • Working with the bootclasspath
  • Specifying garbage collection policy
  • Runtime example
  • Using the Java Plug-in

  • Supported browsers
  • Using DBCS parameters
  • Running Java applications with native assistive technologies

    Using Web Start

    Working with an Input Method Editor

    |Known limitation

    Any comments on this User Guide?

    Notices

  • Trademarks

  • Using the Runtime Environment

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


    Obtaining the IBM build and version number

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

    java -version


    Launching a Java application

    The java tool launches a Java application.

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

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

    Summary of commands

    The java and javaw command have the following syntax:

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

    Items that are within brackets are optional.

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

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

    Options

    The launcher has a set of standard options that are supported on the current runtime environment and will be supported in future releases. In addition, there is a set of non-standard options.

    Standard options

    -D<property_name>=<value>

    Sets a system property.

    -assert

    Prints help on assert-related options.

    -cp or -classpath <directories and zip or jar files separated by ;>

    Set search path for application classes and resources. If -classpath and -cp are not used, and CLASSPATH is not set, the user classpath is, by default, the current directory (.). Also see Working with classpaths.

    -help or -?

    Prints a usage message.

    -showversion

    Prints product version and continues.

    -verbose[:class | gc | jni]

    Enables verbose output.

    -version

    Prints product version.

    -X

    Prints help on non-standard options.

    Non-standard options

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

    -Xargencoding

    Allows the options on the java command to use Unicode escape sequences to represent characters that are not in the character set of the locale. Unicode escape sequences are of the form \u#### where # is a hexadecimal digit.

    -Xbootclasspath:<directories and zip or jar files separated by ;>

    Sets search path for bootstrap classes and resources. There are other ways of setting the bootclasspath. See Working with the bootclasspath. |Do not deploy applications that use this option to override a class |in core.jar, graphics.jar, server.jar, |security.jar, xml.jar, tools.jar, or charsets.jar, |because such a deployment would contravene the Java 2 Runtime Environment |binary code license.

    -Xbootclasspath/a:<directories and zip or jar files separated by ;>

    Appends to end of bootstrap class path.

    |-Xbootclasspath/p:<directories and zip or |jar files separated by ;> |

    |Puts on the front of bootstrap class path. Do not deploy applications that use this option to override a class |in core.jar, graphics.jar, server.jar, |security.jar, xml.jar, tools.jar, or charsets.jar, |because such a deployment would contravene the Java 2 Runtime Environment |binary code license. |

    -Xcheck:jni

    Performs additional checks for JNI functions.

    -Xcheck:nabounds

    Performs additional checks for JNI array operations.

    -Xdebug

    Starts the JVM with the debugger enabled.

    |-Xdisableexplicitgc |

    |Changes calls to System.gc() into no-ops. |

    -Xdisablejavadump

    Disables the java dump facility for abnormal process termination. When the java dump is disabled, the system process termination dump is run. The java dump is useful when the problem occurs within the java code. If the problem is in system components, it might be more useful to get the normal system dump.

    |-Xgcpolicy:{optthruput | optavgpause} |

    |Specifies the garbage collection setting. The default setting is |optthruput. For more information, see Specifying garbage collection policy. |

    -Xms<size>

    Sets initial Java heap size.

    -Xmx<size>

    Sets maximum Java heap size.

    -Xnoclassgc

    Disables class garbage collection.

    -Xoss<size>

    Sets maximum Java stack size for any thread.

    -Xquickstart

    |Improves the startup time of applications . If you do not |specify this option, the initial compilation of methods is done at high |optmization (that is, the JIT does not recompile "hot" methods because the |methods are initially compiled with high optimization).

    -Xrs

    Reduces the use of operating system signals.

    -Xrunlibrary_name[:options]

    Loads helper libraries. To load multiple libraries, specify it more than once on the command line. Examples of these libraries are:
    • -Xrunhprof[:help] | [:<option>=<value>, ...]
      Performs heap, CPU, or monitor profiling.
    • -Xrunjdwp[:help] | [:<option>=<value>, ...]
      Loads debugging libraries to support the remote debugging of applications.

    -Xss<size>

    Sets maximum native stack size for any thread.

    |-Xverbosegclog:<path to |file><filename>[X, Y] |

    |Causes verboseGC output to be written to the specified file. If the |file exists, it is overwritten. Otherwise, if an existing file cannot |be opened or a new file cannot be created, the output is redirected to |stderr. If you specify the arguments X and Y (both are integers) the |verboseGC output is redirected to Y number of files, each containing X number |of gc cycles worth of verboseGC output. These files have the form |filename1, filename2, and so on.
    |Note:
    The environment variable IBM_JVM_ST_VERBOSEGC_LOG has been removed |from this release. |
    |

    -Xverify

    Enables strictest checks, anticipating future default.

    Globalization of the java command

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

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

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

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

    Working with classpaths

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

    Executing a Java file automatically

    To set a java class or jar file to execute automatically from the file use Tools->Folder Options->File Type option of Windows Explorer. Alternatively, at a command prompt type:

    assoc .class=javaclass 
    ftype javaclass=C:\Program Files\IBM\Java141\jre\bin\java.exe %l %*
    

    Notes:

    1. The %l is the letter l and not the number 1.

    2. If your Java is installed in a directory other than C:\Program Files\IBM\Java141\, substitute your directory.

    |How the JVM processes signals

    |When a signal is raised that is of interest to the JVM, a signal handler is |called. This signal handler determines whether it has been called for a |Java or non-Java thread. If the signal is for a Java thread, the JVM |takes control of the signal handling. If the signal is for a non-Java |thread, and the application that installed the JVM had previously installed |its own handle for the signal, control is given to that handler. |Otherwise, the signal is ignored (whether or not this is not the signal's |default action). The exception to this rule is on Windows, where for a |signal generated externally (for example, when you enter CTRL-C or CTRL-BREAK) |a new thread is created to execute the signal handler. In this case, |the JVM signal handler assumes that the signal is for the JVM.

    |For exception and error signals the JVM either: |

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

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

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

    |Signals used by the JVM

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


    |

    |Table 1. Signals used by the JVM

    Signal Name Signal type Description Disabled by -Xrs
    SIGSEGV Exception Incorrect access to memory (write to inaccessible memory) No
    SIGILL Exception Illegal instruction (attempt to invoke an unknown machine instruction) No
    SIGFPE Exception Floating point exception (divide by zero) No
    SIGABRT Error Abnormal termination. The JVM raises this signal whenever it detects a JVM fault. Yes
    SIGINT Interrupt Interactive attention (CTRL-C). JVM exits normally. Yes
    SIGTERM Interrupt Termination request. JVM will exit normally. Yes
    SIGBREAK Control A break signal from a terminal. JVM uses this for taking Java core dumps. Yes

    |Use the -Xrs (reduce signal usage) option to prevent the JVM |from using most signals. For more information, see Sun's Java |application launcher page at http://java.sun.com/j2se/1.4.1/docs/tooldocs/windows/java.html.

    |Signals 2 (SIGINT), 4 (SIGILL), 6 |(SIGABRT), 8 (SIGFPE), 11 (SIGSEGV), and 15 |(SIGTERM) cause the JVM to shut down; therefore, an application |signal handler should not attempt to recover from these unless it no longer |requires the services of the JVM.

    |Linking a native code driver to the signal-chaining library

    |The IBM 32-bit Runtime Environment for Windows, Java 2 Technology Edition, |Version 1.4.1 JVM contains a new signal-chaining |facility. Signal-chaining enables the JVM to interoperate more |efficiently with native code that installs its own signal handlers.

    |The signal-chaining facility enables an application to link and load the |shared library jsig.dll before msvcrt.dll. The |jsig.dll library ensures that calls to signal() are |intercepted so that their handlers do not replace the JVM's signal |handlers. Instead, these calls save the new signal handlers, or "chain" |them behind the handlers that are installed by the JVM. Later, when any |of these signals are raised and found not to be targeted at the JVM, the |preinstalled handlers are invoked.

    |To use jsig.dll, link it with the application that creates or embeds |a JVM.

    Working with the bootclasspath

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

    Specifying garbage collection policy

    The -Xgcpolicy JVM runtime option specifies garbage collection policy.

    The -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 that are caused by garbage collection.

    The format of the option and its values is:

    -Xgcpolicy:optthruput

    and

    -Xgcpolicy:optavgpause

    Pause time

    When an application's attempt to create an object cannot be satisfied immediately from the available space in the heap, the garbage collector is responsible for identifying unreferenced objects (garbage), deleting them, and returning the heap to a state in which the immediate and subsequent allocation requests can be satisfied quickly. Such garbage collection cycles introduce occasional unexpected pauses in the execution of application code. Because applications grow in size and complexity, and heaps become correspondingly larger, this garbage collection pause time tends to grow in size and significance. The default garbage collection value, optthruput, delivers very high throughput to applications, but at the cost of these occasional pauses, which can vary from a few milliseconds to many seconds, depending on the size of the heap and the quantity of garbage.

    Pause time reduction

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

    Environments with very full heaps

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

    Further information about garbage collection

    For more detailed information about garbage collection, see:

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

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

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

    |For information about handling memory leaks in your Java |application, see: http://www.ibm.com/developerworks/library/j-leaks/index.html.


    Runtime example

    The Sun Web site, http://java.sun.com, contains a "Hello World" example that you can download. The example demonstrates how to create a simple Java application that runs on the Runtime Environment.


    Using the Java Plug-in

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


    Supported browsers


    Table 2. Browsers supported by the Java Plug-in

    Operating System Internet Explorer default versions Internet Explorer supported versions Netscape default versions Netscape supported versions
    Windows 98 5.0 (Second Edition) 5.5 SP2, 6.0
    4.77, 6.2.2
    Windows ME 5.5 5.5 SP2, 6.0
    4.77, 6.2.2
    Windows NT 4.0 SP6a
    5.5 SP2, 6.0
    4.77, 6.2.2
    Windows 2000 SP2 5.01 5.5 SP2, 6.0
    4.77, 6.2.2
    Windows XP 6.0 6.0
    4.77, 6.2.2

    Using DBCS parameters

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

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

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

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


    Running Java applications with native assistive technologies

    Sun provides the Java Access Bridge to give native Windows assistive technologies, such as screen readers, access to the Java Accessibility support in a Java application. These native Windows assistive technologies must support calls to the Java Access Bridge.

    The Java Access Bridge available from Sun includes an installer, which places five files in the correct directories: access-bridge.jar, jaccess.jar, accessibility.properties, JavaAccessBridge.dll and WindowsAccessBridge.dll. A copy of jaccess.jar is shipped in the appropriate directory for use with JawBridge.

    If you have already installed the IBM Accessibility Bridge (JawBridge), which allows the Windows 2000 Magnifier to function with Swing applications, and you want it to run at the same time as the Java Access Bridge, edit the line in the accessibility.properties file to read:


    assistive_technologies=com.sun.java.accessibility.AccessBridge, 
    JawBridge
    

    Comment out the line with a leading # to deactivate both bridges. This Web site tells you how to how to download the Java Access Bridge:

    http://java.sun.com/products/jfc/accessibility.html


    Using Web Start

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

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

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

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


    Working with an Input Method Editor

    When working with an Input Method Editor (IME), you are advised that character composition should be completed and the candidate selected before using the workspace for any other operation.


    |Known limitation

    |If you are typing DBCS characters in a JTextArea, JTextField, or |JFileChooser, switching from some Chinese IMEs (in particular, Chinese |Internal Code and Zhengma) to Intelligent ABC IME might cause a core dump to |be produced.


    Any comments on this User Guide?

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

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


    Notices

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

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

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

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

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

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

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

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

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

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

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

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

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


    Trademarks

    IBM is a trademark 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.

    Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.

    Other company, product, or service names may be trademarks or service marks of others.

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