Download Support Readiness Document Java™ 2 Standard Edition, Version

Support Readiness Document
Java™ 2 Standard Edition,
Version 1.4
Java Plug-In
Sun Microsystems, Inc.
901 San Antonio Road
Palo Alto, CA 94303
U.S.A. 650-960-1300
March 2002
 2002 by Sun Microsystems, Inc.—Printed in USA.
901 San Antonio Road, Palo Alto, CA 94303-4900
All rights reserved. No part of this work covered by copyright may be duplicated by any means—graphic, electronic or mechanical,
including photocopying, or storage in an information retrieval system—without prior written permission of the copyright owner.
RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the government is subject to restrictions as set forth in
subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 (October 1988) and FAR
52.227-19 (June 1987). The product described in this manual may be protected by one or more U.S. patents, foreign patents, and/or
pending applications.
TRADEMARKS: Java, Java 2 Platform, J2SE, Java 2 Enterprise Edition, J2EE, Java 2 SDK, JDK, Java 2D, Java Compatibility Kit, Java
HotSpot, JavaBeans, Solaris, and Sun are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and
other countries. UNIX is a registered trademark in the United States and other countries, exclusively licensed through X/Open
Company, Ltd. Netscape is a trademark or registered trademark of Netscape Communications Corporation.
Sun Microsystems, Inc.
Table of Contents
1.
2.
Java Plug-In Overview 1
1.1
Overview
1
1.2
Localization and Internationalization
1.3
Features, Advantages, and Benefits
2
2
1.3.1
Advantages and Benefits
2
1.3.2
Features
3
1.3.2.1
Networking
1.3.2.2
Security
1.3.2.3
Scripting
1.3.2.4
Optional Package Installation
3
3
4
1.4
Features or Services Not Provided
1.5
How Java Plug-In Works
4
4
4
Product Changes for Version 1.4 6
2.1
Changes and New Features in Version 1.4
2.1.1
Usability Enhancements
6
6
2.1.1.1
Unified Error and Warning Dialog
2.1.1.2
Enhanced Error Condition Handling
2.1.1.3
Java Plug-In Exception Handling
2.1.1.4
Enhanced Java Plug-In Tracing
2.1.1.5
Java Console Enhancements
2.1.1.6
Applet Progress Status
Sun Microsystems, Inc.
6
6
6
7
7
8
Table of Contents
iii
2.1.2
Multi-Version
8
2.1.2.1
Usage
9
2.1.2.2
Collision Detection
2.1.3
HTTPS Through JSSE
10
2.1.4
Common DOM APIs
10
2.1.5
Persistence APIs
2.1.6
2.1.7
11
2.1.5.1
Static Variable
2.1.5.2
Local Files
2.1.5.3
Cookies
2.1.5.4
AppletContext
File Caching
9
11
11
12
12
12
2.1.6.1
Configuring the Cache
13
2.1.6.2
HTML Parameters for JAR Files
2.1.6.3
Update Logic
2.1.6.4
Cache Cleanup Policy
XP/IE6.0
15
14
14
2.1.7.1
Enabling APPLET Tag Support
2.1.7.2
Deployment Model
Bugs Fixed in Version 1.4
2.3
Previous Versions of Java Plug-In
2.4
Upgrading to Version 1.4 From a Previous Version
2.5
Porting Applications to Version 1.4
HTML Converter 18
4.
Code Samples 20
4.1
Common DOM APIs
16
Object Creation
4.1.2
Retrieve HTML Title
Persistence APIs
4.3
File Caching
4.4
Scripting
16
16
17
20
4.1.1
4.2
15
15
2.2
3.
13
20
23
24
25
26
Sun Microsystems, Inc.
Table of Contents
iv
5.
JavaScript to Java
26
4.4.2
Java to JavaScript
27
Troubleshooting 28
5.1
Common User Questions
28
5.2
Troubleshooting Utilities
28
5.3
6.
4.4.1
5.2.1
Isolating Java Plug-In Bugs
5.2.2
Basic Debugging Techniques
5.2.3
Troubleshooting Deadlocks
5.2.4
Debugging an Applet
29
Common Developer Problems
30
5.3.1
Static Variables
5.3.2
Threads
5.3.3
Applet Life Cycle
28
29
29
30
30
31
5.4
Common Installation and Uninstallation Problems
5.5
Common User Problems
31
31
5.5.1
Java/JavaScript
32
5.5.2
HTTPS Through JSSE
5.5.3
Multi-Version
5.5.4
Compatibility issues between Microsoft VM and Java 2
5.5.5
Signed Applet (RSA Verification)
5.5.6
Optional Package Installation Issues
32
33
33
34
34
Installing Java Plug-In 35
6.1
Product Distribution
6.2
Product Licensing
6.3
Hardware Requirements and Dependencies
6.4
35
35
6.3.1
Platforms Supported
6.3.2
Disk Space Requirements
35
35
36
Software Requirements and Dependencies
6.4.1
Required Operating System Patches
6.4.2
Product Dependencies
36
36
37
Sun Microsystems, Inc.
Table of Contents
v
6.5
6.6
7.
8.
9.
Installing Java Plug-In
37
6.5.1
Downloading Java Plug-In
37
6.5.2
Pre-Installation Considerations
6.5.3
Default Installation Path
6.5.4
Steps for Installing Java Plug-In
37
37
37
6.5.4.1
Solaris OE
38
6.5.4.2
Linux OS
6.5.4.3
Microsoft Windows OS
38
40
6.5.5
Steps for Installing Version 1.4 as an Upgrade
6.5.6
Post-Installation Considerations
41
6.5.6.1
Netscape 4.7x Users
6.5.6.2
Netscape 6.1 Users
43
6.5.6.3
Microsoft IE Users
44
Uninstalling Java Plug-In
41
41
44
6.6.1
Solaris OE
44
6.6.2
Linux OS
6.6.3
Microsoft Windows OS
45
45
Key Files and Directories 46
7.1
Configuration Files
46
7.2
Directories Created at Installation
7.3
Generated Files and Their Locations
7.4
Tools/Utilities location
46
46
47
Configuring Java Plug-In 49
8.1
Java Plug-In Control Panel
8.2
user.home
8.3
Properties File
8.4
Microsoft IE Control Panel
49
49
49
50
Reference Information 51
9.1
Product Information
51
Sun Microsystems, Inc.
Table of Contents
vi
9.2
Technical Documentation
51
9.3
Frequently Asked Questions
9.4
Tutorials and Other References
51
Sun Microsystems, Inc.
51
Table of Contents
vii
Preface
This document provides support readiness information for the Java™ Plug-In,
which is part of the Java 2 Platform (J2SE™), Standard Edition, version 1.4.
This document is not designed to provide comprehensive product training.
Instead, it focuses on issues immediately relevant to support, such as changes in
this version of the product, using and troubleshooting the product, and
installing and configuring the product. For pointers to other documentation, see
Section 9 “Reference Information.”
Sun Microsystems, Inc.
Preface
ix
1
Java Plug-In Overview
The following SRD may contain actual software programs in source code form.
This source code is made available for developers to use as needed, pursuant to
the terms and conditions of this license located at:
http://access1.sun.com/SRDs/BSD.html
1.1
Overview
Java Plug-In, Version 1.4, software from Sun Microsystems enables web page
authors to direct Java applets or JavaBeans™ components on their Internet web
pages to run, using Sun Microsystems Java 2 Runtime Environment (JRE)
instead of the browser’s default Java Virtual Machine (JVM). This release
provides support for Microsoft Internet Explorer (IE) and Netscape Navigator
on various Microsoft Windows platforms. Java Plug-In delivers full Java 2
Platform support for Microsoft IE and Netscape Navigator users.
Java Plug-In is designed for enterprise customers who wish to deploy Java 2
Platform-based applets on their web pages today. Specifically, web pages
modified to support Java Plug-In enable users to run Java 2 Platform-based
applets in Microsoft IE or Netscape Navigator. Java Plug-In infuses today’s
widely adopted web browsers with the benefits of all of the new features and
capabilities of the Java 2 Platform. For a list of new features found in the Java 2
Platform, see:
http://java.sun.com/products/j2se/1.4/docs/relnotes/
features.html
Java Plug-In is written using C++ and the Java programming language. The JRE,
Standard Edition, Version 1.4, contains the Java HotSpot™ Client VM. Sun
Microsystems is simultaneously releasing version 2.0 of the Java HotSpot Server
VM, the server-side counterpart to the Java HotSpot Client VM that ships as part
Sun Microsystems, Inc.
1 of 51
of J2SE™, v. 1.4. Together, these Java HotSpot technologies comprise the
complete solution for high-performance Java computing on both the client and
the enterprise server.
1.2
Localization and Internationalization
Java Plug-In and HTML converter have been localized in ten languages,
including English. Documentation is available in English and Japanese.
Installation is available in the languages for the Microsoft Windows platform.
1.3
Features, Advantages, and Benefits
1.3.1
Advantages and Benefits
Below is a list of major advantages and benefits of Java Plug-In:
■
Full Java 2 Platform support
Allows enterprise developers to develop and deploy applets, taking full
advantage of Java 2 Platform features and functionality, such as the new
security model, signed applets, Java Foundation Classes, and JavaBeans
enhancements.
■
Full Java Compatibility Kit (JCK) test suite compliance
Java Plug-In utilizes the latest release of Sun Microsystems JRE, which is fully
compliant with the JCK test suite.
■
Future-ready Java platform architecture
Java Plug-In features an architecture that makes it easy for Sun to bring new
Java platform features and functionality, including those contained in the
latest Java 2 Platform and the new high performance HotSpot VM, to the
Solaris Operating Environment (OE), Linux, and Microsoft Windows systems
much more quickly than has been previously possible.
■
Automatic, free public download and easy installation
Upon encountering a web page that specifies Java Plug-In, the browser will
download and install all the necessary files and render the applet, requiring
minimal user intervention.
■
Free Java Plug-In HTML converter
Sun Microsystems, Inc.
2 of 51
Information Services (IS) managers and web page authors can modify their
hypertext markup language (HTML) pages to specify the use of Java Plug-In
rather than the browser’s default VM. The HTML converter is written using
the Java programming language and the Java Foundation Classes (JFC), v. 1.1.
1.3.2
Features
1.3.2.1
Networking
■
Cookies
Java Plug-In provides full bidirectional support for cookies. That is, it is
capable of both sending cookies to and receiving cookies from a web server.
No action must be taken by a user (either end user or web developer) of the
Plug-In to use the cookie support. They should be aware, however, that the
browser’s cookie policy applies to the Plug-In as well.
■
Proxy
In order to support operation behind firewalls, the Java Plug-In provides the
ability to establish proxy information for use in establishing communication
channels with servers.
Java plug-in provides full support for manual proxy configuration and
automatic proxy configuration in Netscape Navigator and Microsoft IE. This
information is set up through the Java Plug-In control panel.
1.3.2.2
Security
■
Signed applets
If an applet is signed with a trusted cryptographic key, the applet will be
allowed to run fully trusted and will be able to access a user’s local disk files,
open arbitrary network connections, call native methods, and perform other
actions. Java Plug-In supports signing through Netscape Object signing tool
and Jarsigner.
In order for Java Plug-In to be able to verify RSA signatures in a browserindependent way, a Cryptographic Service Provider (CSP) has been bundled
with Plug-In. This CSP is capable of verifying RSA signatures. In particular, it
supports the MD2withRSA, MD5withRSA, and SHA1withRSA digital signature
algorithms.
■
Hypertext Transfer Protocol Secure (HTTPS)
Sun Microsystems, Inc.
3 of 51
Java Plug-In supports all HTTPS policies that are supported in both Netscape
Navigator and Microsoft IE. It provides full proxy configuration support for
HTTPS.
1.3.2.3
Scripting
The Java Plug-In supports the ability to access the JRE from JavaScript. This is
typically referred to as JavaScript-to-Java communication. The reverse is also
supported and is known as Java-to-JavaScript communication. Often, these two
features are used in conjunction. For example, a web developer will write some
JavaScript that calls a method on a Java object and that method, in turn, calls
back to the browser to access the Document Object Model (DOM). This sort of
interaction can be very complex, so it is important to understand the full
transaction involved when helping a customer with a scripting problem.
Code samples illustrating the use of scripting are provided in Section 4.4
“Scripting.”
1.3.2.4
Optional Package Installation
Optional packages are packages of Java classes and any associated native code,
embodied in one or more JAR file, that application developers can use to extend
the functionality of the core Java platform. Optional package classes extend the
platform in the sense that the VM can find and load them without their being on
the classpath, much as if they were classes in the platform’s core API. Java PlugIn provides easier and automatic optional package deployment.
1.4
Features or Services Not Provided
Support for ActiveX bridge has been disabled due to a lack of resources.
Support will be renewed in a future release.
1.5
How Java Plug-In Works
Java Plug-In does not replace the underlying Java Virtual Machine (JVM).
Rather, it allows web page authors to specify the use of Sun Microsystems JRE
instead of the default JVM for a given web page. This ensures enterprise
developers that Java 2 Platform-based applets are executed with full support for
all of the features and capabilities of the Java 2 Platform in Netscape Navigator
and Microsoft IE.
Sun Microsystems, Inc.
4 of 51
Java Plug-In leverages Netscape Navigator’s plug-in architecture to allow JRE to
run inside Netscape Navigator, much like users can run QuickTime movies or
Shockwave animations with plug-ins today. Using the HTML <EMBED> tag, web
page authors can run plug-ins as part of a web page. This make it possible for
the web browser to use JRE in Netscape Navigator.
To use all of the features and capabilities of the Java 2 platform in Microsoft IE
or Netscape Navigator, web page authors must specify the use of JRE through
Java Plug-In. Thus, web pages must be modified to invoke JRE. Sun provides a
written specification to guide web page authors on how to make these changes.
In addition, Sun provides the Java Plug-In HTML converter that will
automatically make the changes to the selected set of HTML pages.
Java Plug-In leverages Microsoft IE’s extension mechanisms to allow JRE to run
inside Microsoft IE. The technology used to achieve this is Microsoft’s COM or
ActiveX. Using the HTML <OBJECT> tag, web page authors can run ActiveX
controls or COM components as part of a web page. Microsoft IE provides
elaborate mechanisms for downloading and caching ActiveX controls. This
makes it possible for the web browser to use JRE with minimal user
intervention.
All Java 2 Platform-based, 100% Pure Java applets should run unmodified using
Java Plug-In.
Sun Microsystems, Inc.
5 of 51
2
Product Changes for Version 1.4
2.1
Changes and New Features in Version 1.4
2.1.1
Usability Enhancements
The main goal of this enhancement is to make Java Plug-In easier to use during
the applet development and deployment stage. The enhancements are described
in the following sections.
2.1.1.1
Unified Error and Warning Dialog
This enhancement will unify the look-and-feel of all the error and warning
dialogs that displayed directly from Java Plug-In so that developers and users
can distinguish errors and warnings more easily.
2.1.1.2
Enhanced Error Condition Handling
This enhancement provides more information when errors are encountered in
Java Plug-In. This helps developers to debug and report problems.
2.1.1.3
Java Plug-In Exception Handling
To allow users to view exception details even when the Java Console is not
open, this enhancement displays a dialog box with all the exception details
whenever there is an exception in the applet’s init(), start(), stop(), or
Sun Microsystems, Inc.
6 of 51
destroy() methods. This feature is disabled by default and can be turned on
by selecting the Show Exception Dialog Box check box in the Basic tab on the
Java Plug-In control panel.
2.1.1.4
Enhanced Java Plug-In Tracing
Tracing in Java Plug-In can be turned on by enabling the property
javaplugin.trace at JPI startup:
javaplugin.trace = true/false
Using the javaplugin.trace property enables all the tracing capabilities
inside Java Plug-In, causing tracing messages to flood the Java Console, making
it difficult to read.
More fine-grained tracing control is now available. The property
javaplugin.trace.option allows users to turn on fine-grained tracing. The
user can choose the following options:
■
■
■
■
■
basic - turn on basic tracing: System.out.println,
System.err.println statements
net - turn on networking-related tracing
security - turn on security-related tracing
ext - turn on extension-related tracing: the debug statements from Java PlugIn support Java extensions
liveconnect - turn on liveconnect-related tracing (for NS6 only)
Tracing can also be turned on or off by using the options in Java Console.
2.1.1.5
Java Console Enhancements
Java Console is now a Swing based window to handle many tracing messages. It
also provides a simple way to show System.out and System.err so
developers can debug their applets. Debugging applets usually requires more
than System.out and System.err.
This enhancement provides the following options in the Java Console:
■
■
■
■
■
■
■
■
Finalize objects on finalization queue
Trigger garbage collection
Display memory usage
Display thread list
Clear the console window
Display the available debug options
Quit the console
Display classloader list
Sun Microsystems, Inc.
7 of 51
■
■
■
2.1.1.6
Print memory usage
Display system properties
Clear classloader cache
Applet Progress Status
This enhancement provides applet-specific progress status in the applet’s
window. The progress status is shown inside the applet’s window and indicates
that the applet is being loaded. Useful status messages are printed inside a gray
box. A progress bar has been added to the gray box. It gets updated while the
applet is being downloaded. The way the progress bar is displayed can be
customized as follows:
■
The HTML parameter PROGRESSCOLOR can be used to change the default
color for the progress bar.
■
The HTML parameters BOXFGCOLOR and BOXBGCOLOR can be used to specify
foreground and background color for the applet window. The default color is
black/gray. Color tags currently accept colors in RGB format to satisfy
Color(int r, int g, int b) or string representation of colors from
java.awt.Color.
■
The HTML parameter BOXMESSAGE can be used to customize the status
message for the applet window or to turn status messages off. See the
following examples:
BOXMESSAGE=”BOXMESSAGE=””
BOXMESSAGE=”My personal message here”
In this example, the message “My personal message here” is shown in a gray
box. HTML tags are available for the Netscape browser only.
2.1.2
Multi-Version
This feature allows users to install more than one version of Java Plug-In on
their machines by assigning unique MIME type and CLSID for each version of
Java Plug-In from the 1.4 release. Class-ID (CLSID) is a unique identifier used to
identify ActiveX Controls. Legacy CLSID and MIME types are still supported
with every version of Java Plug-In.
To help users and developers to select and use a particular version of Java PlugIn, the following conventions are used to name unique CLSID and MIME type.
■
CLSID format:
"CAFEEFAC-<Major Version>-<Minor Version>-<Patch Version>ABCDEFFEDCBA"
Sun Microsystems, Inc.
8 of 51
Major version, minor version, and patch version are four-digit hex numbers.
For example, CLSID for version 1.4 is:
"CAFEEFAC-0014-0000-0000-ABCDEFFEDCBA"
Similarly, CLSID for version 1.3.0_03 is:
"CAFEEFAC-0013-0000-0003-ABCDEFFEDCBA"
■
MIME type format:
application/x-java-applet;jpi-version=<version number>
For example, MIME type for version 1.4 is:
application/x-java-applet;jpi-version=1.4
Similarly, MIME type for version 1.3.0_03 is:
application/x-java-applet;jpi-version=1.3.0_03
Each version of Java Plug-In has its own registry settings, control panel,
properties file, certificate store, trace file, and log file.
2.1.2.1
Usage
On the UNIX platform, specify the MIME type in the HTML page and set the
environment variable NPX_PLUGIN_PATH to multiple Netscape plug-in
locations.
For example, set:
NPX_PLUGIN_PATH <jre1>/plugin/sparc/ns4:<jre2>/plugin/sparc/ns4
Where <jre1> and <jre2> are the install locations for JREs.
On the Microsoft Windows platform, specify unique CLSID/MIME type in the
HTML page for IE and Netscape 4.x.
2.1.2.2
Collision Detection
Although Java Plug-In multi-versioning enables multiple JREs to co-exist on the
same machine, version 1.4 does not yet support multi-versioning of JREs in one
browser session. That means that, when a browser is running with one version
of JRE and then loads a page with an applet that requires another version of JRE,
there is a collision. An error dialog box is displayed, indicating that a new
session must be started to run the applet.
Sun Microsystems, Inc.
9 of 51
2.1.3
HTTPS Through JSSE
Java Plug-In has supported HTTPS through browser-dependent native APIs
since the 1.2.2 release. Java Secure Socket Extension is part of the core Java 2
Platform in version 1.4. It provides a Java implementation of SSL and HTTPS.
Java Plug-In, v. 1.4, leverages JSSE to provide HTTPS support by default, instead
of relying on the browser.
Advantages of using HTTPS through JSSE include:
■
■
■
Pure Java code making the applet browser independent and platform
independent
User can leverage the features provided in JSSE
Multi-threaded support
For each HTTPS connection, a different proxy configuration can be used. Java
Plug-In provides full support for proxy configuration support in HTTPS.
For each HTTPS connection, a cookie may be sent or received from the web
server. Java Plug-In provides full cookie support, which automatically retrieves
or updates the cookie through the browser cookie store.
2.1.4
Common DOM APIs
The Common DOM API was introduced in Java 2 Software Development Kit
(J2SDK), version 1.4. The main goal of this API is to provide a way for Java
applications to access the DOM in the browser from different vendors on
various platforms through a standard set of APIs.
The Common DOM API is built upon the DOM Level 2 specification defined by
the World Wide Web Consortium (W3C) DOM work group. The specification
defines a set of interfaces, using Interface Definition Language (IDL) in a
language independent fashion to manipulate DOM and also includes a Java
language binding. This specification subsumes the abstract semantics described
for the DOM Level 2 Core interfaces, the DOM Level 2 HTML interfaces, the
DOM Level 2 Event interfaces, and the associated Java Language binding.
The API packages subsumed by this specification are:
■
■
■
■
■
■
org.w3c.dom.*
org.w3c.dom.css.*
org.w3c.dom.events.*
org.w3c.dom.html.*
org.w3c.dom.stylesheets.*
org.w3c.dom.views.*
Sun Microsystems, Inc.
10 of 51
The Common DOM API uses the service provider pattern. Third-party vendors
can provide their own implementation by implementing the
com.sun.java.browser.dom.DOMServiceProvider interface. The plug-in
provides an implementation in the package sun.plugin.dom.*. This
implementation uses the Java-to-JavaScript communication capability to
manipulate the browser DOM. The advantage of this approach is that it is a
browser-independent implementation. The disadvantage is that it depends on
the capabilities of the browser’s JavaScript support of the DOM.
The Common DOM API provides the applet with the ability to access the
browser DOM through a set of standard interface.
Due to the limitation of browser support on the DOM and JavaScript, plug-in
implementation of the DOM API is very limited. Some function calls throw
DOMUnsupportedException or return null when they should not.
Code samples illustrating the use of the Common DOM APIs are provided in
Section 4.1 “Common DOM APIs.”
2.1.5
Persistence APIs
The primary goal of the persistence API is to cause data to persist across the
pages within a browser session. This is a common requirement of browser.
There are several approaches to making data persistent across pages within a
browser session. These approaches are described in the following sections.
A code sample illustrating the use of the persistence API is provided in
Section 4.2 “Persistence APIs.”
2.1.5.1
Static Variable
Using a static variable to cause data to persist is simple. However, since the
lifetime of a Java object is often bounded to the classloader lifetime, this makes
the static variable approach less attractive and it will make the applet hang or
the browser crash.
2.1.5.2
Local Files
The Java object can be streamed into a local file. However, access to a local file
requires additional permissions, requiring the Java object to be signed.
Sun Microsystems, Inc.
11 of 51
2.1.5.3
Cookies
Two disadvantages exist for this approach. One is that the amount of data stored
using cookies is very limited, and the other is that extra connections back to the
server may be needed.
2.1.5.4
AppletContext
Beginning with the J2SDK, v 1.4, several new methods have been added to the
interface AppletContext.java to allow applet persistence across browser
sessions. These methods are:
■
■
■
setStream(String key, InputStream stream)
getStream(String key)
getStreamKeys()
These new methods enable the applet developer to stream data and objects from
one browser session so that they can be reused in subsequent browser sessions.
This provides applet persistence and makes it unnecessary to use static objects
in applets for this same purpose.
setStream(key, stream) maps a key to a stream. getStream(key) returns
the stream mapped to the key. If the AppletContext already has a stream
mapped to the key when setStream(key, stream) is invoked, the mapping
is updated. getStreamKeys() finds all the keys of the streams in this applet
context.
For security reasons, the mapping of streams and keys exists for each codebase.
In other words, an applet from one codebase cannot access the streams created
by an applet from a different codebase.
2.1.6
File Caching
Starting with version 1.4, Java Plug-In, by default, caches files of the following
types downloaded by using HTTP and HTTPS protocols.
■
■
■
■
■
■
■
.jar (jar file)
.zip (zip file)
.class (Java class file)
.au (audio file)
.wav (audio file)
.jpg (image file)
.gif (image file)
A code sample illustrating file caching is provided in Section 4.3 “File Caching.”
Sun Microsystems, Inc.
12 of 51
2.1.6.1
Configuring the Cache
The default location of the cache for JAR files is:
<user home>/.jpi_cache/jar/1.0
The default location of the cache for non-JAR files is:
<user home>/.jpi_cache/file/1.0
Where <user home> is the value of the system property user.home. Its value
is dependent on the operating system. Refer to Section 8 “Configuring Java
Plug-In” for more information.
Cache can be configured to user-specific settings by using the Java Plug-In
control panel. Refer to Section 8 “Configuring Java Plug-In” for details.
2.1.6.2
HTML Parameters for JAR Files
Java Plug-In does not require any special parameters in HTML tags in order to
use Java Plug-In cache. Whenever a .jar file is required to run an applet, Java
Plug-In checks whether or not that file exists in the cache. If it exists, before
using the cached file, Plug-In verifies whether the file is up to date by obtaining
the header information from the host.
For performance reasons, some users do not like to make a connection every
time they run their applets. Java Plug-In resolves this issue by using the HTML
parameters cache_archive and cache_version. Similar to the HTML
parameter archive, users can specify .jar files in the HTML parameter
cache_archive. For each of the .jar files specified in cache_archive, users
can specify the version in the format x.x.x.x, where x is an hexadecimal number
ranging from 0000-FFFF. When a version is specified for a .jar file, Plug-In
checks whether or not the version for the cached .jar file is equal to or greater
than the version specified in the HTML page. If yes, it uses the cached .jar file.
Otherwise, it downloads the .jar file. This avoids extra connections to verify
the .jar file.
In order to allow preloading of .jar files, a new HTML parameter called
cache_archive_ex has been added. This parameter allows users to specify
whether the .jar file needs to be preloaded. Optionally, the version of the .jar
file can also be specified.
The value of cache_archive_ex has the following format:
cache_archive_ex = "<jarfilename>;<preload(optional)>;<jar file
version(optional)>
Sun Microsystems, Inc.
13 of 51
The optional tags, such as preload or the .jar file version, can be listed after the
.jar file name in any order separated by the semi-colon delimiter (;).
Java Plug-In does not compare the versions if they are not specified for all the
.jar files in HTML parameter cache_archive. If cache_archive is used
without cache_version, the .jar files specified in cache_archive are
treated no differently than the .jar files specified in the HTML parameter
archive. Similar treatment goes to the .jar files specified in
cache_archive_ex without preload or version options.
Class files and resources will be searched in the following order from the .jar
files specified by the HTML parameters:
1. cache_archive_ex
2. cache_archive
3. archive
2.1.6.3
Update Logic
Files in the cache will be updated based on the following attributes:
■
■
■
Expiration date - obtained from the HTTP/HTTPS header
Last modify date - obtained from the HTTP/HTTPS header
Version - specified in cache_version/cache_archive_ex HTML
parameter
If the version is specified for a file and if the specified version is greater than the
version of the cached file, the cached file is marked as unusable and the new file
is downloaded from the web server.
Note – Only .jar files can be given versions.
If the version is not specified, the necessary connection is made to the web
server to obtain the expiration date and last modify date. Expiration date and
last modify date for the cached file are compared to determine if it is up to date.
If it is not, the new file is downloaded from the web server.
2.1.6.4
Cache Cleanup Policy
Whenever a new file is added into the cache, if the cache size exceeds the
specified limit, it will try to remove some of the unusable and the least recently
used files until the cache size is within the limit. Unusable files are deleted
Sun Microsystems, Inc.
14 of 51
before any usable files are. Among the usable files, non-.jar files are removed
before the .jar files since it takes more time to download a .jar file. Cache
Viewer allows the user to selectively delete the cached files. An option to delete
files from the cache is available in the Cache tab of the control panel.
2.1.7
XP/IE6.0
Since Microsoft announced that there will be no JVM bundled with the
upcoming Microsoft Windows XP and IE 6, the APPLET tag will launch applets
using Java Plug-In. An option is provided for users to set Sun’s JRE as the
default runtime environment for handling the APPLET tags.
Java Plug-In provides support for the APPLET tag on the following web
browsers:
■
■
2.1.7.1
Netscape, v. 6.0, 6.1
Microsoft IE, v. 4.0 (4.01 recommended), 5.0 (5.01 recommended), 5.5 (Service
Pack 2 recommended), 6.0
Enabling APPLET Tag Support
End users of Java Plug-In could enable or disable APPLET tag support during
installation or at any time after installation.
During installation, users are given an option to select JRE/Java Plug-In to be
the default runtime environment for handling APPLET tags in Netscape 6
browsers and Microsoft IE browsers. The installer uses the Microsoft Windows
registry to determine whether the user’s machine has these browsers installed
and checks by default the boxes corresponding to any installed browser.
The user can enable or disable APPLET tag support after installation through the
browser panel of the Java Plug-In control panel.
On Microsoft IE, users also can use the Advanced tab in the Internet Options
window to enable or disable Java Plug-In’s APPLET tag support.
2.1.7.2
Deployment Model
For developers, the Java Plug-In enhancements enable you to deploy your
applet web pages without the need for an HTML converter or the use of OBJECT
tags while still ensuring that your users will have the latest JRE/Java Plug-In for
running your code. In outline form, the new model for launching an applet is as
follows:
Sun Microsystems, Inc.
15 of 51
■
■
The user accesses a web page which employs APPLET tags (not OBJECT tags)
to invoke an applet.
The web page invokes a script that determines whether the latest, enhanced
JRE/Java Plug-In is installed on the user’s machine. For more information on
this script, see:
http://java.sun.com/j2se/1.4/docs/guide/plugin/
developer_guide/oji.html#automatic
■
■
2.2
If the latest, enhanced JRE/Java Plug-In is not installed on the user’s
machine, the script initiates an auto-download process for the JRE/Java
Plug-In.
If the latest JRE/Java Plug-In from Sun is installed on the user’s machine,
Java Plug-In checks whether the user has selected it as the default runtime
environment for running applets. If so, then the applet is launched on Sun’s
JRE. If not, the browser’s internal JRE, if it has one, will be used to run the
applet.
Bugs Fixed in Version 1.4
The bugs fixed in version 1.4 can be found in the Java Plug-In category in
merlin/1.4 at:
http://developer.java.sun.com/developer/bugParade/
index.jshtml
2.3
Previous Versions of Java Plug-In
■
1.1.x
http://java.sun.com/products/jdk/1.1/jre/
■
1.2.x
http://java.sun.com/products/jdk/1.2/jre/
■
1.3.x
http://java.sun.com/j2se/1.3/jre/
2.4
Upgrading to Version 1.4 From a Previous
Version
Upgrading is the same as installing for the first time. Simply follow the normal
installation instructions.
Sun Microsystems, Inc.
16 of 51
2.5
Porting Applications to Version 1.4
Applets developed for previous version of Java Plug-In should work fine
without any modifications.
Sun Microsystems, Inc.
17 of 51
3
HTML Converter
The HTML converter is used to convert your HTML files with <APPLET> tags to
HTML files with <OBJECT> and <EMBED> tags. The HTML converter is
included with the J2SDK, not the JRE. To run the converter, go to the lib
subdirectory of your SDK installation directory. The converter
(htmlconverter.jar) is contained in that directory.
To launch the converter, go to the directory where htmlconverter.jar is
located and type:
<full path to java command\java> -jar htmlconverter.jar -gui
This applies to all platforms.
To convert a single file within a folder, you may specify the path to the file and
include the file name. Browse for the file and select it.
To convert all files within a folder:
1. Type in the path to the folder or choose the browse button to select a folder
from a dialog box.
Once you have chosen a path, you may supply any number of file specifiers
in Matching File Names. Each specifier must be separated by a comma. You
may use * as a wildcard.
2. To make all files in nested folders match the file name to be converted, select
the checkbox Include Subfolders.
3. Choose the backup folder for converted files.
The default backup folder path is the source path with a _BAK appended to
the name. The backup path may be changed by entering a path in the field
labeled Backup Files to Folder or by browsing for a folder.
4. To generate a log file, go to the Advanced Options screen (Edit-->Options)
and check Generate Log File.
Sun Microsystems, Inc.
18 of 51
5. Enter a path in the text field or browse to choose a folder.
The log file contains basic information related to the conversion process.
The conversion template defines for which types of browsers converted
HTML pages will work. A default template will be used if none is chosen.
This template will produce converted HTML files that will work with IE and
Netscape.
6. To use a different template, choose it from the menu on the main screen.
If you choose Other Template... from the menu, you will be allowed to choose
a file to be used as the template. If you choose a file, be sure that it is a
template.
7. If you want, choose to have conversion tags that will require the specified
version of Java Plug-In run your applets.
If the specified version is not installed, then the client will be asked if he/she
wants to install and download it.
You can choose conversion tags that will allow any installed version of Java
Plug-In in the family (the first two numbers in the version indicate the family;
for example, 1.4.3_02 is in the 1.4 family), equal to or higher than the specified
version, to run your applets. If there is no installed version of Java Plug-In or
no installed version in the family equal to or higher than the specified
version, then the client will be asked if he/she wants to install and run the
latest version of Java Plug-In in the family.
8. Click the Convert button to begin the conversion process.
A dialog will show the files being processed, the number of files processed,
the number of applets found, and number of errors.
Sun Microsystems, Inc.
19 of 51
4
Code Samples
The following or section may contain actual software programs in source code
form. This source code is made available for developers to use as needed,
pursuant to the terms and conditions of this license located at:
http://access1.sun.com/SRDs/BSD.html
4.1
Common DOM APIs
The Common DOM APIs are new in J2SE, v. 1.4. They are described in
Section 2.1.4 “Common DOM APIs.”
4.1.1
Object Creation
This sample demonstrates how to use the DOM API to create various objects. A
programmer can use the DOM API to dynamically create various elements in a
DOM to make dynamic content on HTML document.
import
import
import
import
java.applet.*;
com.sun.java.browser.dom.*;
org.w3c.dom.*;
org.w3c.dom.html.*;
public class DocCreation extends Applet
{
public Applet myApplet;
public void init() {
myApplet = this;
}
public void start() {
try {
// get browser DOM service
DOMService service = DOMService.getService(myApplet);
Sun Microsystems, Inc.
20 of 51
// retrieve DOM document element. According to spec, following code
// will ensure that it will run from event dispatch thread to
// avoid dead-lock.
service.invokeLater(new DOMAction() {
public Object run(DOMAccessor accessor)
{
Document doc = accessor.getDocument(myApplet);
docCreateElement(doc);
docCreateObject(doc);
docCreatePI(doc);
return doc;
}
}
);
}
catch (DOMException e1){
e1.printStackTrace();
}
catch (DOMUnsupportedException e2) {
e2.printStackTrace();
}
catch (Exception e3) {
e3.printStackTrace();
}
}
/*
* The method create a HTML element on the document
*
* @param doc document
*/
public void docCreateElement(Document doc) {
try {
Element elem;
// Try to create a new element in the document(
// Feature Not_supported yet)
elem = doc.createElement("TABLE");
if(elem !=null)
{
System.out.println("Element created");
}
} catch(DOMException e) {
e.printStackTrace();
}
}
/*
* Method to test the creation of different document objects
* e.g DocumentFragment
Sun Microsystems, Inc.
21 of 51
*
* @param doc document
*/
public void docCreateObject(Document doc) {
try {
//Try to create an empty DocumentFragment
DocumentFragment df = doc.createDocumentFragment();
testname = "DocCreationTestCreateDocumentFragment";
if (df !=null)
System.out.println("DocumentFragment created");
// Create a Text node
Text tn = doc.createTextNode("NEW_NODE");
if(tn != null)
System.out.println("New Text node created");
// Create a Comment node
Comment cmnt = doc.createComment("TEST_COMMENT");
if(cmnt !=null)
System.out.println("New Comment node created");
// Create CDATA node
CDATASection cds = doc.createCDATASection(
"TEST_CDATASection");
if(cds != null)
System.out.println("New CDATA node created");
}
catch (Exception e){
e.printStackTrace();
}
}
/*
* The method create a processing instruction
*
* @param doc document
*/
public void docCreatePI(Document doc) {
try {
//Try to create processing instruction
ProcessingInstruction pi =
doc.createProcessingInstruction(
"TEST_TARGET","TEST_DATA");
if(pi != null)
System.out.println("New PI created");
} catch(DOMException e) {
//Raised if an Document is an HTML Document
if(e.code == DOMException.NOT_SUPPORTED_ERR){
System.out.println("Create PI not supported");
}
else {
if(e.code == DOMException.INVALID_CHARACTER_ERR) {
Sun Microsystems, Inc.
22 of 51
System.out.println(
"PI contains invalid character");
}
else {
System.out.println("Other error");
}
}
}
}
}
4.1.2
Retrieve HTML Title
This sample shows how to retrieve an HTML document title through the DOM
APIs. Using this sample as a base, a programmer can extend the code to walk
through the HTML document DOM to retrieve the information needed.
import
import
import
import
java.applet.*;
com.sun.java.browser.dom.*;
org.w3c.dom.*;
org.w3c.dom.html.*;
public class HTMLTitle extends Applet
{
public Applet myApplet;
public void init() {
myApplet = this;
}
public void start() {
try {
// get browser DOM service
DOMService service = DOMService.getService(myApplet);
// retrieve HTML document DOM.
HTMLDocument doc = (HTMLDocument)service.invokeAndWait(
new DOMAction() {
public Object run(DOMAccessor accessor)
{
HTMLDocument doc =
(HTMLDocument) accessor.getDocument();
return doc;
}
}
);
// Once we have Document, we can walk through the document DOM
// tree. Here, we only demonstrate how to get document title. But
// anyone who is familiar with W3C DOM API, can extend to code to
// retrieve various elements inside the document.
String title = doc.getTitle();
Sun Microsystems, Inc.
23 of 51
}
catch (DOMException e1){
e1.printStackTrace();
}
catch (DOMUnsupportedException e2) {
e2.printStackTrace();
}
catch (Exception e3) {
e3.printStackTrace();
}
}
}
4.2
Persistence APIs
In the following example, a class called PersistentData is created. Its state
will persist across pages since the object of PersistentData will persist in
memory. This requires the class to implement a Serializable interface.
During the applet init method, we first call getStream(String key) to get
an InputStream. If the applet is loaded for the first time, the return value from
that function is null. As a result, we may need to call the constructor to create a
new instance of PersistentData.
When the page is switched or refreshed, the applet stop method is called. In the
code we first get an ObjectOutputStream to serialize the data into memory
and then create an ByteArrayInputStream from that ObjectOutputStream
and call setStream to match the data with a unique key.
import java.applet.*;
import java.awt.*;
import java.io.*;
public class PersistenceApplet extends Applet {
private PersistentData pd = null;
public void init()
{
try {
InputStream in = getAppletContext().getStream("My Data");
if (in == null)
{
// Initialize the data
pd = new PersistentData();
}
else {
ObjectInputStream oin = new ObjectInputStream(in);
pd = (PersistentData)(oin.readObject());
System.out.println(pd.getAngle());
Sun Microsystems, Inc.
24 of 51
in.close();
oin.close();
}
}
catch(Exception e)
{
System.out.println(e + "Exception caught");
}
}
public void stop()
{
System.out.println("Applet get stoped");
try {
ByteArrayOutputStream bout =
new ByteArrayOutputStream();
ObjectOutputStream out =
new ObjectOutputStream(bout);
out.writeObject(pd);
ByteArrayInputStream bin =
new ByteArrayInputStream(bout.toByteArray());
getAppletContext().setStream("My Data", bin);
out.close();
bin.close();
}
catch(Exception e)
{
Thread.dumpStack();
}
}
}
class PersistentData implements Serializable {
private int angle = 0;
public PersistentData()
{
angle = 45;
}
public int getAngle()
{
return angle;
}
}
4.3
File Caching
In this example:
■
■
app.jar is specified in archive
util.jar is specified in cache_archive
Sun Microsystems, Inc.
25 of 51
■
■
■
■
The version is specified for util.jar as 0.1.A.1
tool.jar is specified to be pre-loaded in cache_archive_ex
support.jar is also specified to be pre-loaded but along with the version
games.jar, only the version is specified
<HTML>
<TITLE>Jar Cache Version Sample page</TITLE>
<BODY>
<APPLET WIDTH = 400 HEIGHT = 300 NAME = "TestApplet" CODEBASE=".">
<PARAM NAME = archive VALUE="app.jar">
<PARAM NAME = cache_archive VALUE = "util.jar" >
<PARAM NAME = cache_version VALUE ="0.1.A.1">
<PARAM NAME = cache_archive_ex VALUE =
"tool.jar;preload,support.jar;0.0.a.abcd;PRELOAD,games.jar;0.9.8.7">
</APPLET>
</BODY>
</HTML>
4.4
Scripting
4.4.1
JavaScript to Java
To communicate from JavaScript to Java, the developer needs to establish the
name of the object they will be communicating with. This is done by assigning a
NAME or ID in the APPLET/EMBED and OBJECT tags, respectively. This name is
used to refer to the applet you are communicating with. Consider the following
example.
<html>
<head>
<title>A simple Test of Liveconnect: Javascript call Java</title>
</head>
<body>
<h1>A simple Test of Liveconnect: Javascript call Java</h1>
<h3><I> Click the button to see if the color is changing or not</
I><h3>
<Applet code = "SimpleApplet.class" Name = myApplet width = 200 height
= 200></Applet>
<Form id = form1 name = myForm>
<INPUT id=button1 onclick=clickMe() type=button value="Click Me"
name=buttonOne>
</Form>
<script>
function clickMe(){
document.myApplet.changeColor();
Sun Microsystems, Inc.
26 of 51
}
</script>
</html>
Note the name “myApplet” and the calling convention:
document.myApplet.<functionname>
The single most important thing to remember about JavaScript-to-Java
communication is that it does not work with Netscape 4.X.
4.4.2
Java to JavaScript
Java-to-JavaScript communication centers around the JSObject object. Objects
of this type provide the interface that allow for calling back to the browser.
A transaction always starts with a call to:
public static JSObject getWindow(Applet a)
which returns a JSObject for the window that contains the given applet. Here
is an example of Java code that acquires information from the browser for the
document that contains the applet.
public void init() {
// Starting point
JSObject win = JSObject.getWindow(this);
// get the document object
JSObject doc = (JSObject) win.getMember("document");
// get the location object
JSObject loc = (JSObject) doc.getMember("location");
// call the "f" function in the HTML page
String s = (String) loc.getMember("href"); // get the href object
win.call("f",null);
}
Finally, it is important to understand that these communication mechanisms do
not work at all in the AppletViewer. Web developers trying to test their code in
that environment will be unsuccessful.
Sun Microsystems, Inc.
27 of 51
5
Troubleshooting
5.1
Common User Questions
Frequently asked questions are located at:
http://java.sun.com/j2se/1.4/docs/guide/plugin/
developer_guide/faq/index.html
5.2
Troubleshooting Utilities
5.2.1
Isolating Java Plug-In Bugs
Many bugs reported against Java Plug-In are related to other parts of JRE/JDK.
Some of the approaches to identify Java Plug-In bugs are as follows:
■
Use appletviewer
You can run your applets that do not use any scripting with appletviewer. If
the bug is reproducible, it is likely that it is a problem related to JRE.
■
Select different JRE/JDK through the control panel
Java Plug-In allows users to use Java Plug-In with different versions of JRE/
JDK that exist on the user's machine. Try running the applet with a different
version of the JRE/JDK. See Section 8 “Configuring Java Plug-In.” If the bug
is not reproducible with a previous version of JRE/JDK, it is likely a JRE
problem.
Sun Microsystems, Inc.
28 of 51
■
Use different browsers
Try to run your applet in both Netscape and IE browsers. If the problem is
reproducible in both the browsers, it is likely a Java Plug-In problem.
Otherwise, it could be a bug in the browser code.
■
Use Java run-time parameters
Certain Java run-time parameters are used by each java package to identify
bugs in it. You may have to consult the appropriate teams to find out about
these parameters. For example Java 2D team uses the property
sun.java2d.noddraw=true to isolate Java 2D bugs
5.2.2
Basic Debugging Techniques
The Java console allows you to do basic debugging. Options are available to:
■
■
■
■
■
Enable/disable different levels of tracing
Watch the threads
List the classloaders
List the system properties
Watch debug/error messages from Applet/Java Plug-In
To see debug messages so that you can analyze the problem, different levels of
tracing can be enabled using the Java console or control panel. Logging and
assertion can also be enabled for debugging.
5.2.3
Troubleshooting Deadlocks
If the browser deadlocks while running an applet, it is possible to dump the
stack trace for all the threads. Steps to dump the stack are as follows:
1. Specify the Java run-time parameter -Dverbose in the Advanced tab of the
Java Plug-In control panel.
A DOS window is displayed with a VM debug message.
2. When the browser deadlocks, type Ctl-Alt-Brk in the DOS window
5.2.4
Debugging an Applet
Steps to debugging an applet:
Sun Microsystems, Inc.
29 of 51
1. Compile your applet with the -g option.
2. Switch the Java Plug-In to use the SDK in Advanced tab of the Java Plug-In
control panel.
Debugger is available only with SDK.
3. Specify Java Runtime Parameters in Advanced tab of the Java Plug-In control
panel.
-Djava.compiler=NONE , -Xnoagent, -Xdebug, &
-Xrunjdwp:transport=dt_shmem, address=2502, server=y,suspend=n
4. Run the applet in either the IE or Netscape browser.
5. Attach the debugger to the browser process by running the following
command line:
jdb -attach 2502
5.3
Common Developer Problems
5.3.1
Static Variables
Static variables are bound to the classloader’s life time. Classloaders are reused
and cached to improve the performance of an applet. The reuse of a classloader
is based on the codebase and the HTML parameters archive, cache_archive,
and cache_archive_ex. Because of reuse and caching, the life time of a
classloader is not predictable. Hence, the values of static variables are
unpredictable.
To overcome this problem, do not use static variables. If it is necessary for data
to persist safely across pages , use the persistence APIs. They are explained in
Section 2 “Product Changes for Version 1.4.”
5.3.2
Threads
In J2SE, v. 1.2, the stop() method in Thread Class was deprecated since it could
result in inconsistent states. An applet could create many threads to accomplish
its functionality. If the applet threads fail to handle InterruptedException in
its run() method, the threads will persist even after the page switches.
Sun Microsystems, Inc.
30 of 51
5.3.3
Applet Life Cycle
Assumptions about the life cycle methods init(), start(), stop(), and
destroy() could result in problems. For example, with Java Plug-In it is not
possible to invoke Java methods from JavaScript in init() methods. If any of
the features depend on applet life cycle methods, check the developer’s guide
at:
http://java.sun.com/j2se/1.4/docs/guide/plugin/
developer_guide/contents.html
5.4
Common Installation and Uninstallation
Problems
■
Java Plug-In-generated files are not removed during uninstallation [.trace,
.log ....]
■
Uninstalling one version of Java Plug-In removes support for legacy CLSID
and MIME types.
If multiple versions of the Java Plug-In are installed on the same machine and
if any one version is uninstalled, support for legacy CLSID and MIME types
is no longer available.
■
Uninstaller does not remove some files.
This happens only if any of the files that needs to be removed are being used
by at least one process. Such files are removed automatically after a reboot.
5.5
Common User Problems
The following sections describe some of the common problems users may
encounter when using Java Plug-In.
See the published FAQ for additional issues:
http://java.sun.com/j2se/1.4/docs/guide/plugin/
developer_guide/faq/index.html
Sun Microsystems, Inc.
31 of 51
5.5.1
Java/JavaScript
■
Java methods invoked from JavaScript will not be in the applet’s thread
group.
There could be deadlocks since the Java method might post the events to a
wrong event queue.
■
Invoking JavaScript methods in an event dispatch thread could result in
deadlocks.
For example, if the JavaScript method invokes the Java method which
executes a method in the event dispatch thread, it cannot execute until the
JavaScript method returns, which, in turn, cannot return until the Java
method is finished. Hence there will be deadlock.
■
5.5.2
JavaScript to Java does not work before init() is called.
HTTPS Through JSSE
Although supporting HTTPS through JSSE eliminates lots of browser-specific
problems in the Java Plug-In, there are some potential issues that developers
may need to be aware of:
■
Untrusted server certificate
When SSL handshaking takes place in establishing the HTTPS connection, the
server certificate is verified against the root Certification Authority (CA) store
in J2SE. The number of root CA certificates supported in J2SE is not as broad
as those supported in the browser. As a result, some developers may
experience an untrusted server certification problem when the certificate of
the HTTPS server is issued by a CA not recognized by J2SE.
■
Client authentication
Some HTTPS servers may require client authentication, and a local client
certificate is sent to the server for authentication. In JSSE, the client certificate
is stored in a separate file that is independent with the browser. For client
authentication to work, developers are required to import their client
certificate into JSSE through the keytool. Please review the JSSE
documentation for more information.
http://java.sun.com/j2se/1.4/docs/guide/security/jsse/
JSSERefGuide.html
Sun Microsystems, Inc.
32 of 51
■
Level of error handling
Java Plug-In currently handles the types of errors listed in the previous
section. If there are additional types of errors that Java Plug-In does not
recognize, the Java applet code may break.
■
Startup delay
When HTTPS is used, a secure random number generator will be created.
This process may take several seconds or up to a minute, depending on the
speed of the client machine. In some cases, Java Plug-In may appear to be
hung during the creation of secure random number. This issue has been
addressed by delaying the loading of HTTPS code in Java Plug-In, so Java
Plug-In startup time should not be affected if HTTPS is not used. However,
some users may still see the startup delay, depending on the exact loading
sequence of the startup code in Java Plug-In.
5.5.3
Multi-Version
Legacy CLSID and MIME types use the latest installed Java Plug-In. For
example, if Java Plug-In, v. 1.3, is installed after Java Plug-In, v. 1.4, is installed
on a machine, Java Plug-In, v. 1.3, will be used by applets if legacy CLSID and
MIME types are specified in the HTML page
On Microsoft Windows, it is not possible to run applets requiring more than one
version of Java Plug-In in the same browser session.
5.5.4
Compatibility issues between Microsoft VM and
Java 2
The APPLET will cause JRE, v. 1.4, to run applets even if they were written
primarily to run in IE using the Microsoft VM. Since the Microsoft VM and JRE,
v. 1.4, implementations are quite different, users may experience problems. To
understand the compatibility issues between Microsoft VM and JRE, v. 1.4, see:
http://java.sun.com/j2se/1.4/docs/guide/plugin/
developer_guide/compatibility.html
Sun Microsystems, Inc.
33 of 51
5.5.5
Signed Applet (RSA Verification)
If the .jar file is not signed properly, if the RSA certificate has expired, or if the
RSA certificate is a self-generated, self-signed certificate, Java Plug-In may fail
silently and not display the security dialog. The applet will be treated as
unsigned.
5.5.6
Optional Package Installation Issues
The following are some of the issues that may be encountered when installing
Java Plug-In to run with an optional package.
■
■
■
■
■
■
■
If the optional package installation is not signed properly, Java Plug-In will
fail silently.
If the version string ID naming convention is not followed in the manifest
files, the optional package installation will not work properly.
If the .jar files do not have a .jar or .zip extension, the optional package
installation will not work properly.
For optional package installation, please ensure that the newer version of the
optional package contains at least the same set of the JAR file names as the
older version. Otherwise, installing a newer optional package may not
overwrite all the older optional package, and there will be a mix of different
versions of optional packages in the same Java runtime. The results will be
unpredictable.
If the applet consists of several JAR files, only one of them is required to have
the optional package versioning information if optional package installation
is used. We recommend putting the versioning information in the first JAR
specified in the archive/cache_archive attribute to speed up the optional
package download.
If the optional package consists of several JAR files and is installed through a
Java installer or a native installer, only one of the JAR files is required to have
the optional package versioning information. However, for raw optional
package installation, each JAR files must contain the proper optional package
versioning information.
If a Java installer is used, make sure the program does not exit the main-class
until the installation is done. In some cases, the Java installer may create an
Abstract Window Toolkit (AWT) window and switch control to a different
thread and return immediately from main-class. Returning control from the
main-class will force the applets to be loaded and started immediately even if
the Java installer is still in the process of installation. This will cause the
applet to fail to load because the optional package is not installed yet.
Sun Microsystems, Inc.
34 of 51
6
Installing Java Plug-In
6.1
Product Distribution
The Java Plug-In is part of the JRE, v. 1.4. For more information or to download
the software, see the J2SE home page at:
http://java.sun.com/j2se/1.4
6.2
Product Licensing
The licensing agreement (LICENSE) can be found at the J2SE home page at:
http://java.sun.com/j2se/1.4
Also, the license agreement will be displayed when the software is downloaded
and installed.
6.3
Hardware Requirements and Dependencies
6.3.1
Platforms Supported
Operating Systems Supported:
■
■
■
Solaris OE
Linux
Windows 95/98SE/ME/NT 4.0/2000/XP
Sun Microsystems, Inc.
35 of 51
6.3.2
Disk Space Requirements
For disk space requirement, see the installation document for the particular
platform of interest found at the JRE, v. 1.4, home page at:
http://java.sun.com/j2se/1.4/jre
The disk space requirements change, depending on the platform and what J2SE
is installed.
TABLE 6-1
Disk Space Required to Download and Install JRE
Platform
Download File Name
Download File Size
Solaris
j2re-1_4_0-solsparc.sh
22629616 bytes
j2re-1_4_0-solx86.sh
20455032 bytes
j2re-1_4_0-win.exe
9371328 bytes
40 MB
j2re-1_4_0-win-i.exe
12212160 bytes
40 MB
j2re-1_4_0-linux-i386-rpm.bin
21271739 bytes
45 MB
j2re-1_4_0-linux-i386.bin
21820327 bytes
45 MB
Windows
Linux
Free Disk Space required
6.4
Software Requirements and Dependencies
6.4.1
Required Operating System Patches
For a listing of the required patches needed for this release, see the Solaris
installation document found at the J2SE, v. 1.4, home page:
http://java.sun.com/j2se/1.4
Also see the following URLs for more information.
Solaris patches for J2SDK, v. 1.4.0:
http://java.sun.com/j2se/1.4/install-solaris-patches.html
Solaris patch installation instructions:
http://java.sun.com/j2se/1.4/install-patches.html
Sun Microsystems, Inc.
36 of 51
6.4.2
Product Dependencies
Browsers supported:
■
■
Netscape 4, Netscape 6.2.1 and higher
Microsoft IE 4/5/6
6.5
Installing Java Plug-In
6.5.1
Downloading Java Plug-In
The Java Plug-In is part of the JRE, v. 1.4. For more information or to download
the software, see the J2SE home page at:
http://java.sun.com/j2se/1.4
6.5.2
Pre-Installation Considerations
For pre-installation consideration, see the installation document for the
particular platform of interest found at the J2SE v. 1.4, home page:
http://java.sun.com/j2se/1.4/jre
Also see the Readme and Release Notes found at this site for any other
information that may be relevant.
6.5.3
Default Installation Path
See Section 7.2 “Directories Created at Installation.”
6.5.4
Steps for Installing Java Plug-In
Installation notes for each of the supported platforms can be found at the J2SE
home page, in the installation document at:
http://java.sun.com/j2se/1.4
Sun Microsystems, Inc.
37 of 51
6.5.4.1
Solaris OE
The JRE, Standard Edition, v. 1.4, comes as a self-extracting binary file.
1. Make sure that execute permissions are set on the self-extracting binary:
chmod +x j2re-1_4_0-{solsparc, solx86}.sh
2. Change directory to the location where you would like the files to be
installed.
3. Run the self-extracting binary.
A directory called j2re1.4.0 will be created in the current directory.
4. Set the NPX_PLUGIN_PATH environment variable to the directory
containing the javaplugin.so file.
javaplugin.so is a solaris shared object library. The default location of
javaplugin140.so for the package installation is in this directory:
/usr/j2se/jre/plugin/<arch>/ns4/
5. For Netscape 6 browsers: Use regxpcom tool provided by Netscape to
register Java Plug-In, v. 1.4.
If you are using Netscape 6, you will need to use regxpcom provided by
Netscape to register the libjavaplugin_oji140.so file. In the package
installation of J2SDK, v. 1.4.0, this file is located at /usr/j2se/jre/
plugin/<arch>/ns600/libjavaplugin_oji140.so, where <arch> is
either sparc or i386, depending on your platform. For example:
cd ${NETSCAPE6}/bin
regxpcom ${JRE}/plugin/sparc/ns600/libjavaplugin_oji140.so
6. For all Netscape browsers: Start your Netscape browser, or restart it if it is
already running.
6.5.4.2
Linux OS
The JRE, Standard Edition, v. 1.4, comes in two installation formats: selfextracting binary file and a RPM file.
Installation of Self-Extracting Binary
1. Set execute permissions on the self-extracting binary:
chmod a+x j2re-1_4_0-linux-i386.bin
Sun Microsystems, Inc.
38 of 51
2. Change to the directory you want to install into.
3. Run j2re-1_4_0-linux-i386.bin and agree to the license it displays.
Once you have agreed to the license agreement, the install script will install
the JRE in a directory called j2re1.4.0 in the current directory.
Note – If you choose to install the JRE into system-wide location such as
/usr/local, you must first become root to gain the necessary permissions. If
you do not have root access, install the JRE into your home directory or a
subdirectory to which you have permission to write.
Installation of RPM File
1. Become root by running the su command and entering the super-user
password.
2. Type:
chmod a+x j2re-1_4_0-linux-i386-rpm.bin
3. Run j2re-1_4_0-linux-i386-rpm.bin and agree to the license it
displays.
Once you have agreed to the license, the install script will create the file
j2re-1_4_0-linux-i386.rpm in the current directory.
4. Run the rpm command to install the packages:
rpm -iv j2re-1_4_0-linux-i386.rpm
This will install the packages comprising the JRE.
5. Exit the root shell.
Java Plug-In Specific Setup Steps
1. Uninstall previous installation of the Java Plug-In, if applicable.
rm -fr $HOME/.netscape/java
rm $HOME/.netscape/plugins/javaplugin.so
rm $HOME/.netscape/plugins/libjavaplugin.so
One or more of these files may exist on your machine, depending on which
previous versions of Java Plug-In you have installed.
Sun Microsystems, Inc.
39 of 51
2. Set the NPX_PLUGIN_PATH environment variable to the directory containing
the javaplugin.so file.
This file is located inside the J2SDK in the jre/plugin/i386/ns4/
directory.
3. For Netscape 6 browsers: Use regxpcom tool provided by Netscape to
register Java Plug-In, v. 1.4.
4. If you are using Netscape 6, you will need to use regxpcom provided by
Netscape to register the libjavaplugin_oji140.so file.
In the package installation of J2SDK, v. 1.4, this file is located at:
/usr/j2se/jre/plugin/i386/ns600/libjavaplugin_oji140.so
For example:
cd ${NETSCAPE6}/bin
regxpcom ${JRE}/plugin/sparc/ns600/libjavaplugin_oji140.so
5. For all Netscape browsers: Start your Netscape browser, or restart it if it is
already up.
6.5.4.3
Microsoft Windows OS
The JRE comes in the form of a executable file.
1. Run the j2re-1_4_0-win.exe install program.
Note – You must have administrative permissions in order to install the JRE on
Microsoft Windows 2000 and Microsoft Windows XP.
2. Follow the instructions the installer provides.
3. When done with the installation, to recover more disk space, delete the
bundle you downloaded.
The installation process will also install the Java Plug-In product. Look for a
Java Plug-In icon in the Control Panel. To know about silent install techniques,
see:
http://java.sun.com/j2se/1.4/docs/guide/plugin/
developer_guide/silent.html
Sun Microsystems, Inc.
40 of 51
6.5.5
Steps for Installing Version 1.4 as an Upgrade
Installing Java Plug-In as an upgrade is the same as installing it for the first
time.
6.5.6
Post-Installation Considerations
Verify that installation of the Java Plug-In was successful in any of the following
ways.
6.5.6.1
Netscape 4.7x Users
Choose About Plug-Ins from Netscape’s Help Menu. Three sets of multipurpose Internet mail extensions (MIME) types should have been installed:
1. npjava11.dll Settings
File name:
C:\Program Files\Netscape\Communicator\Program\plugins\npjava11.dll
TABLE 6-2
Java Plug-In, v. 1.4, for Netscape Navigator (DLL Helper)
Mime Type Description
Suffixes
Enabled
application/x-java-bean
JavaBeans
Yes
application/x-java-applet
Java Applet
Yes
application/x-java-bean;version=1.1
JavaBeans
yes
application/x-java-applet;version=1.1
Java Applet
Yes
application/x-java-bean;version=1.1.1
JavaBeans
Yes
application/x-java-applet;version=1.1.1
Java Applet
Yes
2. npjava12.dll Settings
File name:
C:\Program Files\Netscape\Communicator\Program\plugins\npjava12.dll
Sun Microsystems, Inc.
41 of 51
TABLE 6-3
Java Plug-In 1.4.0 for Netscape Navigator (DLL Helper)
Mime Type Description
Suffixes
Enabled
application/x-java-bean;version=1.1.2
JavaBeans
Yes
application/x-java-applet;version=1.1.2
Java Applet
Yes
application/x-java-bean;version=1.1.3
JavaBeans
Yes
application/x-java-applet;version=1.1.3
Java Applet
Yes
application/x-java-bean;version=1.2
JavaBeans
Yes
application/x-java-applet;version=1.2
Java Applet
Yes
3. npjava32.dll Settings
File name:
C:\Program Files\Netscape\Communicator\Program\plugins\npjava32.dll
TABLE 6-4
Java Plug-In 1.4.0 for Netscape Navigator (DLL Helper)
Mime Type Description
Suffixes
Enabled
application/x-java-bean;version=1.2.1
JavaBeans
Yes
application/x-java-applet;version=1.2.1
Java Applet
Yes
application/x-java-bean;version=1.2.2
JavaBeans
Yes
application/x-java-applet;version=1.2.2
Java Applet
Yes
application/x-java-bean;version=1.3
JavaBeans
Yes
application/x-java-applet;version=1.3
Java Applet
Yes
4. npjava13.dll Settings
File name:
C:\Program Files\Netscape\Communicator\Program\plugins\npjava13.dll
TABLE 6-5
Java Plug-In 1.4.0 for Netscape Navigator (DLL Helper)
Mime Type Description
Suffixes
application/x-java-bean;version=1.4
Sun Microsystems, Inc.
JavaBeans
Enabled
Yes
42 of 51
TABLE 6-5
Java Plug-In 1.4.0 for Netscape Navigator (DLL Helper)
Mime Type Description
Suffixes
Enabled
application/x-java-applet;version=1.4
Java Applet
Yes
application/x-java-bean;version=1.3.1
JavaBeans
Yes
application/x-java-applet;version=1.3.1
Java Applet
Yes
5. npjpi140.dll Settings
File name:
C:\Program Files\Netscape\Communicator\Program\plugins\npjpi140.dll
TABLE 6-6
6.5.6.2
Java Plug-In 1.4.0 for Netscape Navigator (DLL Helper)
Mime Type Description
Suffixes
Enabled
application/x-java-bean;jpi-version=1.4
JavaBeans
Yes
application/x-java-applet;jpi-version=1.4
Java Applet
Yes
Netscape 6.1 Users
Choose About Plug-Ins from Netscape’s Help Menu. Three sets of multipurpose Internet mail extensions (MIME) types should have been installed:
1. npoji610.dll Settings
File name:
C:\Program Files\Java\j2re1.4.0\bin\NPOJI610.dll
TABLE 6-7
Sun's Java(tm) Plug-In
Mime Type Description
Suffixes
Enabled
application/x-java-bean
JavaBeans
Yes
application/x-java-applet
Java Applet
Yes
application/x-java-bean;version=1.1
JavaBeans
Yes
application/x-java-applet;version=1.1
Java Applet
Yes
application/x-java-bean;version=1.1.1
JavaBeans
Yes
application/x-java-applet;version=1.1.1
Java Applet
Yes
application/x-java-bean;version=1.1.2
JavaBeans
Yes
application/x-java-applet;version=1.1.2
Java Applet
Yes
Sun Microsystems, Inc.
43 of 51
TABLE 6-7
6.5.6.3
Sun's Java(tm) Plug-In
Mime Type Description
Suffixes
Enabled
application/x-java-bean;version=1.1.3
JavaBeans
Yes
application/x-java-applet;version=1.1.3
Java Applet
Yes
application/x-java-bean;version=1.2
JavaBeans
Yes
application/x-java-applet;version=1.2
Java Applet
Yes
application/x-java-bean;version=1.2.1
JavaBeans
Yes
application/x-java-applet;version=1.2.1
Java Applet
Yes
application/x-java-bean;version=1.2.2
JavaBeans
Yes
application/x-java-applet;version=1.2.2
Java Applet
Yes
application/x-java-bean;version=1.3
JavaBeans
Yes
application/x-java-applet;version=1.3
Java Applet
Yes
application/x-java-bean;version=1.4
JavaBeans
Yes
application/x-java-applet;version=1.4
Java Applet
Yes
application/x-java-bean;version=1.3.1
JavaBeans
Yes
application/x-java-applet;version=1.3.1
Java Applet
Yes
application/x-java-bean;jpi-version=1.4
JavaBeans
Yes
application/x-java-applet;jpi-version=1.4
Java Applet
Yes
Microsoft IE Users
Use your Explore window and look at the <windows directory>\Downloaded
Program Files. Here you should see JRE, v. 1.4, the Java Plug-In ActiveX
component used with Microsoft IE to execute Java Plug-In.
6.6
Uninstalling Java Plug-In
Uninstall instructions for each of the supported platforms can be found at the
J2SE home page in the installation document located at:
http://java.sun.com/j2se/1.4
6.6.1
Solaris OE
rm -rf <install directory>/j2re1.4.0
Sun Microsystems, Inc.
44 of 51
6.6.2
Linux OS
● To determine if a JRE is installed, type:
rpm -query -a | grep j2re-<version>
● To remove the JRE package, type:
rpm -e j2re-<version>
6.6.3
Microsoft Windows OS
Use the Add/Remove Programs utility in the Microsoft Windows control panel
to remove the JRE.
Sun Microsystems, Inc.
45 of 51
7
Key Files and Directories
7.1
Configuration Files
For configuration, see Section 8.3 “Properties File.”
7.2
Directories Created at Installation
The following directories are created at installation:
■
Solaris OE
<install directory>/j2re1.4.0
■
Linux OS
/usr/java/j2re1.4.0
■
Microsoft Windows OS
C:\Program Files\Java\j2re1.4.0
The file javaplugin.so (used in NPX_PLUGIN_PATH environment variable)
is installed in the following locations:
■
Sparc
/<j2se>/jre/plugin/sparc/ns4/
■
Intel x86
/<j2se>/jre/plugin/i386/ns4/
7.3
Generated Files and Their Locations
■
Cache file location:
<user home>\.jpi_cache
Sun Microsystems, Inc.
46 of 51
Where <user home> is the value for system property user.home. For more
information, see Section 8.2 “user.home.”
■
.java directory
■
Files used in the Java Plug-In certificates support:
<user home>\.java
jpicerts140
jpihttpscerts140
■
Java Plug-In properties file that holds setting that are made in the Java PlugIn Control Panel:
properties140
■
Trace and log files:
C:\<Windows>\Profiles\<user>\
/home/<user>
.plugin140.log
.plugin140.trace
/tmp
child_java_vm140.trace
plugin_java140.trace
plugin_parent140.trace
■
Optional package directories:
■
Temporary directory containing optional package (extension) jar files:
■
Directory containing optional package (extension) jar files
<user home>\java_plugin_AppletStore/1.4.0/ext
C:\Program Files\Java\j2re1.4.0\jre\lib\ext
/j2sdk1.4.0/jre/lib/ext
7.4
Tools/Utilities location
Tools used with Java Plug-In are located in the directory:
/j2sdk1.4.0/bin
These tools include:
■
■
■
■
■
ControlPanel - Java Plug-In control setting tool
HtmlConverter - HTML converter tool
jar - Java archive tool
jarsigner - Jar signing tool
keytool - Key and certificate management tool
Tools used with Java Plug-In supported features, such as RSA signed applet,
Optional package deployment are located in the directory:
/j2re1.4.0/bin
Sun Microsystems, Inc.
47 of 51
These tools are available in the ControlPanel, the Java Plug-In control setting
tool.
Sun Microsystems, Inc.
48 of 51
8
Configuring Java Plug-In
8.1
Java Plug-In Control Panel
For information on Java Plug-In configuration, see:
http://java.sun.com/j2se/1.4/docs/guide/plugin/
developer_guide/control_panel.html
8.2
user.home
Java Plug-In configuration files, trace files, and default cache locations are based
on the system property user.home.
The default user.home is platform dependent.
■
On UNIX, the default user.home is /home/user
■
On Microsoft NT, 2000, and XP, the default user.home is same as the
environment variable USERPROFILE
■
On Microsoft Windows 98 and ME, the default user.home is c:\win98 and
c:\winme respectively
Independent of the platform, user.home can be set to any location by using an
envariable variable called USER_JPI_PROFILE.
8.3
Properties File
Control panel changes are stored in a file called the properties file. Each version
of the Java Plug-In has a unique properties file, which is named
properties<jpi-version>. For example, in Java Plug-In, v. 1.4, it is
Sun Microsystems, Inc.
49 of 51
properties140. Default settings can be altered by modifying the properties
file, and this allows system administrators to configure Java Plug-In on user
machines.
The following is the typical content of a properties file:
javaplugin.jre.path=C\:\\Java\\j2re1.4.0
javaplugin.proxy.usebrowsersettings=true
javaplugin.enabled=true
javaplugin.jre.version=1.4.0 rc
javaplugin.exception=false
javaplugin.cache.size=40m
javaplugin.debug.mode=false
javaplugin.jre.params=-Djavaplugin.trace\=true
javaplugin.jre.type=JRE
javaplugin.console=hide
8.4
Microsoft IE Control Panel
On Microsoft IE browsers, users can use the Advanced tab in the Internet
Options window to enable or disable Java Plug-In’s APPLET tag support.
Sun Microsystems, Inc.
50 of 51
9
Reference Information
9.1
Product Information
http://java.sun.com/products/plugin/
9.2
Technical Documentation
http://java.sun.com/j2se/1.4/docs/guide/plugin/
developer_guide/contents.html
9.3
Frequently Asked Questions
http://java.sun.com/j2se/1.4/docs/guide/plugin/
developer_guide/faq/index.html
9.4
Tutorials and Other References
Release notes
http://java.sun.com/j2se/1.4/relnotes.html#plugin
Sun Microsystems, Inc.
51 of 51