Deploy an SWT application using Java Web Start

http://www-128.ibm.com/developerworks/java/library/os-jws/

Level: Introductory

Jeff Gunther (jeff.gunther@intalgent.com), General Manager, Intalgent Technologies

19 Jun 2003

Over the past few months, the Standard Widget Toolkit (SWT) has continued to pick up momentum and is capturing more and more of the brain-share of Java developers. At some point in the development process of an SWT application -- typically after a basic prototype is operational -- concerns about the deployment process arise. Unlike traditional Java applications, SWT applications require some operating system-specific libraries to be loaded before an application can operate. While the ongoing deployment and maintenance of these libraries might seem like a headache, rest assured there is a solution -- Sun's Java Web Start. The marriage of SWT with Java Web Start provides powerful tools to deploy great-looking client-side Java applications.

Overview of SWT

The introduction of Standard Widget Toolkit (SWT) into the development community couldn't have come at a better time. While Sun's Java Foundation Classes (JFC) has been appeasing developers of client-side applications for several years now, many have avoided using the toolkit for a variety of reasons. For many developers and architects, the dream of being able to develop client-side Java applications that visually appear, operate, and perform like traditional native desktop applications seemed remote.

Then in the middle of 2001, the Eclipse project burst onto the development landscape. Initially the Eclipse project was perceived as only an open source Integrated Development Environment (IDE) for Java; however, the project's scope is much broader. During the development of Eclipse, the SWT toolkit was born. Similar to JFC and its cousin the Abstract Window Toolkit (AWT), the SWT toolkit provides a set of widgets to developers. However, the primary distinction between SWT and other toolkits revolves around SWT's use of an operating system's underlining GUI widgets. This approach provides Java developers a cross-platform API to implement solutions that "feel" like native desktop applications.

Back to top

Overview of Java Web Start

Without the right tools, regardless of the language, deployment and maintenance of traditional desktop applications can be a major headache for developers. Thoughts of having to touch and update every workstation when a new version of the software is released haunt even the most effective support department. To ease the distribution and maintenance requirements of Java developers, Sun Microsystems introduced Java Web Start a few years ago. This technology greatly simplifies the deployment, maintenance, and upgrading of Java applications on end-user's workstations.

Using a Web browser as the initial tool to launch an application, Java Web Start is a locally installed helper application that is included with Sun's Java Runtime Environment. Whenever a user accesses a Java Network Launching Protocol (JNLP) file, the application is automatically downloaded to the user's workstation and starts running. The whole process requires little to no interaction from the end-user and greatly simplifies the effort to distribute an application. Refer to the Resources at the end of the article for more information about Java Web Start.

Back to top

File viewer application

Before we review the implementation details of how to deploy an SWT application using Java Web Start, let's take a look at the application we're going to deploy. The application that's included with this article is an example application provided by the Eclipse project. As shown in Figure 1, the application is a simple cross-platform file viewer that allows users to browse the files and folders on their hard drive.

Figure 1. File viewer running on Windows XP

To demonstrate the cross-platform capabilities of SWT and Java Web Start, the included example stand-alone application has been packaged to run on both Microsoft Windows and Red Hat Linux.

Back to top

Environment requirements

The code used in this document is available for download at the end of this article. In order to fully test out the file viewer application with Java Web Start, your environment must meet the following minimum requirements (see the download links in Resources):

• Microsoft Windows XP or Red Hat Linux 8 operating system
• Java 2 SDK, Standard Edition 1.4 or later installed
• Apache Ant 1.5.3 or later installed
• Jakarta Tomcat 4.1.24 or later installed

Although attention has been given to make the Ant build script cross-platform, the file viewer application has only been tested and verified on Microsoft Windows XP and Red Hat Linux 8 operating systems. Additionally, it's assumed that Tomcat is running on your local workstation and running on port 8080. Let's get started by installing, building, and running the example application.

Back to top

Installing the file viewer application

To install the file viewer application, complete the following steps:

1. Download the source code package via the link in Resources.
2. Unzip the fileviewer.zip file into a temporary directory.

Back to top

Security and code signing

Unlike AWT or JFC, SWT is tightly integrated with the operating system's native windowing environment. SWT uses a system library to manage the integration between its platform-independent API and the underlying operating system. By default, an application running under Java Web Start runs within a restricted sandbox. This environment controls access to resources such as the workstation's file system, system libraries, and other resources. Since SWT needs to operate outside the default sandbox to load a system library, all JAR files deployed with Java Web Start must be digitally signed. Since this application is not going to be deployed to a wide user base, we'll create a self-signed test certificate.

If you're going to put an SWT application into production, it's highly recommended that you obtain a certificate from a certificate authority like Thawte or VeriSign.

Back to top

Creating a self-signed certificate

To create a self-signed test certificate, complete the following steps:

1. Execute the following command within the directory where you unpacked the source code: keytool -genkey -keystore keystore -alias myself.

   You'll be prompted to provide details about the new key including a password, your name, locality, etc. In order to use the provided Ant build process, make sure you set the password to "password". If you don't want to use the hard-coded password of "password", edit the "sign-jars" target within the build.xml file. The actual process of signing each JAR file is completed during the Ant build.

2. To verify that the keystore was properly created, execute the following command within the directory where you unpacked the source code: keytool -list-keystore keystore

   The output will appear something like the following:

   Keystore type: jks Keystore provider: SUN Your keystore contains 1 entry myself, Jun 3, 2003, keyEntry, Certificate fingerprint (MD5):B8:C4:48:ED:68:E8:FE:47:83:78:F5:14:4E:28:5C:80

   
   

Back to top

Building the file viewer application

To build the file viewer application, complete the following steps:

1. To clean the environment, execute the following command within the directory where you unpacked the source code: ant clean
2. Execute the following command to start the build process: ant

If your environment met the requirements and was properly configured, you should have seen something similar to the following:

Buildfile: build.xml init: compile-common: compile-module: [echo] Compiling ... package-common: package-swtlib: sign-jars: [echo] Signing JARS... [signjar] Signing Jar : D:/FileViewer/dist/swt-lib.jar [signjar] Signing Jar : D:/FileViewer/dist/fileviewer.jar [copy] Copying 1 file to D:/FileViewer/dist [signjar] Signing Jar : D:/FileViewer/dist/swt-win32.jar package-web: [war] Building war: D:/FileViewer/dist/fileviewer.war default: BUILD SUCCESSFUL Total time: 6 seconds

Back to top

Running the file viewer application

Before using Java Web Start to deploy the file viewer application, let's try executing the application locally. To start the application, execute the following command within the directory where you unpacked the source code: ant run

Upon execution of the Ant script, the file viewer application should appear. Figure 2 demonstrates the application running under Red Hat Linux 8.

Figure 2. File viewer running on Red Hat Linux 8

Back to top

Deploying and testing the file viewer application

To deploy the application to Tomcat 4, complete the following steps:

1. Copy the fileviewer.war file from the dist directory to the webapps directory under Tomcat 4.
2. Execute the script to start Tomcat 4.
3. Open your Web browser to the following URL and click on the "Launch Application" link: http://localhost:8080/fileviewer/index.html

   Upon clicking the link, you should see the following image (Figure 3) while the application's JAR files will be downloaded to the workstation:

   
   Figure 3. File viewer
   
   
4. The first time the application is downloaded, you'll see the following dialog box, shown in Figure 4.
   Figure 4. Security warning
   
   

   Click "Start" to start the file viewer application.

Back to top

Implementing a JNLP File

Now that we've covered how to build, distribute, and deploy an SWT application using Sun's Java Web Start, let's review how to implement a JNLP file. The Java Network Launching Protocol specification is managed via the Java Community Process (JCP). Since this article's purpose is to cover the specifics of deploying an SWT application using this technology, not much background information is provided. For more information and background about Java Web Start, refer to Steve Kim's article, "Java Web Start", listed in the Resources.

Listing 1 illustrates the various tags used within a JNLP file for an SWT application.

Listing 1. index.jnlp file

1 <?xmlversion="1.0" encoding="utf-8"?> 2 <jnlp spec="1.0+"codebase="http://localhost:8080/fileviewer"href="index.jnlp"> 3 <information> 4 <title>File Viewer</title> 5 <vendor>IBM developerWorks</vendor> 6 <homepage href="index.html"/> 7 <description>File Viewer</description> 8 <description kind="short">FileViewer</description> 9 </information> 10 <security> 11 <all-permissions/> 12 </security> 13 <resources> 14 <j2se version="1.4"/> 15 <jar href="fileviewer.jar"/> 16 <nativelib href="swt-lib.jar"/> 17 </resources> 18 <resources os="Windows"> 19 <jar href="swt-win32.jar"/> 20 </resources> 21 <resources os="Linux"> 22 <jar href="swt-linux.jar"/> 23 </resources> 24 <application-descmain-class="org.eclipse.swt.examples.fileviewer.FileViewer"/> 25 </jnlp>

Let's step through the important parts of this XML file:

1. Because an SWT application is required to load a system library upon execution, it needs to have full access to the user's workstation. Lines 10 through 12 show how an application can request full access to a client's environment. In order for Java Web Start to grant this level of access, all the application's JAR files must be digitally signed.
2. As shown on line 16, we need to declare a nativelib tag to tell Java Web Start that this JAR file contains native libraries. In our example file viewer application, this JAR file contains a Windows DLL and a series of SO files for Linux.
3. Lines 18 through 23 load the appropriate SWT JAR for each operating system. The "resources" tag allows you to protect resources for use only by a particular operating system and architecture. The os attribute specifies the operating system for which the resources element should be considered. This value is based on the end-user's os.name Java system property. While not used in this example, you can also use an arch attribute to further restrict access to a Java library. The arch attribute is based on the end-user's os.arch Java system property.

For more information about the various elements and format of a JNLP file, refer to the Resources below.

Back to top

Summary

The coupling of the SWT user interface toolkit and Java Web Start provides developers with a great set of tools to deploy create highly interactive client-side Java applications. The example file viewer application provides a build and packaging framework that you can use to create your own stand-alone SWT applications to distribute via Java Web Start.

Back to top

Download

Name	Size	Download method
os-jws/fileviewer.zip		FTP

	Information about download methods			Get Adobe® Reader®

Back to top

Resources

• Download the companion source code that was demonstrated throughout this article.
  
  
• Download Java 2 SDK, Standard Edition 1.4.1 from Sun Microsystems.
  
  
• Download Ant 1.5.3 from the Apache Software Foundation.
  
  
• Download Tomcat 4.1.24 from the Jakarta project.
  
  
• For an overview of Java Web Start and information on developing and distributing Java applications for the client side, read Steve Kim's "Java Web Start" (developerworks, September 2001).
  
  
• More information about Java Network Launching Protocol and API specification and the reference implementation is available at Sun's Web site.
  
  
• The Eclipse project provides the SWT toolkit that was used in this article's source code.
  
  
• The Eclipse Technical Overview provides an introduction to the core components of the Eclipse platform.
  
  
• The Eclipse project has released a series SWT examples that provide a good starting point for learning more about creating stand-alone SWT applications.
  

Back to top

About the author

Jeff Gunther, a Studio B author, is the General Manager and founder of Intalgent Technologies, an emerging provider of software products and solutions utilizing the Java 2 Enterprise Edition and Lotus Notes/Domino platforms. Jeff has been a part of the Internet industry since its early, "pre-Mosaic" days. He has professional experience in all aspects of the software life cycle including specific software development expertise with Java/J2EE, DHTML, XML/XSLT, database design, and handheld devices. You can contact him at jeff.gunther@intalgent.com.