WURFL?! Yes, another acronym: Wireless Universal Resource FiLe The WURFL website expands on this: "You can think of the WURFL as a global database of all devices and their capabilities." Such a database is especially useful in the current mobile device landscape where a vast array of HTML/WML/Flash/AJAX features are implemented differently (or not at all.) In essence, WURFL makes it easier for you to improve the web experience you offer people when they are on the move.

WURFL is the product of much diligence and attention to detail by Luca Passani and many contributors of device information. As an added bonus it is open and free for anyone to use. This is in the best interests of mobile device users everywhere of course! Luckily for us the WURFL project goes all the way and provides a Java API. To get started with WURFL you first need to ensure your ZXTM has working Java support and then download the following items.

• wurfl-latest.zip - the WURFL itself
• web_browsers_patch.xml - an optional file that adds data for desktop web browsers
• wurfl-1.0.jar - get the most recent WURFL .jar file, 1.0 at the time of writing
• commons-collections - extract the commons-collections-<ver>.jar file from the latest 3.2 binary release
• commons-lang - extract the commons-lang-<ver>.jar file from the latest 2.4 binary release
• commons-logging - extract the commons-logging-<ver>.jar file from the latest 1.1 binary release
• backport-util-concurrent - download most appropriate 3.x release (backport-util-concurrent-Java60-3.1.tar.gz in my case) and extract the backport-util-concurrent.jar file from it

Upload the files specified using the Calalogs > Java UI page on your ZXTM. Note that the wurfl-latest.zip can be uploaded as-is, but you can choose to unzip it and upload the wurfl.xml file. Now you're all set to experiment with the following examples.

The first sample servlet is a very simple use-case of WURFL, useful as a base for your own servlet or for debugging. The intention is for it to introduce the WURFL API as it fits within the framework of Zeus Java Extensions. WURFL is typically configured using the ConfigListener model, but we're not TomCat and don't go as far as implementing all the nuts and bolts required by full web applications. Our WURFL servlet must perform the required initialisation itself, so I've implemented an init method that sets up a WURFLManager. As much work as possible is done at servlet initialisation time. Then all the doGet method needs to do is check the request against the pre-initialised WURFLManager. You can download the code or the compiled class for this servlet. To compile the code yourself execute the following javac command. This example is given for compiling on the ZXTM host system after all the .jar files mentioned above have been uploaded to your ZXTM, you can also compile the servlet on another machine as outlined in our Java Devlopment Guide.

javac -cp "$ZEUSHOME/zxtm/lib/*:$ZEUSHOME/zxtm/conf/jars/wurfl-1.0.jar" \
   ZeusWURFLInfoServlet.java 

To get the servlet working follow these steps:

1. Upload the ZeusWURFLInfoServlet.class file using your ZXTM's Catalogs > Java UI page, leave the "Automatically create TrafficScript rule" checkbox ticked
2. If you want normal web browsers to be detected properly click on the ZeusWURFLInfoServlet link on the UI page and add the parameter "wurfl_patches" with the value "web_browsers_patch.xml" (which you must also upload to the Catalogs > Java page as covered above)
3. Set up a Virtual Server for testing, I set one up listening on port 60000 and tied it to the special "discard" pool
4. Associate the auto-generated ZeusWURFLInfoServlet rule with the test Virtual Server as a request rule
5. Visit your virtual server in some different web browsers!

The result should be a page showing some general information about your browser at the top followed by the full table of WURFL capabilities and their values. The following screenshots show the top part of the output using a few browsers available in the Zeus office.

Firefox on Ubuntu Linux

Opera on HTC S710

IE on HTC S710

Safari on iPhone

This is neat and all as a demo, but not particularly useful. What we really want is a module that can export capabilities so that they can be used by TrafficScript and other extensions. We also don't want to specifically be a doGet processor, so we'll modify the servlet along the lines described in the Writing TrafficScript functions in Java article.

There are a lot of capabilities covered by WURFL, the tables in the above screenshots go on for several pages - more than 500 capabilities in all. So we'll make it possible for TrafficScript to specify what capability fields it wants.

This gives us a servlet that could be used from TrafficScript using the following function.

sub checkWURFL() {
   $ua = http.getHeader( "User-Agent" );
   if (!string.length($ua)) return;

   $markup = data.get("WURFL" . $ua . "preferred_markup");
   $datarate = data.get("WURFL" . $ua . "max_data_rate");
   if (string.length($markup)) {
      log.info("Returning cached values for User-Agent: " .
         $datarate . ", " . $markup);
      $1 = $markup;
      $2 = $datarate;
      return;
   }

   # no cached values for the UA, so run it through WURFL
   java.run( "ZeusWURFLServlet", "max_data_rate", "preferred_markup" );
   $markup = connection.data.get("preferred_markup");
   $datarate = connection.data.get("max_data_rate");

   data.set("WURFL" . $ua . "preferred_markup", $markup);
   data.set("WURFL" . $ua . "max_data_rate", $datarate);

   log.info("Returning fresh WURFL values for User-Agent: " .
      $datarate . ", " . $markup);
   $1 = $markup;
   $2 = $datarate;
   return;
}

# simple case to test the checkWURFL function
checkWURFL();
http.sendResponse("200", "text/html",
    "<html><head><title>WURFUL</title></head><body>" .
    "<h1>Max Data Rate: " . $2 . "kbps</h1>" .
    "<h1>Preferred Markup: " . $1 . "</h1></body></html>", "");

The corresponding Java code and .jar file are available for you to download.

• ZeusWURFLServlet.java
• ZeusWURFLServlet.jar

Rather than the doGet method implemented in the ZeusWURFLInfoServlet we now have a simpler service method.

   public void service(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {

      String[] args = (String[])request.getAttribute( "args" );
      if (args == null || args.length == 0) {
         throw new ServletException("error: no arguments supplied");
      }

      Device device = manager.getDeviceForRequest(request);
      Map capabilities = device.getCapabilities();

      for (int i = 0; i < args.length; ++i) {
         String cap = (String)capabilities.get(args[i]);
         if (cap == null) {
            log("no capability found matching: " + args[i]);
         } else {
            ((ZXTMServletRequest)request).setConnectionData( args[i], cap );
         }
      }
   }

Note that for this implementation I've included another class that properly directs org.apache.commons.logging messages to the ZXTM Event Log properly. The logging code is documented here, you can also download ZeusServletLogger.class here or from that page. The commands used to build the jar file on my ZXTM host machine follow.

javac -cp "$ZEUSHOME/zxtm/lib/*:$ZEUSHOME/zxtm/conf/jars/wurfl-1.0.jar" \
   ZeusWURFLServlet.java
jar -cvf ZeusWURFLServlet.jar ZeusWURFLServlet.class ZeusServletLogger.class

There is much more you could do with the WURFL Java Extension provided in this article. Think of it as a starting point for developing your own solutions to improve the web browsing experience of your mobile users.

A few examples:

• The max_data_rate value retrieved above could be used to reduce image quality or size for people with low bandwidth devices. This would result in a snappier web browsing experience for these people as there would be less data for them to retrieve over their slow links.
• The preferred_markup value can be used to direct clients to different backend pools based on whether they can handle XHTML, or should be served WML.
• The streaming_flv value can be checked to see if the device has Flash video support and can thus be sent to your full bells-and-whistles website. A scaled down version could be made for those that only have Flash Lite, which is specified by the value of flash_lite_version. Devices that don't support flash at all (such as the iPhone) can be sent to a plain HTML version of the site, or WML as in the previous bullet point.
• Speaking of the iPhone, it doesn't have Flash but its browser does have excellent AJAX support. You know your site is being visited by an iPhone user using the normal iPhone web browser when model_name is "iPhone" and mobile_browser is "Safari". If there are important differences between iPhone OS releases you can also check model_extra_info or device_os_version for this detail.
• For AJAX in general there are a whole set of specific properties:
  • ajax_manipulate_css
  • ajax_manipulate_dom
  • ajax_support_event_listener
  • ajax_support_events
  • ...

Up to date documentation on all the WURFL capabilities can be found on the WURFL website.

Any of these values can also be passed on to your backend nodes of course. You could add special headers containing the values, a cookie, or a URL argument. You could also cache browser capabilities uniquely to each device with cookies or another method of session tracking, rather than cache the capabilities based solely on the user agent. Then you could offer users the ability to override special mobile device modes.

We would love to hear your ideas and learn how we can help you in this exciting area - the opportunities are practically limitless.