Readme for the JDK 1.1.8 Windows NT Alpha

The Java Development Kit (JDK) lets you write applets and applications that conform to the Java Core Application Program Interface (API).

IMPORTANT:

Release Notes Information

The JDK 1.1.8 is primarily a bug-fix release. See the changes file for a list of fixes made by Sun for this and previous releases of the JDK. The following section describes fixes made by Compaq for this release.

Problems Fixed in the Compaq JDK 1.1.8

There are no Alpha specific changes to this JDK 1.1.8.

Known Problems

When using the JDK V1.1.8 release, you may experience the following known problems:

 

Readme Contents

Overview of the Java Development Kit

Installing and Running the JDK Software

Class Load Hook

Euro Support

Data Transfer Problems on Windows

Deploying Java Applications

Submitting Comments

Support and Problem Reporting


OVERVIEW OF THE JAVA DEVELOPMENT KIT

INTRODUCTION

The Java Development Kit is a development environment for writing applets and applications that conform to the Java 1.1 platform. Its compiler and other tools are run from a shell and have no GUI interface. This version includes improvements in functionality, performance, and quality over version 1.0.2 of the Java platform, including bug fixes since the previous release of the 1.1 platform.

This is a maintenance release. Changes Sun has made to the JDK software since the first 1.1 beta release are in the file named changes.

Because there are no API changes in maintenance releases, we continue to refer to this platform as the Java platform 1.1 (rather than 1.1.8). While bugs have been fixed in version 1.1.8, the platform hasn't changed.

The Java platform 1.1 offers capabilities over the 1.0 platform: Internationalization, signed applets, JAR file format, AWT (window toolkit) enhancements, JavaBeans™ component model, networking enhancements, Math package for large numbers, Remote Method Invocation (RMI), Reflection, database connectivity (JDBC), new Java Native Interface, Object Serialization, Inner Classes, and performance enhancements.

A JIT bytecode compiler is included in the JDK software. All tools in the JDK software use the JIT by default. To disable the JIT, see Using the JIT Compiler.

As part of our ongoing effort to improve the quality of the JDK software, we will continue to fix bugs and develop new features. In order to help us prioritize our bug-fixing effort, please submit any bugs you find as soon as possible, using the procedure described in the Support and Problem Reporting section below.

 

VERSION COMPATIBILITY

In general, any applet or application that ran in previous versions of the Java Development Kit should run correctly in version 1.1.8. A failure to do so is a bug, except for a small number of cases where compatibility has had to be broken to close potential security holes or fix implementation or design bugs.

Of course, applets that depend on any new 1.1 APIs will not work on any browsers that support only 1.0.2, such as Internet Explorer 3.0 and Netscape 3.0. However, in general, applets relying only on APIs defined in 1.0.2 (but compiled with the JDK 1.1 compiler) will run on 1.0.2 browsers. This "downwards" compatibility has not been extensively tested and cannot be guaranteed. For more details, see the document on compatibility at:

http://java.sun.com/products/jdk/1.1/compatibility.html

If you find any such incompatibilities that are not listed on the Compatibility web page, please report them to us as noted below under Support and Problem Reporting; and mention that they are compatibility bugs.

 

WHAT THE JDK SOFTWARE CONTAINS

1) RUNTIME

DO NOT UNZIP THIS FILE! It must remain zipped for the compiler and interpreter to access the class files within it properly. This file contains all of the the compiled .class files for the platform.

2) SOURCE FILES

Do not modify these classes; instead, create subclasses and override where you need to.

The source files are automatically unzipped for you during installation.

3) TOOLS

4) JAVA DOCUMENTATION AND DEMOS

awt-1.1
i18n
Animator
ArcTest
BarChart
Blink
CardTest
Clock
DitherTest
DrawTest
Fractal
GraphLayout
GraphicsTest
ImageMap
JumpingBox
MoleculeViewer
NervousText
SimpleGraph
SortDemo
SpreadSheet
TicTacToe
WireFrame
AWT demos
Internationalization demos
General-purpose animator
Test arc drawing and filling
Simple bar-chart applet
Blinking, multicolored text
Test card layout manager
Analog clock
Test image dithering
Draw points and lines
Fractal figures
Graph layout by iterated relaxation
Test graphics operations
Live-feedback image map
Catch the jumping box
Three-dimensional chemical model viewer
Nervous text
Draw a simple graph
Animated sorting algorithms
Simple spreadsheet
Tic-tac-toe game
Three-dimensional wire-frame model viewer

RMI demos are available in the separately-downloadable JDK documentation. See the entry "Demonstration Applets and Applications" in the JDK documentation table of contents for access.

NOTE: The JDK software does NOT include a Web browser. To obtain the HotJava(tm)Browser, see the HotJava Browser web page:

http://java.sun.com/products/hotjava/

 

WHERE TO FIND MORE INFORMATION

This Readme file and the accompanying changes, license, copyright  files, demo directory, and source code (src.zip) are the only "documentation" included in this JDK software bundle. You can download the JDK Documentation Bundle from:

http://www.compaq.com/java

The JDK Documentation Bundle includes:

The Documentation Bundle is designed to be extracted into the JDK software installation directory. If you download the ZIP archive version, be sure to preserve the file path names when you extract the files from the archive. (With pkunzip, specify the -d option.)

If you are new to the Java programming language, you will want to browse or download the Java Tutorial at:

http://java.sun.com/docs/books/tutorial/

 

JAVABEANS(TM) AND THE BEANS DEVELOPMENT KIT

A version of the Beans Development Kit (BDK) is also available for immediate download from JavaSoft. BDK includes specific tools and support for JavaBeans developers such as the BeanBox test containers and example beans. See:

http://java.sun.com/beans/bdk_download.html

Updates to the BDK, tools, and general JavaBeans information are posted on a regular basis to the JavaBeans web site:

http://java.sun.com/beans


INSTALLING AND RUNNING THE JDK SOFTWARE

INSTALLATION NOTES

IMPORTANT: Please make sure you understand the Copyright and License information (in the files named copyright and license) before installing this release.

The JDK software and documentation are available in two separate downloadable compressed files, called "bundles". They need to be downloaded separately into the same directory and unpacked as follows for the few html links between them to work.

Here are the instructions:

  1. Go to the download page for the Java Development Kit and download the software:
    http://www.digital.com/java/download/index.html
  2. Go to the download page for the Java Development Kit and download the documentation separately:
    http://www.digital.com/java/download/index.html

  3. Install the software first, then the documentation bundle.

  4. To install the software:

    1. Run the JDK software installer, if necessary.

      To run the JDK software installer, double-click on the icon for this file. Follow the instructions the installer provides.

    2. When done with the installation, you can delete the downloaded bundle to recover disk space.

    Installed Directory Tree

    The JDK software and documentation directories will have the following structure. The docs directory and its contents will not be installed until you download and unbundle the JDK software documentation.

                             
                               jdk1.1.8
          _________________________|________________
         |    |    |     |  |   |   |     |  |  |   |
       README |    |     | bin lib  |   demo | docs |
           CHANGES |     |  |   | include | src |   |
               COPYRIGHT |          |     |  |      |
                      LICENSE                   index.html
                                  
    

    Included in the unbundled files is a file lib/classes.zip. DO NOT UNZIP THE CLASSES.ZIP FILE. This file contains all of the core class binaries, and must remain in its zipped form for the JDK software to use it.

  5. To install the documentation:

    Unbundle the JDK software bundle and the JDK documentation bundle in the same directory to ensure that HTML links between the bundles will work properly.

    1. Determine where to put the documentation before unbundling it.

      By default, unbundling the JDK documentation creates a jdk1.1.8 directory with a docs subdirectory, putting all the documentation inside that docs directory, as shown in the figure below.

      WinZip lets you determine where the docs will be installed during the installation -- Choose the same directory where the JDK software was installed.

      If you are not using WinZip, continue with the rest of this step:

      • If you have already installed the JDK 1.1.8 software, you should put the documentation bundle in the parent directory of the jdk1.1.8 directory. Then when you unbundle it, the links to the files in the software bundle will work.

        For example:

        If your jdk1.1.8 directory is located at C:\jdk1.1.8, then place your documentation bundle in C:\ before unbundling it.

      • If you have not yet installed the JDK 1.1.8 software, unbundle the documentation bundle in the directory where you want the jdk1.1.8 subdirectory to reside.

    2. Unbundle your documentation

      Unbundle the documentation using the appropriate utility: WinZip, unzip, pkunzip. (Your utility must support long filenames.)

      For .zip files:

           C:> unzip jdk118-doc.zip 
      

      Note: If you're using another tool that does not preserve path names by default, be sure to specify that path names be preserved. If you are using pkunzip, specify -d:

           C:> pkunzip -d jdk118-doc.zip
      

      Unbundling the documentation bundle creates a jdk1.1.8/docs/ directory containing your JDK documents, as shown below.

    3. View the documentation:

      Open the jdk1.1.8/docs/index.html page in a browser. This is the front page of the JDK documentation.

    Installing the JDK software and documentation creates the following directory structure. The directories shown in bold are installed with the JDK documentation bundle:

    
                             jdk1.1.8
        _________________________|_____________________________________
       |      |         |      |      |   |     |     |    |    |      |
    README CHANGES COPYRIGHT LICENSE bin lib include demo src docs index.html
                                      |   |     |     |    |    |
                                                                |
                                   _____________________________|_____
                                  |       |        |       |          |
                                 api  tooldocs relnotes  guide   index.html
                                  |       |        |       |
    

    If you don't unbundle the documentation at the proper directory, the HTML links from docs/index.html to the README, CHANGES, COPYRIGHT, LICENSE, and demo files will be broken.

  6. Set the PATH and CLASSPATH for Windows as described in the section that follows.

Running JDK Tools in Microsoft Windows

After installing the JDK software, you start a tool by typing its name into the DOS window with a filename as an argument. None of the main JDK tools have GUI interfaces -- they are all run from the DOS command line. (For example, if you double-click on the compiler "javac" icon, it will briefly open and immediately close a DOS window, because that is not the proper way to run it.)

You can specify the path to a tool either by typing the path in front of the tool each time, or by adding the path to the startup file(autoexec.bat). For example, if the JDK software is installed at C:\jdk1.1.8, to run the compiler on a file myfile.java, go to a DOS shell and execute this:

Type: C:\jdk1.1.8\bin\javac myfile.java
-or-
Add C:\jdk1.1.8\bin to your path statement
Type: javac myfile.java

See the next section about setting the PATH and CLASSPATH variables.

Microsoft Windows PATH and CLASSPATH

The CLASSPATH is not required, but if it is set, it will need to be unset. You may want to update the "path" variable for convenience.

It is preferable to make the following environment variable changes in the Control Panel. Start the Control Panel, select System, then edit the environment variables:

  1. PATH - You may want to set the PATH variable for convenience. Add the absolute path of the "jdk1.1.8\bin" directory to your PATH statement as follows.

    The PATH statement enables Windows to find the executables (javac, java, javadoc, etc.) from any current directory.

    To find out the current value of your PATH, at the DOS prompt type:

         C:\> path
    

    To change the PATH, open the AUTOEXEC.BAT file and make the change to the PATH statement. To edit the AUTOEXEC.BAT file in Microsoft Windows 95 or Microsoft Windows 98:

    1. Start a text editor by choosing "Start", "Programs", "Accessories", and choosing WordPad or NotePad.

    2. Choose Open from the File menu and type "c:\autoexec.bat" for the filename This will open the file for editing.

    3. Look for the PATH statement. Notice that the PATH statement is a series of directories separated by semi-colons (;). Windows looks for programs in the PATH directories in order, from left to right. Look for other versions in the PATH. There should only be one path to a classes.zip file. When in doubt, put the java directory at the end of the path statement. For example, in the following PATH statement, we have added the java directory at the end:
           PATH C:\WINDOWS;C:\WINDOWS\COMMAND;C:\;C:\DOS;C:\JDK1.1.8\BIN 
      

    To make the path take effect, execute the following:

         C:\> autoexec.bat
    

  2. CLASSPATH Environment Variable

    The CLASSPATH environment variable tells the Java development tools where to find Java class files such as those in classes.zip and any class files used by applications that you write. If the CLASSPATH environment variable is not set, the following is used as a default class path:

         .;[bin]\..\classes;[bin]\..\lib\classes.zip
    

    In this expression, [bin] is substituted by the absolute path to the jdk1.1.8\bin directory. Note that this default class path includes '.', the current directory and the classes.zip file for the Java platform api. This means that you do not have to (and shouldn't) set the CLASSPATH environment variable when the .class files you want to use are all in the current directory.

    UNSETTING CLASSPATH

    If you have previously set the CLASSPATH and want to unset it, you normally need to change the current value (at the command line) and the startup value (in a startup file or script). For example, to see if it is currently set, type:

         % set
    

    This lists all of the environment variables. CLASSPATH will not appear if it is not set.

    If it is set, you can unset the current value by setting it to no value:

         % set CLASSPATH=
    

    Also open your startup file (autoexec.bat) or script and remove the path to the Java platform classes from the CLASSPATH environment variable, if you want the change to be permanent.

Refer to the Windows Installation Troubleshooting section below if you have problems running the JDK software.

For more information, see the CLASSPATH entry in the tools subdirectory of the installed documentation bundle.

Using the JIT Compiler

The Just In Time (JIT) bytecode compiler converts virtual machine bytecodes to native instructions before execution. This can cause some delay in program startup and class file loading, but can also reduce overall program execution time by a factor of ten.

In the Win32 version of the Java Development Kit, the JIT is part of the JDK software and is invoked by default. Should you ever want to disable the JIT compiler, you can do so by setting the java.compiler property to NONE:

   java -Djava.compiler=NONE MyClass

This method of disabling the JIT compiler works with both this release of the Java Development Kit and with the JDK 1.2 software. It is the recommended method for disabling the JIT. In this version of the Java Development Kit, you can also disable the JIT compiler by using the -nojit command-line option:

   java -nojit MyClass
   jre -nojit MyClass

Some JDK tools, such as appletviewer, run by invoking a launcher. To use these tools without the JIT, uses the -J option to pass the -nojit option to the launcher:

   appletviewer -J-nojit mypage.html

With the java tool, setting JAVA_COMPILER also affects JIT usage. The jre tool ignores JAVA_COMPILER. Both tools also use the java.compiler property to determine JIT usage. See the appropriate tool documentation.

Microsoft Windows Installation Troubleshooting

Here are some troubleshooting tips for Microsoft Windows:

  1. set HOMEDRIVE=c:

      set HOMEPATH=\

    and restart the AppletViewer (in the same DOS box)

  2. set HOME=c:\

    and restart the AppletViewer (in the same DOS box)

If none of these work, try:

      java -verbose sun.applet.AppletViewer
  

This lists the classes that are being loaded. From this output, you can determine which class the AppletViewer is trying to load and where it's trying to load it from. Check to make sure that the class exists and is not corrupted in some way.

If you are getting one of these fatal error messages when running java, javac, or appletviewer, you should check your CLASSPATH environment variable. It may list "c:\java" or the "classes" directory from an older release. You can either unset the CLASSPATH variable, or set it to include only the latest version of the Java platform class library. For example:

       C:\> set CLASSPATH=.;C:\jdk1.1.8\lib\classes.zip
  

This will make sure that you are using the correct classes for this release.

 

RUNNING APPLETS WITH THE APPLETVIEWER

AppletViewer allows you to run one or more applets that are called by reference in a web page (HTML file) using the APPLET tag. The AppletViewer finds the APPLET tags in the HTML file and runs the applets (in separate windows) as specified by the tags.

AppletViewer is for viewing applets. It cannot display an entire web page that contains many HTML tags. It parses only the APPLET tag and no other HTML on the web page.

To run an applet with appletviewer, you go to a command line for your operating system and run appletviewer, passing in the filename or URL of the web page as its argument.

EXAMPLE

Here is an example of how to invoke AppletViewer on a file-based web page in Windows. Go to a DOS prompt, change to the "jdk1.1.8" directory and then execute:

      bin\appletviewer demo\GraphLayout\example1.html
  

Here is an example of how to invoke AppletViewer on a URL-based web page in Windows. Execute:

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

 

INNER CLASSES AND JAR FILES

Many users have reported problems using appletviewer to run applets when the applet classes are located in a JAR file. The applet class throws an IllegalAccessError when trying to access its own inner class. The same applet runs without error when all the class files are located on the file system.

This error occurs because the main applet class and the applet inner class have different class loaders. This can happen when the JAR file and the original class files are located in the same directory. It can also happen when the same JAR file is passed to appletviewer twice: once as an ARCHIVE attribute in an APPLET tag, and again in the class path. In both cases, the applet class loader loads the applet class, while the system class loader loads the inner class.

When running an applet from a JAR file, make sure that the classes files are only available in the JAR file, and that the JAR file is not in the class path.

This problem only occurs on the Java 1.1 platform. On the Java 1.2 platform, improvements in the class loading mechanism avoid this problem.

DEBUGGING PROGRAMS WITH THE DEBUGGER (JDB)

You can debug applets using the -debug option of appletviewer. When debugging applets, it's best to invoke appletviewer from the directory that contains the applet's HTML file. For example,

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

You can find documentation on the debugger and its API at:

http://java.sun.com/products/jdk/1.1/debugging/

 

CLASS LOAD HOOK

This release supports use of a class load hook, a native-code function called when each class is loaded. A class load hook can modify the class data to include profiling or debugging information. This feature was requested by development tool vendors.

Support for a class load hook is a temporary feature and is subject to change. Class load hook support is not part of the Java platform specification and will not be available in any 1.2 version of the JDK software. JDK 1.2 software includes profiling and debugging features that are more powerful and general.

CONFIGURING A CLASS LOAD HOOK

If the environment variable _CLASSLOAD_HOOK is set, its value should be the basename of a native code library. For example, if the value of _CLASSLOAD_HOOK is "myhook", the runtime looks for a Windows library called myhook.dll. The runtime looks in the bin directory of the JDK installation, then in each directory in the PATH environment variable for the library.

THE CLASS LOAD HOOK API

The class load hook library must export the following function:

typedef struct {
    unsigned char *class_data; 
    int            class_data_len; 
    unsigned char *new_class_data;
    int            new_class_data_len;
    void *       (*malloc_f)(int);
} classload_event;
void ClassLoadHook(classload_event *);

The runtime calls ClassLoadHook() after it obtains the class file data but before it constructs the in-memory class representation.

ClassLoadHook() is passed the existing class file data (via class_data and class_data_len), and a pointer to a memory allocation function (via malloc_f). ClassLoadHook() should use the memory allocation function to create a new buffer for the modified class file data and return it via new_class_data and new_class_data_len. If ClassLoadHook() chooses not to modify a class, it should set new_class_data to NULL.

The runtime is responsible for deallocating the modified class file data buffer.

EURO SUPPORT

This release of the Java Development Kit includes support for the new European Union currency, the euro. If you download and install the JDK documentation bundle, you will find this file at docs/guide/intl/euro.html.

DATA TRANSFER PROBLEMS ON WINDOWS

A bug in the data transfer API (4032895) prevents most objects from being copied to the Win32 clipboard. A common workaround is to convert objects to a String representation, since String objects are not affected by this bug.

One popular technique for converting an object to a string is to write the object into a ByteArrayOutputStream and convert the stream to a String with toString(). String.getBytes() reverses the process.

There is a potential problem with this kind of byte/character conversion. Both toString() and getBytes() rely on a locale-specific character encoder to translate byte values to and from Unicode character values. Not all encoders assume a one-to-one relationship between byte values and character values. To ensure a reliable translation, do not rely on the default locale encoder. Explicitly specify an encoder that uses a reversible translation, such as ISO8859_1. Do this by passing the encoder name to toString() and getBytes():

aString = aStream.toString("ISO8859_1");
aByteArray = aString.getBytes("ISO8859_1");

In releases prior to JDK 1.1.7, the need to use a reversible encoding was not apparent to most programmers. ISO8859_1 was the default encoder for western locales on Win32. A program's dependence on ISO8859_1 might not be apparent if the program was not tested under a non-western locale.

JDK software running on Win32 machines uses Cp1252 (Windows Latin-1) as the default encoding for western locales. Cp1252 does not implement a reversible byte/character translation. It may appear to some programmers that JDK 1.1.7 introduces an incompatibiity. The real problem is a programming technique that unintentionally relies on the features of specific locales.

DEPLOYING JAVA APPLICATIONS

A Java application, unlike a Java applet, cannot rely on a web browser for installation and runtime services. When you deploy a Java application, your software bundle will probably consist of the following parts:

The first item, you already have, of course. The remainder of this section covers the other two items.

RUNTIME ENVIRONMENT

To run your application, a user needs a Java virtual machine, the Java platform core classes, and various support programs and files. This collection of software is known as a runtime environment.

The JDK software serves as a runtime environment. However, you probably can't assume your users have the JDK software installed, and your JDK software license doesn't allow you to redistribute JDK software files.

Compaq provides a free, redistributable runtime environment for Windows NT on Alpha called the Java Runtime Environment (JRE).  A version of this JRE is available at:

http://www.compaq.com/java/

The Java Runtime Environment for Win32 is available both with and without international support. The non-international version is much smaller, but is suitable only for English-speaking users.

INSTALLATION

The final step in the deployment process occurs when the software is installed on individual user system. Installation consists of copying software onto the user's system, then configuring the user's system to support that software.

This step includes installing and configuring the runtime environment. If you use the Java Runtime Environment, you must make sure that your installation procedure never overwrites an existing installation, unless the existing Java Runtime Environment is an older version.

The Win32 version of the Java Runtime Environment is distributed as a self-installing executable. A simple way to redistribute the Java Runtime Environment is to include this executable in your software bundle. You can then have your installation program run the executable, or simply instruct the user to install the Java Runtime Environment before installing the rest of your bundle.

The Win32 installation program records program information in the Windows Registry. This registry information includes the software version, which you should compare with the Java Runtime Environment version in your software bundle. For more information, refer to the Java Runtime Environment Notes for Developers at:

www.digital.com/java/download/jre_nt/1.1.8/jre118_runtime.html

A more sophisticated approach is to install the Java Runtime Environment on your own system, then copy the files you need into your own installation set. If you choose this approach, you must include all files described as "required" in the Java Runtime Environment README. The Java Runtime Environment software can only be redistributed if all "required" files are included. See the LICENSE file for specifics.

If you use this approach, do not try to emulate the installation steps performed by the Java Runtime Environment installer. You might "break" an existing Java Runtime Environment installation by missing a new or undocumented installation step. Instead, you should include the Java Runtime Environment files in your own application directory. In effect, your application has its own "private" copy of the Java Runtime Environment.

SUBMITTING COMMENTS

We are very interested in receiving your comments and suggestions as early as possible.   If you have a specific feature request or bug to report, please refer to the next section for how to submit it. Send other comments and informal suggestions directly to us at:

java-info@zko.dec.com

SUPPORT and PROBLEM REPORTING

Telephone support is available for the JDK and JRE on Alpha systems running Windows NT. Software Telephone Support provides software usage assistance as well as advisory and remedial support. Support is provided via access to the DIGITAL technical databases and electronic or telephone communications from 8-8 ET Mon-Fri. Support pricing is based on a one-year contract and, in the USA, is priced at $50 per month for the development environment (specify part number QT-66ZAA-ZA) and $5 per month for the runtime (part number QT-670AA-ZA).

In the U.S. please contact Sales Help Line at 1-800-DECSALE or AMCS Pre-Sales at 1-800-DIGITAL, or 1-800-277-8988. In Australia and New Zealand, please call the CCS Help Desk 1-800-500-255. In the Netherlands the phone number of the CCS Pre-Sales unit is 030-2834567.

Customers who do not have support contracts are encouraged to continue to mail problem reports, using the problem report template ( http://www.digital.com/java/contact/bugreport.txt), to java-bugs@zko.dec.com. These reports will certainly be used as a source of input for fixing problems for new releases, however, we will only be able to give these reports individual attention and take remedial action on a best-effort basis.

You can look for updates to this kit when new revisions become available at our Java web site at
http://www.compaq.com/java/.