Chapter 4. JNLP Client

Table of Contents

4.1. Overview
4.2. Programming
4.3. Execution
4.3.1. Executing a Client
4.3.2. Executing via Client Container

This chapter describes how to deploy a client and its JNLP file to the web application, and how to execute a client.

4.1. Overview

If an application is large in size and its version is frequently changed, it is recommended to use JNLP. JNLP(Java Network Launching Protocol) is a protocol for the deployment and execution of software components. Using the protocol, a client application (hereafter client) can automatically be downloaded via the web server, and the client can be executed. This is called Java Web Start. Like other clients, a client downloaded by JNLP can access JEUS.

JNLP makes it easier to deploy client programs, and automatically transmits binaries which are required for version upgrade. This enables continued deployment. Furthermore, sample\jnlp in the JDK home directory contains various JNLP samples for the user to practice using the JNLP file following the README file under this directory. For details about JNLP, refer to http://java.sun.com/products/javawebstart/index.jsp.

Note

This manual does not cover details about JNLP. Make sure that you have the necessary knowledge about JNLP before you read this chapter. Since permission problems always arise when deploying jar files using JNLP, a signature is required. The jclient.jar and clientcontainer.jar files do not have a signature, and so, make sure that these files are signed along with other jar files.

4.2. Programming

This section describes how to configure a web application.

Configuring Web Application

To obtain the JNLP file from the web and download the defined JAR files from the web server, the servlet that implemented the JNLP protocol is required. Since JEUS does not provide the servlet, use a sample JNLP servlet provided by JDK 1.6. The jnlp-servlet.jar file, where the servlet is implemented, resides in the following directory of Sun JDK 1.6. (For IBM JDK 1.6, it exists in the lib directory.)

sample/jnlp/servlet

Copy the jnlp-servlet.jar file to WEB-INF/lib directory of the web application, and create the web.xml file as follows. When this is done, the servlet will transmit the JNLP and resource files to the client according to the JNLP protocol.

Note

For details about 'JnlpDownloadServlet' which transmits resource files according to the JNLP protocol, refer to http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/downloadservletguide.html.

The following is an example of the web.xml file for JNLP servlet.

[Example 4.1] JNLP servlet: <<web.xml>>

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
         http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
  <servlet>
       <servlet-name>JnlpDownloadServlet</servlet-name>
       <servlet-class>jnlp.sample.servlet.JnlpDownloadServlet</servlet-class>
       <init-param>
           <param-name>logLevel</param-name>
           <param-value>DEBUG</param-value>
       </init-param>
       <init-param>
           <param-name>logPath</param-name>
           <param-value>jnlpdownloadservlet.log</param-value>
       </init-param>
  </servlet>
  <servlet-mapping>
      <servlet-name>JnlpDownloadServlet</servlet-name>
      <url-pattern>*.jnlp</url-pattern>
  </servlet-mapping>
</web-app>


The following is the source code for the HelloClient class. A JNLP client is not much different from normal clients. Since a JNLP client does not have a console window, like an applet, a GUI window is created by using Swing.

[Example 4.2] <<HelloClient.java>>

package helloejb;

import javax.naming.Context;
import javax.naming.InitialContext;
import java.util.Hashtable;

import java.awt.BorderLayout;
import java.awt.Font;
import java.awt.event.*;

import javax.swing.*;

public class HelloClient extends JFrame {
   public static void main(String[] args)
   {
      new HelloClient();
   }

   public HelloClient() {
        try {
            Hashtable env = new Hashtable();
            env.put(Context.INITIAL_CONTEXT_FACTORY,"jeus.jndi.JNSContextFactory");
            Context context = new InitialContext(env);
            Hello hello = (Hello) context.lookup("helloejb.Hello");

            JLabel label = new JLabel(hello.sayHello());
            label.setFont(new Font("Helevetica", Font.BOLD, 15));
            getContentPane().setLayout(new BorderLayout());
            getContentPane().add(label, BorderLayout.CENTER);
            setSize(500, 250);
            setVisible(true);
        } catch (Exception ex) {
            ex.printStackTrace();
        }
   }
}


Java Web Start requires a JNLP file containing information for executing HelloClient.

The following example specifies the JAR file to execute HelloClient, the Java version in use, etc. The '$$codebase' setting of the codebase attribute in the <jnlp> tag is automatically replaced according to the context used for deploying the web application including the JNLP servlets. In the example, since there is no path specified for the href attribute for the JAR file, JNLP file and JAR file should be placed in the same directory.

[Example 4.3] <<HelloClient.jnlp>>

<?xml version="1.0" encoding="utf-8"?>
<jnlp spec="1.0" codebase="$$codebase">
   <information>
      <title>HelloClient</title>
      <vendor>TmaxSoft</vendor>
   </information>
   <resources>
      <j2se version="1.5+" href="http://java.sun.com/products/autodl/j2se"/>
      <jar href="hello-client.jar"/>
      <jar href="jclient.jar"/>
   </resources>
   <application-desc main-class="helloejb.HelloClient"/>
</jnlp>


Note

Reserved words like '$$codebase' is provided by Oracle's JNLP servlet implementation. It's not defined in the JNLP standard.

4.3. Execution

This section explains how to execute a client.

4.3.1. Executing a Client

When accessing the JNLP file from the web browser after deploying a web application, the Java Web Start will start and the client will be executed.

Following is an example of URL requesting a JNLP file when the web application context is 'hello. Since the URL path of HelloClient.jnlp, and that of hello-client.jar and jclient.jar defined in HelloClient.jnlp is specified to 'app,' they reside in the hello directory, or the app directory within the WAR file.

http://localhost:8088/hello/app/HelloClient.jnlp

As the result of requesting the JNLP file from the web browser, the specified client is executed. A separate Java window appears showing that the client has been executed.

4.3.2. Executing via Client Container

A JNLP client can use the dependency injection via a client container. To do so, a method different from the previous one is needed.

The following example is the code that uses injection in HelloClient.java.

[Example 4.4] <<HelloClient.java>>

package helloejb;

import java.awt.BorderLayout;
import java.awt.Font;
import java.awt.event.*;

import javax.swing.*;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.ejb.EJB;

public class HelloClient extends JFrame {
   @EJB
   private static Hello hello;

   public static void main(String[] args) {
      new HelloClient();
   }

   public HelloClient() {
        try {
            JLabel label = new JLabel(hello.sayHello());
            label.setFont(new Font("Helevetica", Font.BOLD, 15));
            getContentPane().setLayout(new BorderLayout());
            getContentPane().add(label, BorderLayout.CENTER);
            setSize(500, 250);
            setVisible(true);
        } catch (Exception ex) {
            ex.printStackTrace();
        }
   }
}

A JNLP file should also be written following the aforementioned method. First, implement the JEUS client container class instead of the client's main class, and specify a parameter that will be passed to the class. For information about parameters, refer to "1.6.1. Executing in Console".

Set the <resources> tag as clientcontainer.jar instead of jclient.jar, and set the jeus.client.container. jws property to 'true,' which shows that the JEUS client container is in the Java Web Start mode.

Furthermore, since there is a permission check for Java Web Start program, <all-permission> or <j2ee-application-client-permissions> settings in the <security> tag must be specified and the JAR file must be signed.

[Example 4.5] <<HelloClient.jnlp>>

<?xml version="1.0" encoding="utf-8"?>
<jnlp spec="1.0" codebase="$$codebase">S
   <information>
      <title>HelloClient</title>
      <vendor>TmaxSoft</vendor>
   </information>
   <security>
      <all-permissions/>
   </security>
   <resources>
      <j2se version="1.5+" href="http://java.sun.com/products/autodl/j2se"/>
      <jar href="clientcontainer.jar"/>
      <jar href="hello-client.jar"/>
      <property name="jeus.client.container.jws" value="true"/>
   </resources>
   <application-desc main-class="jeus.client.container.ClientContainer">
        <argument>-main</argument>
        <argument>helloejb.HelloClient</argument>
   </application-desc>
</jnlp>

As in the previous case, loading the JNLP file using the web browser or Java Web Start produces the same results.

Signing the JAR File

If there is a <security> tag in the JNLP file, you should sign the hello-client.jar file of the previous example, because Java Web Start requires the signed JAR file.

The following example shows how to sign the hello-client.jar file by using keytool and jarsigner that are provided by JDK.

keytool -genkey -alias helloclient -keypass 1234 -keystore helloks -storepass 1234
jarsigner -keystore helloks hello-client.jar helloclient