this document demonstrates how to provide wap access into ... applications with jbuilder 5 ... that...
TRANSCRIPT
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 <p>…</p> tag.
out.println("<card id='results' title='Results'>");
out.println("<p>");
out.println("<br/>" + guilders + " Guilders <br/>");
out.println("is equivalent to <br/>");
out.println(euros + " Euros <br/>");
out.println("<br/>");
out.println("</p>");
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("<p>");
out.println("Some text etc");
out.println("</p>");
out.println("</card>");
W
u
o
private void reportServiceProblem(PrintWriter out){
out.println("<?xml version=\"1.0\"?>");
out.println(DOC_TYPE);
out.println("<wml>");
out.println("<template>");
out.println("<do type='prev' label='Back'>");
out.println("<prev/>");
out.println("</do>");
out.println("</template>");
out.println("<card id='error' title='Service Down'>");
out.println("<p>");
out.println("<br/> Currency conversion is not available at
this time.<br/>");
out.println("</p>");
out.println("</card>");
out.println("</wml>");
}
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){
reportServiceProblem(out);
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>
<p>Guilders: <input type="text" name="amount"
format="*N" /> </p>
</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)
{
reportServiceProblem(out);
return;
}
try
{
float guilders = new
Float(request.getParameter("amount")).floatValue();
reportResults(out, guilders, convert(guilders));
}
catch (Exception ex)
{
reportServiceProblem(out);
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("<?xml version=\"1.0\"?>");
out.println(DOC_TYPE);
out.println("<wml>");
out.println("<template>");
out.println("<do type='prev' label='Back'>");
out.println("<prev/>");
out.println("</do>");
out.println("</template>");
out.println("<card id='error' title='Service Down'>");
out.println("<p>");
out.println("<br/> Currency conversion is not available at
this time.<br/>");
out.println("</p>");
out.println("</card>");
out.println("</wml>");
}
private void reportResults(PrintWriter out, float guilders, float
euros)
{
out.println("<?xml version=\"1.0\"?>");
out.println(DOC_TYPE);
out.println("<wml>");
out.println("<template>");
out.println("<do type='prev' label='Back'>");
out.println("<prev/>");
out.println("</do>");
out.println("</template>");
out.println("<card id='results' title='Results'>");
out.println("<p>");
out.println("<br/>" + guilders + " Guilders <br/>");
out.println("is equivalent to <br/>");
out.println(euros + " Euros <br/>");
out.println("<br/>");
out.println("</p>");
out.println("</card>");
out.println("</wml>");
}
}
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>
<p>Guilders: <input type="text" name="amount"
format="*N" /> </p>
</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