JNLP apps
Run a working example of a JNLP application or applet
This tutorial will take you step by step on how to run a working example of a JNLP (also known as JWS app) in the browser using CheerpJ.
If you are interested in a ready-to-use tool for running Java Web Start applications, we recommend taking a look at our CheerpJ JNLP Runner browser extension.
This tutorial is divided in two parts:
Prerequisites
For either application or applet, you will need:
- The application
.jnlp
file (given below) - Node.js (>= 18)
- A simple http-server to host your page locally
- A text editor to create and edit an HTML file
- A modern browser like Chrome, Firefox or Safari.
If you already have a JNLP app and you want to go straight to run it in the browser with CheerpJ, we recommend taking a look at our JNLP quickstart tutorial.
JNLP application: SwingSet3
1. The .jnlp
file
We are going to start by looking at the JNLP file. Below, there is an example of an JNLP file for the known demo application SwingSet3. There are three essential elements highlighted:
- The code base: Found as
<jnlp codebase="">
Indicates where the application files will be downloaded from. - The JAR files: Given by the
<jar>
tag in the<resources>
section. - The class name: Given by
main-class
under the<application-desc>
tag. This tag also indicates that the app is a standalone application.
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE jnlp PUBLIC "-//Sun Microsystems, Inc.//DTD JNLP 1.5//EN"><jnlp codebase="https://raw.githubusercontent.com/leaningtech/cheerpj-meta/main/examples/SwingSet3/" href="SwingSet3.jnlp" spec="6.0+"> <information> <title>SwingSet3</title> <vendor>Oracle America, Inc.</vendor> <homepage href="https://swingset3.dev.java.net"/> <description>Demo to showcase features of the Swing UI toolkit in Java 6</description> <icon href="swingset3/resources/images/splash.png" kind="splash"/> <offline-allowed/> <shortcut online="true"/> </information> <resources> <j2se version="1.6+"/> <jar href="SwingSet3.jar" main="false"/> <jar href="lib/AppFramework.jar"/> <jar href="lib/TimingFramework.jar"/> <jar href="lib/swing-worker.jar"/> <jar href="lib/swingx.jar"/> </resources> <application-desc main-class="com.sun.swingset3.SwingSet3"/></jnlp>
2. Download the application files
Download the application JAR files by manually building their full URL and pasting it in the browser navigation bar. This is done by concatenating the codebase
URL and the jar
URL.
For example:
https://raw.githubusercontent.com/leaningtech/cheerpj-meta/main/examples/SwingSet3/SwingSet3.jar
Do this for all the JARs in the JNLP.
3. Create a project directory
Create a directory where all the files will live. You can choose any name, such as cheerpj-example-swingset3
:
mkdir cheerpj-example-swingset3
Now create the application structure as shown in the JNLP file. For this example there is a subdirectory called lib
.
cd cheerpj-example-swingset3mkdir lib
Now allocate the application JARs inside this directory following the JNLP directory structure. For this app it will be something like this:
└──cheerpj-example-swingset3 ├── SwingSet3.jar └── lib ├── AnimatedTransitions.jar ├── AppFramework.jar ├── Filters.jar ├── MultipleGradientPaint.jar ├── TimingFramework.jar ├── javaws.jar ├── swing-layout-1.0.jar ├── swing-worker.jar └── swingx.jar
4. Create an HTML file
Inside our project directory cheerpj-example-swingset3
we will create a basic HTML file called index.html
like the following:
<!doctype html><html> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width,initial-scale=1" /> <title>SwingSet3 (CheerpJ)</title> <script src="https://cjrtnc.leaningtech.com/3.1/cj3loader.js"></script> <style> html, body { margin: 0; }
#container { width: 100vw; height: 100svh; } </style> </head> <body> <div id="container"></div> <script type="module"> await cheerpjInit(); cheerpjCreateDisplay(-1, -1, document.getElementById("container")); await cheerpjRunJar("/app/SwingSet3.jar"); </script> </body></html>
What is going on?
- The CheerpJ runtime environment is being integrated at:
<script src="https://cjrtnc.leaningtech.com/3.1/cj3loader.js"></script>
cheerpjInit()
initializes the CheerpJ runtime environmentcheerpjCreateDisplay()
creates a graphical environment to contain all Java windows.cheerpjRunJar()
executes the application./app/
is a virtual filesystem mount point that references the root of the web server this page is loaded from.
For this example we are using
cheerpjRunJar()
as the class name is included in the manifest. When this is not the case you can usecheerpjRunMain()
with the main-class name indicated in the JNLP.
5. Host your page locally
To view the example, we need to host the files on a web server. Vite is a convenient tool for this, as it automatically reloads the page when the files change.
npx vite
Alternatively you can also use the http-server utility:
npm install http-serverhttp-server -p 8080
Visit the address indicated by your http-server in the browser. For example, http://localhost:8080
.
The result
You should be able to see the application running in the browser:
Source code and credits
- View full source code fort this example on GitHub
- SwingSet3 is a demo application by Oracle America, Inc.
JNLP applet: Pitch
We will use the Pitch applet from NASA’s Beginner’s Guide to Aeronautics. This applet shows an interactive animation of an aircraft’s pitch motion. See more
.
1. The .jnlp
file
We are going to start by looking at the JNLP file. Below, there is an JNLP example for Pitch applet. There are three essential elements highlighted:
- The code base: Found as
<jnlp codebase="">
Indicates where the application files will be downloaded from. - The JAR files: Given by the
<jar>
tag in the<resources>
section. - The class name: Given by
main-class
under the<applet-desc>
tag. This tag also indicates that the app is an applet.
<?xml version="1.0" encoding="utf-8"?><!-- JNLP File for Pitch applet --><jnlp spec="1.0+" codebase="https://raw.githubusercontent.com/leaningtech/cheerpj-meta/main/examples/Pitch-Applet/"
href="PitchApplet.jnlp"> <information> <title>Pitch</title> <vendor>NASA Glenn Research Center</vendor> <homepage href="https://www.grc.nasa.gov/WWW/K-12/airplane/"/> <description>Pitch motion simulator</description> <description kind="short">Beginner's Guide to Aeronautics - Pitch motion simulator written in Java</description> <offline-allowed/> </information> <security> <all-permissions/> </security> <resources> <j2se version="1.4+" initial-heap-size="30m" max-heap-size="300m" /> <jar href="Pitch.jar"/> </resources> <applet-desc main-class="Pitchview" width="300" height="500"/></jnlp>
2. Download the applet file
Download the applet JAR files by manually building the full URL and pasting it in the browser navigation bar. This is done by concatenating the codebase
URL and the jar
URL.
For example:
https://raw.githubusercontent.com/leaningtech/cheerpj-meta/main/examples/Pitch-Applet/Pitch.jar
3. Create a project directory
Create a directory where all the files will live. You can choose any name, such as cheerpj-example-applet
:
mkdir cheerpj-example-applet
Now allocate the application JAR inside this directory following the JNLP directory structure. For this app it will be something like this:
└──cheerpj-example-applet ├── Pitch.jar
4. Create an HTML file
Inside the project directory, create an HTML file called index.html
like the following:
<!doctype html><html lang="en"> <head> <meta charset="utf-8" /> <title>Pitch applet (CheerpJ)</title> <script src="https://cjrtnc.leaningtech.com/3.1/cj3loader.js"></script> </head> <style> div { max-width: 500px; margin: auto; text-align: center; } h1 { margin-bottom: 50px; } h5 { margin-top: 20px; } </style>
<body> <div> <h1>Applet example with CheerpJ</h1> <div> <cheerpj-applet archive="Pitch.jar" code="Pitchview" height="300" width="500" > Your browser cannot handle the applet tag! </cheerpj-applet> </div> <h5> The applet shown in this example belongs to the NASA's <a href="https://www.grc.nasa.gov/WWW/K-12/airplane/" >Beginner's Guide to Aeronautics</a > and it is available at their <a href="https://github.com/nasa/BGA/tree/main">GitHub repository</a>. </h5> <h5> Applet is running with <a href="https://labs.leaningtech.com/cheerpj3">CheerpJ</a> by <a href="https://leaningtech.com/">©Leaning Technologies</a> </h5> </div> <script type="module"> await cheerpjInit(); </script> </body></html>
What is happening?
- The CheerpJ runtime environment is being integrated at:
<script src="https://cjrtnc.leaningtech.com/3.1/cj3loader.js"></script>
- The
<cheerpj-applet>
tag contains the applet.jar
location, size and class name. This tag prevents conflicts with native java, the classic<applet>
tag can also be used. cheerpjInit()
initializes the CheerpJ runtime environment.
5. Host your page locally
To view the example, we need to host the files on a web server. Vite is a convenient tool for this, as it automatically reloads the page when the files change.
npx vite
Alternatively you can also use the http-server utility:
npm install http-serverhttp-server -p 8080
Visit the address indicated by your http-server in the browser. For example, http://localhost:8080
.
The result
You should be able to see the applet running in the browser:
Source code and credits
-
The applet used for this tutorial belongs to the NASA’s Beginner’s Guide to Aeronautics
and it is available at their GitHub repository
.
Further reading
To continue learning about CheerpJ, visit the reference. If you are interested in a ready-to-use tool for running Java Web Start applications, we recommend taking a look at our CheerpJ JNLP Runner browser extension.