README Java(tm) Development Kit JDK(tm) 1.1.6 Software ----------------------------------------------------------------------- CONTENTS Overview of the Java Development Kit - Introduction - Purpose - Version Compatibility - Bug Fixes - What the JDK Software Contains - Where to Find More Information - Submitting Comments - Reporting Bugs and Requesting Features - JavaBeans(tm) and the Beans Development Kit Installing and Running the JDK Software - Installation Notes - Windows - Winsock Issues - Running JDK Tools in Microsoft Windows - Microsoft Windows PATH and CLASSPATH - Using the JIT Compiler - Microsoft Windows Installation Troubleshooting - Solaris - Running JDK Tools in Solaris - Solaris PATH and CLASSPATH - Solaris Installation Troubleshooting - Running Applets with the AppletViewer - Debugging Programs with the Debugger - Tips and Tricks Deploying Java Applications - Runtime Environment - Installation ======================================================================= OVERVIEW OF THE JAVA DEVELOPMENT KIT ======================================================================= ----------------------------------------------------------------------- INTRODUCTION ----------------------------------------------------------------------- This is version 1.1.6 of the Java Development Kit. The Java Development Kit is a development environment for writing applets and applications that conform to the Java 1.1 Core API. 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, and includes bug fixes since version 1.1.5. This is a maintenance release. Changes 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.6). While bugs have been fixed in version 1.1.6, the platform hasn't changed. Although this is a maintenance release, the Win32 version of the Java Development Kit includes a significant performance enhancement. A production-quality version of Symantec JIT bytecode compiler is included. This is the same JIT previously packaged as an early-access product in the Win32 Performance Pack. Because the JIT is now included in the JDK software, the Performance Pack has been discontinued. The Symantec JIT compiler is copyrighted (c), 1996-1998, by Symantec Corporation. All rights reserved. In the Win32 version, all JDK tools use the JIT by default. To disable the JIT, see "Using the JIT," below. The Java platform 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 (RMI), Reflection, database connectivity (JDBC), new Java Native Interface, Object Serialization, Inner Classes, and performance enhancements. For further description of these features, see the "New Feature Summary" in the JDK documentation. 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 "Reporting Bugs" section below. The Java Development Kit is a product of Sun Microsystems, Inc. JavaSoft(tm), an operating company of Sun Microsystems, develops the JDK software. ----------------------------------------------------------------------- PURPOSE ----------------------------------------------------------------------- The JDK software allows you to: - Develop applets that will run in browsers supporting the Java platform, such as HotJava(tm) Browser. Some browsers provide a limited or incompatible implementation of the Java 1.1 platform. To fully enable such browsers, use the Java(tm) Plugin. See: http://java.sun.com/products/plugin/ - Develop applications. Applications run without the need for a browser. (HotJava Browser is written in the Java programming language.) ----------------------------------------------------------------------- VERSION COMPATIBILITY ----------------------------------------------------------------------- In general, any applet or application that ran in version 1.0.2 of the Java Development Kit should run correctly in version 1.1.6. 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 "Reporting Bugs," and mention that they are compatibility bugs. Compatibility is critically important to us, and a cornerstone of the promise: Write Once, Run Anywhere(tm). ----------------------------------------------------------------------- BUG FIXES ----------------------------------------------------------------------- As with any release, we will continue vigorously testing and debugging the JDK software. If we uncover any important bugs, we will post them on the Java Developer Connection(sm) web site at: http://developer.javasoft.com/developer/bugParade/index.html 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 SOFTWARE CONTAINS ----------------------------------------------------------------------- RUNTIME ---------------------------------------------------------- - 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 platform. SOURCE FILES ----------------------------------------------------- - Source Files for Public Classes (src.zip file or src directory) This is the set of source files used to create the classes included in the core classes classes.zip file (above). These source files are provided for information purposes only, to help developers learn and use the Java programming language. They do not include the private java.* classes or the sun.* classes, and therefore cannot be compiled into a complete 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 during installation. - On Solaris, you must unzip the src.zip file yourself. You can get a free copy of the correct version of unzip in source form (which you must compile) from: http://www.cdrom.com/pub/infozip/zlib/ or ftp://ftp.cdrom.com/pub/infozip/zlib/ or ftp://ftp.uu.net/pub/archiving/zip/UNIX/SUN/ TOOLS ------------------------------------------------------------ - Java Compiler (javac) Compiles programs written in the Java programming language into bytecodes. - Java Interpreter (java) Executes Java bytecodes. In other words, it runs programs written in the Java programming language. - Jave Runtime Interpreter (jre) Similar to the Java Interpreter (java), but intended for end users who do not require all the development-related options available with the java tool. - Java AppletViewer (appletviewer) Used for testing and running applets. - Java Debugger (jdb) Helps you find bugs in programs. - Class File Disassembler (javap) Disassembles compiled files and prints out a representation of the bytecodes. - Java Documentation Generator (javadoc) 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. - C Header and Stub File Generator (javah) For attaching native methods to code written in the Java programming language. - Java Archive Tool (jar) Combines many class files and other resources 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 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 (updateAWT) Included with the JDK AWT documentation, rather than in the bin directory. 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 awt-1.1 AWT demos i18n Internationalization demos 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 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. - README This file you are currently reading - CHANGES Changes made in the beta and final releases - COPYRIGHT Copyright notice for the JDK software - LICENSE License agreement for the JDK software 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 browse the JDK software documentation by visiting the JavaSoft web site, or you can download the JDK Software 1.1.6 Documentation Bundle from: http://java.sun.com/products/jdk/1.1/ The JDK Software 1.1.6 Documentation Bundle includes: - Release Notes - API Reference - Guide to New Features - Additional Demo Programs - Demo Overview Page - Tools Documentation 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/ For a comprehensive list of online documents, go to the JavaSoft Documentation page at: http://java.sun.com/docs/ ----------------------------------------------------------------------- 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 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 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 jni@java.sun.com Java Native Interface javadoc@sun.com Javadoc Tool 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. When submitting a bug, be sure you include the version number of the JDK software you are running. You can get the version number of the JDK software 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 software. Updates to the BDK, tools, and general JavaBeans information will be 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 1.1.6 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 abbreviated instructions. (The installation procedure is different on different platforms, so these instructions are quite general.) 1. Go to the download page for the Java Development Kit and download the software and documentation separately: http://java.sun.com/products/jdk/1.1/ 2. Follow the installation instructions for your particular platform at: http://java.sun.com/products/jdk/1.1/installation-solaris2.html OR http://java.sun.com/products/jdk/1.1/installation-win32-x86.html 3. Unpack the software and documentation bundles according to the instructions on the web page given in step 2. 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 your new, local JDK documentation table of contents by opening the "index.html" file in the "docs" directory: jdk1.1/docs/index.html jdk1.1.6 _________________________|_____________________________________ | | | | | | | | | | | README CHANGES COPYRIGHT LICENSE bin lib include 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. On Windows, the installer automatically unzips it for you. ----------------------------------------------------------------------- WINDOWS ----------------------------------------------------------------------- ______________ Winsock Issues JDK software no longer includes Microsoft Winsock 2.0. It is extremely likely that your system already has Winsock 2.0. Windows NT 4.0 and Windows 98 come with Winsock 2.0. Windows 95 comes with Winsock 1.2, but most Windows 95 systems have been upgraded to Winsock 2.0 by now. Microsoft provides a free software bundle, the Microsoft Windows Sockets 2.0 Software Development Kit, that includes Winsock 2.0. Even if you don't need to upgrade your own system, you may want to obtain this kit so you can deploy network applications on Windows 95 systems. For more information, see "Deploying Java Applications," below. ______________________________________ 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 are Windows programs with 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.6, to run the compiler on a file myfile.java, go to a DOS shell and execute this: Type: C:\jdk1.1.6\bin\javac myfile.java -or- Add C:\jdk1.1.6\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. Developing in both versions 1.0.2 and 1.1.6 - If you want to develop in both versions 1.0.2 and 1.1.6, you must set CLASSPATH (and PATH) separately for each one. To run both versions simultaneously, you can run each one from its own DOS window. If you are running only one at a time, you can write a batch script to switch the value of CLASSPATH (and PATH). Windows NT only - If you are using Windows NT, 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 - Add the absolute path of the "jdk1.1.6\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 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. 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.6\BIN To make the path take effect, execute the following: C:\> autoexec.bat 2. CLASSPATH Environment Variable - If you follow the default installation, you do not need to set CLASSPATH, because the tools automatically set it for you. If your CLASSPATH has not previously been set, you can skip this step. 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. WHAT CLASSPATH DOES The CLASSPATH tells the Java virtual machine and other applications (which are located in the "jdk1.1.6\bin" directory) where to find the class libraries, such as classes.zip file (which is in the lib directory). By default, the java tools temporarily append the following to whatever CLASSPATH you have explicitly set in your startup file: .;[bin]\..\classes;[bin]\..\lib\classes.zip where [bin] is substituted by the absolute path to the jdk1.1\bin directory. Therefore, if you keep the bin and lib directories at the same directory level (that is, if they have a common parent directory), the executables will find the classes. You need to set the CLASSPATH only if you move classes.zip or want to load a different library (such as one you develop). Refer to the Windows Installation Troubleshooting section below if you have problems running the JDK software. ______________________ Using the JIT Compiler The Win32 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. To disable the JIT, pass the -nojit option to the launcher tool: 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 -D option to pass the -nojit option to the launcher: appletviewer -D-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 four troubleshooting tips for Microsoft 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" or "Unable to initialize threads: cannot find class java/lang/Thread" (yes, with forward slashes) If you are getting one of these fatal error messages when running java, javac, or appetviewer, 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.6\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 ----------------------------------------------------------------------- ____________________________ Running JDK Tools in Solaris After installing the JDK software, you start a tool by typing its name into a shell window with a filename as an argument. 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. For example, if the JDK software is installed at /usr/local/jdk1.1.6, to run the complier on a file myfile.java, go to a shell and execute: Type: /usr/local/jdk1.1.6/bin/javac myfile.java -or- Add /usr/local/jdk1.1.6/bin to your path statement Type: javac myfile.java The path and CLASSPATH variables are not required, but it is helpful to know more about them. See the next section about setting these variables. __________________________ Solaris 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. NOTE - If you want to develop in both version 1.0.2 and version 1.1.6, you must set CLASSPATH (and path) separately for each one. To run both versions simultaneously, you can run each one from its own shell window. If you are running only one at a time, you can write a batch script to switch the value of CLASSPATH (and PATH). 1. Path Variable - Add the absolute path of the "jdk1.1.6/bin" directory to your Unix path variable, as follows. The path variable enables Solaris to find the executables (javac, java, javadoc, etc.) from any current directory. To find out if the path is currently set for any java tools, execute: % which java This will print the path to java, if it can find it. If you use the C shell (csh), you can set the path in your startup file (~/.cshrc) as follows, for example: set path=($path /usr/local/jdk1.1.6/bin) Then load the startup file and verify that the path is set by repeating the "which" command above: % source ~/.cshrc % which java 2. CLASSPATH Environment Variable - If you follow the default installation, you do not need to set CLASSPATH, because the shell scripts automatically set it for you. If your CLASSPATH has not previously been set, you can skip this step. If you want to develop in both 1.0.2 and 1.1.6, you must set CLASSPATH separately for each one. To run both simultaneously, run each one in its own DOS window. If you are running only one at a time, you can write a batch script to switch the value of CLASSPATH. 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: % echo $CLASSPATH If it is set, you can unset the current value by typing: % unsetenv CLASSPATH Also open your startup file (~/.cshrc) or script and remove the path to the JDK classes from the CLASSPATH environment variable if you want the change to be permanent. WHAT CLASSPATH DOES The CLASSPATH tells the Java virtual machine and other applications (which are located in the "jdk1.1.6/bin" directory) where to find the class libraries, such as classes.zip file (which is in the lib directory). By default, the java tools temporarily append the following to whatever CLASSPATH you have explicitly set in your startup file: .:[bin]/../classes:[bin]/../lib/classes.zip where [bin] is substituted by the absolute path to the jdk1.1/bin directory. Therefore, if you keep the bin and lib directories at the same directory level (that is, if they have a common parent directory), the executables will find the classes. You need to set the CLASSPATH only if you move classes.zip or want to load a different library (such as one you develop). Refer to the Solaris Installation Troubleshooting section below if you have problems running the JDK software. ____________________________________ Solaris Installation Troubleshooting * Error Message: "Exception in thread NULL" or "Unable to initialize threads: cannot find class java/lang/Thread" If you are getting one of these fatal error messages when running java, javac, or appetviewer, you should check your CLASSPATH environment variable. It may list "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: % setenv CLASSPATH .:/usr/local/jdk1.1.6/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 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. _______ SOLARIS Here is an example of how to invoke AppletViewer on a file-based web page in Solaris. First change to the "jdk1.1.6" 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/NervousText/example1.html _______ WINDOWS 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.6" 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 ----------------------------------------------------------------------- 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, 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/1.1/debugging/ ----------------------------------------------------------------------- Tips and Tricks ----------------------------------------------------------------------- ____________________________________ Windows Conventions and java.io.File In the Windows implementation of 1.1.5, java.io.File made an incorrect assumption about the meaning of a bare drive name such as "C:". A bare drive name was assumed to refer to the root directory for that drive. Thus, "C:" was equivalent to "C:\". In 1.1.6, java.io.File follows proper Windows conventions. Windows recognizes a distinct working directory for each drive. A bare drive name refers to the working directory for that drive. If your software relies on "C:" being equivalent to "C:\", you will need to modify it for 1.1.6. _____________________ Locale Bug on Solaris A bug in the class java.util.Locale can cause errors when run on Solaris. This problem only occurs when a program is run under a Solaris locale that does not include an ISO 3166 country name. Under these circumstances, the Solaris locale is mapped to a Java platform language locale, instead of a country locale. When this happens, the getISO3CountryCode() and getDisplayCountry() methods return incorrect values. This bug will be fixed in the next release. (Bug 4118731.) As a workaround, you can directly set the default locale through the user.region property. For example, this command sets the default locale to "ja_JP": java -Duser.region=ja_JP MyClass ___________________ Win32 Peer Controls Some text controls, such as java.awt.TextArea, do not always handle large text strings correctly on Win32 systems. If, for example, you pass a 64K string to setText(), the control may display nothing. (Bug 4080391.) This is not a bug in the JDK class libraries. The actual bug is in the "peer" control, the native platform control that actually appears on the screen. Win32 screen controls can only handle a limited amount of text. In theory, the limit is 32K. In practice, the limit may be as little as 20K or as much as 60K. JDK 1.2 software includes "lightweight" controls, which do not use peers. Lightweight text controls can display any string that will fit in memory. _________________________________________________ The JIT, HotJava(tm) Views(tm), and the JA Locale Some users have been unable to use JDK 1.1.6 software to run HotJava Views under Japanese Windows NT 4.0. (Bug 4128993.) This problem appears to be due to a bug in the JIT which prevents parsing of the JA locale. This bug will be fixed in a future release. Note that in 1.1.6, the JIT is on by default. If you have problems with the JA locale, use the -nojit flag to disable the JIT. ======================================================================= 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: * Your own class, resource, and data files. * A runtime environment. * An installation procedure or program. 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. JavaSoft provides a free, redistributable runtime environment called the Java Runtime Environment. Versions of this are are available for all platforms that run the JDK software. The Java Runtime Environment Version 1.1.6 is available for download at: http://java.sun.com/products/jdk/1.1/jre/ The Win32 versions comes with a built-in installation program suitable for end-users. Solaris versions require the developer to provide installation support. 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. JavaSoft is not the only supplier of runtime software for Java programs. If you use a third-party runtime, you should make sure it is fully compatible with the Java Runtime Environment. For information on third-party runtime environments, see: http://java.sun.com/cgi-bin/java-ports.cgi ----------------------------------------------------------------------- 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 the Java Runtime Environment Notes for Developers at: http://java.sun.com/products/jdk/1.1/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. If your application uses the networking classes, it may not run reliably under Winsock 1.1. If your networking application must support Windows 95, which comes with Winsock 1.1, you will want to include a Winsock 2.0 install in your installation procedure. (Windows NT 4.0 and Windows 98 come with Winsock 2.0.) To provide Winsock 2.0, you need the Microsoft Windows Sockets 2.0 Software Development Kit. This free software can be downloaded from the following addresses: http://www.microsoft.com/win32dev/netwrk/winsock2/ws295sdk.html http://www.microsoft.com/windows95/info/ws2.htm ftp://ftp.microsoft.com/bussys/WinSock/winsock2/ ----------------------------------------------------------------------- Copyright © 1996, 1997, 1998 Sun Microsystems, Inc. 901 San Antonio Rd., Palo Alto, CA 94303 USA All rights reserved.