Run a JNLP
Run a JWS/JNLP application in the browser
This page takes you step by step from a Java Web Start (JNLP) application to the same application running in the browser with CheerpJ. You read the JAR files and the main class from the .jnlp file, then start the application from your own HTML page.
The JNLP Runner browser extension opens Java Web Start applications from the pages users already launch them from, with no changes to the page.
To get started you will need:
- The applicationβs
.jnlpfile. - An HTML page to run the application from.
- An HTTP server that supports Range requests, to test the page locally.
1. The .jnlp file
The .jnlp file describes how to launch a Java Web Start application. Normally a website serves this file, the userβs local Java Web Start client downloads the JAR files it lists, and the application runs on the Java installation on the userβs computer. With CheerpJ the application runs in the browser sandbox instead, with no Java installation.
Your .jnlp file might look like the example below. Find these elements in it:
- The JAR files under
<resources>, listed in<jar>tags. - The application type: an
<application-desc>or an<applet-desc>tag. - The
codebaseURL in the<jnlp>tag, if the JAR URLs are relative.
<?xml version="1.0" encoding="utf-8"?><!-- JNLP Example --><jnlp spec="1.0+" codebase="code-base-url" href="example.jnlp"> <information> <title>Your application name</title> <vendor>Vendor name</vendor> <homepage href="home-page-url"/> <description>Description of your Java application</description> <description kind="short">Another description of your Java application</description> <icon href="image-url"/> <icon kind="icon-name" href="image-url"/> <offline-allowed/> </information> <security> <all-permissions/> </security> <resources> <j2se version="1.4+" initial-heap-size="64m" max-heap-size="640m"/> <jar href="my_application_archive.jar"/> <jar href="lib/my_dependency.jar"/> <property name="key" value="overwritten"/> </resources> <application-desc main-class="com.application.MyClassName"/></jnlp>The other elements need no action, with two exceptions:
<property>elements set Java system properties. Pass them tocheerpjInit()with thejavaPropertiesoption, for examplecheerpjInit({ javaProperties: ["key=overwritten"] }).<nativelib>elements list JARs of pre-built native libraries (.dll,.soor.dylibfiles), which cannot run in the browser. If the application needs them, implement its native methods in JavaScript or compile them to WebAssembly instead.
CheerpJ ignores the <j2se> element: the application runs on the Java version cheerpjInit() chooses, Java 8 by default. JNLP applets run on Java 8 only; a standalone JNLP application can use another version with the version option.
2. Create a project directory
Download each JAR listed in a <jar> tag by opening its URL in the browser. If the URLs are relative, build the full URL by joining the codebase URL and the href of the <jar> tag.
For example:
code-base-url/my_application_archive.jarcode-base-url/lib/my_dependency.jarCreate a directory for the project and place the downloaded JARs inside it, keeping the directory structure of the href paths in the .jnlp file.
For example:
mkdir -p my-project/libWith the JARs in place, the directory looks like this:
βββ my-project βββ my_application_archive.jar βββ lib βββ my_dependency.jar3. Create a basic HTML file
3.1 Identify your application type
A JNLP app is either a standalone application or an applet. The .jnlp file shows which: it has an <application-desc> tag for an application and an <applet-desc> tag for an applet.
Create an index.html file in the root of the project directory. The HTML is different for each type, as the next sections show.
3.2 If your application is a standalone app
Look at the <application-desc> tag and note:
- The application class name: the
main-classattribute. If it is missing, the main class is named in the manifest of the main JAR. - The application arguments: any
<argument>elements inside the tag, in order.
If the .jnlp file gives a main-class, start the application with cheerpjRunMain(), passing the class name and all the JARs separated by ::
<!doctype html><html lang="en"> <head> <meta charset="utf-8" /> <title>CheerpJ test</title> <script src="https://cjrtnc.leaningtech.com/5.0/loader.js"></script> </head> <body> <script type="module"> await cheerpjInit(); cheerpjCreateDisplay(800, 600); await cheerpjRunMain( "com.application.MyClassName", "/app/my_application_archive.jar:/app/lib/my_dependency.jar" ); </script> </body></html>If there is no main-class attribute, use cheerpjRunJar() with the main JAR instead. This finds the main class in the JARβs manifest, as java -jar does, and the dependencies through the manifestβs Class-Path:
await cheerpjRunJar("/app/my_application_archive.jar");Pass the application arguments to cheerpjRunMain() or cheerpjRunJar() after the class path or JAR name, one string per <argument>.
The /app/ prefix is a virtual filesystem mount point for the root of the web server the page is loaded from, so /app/lib/my_dependency.jar is the file lib/my_dependency.jar in the project directory.
3.3 If your application is an applet
Look at the <applet-desc> tag in the .jnlp file and note:
- The applet class name: the
main-classattribute. - The applet size: the
widthandheightattributes. - The applet parameters: any
<param>elements inside<applet-desc>. - The
documentBaseattribute, if present: the URL of an HTML page that embeds the applet. You can start from that page, adding the CheerpJ scripts to it, or write your own HTML like the example below.
Put these into an <applet> tag. List all the JARs in the archive attribute, separated by commas, with paths relative to the page:
<!doctype html><html lang="en"> <head> <meta charset="utf-8" /> <title>CheerpJ applet test</title> <script src="https://cjrtnc.leaningtech.com/5.0/loader.js"></script> </head> <body> <applet archive="my_application_archive.jar,lib/my_dependency.jar" code="com.applet.MyClassName" height="900" width="900" ></applet> <script> cheerpjInit(); </script> </body></html>Pass any applet parameters as <param> elements inside the <applet> tag, as usual:
<applet archive="my_application_archive.jar,lib/my_dependency.jar" code="com.applet.MyClassName" height="900" width="900"> <param name="paramName" value="paramValue" /></applet>If some of your users still have the native Java plug-in installed, rename the tag with a cheerpj- prefix so that only CheerpJ runs the applet: <cheerpj-applet>, <cheerpj-object> and <cheerpj-embed> are all supported.
Java applets and Java 8Applets run on Java 8 only. cheerpjInit() uses Java 8 when no version is given, so do not set the version option on a page with applets.
4. Host your page
The final project directory looks like this:
βββ my-project βββ index.html βββ my_application_archive.jar βββ lib βββ my_dependency.jarGo to the project directory and serve it with an HTTP server, such as http-server:
cd my-projectnpx http-server -p 8080Open http://localhost:8080 in the browser. CheerpJ shows loading messages, then the applicationβs windows or the applet. The first start downloads the parts of the Java runtime the application needs, so it is slower than later starts.
InfoOpening the page directly from disk (a file:// URL) does not work. The server must support HTTP Range requests: npx http-server and npx serve do, Pythonβs http.server does not. See basic server setup, and use HTTPS in production.
If the application does not start, check in the browser developer toolsβ Network tab that every JAR downloads. A 404 means a JAR is missing from the project directory or its path is wrong.
Further reading
To learn more about running standalone applications and applets with CheerpJ, see the dedicated getting started pages, or the JNLP tutorial, which runs a real JNLP application and a JNLP applet: