recently tested one of my J2ME MIDlet applications on a Sprint Vision handset. Once on the handset, the application ran great and I needed to make only a few changes to the code, but I ran into a few snags before I could even get my MIDlet onto the device.
In this article, I detail some of the bumps I ran into, including Web server configuration and caching problems, and I explain the solutions I used to overcome them. I also discuss Over The Air (OTA) Provisioning on the Sprint PCS network and the Java Application Descriptor’s contribution to the provisioning process?this little file can provide useful additions for your application that will enhance the user’s experience.
I use simple, readily available tools for development and deployment, so you can take these techniques and apply them to your own development, testing, and deployment processes. Although most of the techniques and advice I provide were applied on a Sprint Vision handset, the majority should be applicable to other J2ME-enabled devices.
MIDlets and MIDlet Suites
MIDP is a version of the java platform that is aimed at small footprint devices like cellular handsets. Java applications that run on MIDP devices are called MIDlets, and a MIDlet suite is a grouping of MIDlets that can share resources at runtime. A suite is actually comprised of two separate files:
I concentrate on the JAD because this little jewel enables you to do all sorts of cool things. For example, you can:
You can use development environments like KToolBar or Sun ONE Studio ME to automate the creation and maintenance of the JAD file. (If you use the KToolBar, you eventually have to modify the JAD file manually as some of the techniques in this article cannot be implemented through this tool).
First, I’ll demonstrate how to create a simple MIDlet that you can use for practice. This article includes a KToolBar project, which you can just download into the KToolBar “/apps” directory. This MIDlet will help you get your feet wet and figure out how to upload the application onto a phone before you try out any of the cooler features the JAD offers. Uploading an App to the Handset
When I got my first Sprint handset, the LG 5350, I was eager to incorporate it into the testing pipeline. I assumed I would connect it with a USB cable (typical of most handsets), upload the application, and test. Unfortunately, Sprint controls handset access tightly. Like the Microsoft Xbox and Sega Game Cube gaming consoles, no hacking is allowed; only registered developers can gain access to the hardware.
Your only option is to follow Sprint’s recommendations and download your application Over The Air (OTA). This simply means that you have to make your application’s JAR and JAD files available on a Web server, where you can then “HTTP” your way to the URL where your JAD file resides. The browser will download your application into the Applications folder and test it. Sun Microsystems publishes the high-level OTA Provisioning guidelines on the J2ME portion of its site, and keeping up to date on this process is not only advantageous for development and testing purposes but also may provide you with interesting opportunities for commercial deployment, as you’ll learn later.
This OTA procedure can be rather time consuming if the reception in your area is not great, and caching issues with the Sprint gateway can make it confusing and error prone. In the following sections, I share more details about the specific problems you will face and the workarounds I’ve established in my development processes to deal with these issues.
Trying an App on the Hardware
Place the .jar and .jad files in a place that is accessible via HTTP. For the purposes of this article, I use the fictitious URL: http://webserver/devx/SimpleMidlet.jad. You’ll have to make a few configuration changes to the Web server that will serve your JAR and JAD files. This tutorial deals with Apache 1.3 Web server. Consult your particular server’s documentation for proper instructions on how to do this.
If you access the Web server containing your JAR and JAD files with your handset, you may find that the JAD file is delivered to the phone as only a text file with its contents displayed as normal text. This indicates that your Web server needs to be configured.
You need to associate specific MIME types to the “.jar” and “.jad” extensions so that the Web server can tell the client which kind of content to expect. In apache, you add the following two lines to the httpd.conf configuration file:
AddType text/vnd.sun.j2me.app-descriptor .jadAddType application/java-archive .jar
You then restart the server and point your handset to the URL where your .jad file resides. Your particular hardware will vary depending on how its download, confirmation, and installation process works, but most generally tend to follow the high-level process defined by the OTA Provisioning guidelines. On my LG 5350, once the download process is complete, it deposits the MIDlet into the generic Applications directory and prompts me to run the application.
The JAD File
As I mentioned earlier, two files are required for provisioning your application, the JAR and JAD. If you use a tool like KToolBar or Sun ONE to create a MIDlet, you’ll notice that the JAD file is automatically created for you and your application’s class files are packaged into a JAR along with a file titled manifest.mf. Both the manifest and the JAD files allow you to describe the application by specifying such things as the minimum requirements for running the application, how many MIDlets are part of the MIDlet suite, and any dependencies. Since a JAR file for a MIDlet suite contains information describing itself and might be quite large, the JAD file provides this information without requiring the user to download the entire JAR. This feature potentially saves the user a considerable amount of download time.
The .jad file is a simple text file with an attributes key, a colon, an optional space, and the value for that attribute. It looks like the following:
The optional and user-defined parameters I cover in this section include the following:
Many more optional parameters are described in the OTA Recommended Practices document.
You’ll see that knowing this file’s purpose and formatting will help you overcome some of the bumps you’ll run into when provisioning.Caching Problems
Since OTA Provisioning requests occur over HTTP on the Sprint network. The Sprint Gateway’s caching poses a problem when you try to frequently update your content during testing. When I updated a piece of code in my MIDlet and placed the new JAR into the Web server, I noticed that a new request from the handset for the JAD did not return the updated JAR to the handset. In fact, checking the server logs, I noticed that no new requests had been made for the files.
The solutions I propose are adding extra HTTP headers that tell the Gateway that the file should not be cached and creating a workaround that simply adds a random query string to the URL to trick it into thinking it needs to make a new request for entirely different content.
Using HTTP Headers
There are two ways to specify that certain groups of files or a particular file should not be cached by the gateway:
- Specify it in the HTTP header via something like PHP or Perl when outputting a file.
- Configure the Web server to mark certain MIME types as non-cacheable.
To mark a file as non-cacheable in PHP, add the following line of code somewhere in the file prior to outputting anything else:
For testing purposes on the development server, I’ve configured the server to specify that files with the extensions .jar and .jad should never be cached. This allows me to mark a group of files as non-cacheable and frees me from having to use the first method described above, which taints my code. Again, I am using the Apache httpd server. Configuring your server probably will be different, so consult the documentation.
In your httpd.conf file, uncomment the lines of code that look like this:
LoadModule expires_module modules/mod_expires.so...AddModule mod_expires.c
This will activate the expiration module. If you haven’t added the appropriate MIME types for .jar and .jad file extensions as I specified previously, then do so now. Next, add the following three lines at the end of the file to mark .jar and .jad as non-cacheable:
ExpiresActive OnExpiresByType text/vnd.sun.j2me.app-descriptor "access plus 1 second"ExpiresByType application/java-archive "access plus 1 second"
This tells the proxy or browser that files of type .jar and .jad expire one second after they’ve been accessed. Don’t use this for deployment purposes, however; there are good reasons for the gateway caching.
Adding a Random Query String
If you have absolutely no access to either your server’s configuration file or a processing language like PHP or Perl, you can trick the gateway into thinking that a new request you make is for a completely different file. Just append a random query string to the JAR or JAD’s URL.
Using my fictitious URL for the SimpleMidlet, the change will look like this:
HTTP://webserver/SimpleMidlet.jad?r=[some random number]
This ensures that the gateway will request the file anew from your server.
This works only if you need to download a new version of the JAD. To download a new version of the JAR, you’ll have to modify the MIDlet-Jar-URL using the same scheme as you did for the JAD. The new entry will look something like this:
MIDlet-Jar-URL: HTTP://webserver/SimpleMidlet.jar?r=[some random number]
A word of caution: you might run into trouble with tools like KToolBar if you add too many pre-processing directives to the JAD. Keep them to a minimum.Fun Things with JAD
Now that you’ve expedited OTA Provisioning to our handset without any caching problems and you know what a MIDlet suite is comprised of you can begin to have some fun. More specifically, I’ll demonstrate how you can add certain key-value pairs to the application’s JAD file by using the KToolBar settings panel to specify optional and user-defined entries.
Remember that the manifest file inside the JAR partly mirrors the JAD file. That’s why a tool like KToolBar can help ensure that the appropriate values are copied to both files. Consult the documentation if you’re doing this manually.
Representing Your Application
Adding an icon to your application makes it stand out from the other applications on the phone, and it’s really rather simple. First, create a PNG icon. If you’re using KToolBar, put the file into the “/res” directory inside the project directory. Add the following entry to the JAD file:
MIDlet-Icon: /[path to icon]
The “[path to icon]” is a relative path to the file inside the JAR file.
Specify a description that will appear to the user upon installation. Add the following entry to the JAD file:
MIDlet-Description: A simple OTA Test Midlet
Replace it with a description that is appropriate for your application.
When I browse through the Applications folder of my LG5350, I can access a menu with the option to show me more information about the application I currently have highlighted. Wouldn’t it be nice to send the user to a page with more information about that app and a link to other products you might offer? Well you can. Just add the following entry to the JAD file:
Replace the absolute URL with the one for your application.
You can also have the handset notify you that the user has successfully installed or failed to install the application on his or her handset. This is a great way of keeping track of how many people are downloading and trying out your application. And since extra information about the particular handset that made the request is provided as an HTTP request header, you can use this information to track on which phones your application is installed. The success code and a brief message are provided in the POST body of the request. Since the request headers also contain an identifier for the handset in the User-Agent field, you can use this information and the success code to identify which handsets successfully install your applications and which fail to install it. To enable this you add the following entry to the JAD file:
A note of caution: this attribute is not included in the current MIDP specification, so consult the hardware manufacturer’s specification to make sure this feature is supported on its handset. See the list of success codes in the OTA Provisioning Recommended Practices.
Some handsets will separate applications into different folders that are appropriately named for their content. My LG5350 automatically places applications I download via OTA into the Applications folder. But what if I wanted my application to be automatically downloaded into the Games folder? I’d simply add the following line to the JAD file:
You should, of course, replace Games with whatever category name is appropriate for your application. If the folder does not exist, the AMS will automatically create it.
Finally, one of the coolest things you can do with J2ME on Sprint phones is to create applications that can act as handlers for specific URI schemes or Internet Media Type handlers. This particular functionality requires the use of the Muglets API provided by Sprint. I’ll explain how to use the Muglet API in my next article, but I’ll explain briefly how to get started.
Say you’ve created an enhanced mail client and you want the application to handle mailto URIs in a Web page. Simply add the following line to your JAD and your application will be called whenever the user clicks on a link containing that URI:
Content-1-Handler: uri-scheme, mailto
You’ll have to access the value passed through the Muglet API.
Finally, if you want to associate a file type to your application, add the following line to the JAD file:
Content-1-Handler: media-type, [mime/type]
Mime/type is the mime type of the file you want to handle.
You can see that OTA User Initiated Provisioning has some unexpected aspects that, although not complicated to resolve, may be quite confusing when you first encounter them during testing and even deployment. Once you overcome them, however, you can start to take advantage of some of the features that a JAD provides. Although they may not make your application run faster (they certainly will not slow it down), extras like icons and Help URLs make your application look more professional to users. In addition, the ability to specify Media Type handling and URIs instantly provides a developer the opportunity to create some interesting applications.