This document demonstrates how to provide WAP access into...

BuildingWAP-enabledapplications withJBuilder 5Adding WAP clients as an additionalpresentation layer into enterpriseapplications.

by Giles Davies, Borland UK

IntroductionThis document demonstrates how to provide WAP access into

an enterprise application, in this case using EJB in the business

logic layer.

The intent is to demonstrate how WAP clients can be developed

with JBuilder to provide another client presentation layer into

existing or new enterprise applications.

Table of ContentsIntroduction 1

Summary 2

WAP Overview 3

The WAP Application 4

Resources 12

Appendix 15

JBuilder™

2

Glossary

Acronym DescriptionDTD Document Type Definition

EJB Enterprise JavaBean

HTML Hyper Text Markup Language

HTTP Hyper Text Transfer Protocol

BAS Borland Application Server

IP Internet Protocol

JSP Java Server Page

JWS Java Web Server

MIME Multi-Purpose Internet Mail Extensions

SSL Secure Socket Layer

TCP Transmission Control Protocol

UDP User Datagram Protocol

URL Uniform Resource Locator

WAP Wireless Application Protocol

WML Wireless Markup Language

WSP Wireless Session Protocol

WTLS Wireless Transport Layer Security

WTP Wireless Transport Protocol

XML eXtended Markup Language

Summary

It is projected that by the end of 2002 there will be as many

people accessing the Internet via handheld devices as there are

people accessing the Internet via desktop computers. Beyond

2002, the numbers of people accessing the Internet via handheld

devices will increase dramatically and start to place desktop

access into the minority. For many people, their first, and

perhaps only, meaningful interaction with the Internet may be

via handheld devices, such as mobile phones, PDAs, or their

successors.

WAP is therefore going to be an increasingly important means

of delivering services to end users. Developers, architects, and

business managers need to enable WAP access into their

enterprise applications in order to compete effectively.

WAP presents several opportunities:

• A new channel for existing services.

• The scope for an entirely new set of services that capitalize

on the mobile paradigm.

• Access to a much larger user base.

This document demonstrates the building of an enterprise

application, based around a national bank, which offers financial

services to its customers via a variety of interfaces, from the

native desktop applications of its employees, through to both

Web and WAP based access.

In the process, it is intended to show that WAP is another

presentation layer, and that a well-designed system, with the

business logic layers separated from the presentation layers, can

incorporate a WAP interface without needing to reengineer the

business logic and in isolation from all other presentation layers.

The WAP client places a number of restrictions on the

developer, primarily concerning the limited display

characteristics of today’s devices, and being aware of these issues

is important in deciding what services can be made available.

This document will briefly overview WAP as a technology,

before walking through writing the example application, using

Java servlets built using Borland JBuilder 4.

JBuilder™

3

WAP Overview

What is WAP?WAP is the Wireless Application Protocol. It is an open

standard designed to allow users of mobile/handheld devices to

access the Internet as easily as they can make telephone calls,

send SMS messages, and so on.

There are limitations with the current range of WAP devices, as

we shall see later, that mean that accessing the Internet via a

WAP device is a different experience to accessing the Internet

via a traditional Web browser on a desktop computer.

Nevertheless, there are great possibilities for accessing

services via WAP.

Who’s behind WAP?WAP is the product of the WAP Forum (www.wapforum.org),

an association founded in 1997 by Ericsson, Motorola, Nokia,

and Phone.com (formerly Unwired Planet). The WAP Forum

now has more than 200 members and represents over 95% of

the global handset market.

The primary goal of the WAP Forum is “to bring together

companies from all segments of the wireless industry value chain

to ensure product interoperability and growth of the wireless

market.”

WAP ArchitectureWAP consists of a number of protocols, which are analogous to

the protocols required by “normal” HTTP Web communication.

Layer WAP Web

Application Layer Wireless

Application

Environment

(WML and

WMLScript)

HTML, Scripting

languages

Transport Layer WSP, WTP, WTLS

and WDP

HTTP, SSL, TCP,

UDP

Network Layer Bearer IP

In addition to these protocols there are some more elements

required by WAP, including:

• A microbrowser. Used by the WAP device to render the

WML and/or WMLScript to the user.

• A WAP Gateway. This can provide integration and routing

facilities.

When a WAP device is used, the user enters a URL into the

device’s microbrowser by either using a bookmark or typing the

URL, as with Web browsers. This URL may be routed via a

WAP Gateway, which can then either return WML from the

target URL or, if appropriate, pass HTML through an HTML

filter to return WML to the WAP device.

Fig 2. High level overview of WAP communication.

HTML

Filter

URL URL

WML

(Compiled)

WMLHTML

WAP

Gateway

Target HostWAP Device

JBuilder™

4

A frequently asked question is whether a WAP Gateway is

necessary. A WAP Gateway essentially allows full integration

into a Service Provider’s facilities, which could include:

• Personalization services, such as online customization of the

user’s bookmarks, which are then updated on the WAP

device.

• Integration into enterprise services such as email or security.

It is not therefore a requirement that a WAP Gateway is used, as

WML can be accessed from the WAP device directly from a

normal Web server. Note that it may be necessary to set up the

WAP MIME types in the Web server, which will be covered

later in this document.

WMLThe Wireless Markup Language is XML based, being defined in

an XML DTD. For example, the DTD for WML 1.1 is

http://www.wapforum.org/DTD/wml_1.1.xml. WML supports

text, images, user input, option lists, hyperlink navigation, and

unicode.

The good news is that WML is very like HTML. Many of the

tags are the same, and familiarity with HTML enables fast takeup

of WML.

The bad news is that WML is very like HTML–similar enough to

be familiar, but with sufficient differences to be initially

frustrating! For example, all tags must be completed, something

that is less strictly enforced in HTML. Similarly, all tags must be

in lower case, rather than in the mixture of cases that HTML

permits.

WML also has some more fundamental structural differences to

HTML, reflecting the different environment that the

microbrowsers operate in; namely that a WAP device’s screen is

small and typically monochrome. Take these differences in

conjunction with a download capability of 9600 kbps, and the

solution WML provides is that of a deck of cards. The basic

concept is that a number of screens worth of data (the cards) are

downloaded together in one file (the deck). This helps overcome

issues of network latency that might otherwise impose relatively

lengthy delays for each small screen’s worth of WML.

Navigation between cards and decks is achieved using <href>

hyperlinks, as with HTML. As well as having the cards, it is also

possible to provide a template in the deck, which can be used to

provide one or more options on every card. A typical example is

to provide a “back” option so that the user can return to the

previous screen.

Fig 3. WML’s deck of cards.

The WAP application

ObjectivesThis sample application is designed to:

1. Illustrate WAP functionality.

2. Demonstrate how WAP clients can access enterprise

services.

3. Demonstrate that WAP clients can be added as “just”

another presentation layer into applications.

CardCard

CardTemplate

Card

CardCard

JBuilder™

5

ScenarioThis example is intended to build upon the currency conversion

application detailed in the Getting Started Guide, “Creating Your

First Enterprise JavaBean Stateless Session Bean.” This white

paper can be found on the Borland community site at

http://community.borland.com.

The scenario is that, following the success of the Currency

Converter application, a WAP presentation layer needs to be

added in order to allow users to access the business logic on the

move. This should involve no reengineering of the business logic

in order to keep time to market and costs down.

SolutionThe solution to this scenario that this paper will follow is to

develop a WML form that allows the user to input the currency

amount to be converted, which in turn delegates the conversion

calculation to the CurrencyConverter Session Bean.

The project will consist of:

1. A WML file providing the input form.

2. A servlet that is called by the WML form and obtains a

reference to the EJB.

PreparationEnsure that you have the Currency Convertor Stateless Session

Bean deployed into Borland AppServer, as described in the

above white paper.

It would be quite usual for the presentation layer(s) to be written

by a separate team of developers than those who wrote the

business logic. In order to simulate this, the WAP client will be

in a new project. It will therefore be necessary to create a project

library so that the EJB source code is not required in the WAP

project. The first step is therefore to generate a client jar from

the AppServer.

Start Borland AppServer and the AppServer Console. In the

console, right-click on the CurrencyConverter JAR file and select

“Generate Client JAR”.

The Wizard will step you through creating the client JAR for the

EJB:

Generate a single JAR file and select a suitable location for the

library.

JBuilder™

6

Select Finish to complete the wizard

Start the new projectNow that all the preparation is complete, the new WAP project

can be started. Start JBuilder, and select File | New Project.

Change the project name to WAPClient.

In the next step of the project wizard, ensure that the Borland

AppServer library is included (as the WAP client will include an

EJB client).

Select Finish or, optionally, Next and then complete the project

description details for the project.

Configuring Project LibrariesNext, the EJB client JAR needs to be added as a project library.

Select Tools | Configure Libraries, and then New from the

Configure Libraries Dialog. Give the new library a name, such as

CurrencyConverterLibrary, and add the JAR file generated

earlier to the library.

Next, add the newly created library into the current project.

Select Project | Project Properties and in the Required Libraries

tab, add in the CurrentConverterLibrary.

JBuilder™

7

Write the WML servletThe first step is to run the servlet wizard from the JBuilder

Object Gallery.

In the servlet wizard:

• Specify the package as wapclient.

• Give the servlet the class name of ConverterServlet.

On the next screen of the servlet wizard:

• Select WML as the content type

• Uncheck the doGet() and check the doPost() service

methods.

Select Finish to complete the Wizard, and the ConverterServlet

framework is ready for our code to be inserted.

Notice that the Wizard has added the correct MIME type and

XML DTD for WML, as well as providing a simple WML deck

with one card in the service method.

The CurrencyConverter package that contains the relevant EJB

Home and Remote interfaces needs to be imported. This

JBuilder™

requires that the generated client JAR file has been added as a

project library, as discussed earlier.

N

in

th

a

o

a

In

p

In

a

N

in

th

o

import currencyconverter.*;

ext, the code to locate the EJB is going to be added to the

it() method. Although it’s not necessary to place the lookup in

e init(), the JNDI lookup is a relatively expensive procedure

nd in this instance it can be performed once at the initialization

f the servlet, and a reference to the Home interface can be held

s an instance variable:

the init() method, after the super.init() call, enter tryc and

ress <Ctl>-J to invoke the try-catch clause code template.

the try clause now add the following lines of code to locate

nd reference the Home interface of the EuroConverter EJB:

Before finally turning to the doPost() service method in the

servlet, two utility methods can be added, which will be

responsible for formatting the WML output.

The first method, reportResults, is going to take the doPost()

PrintWriter, the guilders amount, and the euro amount as

arguments and simply format the results into a WML card for

display in the client device’s microbrowser.

}

try {

// Obtain the initial JNDI context

javax.naming.Context initialContext =

new javax.naming.InitialContext();

// Get the object by name from the initial context

Object objref = initialContext.lookup("EuroConverter");

// Narrow the reference for RMI/IIOP

home = (EuroConverterHome)

javax.rmi.PortableRemoteObject.narrow

(objref, EuroConverterHome.class);

}

catch (Exception ex){

}

private EuroConverterHome home = null;

8

ow we are going to add a method that uses the Home

terface, obtained in the init() lookup, to request an instance of

e EuroConverter EJB Object and carry out the conversion

peration:

In

a

D

private float convert(float amount) throws Exception{

float convertedAmount = 0.0f;

// Obtain a reference to the remote interface from the

// home interface

EuroConverter converter = home.create();

// Carry out the conversion from Guilders to Euros

convertedAmount = converter.hfl2euro(amount);

// Let the EJB Container know that we no longer

// require the EJB

converter.remove();

return convertedAmount;

}

private void reportResults(PrintWriter out, float guilders,

float euros)

{

order to form the WML correctly, the XML type and DTD

re declared. The DTD is referenced by the variable

OC_TYPE that the servlet wizard created.

out.println("<?xml version=\"1.0\"?>");

out.println(DOC_TYPE);

JBuilder™

9

The WML document itself can now be started using the <wml>

tag:

Next, the deck of cards needs to be created. The first, but

optional, step here is to include a template section:

The <do> tag allows the association of specific actions with the

command buttons on the WAP device. The above template uses

the <do> tag with the known type of “prev”, which the

microbrowser uses to take the user back to the previous screen.

The label attribute is simply a text string, and is placed above the

relevant button on the device, as shown below:

Now the (single) card in the deck needs to be written. A card is

of the format:

The <card> tag requires a unique id and a display title. The

unique id is used in referencing the card for a link, as we shall

see later. Note that any text to be displayed needs to be enclosed

inside a … tag.

out.println("<card id='results' title='Results'>");

out.println("");

out.println(" " + guilders + " Guilders ");

out.println("is equivalent to ");

out.println(euros + " Euros ");

out.println(" ");

out.println("");

out.println("</card>");

out.println("<wml>");

… (deck of card goes here)

out.println("</wml>");

The second utility method is intended to provide some feedback

to the user should it not be possible to establish a reference to

the EuroConverter EJB. The format of the message is the same

as the reportResults() method:

out.println("<template>");

out.println("<do type='prev' label='Back'>");

out.println("<prev/>");

out.println("</do>");

out.println("</template>");

out.println("<card id='cardid' title='CardTitle'>");

out.println("");

out.println("Some text etc");



W

u

o

private void reportServiceProblem(PrintWriter out){









out.println("<card id='error' title='Service Down'>");

out.println("");

out.println(" Currency conversion is not available at

this time. ");




}

e can now implement the doPost() service method and make

se of these utility methods. First of all, delete all the example

ut.println() statements that the servlet wizard inserted.

JBuilder™

Next, let’s add some basic error checking–if the EuroConverter

Home interface is null, then something went wrong in the init(),

so let’s make use of the reportServiceProblem() method we

wrote earlier and inform the user.

H

n

m

H

T

E

w

m

T

fo

G

WT

m

1

2

T

c

JBuilder 5 and also represents a fairly typical scenario, directly

analogous to HTTP servlets being called from HTML pages.

The first step is to create a new WML file within JBuilder. A new

file of any type can be created in JBuilder by selecting File |

Open File and selecting the path and filename for the new file.

In this case create a file named “input.wml” in the project root

if (home == null){

reportServiceProblem(out);

return;

aving established that the Home interface is not null, we can

ow make use of it. The request.getParameter(“amount”)

ethod extracts the value for the parameter “amount” from the

ttpServletRequest object passed to the doPost() method.

he extracted amount of guilders is then passed to the

uroConverter EJB for conversion, via the convert() method we

rote above, and the result is passed to the reportResults()

ethod for formatting into a WML card:

directory:

The new blank file will now be open in JBuilder. Note that until

the file is saved, it exists only in the buffer, so be sure to save the

file.

As with the WML servlet, the first entry in the WML page is the

XML version and WML DTD:

}

try{

float guilders = new Float

(request.getParameter("amount")).floatValue();

reportResults(out, guilders, convert(guilders));

}

catch (Exception ex){


System.out.println("Exception: "+ex);

}

10

hat’s it for the WML servlet! Now all that’s needed is an input

rm in which to enter and supply the servlet with the amount of

uilders to be converted.

rite the WML input formhere are a few ways in which we can call the doPost() service

ethod on the servlet, with the main options being:

. Another WML servlet

. A WML page

he approach being taken here is to use a WML page as the

alling “client” as this demonstrates writing “straight” WML in

N

A

in

d

W

d

n

<?xml version="1.0"?>

<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD

WML 1.2//EN"

"http://www.wapforum.org/DTD/wml12.dtd">

ext add the WML start and end tags:

<wml>

</wml>

s WML is a recognized file type in JBuilder 5, you will see that

addition to colored syntax highlighting the structure pane also

isplays dynamic error checking. You will see that as you add the

ML tags, the error caused by an absence of a root tag

isappears and the (so far rather limited) WML document can be

avigated via the structure pane.

JBuilder™

The sole card required can now be added:

T

c

p

th

th

T

e

d

re

<

p

<

T

n

ta

n

N

th

b

Testing the ExampleThe first step is to use the integrated TomCat Serlvet and JSP

engine in JBuilder to simply run the ConverterServlet. Simply

right-click on the servlet in the project and select Web Run.

r

<card>

<do type="accept" label="Convert" >

<go method="post"

href="http://localhost:8082/servlet/wapclient.ConverterSe

vlet" >

<postfield name="amount" value="$(amount)" />

</go>

</do>

Guilders: <input type="text" name="amount"

format="*N" /> 

</card>

11

he <do> tag links a button (typically) with a function, so in this

ase there will be a label of “Convert” associated with the

hone’s action button. The type attribute of “accept” indicates

at an action should be accepted, the action being defined in

e following <go> tag.

he <go> tag defines a transfer to a new URL as a result of the

vent defined in the <do> tag. The HTTP transfer method is

efined as post in this instance. We will return to the href value

quired in the next section, testing the example. The

postfield> tag defines a name/value pair where the value is a

laceholder for the actual value, which will be obtained via the

input> tag.

he <input> tag defines the type as a text field, and the variable

ame that the value will be associated with in the <postfield>

g. The format attribute simply specifies that any number of

umeric characters can be entered into the field.

ote that this is a very dull piece of WML–rather than clutter

e WML with cosmetics, such as more text or an image, it has

een left very simple.

TomCat will be started and the servlet will be run; however,

since the servlet is waiting for an HTTP post, the browser will a

warning message–“Unable to open location: Could not connect

to: http://localhost:8082/servlet/wapclient.ConverterServlet”:

This is to be expected and the servlet is now available within the

servlet engine at the URL specified in the address bar of the

JBuilder browser. It is this URL, for example

http://localhost:8082/servlet/wapclient.ConverterServlet, that

needs to be inserted into the href attribute of input.wml.

For the input.wml file the most effective test harness is to use a

WAP emulator. There are several emulators available, the one

JBuilder™

12

being used for this document being the Nokia WAP Toolkit,

which is available from www.forum.nokia.com. The Nokia

emulator is free of charge, but does require that you register.

Another free of charge emulator can be found at

www.phone.com.

Using the Nokia WAP Toolkit:

• Select Go | Load File

• Open the input.wml in the project folder

• Select “Show”

The WML page will then be loaded and the output displayed in

the emulator:

To use the application select Options and Edit Selection. Then

enter the Guilders that you would like converted to Euros:

Select OK, Options, and then Convert:

And there is the final result! We have been able to add an

entirely new presentation layer to existing business logic

deployed as an EJB in Borland AppServer 4.5, without needing

to change (or even view) the business logic.

The entire source code for the WML servlet and the WML page

can be found in the Appendices to this document.

Resources

A summary of the links referred to in this document, as well as

some additional related links:

Borland JBuilder

http://www.borland.com/jbuilder/

Borland AppServer

http://www.borland.com/appserver/

http://www.borland.com/devsupport/appserver/faq/

http://www.borland.com/appserver/papers/

WAP

http://www.wapforum.org

WAP Emulators

http://www.forum.nokia.com/main.html

http://developer.phone.com/

JBuilder™

13

Appendix A

WML Servlet sourcepackage wapclient;

import javax.servlet.*;

import javax.servlet.http.*;

import java.io.*;

import java.util.*;

import currencyconverter.*;

public class ConverterServlet extends HttpServlet

{

private static final String CONTENT_TYPE =

"text/vnd.wap.wml";

private static final String DOC_TYPE = "<!DOCTYPE wml

PUBLIC \"-//WAPFORUM//DTD WML 1.2//EN\"\n" +

" \"http://www.wapforum.org/DTD/wml12.dtd\">";

private EuroConverterHome home = null;

/**Initialize global variables*/

public void init(ServletConfig config) throws ServletException

{

super.init(config);

try

{

// Obtain the initial JNDI context

javax.naming.Context initialContext = new

javax.naming.InitialContext();

// Get the object by name from the initial context

Object objref = initialContext.lookup("EuroConverter");

// Narrow the reference for RMI/IIOP

home = (EuroConverterHome)

javax.rmi.PortableRemoteObject.narrow(objref,

EuroConverterHome.class);

}

catch (Exception ex)

{

}

}

/**Process the HTTP Post request*/

public void doPost(HttpServletRequest request,

HttpServletResponse response) throws ServletException,

IOException

{

response.setContentType(CONTENT_TYPE);

PrintWriter out = response.getWriter();

if (home == null)

{


return;

}

try

{

float guilders = new

Float(request.getParameter("amount")).floatValue();

reportResults(out, guilders, convert(guilders));

}

catch (Exception ex)

{


System.out.println("Exception: "+ex);

}

}

/**Clean up resources*/

public void destroy()

{

}

JBuilder™

14

private float convert(float amount) throws Exception

{

float convertedAmount = 0.0f;

// Obtain a reference to the remote interface from the home

interface

EuroConverter converter = home.create();

// Do stuff

convertedAmount = converter.hfl2euro(amount);

// Tidy up

converter.remove();

return convertedAmount;

}

private void reportServiceProblem(PrintWriter out)

{









out.println("<card id='error' title='Service Down'>");

out.println("");

out.println(" Currency conversion is not available at

this time. ");




}

private void reportResults(PrintWriter out, float guilders, float

euros)

{









out.println("<card id='results' title='Results'>");

out.println("");

out.println(" " + guilders + " Guilders ");

out.println("is equivalent to ");

out.println(euros + " Euros ");

out.println(" ");




}

}

JBuilder™

15

Appendix B

WML Page<?xml version="1.0"?>

<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML

1.2//EN" "http://www.wapforum.org/DTD/wml12.dtd">

<wml>

<card>

<do type="accept" label="Convert" >

<go method="post"

href="http://localhost:8082/servlet/wapclient.ConverterServlet

" >

<postfield name="amount" value="$(amount)" />

</go>

</do>

Guilders: <input type="text" name="amount"

format="*N" /> 

</card>

</wml>

MBCot

100 Enterpr ise WayScotts Va lley, CA 95066-3249www.bor land.com | 831-431-1000

ade in Borland® Copyright © 2001 Borland Software Corporation. All rights reserved. Allorland brand and product names are trademarks or registered trademarks of Borland Softwareorporation in the United States and other countries. Java is a trademark or registered trademarkf Sun Microsystems, Inc. in the U.S. and other countries. CORBA is a trademark or registeredrademark of Object Management Group, Inc. in the U.S. and other countries. 12351

This document demonstrates how to provide WAP access into...

Documents

Transcript of This document demonstrates how to provide WAP access into...