Write Your First Web Services Client Part 2: Using Services

Lets dive into our second part of demystifying Web Services tutorial and writing your first (second :)) Web Services Client (you might want to read first part 1 about Finding and Testing Web Services Tutorial). Again, I do not want to show you how to write a new Web Service, as I personally believe that it is more motivational for a new user of Web Services technologies to use existing service to grasp an idea of them, rather than to write services themselves. That is why we will find and use an existing Web Service and write some useful Web application. I will use for this tutorial Java, Tomcat and Eclipse. If you have these installed on your machine, then in 10-15 minutes you should have your application up and running. Otherwise you have to reserve more time to download and install required components. Anyway, once you are done with installations, the practical part of this tutorial will be very short as I have cut everything to absolute minimum. I want you to use Web Services, not to waste your time on understanding bits and bytes of their particular protocols (this you can find yourself in WSDL and SOAP specifications and various more advanced tutorials available on the Web).

I assume you might be a Web Developer, who has learned somewhere about Web Services technologies and would like to use them. All you need to know at this stage is to have some very basic understanding of HTML, Java and JSP technologies to follow up this tutorial. You do not really have to be a master in any of them. If you ever read any basic course about JSP and wrote a simple page yourself, then you should have no troubles with finishing this tutorial at all.

So first lets think about a motivating scenario. I would like to reuse partially the scenario from part 1 of this tutorial. My hypothetical Web development company from Tirol remains contracted by a local hotels resort from Innsbruck to build and maintain a website for their hotels. What would then usually a customer expect to find on the website of the hotel? As part of the Web presence of any hotel, visitors expect a reservation page including pricing information. Although in Austria, as in most of the European countries we already use the same currency, which is Euro, Tirol is getting these days tourists from all around the world. So lets be nice to our tourists coming from non-Euro countries and lets provide currency conversion service directly at the website so the prices are displayed in currencies of our customers (for simplification we will do it only for our American and Russian friends). At the end of the day there is no better way of attracting customers, than when already at the time of making reservation, they would feel like at home :).

What are dependent components for this tutorial and from where can you download them:

1. I use Java Development Kit. Download JDK 6 from Sun download page.
2. I use Tomcat 6.x. Find it at Apache Tomcat download page.
3. Finally we will need Eclipse. Please use Eclipse IDE for Java EE Developers (or at least add Web Tools (WTP) to your existing Eclipse installation). You will find a complete download for it at Eclipse download page.

We must find an appropriate service to conduct currency conversion. We find it at seekda search page. Just type “currency converter” in the search box and over 70 services, which are having something to do with the currency conversion are getting presented to us (some of them are paid services, but also several free ones are getting found). Use your knowledge gained with part 1 of this tutorial to investigate these services and identify the right and the most appropriate for you. I will simply use the first one from the list, namely the free currency converter from webservicex.com. Although availability and response time of this service are not so perfect (see Availability Tab, where all the monitoring information is collected), still for the purpose of this tutorial this service should be satisfactory.

So we know already the Web Service, which we would like to use. Now we will write a JSP page, which connects to this Web Service.

1. Start Eclipse
2. Select Window > Open Perspective > Other > Java EE
3. Select File > New > Other > Web > Dynamic Web Project
4. Give a name to your project (I use “innsbruck-hotels”) and click Finish.

Now we have to create a JSP page. Eclipse will create a skeleton of this page for us.

1. Select project “innsbruck hotels” in the Project Explorer
2. Click the right button of mouse on the project name and from the context menu select New > JSP
3. Give a new name to your page. I will call my page just “reservation”

We need to provide some content for our JSP page. At this stage this would be just a couple of simple HTML tags with some basic info about our hotel plus selection box for three currencies we use for this tutorial namely for EUR, USD and RUB.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
    pageEncoding="ISO-8859-1"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
	<head>
		<title>Available hotels in Innsbruck, Austria</title>
	</head>
	<body>
 		<h3> Available hotels in Innsbruck, Austria</h3>
 		<h4><strong>Luxury Hotel Innsbruck</strong></h4>
 		<p>Type: Romantic, Ski<br/>
    	   The Luxury Hotel Innsbruck is a family-operated
    	   property set amid the snow-capped mountains</p>	
 
 		<h5>Price for night: 80
   			<select>
     			<option value="EUR" selected >EUR</option>
     			<option value="USD">USD</option>
     			<option value="RUB">RUB</option>
   			</select>
 		</h5>
	</body>
</html>

Next we will run our reservation.jsp page in Tomcat container.

1. Select project “innsbruck hotels” in the Project Explorer.
2. Select WebContent > reservation.jsp.
3. Click the right button of mouse on the reservation.jsp page and from the context menu select Run As > Run on Server
4. Select Apache and next Tomcat v6.0 Server
5. Click Next >

   

You will have to point Eclipse to the folder, where Tomcat has been installed. reservation.jsp page should automatically open in the Eclipse browser. You can also alternatively open this page in your usual browser. If you did not change any of the default installation settings, then your page is available at the following address: http://localhost:8080/innsbruck-hotels/reservation.jsp

We will make a couple of adjustments to reservation.jsp page to prepare it before we can connect the currency converter Web Service into it.

1. We will make the price a parameter. Once we will know the exchange rate of other currencies we will simply multiply pricePerNigth parameter by this value:

   15	double pricePerNight = 80;

2. We will refresh our page every time user selects another currency. We can obtain this effect with onchange attribute of the select tag. We just call reservation.jsp page passing by currency as a property:

   22	<select onchange="location.href='reservation.jsp?currency='+this.value;">

3. Than we have to read this currency Parameter:

   17 18

   if (request.getParameter("currency") != null) currency = request.getParameter("currency");

   if (request.getParameter(”currency”) != null)
   currency = request.getParameter(”currency”);

4. Finally we have to modify each of three option tags, so the tag selected by user will hold its selected currency:

   23 24 25

   <option value="EUR" <%=currency.equals("EUR")?"selected":""%>>EUR</option> <option value="USD" <%=currency.equals("USD")?"selected":""%>>USD</option> <option value="RUB" <%=currency.equals("RUB")?"selected":""%>>RUB</option>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
    pageEncoding="ISO-8859-1"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
	<head>
		<title>Available hotels in Innsbruck, Austria</title>
	</head>
	<body>
 		<h3> Available hotels in Innsbruck, Austria</h3>
 		<h4><strong>Luxury Hotel Innsbruck</strong></h4>
 		<p>Type: Romantic, Ski<br/>
 		   The Luxury Hotel Innsbruck is a family-operated property
           set amid the snow-capped mountains</p>
		<%
		  double pricePerNight = 80;
		  String currency = "EUR";
		  if (request.getParameter("currency") != null)
		  	currency = request.getParameter("currency");
		%>
 
		<h5>Price for night: <%=pricePerNight %>
 			<select onchange="location.href='reservation.jsp?currency='+this.value;">
  				<option value="EUR" <%=currency.equals("EUR")?"selected":""%>>EUR</option>
  				<option value="USD" <%=currency.equals("USD")?"selected":""%>>USD</option>
  				<option value="RUB" <%=currency.equals("RUB")?"selected":""%>>RUB</option>
 			</select>
		</h5>
	</body>
</html>

So now we are ready to connect currency converter Web to our application

1. Select project “innsbruck hotels” in the Project Explorer.
2. Select New > Other… > Web Services > Web Services Client
3. Paste into Service Definition box the URL of the WSDL currency converter service, which you found at seekda: http://www.webservicex.com/CurrencyConvertor.asmx?wsdl
4. Make sure that the client type is set to Java Proxy and that you Develop Client (move the slider to the bottom).
5. Click Finish

Now, when the whole code has been automatically generated for us, we have just to make the final step - we have to connect the currency converter Web Service to our reservation.jsp page.

1. We use CurrencyConvertorSoapProxy class generated for us in the previous step. Just instantiate it and call conversionRate operation on it. You have to provide names of the source currency (EUR) and target currency as parameters.

   23 24

   CurrencyConvertorSoapProxy proxy = new CurrencyConvertorSoapProxy(); double conversionRate = proxy.conversionRate(Currency.EUR, Currency.fromValue(currency));

2. Multiply pricePerNight (which is price in Euro) by a conversion rate returned by the Web Service.

   25	pricePerNight = pricePerNight*conversionRate;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
    pageEncoding="ISO-8859-1"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<%@page import="NET.webserviceX.www.CurrencyConvertorSoapProxy"%>
<%@page import="NET.webserviceX.www.Currency"%>
<html>
	<head>
		<title>Available hotels in Innsbruck, Austria</title>
	</head>
	<body>
  		<h3> Available hotels in Innsbruck, Austria</h3>
  		<h4><strong>Luxury Hotel Innsbruck</strong></h4>
  		<p>Type: Romantic, Ski<br/>
     	   The Luxury Hotel Innsbruck is a family-operated property
     	   set amid the snow-capped mountains</p>
		<%
		double pricePerNight = 80;
		String currency = "EUR";
		if (request.getParameter("currency") != null)
			currency = request.getParameter("currency");
 
		if (!currency.equals("EUR")) {
			CurrencyConvertorSoapProxy proxy = new CurrencyConvertorSoapProxy();
		   	double conversionRate = proxy.conversionRate(Currency.EUR, Currency.fromValue(currency));
		   	pricePerNight = pricePerNight*conversionRate;
		}
		%>
 
 		<h5>Price for night: <%=pricePerNight %>
 			<select onchange="location.href='reservation.jsp?currency='+this.value;">
  				<option value="EUR" <%=currency.equals("EUR")?"selected":""%>>EUR</option>
  				<option value="USD" <%=currency.equals("USD")?"selected":""%>>USD</option>
  				<option value="RUB" <%=currency.equals("RUB")?"selected":""%>>RUB</option>
 			</select>
 		</h5>
	</body>
</html>

We just reached almost the end of our second tutorial :). Reload the reservation.jsp page in the browser and you get *the real* Web Service doing job for you (please remember that the availability of this particular Web Service as measured by seekda was far from perfect, so you might experience some small delays).

My intention in this tutorial was to show how to use Web Services, not how to write a fully fledged business application. That is why please remember that I made many simplifications in this scenario, which you would have to address if you would like to build a real web application using this service. I picked up some of the issues you would have to remember about:

1. If you would be building a real application, which would be used for currencies conversion at your website, in 99 percent of the cases it would be probably enough just to store exchange rates locally and update them only once or twice a day. Unless you build an application for a company from for example financial sector, which really needs the most recent and accurate rates, there would be absolutely no reason why you would have to call a currency converter service every time your user selects a new currency in an option box. You would also probably write a code to connect to currency converter Web Server in the business logic layer of your application and execute it only once, rather than code it directly at jsp page and execute it thousands of times during the day.
2. Assuming that you use a different Web Service, which must be called every time your user does some particular activity on the page (e.g. your user proceed to checkout in your eCommerce application and you want to check through Web Services if his/her address as provided at a checkout page is the real and existing address or a fake one) then you would probably use some AJAX trick, so that the user does have a feeling of a delay (freeze page) when waiting for a Web Service to get executed.
3. You would have to remember to handle exceptions. Even with our simply currency converter you might experience a problem that a Web Service is not available at a given time. You have to decide yourself how to handle exception in this situation e.g. you can use another Web Service, provide a default value or simply do nothing etc.
4. Although we have used a free Web Service for our tutorials, please remember that seekda indexes a huge amount of non-free Web Services. While you find these services at seekda, you still have to go to pages of particular providers if you want to use them. Our technical team is currently working very hard to offer a marketplace for Web Services, so one day seekda will be a shopping point for Web Services, offered by providers from all around the world.