Documentation Contents

< Contents

# Migrating Java Applets to Java Web Start and JNLP

Because browsers are reducing or eliminating support for the Java Plug-in, consider migrating existing Java applets to Java Web Start, which uses the Java Network Launching Protocol (JNLP) to download and run an application locally.

Although available and supported in JDK 8, the Applet API and the Java Plug-in are marked as deprecated in preparation for removal in a future release. Alternatives for applets and embedded JavaFX applications include Java Web Start and self-contained applications.

Migrating to Java Web Start provides the ability to launch the application independent of a web browser. When your user is offline or unable to access the browser, a desktop shortcut can launch the application, providing your user with the same experience as that of a native application.

This chapter includes the following topics:

- Migrating an Existing Java Applet

- Rewriting a Java Applet as a Java Web Start Application

- Special Considerations

## Migrating an Existing Java Applet

Java Web Start technology has built-in support for applets. Your applet can run with Java Web Start technology without any recompilation of the applet. Just convert your applet HTML tags to a Java Network Launching Protocol (JNLP) file using the JNLP `applet-desc` element, for example:

    <resources>
      <jar href="SwingSet2.jar"/>
    </resources>
    <applet-desc main-class="SwingSet2Applet" name="SwingSet" width="625" height="595">
      <param name="param1" value="value1"/>
      <param name="param2" value="value2"/>
    </applet-desc>

Note: Although available and supported in JDK 8, the Applet API is marked as deprecated in preparation for removal in a future release. Instead of applets, consider alternatives such as Java Web Start or self-contained applications.

## Rewriting a Java Applet as a Java Web Start Application

The best way to migrate your applet is to rewrite it as a standalone Java application, and then deploy it with Java Web Start technology. Rewriting your applet and testing the resulting application ensures that your converted applet works as expected, and your application can take advantage of the Java Web Start features.

The major work needed is to convert your `applet` class to the `main` class of the application. The applet `init` and `start` methods are no longer present, instead, initialize the application at the beginning of the application's `main` method.

To quickly begin the migration, add the `main` method to your original `applet` class, and then start calling your applet initialization code where it normally gets called from the applet's `init` and `start` methods. When there is a `main` method in the `applet` class, you can begin launching it by using the Java Web Start technology, and then slowly remove the dependency on the `Applet` class and convert it completely to your application's `main` class.

## Special Considerations

The following items are things to consider when migrating:

- A Java Web Start application does not run within the web browser. If your applet has any dependency on the browser (for example, Java-to-JavaScript or JavaScript-to-Java communications using the browser), the communication code will no longer work. The APIs that are affected include:

  - `JSObject` API (`netscape.javascript.JSObject.*`) for Java-to-JavaScript communication does not work for Java Web Start applications.

  - Common Document Object Model (DOM) APIs (`com.sun.java.browser.dom.*` and `org.w3c.dom.*`) available for Java Plug-in applets are not available to Java Web Start applications.

- Similar to Java Plug-in technology, for faster start-up performance, Java Web Start technology caches your application JARs and resources downloaded by your application.

- Java Web Start technology provides permanent cookie support on Windows using the cookie store in Internet Explorer (IE), and the cookie-handling behavior is determined by the cookie control in IE. On Linux and Solaris, Java Web Start technology provides permanent cookie support using its own cookie store implementation. See Cookies in the Java Tutorials.

- If you deploy an applet with the JNLP `applet-desc` element, your applet is created using the `AppletContainer` provided by Java Web Start technology. When your applet calls `Applet.getAppletContext()`, it returns the `AppletContainerContext` provided by Java Web Start technology. The following list describes minor differences in implementation between the Java Plug-in `AppletContext` and the Java Web Start `AppletContext`:

  - The following Applet Persistence API methods are not implemented by Java Web Start technology:

        AppletContext.getStream(String key)
        AppletContext.getStreamKeys()
        AppletContext.setStream(String key, InputStream s)

    For Java Web Start applications, you can use the JNLP Persistence Service API for storing data locally on the client's system. See the `PersistenceService` interface.

  - For `AppletContext.showDocument(URL url, String target)`, the target argument is ignored by Java Web Start technology.

  - For `AppletContext.showStatus(String status)`, when launched with Java Web Start technology, this sets the `JLabel` text that is below the applet, hosted by the Java Web Start `AppletContainer`.

- Similar to `AppletContext.showDocument`, Java Web Start applications are capable of showing an HTML page using the system's default web browser by using the `BasicService.showDocument` API.

  For a Java Plug-in applet:

  AppletContext.showDocument(URL url) AppletContext.showDocument(URL url, String target)

  For a Java Web Start application:

  BasicService.showDocument(URL url)

  See the `BasicService` interface.

- In an applet, if you obtain a resource using the following calls:

      Applet.getImage(URL url)
      Applet.getImage(URL url, String name)
      Applet.getAudioClip(URL url)
      Applet.getAudioClip(URL url, String name)
      AppletContext.getAudioClip(URL url)
      AppletContext.getImage(URL url)

  Then in Java Web Start technology, the best practice is to include the resources in your application JAR files, and access the resources using the `JNLPClassLoader`:

      ClassLoader cl = this.getClass().getClassLoader();
      URL url = cl.getResource(url);
      Image im = Toolkit.getDefaultToolkit().createImage(url);

  See Retrieving Resources from JAR Files.

- The pack200 JAR packing tool is supported by both the Java Web Start and the Java Plug-in technologies. If you are already deploying your applet JARs with pack200, no change is needed when migrating to Java Web Start technology.

- By using the `OBJECT` tag in Java Plug-in technology, you can detect whether Java is available on the client's machine with the plug-in `CLSID` and then auto-download Java if necessary. The same support is available with Java Web Start technology by using the Java Web Start `CLSID`. See Ensuring the Presence of the JRE Software in the Java Tutorials.

- If you want to deploy extensions for your Java Web Start application, then use the JNLP extension protocol mechanism. See the JSR 56: Java Network Launching Protocol and API, section 3.8 "Extension Descriptor."

  One advantage of the JNLP extensions mechanism over Java Plug-in technology is that the installed extensions are available to all Java Web Start applications running on the system, no matter what version of the JRE the application is running. For Java Plug-in technology, only applets running in the same JRE version can use the installed extensions.

- For signed JAR files, similar to Java Plug-in technology, you can sign your application JAR files and request your application to be run with all permissions using the JNLP file. In Java Plug-in technology, your applet JARs can be signed by different certificates. In Java Web Start technology, the same certificate must be used to sign all JAR files (`jar` and `nativelib` elements) that are part of a single JNLP file. This simplifies user management because only one certificate must be presented to the user during a launch per JNLP file. If you must use JARs signed with different certificates, then you can put them in a component extension JNLP file, and reference the extension file from the main JNLP file. See the JSR 56: Java Network Launching Protocol and API, section 5.4 "Signed Applications" and section 4.7 "Extension Resources."

Copyright © 1993, 2026, Oracle and/or its affiliates. All rights reserved.
Contact Us