As discussed in the previous section, Pivot provides a set of classes for interacting with HTTP-based REST services, which Pivot calls "web queries". Pivot also provides an abstract base class named org.apache.pivot.web.server.QueryServlet that helps to facilitate implementation of such services.
The following example shows a Pivot client application that interacts with a REST service for managing expense data. The web service is implemented using QueryServlet and is discussed below:
NOTE This application must be run via a locally-deployed WAR file. It will not work in the online tutorial.
The QueryServlet class extends javax.servlet.http.HttpServlet and provides overloaded versions of the base HTTP handler methods that make them easier to work with in a REST-oriented manner:
Each method takes an instance of QueryServlet.Path that represents the path to the resource being accessed, relative to the location of the servlet itself. Path is a sequence type that allows a caller to access the components of the path via numeric index. For example, if the query servlet is mapped to the "/my_service/*" URL pattern, given the following URL:
http://pivot.apache.org/my_service/foo/bar
the path argument would contain the values "foo" and "bar", accessible via indices 0 and 1, respectively.
Unlike the base HttpServlet class, QueryServlet operates on arbitrary Java types rather than HTTP request and response objects. This allows developers to focus on the resources managed by the service rather than the lower-level details of the HTTP protocol.
QueryServlet uses a serializer (an implementation of the org.apache.pivot.serialization.Serializer interface) to determine how to serialize the data sent to and returned from the servlet. The serializer used for a given HTTP request is determined by the return value of the abstract createSerializer() method. This method is called by QueryServlet prior to invoking the actual HTTP handler method. The example servlet uses an instance of org.apache.pivot.json.JSONSerializer, which supports reading and writing of JSON data. Pivot provides a number of additional serializers supporting XML, CSV, and Java serialization, among others, and service implementations are free to define their own custom serializers as well.
Each handler method declares that it may throw an instance of org.apache.pivot.web.QueryException. This exception encapsulates an HTTP error response. It takes an integer value representing the response code as a constructor argument (the org.apache.pivot.web.Query.Status class defines a number of constants for status codes commonly used in REST responses). The web query client API, discussed in the previous section, effectively re-throws these exceptions, allowing the client to handle an error response returned by the server as if the exception was generated locally.
Though it is not shown in this example, query servlet implementations can also access the query string arguments and HTTP headers included in the HTTP request, as well as control the headers sent back with the response. Query string parameters are accessible via the getParameters() method of QueryServlet, and the request/response headers can be accessed via getRequestHeaders() and getResponseHeaders(), respectively. All three methods return an instance of org.apache.pivot.web.QueryDictionary, which allows the caller to manipulate these collections via get(), put(), and remove() methods.
The following listing contains the full source code for ExpenseServlet, which provides the implementation for the REST service used in this example. The implementation of each method is discussed in more detail below:
The init() method, which is defined by QueryServlet's base class HttpServlet, is called when a servlet is first created by a servlet container. ExpenseServlet's implementation of init() is as follows:
It loads an initial list of expenses using an instance of CSVSerializer. The contents of the CSV file are as follows:
2010-03-28, Travel, 1286.90, Ticket #145-XX-71903-09
2010-03-28, Meals, 34.12, Took client out
2010-03-31, Meals, 27.00,
2010-04-01, Meals, 12.55,
2010-04-02, Meals, 18.86,
2010-04-02, Parking, 30.00, Cambridge Center parking
2010-04-03, Meals, 20.72,
2010-04-06, Travel, 529.00, Marriott reservation #DF-9982-BRN
Due to the call to setItemClass(), the rows in the CSV file are deserialized as instances of org.apache.pivot.tutorials.webqueries.server.Expense, a Java Bean class that is defined as follows:
After the list of expenses has been loaded, init() iterates over the list, assigns each expense an ID, and adds it to a map. This collection-based approach is sufficient for a tutorial example; a real application would most likely use a relational database to manage the expense data.
doGet() is used to handle an HTTP GET request. It returns an object representing the resource at a given path. The doGet() method in the example servlet is defined as follows:
If the request does not contain a path, the method returns the list of all expenses. Otherwise, it attemps to look up and return the requested expense by its ID. If the expense is not found, an HTTP 404 ("Not Found") error is returned to the caller via the thrown QueryException; otherwise, the expense is returned along with the default HTTP 200 ("OK") status code. The bean value is converted to JSON format by the JSONSerializer instance returned by createSerializer().
doPost() is used to handle an HTTP POST request. It is primarily used to create a new resource on the server, but can also be used to execute arbitrary server-side actions.
When a resource is created, doPost() returns a URL representing the location of the new resource. Consistent with the HTTP specification, this value is returned in the "Location" response header along with an HTTP status code of 201 ("Created"). If a POST request does not result in the creation of a resource, doPost() can return null, which is translated by QueryServlet to an HTTP response of 204 ("No Content") and no corresponding "Location" header.
The doPost() method in the example looks like this:
The first thing the method does is ensure that the request is valid. If the caller has not provided a value in the body of the request, HTTP 400 ("Bad Request") is returned. Otherwise, it assigns the expense an ID and adds it to the list and map.
Finally, it returns the location of the new expense resource. The location value is generated simply by appending the name of the temp file to the location of the servlet, obtained by a call to QueryServlet#getLocation().
doPut() handles an HTTP PUT request. It is often used to update an existing resource, but can also be used to create a new resource. The return value of doPut() is a boolean flag indicating whether or not a resource was created. If true, HTTP 201 is returned to the caller; otherwise, HTTP 204 is returned.
ExpenseServlet's implementation of doPut() is as follows:
Like doPost(), it first validates the format of the request. In addition to a body, doPut() also requires a path component to identify the resource to be updated. A real expense service might want to verify that the requested resource exists before proceeding; however, the example service simply interprets an unused ID as a request to create a new resource. Consistent with the API, it returns true if a resource was created and false otherwise.
doDelete() handles an HTTP DELETE request. When successful, it simply deletes the resource specified by the path and returns HTTP 204. The source code for this method is shown below:
Like the other methods, the request is first validated; then, if the expense exists, it is deleted. Otherwise, HTTP 404 is returned.
The Expenses client application allows a user to interact with the web service. It is not described in this section, but builds on concepts discussed in earlier sections. The source code is available in the Pivot source distribution under the "tutorials" project.