When the predictions service is deployed to a web server such as Tomcat, the server translates the JSP script predictions.jsp (see Example 1-6) into a servlet instance. For now, this technical detail is overlooked because it is convenient to talk about the JSP script itself as the target of a request.

<jsp:useBean id    = "preds"                            
             type  = "predictions.Predictions"
             class = "predictions.Predictions">
  <% // Check the HTTP verb: if it's anything but GET,
     // return 405 (Method Not Allowed).
     String verb = request.getMethod();
     if (!verb.equalsIgnoreCase("GET")) {
       response.sendError(response.SC_METHOD_NOT_ALLOWED,
                          "Only GET requests are allowed.");
     }
     // If it's a GET request, return the predictions.
     else {
       preds.setServletContext(application);            
       out.println(preds.getPredictions());
     }
  %>
</jsp:useBean>

As requests come to the JSP script, the script first checks the request’s HTTP method. If the method is GET, an XML representation of the predictions is returned to the requester. If the verb is not GET, the script returns an error message together with the HTTP status code. The relevant code follows:

String verb = request.getMethod();
if (!verb.equalsIgnoreCase("GET")) {
  response.sendError(response.SC_METHOD_NOT_ALLOWED,
                     "Only GET requests are allowed.");
}

JSP scripts have implicit object references such as request, response, and out; each of these is a field or a parameter in the servlet code into which the web server, such as Tomcat or Jetty, translates the JSP script. A JSP script can make the same calls as an HttpServlet.

On a successful request, the JSP script returns a list of predictions and their predictors, a list available from the backend JavaBean Predictions. The JSP code is pretty straightforward:

out.println(preds.getPredictions());

The object reference out, available in every JSP script, refers to an output stream through which the JSP script can communicate with the client. In this example, the object reference preds (line 1) refers to the backend JavaBean that maintains the collection of predictions; the getPredictions method in the backend bean converts the Java list of Predictions into an XML document.

The backend code consists of two POJO classes, Prediction (see Example 1-7) and Predictions (see Example 1-8). The Prediction class is quite simple, consisting of two properties: who (line 1) is the person making the prediction and what (line 2) is the prediction.

package predictions;
import java.io.Serializable;

public class Prediction implements Serializable {
    private String who;   // person
    private String what;  // his/her prediction
    public Prediction() { }
    public void setWho(String who) { this.who = who; }      
    public String getWho() { return this.who; }
    public void setWhat(String what) { this.what = what; }  
    public String getWhat() { return this.what; }
}

The Predictions class does the grunt work. For example, its populate method (line 3) reads the prediction data from a text file, predictions.db, encapsulated in the deployed WAR file, and the toXML method serializes a Java List<Prediction> into an XML document, which is sent back to the client. If there were problems reading or formatting the data, the predictions service would return null to the client.

package predictions;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.BufferedReader;
import java.io.ByteArrayOutputStream;
import java.beans.XMLEncoder; // simple and effective
import javax.servlet.ServletContext;

public class Predictions {
    private int n = 32;
    private Prediction[ ] predictions;
    private ServletContext sctx;
    public Predictions() { }
    public void setServletContext(ServletContext sctx) { this.sctx = sctx; } 
    public ServletContext getServletContext() { return this.sctx; }
    // getPredictions returns an XML representation of
    // the Predictions array
    public void setPredictions(String ps) { } // no-op
    public String getPredictions() {                                         
        // Has the ServletContext been set?
        if (getServletContext() == null) return null;
        // Has the data been read already?
        if (predictions == null) populate();
        // Convert the Predictions array into an XML document
        return toXML();
    }
    private void populate() {                                                
        String filename = "/WEB-INF/data/predictions.db";
        InputStream in = sctx.getResourceAsStream(filename);
        // Read the data into the array of Predictions.
        if (in != null) {
            try {
                InputStreamReader isr = new InputStreamReader(in);
                BufferedReader reader = new BufferedReader(isr);
                predictions = new Prediction[n];
                int i = 0;
                String record = null;
                while ((record = reader.readLine()) != null) {
                    String[] parts = record.split("!");
                    Prediction p = new Prediction();
                    p.setWho(parts[0]);
                    p.setWhat(parts[1]);

                    predictions[i++] = p;
                }
            }
            catch (IOException e) { }
        }
    }
    private String toXML() {                                              
        String xml = null;
        try {
            ByteArrayOutputStream out = new ByteArrayOutputStream();
            XMLEncoder encoder = new XMLEncoder(out);
            encoder.writeObject(predictions); // serialize to XML
            encoder.close();
            xml = out.toString(); // stringify
        }
        catch(Exception e) { }
        return xml;
    }
}

On a GET request, the JSP script invokes the method setServletContext (line 1 in the bean, line 2 in the JSP script) with an argument, the implicit object reference named application. The backend bean needs access to the servlet context in order to read data from a text file embedded in the deployed WAR file. The ServletContext is a data structure through which a servlet/JSP script can interact explicitly with the servlet container. The call to the setServletContext method sets up the subsequent call to the getPredictionsmethod (line 2), which returns the XML representation shown in Example 1-5. Here is the getPredictions method without the comments:

public String getPredictions() {
   if (getServletContext() == null) return null;
   if (predictions == null) populate(); 
   return toXML();
}

The method populate (line 1 immediately above) reads the data. The predictions reference in the code segment above refers to the Map in which Prediction references are values. If the JSP script fails to set the servlet context, there is no way for the back-end Predictions bean to provide the requested data. The reason is that the populate method requires the servlet context (the reference is sctx, line 1, in the code below) in order to access the data:

private void populate() {
   String filename = "/WEB-INF/data/predictions.db";
   InputStream in = sctx.getResourceAsStream(filename); 
   ...
}

If the servlet context has been set but the predictions reference is null, then the data must be read from the predictions.db file into the Map that makes the data available to clients. Each entry in the Map is a Prediction, which again is a pair: who predicts what. Finally, the toXML method serializes the Java predictions into an XML document using the Java utility class XMLEncoder (line 1):

private String toXML() {
   String xml = null;
   try {
      ByteArrayOutputStream out = new ByteArrayOutputStream();
      XMLEncoder encoder = new XMLEncoder(out);                 
      encoder.writeObject(predictions); // serialize to XML
      encoder.close();
      xml = out.toString(); // stringify
   }
   catch(Exception e) { }
   return xml;                                                  
}

The XML document from the toXML method (line 2) becomes the body of the HTTP response to the client.

Although the XML from the predictions service is generated using the XMLEncoder class, Java does provide other ways to generate XML—but perhaps none quite as simple as XMLEncoder. The Prediction objects must be serializable in order to be encoded as XML using the XMLEncoder; hence, the Prediction class implements the empty (or marker) Serializable interface and defines the get/set methods for the properties who (the predictor) and what (the prediction). The Prediction properties are serialized into XML elements in the response document.

The predictions service can be deployed under the Tomcat web server using a provided Ant script (with % as the command-line prompt):

% ant -Dwar.name=predictions deploy

The deployed WAR file would be predictions.war in this case. The next section (see The Tomcat web server) elaborates on the Apache Tomcat server and explains how to install and use this server. The section An Ant script for service deployment clarifies the Ant script, which is packaged with the book’s code examples. The deployed WAR file predictions.war includes a standard web deployment document, web.xml, so that the URI can be shortened to /predictions/.

% startup.sh   ;; or startup.bat on Windows to start Tomcat
% shutdown.sh  ;; or shutdown.bat on Windows to stop Tomcat

Using CATALINA_BASE:   /home/mkalin/tomcat7
Using CATALINA_HOME:   /home/mkalin/tomcat7
Using CATALINA_TMPDIR: /home/mkalin/tomcat7/temp
Using JRE_HOME:        /usr/local/java
Using CLASSPATH:       /home/mkalin/tomcat7/bin/bootstrap.jar

System.err.println("Goodbye, cruel world!");

cwd: build.xml

cwd: build.xml
 |
src: products.jsp, json.jar, web.xml

acme.Products

cwd: build.xml
 |
src: products.jsp, json.jar, web.xml
 |
acme: Products.java

% ant -Dwar.name=products deploy

% ant

% ant clean

% ant compile

% ant -Dwar.name=predictions deploy

Later examples introduce RESTful clients in Java and other languages; for now, either a browser or a utility such as curl (see The curl Utility) is good enough. On a successful curl request to the service:

% curl -v http://localhost:8080/predictions/

the response includes not only the XML shown earlier in Example 1-5 but also a trace (thanks to the -v flag) of the HTTP request and response messages. The HTTP request is:

GET /predictions/ HTTP/1.1
User-Agent: curl/7.19.7
Host: localhost:8080
Accept: */*

The HTTP response start line and headers are:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=96C78773C190884EDE76C714728164EC; Path=/test1/;
Content-Type: text/html;charset=ISO-8859-1
Transfer-Encoding: chunked

Recall that an HTTP GET message has no body; hence, the entire message is the start line and the headers. The response shows the session identifier (a 128-bit statistically unique number, in hex, that Tomcat generates) in the header. In the JSP script, the session identifier could be disabled, as it is not needed; for now, the goal is brevity and simplicity in the code.

If a POST request were sent to the RESTful predictions service:

% curl --request POST --data "foo=bar" http://localhost:8080/predictions/

the request message header becomes:

POST /predictions/ HTTP/1.1
User-Agent: curl/7.19.7
Host: localhost:8080
Accept: */*
Content-Length: 7
Content-Type: application/x-www-form-urlencoded

The response header is now:

HTTP/1.1 405 Method Not Allowed
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=34A013CDC5A9F9F8995A28E30CF31332; Path=/test1/;
Content-Type: text/html;charset=ISO-8859-1
Content-Length: 1037

The error message:

Only GET requests are allowed.

is in an HTML document that makes up the response message’s body. Tomcat generates an HTML response because my code does not (but could) stipulate a format other than HTML, the default Tomcat format for a Tomcat response.

This first example illustrates how a JSP script is readily adapted to support web services in addition to websites. The next section goes into more detail on servlets and JSP scripts. In summary, the predictions web service is implemented as a JSP script with the two backend JavaBeans in support. This first example highlights key aspects of a REST-style service: