6 Using javax.servlet.http interfaces with WAP protocol

The WAP/WSP protocol is essentially a binary form of HTTP/1.1. The Nokia WAP Server provides a complete implementation of the Java Servlet API 2.1, and existing servlets can be run directly on the Nokia WAP Server. There are some basic differences in the underlying WAP protocols that may affect WAP service development when the Java Servlet API is used.

This chapter describes the biggest differences at the WAP and HTTP concept level. The enclosed Nokia WAP Server API Reference in the [installation directory]\docs directory contains notes about the notable differences between implementing servlets for WAP and for HTTP.

6.1 WSP protocol has two modes

The WSP protocol has two modes of operation: the connection-oriented and connectionless mode. The essential difference between these modes is that the connection-oriented mode uses the WTP transaction protocol and thus provides a reliable service. Connectionless requests are just datagrams that can be lost or duplicated, and they can arrive in a different order than they were sent, and the same applies to responses.

The Nokia WAP Server accepts and negotiates the WSP sessions with the terminals. Session creation is allowed to all terminals that are allowed to communicate with the Nokia WAP Server.

Servlets receive the connectionless requests and connection-oriented requests identically as a HttpServletRequest into their service()(or doGet()) method. If a servlet wants to know how the request was delivered, it should get the WapRequest interface and use the IsConnectionMode() method.

A connectionless service does not have associated session information. This means that session headers can not be used to optimise bandwidth usage, the maximum allowed response size can not be known, the maximum datagram size of the bearer limits the response sizes, and requests can not be aborted.

Both session protocol modes can operate over the security layer (WTLS).

6.2 WAP is message-based (not stream-based)

The HTTP protocol is built on reliable TCP connections. When an HttpServlet on a web server writes its response to the OutputStream, it assumes that the response is then delivered unless the stream writing fails and throws an exception.

WAP does not have a connection-based reliable stream for data transfer. WAP has the Wireless Transaction Protocol (WTP), which provides reliable transactions as its basic service. Servlet requests in the WSP connection-oriented mode are delivered with a WTP class 2 transaction invoke, and the servlet response is delivered in the Result part of the transaction. When the terminal has successfully received the response, it acknowledges the result.

This has some effects on the behaviour of the servlets using the Java Servlet API.

InputStream. When the input stream is being read, the actual data is already in the Nokia WAP Server and thus reading from the stream is fast.

OutputStream. The servlet creates its output by writing to the ServletOutputStream object. The output stream provided by the Nokia WAP Server is not a stream to the terminal, instead it is a memory-based stream that is copied to a WSP protocol message after the service() and sent to the terminal with the Response part of the WTP protocol. Sending the response starts after the service() method has returned. Calling os.close()or os.flush()in service() are ignored by the Nokia WAP Server.

Response Headers. There is a fixed place in the WSP protocol for sending the HTTP headers in encoded format and for the status code. Sending the HTTP headers starts after the service() method has returned. The limitations defined in the Java Servlet API for setting all the headers and status code before writing the response body thus do not apply in the Nokia WAP Server, but it is recommended that you follow the instructions.

6.3 Response delivery in WAP

As mentioned in the previous section, WAP is not stream-based and thus the delivery of the response including the status, body and response headers starts after the servlet service() method has returned. This means that a servlet using the Java Servlet API has no way of getting information about if the response was delivered or not. This also applies to origin server-based architecture: the origin server has no means of getting information about whether the response was delivered to the WAP terminal or not. Often, however, this is an important requirement in order to ensure consistency of a business process (e.g. to make sure that an assignment to a field worker was delivered to the WAP terminal) or to establish accurate billing procedures (a customer is charged only for successful service transactions).

The Nokia WAP Server defines an AckListener interface, which can be implemented by a servlet that requires the response delivery status information. Servlets willing to receive this information must provide their AckListener interface to the Nokia WAP Server during the servlet.init() method through the com.nokia.wap.server.WapServerinterface that can be retrieved via ServletContext.getAttribute(). The Nokia WAP Server will then during the response delivery provide information to the servlet about the status of the delivery with the following functions:

AckListener.ResponseError(reasonClass, reasonCode, ServletRequest, ServletResponse) to inform that the response was not delivered to terminal, because the transaction has been aborted by the terminal or by the Nokia WAP Server. If the terminal is out of coverage, out of battery power or inaccessible for some other reason, the response delivery is aborted by the Nokia WAP Server due to timeout in the WTP protocol.
AckListener.ResponseConfirmed(String ackHeaders, ServletRequest, ServletResponse) to inform that the response was successfully delivered to the terminal and the terminal has acknowledged it.

The ServletRequest and ServletResponse are the same objects that were given to the servlet in the servlet.service() call.

WSP requests made using the connectionless WSP protocol are never confirmed or aborted by the Nokia WAP Server.

For details, see the Nokia WAP Server API Reference.

6.4 Wireless world has limited bandwidth

The driving goal of the WAP protocol development has been to optimise the bandwidth usage of the protocols. This optimisation has some effects on the servlets.

Header encoding. The WSP protocol defines a compact binary encoding of the textual HTTP headers. The Nokia WAP Server does this encoding automatically when the response delivery starts.

Status code. A servlet can set the response status with the status codes defined in the HttpServletResponse interface. The Nokia WAP Server converts the status code to the 8-bit format defined in the WSP protocol. The textual description added with setStatus()in the HttpServlet interface is ignored by the Nokia WAP Server.

Aborting a request. A servlet can also choose to abort a request. If the request is aborted, the terminal does not need to provide an acknowledgement and thus saves it sending a datagram. The request aborting can be done with the WapRequest interface in the Nokia WAP Service API.

Limited data capacity of terminals. Terminals are devices that often have limited processing power and memory capacity. The WSP protocol provides session negotiation where the terminal can express the maximum packet data size it can receive. If a servlet tries to send a response that is known by the Nokia WAP Server to be too big, an error page is returned to the terminal and the servlet is informed if it has registered an AckListener interface. Note that size limitations apply to actual data content, so if the servlet replies with a WML page, the limitation applies to the encoded WML page. The defined maximum size of a WSP data unit for terminals is 1400 bytes.

6.5 WSP session

The WSP protocol defines the concept of a WSP session. The session provides a context for making requests and sending responses. A session holds information that helps to optimise the bandwidth usage. A session contains the following information:

Session headers. A WSP session holds information about server and client headers that remain constant for each request and response. If a request and response contain headers that are equal to the headers in the session, there is no need to transfer them per request or response. The Nokia WAP Server takes care of removing the unnecessary headers from the response and automatically adding the client session headers to the request headers before passing the request to the servlet.

Protocol options. The terminal and the Nokia WAP Server negotiate WSP protocol options during the session setup or resumption. These options specify e.g. if push is allowed, the maximum data amount that can be sent or received, if resumption is allowed, etc.

Header code pages. If additional header code pages have been negotiated, the Nokia WAP Server will automatically use them during header encoding.

Extended methods. If extended methods are used, the HttpServlet helper functions like doGet() can not be used. Instead, the service() method must be overridden and the correct action taken based on the extended method.

Programmer's Guide Nokia WAP Server API 1.1 page 1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17

previous || guide home ||