mDevInf - Mobile Device Information
	Install and Build Guide

Contents

• Introduction
• mDevInf (Mobile Device Information)
• Installing and running a binary package
• Installing
• Running
  Updated 11 Oct 2007
• Running a Web Start package
• Installing, building and running from source
• Installing
• Building
• Running
• Other tasks
• Java Web Start Installation
• mDevInf and WURFL files
• The main WURFL file
• WURFL Patch files
• The capability description file
• The device_pix file
• The mDevInf configuration file

Introduction

If, over the last 3 years, you've needed to know something about the capabilities of a mobile phone, then WURFL (Wireless Universal Resource FiLe) should have been your first port of call.

It's a fantastic resource, crammed with information. The core of WURFL is the (rapidly growing) XML file containing information about almost every mobile device worth knowing about. Information is available for over 400 device capabilities grouped together into areas like security, J2ME, sound formats, DRM and many others.

The problem with such a large amount of information is that it very difficult to use in it's raw form.

Luckily, the authors have provided some useful server-side applications that use the WURFL database that are also open source. (WALL is very useful if you're a WAP developer). Information about these can be found at the WURFL Java pages.

mDevInf (Mobile Device Information)

mDevInf is a desktop utility, written in Java. It helps to find information contained in the WURFL file and displays this information in a useful format.

Reasons for needing to search the WURFL are many and varied, eg.

• Are you a developer, wondering exactly how many different devices will be able to use your WAP content?
• Are you a web administrator and you'd like to know what kind of device is making requests?
• Do you work in customer support dealing with questions about mobile device capabilities?
• Do you own a mobile phone and want to see what your device is capable of?
• Are you about to upgrade your mobile phone, but want to check what other phones can do?

mDevInf can help to answer all of these questions.

How to get mDevInf

You can download the mDevInf application from SourceForge. There are four different files in each release, these are:

• Source bundles - These contain all the files you need except the latest WURFL file. Just choose the format you prefer.
• mDevInf_<version>.src.tar.bz2
• mDevInf_<version>.src.zip
• Binary bundles - These contain the executable JAR file and an explanatory file (RUNNING.txt)
• mDevInf_<version>.tar.bz2
• mDevInf_<version>.zip
• Java Web Start - A pre-built executable that you can run through your browser using the Java Web Start Technology.
• A Web Start version of mDevInf is available from java.net by clicking here.
• Note that the Web Start version provided on java.net only uses the base WURFL file, no patch files can be used.

If you just want to use mDevInf, download one of the binary bundles or take advantage of the Web Start version. If you want to see the source code and build the application for yourself, then download a source package. Instructions for installing, building and running are provided below.

Installing and running a binary package

This section explains how to get the mDevInf application working from the pre-built binary package.

Pre-requisites

In order to build the application, you require

• the Java Runtime Environment (JRE) 1.5.0 or later. The application relies on libraries that have only been built-in since that release.

Installing

Unpack the file using your favourite unpacking tool. This will create the following directories and files on your system:

    .../mDevInf/
    .../mDevInf/bin/
    .../mDevInf/bin/mDevInf.jar
    .../mDevInf/icons/
    .../mDevInf/icons/mDevInfIcon64.png
    .../mDevInf/LICENSE.txt
    .../mDevInf/RUNNING.txt

Running

When the files are unpacked, to run the application, you can type the following at a command prompt:

    > java -jar /home/fred/downloads/mDevInf/bin/mDevInf.jar

or, if you have changed to the .../mDevInf/bin directory:

    > java -jar mDevInf.jar

    > java -Xms256m -Xmx256m -jar /home/fred/downloads/mDevInf/bin/mDevInf.jar

    > java -Xms256m -Xmx256m -jar mDevInf.jar

On the other hand. If you prefer a GUI approach, you can create a desktop shortcut to the mDevInf.jar file. An icon is provided (mDevInfIcon64.png) for use with desktop shortcuts.

The RUNNING.txt file contains more details on running the application.

Running a Web Start package

This section explains how to run the Web Start version of the tool from that java.net site.

If you have any question regarding this version, please see the Java Web Start Technology page on Sun's Java site.

Pre-requisites

In order to run the Web Start version, you require

• the Java Runtime Environment (JRE) 1.5.0 or later. The application relies on libraries that have only been built-in since that release.
• a web browser

Running

To run the Web Start version you just need to point your browser at http://download.java.net/tools/mdevinf.jnlp

Note that you don't always need to access the Web Start version through your browser. When accessing the file, you can save the file (mDevInf.jnlp) to disk and create a desktop shortcut to it. The only thing you need to ensure is that you set up your File Associations to use javaws to execute .jnlp files.

Installing, building and running from source

This section explains how to install, build and run the mDevInf application from the source package. The source package is considerably smaller than the binary package because it does not contain the wurfl.zip file.

Pre-requisites

In order to build the application, you require

• the Java Development Kit (JDK) 1.5.0 or later. The source code uses syntax that has only been available since that release and also relies on libraries that have only been built-in since that release.
• Apache Ant, the Java build tool. The application was originally built using version 1.6.5, but older versions may work OK.

Ant is not mandatory to manage the build, but since the build script is provided and Ant is widely used, the remainder of this guide concentrates on building using Ant. If you don't want to (or can't) use Ant for any reason, the please examine the tasks in the build.xml file for pointers on building the application.

Installing

Unpack the files using your favourite unpacking tool. I won't describe the entire directory structure here, but as with the binary package, it should unpack to a directory called mDevInf.

Building

Open a command prompt and change to the .../mDevInf/build directory. From there type:

    > ant

This will run the default Ant script task, which is "execute".

If you have followed the instructions closely, at this point, the build script should fail and you should be told that the build has failed because the wurfl.zip file could not be found. It should also show the URL to the necessary file (http://sourceforge.net/project/showfiles.php?group_id=55408).

Running

To get the application running successfully, download a copy of the wurfl.zip² file and place a copy in the .../mDevInf/Resources directory.

Typing the ant command again should then result in a successful build.

Other tasks

The Ant build script is quite comprehensive and contains some other tasks that you may wish to use. Type the following from the .../mDevInf/build directory to see all the tasks:

    > ant -projecthelp

The following tasks are the only ones that have not been used either directly, or indirectly so far:

createTarballs

This task creates the files mDevInf_<version>.tar.bz2, mDevInf_<version>.src.tar.bz2, mDevInf_<version>.zip and mDevInf_<version>.src.zip files, ready for distribution.

    > ant createDistroPackages

document

This task creates the Java API documentation (including all private attributes/methods) and is probably only useful if you need to understand the source code.

The documentation produced is written to .../mDevInf/docs

webstartbuild

From version 0.6.1, the build file can also create a basic distribution suitable for Java Web Start deployment.

The webstartbuild task will rebuild the software to include all the necessary files in a single JAR file.

Java Web Start Installation

The mDevInf JAR file is not "signed" and so the Web Start security model will not permit access to files on the local system. This means that mDevInf cannot even check to see if files (such as wurfl.zip or wurfl_patch.xml) exist.

It is therefore important to note that small, but highly significant modifications have been made to the source code to deal with the application behaviour when it is executed using Web Start technology.

1. A new icon file is included in the distribution (mDevInfIconWS.png). This icon replaces the standard icon (mDevInfIcon64.png) in the About... dialog to indicate to users that they are using the Web Start version.
2. The WURFLInfo class attempts to load the Web Start icon as it's first task.
3. If the icon is successfully loaded, it is assumed that mDevInf is being executed using Web Start and no local files will be used.
4. If the icon is not loaded, it is assumed that mDevInf is being executed as a local application with access rights to the file system, so local files will be checked for existence and loaded as necessary.

The JNLP file:

<?xml version="1.0" encoding="UTF-8"?>
<jnlp spec="1.5+"
      codebase="http://download.java.net/tools/mdevinf/"
      href="mdevinf.jnlp">
  <information>
    <title>mDevInf</title>
    <vendor>Jim McLachlan - Objective Software Services Ltd.</vendor>
    <description>Mobile Device Information</description>
    <description kind="tooltip">m(obile)Dev(ice)Inf(ormation)</description>
    <homepage href="http://mdevinf.sourceforge.net/"/>
    <icon href="mDevInfIcon64.png" />
    <offline-allowed />
    <shortcut>
      <desktop/>
    </shortcut>
  </information>
  <resources>
    <j2se version="1.5+" />
    <jar href="mDevInf.jar" />
    <jar href="wurfl.jar" />
    <jar href="images.jar" />
    <jar href="capDesc.jar" />
  </resources>
  <application-desc main-class="com.ossltd.mdevinf.MDevInf" />
</jnlp>

In this file (provided in the source distribution), the codebase is set to the mDevInf page at java.net. Please remember to update this for your distribution.

Unsigned applications using the Java Network Launch Protocol (JNLP) for Web Start deployment can only access resources on the host server within JAR files. These resources must be specified in the resources section of the JNLP file.

The webstartbuild task in the provided Ant build script places the necessary resources inside JAR files. The resources have been included as separate JAR files (rather than all bundled into the mDevInf.jar file) in order to allow updates to be made on the server that should be automatically detected by the client's Web Start installation. This is primarily to allow the WURFL file to be updated without having to re-download the application code.

Server Configuration

Not all servers are set up to deal with Web Start files. A MIME type may need to be added to your system to cope with files with the .jnlp extension. As per usual, the Apache example is:

AddType     application/x-java-jnlp-file     .jnlp

mDevInf and WURFL Files

In the following descriptions, the term working directory is used to define the directory from which the application was executed. When running the application from the command line, the current directory is used. When running the application from a desktop shortcut, the properties of the shortcut define the working directory.

For source distributions, using the execute Ant task, the patch file should appear in the project root directory (.../mDevInf/wurfl_patch.xml)

Note: For users that require different WURFL and/or patch configurations, it is recommended that separate directories are created to store the appropriate WURFL and patch files. If a shortcut/link to the mDevInf executable is also provided in that directory, then that directory will be the working directory and only the data and configuration from that directory will be used.

The main WURFL file

The binary distribution contains a copy of the latest available version of the wurfl.xml file (currently 2.0.2-pre). This is built into the mDevInf.jar file and is not particularly easy to change. To allow alternative WURFL files to be used, the application checks for files as follows. The first matching file is the one that is used:

1. wurfl.zip in the working directory
2. wurfl.xml in the working directory
3. The default wurfl.zip file, built in to mDevInf.jar

The WURFL patch file(s)

The WURFL file (wurfl.xml) does not always contain everything that is necessary for a specific purpose. See the WURFL patch page for more details about the reasons for patching the WURFL file and a description of the format of the WURFL patch file (wurfl_patch.xml).

In a similar way to that described above, the application will search for and include WURFL patch files automatically at start up. There are no patch files built in to mDevInf.jar, so only those files that appear in the working directory will be included.

Only file names that begin with wurfl_patch and end with .xml will be loaded by mDevInf.

The first patch file to be included will always be wurfl_patch.xml. If you have additional patch files to include these should be named wurfl_patch_<identifier>.xml. The application will sort these files and include them in their natural ordering³ eg.

    .../mDevInf/wurfl_patch.xml
    .../mDevInf/wurfl_patch_1.xml
    .../mDevInf/wurfl_patch_2.xml
    etc.

The capDesc file

This capDesc.zip file is a compressed archive containing a single XML file called capDesc.xml. This file contains the following information for each of the capabilities in the WURFL devices:

• name - The name of the capability as it appears in the WURFL (or patch) file(s)
• type - The type of data used to represent the values of the capability (string, integer, true/false)
• description - The descriptive text for the capability (displayed in the information dialogs)

The type element is particularly significant because this is used to determine the type of field used to capture values for the capability. For true/false fields, a combo box is displayed allowing only the selection of true or false values and only the "=" operator is allowed. For integer fields, only numeric input is accepted. For string fields, any input is accepted but only the "=" operator is allowed.

If changes are made to the WURFL capabilities, it is highly recommended that this file also be updated to reflect these changes.

When no matching description can be found for a capability within mDevInf, it's type is assumed to be a string.

<?xml version="1.0" encoding="UTF-8"?>
<wurfl_capability_descriptions>
  <capability>
    <name>brand_name</name>
    <type>string</type>
    <description>Brand</description>
  </capability>
  <capability>
    <name>model_name</name>
    <type>string</type>
    <description>Model</description>
  </capability>
  .
  .
  .
</wurfl_capability_descriptions>

The device_pix file

The binary distribution contains a copy of the latest available version of the device_pix.zip file (currently device_pix_5.zip). This is built into the mDevInf.jar file and is not particularly easy to change. To allow alternative device_pix zip files to be used, the application checks for files as follows. The first matching file is the one that is used:

1. device_pix.zip in the working directory
2. The default device_pix.zip file, built in to mDevInf.jar

Note that the name of the file must be device_pix.zip. If the file is provided with another name (eg. device_pix_5.zip), simply rename it.

mDevInf.cfg.xml

This is the configuration file for mDevInf and will be loaded (from the working directory) at startup.

The file contains the following information:

• The list of selected patch files - this should be a complete list of patch files in the working directory, along with a status indicating whether they are selected for inclusion.
• Save searches - including the name of the search and all search criteria.
• Any user-defined capability name mappings, eg. "Make" may be more appropriate than "brand_name". These values are used in the Comparison tab.