README
The Java(tm) Development Kit
JDK(tm) 1.1
-----------------------------------------------------------------------
CONTENTS
Overview of Java
- Introduction
- Purpose
- Version Compatibility
- Bug Fixes
- What the JDK Contains
- Where to Find More Information
- Submitting Comments
- Reporting Bugs and Requesting Features
- JavaBeans(tm) and the Beans Development Kit
Installing and Running Java
- Installation Notes
- Windows PATH and CLASSPATH
- Windows Installation Troubleshooting
- Solaris PATH and CLASSPATH
- Solaris Installation Troubleshooting
- Running Applets with the AppletViewer
- Debugging Programs with the Java Debugger
=======================================================================
OVERVIEW OF JAVA
=======================================================================
-----------------------------------------------------------------------
INTRODUCTION
-----------------------------------------------------------------------
Thank you for downloading the JDK 1.1 release.
This is version 1.1 of the Java Development Kit, also known as JDK 1.1.
The JDK lets you write applets and applications that conform to
the 1.1 Java Core API. It includes improvements in functionality,
performance, and quality over JDK 1.0.2.
JDK 1.1 offers new capabilities: Internationalization, signed applets,
JAR file format, AWT (window toolkit) enhancements, JavaBeans(tm)
component model, networking enhancements, Math package for large
numbers, Remote Method Invocation, Reflection, database connectivity,
new Native Method Interface, object serialization, Inner
Classes, and performance enhancements.
For further description of these features, see the "New Feature
Summary" in the JDK documentation.
The changes made to the JDK since the first 1.1 beta release
are in the file named CHANGES.
We are planning at least one follow-on bug-fix release, called JDK 1.1.1,
so please submit any bugs you find as soon as possible, using the
procedure described in the "Reporting Bugs" section below.
We also publish a web page of technology related to the JDK, which
includes information about Java IDL, native threads, and
OS platforms. Please refer to:
http://java.sun.com/products/JDK/1.1/jdkrelatedtech.html
The JDK is a product of Sun Microsystems, Inc.
JavaSoft is the operating company of Sun that develops the JDK.
-----------------------------------------------------------------------
PURPOSE
-----------------------------------------------------------------------
The JDK allows you to:
- Develop applets that will run in browsers supporting Java 1.1,
such as HotJava version 1.0, and future versions of Netscape
Navigator and Microsoft Internet Explorer.
- Develop Java applications.
-----------------------------------------------------------------------
VERSION COMPATIBILITY
-----------------------------------------------------------------------
In general, any applet or application that ran in JDK 1.0.2 should
run correctly in JDK 1.1. 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,
Netscape 3.0, and the alpha and pre-beta1 versions of the HotJava
browser. 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 "Reporting Bugs," and mention that they are compatibility
bugs. Compatibility is critically important to us, and a cornerstone
of Java's "Write Once Run Anywhere" promise.
-----------------------------------------------------------------------
BUG FIXES
-----------------------------------------------------------------------
As with any release, we will continue vigorously testing and
debugging the JDK. If we uncover any important bugs, we will
post them at "Known Bugs", which is a bug list that we periodically
update. This web page can be found at
http://java.sun.com/products/JDK/1.1/knownbugs/
For a list of important bugs fixed during the beta cycle,
see "Fixed Bugs" posted at:
http://java.sun.com/products/JDK/1.1/fixedbugs/
We are planning on an upcoming bug-fix release that will
incorporate fixes to JDK 1.1. This release will be called:
JDK 1.1.1
As always, your comments and bug reports are important to making
future releases successful. We will use your feedback to help
plan future releases. Please report bugs, request features and
submit comments using the procedure noted below in the sections
"Submitting Comments" and "Reporting Bugs and Requesting Features".
-----------------------------------------------------------------------
WHAT THE JDK CONTAINS
-----------------------------------------------------------------------
JAVA RUNTIME ----------------------------------------------------------
- Java Core Classes (classes.zip)
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 JDK.
- Java Interpreter (java)
Executes Java bytecodes. In other words, runs programs
written in the Java programming language.
JAVA TOOLS ------------------------------------------------------------
- Java Source Files for Public Classes
(src.zip file or src directory)
This is the set of source files used to create the
class files included in the Java Core Classes classes.zip
file (above). These are provided for information
purposes only, to help developers learn and use Java.
It does not include the private java.* classes or the
sun.* classes, and therefore cannot be compiled into
a new classes.zip file.
Do not modify these classes; instead, create subclasses
and override where you need to. These classes are
documented in the API Reference documentation, which is
generated by javadoc.
How this is installed depends on the platform:
- On Windows, these are automatically unzipped for you
when you install them.
- On Solaris, you must unzip the src. zip file yourself.
You can get a free copy of the correct version
of unzip from:
ftp://ftp.uu.net/pub/archiving/zip/WIN32
- Java Compiler (javac)
Compiles programs written in the Java programming language
into bytecodes.
- Java AppletViewer (appletviewer)
Used for testing and running applets.
- Java Debugger (jdb)
Helps you find bugs in Java programs.
- Class File Disassembler (javap)
Disassembles compiled Java files and prints out a
representation of the Java bytecodes.
- Java Documentation Generator (javadoc)
Parses the declarations and documentation comments in
a set of Java source files and produces a set of HTML pages
describing the public and protected classes, constructors,
methods, and fields. Produces a list of
classes, a class hierarchy, and an index of all APIs.
- C Header and Stub File Generator (javah)
For attaching native methods to Java code.
- Java Archive Tool (jar)
Combines many Java files into a single jar file.
- Digital Signing Tool (javakey)
Manages entities, including their keys, certificates,
and the trust associated with them.
- Native-To-ASCII Converter (native2ascii)
Converts a native encoding file to an ascii
file that includes the \udddd Unicode notation.
- Java RMI Stub Converter (rmic)
Generates objects from the names of compiled Java classes
that contain remote object implementations.
- Java Remote Object Registry (rmiregistry)
Creates and starts a remote object registry on the
specified port of the current host.
- Serial Version Command (serialver)
Returns the serialVersionUID for one or more classes
in a form suitable for copying into an evolving class.
- AWT 1.1 Conversion Tool (awtUpdate)
Updates deprecated 1.0 AWT names to new 1.1 AWT
names (for Sun Solaris and UNIX systems, or Windows
systems with the MKS toolkit).
- Various C libraries and include files
JAVA DOCUMENTATION AND DEMOS ------------------------------------------
- demo directory
Animator General-purpose animator
ArcTest Test arc drawing and filling
BarChart Simple bar-chart applet
Blink Blinking, multicolored text
CardTest Test card layout manager
Clock Analog clock
DitherTest Test image dithering
DrawTest Draw points and lines
Fractal Fractal figures
GraphLayout Graph layout by iterated relaxation
GraphicsTest Test graphics operations
ImageMap Live-feedback image map
JumpingBox Catch the jumping box
MoleculeViewer Three-dimensional chemical model viewer
NervousText Nervous text
SimpleGraph Draw a simple graph
SortDemo Animated sorting algorithms
SpreadSheet Simple spreadsheet
TicTacToe Tic-tac-toe game
WireFrame Three-dimensional wire-frame model viewer
RMI and Internationalization demos are available in the
separately-downloadable JDK documentation. See the entry
"Demonstration Applets" in the table of contents.
- README
This file you are currently reading
- CHANGES
Changes made in the beta and final JDK 1.1 releases
- COPYRIGHT
Copyright notice for the JDK software
- LICENSE
License agreement for the JDK software
NOTE: The JDK 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 in src.zip are the only
"documentation" included in this JDK software bundle.
The rest of the documentation is in a separately-downloaded bundle
known as the "JDK 1.1 Documentation," and is available from the same
download page where you got this software:
http://java.sun.com/products/JDK/1.1/
This JDK 1.1 Documentation includes the following information:
- JDK Release Notes
- JDK API Reference
- JDK Guide to New Features
- JDK Tools Documentation
-----------------------------------------------------------------------
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 our JavaSoft email addresses
at Sun, which are listed at:
http://java.sun.com/mail/
Here is a summary of what is on this web page:
- Technical Help - Sun does not provide free technical help.
See the above web page for some places to obtain help with your
programming problems.
- JavaSoft Email Addresses - The following are our most current
email addresses as of this release. Use these for sending in
comments and informal suggestions.
java-intl@java.sun.com Internationalization
java-awt@java.sun.com AWT package
java-security@java.sun.com Security package
java-io@java.sun.com IO package
java-net@java.sun.com Net package
rmi-support@java.sun.com RMI package
jdbc@wombat.eng.sun.com JDBC package
jdbc-odbc@wombat.eng.sun.com JDBC-ODBC bridge
java-beans@java.sun.com Beans package
reflection-comments@worthy.eng.sun.com Reflection package
If your comment does not fall into any of those categories,
please send it to:
jdk-comments@java.sun.com General comments
While we are not able to respond individually to each comment,
we do review all comments.
-----------------------------------------------------------------------
REPORTING BUGS AND REQUESTING FEATURES
-----------------------------------------------------------------------
To report bugs or feature requests, go to this web page:
http://java.sun.com/cgi-bin/bugreport.cgi
This gives you instructions for checking if your bug is a duplicate
by allowing you to look in our known bugs list. This also gives
instructions for how to submit bugs and request features.
Please be aware that bugs that you submit will not necessarily
appear on the "Known Bugs" or "Fixed Bugs" pages, as we post
only major bugs there.
When submitting a bug, be sure you include the version number of
the JDK you are running. You can get the version number of the JDK
by executing:
java -version
-----------------------------------------------------------------------
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
We will continue to ship the BDK in addition to the JDK.
Updates to the BDK, tools availablity and general JavaBeans
information will be posted on a regular basis to the JavaBeans
web site:
http://java.sun.com/beans
=======================================================================
INSTALLING AND RUNNING JAVA
=======================================================================
-----------------------------------------------------------------------
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 1.1 software and documentation are available in two separate
downloadable compressed files (called "bundles"). They need to be
unpacked as follows for the few links between them to work.
Here are the abbreviated instructions. (Installation procedure
is different on different platforms, so these instructions are
quite general)
1. Download the software and documentation separately. Use
the installation instructions for your particular platform
at:
http://java.sun.com/products/JDK/1.1/
2. Unpack the software bundle first according to the
instructions in step 1.
3. Unpack the documentation bundle into the docs directory
created in step 3. You should end up with the directory
structure shown below.
4. Set the PATH and CLASSPATH for Windows or Solaris as
described in the section that follows.
5. Use a web browser to go to the front page (table of contents)
by opening the "index.html" file in the "docs" directory:
jdk1.1/docs/index.html
jdk1.1
_________________________|_____________________________________
| | | | | | | | | | |
README CHANGES COPYRIGHT LICENSE bin include lib demo src docs index.html
|
_____________________________|_____
| | | | |
api tooldocs relnotes guide index.html
| | | |
The "src" directory shown above originally appears as a "src.zip"
file in the Solaris installation, which you must manually unzip.
-----------------------------------------------------------------------
WINDOWS PATH and CLASSPATH
-----------------------------------------------------------------------
After installing the software, update the PATH and CLASSPATH
as follows.
Windows NT only - If you are using Windows NT you can
instead make the following environment variable changes in
the Control Panel. Start the Control Panel, select System,
then edit the environment variables.
1. PATH - Add the following directory to your path:
JDK1.1\BIN
The PATH statement enables Windows to find the executables
(javac, java, javadoc, etc.) from any current directory.
To change the PATH, open the AUTOEXEC.BAT file and make the
change to the path statement. To edit the AUTOEXEC.BAT
file in Windows 95:
i. Start a text editor by choosing "Start", "Programs",
"Accessories", and choosing WordPad or NotePad.
ii. Choose Open from the File menu and type "c:\autoexec.bat"
for the filename This will open the file for editing.
iii. 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. 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\BIN
2. CLASSPATH Environment Variable - Edit the AUTOEXEC.BAT file
(as in the previous instructions) and set the CLASSPATH
environment variable to the current directory (.) and
the directory containing the Java Core Class library file,
known as CLASSES.ZIP. Separate directories by semi-colons.
SET CLASSPATH=.;C:\JDK1.1\LIB\CLASSES.ZIP
The CLASSPATH tells Java applications where to look for the
CLASSES.ZIP file, which is the Java Core Class library.
See the Troubleshooting section that follows for more information.
3. Reboot - After completing these changes to AUTOEXEC.BAT, save
the file and reboot, to make the changes take effect.
-----------------------------------------------------------------------
WINDOWS INSTALLATION TROUBLESHOOTING
-----------------------------------------------------------------------
Here are four troubleshooting tips for Windows.
* If you see the following error message
net.socketException: errno = 10047
OR
Unsupported version of Windows Socket API
check which TCP/IP drivers you have installed. The AppletViewer
supports only the Microsoft TCP/IP drivers included with
Windows 95. If you are using third-party drivers (e.g.,
Trumpet Winsock), you'll need to change over to the native
Microsoft TCP/IP drivers if you want to load applets over the
network.
* If the AppletViewer does not load applets then you might
try the following:
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.
* Error Message: Exception in thread NULL
If you are getting the fatal error message: Exception in
thread NULL, when running java, javac, or appetviewer, you
should check your CLASSPATH environment variable. It may
list the the 'classes' directory from an older JDK release.
You can either unset the CLASSPATH variable, or set it to
include only the latest version of the JDK class library.
For example:
C:\> set CLASSPATH=.;C:\jdk1.1\lib\classes.zip
This will make sure that you are using the correct classes
for this release.
* Cannot close AppletViewer copyright window (Windows 95 only)
In Microsoft Windows 95, the launch bar may partially cover
the AppletViewer copyright notice window Accept and Reject
buttons. If this happens, you can move the Windows 95
launch bar to the side of the desktop to allow access to
the copyright window Accept and Reject buttons.
-----------------------------------------------------------------------
SOLARIS PATH and CLASSPATH
-----------------------------------------------------------------------
After installing the software, update the PATH and CLASSPATH
variables as follows.
1. path - Add the following directory to the Unix path variable:
jdk1.1/bin
If you use the C shell (csh), you can do this by adding
that path to your path variable in your .cshrc file.
2. CLASSPATH - If you have set the CLASSPATH environment variable
you may need to update it. You must replace CLASSPATH
entries that pointed to the "java/classes" directory to point
to "jdk1.1/lib/classes.zip". You can do this by opening the
.cshrc file and making the change to the CLASSPATH
environment variable. See the Troubleshooting section below
for more information.
After completing these changes to .cshrc, save the file and
execute the following to make the changes take effect:
% source .cshrc
-----------------------------------------------------------------------
SOLARIS INSTALLATION TROUBLESHOOTING
-----------------------------------------------------------------------
Error Message: Exception in thread NULL
If you are getting the fatal error message: Exception in
thread NULL, when running java, javac, or appetviewer,
you should check your CLASSPATH environment variable.
It may list the the 'classes' directory from an older
JDK release. You can either unset the CLASSPATH variable,
or set it to include only the latest version of the JDK
class library. For example:
% setenv CLASSPATH .:/usr/local/jdk1.1/lib/classes.zip
This will ensure that you are using the correct classes for
this release.
-----------------------------------------------------------------------
RUNNING APPLETS WITH THE APPLETVIEWER
-----------------------------------------------------------------------
AppletViewer allows you to run one or more Java 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.
Here is an example of how to invoke AppletViewer on a file-based
web page in Solaris. First change to the "jdk1.1" directory.
Then execute:
bin/appletviewer demo/GraphLayout/example1.html
Here is an example of how to invoke AppletViewer on a URL-based
web page in Solaris. Execute:
bin/appletviewer http://java.sun.com/applets/applets/NervousText/example1.html
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"
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/applets/NervousText/example1.html
-----------------------------------------------------------------------
DEBUGGING PROGRAMS WITH THE JAVA 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,
on Solaris:
cd demo/TicTacToe
../../bin/appletviewer -debug example1.html
On the PC:
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/debugging/
-----------------------------------------------------------------------
Copyright © 1996,1997 Sun Microsystems, Inc.
2550 Garcia Ave., Mountain View, CA 94043-1100 USA.
All rights reserved.