15.1 Generating an XML Response

XML is a set of syntax rules for how to represent structured data using markup elements represented by an opening tag (optionally with attributes), a body, and a closing tag:

<employee id="123">
  <first-name>Hans</first-name>
  <last-name>Bergsten</last-name>
  <telephone>310-555-1212</telephone>
</employee>

This XML example contains four elements: <employee>, <first-name>, <last-name>, and <telephone>.

By selecting sensible element names, an XML file may be understandable to a human, but to make sense to a program, it must use only a restricted set of elements in which each element has a well-defined meaning. This is known as an XML application (the XML syntax applied to a certain application domain). A couple of examples are the Wireless Markup Language (WML) used for browsers in cellular phones and other small devices, and XHTML, which is HTML 4.0 reformulated as an XML application. Another example is the web application deployment descriptor, used to configure various aspects of a standard Java web application, as you have seen in the previous chapters.

As I mentioned in Chapter 3 and Chapter 5, everything in a JSP page that is not a JSP element is template text. In all examples so far, I have used HTML as the template text, but it can be any markup, for instance XHTML or WML XML elements. Example 15-1 shows a JSP page that sends a simple phone book to a wireless device, using the XML elements defined by the WML specification as the template text.

Example 15-1. WML phone book JSP page (phone_wml.jsp)

<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN" 
  "http://www.wapforum.org/DTD/wml_1.1.xml">
<%@ page contentType="text/vnd.wap.wml" %>
<wml>
  <card id="list" newcontext="true">
    <p>Phone List</p>
    <p>
      <anchor>Bergsten, Hans
        <go href="#Bergsten_Hans"/>
      </anchor>
      <br/>
      <anchor>Eckstein, Bob
        <go href="#Eckstein_Bob"/>
      </anchor>
      <br/>
      <anchor>Ferguson, Paula
        <go href="#Ferguson_Paula"/>
      </anchor>
    </p>
  </card>
  
  <card id="Bergsten_Hans">
    <p>Bergsten, Hans</p>
    <p>
      Phone: 310-555-1212
      <do type="prev" label="Back">
        <prev/>
      </do>
    </p>
  </card>
  <card id="Eckstein_Bob">
    <p>Eckstein, Bob</p>
    <p>
      Phone: 800-555-5678
      <do type="prev" label="Back">
        <prev/>
      </do>
    </p>
  </card>
  <card id="Ferguson_Paula">
    <p>Ferguson, Paula</p>
    <p>
      Phone: 213-555-1234
      <do type="prev" label="Back">
        <prev/>
      </do>
    </p>
  </card>
</wml>

A discussion of the WML elements is outside the scope of this book, but let's look at some important details of the JSP page. The first line in Example 15-1 is an XML declaration, telling which version of XML the document conforms to. Some WML browsers are very picky about this being the first thing in an XML document, and even whitespaces—regular spaces, linefeed characters, and tab characters—before the declaration can throw them off. In all examples you have seen so far, the JSP page directive has been on the first line. Here, I have moved it down so that the linefeed character that ends the directive line doesn't cause any problems.

The second and third lines in Example 15-1 contain an XML document type declaration. This identifies the so-called Document Type Definition (DTD) for the document, basically the definition of all XML elements a conforming document of this type can contain. Here, it's the DTD for the WML 1.1 elements.

The JSP page directive on the fourth line is important. The content type for a JSP page is text/html by default. For a WML document, you must instead specify the content type text/vnd.wap.wml. Otherwise the WML browser doesn't accept the document.

The rest of the page in Example 15-1 is just static WML code. To run this example, you need a WML browser. I've used the WML browser included in the Openwave Systems Inc. SDK 4.1, available at http://developer.openwave.com/resources/sdk.html, to test the examples in this chapter. Figure 15-1 shows what the phone-list menu card and one details card look like in this WML browser.

Figure 15-1. Phone list in WML browser (UP.SDK image courtesy of Openwave Systems Inc.)