如何升级Tomcat Java Applet以使用JNLP？

Question

I have a set of Java Applet programs that run on Tomcat. These programs keep track of informal golf "tournament" events, including friendly player competitions.

While the program details aren't important, the code set includes over 30,000 source lines. I chose Java as the implementation language for portability and to avoid maintenance problems. I use Tomcat to deploy the application and javascript to invoke the applets. All my applets use parameters, such as event name, course name, and date of play.

Unfortunately, java and browser changes have now caused maintenance problems for my application. The first problem was that java added a requirement that jar files be signed. The second problem was that first Chrome and now Firefox have removed support for NPAPI plugins, which essentially removed Java Applet support from html.

JNLP ( Java Web Start ) is the new replacement. Both problems were somewhat difficult to fix because there were no clear step-by-step documentation detailing exactly what actually needs to be done.

There may be different, even better, ways to migrate applets to JNLP but the procedures described here work and are complete. However, in describing them I have to assume that you already know how to create a java web application since there's no need to update something you don't already have.

I work with Tomcat in the Windows Cygwin environment. My example mkJavaKey script explicitly uses that environment but all the Java and javascript code is portable. Tomcat uses web.xml to define how Servlets are invoked. If you use a different deployment method, my web.xml file should at least work as a starting point.

Answer 1

Why do you need to sign a jar file?

I can't answer this part of the question. But, for any non-trivial application you will need to go at least through the procedure to self-sign your jar files even though this self-signing provides no real additional security. Anyone can self-sign an application using tools provided in the Java Development Kit. Self-signed certificates are fine for development work, but you will have to click a risk acceptance check box each time you run your application.

OK, my application is non-trivial and I need my jar files signed. What's the procedure?

Here's the quick answer: It's a two step process. You first use the keytool program to create the necessary credentials and then use the jarsigner tool to sign your jar files. You only need to create credentials once in a while but need to sign every deployed jar file.

To create these credentials (a self-signed certificate) use:

$JAVA_HOME/bin/keytool -genkeypair -keyalg RSA -keysize 2048 -alias mydomain -validity 1825

This creates a certificate named .keystore in your home directory that's good for five years. You have to respond to its prompts and I used "password" as the password. Since I only use this certificate for self-signing jar files, security is not a big issue. The validity parameter specifies how long (in days) the certificate is valid.

Each time you update a jar file you will need to sign it. Assuming that you are in your distribution directory and need to sign applet.jar , use:

$JAVA_HOME/bin/jarsigner -tsa http://timestamp.digicert.com -storepass password applet.jar mydomain

The "password" after -storepass matches the password you used with keytool, and the "mydomain" matches the keytool -alias parameter. You will need to specify the -tsa (Time Stamp Authority) parameter and http://timestamp.digicert.com is (or at least was) one publicly available. I don't know exactly what a TSA does or why you need one, but jarsigner isn't happy without it, won't default it, and doesn't directly document how to find one.

You can now either use or ignore the following batch file. I created it because when I needed to create a new certificate (my original certificate expired) I had forgotten how to create it. Hopefully we'll be able to find this batch file the next time we need it, perhaps five years from now.

#!/bin/bash
#
# Title-
#        mkJavaKey
#
# Function-
#        Create a new key using $JAVA_HOME/bin/keytool
#
# Usage-
#        mkJavaKey ## CYGWIN ONLY ##
#        (This is required when jarsigner complains about an expired key.)
#        NOTE: This *REMOVES* and *REPLACES* your existing .keystore file!
#
#######

##########################################################################
# Environment check
if [ -z "$JAVA_HOME" ] ; then
  . setupJAVA ## (This personal script sets JAVA_HOME)
  if [ -z "$JAVA_HOME" ] ; then
    echo "JAVA_HOME environment variable missing"
    exit 1
  fi
fi

if [ -z "$HOMEPATH" ] ; then
  echo "HOMEPATH environment variable missing"
  echo "Try export HOMEPATH=\Users\myname"
  exit 1
fi

home_path=`cygpath --path --unix C:$HOMEPATH`
PGM=$JAVA_HOME/bin/keytool
if [ ! -x "$PGM" ] ; then
  echo "$PGM not executable"
  exit 1
fi

##########################################################################
# Create a new .keystore
set -x
rm -Rf $home_path/.keystore
$PGM -genkeypair -keyalg RSA -keysize 2048 -alias mydomain -validity 1825
exit $?

Notes: My setupJAVA script sets the JAVA_HOME environment variable. For Linux, use $HOME instead of $HOMEPATH and skip the cygpath sections. These convert between Linux and Windows filename formats in the Cygwin environment.

You'll need to sign your jar files every time you install them. To automate this, I modified my Makefile to do this. Here's the make code snippet I used:

.PHONY: golfer.install
golfer.install: test golfer
: (Not relevant to discussion)
cp -p $(OBJDIR)/usr/fne/golfer/Applet/applet.jar $(DEPLOYDIR)/webapps/golfer/.
jarsigner -tsa http://timestamp.digicert.com -storepass password "$(shell cygpath --path --windows "$(DEPLOYDIR)/webapps/golfer/applet.jar")" mydomain
: (Not relevant to discussion)

The $(OBDIR) and $(DEPLOYDIR) variables are not relevant to this discussion. They are directory paths set within my Makefile based build environment.

How do you migrate Applets to the new JNLP environment?

Now that we have self-signed jarfiles, we can start figuring out how to run them. Many browsers no longer support NPAPI so the <applet> tag won't work. Neither will deployJava.runApplet(). I won't get into why NPAPI support was dropped, just what needs to be done to make your existing applications run.

The biggest problem I found migrating my code was that, eventually, I had to create .jnlp files rather than .html files. I'll show you how to do this, describing the code I modified and added.

This is the (now obsolete) javascript code I used to generate html:

//------------------------------------------------------------------------
//
// Title-
//       applet.js
//
// Purpose-
//       Common applet javascript.
//
// Last change date-
//       2010/10/19
//
//------------------------------------------------------------------------
var out;     // Output document

//------------------------------------------------------------------------
// appHead
//
// Generate html header for application.
//------------------------------------------------------------------------
function appHead(title,cname,height,width)
{
   var todoWindow= window.open('','','');
   out= todoWindow.document;
   out.write('<html>');
   out.write('<head><title>' + title + '</title></head>');
   out.write('<body>\n');
   out.write('<applet code="' + cname + '.class"');
   out.write('    codebase="./"')
   out.write('    archive="applet.jar,jars/common.jar"');
   out.write('    width="' + width + '" height="' + height + '">\n');
}

//------------------------------------------------------------------------
// appParm
//
// Add parameter information
//------------------------------------------------------------------------
function appParm(name, value)
{
     out.write('        <param-name="' + name + '" value="' + value + '"/>\n');
}

//------------------------------------------------------------------------
// appTail
//
// Generate html trailer information.
//------------------------------------------------------------------------
function appTail()
{
   out.write('Your browser is completely ignoring the &lt;APPLET&gt; tag!\n');
   out.write('</applet>');
   out.write('<form>');
   out.write('<input type="button" value="Done" onclick="window.close()">');
   out.write('</form>');
   out.write('</body>');
   out.write('</html>');
   out.close();
   out= null;
}

//------------------------------------------------------------------------
// cardEvents
//
// Display scorecard for selected date.
//------------------------------------------------------------------------
function cardEvents(eventsID, obj) 
{
   if( obj.selectedIndex == 0 )
   {
     alert("No date selected");
     return;
   }
   appHead('Score card', 'EventsCard', '100%', '100%');
   appParm('events-nick', eventsID);
   appParm('events-date', obj[obj.selectedIndex].value);
   appTail();
   reset();
}

We don't need to see html generated by my servlet that includes the form button used to invoke the cardEvents function. It's similar to the "DONE" button generation and didn't need to be changed.

It should have been pretty straight-forward to just convert this javascript to generate a jnlp file. This was not possible, or at least I couldn't find any working examples of how to do it and couldn't figure out a way to do it modifying any of the broken examples. The window.open() statement would always add <html> and <body> sections even though I only wanted to generate jnlp xml. I also tried document.open("application/x-java-jnlp-file") . Even though the mime-type was specified, the unwanted html and body sections were still present.

None of the documentation I found showed how to dynamically generate the .jnlp file I needed, which included user-selected applet parameters. Here's the work-around I used instead.

I replaced the html generation in applet.js with this:

//------------------------------------------------------------------------
//
// Title-
//       applet.js
//
// Purpose-
//       Common applet javascript.
//
// Last change date-
//       2017/03/15
//
//------------------------------------------------------------------------
var out;     // Output URL

//------------------------------------------------------------------------
// appHead
//
// Generate application URL header.
//------------------------------------------------------------------------
function appHead(title,cname,height,width)
{
   out= cname + ',' + title;
}

//------------------------------------------------------------------------
// appParm
//
// Generate html parameter information.
//------------------------------------------------------------------------
function appParm(name, value)
{
   out= out + ',' + name + '=' + value;
}

//------------------------------------------------------------------------
// appTail
//
// Generate html trailer information.
//------------------------------------------------------------------------
function appTail()
{
   var specs= 'menubar=yes,toolbar=yes';
   window.open('Applet.jnlp?' + out, '_self', specs);
}

//------------------------------------------------------------------------
// cardEvents
//
// Display scorecard for selected date.
//------------------------------------------------------------------------
function cardEvents(eventsID, obj)
{
    // (UNCHANGED!)
}

This generates a URL in the form of Applet.jnlp,className,description,parm=value,parm=value,... .

I then created a new Servlet named AppletServlet.java. The URL passed to it provides all the information needed to generate the .jnlp file. This code follows the standard sample Servlet structure where doGet is called to handle the request. Here's the code:

//------------------------------------------------------------------------
//
// Method-
//       AppletServlet.doGet
//
// Purpose-
//       Called for each HTTP GET request.
//
//------------------------------------------------------------------------
public void
   doGet(                           // Handle HTTP "GET" request
     HttpServletRequest  req,       // Request information
     HttpServletResponse res)       // Response information
   throws ServletException, IOException
{
   String q= req.getQueryString();
   if( debug ) log("doGet("+q+")");

   res.setContentType("text/html");

   query(req, res);
}

//------------------------------------------------------------------------
//
// Method-
//       AppletServlet.putError
//
// Purpose-
//       Generate error response.
//
//------------------------------------------------------------------------
public void
   putError(                        // Generate error response
     PrintWriter       out,         // The response writer
     String            msg)         // The error message
{       out.println("<HTML>");
   out.println("<HEAD><TITLE>" + msg + "</TITLE></HEAD>");
   out.println("<BODY>");
   out.println("<H1 align=\"center\">" + msg + "</H1>");
   out.println("</BODY>");
   out.println("</HTML>");
}

//------------------------------------------------------------------------
//
// Method-
//       AppletServlet.query
//
// Purpose-
//       Handle a query.
//
//------------------------------------------------------------------------
protected void
   query(                           // Handle a query
     HttpServletRequest  req,       // Request information
     HttpServletResponse res)       // Response information
   throws ServletException, IOException
{
   String q= req.getQueryString();
   if( debug ) log("query("+q+")");

   PrintWriter out = res.getWriter();
   String BOGUS= "<br> Malformed request: query: '" + q + "'";

   //=====================================================================
   // Applet.jnlp?classname,title,parm=value,parm=value,...
   int index= q.indexOf(',');
   if( index < 0 || index == (q.length() - 1) )
   {
     putError(out, BOGUS);
     return;
   }
   String invoke= q.substring(0, index);

   q= q.substring(index+1);
   index= q.indexOf(',');
   if( index < 0 )
     index= q.length();
   String title= q.substring(0, index);
   title= java.net.URLDecoder.decode(title, "UTF-8");

   // Parameter extraction
   Vector<String> param= new Vector<String>();
   if( index < q.length() )
   {
     q= q.substring(index+1);
     for(;;)
     {
       index= q.indexOf(',');
       if( index < 0 )
         index= q.length();

       String s= q.substring(0, index);
       int x= s.indexOf('=');
       if( x < 0 )
       {
         putError(out, BOGUS);
         return;
       }

       param.add(s);
       if( index >= q.length() )
         break;

       q= q.substring(index+1);
     }
   }

   //---------------------------------------------------------------------
   // We now have enough information to generate the response
   //---------------------------------------------------------------------
   res.setContentType("application/x-java-jnlp-file");
   out.println("<?xml version='1.0' encoding='utf-8'?>");
   out.println("<jnlp spec='1.0+' codebase='http://localhost:8080/golfer'>");
   out.println(" <information>");
   out.println("  <title>" + title + "</title>");
   out.println("  <vendor>My Name</vendor>");
   out.println("  <description>" + title + "</description>");
   out.println(" </information>");
   out.println(" <security><all-permissions/></security>");
   out.println(" <resources>");
   out.println("  <j2se version='1.7+'/>");
   out.println("  <jar href='applet.jar'/>");
   out.println("  <jar href='jars/common.jar'/>");
   out.println(" </resources>");
   out.println(" <applet-desc main-class='" + invoke + "' name='" + title + "'" +
                " height='90%' width='98%'>");

   // Insert applet parameters
   for(int i= 0; i<param.size(); i++)
   {
     String s= param.elementAt(i);
     int    x= s.indexOf('=');
     String n= s.substring(0,x);
     String v= s.substring(x+1);
     out.println("  <param name='" + n+ "' value='" + v + "'/>");
   }
   out.println(" </applet-desc>");
   out.println("</jnlp>");
}

Notes: debug is my "debug enabled" flag, and log() writes a debugging message to stdout. In this new code version the height and width are not passed as parameters, but are hard-coded instead. It turned out that in the HTML version "100%" was always used as the height and width and worked well. For some (unknown to me) reason my applet windows are truncated at the bottom and possibly on the right when called using .jnlp code with 100% height and width. I use these new height and width parameters to work around this formatting problem.

In order to invoke my new AppletServlet, I modified my web.xml file:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
   <servlet>
     <servlet-name>Applet</servlet-name>
     <servlet-class>usr.fne.golfer.AppletServlet</servlet-class>
     <init-param>
       <param-name>property-path</param-name>
       <param-value>profile</param-value>
     </init-param>
     <init-param>
       <param-name>property-file</param-name>
       <param-value>golfer.pro</param-value>
     </init-param>
     <load-on-startup>30</load-on-startup>
   </servlet>

   <servlet-mapping>
     <servlet-name>Applet</servlet-name>
     <url-pattern>/Applet.jnlp</url-pattern>
   </servlet-mapping>

   : (Other Servlets unchanged) 
</web-app>

This causes AppletServlet to be invoked for any Applet.jnlp URL. Browsers ignore the query string and treat the result as if the file name is Applet.jnlp.

For smoother operation, you'll need to set your Windows file associations so that .jnlp files invoke Java(TM) Web Start Launcher. In Windows, your JWS Launcher is C:\\Program Files\\java\\jre*\\bin\\javaws.exe (Use your latest jre folder.) Also, if you use Chrome, your download directory will contain the generated Applet.jnlp files. You'll need to clean them out now and then.

This completes the migration process. No applets were harmed (or changed) in this migration, so the bulk of the 30,000 source lines remained unchanged.

While I used cut and paste from operational code to create the examples, it's possible that typos could have snuck in. Please comment if you find anything incorrect, missing, or unclear.