A WML helper class

The WML class is fairly basic and could be extended to interpret more of the tags that can be used within WML cards. The abstraction and separation of this presentation code is vital, as all WAP applications will eventually need to cope with a wide variety of different device capabilities, and being able to separate our business logic from our presentation logic is the first step on the road to achieving this goal.

The maximum defined size of a WSP data unit is 1400 bytes. This means that if our decks become too large the WAP device will not be able to receive them. It is good practice to keep deck sizes to below one kilobyte; with this in mind, the size of our deck contents is specified as:

   private static final int _deckSize = 1024;

This header string defines the document has being a WML deck. Beware of including unnecessary line breaks in this string - it shouldn't matter, but certain WML browsers currently have problems with linefeed characters.

   <?xml version=\"1.0\"?>
 <DOCTYPE wml PUBLIC \"-//WAPFORUM//DTD WML 1.1//EN\" 
            "http://www.wapforum.org/DTD/wml_1.1.xml\">

Here is the WML class in full.

WML.java

   package com.wrox.util;

 import java.util.Date;
 import javax.servlet.http.*;
 import java.io.IOException;
 import java.io.PrintWriter;

 //Utility class encapsulating some basic WML
 public class WML
 {
   private StringBuffer _buffer;
   private static final int _deckSize = 1024;
   private void setBuffer(StringBuffer newBuffer) {
    _buffer = newBuffer;<
   }

   private StringBuffer getBuffer() {
    return _buffer;
   }

   public WML() {
    setBuffer(new StringBuffer(_deckSize));
    beginDeck();
   }

  private void beginDeck () {
   getBuffer().append("");
   getBuffer().append("");
    getBuffer().append("");
   }

  private void endDeck() {
   getBuffer().append("");
   }

   public void addCard(String id) {
    getBuffer().append("");
   }

   public void addCard(String id, String title) {
    getBuffer().append("");
   }

   public void endCard() {
    getBuffer().append("");
   }

   public void println(String line) {
    getBuffer().append(line);
   }

   private String getDeck()  {
    endDeck();
    return getBuffer().toString();
   }

   public void outputWML (HttpServletResponse response,
               boolean disableCaching) {
    PrintWriter writer = null;
    try {
      response.setContentType("text/vnd.wap.wml");
      if (disableCaching) {
       //Send a NO CACHING instruction to the user agent
       response.setHeader("Cache-Control", 
               "must-revalidate, no-store");
      }
      //Set the Date header to help calculate cache time outs
      Date now = new Date();
      long timeNow = now.getTime();
      response.setDateHeader("Date", timeNow);

      writer = response.getWriter();
      writer.println(this.getDeck());
    } catch (IOException ioe) {
      ioe.printStackTrace();
    } finally {
      if (writer!=null) writer.close();
    }
   }
 }

The WML class encapsulates the details and logic needed by the servlet to generate a correctly formed WML page to send as the response to the user's WAP browser request.

Using the WML class

To use the WML class the client code simply creates a new WML instance, and then sends it the strings that make up the content of the WML cards. In this simplistic implementation <p> paragraph and <br/> line breaks are input by the client, but a more sophisticated WML class would want to encapsulate this logic as well.

As an example of how to use the WML class, consider the following code snippet:

   WML wml = new WML();
 wml.addCard("WAPMailLogout");
 wml.println("<p align=\"left\">");
 wml.println("Thank you for using WAP Mail<br/>");
 wml.println("<anchor>Restart E-mail");
 wml.println("<go href=\"" + request.getRequestURI() + "\"/>");
 wml.println("</anchor>");
 wml.println("</p>");
 wml.endCard();
 wml.outputWML(response, true);

This produces a deck that contains a single card; this card in turn contains a single paragraph, which displays a message and provides a hyperlink.

Caching

Caching presents the developer of WAP applications with both benefits and problems. The benefits of caching are obvious; it reduces the need for a device to repeatedly fetch information from the server, when it is unnecessary to do so. In this sense caching is a feature and can drastically improve the performance of some applications.

However, this feature can also present a problem for the developer, who has to handle this caching correctly. For an application that visits the same page again and again it is sometimes necessary to convince the browser to fetch a fresh version page if the information contained therein has changed, and not rely on any cached version it may have tucked away in memory.

The knowledge of how to disable the caching of WAP pages is then an important item in the development of WAP applications; to disable caching our WML class contains the following
boolean test:

   if (disableCaching) 
 {
   //Send a NO CACHING instruction to the user agent
   response.setHeader("Cache-Control", "must-revalidate, no-store ");
 }

The Cache-Control instruction we have used in the above WML class should give us the ability to disable the caching of the page by the WAP browser. However, this does not seem to be fully implemented in the Nokia and Phone.com simulators at the time of writing.

Cache-Control Header

The Cache-Control header can take various values, including those used in our WML class, which are summarized below:

• no-cache
  This indicates that the browser should not cache the WML deck.
• no-store
  This indicates not only that the WML deck should not be cached by the browser, but that it shouldn't even be stored by proxy servers. This setting is usually used with sensitive, or time-critical, fast-changing information.
• max-age=seconds
  This specifies a period of time after which the document should be considered invalid and retrieved. For example a 'clock' page might specify max-age=60 so that it is freshly retrieved every minute.
• must-revalidate
  The must-revalidate response header instructs the browser to revalidate, and if necessary re-retrieve each page stored in the history stack even when doing a backwards fetch. It can be combined with the other Cache-Control instructions. For example, the following code instructs the browser to force a reload of a page, even on a <prev> fetch from the browser's recent history stack:

     response.setHeader("Cache-Control", "must-revalidate, no-cache");

  Expires Header
  
  The Expires header could also be used (although it isn't in our WML class), and specifies a time after which the cached page is invalid and should be re-retrieved. For instance to set the page to expire at 11am GMT on Friday 21st April 2000, you would write:

     response.setHeader("Expires", "Fri, 21 Apr 2000 11:00:00 GMT");