Provisioning Multiple Client Devices

Print-friendly Version

Learn how to "package once, stock anywhere," using JSR 124

Client network devices come in many shapes and sizes, and their functionality varies widely. Some are more capable than others; simple browser-based clients can work only with web pages, while others implement the Java virtual machine and can run interactive applications with a rich client side.

Provisioning -- managing, upgrading, and tracking the content that the many different kinds of clients can use, supporting the user's discovery and selection of suitable applications, and delivering the selected applications to the client platform -- is a challenging task. Applications, services, and content are usually controlled by a provisioning server. When a wireless carrier or other provider 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 J2EE Client Provisioning Specification, developed within the Java Community Process (JCP) as JSR 124, aims to provide a framework and APIs for using the Java 2 Platform, Enterprise Edition (J2EE) to provision a variety of clients with applications, services, and other content. A reference implementation (RI) of this technology is available from Sun Microsystems.

This article provides a quick overview of the J2EE Client Provisioning Specification, tells you why this technology is needed and how it works. Then the article gives you a taste of the effort involved in using JSR 124 to develop provisioning applications: server-based applications that provision network devices. To get the most value from this article, you should begin by downloading the J2EE Client Provisioning reference implementation.

The J2EE Client Provisioning Specification is an extension of the J2EE platform to provide application servers with facilities for building provisioning applications. The architecture of this technology enables centralized automated distribution of content and applications through a web site. Developers submit their applications, services, and content in the form of client bundles that client devices will discover, and application servers will deliver. A provisioning server is much like a vending machine: Providers stock a machine with attractive products, consumers browse available content, select items they find appealing, and pay for them, and the machine delivers the selected products.

JSR 124 was created by an expert group of wireless operators, device manufacturers, provisioning server vendors, and information technology vendors. It defines standard ways to handle the submission, discovery, and delivery phases of provisioning.

One can distribute applications, services, and content to be accessed through a browser simply by publishing their URLs. The challenge, however, lies in maintaining and upgrading these applications, services, and content. The J2EE Client Provisioning Specification defines a central repository of client applications, services, and content called a provisioning portal, which is responsible for managing the distribution of rich clients and their content. This centralized solution allows developers to update and enhance their applications and services easily. Users interact with this portal to discover applications, and the portal delivers selected content to the devices.

JSR 124 technology aims to provide seamless access to a wide array of applications, services, and content of many kinds, from ringtones to images to informative text. It allows developers to package their applications once and deploy them anywhere. It takes full advantage of J2EE technology, which is a prominent standard for enterprise applications.

Three groups of people are involved in the provisioning process:

• Provisioning Server Operators define the submission, discovery, and delivery processes.
• Developers package their applications, services, or content into a special file format known as a Provisioning ARchive (PAR) and submit it to the operators.
• Consumers search for applications, services, and content, then select what they need.

The J2EE Client Provisioning Specification includes an extensible service provider interface (SPI) that enables operators to extend the provisioning server to provision new types of client devices. Server-side developers achieve each such extension by defining an adapter, a software component that implements a particular provisioning model. The provisioning model defines how client devices interact with the provisioning server during delivery. Provisioning models include J2ME MIDP over-the-air (OTA) and the Java Network Launching Protocol (JNLP). Such models define a network protocol for delivering client bundles to client devices. Note that a provisioning server may host one or more provisioning adapters.

Supporting delivery to a new client device is a simple matter of extending the provisioning server, by configuring a suitable provisioning adapter for the new device. An adapter may be produced by the same company that develops the provisioning framework or by a third party.

Figure 1 shows a high-level view of the J2EE Client Provisioning architecture.

Figure 1: The J2EE Client Provisioning Architecture

The J2EE platform offers a reliable and flexible technology to integrate enterprise services including billing, location, presence, and user profiling into provisioning applications that use the J2EE Client Provisioning Specification, but you should note that JSR 124 doesn't define APIs to such services.

The J2EE Client Provisioning Specification provides APIs that are exposed in the J2EE web container. These APIs enable J2EE developers to write provisioning portals. A low-end implementation of the specification could well be just a servlet that acts as the underlying platform. High-end implementations may provide a full J2EE platform as the underlying container. The reference implementation of JSR 124 available from Sun Microsystems is based on the J2EE application server RI, also available from Sun.

The J2EE Client Provisioning Reference Implementation
The JSR 124 reference implementation conforms to the final draft of the specification. In addition to implementing the provisioning framework, it provides three adapters:

• J2ME MIDP 2.0 OTA
• JNLP
• Generic content

With the RI you also get a sample application, RI-Test, which demonstrates the JSR 124 specification and the RI. The test application includes a provisioning server into which you can upload client bundles and their associated metadata using a web browser interface. RI-Test also lets you search the bundle repository and download content files.

To experiment with the RI, you need:

• The J2SE SDK 1.4.1 or higher
• An application server implementing J2EE 1.3.1 or higher
• Apache Ant 1.5.1 or higher

Note well: The JSR 124 RI was tested using Sun's J2EE reference implementation, which includes the Cloudscape database. You need to be aware that the configuration files are specific to the J2EE RI; if you wish to use a different application server in your experiments with the JSR 124 RI you'll need to configure it accordingly.

An earlier article, "Getting Started with the J2EE Client Provisioning Reference Implementation," shows how to set up the J2EE Client Provisioning RI so you can use it in either of two ways: with the J2ME Wireless Toolkit to demonstrate use of MIDP 2.0 OTA, or with Java Web Start to demonstrate the use of the JNLP protocol. That article also shows you how to set up and run RI-Test, which is the easiest way to get an idea of how provisioning applications work behind the scenes.

Basically, a provisioning application contains one or more servlets that you write, or adapt, to allow client users to discover client bundles they may select for download. These servlets will then use the provisioning framework and APIs to deliver the bundles to the users' devices.

The development process can be summarized in three steps:

1. Package your application in a Provisioning ARchive (PAR file).
2. Write one or more servlets.
3. Customize the configuration files.

Let's walk through each of these in turn:

Package the Application
The procedure for packaging the application comprises four steps:

1. Create the files that will form the contents of the PAR archive, of the types you need: JAD, JAR, JNLP, PNG, GIF, JPG, and so on. Store them in their own directory, named first in this example.
   
   A PAR file is simply a ZIP file used to hold provisioning content. It may contain one or more client bundles and must be accompanied by a provisioning descriptor, which you'll create next.
   
   
2. Create the PAR's descriptor file; name it provisioning.xml and save it in a subdirectory named META-INF.
   
   This file uses a standard set of XML tags to specify the contents of the PAR file. Code Sample 1 is a descriptor that contains one client bundle, added using the <client-bundle> tag. Another crucial feature of the descriptor file is the <device-requirement> tag, which identifies the software platform needed to run the application.
   
   Code Sample 1: provisioning.xml

   <?xml version="1.0" encoding="ISO-8859-1"?> <provisioning-archive xmlns="http://java.sun.com/xml/ns/j2ee-cp" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee-cp Provisioning_1_0.xsd"> <!-- ********* MIDP Game ********** --> <client-bundle> <content-id> http://java.sun.com/products/j2ee/provisioning/demos/midlets/nim </content-id> <bundle-type>APPLICATION</bundle-type> <descriptor-file>/nim.jad</descriptor-file> <user-descriptions> <display-name> Nim Game </display-name> <description>The game of Nim.</description> <icon>/JavaPowered-8.png</icon> </user-descriptions> <vendor-info> <vendor-name>Sun Microsystems, Inc.</vendor-name> <vendor-url>http://www.sun.com</vendor-url> <vendor-description>Some text</vendor-description> </vendor-info> <copyright> Copyright 2003 Sun Microsystems, Inc. All Rights Reserved. </copyright> <device-requirement> <requirement-name>SoftwarePlatform.JavaPlatform</requirement-name> <requirement-value>MIDP/1.0+</requirement-value> </device-requirement> <catalog-property> <property-name>Category</property-name> <property-value>Game</property-value> </catalog-property> <catalog-property> <property-name>Billing Plan</property-name> <property-value>Price List</property-value> </catalog-property> </client-bundle> </provisioning-archive>

   
   

3. In first, the directory that holds the PAR file's contents, create a build.xml file with the following content:

   <?xml version="1.0" encoding="ISO-8859-1"?> <project name="first" default="first" basedir=">"> <target name="first"> <zip destfile="first.par" basedir="./first" /> </target> </project>

   
   

   Note well: The names of the PAR file and the directory that will hold it must match.
   
   
4. Run the Ant tool, which will execute the build.xml script to create the PAR file.

You can test the newly created PAR file with the partester utility, which comes with the RI. This tool:

• Checks the provisioning.xml file for XML schema compliance
• Checks that the bundles in the provisioning.xml match the contents of the PAR file, and that the contents are correctly set
• Checks the syntax of MIDP application descriptor JAD files
• Checks the syntax of Java Web Start descriptor JAD files.

The invocation command is:

partester [options] first.par

Write the Servlets
In this step, you basically write a servlet that handles requests, then uses the provisioning framework and APIs to deliver the bundles to the user. A good example servlet comes with the JSR 124 reference implementation; JAM.java is too long to list here, but you can find it in \j2ee_cp_ri_1_0\test\src\web.

Customize the Configuration Files
Three main configuration files need attention:

• To add or remove support for specific devices, you can customize the devices setup file, devices.xml, that comes with the RI, or you can create your own. This file defines the set of device types known to the RI, and the capabilities of each: software platform, screen size, network protocol, and so on. It also defines the mapping from HTTP request headers to device types. A snippet of devices.xml appears in Figure 2:
  
   
  

  Figure 2: A Fragment of a Devices Setup File

  
  
  
• You can modify adapters.xml to add or remove support for specific adapters. The adapters configuration file that comes with the RI supports three adapters: MIDP OTA, JNLP, and generic. Code Sample 2 shows a MIDP OTA adapter:
  
  Code Sample 2: adapters.xml

  <?xml version="1.0" encoding="ISO-8859-1"?> <adapters xmlns="http://java.sun.com/xml/ns/j2ee-cp" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee-cp Adapters_1_0.xsd"> <adapter> <!-- This is the MIDP OTA adapter. --> <adapter-name>midp</adapter-name> <adapter-class>com.sun.provisioning.adapters.midp.AdapterMIDP</adapter-class> <base-uri>/delivery/midp</base-uri> <descriptor-file> <extension>jad</extension> <mime-type>text/vnd.sun.j2me.app-descriptor</mime-type> </descriptor-file> <fulfillment-duration>0</fulfillment-duration> <init-param> <param-name>install-notify</param-name> <param-value>true</param-value> </init-param> <init-param> <param-name>delete-notify</param-name> <param-value>true</param-value> </init-param> </adapter> </adapters>

  
  

  The tag <adapter-name> defines a unique name for the adapter, and <adapter-class> identifies the Java class file that defines the adapter. If you wish to define your own adapter, your class must extend javax.provisioning.adapter.Adapter. The <base-uri> tag represents a unique base URI related to the root of the provisioning server's URI. The <fulfillment-duration> tag specifies the default number of milliseconds between the creation of the fulfillment task and its expiry; 0 indicates it doesn't expire.
  
  
• Bundle requirements are matched with device capabilities using the matching engine and rules defined in the matchers configuration file, matchers.xml. You can add or remove matcher tags as needed. Code Sample 3 shows a snippet of a matchers.xml file that declares matching rules for the attributes SoftwarePlatform.JavaPlatform and HardwarePlatform.ScreenSize. Note that for each attribute defined by a matcher tag, a matcher object is created at startup by insantiating the named class; for example, HardwarePlatform.ScreenSize causes creation of an instance of javax.provisioning.matcher.DimensionMatcher. The initialization parameter allMustMatch matches Version Match, String Match, Preference Match, Integer Match, and Dimension Match. If the parameter value is true, then all values in the requirement list must be matched by a capability; if false, then any value in the requirement list can be matched by a capability.
  
  Code Sample 3: matchers.xml

  <?xml version="1.0" encoding="ISO-8859-1"?> <matchers xmlns="http://java.sun.com/xml/ns/j2ee-cp" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee-cp Matchers_1_0.xsd"> <matcher> <attribute-name>SoftwarePlatform.JavaPlatform</attribute-name> <matcher-class>javax.provisioning.matcher.VersionMatcher</matcher-class> <init-param> <param-name>allMustMatch</param-name> <param-value>false</param-value> </init-param> </matcher> <matcher> <attribute-name>HardwarePlatform.ScreenSize</attribute-name> <matcher-class>javax.provisioning.matcher.DimensionMatcher</matcher-class> <init-param> <param-name>allMustMatch</param-name> <param-value>false</param-value> </init-param> </matcher> </matchers>

  
  

  Note that you can write new matching rules for attribute names not already declared by the RI. To define the new attributes, use the existing matching classes and add a declaration to the matchers.xml file.

Two more files contain essential configuration information for the provisioning framework and supported adapters: web.xml and sun-j2ee-ri.xml. You need to modify the former to describe your own servlets. You'll need to modify the latter only if you plan to use a database other than Cloudscape.

The J2EE Client Provisioning Specification defines a programming framework that enables J2EE applications to interact with provisioning facilities for client devices in a standard way. It defines a central repository of client applications, services, and content called a provisioning portal, which is responsible for managing the distribution of rich clients and their content. Such a centralized approach allows developers to add features to their applications and services easily. Users interact with this portal to discover rich-client applications, and the portal delivers the items the user selects to their devices.

The J2EE Client Provisioning Specification makes it much easier to provision J2ME devices. The JSR 124 RI implements the final version of the specification; it comes with three adapters and a sample application, RI-Test. As an exercise you may want to download, install, set up, and experiment with the RI. You can then go on to adapt RI-Test's servlets and configuration files for your own applications.

• JSR 124: J2EE Client Provisioning Specification
• Download the J2EE Client Provisioning Reference Implementation
• Java Web Start
• Download Java Web Start
• Over The Air User Initiated Provisioning Recommended Practice for the Mobile Information Device Profile
• Deploying Wireless Java Applications
• The J2ME Wireless Toolkit

Special thanks to David Bowen of Sun Microsystems, whose feedback helped me improve this article.

Qusay H. Mahmoud provides Java consulting and training services. He has published dozens of articles on Java, and is the author of Distributed Programming with Java (Manning Publications, 1999) and Learning Wireless Java (O'Reilly, 2002).