Programmers Guide

Programmer's Guide
Nokia WAP Server API 1.0
http://www.nokia.com
Material code: WSRN10060WW0028
VERSION 1.0 November 18, 1999
Copyright © Nokia Corporation 1999. All Rights Reserved.
Please send your comments and suggestions to:
Nokia Group Finland
P.O. Box 207,
FIN-00045 NOKIA GROUP, FINLAND
Tel. 00800 6654 2927 (00800 nokiawap), +358 9 692 7156
Fax. 00800 6054 2927, +358 9 692 6894
Internet mail address:
wap.software@nokia.com
http://www.nokia.com
This document is provided "as is" without warranty of any kind, either express or implied,
including, but not limited to, the implied warranties of merchantability, fitness for a
particular purpose, or non-infringement. Nokia will not, in any event, be responsible for
possible errors in this document or for any damages, incidental or consequential
(including, but not limited to monetary losses), that might arise from the use of or
inability to use the document or the information in it, even if Nokia has been advised of
the possibility of such damages.
The document could include technical inaccuracies or typographical errors. Nokia
welcomes customer comments as part of the process of continuous development of the
document. Any such comments shall become the property of Nokia without any duty of
compensation or obligation to use.
Changes are periodically added to the information herein; these changes will be
incorporated in the new editions of the document. Nokia may at any time make
improvements and/or changes in the product(s) and/or the program(s) described in the
document.
This document is part of the Nokia WAP Server. Reproduction, distribution or transmission
of part or all of this documentation in any form without the prior written permission of
Nokia is prohibited.
Nokia and Nokia Connecting People are registered trademarks of Nokia Corporation. Java,
Sun and Sun Microsystems are trademarks of Sun Microsystems, Inc. Windows NT is a
trademark of Microsoft Corporation. Other product and company names mentioned herein
may be trademarks or trade names of their respective owners, and are mentioned for
identification purposes only.
Copyright © Nokia Corporation 1999. All Rights Reserved.

Contents
1 Introduction ............................................................................ 1
1.1 Overview of the WAP architecture...................................................... 1
1.2 Nokia WAP Server..................................................................................... 2
1.2.1 Purpose and scope.................................................................................... 2
1.3 Background ................................................................................................. 2
1.4 Terminology ................................................................................................ 3
1.5 References................................................................................................... 3
2 Overview of Java Servlets for the Nokia WAP Server........ 5

2.1 Motivation for server side programming with Java Servlets ...... 5
2.2 Servlet architecture overview ............................................................... 6
2.3 What a servlet is for the Nokia WAP Server .................................... 7
2.4 Why write servlets directly for the Nokia WAP Server ................. 7
2.5 Installing a servlet for the Nokia WAP Server ................................. 8
2.6 Tools for the Nokia WAP Server service development ................10
3 Servlet samples ..................................................................... 11

3.1 HelloWorld sample .................................................................................11
3.2 Connector sample ...................................................................................12
4 Features in the Nokia WAP Server API.............................. 15

4.1 Java Servlet API .......................................................................................16
4.2 WAP Service API......................................................................................17
4.3 Server Extension API ..............................................................................19
4.3.1 Server extension sample.......................................................................20
5 Servlets in the Nokia WAP Server...................................... 23

5.1 The life cycle of a servlet......................................................................23
5.2 Security ......................................................................................................24
5.2.1 WAP security protocol (WTLS) ............................................................24
5.2.2 Nokia WAP Server user authentication ...........................................25
5.3 Session tracking.......................................................................................26
5.3.1 Services for session tracking via
the HttpSession interface...........................................................26
5.3.2 WML code..................................................................................................27
5.3.3 Other optional ways to implement session tracking...................28

ii Programmer's Guide
5.4 Error handling ..........................................................................................28

5.4.1 Service errors............................................................................................29
5.4.2 Servlet errors ............................................................................................29
5.4.3 Nokia WAP Server errors ......................................................................29
5.4.4 WAP protocol error.................................................................................29
5.5 Performance..............................................................................................30
5.5.1 Threading ...................................................................................................30
5.6 Servlets working together ....................................................................30
5.6.1 Servlet chaining.......................................................................................31
5.6.2 Mapping servlets to handle specific MIME types.........................33
5.6.3 Locating other servlets and server extensions...............................34
5.7 Pre-installed servlets .............................................................................35
5.8 WAP MIME types ....................................................................................37
6 Using javax.servlet.http interfaces with WAP protocol ... 39

6.1 WSP protocol has two modes .............................................................39
6.2 WAP is message-based (not stream-based)...................................40
6.3 Response delivery in WAP....................................................................40
6.4 Wireless world has limited bandwidth.............................................41
6.5 WSP session ..............................................................................................42

1 Introduction
WAP services can be created in many ways. A simple approach is to place static WAP
(WML and WML Script) content on an existing web server or a Nokia WAP Server.
However, utilizing the Nokia WAP Server’s Application Programming Interfaces
provides remarkable benefits for advanced WAP development. This document is
directed at application developers interested in implementing versatile, dynamic
services by utilizing the open programming interfaces provided by the Nokia WAP
Server.
This document gives an overview and specification of the programming APIs for the
Nokia WAP Server. This chapter contains a short introduction to the WAP architecture
and Nokia WAP Server product. Chapters 2 and 3 give an overview of programming for
Nokia WAP Server and a sample program. Chapters 4 and 5 go into the details of the
Nokia WAP Server application development, and the last chapter discusses the
technical aspects related to WAP protocols that a programmer might find useful when
fine-tuning a WAP service.
The accompanying "Nokia WAP Server API reference" contains detailed interface, class
and method definitions for the API. The reference material is distributed as HTML files
with this document.
More information about WAP can be found at http://www.wapforum.org. More
information about the Nokia WAP Server can be found at
http://www.nokia.com/corporate/wap.
1.1 Overview of the WAP architecture

The WAP Architecture has many components. The essential ones are the WAP terminal,
wireless network, WAP gateway and origin server. The following figure shows one
example of an end-to-end WAP architecture.

2 Programmer's Guide
Datacom network
Application server
Telecom network
SMS, Company
CSD, Operator Intranet
WAP GPRS, network
SMS-C,
terminals IP
...
WAP
gateway
Web Server
For details of the WAP architecture, see the WAP Architecture Specification [2].
1.2 Nokia WAP Server
1.2.1 Purpose and scope

The Nokia WAP Server, a software product running on Windows NT, connects Wireless
Application Protocol (WAP)-enabled terminals to content and applications hosted by
web servers or any other servers on the Internet or a private Intranet. It is targeted at
companies that offer wireless services both internally to their employees and externally
to their customers and business partners.
The Nokia WAP Server enables WAP terminals to receive information from web servers
and other sources, bringing the services at customers', employees' and partners'
fingertips anytime and anywhere. Full standard compliance, easy management, and
expandability have been the driving design goals of the Nokia WAP Server. Being a
committed promoter of open industrial standards and leading manufacturer of WAP-
enabled mobile phones, Nokia is uniquely positioned to provide the market with a full-
featured WAP server based on an open, extensible architecture.
1.3 Background
Because Java Servlets have achieved a strong position in web application development,
the same concept was selected to make it easy for developers to start developing WAP
applications for the Nokia WAP Server.

Introduction 3
The reader of this document is assumed to have a basic knowledge of Java Servlet
development. The Java Servlet API and other servlet developer information is available
at http://www.javasoft.com. The Java Servlet API 2.0 reference material is included in
the [installation directory]\docs directory.
1.4 Terminology
WAP gateway A general entity in the WAP architecture between a WAP
terminal in a telecom network and an origin server in a data
network. The WAP gateway makes a protocol transformation
from WAP to HTTP.
Nokia WAP Server A Nokia product that acts both as an origin server and a WAP
gateway.
Servlet Servlets are software modules that conform to the Nokia WAP
Server API. These modules can be plugged into the Nokia WAP
Server.
Bearer Adapter A piece of software that provides the Nokia WAP Server with
network connectivity.
WPS Wireless Protocol Stack
WSP Wireless Session Protocol. The session layer in WPS.
WTP Wireless Transaction Protocol. The transaction layer in WPS.
WTLS Wireless Transport Layer Security. The security layer in WPS.
MSISDN Mobile subscriber ISDN. (Telephone number or address of

device)
1.5 References
[1] Java Servlet API, Javasoft, http://www.javasoft.com
[2] WAP Architecture Specification, WAP Forum, http://www.wapforum.org
[3] Wireless Session Protocol Specification, WAP Forum, 30-April-1998
[4] RFC 2068, "Hypertext Transfer Protocol - HTTP/1.1", Fielding, R., et.al.


2 Overview of Java Servlets
for the Nokia WAP Server
2.1 Motivation for server side programming with Java

Servlets
Developing advanced online services to be used either through a web browser or a
WAP terminal usually requires server side programming. Various technologies are
nowadays used to handle clients' requests and to generate dynamic content such as
shopping carts and customised home pages.
Technologies such as Common Gateway Interface (CGI) scripts written in Perl or C/C++
have been widely used in the development of dynamic services. Nowadays, however,
Java Servlets are becoming commonly used as an efficient platform-independent
replacement for (CGI) scripts. The main benefits of using Java Servlets for server side
programming are e.g.:
■ Persistency. Instead of creating a separate process for each request, servlets are
typically loaded only once by the server and servlets can maintain services such as
database connection between requests (persistent).
■ Performance. Due to the persistency, servlets perform better than CGI.
■ Portability. Servlets provide the benefits of the Java language: it is easy to code
due to the object model and it is platform-independent (Java Servlets
alreadywritten for web servers can be easily modified to be deployed also on the
Nokia WAP Server).
■ Connectivity. Java Servlets can act as middleware to enterprise Java Beans
(through RMI, IDL) and other resources also via protocols other than HTTP.
For further information on the use of Java Servlets for server side programming and
integration with various environments, see [1].

2.2 Servlet architecture overview

The servlet architecture in the Nokia WAP Server is similar to the Java Servlet concept
defined by Sun Microsystems Inc., which is widely used on web servers for server side
programming.
The basic interaction is based on a request-response model. The following figure shows
the overall architecture.
WAP Request (URL),

WAP Response (WML)
Nokia WAP Server
Java Servlet
Java Servlet interface

interfaces
Request mgmt
Wireless
URL mapping,
bearer
Content encoding, Servlet
&
Caching,
WAP
WAP Server
Authentication,
Protocol
interfaces
WAP Access control
Protocol
WAP Architecture terminology

WAP Wireless Origin Server
WAP Gateway
Terminal network WAP Service
The architecture has three major parts:

WAP Terminal. The mobile user is using a user agent program on the WAP terminal.
Typically, the user agent is a WAP Browser for viewing WML pages and executing
WMLScripts. The WAP Terminal uses the WAP protocol in the wireless network to
connect to a WAP gateway.
Nokia WAP Server is communicating with WAP terminals in the wireless network with
WAP protocols. When receiving a WAP request from the terminal, the Nokia WAP
Server creates a HttpServletRequest and forwards it to the correct servlet. The Nokia
WAP Server takes care of some of the underlying functionality like managing the
servlets and their configurations, managing the requests, forwarding the request to the
correct servlet, decoding the WAP request for the servlet, encoding the WML and
WMLScript responses and encoding the HTTP headers for the WSP protocol. In addition
to these, the server can perform user authentication, access control, response caching,
etc.
WAP Service. A servlet receives a request as an HttpServletRequest object from the
mobile user via the Nokia WAP Server, processes the request and uses the provided
HttpServletResponse to send the response to the mobile user.

Overview of Java Servlets for the Nokia WAP Server 7
In addition to the Java Servlet interfaces, a WAP service can use other services
provided by the Nokia WAP Server. A WAP service can also use other servlets to
complete its tasks.
2.3 What a servlet is for the Nokia WAP Server

As presented above, a Nokia WAP Server servlet is a piece of software that receives
requests from WAP terminals via the Nokia WAP Server and returns responses to them.
A servlet can serve many purposes. Some examples are:
■ WAP Connector. A servlet provides WAP connectivity to existing application
servers. These could be e.g. e-mail systems, process control, logistics, fleet
management, etc.
■ WAP Filter. Pre- or postprocessor for HTTP services. This type is suitable for
integrating to existing web-based services or creating filters that can perform
specific tasks for other servlets.
■ WAP Application. Application that handles WAP requests and typically provides
the reply as a WML response. In this document, a WAP application is a servlet that
provides the service directly without an external origin server.
Nokia WAP Server servlets can also be used to enhance the Nokia WAP Server's
functionality and provide services for other servlets. This kind of servlets that
implement interfaces in the Server Extension API are called server extensions.
2.4 Why write servlets directly for the Nokia WAP Server
WAP services can be implemented in many ways. One way to develop WAP services is
to write the application for a web server. In this case, the Nokia WAP Server works as a
WAP gateway, using HTTP to connect to the application on the web server. This model
works without any additional software on the Nokia WAP Server, and the service is
located completely on the web server. However, this approach does not utilise all the
information and services that could be used in the development of advanced, secure
and user friendly WAP applications.
The Nokia WAP Server provides a platform that can be used to write applications
directly on top of the Nokia WAP Server. The major differences to web server
application authoring are:
■ WAP-specific user and protocol information is available to the servlet.
■ Powerful WAP- and Nokia WAP Server-specific functionality is available (bearers,
information push, response delivery confirmation).
■ Nokia WAP Server provides end-to-end security.
■ Web server is not required.

■ No additional HTTP communication is required from the Nokia WAP Server to an

origin server.
In addition to this, Nokia WAP Server servlets offer an easy environment for
communicating directly with origin servers that offer some application domain-specific
protocol instead of HTTP. For information on implementing various back-end protocols
with Java technology, see [1].
2.5 Installing a servlet for the Nokia WAP Server
NOTE: The user interface screen shots in this chapter are subject to change.
Once a WAP service is created as a Java Servlet, it must be installed and configured for
the Nokia WAP Server. This includes several steps:
1 Install the servlet with the Nokia WAP Server Manager, which is the management
user interface of the Nokia WAP Server. Provide the initial configuration
information and the Java classes that implement the servlet.
2 Map a specific URL to the installed servlet and define the necessary access control
to possibly limit access to your servlet.

Overview of Java Servlets for the Nokia WAP Server 9
3 Configure the servlet. The Nokia WAP Server Manager provides a generic user
interface to modify the configurable properties of servlets.
4 The servlet is now available for WAP terminal users. The servlet can then be
accessed with a WAP terminal by selecting a URL that is mapped to the servlet.
For information on how to configure servlets with Java Archive (JAR) files, see the
Nokia WAP Server Administration Guide.

2.6 Tools for the Nokia WAP Server service development

Servlets for the Nokia WAP Server can be developed with any Java tools that conform
to Sun Java JDK 1.2. The Java Servlet Development Kit is available from Sun
Microsystems Inc. at http://java.sun.com/products/servlet/.
Note: You have to set the classpath to the jsdk.jar and to the wapsrv.jar to
be able to compile servlets that utilise the interfaces in the WAP Service API. The
classpath could look e.g. like the one in the following example:
c:\jsdk2.0\lib\jsdk.jar;c:\progra~1\nokia\nokiaw~1\servle
ts;c:\progra~1\nokia\nokiaw~1\lib\wapsrv.jar
For testing the servlet or any WAP service, a WAP terminal or some WAP terminal
simulator is required. Nokia provides a software product called The Nokia WAP Toolkit
that can be used to test WAP services.
The Nokia WAP Toolkit contains a development environment for WML and WMLScript
content creation and it has a WAP terminal simulator with a full-featured WAP
browser that can be used to browse, run and debug the WAP content.
The Nokia WAP Toolkit is available at http://www.forum.nokia.com, the Nokia WAP

Developer Forum's web site.

3 Servlet samples
3.1 HelloWorld sample

The following class presents a basic sample of a WAP service implemented as a servlet.
As the sample illustrates, writing servlets producing WML content is very much like
writing servlets for generating HTML content. Thus, all the knowledge regarding Java
Servlets available in various sources can easily be applied to the development of
servlets for the Nokia WAP Server.
import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
/**
* HelloWorldServlet - a very simple servlet
*/
public class HelloWorld extends HttpServlet

{
String m_text;
// the initialization parameter is read during

// the initialization of the servlet
public void init(ServletConfig config) throws

ServletException
{
super.init(config);
m_text = config.getInitParameter("text");
if (m_text == null)
{
m_text = "This is a simple test servlet.";
}
}
public void doGet(HttpServletRequest request,

HttpServletResponse response)
throws IOException, ServletException
{
PrintWriter out = response.getWriter();
out.println("<?xml version=\"1.0\"?>");
out.println("<!DOCTYPE wml PUBLIC \"-//WAPFORUM//DTD WML
1.1//EN\"
\"http://www.wapforum.org/DTD/wml_1.1.xml\">");
out.println("<wml>");
out.println("<card id=\"card1\" title=\"Hello
World\">");
out.println("<p>");

out.println(m_text);
out.println("</p>");
out.println("</card>");
out.println("</wml>");
// Remember to close the out object

out.close();
}
public String getServletInfo()

{
return "The simple HelloWorld servlet.";
}
}
Note: The above sample is the same one that is pre-installed in the standard Nokia
WAP Server 1.0 package.
3.2 Connector sample

The following servlet illustrates an imaginary application that initialises an application
server connection during servlet.init() and uses the application server during the
request processing. The Nokia WAP Server has been configured so that it requires
authentication before the request reaches the servlets.
The sample service is a connector type of servlet that connects to an existing system
that controls doors and locks in an office building. The door locking system provides a
monthly changing PIN-code to prevent unauthorized entry to building outside office
hours. The WAP service provides the authorized users the currently correct PIN-code
for the selected door. The user navigates to a WML page that either contains a list of
possible doors or that asks the user to supply the door ID with a WML input form. The
servlet then responds with the correct PIN.
import java.io.*;
import java.util.*;
import javax.servlet.http.*;
import com.xcomp.DoorService.*;
import com.nokia.wap.server.*;
import samples.WMLTool;
public class WapService extends HttpServlet

{
// Initialization of a connection to a DoorService system
DoorService doors;
public void init(ServletConfig config)

throws ServletException
{
doors = new DoorService
(config.getInitParameter("ServerAddress"));
doors.openConnection();
}
public void doGet(HttpServletRequest req,

Servlet samples 13
HttpServletResponse res)
throws ServletException, IOException
{
String user = req.getRemoteUser(); // Authenticated user
Hashtable ht =
HttpUtils.parseQueryString(req.getQueryString());
String door = (String)ht.get("doorId");
int pin = doors.FetchCurrentPIN(user, door);
StringBuffer response = new StringBuffer();
if (pin > 0)
{
response.append("Welcome, the current PIN to this
door is:");
response.append(pin);
}
else
{
response.append("Sorry, correct PIN can not be
provided now.");
}
// Create the response by using the WMLTool sample
WMLTool.Deck deck = new WMLTool.Deck(

new WMLTool.Card("card1", "Door Service"));
deck.getCard(0).add(new WMLTool.Paragraph(response));
res.setContentType(WMLTool.WML_MIME_TYPE);
res.getWriter().print(deck);
res.getWriter().close();
}
}
The following chapter describes in more detail the interfaces used in the sample.


4 Features in the Nokia WAP
Server API
The Nokia WAP Server APIs have been designed to make service authoring easier and to
reduce the learning effort required of web service developers. Developers familiar with
Java Servlet programming for web servers can get into WAP development directly. The
Java Servlet concept is also open for additional functionality. When needs for more
advanced WAP services occur, an existing servlet can be extended to use the additional
services available in the WAP Service API, which has been desiged to provide
developers with an opportunity to use the full potential of WAP.
The following figure shows the logical groups of the interfaces that are available for
servlet authoring.
Servlets
Java Servlet API Basic

Java Servlet
WAP
interfaces
Servlet
Application
Nokia WAP Server Servlet WAP

WAP Service API
Application
AckListener
WAP Server
interfaces
Server Extension API

Servlet Server
Extension
SomeExtension
Server mgmt API Interface
Java Servlet API. A set of standard interfaces defined by Sun that are implemented by
the Nokia WAP Server and used by the WAP services.
WAP Service API. A set of Nokia WAP Server-specific interfaces that provide access to
advanced information and functionality in the Nokia WAP Server. The interfaces are
implemented by the Nokia WAP Server and used by the WAP services.

Server Extension API. A set of interfaces defined by the Nokia WAP Server. A servlet
may provide an implementation of one of the defined interfaces and thus customize
the server operation to meet specific needs. These servlets are called Server extensions.
Servlet. A standard Java interface that must be implemented by all servlets. The
Interface is defined as part of the Java Servlet API.
AckListener may be implemented by a servlet in order to get detailed information
about the response status. This interface is defined as part of the WAP Service API.
Server Management API is a programming interface that provides e.g. servlet
installation and configuration services to allow e.g. installation program creation for
WAP services written as servlets. In practice, that can be implemented as a script that
utilises the commands available via the Nokia WAP Server Command Prompt [see
details of the use of the Command Prompt in the Nokia WAP Server Administration
Guide].The following sections present the interfaces, their purpose and the
functionality of each interface.
4.1 Java Servlet API

The Nokia WAP Server provides a full implementation of the Java Servlet concept
defined by Sun. The Nokia WAP Server implements the HTTP related Java Servlet
interfaces on top of the WAP protocols. The Nokia WAP Server implements Java Servlet
interfaces as specified for Java Servlet API 2.0. A detailed specification of the
interfaces can be found in the [installation directory]\docs directory.
The Nokia WAP Server contains the following interfaces and classes:
Defined in the javax.servlet package:
Interface ServletConfig
Interface ServletContext
Interface ServletRequest
Interface ServletResponse
Interface SingleThreadModel
Class GenericServlet
Class ServletInputStream
Class ServletOutputStream
Exception ServletException
Class UnavailableException
Defined in the javax.servlet.http package:

Interface HttpServletRequest
Interface HttpServletResponse
Interface HttpSession
Interface HttpSessionBindingListener
Interface HttpSessionContext
Class HttpServlet
Class HttpSessionBindingEvent
Interfaces and classes in the Java Servlet API 2.0 that can be used directly from the
javax.servlet.http package:
Class Cookie // Can be used as such from
javax.servlet.http
Class HttpUtils // Can be used as such from

Features in the Nokia WAP Server API 17
javax.servlet.http
Every servlet must implement the servlet interface in order to be identified as a

valid Nokia WAP Server servlet.
There are some basic differences in the underlying WAP protocols that may affect WAP
service development when the Java Servlet API is used. For details, see Chapter 6 and
the enclosed Nokia WAP Server API Reference in the[installation
directory]\docs directory.
4.2 WAP Service API

This group of interfaces provides access to advanced information and functionality in
the Nokia WAP Server. It is not required to use any of the interfaces listed in this group
when creating a WAP service. However, the interfaces provide application developers
with information and services that enable the development of user friendly and secure
applications.
The interfaces are accessed via the ServletRequest.getAttribute() or via
the ServletContext.getAttribute(), depending on the interface.
The following interfaces are found in the com.nokia.wap.server package.
Interface Description Used by

WapRequest Provides WAP-specific A WAP service that needs
information about a WSP more information about the
request. E.g. protocol request than the
configuration, bearer, WSP HttpServletRequest
session. Provides services to can provide or wants to e.g.
manage the requests, e.g. abort a request.
abort() the request.
WapServer Provides services to register A servlet author who wants
and locate server extension to register a server
interfaces. extension interface to make
it known by the Nokia WAP
Server or wants to locate an
implementation of a server
extension.

Interface Description Used by

AckListener Provides detailed A WAP service that needs to
information about the know if the response is
status of a response created really delivered or not. This
by the servlet. E.g. could be used e.g. for billing
successful delivery to the purposes. The AckListener
terminal. implemented by a servlet is
registered to the Nokia WAP
Server using the WAPServer
interface during the
servlet.init()
procedure.
ShortMessaging Provides functions for A WAP service that wants to
sending textual and binary notify the user with SMS or
non-WAP short messages send binary messages to the
(SMS) with the Nokia WAP terminal, e.g. ringing tones.
Server bearers.
HttpManager Provides HTTP protocol A WAP developer needing to
functionality for HTTP client make an HTTP service
including caching. request to an origin server.
AlarmManager Provides access to the Nokia A WAP service that wants to
WAP Server alarm get and acknowledge
information. Via this alarms. This interface is
interface, a servlet can get commonly used together
the active alarms in the with the AlarmHandler
system and acknowledge extension.
them.
BearerManager Provides information about A WAP service that needs to
available bearers. select the bearer for e.g.
push purposes.
UserDirectory Provides information about A WAP service that needs
the Nokia WAP Server users, user identification or other
user groups and details user information.
about individual users.
New interfaces may be added in the future releases of the Nokia WAP Server. For a
detailed description of the above mentioned interfaces, see the enclosed Nokia WAP
Server API Reference.

4.3 Server Extension API

The Nokia WAP Server provides an open architecture for WAP development. The Server
Extension API is a group of interfaces defined by the Nokia WAP Server that are used
by the Nokia WAP Server itself or by servlets. A servlet may provide an implementation
of one of the defined interfaces and thus customize the server operation to meet
specific needs.
All server extensions must provide the Servlet interface. It is used to load, initialize
and destroy the servlet instance. Servlets providing an implementation of some
interface in the Server Extension API may provide an empty service() method in
the Java Servlet API, because the servlet does not provide any direct service for
requests and thus the service() method is never called. A URL mapping to the
servlet does not need to exist.
For example, if a developer implements a more advanced access log writing
functionality that integrates the Nokia WAP Server logging into an existing billing
system, the developer will:
1 Implement a servlet that provides the Servlet interface and

AccessLogWriter interface.
2 In a servlet.init()call made by the Nokia WAP Server, register the exposed

AccessLogWriter interface to the Nokia WAP Server via the
com.nokia.wap.server.WapServer interface by using the
registerExtensionService() method.
3 When an event to be written to the access log occurs inside the Nokia WAP Server,
the logAccess() method of the registered interface is called and the server
extension has all the information there is in the access log entry.
4 The Nokia WAP Server never calls the service() method of the servlet if there
is no URL mapping defined for the servlet.
If a servlet wants to use a server extension, the
com.nokia.wap.server.WapServer interface provides methods for locating
an implementation.
For each interface, it is defined whether there can be several registered
implementations.
The following interfaces have been defined for the Nokia WAP Server 1.0 release:

Interface Purpose
AccessLogWriter Provides a customized log writer for access
information. Can be used to e.g. collect
billing information.
AlarmHandler Enables an extension to receive and handle
alarms generated in the Nokia WAP Server.
Using this interface, a WAP Server
extension can integrate to existing alarm
management software.
For a detailed description of the interfaces, see the enclosed Nokia WAP Server API
reference.
4.3.1 Server extension sample

The following sample illustrates how integration with existing billing information
system can be implemented. The sample code shows how to create a server extension
that implements the AccessLogWriter interface and maintains a persistent
connection to a billing system. As discussed later [see 5.1], a servlet can initialise
persistent connections during the initialisation of the servlet.
import com.nokia.wap.server.*;
import com.bcomp.billing.*;
public class WapService extends GenericServlet,

implements com.nokia.wap.server.extension.AccessLogWriter {
// My connection to on-line billing system

BillingOnLine billSystem;
public void init(ServletConfig config) throws

ServletException
{
// create and open connection to actual system
billSystem = new
BillingOnLine(config.getInitParameter("SysName"));
billSystem.loginAsRecordCreator(config.getInitParameter("BFo
rmat"));
// Get WAPServer interface

ServletContext myCntx = config.getServletContext();
WapServer iServ=(WapServer)myCntx.getAttribute
("com.nokia.wap.server.WapServer");
// Register myself as AccessLogWriter

iServ.registerExtensionService(
"com.nokia.wap.server.extension.AccessLogWriter", this);
}
// AccessLogWriter methods

public void LogAccess(AccessLogEntry entry)
{
if (entry.getWspStatusCode() == 0x20)
{
Brecord
br=billSystem.createRecord(entry.getUserid());
br.setSelector(GetServiceName(entry.getRequestedUrl()));
billSystem.commit(br);
}
}
String GetServiceName(URL url)

{ return …; }
}


5 Servlets in the Nokia WAP
Server
This chapter gives a more technical description of the dynamics of a servlet in the
Nokia WAP Server.
5.1 The life cycle of a servlet

Servlets are loaded dynamically by the Nokia WAP Server. The loading is done using the
normal Java class loading and initialisation facilities. The Nokia WAP Server loads the
servlet when the server starts or when the servlet is installed.
WAP Request :
method, URL,
headers, request data WAP Response :
status, response data,
response headers
Nokia WAP Server init()
service()
Servlet
destroy()
After the loading, the following three main methods are involved in the life cycle of the
servlet:
Servlets are activated by the Nokia WAP Server through an init() call. Servlets are
likely to provide their own implementation of this method to perform the possibly slow
and costly initialization of the servlet only once, rather than once per request. With the
init() call, the servlet receives the configuration information
(ServletConfig). The Nokia WAP Server provides a user interface for editing and
maintaining these configuration settings.

After the initialization, the servlets handle many requests. Each terminal request
generates one service() method call. These requests can be concurrent.
The request processing goes on until the Nokia WAP Server explicitly shuts down the
servlet by calling the destroy() method.
The Nokia WAP Server provides a "reload servlet" functionality for the administrator.
The servlets see this as a destroy() call for the current servlet instance, followed by
the creation of a new instance and an init() call for it. If the configuration of the
servlet is changed, the updated configuration is provided in the init() call for the
new instance.
5.2 Security
The Nokia WAP Server is responsible for an end-to-end security solution for the
servlets. The Nokia WAP Server takes care of all the security issues and a servlet does
not have to implement anything in order to be accessed securely. This chapter describes
how a servlet can know the level of security and the authentication method that the
Nokia WAP Server has used to identify the servlet user.
The Nokia WAP Server also has access control features that are not visible to the
servlets. These features contain URL based access control and terminal access control.
Terminal access control means that the Nokia WAP Server can be accessed only with
defined terminals. For a detailed description of the Nokia WAP Server security and
access control features, see the Nokia WAP Server product information.
5.2.1 WAP security protocol (WTLS)

The Nokia WAP Server supports the WAP security protocol, which provides the
following security features:
■ Content encryption
■ Content integrity
■ Server authentication using certificates
The level of security varies depending on the algorithms used. The algorithms are
selected by the Nokia WAP Server administrator. With the
WapRequest.getSecureClass() method, a servlet can query the security class
that is used by the WTLS security. If the WTLS protocol is not used at all, the method
also returns the information about that. Nokia WAP Server administrator selects the
server certificates to be used.
Note:
A WAP service author has no way of influencing when WTLS is used and when it is not
used. The terminal decides when to use WTLS : it might use it always or it may have a
user option for that. Also, an HTTPS scheme in the WML deck has no influence on
whether WTLS is used or not. It is up to the Nokia WAP Server or the servlet to allow or

Servlets in the Nokia WAP Server 25
disallow communication to origin servers or to a local application when WTLS is not

used.
You should also note that as the Nokia WAP Server 1.0 does not support HTTPS to the
origin server, the HTTPS requests are not served at all.
In case high security is needed, the most important thing is to have WTLS security
between the WAP terminal and the Nokia WAP Server hosted by the trusted party (the
company itself). Then the connection from the Nokia WAP Server to the origin server
within the trusted domain can be implemented over plain HTTP.
5.2.2 Nokia WAP Server user authentication

The Nokia WAP Server applies user authentication if so requested by the Nokia WAP
Server administrator. The user authentication can be applied with OR without using the
WTLS protocol. The user authentication can be done in the following ways:
■ Using the HTTP proxy authentication protocol [4]. The Nokia WAP Server user
database contains the users and their passwords. The Nokia WAP Server uses the
Basic authentication scheme for the proxy authentication.
■ Using terminal address information. For each user, the administrator can define a
set of terminal addresses (MSISDN numbers), which can be marked as "trusted"
MSISDN numbers.
Servlets have access to the authentication information, which contains the following
items: who the authenticated user is and how the authentication was done.
WapRequest.getAuthenticationType() returns which of the above
mentioned authentication types was used. If the authentication is not done, user
information is not available with the other functions.
WapRequest.getUserId() provides the Nokia WAP Server specific ID of the

authenticated user. The ID can be used to access information via the
UserDirectory interface.
WapRequest.getUserName() provides the Nokia WAP Server username of

the authenticated user if it is available.
HttpServletRequest.getRemoteUser() provides the user's Nokia WAP

Server username only if the user has been authenticated with proxy authentication.
HttpServletRequest.getAuthType() returns the proxy authentication

scheme that was used for the authentication.
When the WTLS protocol is used, HTTP proxy authentication is a very reliable way of
authenticating users.
If a servlet requires separate user authentication, it may use the HTTP authentication
for its own purposes. For details, see [4].

5.3 Session tracking

It is often necessary to keep track of how a user navigates in a WAP service and what
kind of interrelated actions the user performs within one WAP session (e.g. what items
are collected into a shopping cart). Thus, the WAP application has to be able perform
session tracking. There are several alternatives for implementing session tracking with
the Nokia WAP Server.
All the options below are possible for implementing session tracking, and there is no
single right way to implement session tracking in WAP applications. The best practice
should be selected case by case, depending on the application type (e.g. the amount of
information that is tracked during the session).
5.3.1 Services for session tracking via the HttpSession

interface
The standard Java Servlet API defines the HttpSession interface, which enables
session management. For details of the use of the HttpSession interface, see [1].
Note: URL rewriting is implemented in the Nokia WAP Server API as defined in the Java
Servlet API, but instead of cookies, the Nokia WAP Server implementation uses WSP
session IDs for session identifying. However, also note the following remarks and other
optional ways for implementing session tracking.

WSP Session ID The Nokia WAP Server creates a unique

session ID for each WSP session. The WSP
session is created only in the connection
oriented mode and you should note that e.g.
Nokia 7110 creates a new WSP session for
each CSD call. For additional information on
the WSP protocol, see [3]
The session ID can be retrieved also for

application session handling purposes via
the WapRequest interface by using the
getWapSessionId() method.
Note: the WSP session IDs are the same for

all the servlets. Thus, several servlets can
utilise the IDs created by the Nokia WAP
Server.
5.3.2 WML code

WML variables retain their values between requests and thus are a nice way to
implement session tracking. WML code generated e.g. by servlets (or some script on the
origin server) can thus include the necessary session information in the form of
variables. For further information, see e.g. the WML Reference document included in
the Nokia WAP Toolkit.

5.3.3 Other optional ways to implement session tracking

WTLS Session ID The Nokia WAP Server creates a unique ID
for each WTLS session. This ID remains the
same for subsequential WTLS connections,
depending on the terminal implementation
(in the case of Nokia 7110, the ID remains
the same). The session ID can be retrieved
for application session tracking purposes via
the WapRequest interface by using the
getWtlsConnectionId() method.
Note: WTLS session IDs are the same for all

the servlets. Thus, several servlets can utilise
the IDs created by the Nokia WAP Server.
Cookies Cookies can be used e.g. by the origin server

to handle sessions in the WAP application.
In that case, the Nokia WAP Server will pass
the cookies from the origin server to the
terminal and vice versa.
However, it is important to notice that

not all WAP terminals (such as Nokia
7110) support cookies and thus the use
of this option should be considered very
carefully.
5.4 Error handling

Like all programming, WAP programming must also handle errors. In WAP servlet
programming, errors can occur in various phases of the processing. This section
outlines the error types, defines the Nokia WAP Server behaviour in these situations
and suggests how the servlets should handle errors.
■ Service error. The servlet detects that there is an error, and the requested service
can not be provided to the terminal user. E.g. there is insufficient input for the
service or a broken database connection.
■ Servlet error. The servlet works incorrectly, e.g. creates an invalid WML page,
provides content type that is not supported by the terminal, provides content too
large for the terminal, or the servlet goes into an infinite loop.
■ Nokia WAP Server error. The WAP Server fails to convert, encode or deliver the
given content.

■ WAP Protocol error. Delivering the data fails due to networking problems,
terminal out of battery power, failed security, etc.
5.4.1 Service errors

Service errors are handled in WAP as they are handled in HTTP. A servlet should use
either HttpServletResponse.sendError(code, msg) with the
appropriate HTTP status code. If msg is provided, it is sent in a WML page to the
terminal. The code is one of the SC_* error status codes defined in the
HttpServletResponse. The servlet should use an error code from the 400 range
of HTTP error codes.
The servlet can also decide to report a service error with an SC_OK status and provide
a WML page describing the problem.
5.4.2 Servlet errors

These errors are detected by the Nokia WAP Server. The request is responded with an
HTTP status code from the 500 range, and the servlet is provided the information via
the AckListener interface if it has been registered.
If the servlet uses too much time for the service() call, the Nokia WAP Server will
terminate the request processing, unload the servlet and then reload and initialize it
again. The interrupted request is returned to the terminal with an
SC_GATEWAY_TIMEOUT status.
The servlet can throw a ServletException or IOException when service() is called.
If the ServletException is thrown, the Nokia WAP Server sets the status of the response
to SC_SERVICE_UNAVAILABLE. The AckListener interface is not called for
service() calls that have thrown an exception.
5.4.3 Nokia WAP Server errors

If the Nokia WAP Server fails to convert, encode or deliver the given content, the
request is responded to with an HTTP status code from the 500 range, and the servlet is
provided with the information via the AckListener interface.
5.4.4 WAP protocol error

If the delivery of the content fails at the protocol level (timeout, communication error),
the servlet will be informed in case it has registered an AckListener interface. This
applies to requests made using the connection-oriented WSP protocol. When the
connectionless WSP protocol is used, these errors are never delivered to the servlet.

5.5 Performance
A Nokia WAP Server servlet is a fast way to provide a response to a request. This is
because servlets run in the same process context as the Nokia WAP Server. Activating a
servlet requires only a lightweight thread context switch for the Nokia WAP Server. On
the other hand, the WAP protocol processing, content encoding and other Nokia WAP
Server functionality require processor time. Thus, WAP services requiring a lot of
processing power should be placed on another machine if the number of requests is
great. For that kind of services, servlets are more like WAP connectors than standalone
WAP applications.
5.5.1 Threading
Servlets run in the same process as the Nokia WAP Server. When several clients try to
use the servlet simultaneously, the service() method is called by several threads
concurrently. The servlet should itself protect class specific data and other necessary
resources from concurrent access.
If the servlet is not prepared for concurrent use, it should implement the
SingleThreadModel interface. This ensures that the Nokia WAP Server will call
the service() method of the servlet only from one single thread.
5.6 Servlets working together

A servlet can be in various roles in a complete WAP service. As discussed earlier, a
servlet might perform preprocessing of WAP terminals' requests that will be forwarded
either to another servlet or to an origin server. Alternatively, a servlet might perform
postprocessing of data returned by an origin server or another servlet in the Nokia WAP
Server. Thus, servlets could serve e.g. the following practical purposes:
■ A servlet might preprocess the WAP terminal's request in order to check e.g. the
security class of the request before the request is forwarded to any other servlet or
origin server.
■ A servlet might incorporate some information (such as MSISDN number or type of
connection) from the WAP Service API's interfaces to the HTTP request that will be
forwarded to the origin server.
■ A servlet might filter the origin server's response based on specific rules (e.g.to
optimise the content for a specific terminal)
■ A servlet might monitor the service and register the AckListerner interface in
order to verify the delivery of the response (for creating accurate billing
information or for ensuring some specific business logic).
Depending on the application's needs, various techniques can be used to link servlets
to work together or to perform above type of filtering for terminals' requests or origin
servers' responses:

■ Servlet chaining. The Nokia WAP Server supports servlet chaining, which is an
easy way to link several servlets to process a WAP terminal's request.
■ MIME type mapping. The Nokia WAP Server supports mapping of MIME types to
specific servlets to perform postprocessing of predefined content types returned by
e.g. another servlet or origin server.
■ Locating other servlets via ServletContext. Servlets can locate other servlets via
Java Servlet API's ServletContext to perform specific tasks.
■ Locating server extensions. Finally, servlets can utilise server extensions, which
are servlets implemented by the developer to enhance the Nokia WAP Server's
functionality to serve specific needs.
The following sections describe the techniques in further detail.
5.6.1 Servlet chaining

The Nokia WAP Server supports servlet chaining, which provides an easy means for
passing the output of one servlet to another servlet as input. The output of the last
servlet in the chain is sent back to the terminal as a response to the terminal's request.
As illustrated in the picture below, a servlet chain might include pre-processing of the
requests, fetching information from the origin server and post-processing of the origin
server's response. All of the servlets in the chain can be mapped to a single URL.

Nokia WAP Server
ServletRequest
Application server
Preprocessor
HTTP request
Connector
HTTP response
ServletResponse
Postprocessor
Servlet chaining: an output from one servlet is passed as input to

another servlet.
The Nokia WAP Server 1.0 does not provide an administration interface for configuring
servlet chains, but you can easily configure them by editing the configuration files
located in the [installation directory]\config directory.
Configuration file Description

Servlets.config Defines the loaded servlets and their
initialization parameters. All these
definitions can be configured from the
Nokia WAP Server Manager. Thus, editing
this file is not recommended as the servlets
can be created and configured via the Nokia
WAP Server Manager.
UrlMappings.config Defines the URLs mapped to servlets and
servlet chains. Note: URL mappings to a
single servlet can be configured from the
Nokia WAP Server Manager, but file editing
is needed for the servlet chaining.
NOTE: The Nokia WAP Server MUST NOT be running when editing the configuration
files. You must shut down the Nokia WAP Server before you edit the configuration
files and you must restart it after you have configured all the configuration files.

Mapping URLs to servlet chains by editing the UrlMappings.config file

The following syntax can be used for mapping URLs to servlets or servlet chains.
However, mapping URLs to a single servlet can be done via the Nokia WAP Server
Manager, the management user interface of the Nokia WAP Server, and thus editing
the file is needed only when mapping URLs for servlet chains.
Syntax:
urlmap.total=[total number of the url mappings]
urlmap.[number].name=[servlet name]
urlmap.[number].url=[url mapping]
Example:
urlmap.total=4
urlmap.1.name=FileServlet
urlmap.1.url=http\://yourdomain/file/
urlmap.2.name=HelloWorld
urlmap.2.url=http\://yourdomain/helloworld/
urlmap.3.name=FilterSample,HeaderSample
urlmap.3.url=http\://yourdomain/myfirstchain/
urlmap.4.name=HTTPManager
urlmap.4.url=http\://
5.6.2 Mapping servlets to handle specific MIME types

A servlet can be mapped to handle particular MIME types returned by another servlet
or an origin server. A typical example of the use of the MIME type mapping is e.g.
conversion of text/html to wml so that the response that is of the text/html MIME type
is automatically directed to a servlet that converts the content to wml. The same
approach can also be used for e.g. converting various image formats to the wbmp
format by using appropriate image converters.

Defining mappings for MIME types by editing the

MimeTypeMappings.config file
Mapping specific MIME types to an appropriate filter (servlet) can be done by editing
the MimeTypeMappings.config file in the [installation
directory]\config directory.
Configuration file Description

MimeTypeMappings.config Defines the MIME types mapped to
appropriate servlets. In the Nokia WAP
Server 1.0 release, MIME types can be
configured only by editing this file (not via
the management user interface). The
following syntax must be used.
Syntax:
mimetypemap.total=[total number of the filter mappings]
mimetypemap.[number].filter=[filter name]
mimetypemap.[number].mimeType=[mime type]
Example:
mimetypemap.total=1
mimetypemap.1.filter=jsp
mimetypemap.1.mimeType=java-internal/java-html
NOTE: The Nokia WAP Server MUST NOT be running when you are editing the
configuration files. You must shut down the Nokia WAP Server before you edit
configuration files and restart it after all the configuration files are configured.
5.6.3 Locating other servlets and server extensions

Servlet chaining and content filtering are not the only ways to make several servlets to
interact with each other. A servlet migh want to utilise other servlets installed into the
Nokia WAP Server e.g. in the following ways:

Locating servlets via ServletContext One way to locate other servlets is to use the
ServletContext services in the Java
Servlet API. Once you have the servlet interface
of another servlet, the service method of
the located servlet can be called.
Locating server extensions A servlet might want to use a server extension

that provides an implementation of some
interfaces defined in the Server Extension API. In
that case, the servlet can locate the desired
extensions by using the QueryInterface
and getProviders methods in the
com.nokia.wap.server.WapServer
interface.
5.7 Pre-installed servlets

There are some servlets pre-installed on the Nokia WAP Server. These include:
HTTPManager A servlet that provides connectivity to

origin servers via HTTP. The servlet is an
integrated part of the Nokia WAP Server
and can not be removed. The servlet can be
used by other servlets that need to request
information from the origin servers via
HTTP. The HTTPManager can be used e.g. in
the servlet chain.
FileServlet A servlet that provides access to files saved

locally to the [installation
directory]\wap_root directory. The
servlet must be configured for various
content types. See the Nokia WAP Server
Administration Guide for further
information on the use of the FileServlet.
The FileServlet and HTTPServlet are features of the official Nokia WAP Server 1.0
product. In addition to these servlets, there also are some samples with source code
that are included in the product package to help developers to learn to write Java
Servlets. These samples include e.g.:

HelloWorld The HelloWorld is a simple example of how

to write Java Servlets. The servlet is also
included in this document.
AckListenerSample The sample illustrates how the

AckListener interface can be used to
verify the delivery of the response. Also, the
sample illustrates one of the ways of
implementing session handling with the
Nokia WAP Server.
WapRequestSample The sample illustrates how to obtain WAP-

specific information from the
WapRequest interface.
WMLTool The WMLTool sample illustrates how writing

servlets to generate WML can be simplified
by creating appropriate utilities.
The related WMLToolSample illustrates the

use of the WMLTool utility. See also the
JavaDoc reference documentation in
[installation directory]\docs
for the details of the WMLTool sample.
HeaderSample The HeaderSample can be used to echo the

HTTP headers back to the WAP terminal.
This sample can be used e.g. together with
the FilterSample. A simple servlet chain can
be implemented according to the servlet
chain configuration instructions in this
document so that the FilterSample adds
some information to the HTTP headers and
the HeaderSample prints the headers back
to the terminal.
FilterSample The FilterSample illustrates how

information, such as WAP–specific
information from the WAP Service API, can
be added to HTTP headers that are then
received by another servlet in a servlet
chain or an origin server.
Note that the samples that are located in the [installation

directory]\servlets\samples directory have to be configured with the
package name (samples.servletname).

Note that the above samples are provided for learning purposes only. Samples, such as
the WMLTool, can be further developed to meet specific needs, but no official support
or maintenance is provided for the samples.
5.8 WAP MIME types

WAP defines its own MIME types for WAP-specific content types. Typically, a WAP
terminal can accept the following MIME types:
application/vnd.wap.wmlc Encoded WML
application/vnd.wap.wmlscriptc Encoded WMLScript
image/vnd.wap.wbmp WAP graphics format
Note that all WAP terminals may not support WMLScripts or bitmaps. In addition to
these, some more specialised content types can be accepted:
application/vnd.wap.wtls-ca-certificate Certificate Authors WTLS

format certificate
When a request comes to the Nokia WAP Server, it adds some accepted content types
to the request before forwarding it to the servlet. The following content types are
added:

MIME type Description
text/vnd.wap.wml Textual WML. If the servlet sets the

content-type to this type, the Nokia WAP
Server automatically encodes the given
WML page before it is sent to terminal.
text/vnd.wap.wmlscript Textual WMLScript. If a servlet sets the

content-type to this, the Nokia WAP Server
automatically compiles and encodes it
before sending it to the terminal.
text/html Textual html. If a servlet is willing to return

HTML, the Nokia WAP Server will convert it
to WML and encode it before sending it to
the terminal.
In addition to these, the MIME types defined in the MIME type mapping (see 5.6.2) are
added to the request's accept header.
Terminals may accept multipart content types. If a servlet replies with a multipart
response containing e.g. textual wml and textual wmlscript, the Nokia WAP Server can
correctly encode the individual subparts with the appropriate encoder.
Note that the WAP protocols and the Nokia WAP Server can be used to deliver any
content type to the WAP terminal. So, the Nokia WAP Server's content delivering
ability is not limited to WAP content types.

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.0, 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.
Terminal Server
Invoke
1
Result
2
Ack
3
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

Using javax.servlet.http interfaces with WAP protocol 41
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.WapServer interface 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.

Programmers Guide

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Programmers Guide

Uploaded by

Copyright:

Available Formats

Programmer's Guide

Nokia WAP Server API 1.0

Copyright © Nokia Corporation 1999. All Rights Reserved.

2 Overview of Java Servlets for the Nokia WAP Server........ 5

3 Servlet samples ..................................................................... 11

4 Features in the Nokia WAP Server API.............................. 15

5 Servlets in the Nokia WAP Server...................................... 23

Nokia WAP Server API 1.0

5.4 Error handling ..........................................................................................28

6 Using javax.servlet.http interfaces with WAP protocol ... 39

Nokia WAP Server API 1.0

1.1 Overview of the WAP architecture

Nokia WAP Server API 1.0

1.2 Nokia WAP Server

1.2.1 Purpose and scope

Nokia WAP Server API 1.0

WPS Wireless Protocol Stack

WSP Wireless Session Protocol. The session layer in WPS.

WTP Wireless Transaction Protocol. The transaction layer in WPS.

WTLS Wireless Transport Layer Security. The security layer in WPS.

MSISDN Mobile subscriber ISDN. (Telephone number or address of

Nokia WAP Server API 1.0

Nokia WAP Server API 1.0

2.1 Motivation for server side programming with Java

Nokia WAP Server API 1.0

2.2 Servlet architecture overview

WAP Request (URL),

Java Servlet interface

WAP Architecture terminology

The architecture has three major parts:

Nokia WAP Server API 1.0

2.3 What a servlet is for the Nokia WAP Server

Nokia WAP Server API 1.0

■ No additional HTTP communication is required from the Nokia WAP Server to an

2.5 Installing a servlet for the Nokia WAP Server

Nokia WAP Server API 1.0

Nokia WAP Server API 1.0

2.6 Tools for the Nokia WAP Server service development

The Nokia WAP Toolkit is available at http://www.forum.nokia.com, the Nokia WAP

Nokia WAP Server API 1.0

3.1 HelloWorld sample

public class HelloWorld extends HttpServlet

// the initialization parameter is read during

public void init(ServletConfig config) throws

public void doGet(HttpServletRequest request,

Nokia WAP Server API 1.0

// Remember to close the out object

public String getServletInfo()

3.2 Connector sample

public class WapService extends HttpServlet

public void init(ServletConfig config)

public void doGet(HttpServletRequest req,

Nokia WAP Server API 1.0

// Create the response by using the WMLTool sample

WMLTool.Deck deck = new WMLTool.Deck(

Nokia WAP Server API 1.0

Nokia WAP Server API 1.0

Java Servlet API Basic

Nokia WAP Server Servlet WAP

Server Extension API

Nokia WAP Server API 1.0

4.1 Java Servlet API

Defined in the javax.servlet.http package: