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 IBM Developer Kit for Windows, Java 2 Technology Edition, V1.3.1, 32-bit version, and to all subsequent releases and modifications until otherwise indicated in new editions.
(c) Copyright Sun Microsystems, Inc. 1997, 2001, 901 San Antonio Rd., Palo Alto, CA 94303 USA. All rights reserved.
(c) Copyright International Business Machines Corporation, 1999, 2001. 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 Developer Kit package provided with IBM(R) Developer Kit for Windows(R), Java(TM) 2 Technology Edition, Version 1.3.1, 32-bit version. Use this README file if you want to use the Developer Kit to write Sun Microsystems Java applications and applets.
The Developer Kit is supported on the following products:
The Developer Kit is a development environment for writing applets and applications that conform to the Sun Java 1.3 Core Application Program Interface (API).
In general, any applet or application that ran with version 1.1.7, 1.1.8, or 1.2.2 of the IBM Developer Kit for Windows, Java Technology Edition, or with IBM Cross Platform Technologies for Windows v 2.0 should run correctly with IBM Developer Kit for Windows, Java 2 Technology Edition, Version 1.3.1, 32-bit version. Applets that depend on Java 1.3 APIs do not run on browsers that do not support these APIs or do not have the Java Plug-in installed.
For more details, see the compatibility documentation at the following Sun Web site:
The following list shows the contents of the Developer Kit package.
Do not modify these classes; instead, create subclasses and override where you need to.
Compiles programs written in the Java programming language into bytecodes (compiled Java code).
Executes Java bytecodes. The Java Interpreter runs programs written in the Java programming language.
Use for testing and running applets.
Helps debug your Java programs.
Disassembles compiled files and prints a representation of the bytecodes.
Parses the declarations and documentation comments in a set of source files and produces a set of HTML pages describing the public and protected classes, interfaces, constructors, methods, and fields. Also produces a class hierarchy and an index of all members.
Converts a HTML page that contains applets to a format that can use the Java Plug-in.
Attaches native methods to code written in the Java programming language.
Generates signatures for Java Archive (JAR) files, and verifies the signatures of signed JAR files.
Manages entities, including their keys, certificates, and the trust associated with them.
Manages a keystore (database) of private keys and their associated X.509 certificate chains authenticating the corresponding public keys.
Creates and modifies the external policy configuration files that define your installation's Java security policy.
Converts a native encoding file to an ASCII file that includes the \udddd Unicode notation; also converts in the opposite direction.
Generates objects from the names of compiled classes that contain remote object implementations. Includes RMI-IIOP support. (IIOP stands for Internet Inter-ORB Protocol.)
Starts the activation system daemon so that objects can be registered and activated in a Java virtual machine (JVM).
Compiles Object Management Group (OMG) Interface Definition Language files to Java code.
Starts the CORBA transient naming service.
Creates and starts a remote object registry on the specified port of the current host.
Returns the serialVersionUID for one or more classes in a form that is suitable for copying into an evolving class.
Detects version conflicts between a target jar file and currently installed extension jar files.
The demo directory contains a number of subdirectories containing sample source code, demos, applications, and applets, which you may use.
This file, readme.devkit.ibm.html, which is in the docs subdirectory of the directory where you installed the Developer Kit.
README file for the Runtime Environment. This file is in the docs subdirectory of the directory where you installed the Developer Kit. The file name is readme.runtime.ibm.html.
Copyright notice for the Developer Kit software, which is in the directory where you installed the Developer Kit.
License agreement for the Developer Kit software, which is in the docs directory.
Note: These README files and the accompanying copyright files and demo directories are the only documentation included in this Developer Kit. To download the Sun Java Software Development Kit (SDK) documentation package, see the following Sun Web site.
The documentation package is designed to be extracted into the directory where you installed the Developer Kit. If you download the zip file archive version, be sure to preserve the path names when you extract the files from the archive. If you use pkunzip, specify the -d option.
The following sections provide information about using the Developer Kit.
The (JIT) compiler (jitc.dll) dynamically generates machine code for frequently used bytecode sequences in a Java application or applet during execution.
The JIT is enabled by default. All Developer Kit tools use the JIT by default. After installation, you can specify whether or not you want to use the JIT. You can disable the JIT to help in the isolation of a problem with a Java application, an applet, or the compiler itself.
There are two ways to disable the JIT:
set JAVA_COMPILER=NONE
On Windows NT, Windows 2000, and Windows XP, you can also permanently set JAVA_COMPILER from the Environment settings of the System properties. (For Windows NT, select the Control Panel, and click System and then click Environment. For Windows 2000 and Windows XP, select the Control Panel and System, and on the Advanced tab select Environment Variables).
java -Djava.compiler=NONE myapp
To enable the JIT, type the following at a command prompt:
set JAVA_COMPILER=jitc
To determine if the JIT is enabled, type the following command at a command prompt:
java -version
If the JIT is not in use, a message is displayed that includes the following:
JIT compiler "jitc" not found.
If the JIT is in use, a message is displayed that includes the following:
JIT enabled: jitc
The Java tools are Windows programs that are run from a command prompt. After installing the Developer Kit software, you run a tool by typing its name at a command prompt with a filename as an argument.
You can specify the path to a tool by typing the path in front of the tool each time. For example, if the javac compiler is in C:\Program Files\IBM\java131\bin, you can compile a file named myfile.java by typing the following at a command prompt:
C:\Program Files\IBM\java131\bin\javac myfile.java
Alternatively, you can add the string C:\Program Files\IBM\java131\bin to your PATH statement. Then, you can compile the myfile.java file by typing the following at a command prompt:
javac myfile.java
The PATH statement enables Windows to find the executable files (such as javac.exe, java.exe, javadoc.exe) from any directory. To find the current value of your PATH, type the following at a command prompt:
path
To change the PATH statement on Windows 98 or Windows ME, edit the AUTOEXEC.BAT file using a text editor.
Look for the PATH statement in the autoexec.bat file. Notice that the PATH statement is a series of directories separated by a semicolon (";"). Windows looks for programs in the PATH directories in order, from left to right. Add the Developer Kit directory to the end of the PATH statement. For example:
PATH C:\WINDOWS;C:\WINDOWS\COMMAND;C:\;C:\DOS;C:\Program Files\IBM\Java131\bin;
Restart the system.
To change the PATH statement on a Windows NT system;
Previously opened Command Prompt windows do not reflect the changes; close and reopen the Command Prompt windows to see the changes.
To change the PATH statement on a Windows 2000 or Windows XP system;
Previously opened Command Prompt windows do not reflect the changes; close and reopen the Command Prompt windows to see the changes.
The CLASSPATH tells the JVM and
other applications located in the
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 only if you move the classes provided by the JVM, or if you want to use other classes (such as classes you develop).
Note: If you have installed more than one version of the Developer Kit (for example, versions 1.1.8 and 1.3.1) and you want to develop applications in more than one version, you must set the CLASSPATH and PATH separately for the different versions. To run different versions simultaneously, you can run them in separate Command Prompt windows. If you are running only one version at a time, you can write a batch script to switch the values of CLASSPATH and PATH.
To see if the CLASSPATH is set, type the following (based on the platform you are using) at a command prompt:
echo %classpath%
set classpath
To set the CLASSPATH to include a particular class of an application, follow this model:
set classpath=[C:\java\apps\classes];%classpath%
where [C:\java\apps\classes] is the drive and path to the application and its classes.
To reset the CLASSPATH to null and remove unwanted classes, type the following at a command prompt:
set classpath=
To make permanent changes to the CLASSPATH on Windows 98 and Windows ME, edit the startup file (AUTOEXEC.BAT) so that it contains the preceding command. On Windows NT, Windows 2000, and Windows XP, the Control Panel can be used to permanently change the CLASSPATH in the same way that you change the PATH. See Changing the PATH Statement on Windows NT or Changing the PATH Statement on Windows 2000 or Windows XP.
The IBM build and version number can be obtained by typing the following at a command prompt:
java -version
To debug Java programs, you can use the Java Debugger (JDB). This debugger interfaces with the Java Platform Debugger Architecture (JPDA) provided by the IBM Developer Kit for Windows, Java 2 Technology Edition, Version 1.3.1 package.
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 Windows.
A JDB debugger is included in the Developer Kit. The JDB starts com.sun.tools.example.debug.tty.TTY. The Java Virtual Machine Debugging Interface (JVMDI) is fully supported. The jdb tool included in Version 1.2.2 is included as oldjdb.
The 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: < PRE>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, make sure that the specified ports are actually free to use.
Note: Sun's documentation for using jdb assumes that the JVM to be debugged is a HotSpot JVM. However, IBM implementations of the JVM always run as a Classic JVM. 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.
The Applet Viewer allows you to 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 command prompt:
appletviewer name
where name
is one of the following:
For example, to invoke the Applet Viewer on a HTML file that calls an applet, type the following at a command prompt:
bin\appletviewer demo\GraphLayout\example1.html
where bin
is replaced by the full path to the
Developer Kit's bin directory.
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 command prompt:
bin\appletviewer http://java.sun.com/applets/NervousText/example1.html
where bin
is replaced by the full path to the
Developer Kit's bin directory.
You can debug applets using the -debug option of the Applet Viewer. When debugging applets, it is best to invoke the Applet Viewer from the directory that contains the HTML file that calls the applet. For example:
cd demo\TicTacToe bin\appletviewer -debug example1.html
where bin is replaced by the absolute path to the Developer Kit's bin directory.
Documentation for the debugger and its API can be found at the following Sun Web site:
You can specify Java options and system properties by creating an environment variable called IBM_JAVA_OPTIONS and setting it to the values you require. Any Java options or system properties specified must be preceded by a space, except for the first option. For example, you could set IBM_JAVA_OPTIONS as follows:
IBM_JAVA_OPTIONS=-Dmysysprop1=tcpip -Dmysysprop2=wait
If you specify the same options or properties from the command line (or from a JNI program), these take precedence over the options and properties specified by the IBM_JAVA_OPTIONS environment variable. The only exception to this rule is when specifying -Xt, -Xtm, or -Xdebug, all of which imply that no JIT should be used.
Notes:
If you use the Applet Viewer or the Java Plug-in to run an applet that is in the CLASSPATH, you might get an AccessControlException in Swing. Because the CLASSPATH implicitly contains the current directory (.), this exception can also occur if you run the Java Plug-in in the same directory as the applet class itself.
To work around this problem, make sure that:
IBM Developer Kit for Windows, Java 2 Technology Edition, Version 1.3.1, 32-bit version 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.
IBM Developer Kit for Windows, Java 2 Technology Edition, Version 1.3.1, 32-bit version adds support for these CORBA specifications:
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://cgi.omg.org/cgi-bin/doc?formal/99-10-07
Bi-directional GIOP is not supported.
This Developer Kit supports Portable Interceptors, as defined by the OMG in the document formal/01-09-58, which you can obtain from:
http://cgi.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.
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://cgi.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 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":
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.
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 named output.trc:
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.
The following properties help you to tune the ORB:
The default fragment size is 1024 bytes. You can turn off fragmentation by setting the fragment size to 0.
By default, the ORB waits indefinitely for a response. Do not set the timeout too low, or connections might be ended unnecessarily.
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 CORBA standard Internet Inter-ORB Protocol (IIOP protocol). This protocol 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 Developer Kit 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.
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 might include the following parts:
The Java Runtime Environment provided with IBM Developer Kit for Windows, Java 2 Technology Edition, Version 1.3.1, 32-bit version can be redistributed with your application. For information, see the IBM Runtime Environment for Windows, Java 2 Technology Edition, Version 1.3.1, 32-bit version README.
If an application or applet fails to function correctly and reports a security exception, there are a number of possible reasons for the failure because of the highly configurable nature of the software. The following points might help you to work out the cause of the exception:
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 will determine what services, if any, you are entitled to receive with respect to the Program.
Note these limitations in IBM Developer Kit for Windows, Java 2 Technology Edition, Version 1.3.1, 32-bit version:
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.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.
Other company, product, and 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.