Getting Started with the J2EE Client Provisioning Reference Implementation

Print-friendly Version

by Qusay H. Mahmoud
September 2003

J2EE Client Provisioning is a specification (JSR 124 in the Java Community Process) that aims to provide a framework and APIs for using J2EE to download applications and other content to a variety of clients. Provisioning includes hosting application client code and associated resources on a server, discovery and selection of suitable applications by the client, and transfer and delivery of the selected applications to the client platform.

In this world of smart cell phones and PDAs that can download exciting new content, a key component of the infrastructure is the provisioning server that manages application client code and associated resources and content. Each time a carrier deploys a provisioning server, a significant amount of work must be done to integrate it with location servers, personalization engines, and billing systems. The magnitude of this effort provides a strong motivation to standardize provisioning servers so they can be integrated in a portable way.

The JSR 124 specification defines a standard file format for packaging applications to be provisioned, called a provisioning archive. A PAR file is actually a ZIP file that contains one or more client application bundles to be provisioned. A bundle repository is a centrally managed database where content providers can add and delete PAR files.

The JSR 124 Reference Implementation provides an implementation of the J2EE Client Provisioning specification in the form of an extension to the J2EE application server, and a sample application called RI-Test (also called the 124 RI Sample Application), a provisioning application written to run on any compliant implementation of the standard.

In this article you'll find a detailed description of the J2EE Client Provisioning Reference Implementation, and step-by-step instructions to install and use the 124 RI Sample Application. Once you have read this article you will be able to go ahead and use the RI to write your own provisioning applications, using RI-Test as a model.

The article assumes you already have a basic understanding of the J2EE Client Provisioning specification. If you don't, please read An Overview of JSR 124: J2EE Client Provisioning first.

Setting Up to Use the Reference Implementation

The J2EE Client Provisioning Reference Implementation and the RI-Test sample application should work properly on any compliant J2EE application server. The provisioning server should be installed on a server-side machine. Here I describe the technologies the RI uses, and what you need to get up and running.

The development you'll do in this article relies on the following technologies:

• J2SE
• J2EE
• Apache Ant

You should make sure you have downloaded and installed all three. As an example configuration, on my Windows 2000 machine I have installed J2SE 1.4.1, J2EE 1.3.1, and Ant 1.5.3-1 in these directories:

• c:\j2sdk1.4.1
• c:\j2sdkee1.3.1
• c:\apache-ant-1.5.3-1

I also have the following systems installed for testing provisioning servers.

• Java Web Start
• The J2ME Wireless Toolkit

Once you have installed everything else, you can download and install the J2EE Client Provisioning Reference Implementation. On my machine, I have installed it at the default location: c:\j2ee_cp_ri_1_0.

Configuring and Setting Up Your Environment

Follow the next two steps to configure and set up your environment.

1. Set the environment variables, changing the following commands as needed to reflect differences between your setup and my Windows 2000 machine:

   set JAVA_HOME=c:\j2sdk1.4.1
   set J2EE_HOME=c:\j2sdkee1.3.1
   set APACHE_ANT=c:\apache-ant-1.5.3-1
   

   Windows users can invoke the echo command to confirm the settings. For example: echo %JAVA_HOME% prints the value of the environment variable JAVA_HOME.

2. Grant servlet permissions:

   To allow access to the bundles in the repository, you must set the security permissions in the server.policy file. The repository directory is by default called MyRepository, and will be created under your home directory. If you do not know your home directory, don't worry, simply refer to it using the environment variable user.home. The following snippet of code grants the system servlets read, write, and delete access to the local file system. Add this code to the server's security policy file, %J2EE_HOME%\lib\security\server.policy. Don't forget the semicolon after the closing curly brace.

   grant { permission java.io.FilePermission "${user.home}${/}MyRepository${/}-", "read,write,delete"; permission java.io.FilePermission "${user.home}${/}MyRepository", "read,write,delete"; };

   
   

   		Note: On a Windows box you can use the following utility to print the path to your home directory: public class GetHomeDir { public static void main(String argv[]) { System.out.println(System.getProperty("user.home")); } } On a Unix system you can find your home directory easily, by invoking two commands in succession: cd and pwd.

Build and Deploy the 124 RI Sample Application

To build and deploy RI-Text you must first start J2EE's Cloudscape database and the J2EE application server. Change to the bin directory of your J2EE installation and type the following commands:

cloudscape -start

j2ee -verbose

In verbose mode all logging output goes to the current shell.

Now you can build and deploy the sample application as follows:

1. Change to the test subdirectory of your J2EE Client Provisioning installation (on my machine, C:\j2ee_cp_ri_1_0\test).
2. Run the Ant script with the deploy target to build and deploy the sample application: ant deploy
   

The whole build took 26 seconds on my Windows 2000 machine. You may want to monitor the J2EE app server's console window to see what's going on. Note that you can ignore any messages like No local string for ..., which are generated by J2EE 1.3.1.

Once the deployment is done, you can test it using the following URL:

http://localhost:8000/ri-test/index.html

		Note: You do not need to start the Apache Tomcat servlet container. The J2EE app server you started earlier acts as an HTTP server running on port 8000.

If all goes well, you'll see a display something like Figure 1.

Figure 1: The 124 RI Sample Application in Action (Click image to enlarge.)

The Ant script c:\j2ee_cp_ri_1_0\test\build.xml has several other useful targets; to see how to use them, simply change to the directory where build.xml is located and enter ant. Here is the output of a sample run:

Usage: [echo] [echo] [echo] COMPILING AND PACKAGING [echo] [echo] ant all Compile and package everything [echo] ant all-jcov Compile and package everything with jcov [echo] ant web.compile Compile web tests [echo] ant web.ear Build the web test .ear file [echo] ant apps Build client app PAR file(s) [echo] [echo] VALIDATING [echo] [echo] ant validate Validate the configuration files - [echo] adapter.xml, devices.xml, matchers.xml - [echo] for correctness [echo] [echo] DEPLOYING - J2EE and Cloudscape must be running [echo] [echo] ant deploy Deploy provisioning app to localhost [echo] ant undeploy Undeploy provisioning app [echo] [echo] VIEWING/EMPTYING THE REPOSITORY - Cloudscape must be running [echo] [echo] ant show-repository Shows PAR files in repository [echo] ant empty-repository Empties the repository [echo] [echo] UNIT TESTING [echo] [echo] ant unit.compile Compile unit tests [echo] ant unit Run unit tests [echo] [echo] CLEANING UP [echo] [echo] ant clean Remove all built files [echo]

As you can see, there are targets for cleaning up (removing all built files). The easiest way to clean up is to remove the PAR files from your bundle repository, using the web-based Bundle Repository Administration tool.

To do a more thorough cleanup and start fresh, make sure that Cloudscape and the J2EE server are running, then:

1. Change to the c:\j2ee_cp_ri_1_0\test directory and run ant empty-repository to remove all PAR references from the database.
2. Run ant undeploy to undeploy the sample application.
3. Change to your home directory and delete MyRepository.

The 124 RI Sample Application Application

RI-Test is a proof-of-concept J2EE client provisioning server, which contains items that illustrate the client provisioning process; these items appear in Figure 1.

• The Device Type Table lists the types of devices the provisioning server can recognize. Figure 2 shows one entry in this table. The first column contains the device identifier, a string that identifies a class of devices (by manufacturer and model, for example). The second column indicates the adapters that can be used to deliver content to the identified device type. The third column contains the capabilities; that is, the properties of the device type. Each capability is made up of a name and a value. The capabilities are matched against bundle requirements on the back end to fulfill service requests made from the device.
  

  Figure 2: A Sample Entry in the Device Type Table (Click image to enlarge.)

• devices.xml is an XML-based configuration file. The device type table is extracted from it. Figure 3 shows the markup for the sample entry.
  

  Figure 3: The XML Markup for the Device in Figure 2

• The Bundle Repository Administration page is a form-based administration tool that enables you to add, view, and remove PAR files in the bundle repository.

  The bundle repository, created when the application is deployed, contains bundles that are available for clients to download. Here it's implemented using the Cloudscape database and a directory (MyRepository, created in your home directory). When you enter the Bundle Repository Administration page, you will see a form that lets you browse to a PAR file and upload it. Browse to c:\j2ee_cp_ri_1_0\test\apps\test.par, select that file, then click on Upload PAR file, seen in Figure 4.

  Figure 4: Contents of the Bundle Repository

• List All Bundles in the Repository allows you to view the current contents of the repository. Click on that link, and you'll see all the bundles in that PAR file you just uploaded. Figure 5 shows a snapshot.
  

  Figure 5: Bundles: a Detailed View of Repository Contents (Click image to enlarge.)

  You can click on any bundle to view its details. An example is shown in Figure 6.

  Figure 6: A Detailed View of a Bundle (Click image to enlarge.)

  The DOWNLOAD button triggers a provisioning request. If the bundle is a Java application and your browser is configured with the appropriate helper application, such as Java Web Start, pushing the button starts that helper application and deploys the bundle to it. I'll show examples later.

• The Discovery Test Page allows you to search the bundle repository. Figure 7 shows a sample query.
  

  Figure 7: The Discovery Test Page

  In this example I've requested bundles that match the following criteria:

  Device type: MIDP-1.0 Bundle Type: Application Category: Game Billing Plan: Freeware Locale: US English App Name: MIDP-MAN Vendor Name: unspecified Keyword match: unspecified

  
  

  If a bundle is found, it will be displayed as in Figure 8.

  Figure 8: A Sample Search Result

  If you click on the link, you'll see the details of the bundle in an information page like the one you saw in Figure 6.

• The link to browse available applications displays Java Web Start bundles. If you have Java Web Start installed, you can browse to and run JNLP (Java Network Launching Protocol) bundles displayed as in Figure 9.
  

  Figure 9: Bundles for Java Web Start

  If you click on one of the links, Java Web Start will be launched, and the application will download and run. For example, clicking on Sun Draw results in the display in Figure 10.

  Figure 10: A JNLP Bundle Running in Java Web Start

• The link to download MIDlet suites displays MIDP bundles as in Figure 11. The hyperlinks point to JAD files that can be downloaded to MIDP-enabled devices.
  

  Figure 11: MIDP bundles (Click image to enlarge.)

  If you have the J2ME Wireless Toolkit installed, go to its bin subdirectory and run:

  emulator -Xjam

  You'll see the Java Application Manager (JAM) GUI interface, as in Figure 12.

  Figure 12: The J2ME Wireless Toolkit's JAM GUI Interface

  Now, select Install Application and enter the URL http://localhost:8000/ri-test/jam, as shown in Figure 13.

  Figure 13: Entering a URL to Install from

  Select Menu, then Go. The bundles will be listed as in Figure 14.

  Figure 14: A List of Bundles to Select from

  Now you can select any of the displayed MIDlets to download and install it.

Conclusion:

The J2EE Client Provisioning specification provides a J2EE-based framework and APIs for making applications easily available to a variety of networked clients. This article provided step-by-step instructions for building, deploying, and using the J2EE Client Provisioning Reference Implementation, which is a proof-of-concept implementation of JSR 124. The examples shown demonstrate that the reference implementation is functional, and that the concepts presented in JSR 124 are quite useful and can be easily implemented.

The examples in this article show the power of the J2EE Client Provisioning APIs by deploying and running the RI-Test sample application, which demonstrates the kind of customization you can do with a provisioning server that complies with JSR 124.

For more information

• JSR 124 J2EE Client Provisioning
• Download the J2EE Client Provisioning Reference Implementation
• Java Web Start
• Download Java Web Start
• Deploying Wireless Java Applications
• Introduction to OTA Application Provisioning
• Over The Air User Initiated Provisioning Recommended Practice for the Mobile Information Device Profile

Acknowledgments

Special thanks to James Allen and Danny Coward of Sun Microsystems, whose feedback helped me improve this article.