Table of Contents

The new Java Plug-In is designed to work in the following browsers:

• Internet Explorer 6 and 7 on Windows XP and Vista
• Firefox 3 on Windows XP, Windows Vista, Solaris and Linux

While other browsers are not specifically supported by Sun, if the browser is on one of the supported platforms and supports the latest version of the NPAPI and NPRuntime interfaces, the new Java Plug-In for Firefox ( npjp2.dll on Windows and libnpjp2.so on Unix platforms) should work in the browser. (Certain functionality, such as cookie access, access to browser proxy settings and access to the browser's authentication results may not currently work.)

Note that the new Java Plug-In does not work in Firefox 2. On the Windows platform, when the new Java Plug-In is enabled via the Java Control Panel, launching Firefox 2 will use the classic plug-in and launching Firefox 3 will use the new plug-in. Sun Microsystems and the Mozilla Foundation have been working closely in order to support the new Java Plug-In in Firefox 3. Both organizations have mutually decided not to back-port the required changes, which are significant, to Firefox 2, as it is expected that most Firefox users will upgrade to Firefox 3.

Windows Platform

On the Windows platform, the new plug-in is automatically enabled for running applets in the Internet Explorer and Firefox 3 web browsers during installation of the JRE. No user intervention is necessary.

For the time being, both the classic and new plug-ins are shipped side-by-side. In order to provide a fallback for backward compatibility purposes, a switch has been provided in the Java Control Panel to toggle which plug-in is used for applet execution. To toggle between them, run the Java Control Panel, go to the Advanced tab, Java Plug-in node, and toggle the checkbox labeled 'Enable the next-generation Java Plug-in'.

Unix Platforms (Solaris and Linux)

Place a symlink to .../jre/lib/{i386,sparc}/libnpjp2.so into either your Firefox 3 firefox/plugins directory or your ~/.mozilla/plugins directory. Remove any stray preexisting symlinks to the libjavaplugin_oji.so library.

You may switch back to using the classic Java Plug-In by removing the symlink to libnpjp2.so and reinstalling a symlink to libjavaplugin_oji.so from the same JRE.

Much of the new functionality in the new Java Plug-In is exposed via new parameters to the preexisting <applet>, <object> and <embed> tags.

In general we recommend using the Deployment Toolkit Script, also new in Java SE 6 update 10, to automatically generate the HTML for the applet tag. The Java Rich Internet Applications Deployment Advice guide shows how to easily and portably deploy applets using the Deployment Toolkit.

All of the following parameters may simply be specified in the parameters array passed in to the runApplet method of the Deployment Toolkit's JavaScript library. Alternatively, you may use either the nested PARAM tag, or the analogous syntax for the EMBED tag, to add these parameters by hand to your existing applets. See Deploying With the Applet Tag in The Java Tutorials for more information. For the purpose of illustration, the examples below use only the <applet> and <param> tags.

All of the following parameters are optional; if they are not specified, default values will be used.

The most significant new feature of the next-generation Java Plug-In is built-in support for launching applets from JNLP files. Using the JNLP file format as the applet descriptor allows applets to instantly reuse JNLP extensions previously written for Java Web Start applications, and significantly expands the capabilities of applets in many other ways.

Specifies the JNLP file the new Java Plug-In should use to launch the applet. Full documentation for this parameter is provided in JNLP Support in the New Java Plug-In.

The new plug-in offers better customization of the image which is displayed before the applet is loaded. Animated GIFs are now supported as the target of the image parameter, as described in Customizing the Loading Screen. Additionally, the following new parameters are now supported:

A boolean parameter indicating whether a one-pixel border should be drawn around the edge of the applet's area while displaying the image shown before the applet is loaded. Defaults to true. We recommend setting this value to false, in particular when using an animated GIF as the loading image, to avoid the possibility of flicker.

A boolean parameter indicating whether the loading image should be centered within the area of the applet instead of originating at the upper left corner. Defaults to false.

Example using the boxborder and centerimage parameters:

   <APPLET archive="large_archive.jar"
           code="MyApplet"
           width="300" height="300">
      <!-- Use an animated GIF as an indeterminate progress bar
           while the applet is loading -->
      <PARAM NAME="image" VALUE="animated_gif.gif">
      <!-- Turn off the box border for better blending with the
           surrounding web page -->
       
<PARAM NAME="boxborder" VALUE="false">

      <!-- Center the image in the applet's area -->
       
<PARAM NAME="centerimage" VALUE="true">
   </APPLET>

Note that both the java_arguments and java_version parameters described here are essentially stopgap measures. The recommended way to access this functionality is via the new JNLP support in the new Java Plug-In; see the discussion of command line argument specification in JNLP-launched applets.

Specifies JVM command-line arguments to be used when executing this applet instance.

Examples

• Specifying a larger-than-default maximum heap size:
  Copy

  
  
  <APPLET archive="my_applet.jar" code="MyApplet" width="300" height="300">
  <PARAM name="java_arguments" value="-Xmx128m">
  </APPLET>
  
  

• Specifying a non-default heap size and a Java 2D hardware acceleration option typically used for applets using OpenGL via JogAmp:
  Copy

  
  
  <APPLET archive="my_applet.jar" code="MyApplet" width="300" height="300">
  <PARAM name="java_arguments" value="-Xmx256m -Dsun.java2d.noddraw=true">
  </APPLET>
  
  

• Enabling the assertion facility in the Java programming language:
  Copy

  
  
  <APPLET archive="my_applet.jar" code="MyApplet" width="300" height="300">
  <PARAM name="java_arguments" value="-ea:MyApplet">
  </APPLET>
  
  

Detailed Description

A set of "secure" JVM command-line arguments and system properties is defined in Structure of the JNLP File. All command-line arguments specified via the java_arguments parameter must come from this secure set.

A more thorough discussion of the handling of per-applet JVM command line arguments, including interaction with arguments specified in the Java Control Panel, is in the section on command line arguments for JNLP-launched applets. The java_arguments parameter and command line arguments for JNLP-launched applets are built with the same underlying mechanism, so their handling is similar.

Specifies a JRE version upon which to launch a particular applet.

Examples

• Specifying a particular JRE version for a particular applet:
  Copy

  
  
  <APPLET archive="my_applet.jar" code="MyApplet" width="300" height="300">
  <PARAM name="java_version" value="1.5.0_09">
  </APPLET>
  
  

• Requesting any JRE in a particular family for a particular applet:
  Copy

  
  
  <APPLET archive="my_applet.jar" code="MyApplet" width="300" height="300">
  <PARAM name="java_version" value="1.5*">
  </APPLET>
  
  

Detailed Description

The version selection support in the next-generation Java Plug-In and associated backward compatibility mechanisms are described in a separate document, JRE Version Selection in the Next-Generation Java Plug-In.

A boolean parameter specifying that a particular applet should run in its own JVM instance. This supports certain powerful desktop applets which can not tolerate any interference from other applets running in the same JVM and potentially consuming heap space or other resources.

<APPLET archive="my_applet.jar" code="MyApplet" width="300" height="300">
<PARAM name="java_arguments" value="...">
<PARAM name="separate_jvm" value="true">
</APPLET>

Normally, if two applets have the same codebase and archive parameters, they will be loaded by the same class loader instance. This behavior is required for backward compatibility, and is relied on by several real-world applications. The result is that multiple applets on the same web page may access each others' static variables at the Java language level, effectively allowing the multiple applets to be written as though they comprised a single application.

While this feature enables certain kinds of applications to be conveniently written, it has certain drawbacks. It interferes with termination of applets, in particular when multiple instances of the same applet are active. It makes the programming model for applets more complex, since it is underspecified exactly when the static fields of an applet will be re-initialized, and when they will be maintained from run to run of the same applet. It causes imprecise behavior of certain user interface operations within the Java Plug-In due to the inability to identify exactly which applet initiated a particular request.

For this reason, the new plug-in provides a way to opt out of the use of the class loader cache on an applet by applet basis.

<APPLET archive="my_applet.jar" code="MyApplet" width="300" height="300">
<PARAM name="classloader_cache" value="false">
</APPLET>

The default value of the classloader_cache parameter is true; class loader caching is enabled by default.

The Java Control Panel has been enhanced to support the new features in the Java Plug-In, in particular to manage multiple versions of the JRE to be used for applet execution. The Java Applet Runtime Settings dialog box, which is used to change global applet settings, now offers the same level of control as the Java Application Runtime Settings dialog box used for Java Web Start.

The user can now explicitly add and remove JREs from the list. On the Windows platform, all installed JREs show up in the list automatically. The "Find" button allows quick configuration of additional JREs that may have been simply unzipped on the local disk rather than installed. The "Enabled" checkbox allows control over which JREs the new Java Plug-In will use when considering a given applet's request to run on a particular version of the JRE.

As before, the Java Runtime Parameters field allows specification of command-line arguments to be applied to all applets run in that particular JRE version. However, we now recommend using the new functionality in the Java Plug-In to specify command-line arguments on a per-applet basis rather than globally. There are however some kinds of command-line arguments that are still most efficiently specified via the Java Control Panel, such as -Xdebug, which is typically used during development.

For compatibility reasons, the new and classic Java Plug-Ins are currently shipped side-by-side. If you find that your content does not run properly in the new Java Plug-In, you can switch back to using the classic plug-in.

On the Windows platform only, this setting can be switched in the Java Control Panel. In the Advanced tab, under the Java Plug-In node, there is a checkbox allowing toggling between the old and the new plug-ins. After this setting is changed, it is necessary to restart the web browser for it to take effect.

On the Linux and Solaris platforms, you may replace the symlink to libnpjp2.so with a symlink to the classic plug-in, libjavaplugin_oji.so. This must currently be done by hand.

If you find applet content that executes correctly in the classic Java Plug-In but not in the new Java Plug-In, please report this compatibility issue to Oracle; see the Feedback section.

Ordinarily, unsigned Java applets or applications may only connect back to the web server from which they originated. This restriction prevents an applet from causing denial-of-service attacks by making rapid connections to arbitrary machines on the Internet.

In Java SE 6 update 10, both the Java Web Start and Java Plug-In technologies contain preliminary support for cross-domain policy files, which specify how unsigned code may access web services on the Internet. The crossdomain.xml policy file is hosted on a given server and allows either selected clients, or clients from anywhere, to connect to that server. Cross-domain policy files make accessing web services much easier, particularly from unsigned applets.

General documentation on cross-domain policy files may be found here:

• Cross-domain policy file specification (non-Oracle site)
• Policy file changes (non-Oracle site)

Java Web Start and the Java Plug-In currently implement only a subset of the cross-domain policy file functionality. Specifically, site access restrictions are not supported. Access to a particular server is only granted if the crossdomain.xml file is present and contains only an entry granting access from all domains:

<cross-domain-policy>
        <allow-access-from domain="*" />
    </cross-domain-policy>

By default, if an applet attempts to connect to the host www.server.com, the system will look for a cross-domain policy file at http://www.server.com/crossdomain.xml. Some web services, however, publish their cross-domain policy files at alternate locations.

An applet or application may specify one or more alternate policy file locations using the jnlp.altCrossDomainXMLFiles system property, which takes a comma-separated list of URLs from which policy files may be loaded. For example:

 
    -Djnlp.altCrossDomainXMLFiles=http://photos.googleapis.com/data/crossdomain.xml,http://foo.bar.com/baz/crossdomain.xml

When a connection is attempted to a server named in the altCrossDomainXMLFiles list, the alternate locations of the policy files on that server, if any, will be checked after the default location.

Since Java SE 1.4, applet developers have been able to traverse the Document Object Model (DOM) of the document containing their applet using the Common DOM API. The Common DOM implementation has been rewritten and simplified in the new Java Plug-In, and is now both more robust and easier to use.

Most importantly, the bootstrapping mechanism for acquiring the the Document object has been simplified. There is now one simple entry point which can be called from any thread:

    
    package com.sun.java.browser.plugin2;
    
    public class DOM {
        public static final org.w3c.dom.Document getDocument(Applet applet)
            throws org.w3c.dom.DOMException;
    }

An applet may call this method as follows:

    
    org.w3c.dom.Document document =
        com.sun.java.browser.plugin2.DOM.getDocument(this);

If you choose to reference this API directly, you need to add plugin.jar to your compilation classpath. However, because the new Java Plug-In might not be available at run time, we recommend calling this method reflectively:

    
    org.w3c.dom.Document document = null;
    try {
        Class c = Class.forName("com.sun.java.browser.plugin2.DOM");
        Method m = c.getMethod("getDocument",
                               new Class[] { java.applet.Applet.class });
        document = (org.w3c.dom.Document)
            m.invoke(null, new Object[] { this });
    } catch (Exception e) {
        e.printStackTrace();
    }
    if (document != null) {
        // ... Manipulate the document ...
    }

In the failure case, you might also fall back to the previous bootstrapping APIs, contained in the com.sun.java.browser.plugin.dom package.

Once you have acquired the Document object, you may cast it to HTMLDocument, and generally use any of the APIs in the org.w3c.dom namespace.

The implementation of the Document and other APIs is thread safe; changes to the document by multiple threads will be performed in an unspecified order. Applets still need to take care, and perform appropriate synchronization, if they intend to modify the same portion of the document concurrently.

The following is a simple test applet which descends recursively into the DOM of the document which contains it, and prints each HTML tag and its attributes to the Java Console. Note that it is not specified exactly which attributes are returned when querying a given node for its attributes, so the output is slightly different on different browsers. Most applets that modify the DOM will probably not be affected by these differences, as they will likely look up and manipulate specific attributes of a node rather than query for all of the available attributes.

• DOMDump test case
• DOMDump.java applet source code

For more information, see:

• Common DOM API reference

The bridge between the Java and JavaScript programming languages, known informally as LiveConnect, has been reimplemented. The new implementation is backward-compatible and features improved reliability, performance and cross-browser portability, for both Java calling JavaScript as well as JavaScript calling Java. Formerly Mozilla-specific LiveConnect functionality, such as the ability to call static Java methods, instantiate new Java objects and reference third-party packages from JavaScript, is now available in all browsers.

A new LiveConnect specification both documents the behavior of the Java/JavaScript bridge in the new Java Plug-In, and specifies how alternate implementations of a Java Plug-In should behave to support portability of mixed Java/JavaScript code.

With Java SE 6 Update 10, Oracle introduces a new paradigm for application deployment over the Internet: the ability to drag a live, running applet out of the web browser, dynamically transforming it into an application running on the desktop. The application can be re-launched later from a desktop shortcut or launch menu item using the standard JNLP and Java Web Start technologies. This capability is unique to the Java platform, and represents a complete unification of development and deployment in the web browser and on the desktop.

This functionality is currently considered experimental, and may change or be removed in future releases.

To enable an individual applet to be dragged out of the web browser, add the following parameter to your <applet> tag:

<param name="draggable" value="true">

By default, the gesture to drag the applet out of the web browser is Alt + Left click + Drag. On some platforms (X11 in particular), this particular gesture is usually intercepted by the window manager to move entire windows around the desktop. You can customize exactly what gesture initiates the drag operation by providing a public isAppletDragStart method on your applet class:

public boolean isAppletDragStart(MouseEvent e);

This method will be called for each candidate MouseEvent: those occurring over the applet or any of its sub-components. When your applet first returns true from this method, the Java Plug-In will initiate the drag operation and make the applet track the mouse pointer. It is currently implicitly assumed that a mouse release event involving mouse button 1 ends the drag operation, placing the applet on the desktop.

Note that even after the applet has been dropped on to the desktop, the drag gesture can still be used to move it around the screen. The isAppletDragStart method will continue to be called for these repeated move operations around the screen. You can change the behavior before and after the applet is dropped on to the desktop, if you like, using the notification methods below.

When the drag operation begins, the applet is removed from its original parent container in the web page and placed in a new, undecorated, top-level window. A Frame is used for applets subclassing java.applet.Applet; a JFrame is used for applets subclassing javax.swing.JApplet.

If your applet supplies the method

public void appletDragStarted();

then it will be called when:

• the applet has been removed from its original parent
• it has been placed into the new undecorated top-level Frame or JFrame
• the new Frame or JFrame is not yet visible

This gives you the opportunity to change the state of decorations on the frame, use the experimental functionality in 6u10 to make the frame translucent (useful when building shaped "widgets"), and perform other operations. If your applet supplies the method

public void appletDragFinished();

then it will be called once the applet has been dropped on to the desktop.

By default, a small, floating "close button" will be drawn above and to the right of the applet's region, and tracks the applet as it moves around the screen. You can customize this user interface. If your applet defines the method

public void setAppletCloseListener(ActionListener l);

then it is assumed that your applet wants to draw its own close button inside its region. In this case, you should save the ActionListener object passed in to the above method call when it is made by the Java Plug-In, and call its actionPerformed method to initiate the shutdown of the applet in response to the user's input. The ActionEvent argument to the actionPerformed method may be null; it is ignored.

If the user clicks the close button while the web page that originally contained the applet is still visible, then the applet will be placed back into its original location on the page, and the method

public void appletRestored();

will be called. If the applet has been disconnected from the browser (see below), then normal applet shutdown will be initiated: the stop and destroy methods will be called.

If the user drags an applet out of the web page and then navigates away from that web page, or shuts down the web browser, the applet is conceptually "disconnected" from the web browser. This means that certain services, such as Java/JavaScript communication, are disabled. Other browser services, such as the implementaton of AppletContext.showDocument(), are replaced with alternate implementations that have slightly less fine-grained control. Specifically:

• Any attempt to call from Java to JavaScript via the netscape.javascript.JSObject class will result in a JSException.
• Any calls to AppletContext.showDocument will open a new browser window. If a call is made to showDocument(URL url, String target), the target will be ignored.
• Calls to AppletContext.showStatus will display the string in the Java Console (assuming it is open) rather than in the browser's status bar.
• Queries of proxy settings and cookies, which are normally redirected back to the web browser, are instead handled by the platform-specific settings. For example, on the Windows platform, the proxy settings for Internet Explorer are implicitly the system-wide proxy settings, and will be used for a disconnected applet even if Firefox was originally used to launch the applet.

Aside from these differences, disconnected applets behave exactly like regular applets. There are no changes to the security model: unsigned applets continue to run in the security sandbox. In fact, disconnected applets basically behave exactly like Java Web Start applications.

A significant unification occurs when the new JNLP support in the Java Plug-In is used to describe the applet in conjunction with the draggable applet feature. In this case, the applet really does transform exactly in to a Java Web Started application as it is disconnected from the browser. If the new jnlp_href applet parameter is used, and the shortcut tag in the JNLP file is added in order to request that a desktop shortcut and/or start menu option be added, then these shortcuts will be created (possibly after the user accepts a dialog box, depending on their Java Control Panel settings) as the applet is disconnected from the web browser. The shortcut can then be double-clicked to re-launch the applet. This means that the operation of dragging the applet out of the browser can be used as the installation step for your application.

While re-launching the applet from a desktop shortcut, the appletDragStarted and appletDragFinished methods will still be called under the same conditions as when the applet was dragged out of the browser, so you only need to write any setup code once and it will still work for the shortcut re-launch scenario.

NOTE that the shortcut creation process requires the use of an absolute codebase in the jnlp tag in the applet's JNLP file. This unfortunately does not follow the best practice advice for deployment with the new Java Plug-In, which is to leave the codebase unspecified and allow it to be picked up from the web browser. We hope to improve this behavior in later builds. Additionally, for your desktop shortcut to size the applet correctly, you should specify the desired width and height in the applet-desc tag in your JNLP file, since when relaunching from the shortcut, the browser will not be available to help size the applet. This behavior may also be improved in later builds.

See Developing Draggable Applets in The Java Tutorials for more information.

Demonstrations of the new capabilities of the Java Plug-In are now available in the Deployment trail in The Java Tutorials.

See Java Rich Internet Applications Development and Deployment for more information.

If you find a bug in the next-generation Java Plug-In, please report by visiting Report a Bug or Request a Feature . Please first query the Bug Database under Category Java Plugin, Subcategory plugin2 to see whether the bug has been reported already. When filing a bug, please use the Product/Category Java Plug-in, Subcategory plugin2, and provide the following information:

• Operating system name and version
• Web Browser name and version
• URL of the applet not working, or better, a self-contained test case
• Clear instructions on how to execute the applet and reproduce the failure
• What the failure mode is (i.e., expected and actual behavior)
• The output from the Java Console (enable the Java Console in the Advanced tab of the Java Control Panel)
• Logging output (enable logging in the Advanced tab of the Java Control Panel)
  • On Windows: logs go into e.g. C:/Documents and Settings/[username]/Application Data/Sun/Java/Deployment/log/
  • On Unix: logs go into ~/.java/deployment/log/
  Please find and send the correct log and trace files for the failure.