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.
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:
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.
In order to build the application, you require
Unpack the file using your favourite unpacking tool. This will create the following directories and files on your system:
.../mDevInf/1 .../mDevInf/bin/ .../mDevInf/bin/mDevInf.jar .../mDevInf/icons/ .../mDevInf/icons/mDevInfIcon64.png .../mDevInf/LICENSE.txt .../mDevInf/RUNNING.txt
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
Since this project was originally developed, the WURFL file has grown in size so that it now requires more than the default amount of memory available to the Java Runtime Environment.
This problem can usually be identified by the application becoming stuck at the splash screen.
To provide the JRE with enough memory, use the following at the command prompt instead:
> java -Xms256m -Xmx256m -jar /home/fred/downloads/mDevInf/bin/mDevInf.jar
or, if you have changed to the .../mDevInf/bin directory:
> 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.
In order to run the Web Start version, you require
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.
In order to build the application, you require
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.
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.
Open a command prompt and change to the .../mDevInf/build directory. From there type:
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).
To get the application running successfully, download a copy of the wurfl.zip2 file and place a copy in the .../mDevInf/Resources directory.
Typing the ant command again should then result in a successful build.
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:
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
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
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.
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.
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:
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 ordering3 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:
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:
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.
This is the configuration file for mDevInf and will be loaded (from the working directory) at startup.
The file contains the following information:
1 Throughout this guide, I will use the Linux path separator of "/". For Windows just replace this with a "\")
2 Capability elements were changed in the WURFL file changed between 1.9 and 2.0, however mDevInf uses the fact that the XML is self-describing to use either version seamlessly.
3 If the patch files are numbered and more than 10 are used, users should note that wurfl_patch_10 would appear before wurfl_patch_2. In such cases where ordering is important, it is suggested that all numbers are padded with leading zeros to avoid possible confusion (eg. wurfl_patch_01.xml, etc.).