Skip to main content

Provisioning Blackberry clients on the Sun GlassFish Mobility Platform

Posted by hans_hrasna on February 27, 2009 at 1:18 PM PST

The Sun Glassfish Mobility Platform 1.1 includes a Client Provisioning Portal which enables administrators to upload client applications to a repository in the Mobile Platform gateway where they are made available for downloading by client devices over the air. The client portal detects the device type and displays a page with a list of applications available for that device. Here are the steps to upload a Blackberry application to the provisioning repository and download it from the client portal to the device.

For this example we will be creating a provisioning archive (PAR file) that contains one Blackberry client application. A PAR file can contain more than one application and they can be for different device types. A PAR file is simply a zip file that contains the client application(s) and a provisioning descriptor file, META-INF/provisioning.xml. So for this PAR we will have one COD file (The Blackberry equivalent of a JAR file), a JAD file and a provisioning.xml file. The provisioning.xml file describes the contents of the PAR file. I am going to use the SecureMusicDB application from the 1.1 client bundle (samples/secure-musicdb/BlackBerry) for this example. The filename for the Blackberry application is securemusicdb.cod. The provisioning.xml file for our PAR might look like this:

<?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">

    <!-- ********* MusicDB Blackberry ********** -->

  <client-bundle>

    <content-id>
      MusicDB Blackberry Client 1.1_01 
    </content-id>

    <bundle-type>
      APPLICATION
    </bundle-type>    

    <descriptor-file>
      /securemusicdb_bb.jad
    </descriptor-file>

    <user-descriptions>
      <display-name>
        MusicDB BlackBerry Client 1.1_01 
      </display-name>
      <icon>
         /Clear_Note_32.png
      </icon>
      <description>Sample MusicDB Client for BlackBerry</description>
    </user-descriptions>

    <vendor-info>
      <vendor-name>Sun Microsystems, Inc.</vendor-name>
      <vendor-url>http://www.sun.com</vendor-url>
      <vendor-description>
        Sun Glassfish Mobility Platform (SGMP)
      </vendor-description>
    </vendor-info>

    <copyright>
      Copyright 2009 SunMicrosystems, Inc. All Rights Reserved.
    </copyright>

    <version>1.1_01 FCS </version>

    <device-requirement>
      <requirement-name>
        SoftwarePlatform.JavaPlatform
      </requirement-name>
      <requirement-value>
        RIM/4.2.1
      </requirement-value>
    </device-requirement>

    <catalog-property>
      <property-name>Category</property-name>
      <property-value>Corporate</property-value>
    </catalog-property>
    <catalog-property>
      <property-name>Keywords</property-name>
      <property-value>MusicDB</property-value>
    </catalog-property>
    <catalog-property>
      <property-name>Device Type</property-name>
      <property-value>BlackBerry</property-value>
    </catalog-property>

  </client-bundle>

</provisioning-archive>

Notice the device-requirement element contents:

<device-requirement>
      <requirement-name>
        SoftwarePlatform.JavaPlatform
      </requirement-name>
      <requirement-value>
        RIM/4.2.1
      </requirement-value>
    </device-requirement>

The entry indicates that this client application requires the RIM Java platform version 4.2.1 or higher. When an application connects to the client portal, the portal detects the device type and maps it
to its software capabilities and only shows the applications that the device can support.

If you developed this application yourself with the Blackberry JDE or in NetBeans as described in Developing Client Applications for the BlackBerry Using NetBeans IDE, you can use the JAD file generated by rapc. If you do not have a JAD file, you can easily create one from scratch.
Here is an example of a JAD file for our BlackBerry application:

	Manifest-Version: 1.0
	MicroEdition-Configuration: CLDC-1.1
	MicroEdition-Profile: MIDP-2.0
	MIDlet-Version: 1.1_01
	MIDlet-Name: securemusicdb
	MIDlet-Jar-URL: securemusicdb.jar	
	MIDlet-Jar-Size: 1
	MIDlet-1: Secure MusicDB,/toolkit_duke.jpg,sample.SecureJdbcMIDlet
	MIDlet-Vendor: Sun Microsystems, Inc.
	RIM-COD-Module-Dependencies: net_rim_cldc,net_rim_pdap
	RIM-COD-URL: securemusicdb.cod
	RIM-COD-Module-Name: securemusicdb
	RIM-COD-Size: 85032

The second and third lines indicate the minimum version of CLDC and MIDP supported by the application. Use CLDC 1.1 and MIDP 2.0 for MP applications.

Use the MIDlet-Version line to specify the version of your application. If you change this value, the user will be prompted to upgrade on subsequent downloads of the application.

Use the MIDlet-Name line to provide a name for your application.

The MIDlet-Jar-URL and MIDlet-Jar-Size properties are not used by the BlackBerry device, but they must still be specified or the BlackBerry device will report the error "Invalid JAD File." In non-BlackBerry MP client applications, provisioning archives are usually composed of a JAD file and a JAR file, which contains the Java class files. The JAR file is irrelevant for BlackBerry MP applications because the BlackBerry has its own special COD file format.

The MIDlet-1 property is series of three comma-separated values. The first value is the name of the application as it appears on the screen of a BlackBerry device. The second value is the graphic file for the icon that will be displayed on the screen. The third value is for the arguments that will be passed to your public static void main(String[] args) method. Multiple application icons can be displayed simply by entering subsequent lines such as: MIDlet-2, MIDlet-3, etc.

Use the MIDlet-Vendor line to specify the company name that you want to display for your application.

Use the RIM-COD-Module-Dependencies line to specify what libraries your application depends on. For example, if it depends on the BlackBerry Browser module, the Phone module, or other third-party libraries, specify it here.

Use the RIM-COD-URL line to specify the location of the COD file for your application. Use the RIM-COD-Module-Name line to provide a unique name for the module. Use the RIM-COD-Size line to indicate the COD file.

Now package the three files into a zip file with this directory hierarchy:

/META-INF/provisioning.xml
/securemusicdb.cod
/securemusicdb_bb.jad

You may want to name the file with the .par extension to indicate that it is a provisioning archive, but this is optional. At this point you are ready to upload the PAR file to the repository. Select the "Provisioning" tab in the MP Admin Console. On the Provisioning page, select the "Upload" tab. Here you will see a Upload PAR File text field and a Browse button. Select the PAR file you just created and click the "Upload PAR File" button. You will see a confirmation message if your file was uploaded to the repository successfully or an error message if there was a problem.

provisioning_upload.jpg

After you have uploaded the PAR file to the repository it is ready for clients to download. From a Blackberry , point the browser to the Client Portal URL: http://:8080/sync/admin/client. You will see the client portal paged and should be able to select the application you provisioned and download it onto the Blackberry. Here is a screenshot sample of the portal page and download screen:

client_portal.jpg

client_download.jpg

Related Topics >>