Creating a Web Service Client

In this section, you create SquareRootClient, a Java application that can call the methods of the web service you just created. The service must, of course, be running for the client to connect to it.

Because web service technology like the JAX-WS library supports standards such as SOAP, REST, HTTP, and XML, you don’t have to use a Java program to connect to the square root web service. Perl, Python, Ruby and other languages all have libraries that support web services.

The JAX-WS library offers the Service class in the javax.xml.ws package, a factory that creates objects that can call a web service.

The class method Service.create(URL, QName) creates the factory. The arguments are a URL object from java.net and a QName from javax.xml.namespace.

The URL must be the address of the web service’s WSDL contract:

URL url = new URL("http://127.0.0.1:5335/service?wsdl");

The QName is a qualified name, an XML identifier that’s associated with the provider of the web service. A qualified name consists of a namespace URI and a local identifier.

Namespace URIs are similar to URLs but do not necessarily work as a web address. Because the package name of the square root web service is com.java24hours.ws, which by convention in Java associates it with the Internet host name ws.java24hours.com, the namespace URI for this web service is http://ws.java24hours.com.

The local identifier for the web service is the name of the Service Implementation Bean with the word “Service” appended. Here’s the statement that creates the qualified name:

QName qname = new QName(
    "http://ws.java24hours.com/",
    "SquareRootServerImplService"
);

With the URL and qualified name, you can create the web service client factory:

Service service = Service.create(url, qname);

The factory has a getPort(Class) method that creates an object of the specified class. To identify a Java class for use as a method argument, use a class variable of the class named class. Confusing? It makes more sense when you see it in a Java statement:

SquareRootServer srs = service.getPort(SquareRootServer.class);

The call to getPort() with SquareRootServer.class as the argument causes the factory to create a SquareRootServer object. This object is stored in the srs variable.

Call the methods of the SquareRootServer object as you would any other object in Java:

System.out.println(srs.getTime());
System.out.println(srs.getSquareRoot(625D));

The JAX-WS library packages these method calls as SOAP messages, sends them over the Internet to the web service, and transmits the calls.

When the service responds to the calls, it packages the responses as SOAP messages, sends them back over the Internet, and they’re converted back to Java data types.

Put all these together by creating an empty Java file named SquareRootClient and entering the text from Listing 22.5 in the file.

Listing 22.5. The Full Text of SquareRootClient.java

 1: package com.java24hours.ws;
 2:
 3: import java.net.*;
 4: import javax.xml.namespace.*;
 5: import javax.xml.ws.*;
 6:
 7: class SquareRootClient {
 8:     public static void main(String[] arguments) throws Exception {
 9:         URL url = new URL("http://127.0.0.1:5335/service?wsdl");
10:         QName qname = new QName(
11:             "http://ws.java24hours.com/",
12:             "SquareRootServerImplService"
13:         );
14:         Service service = Service.create(url, qname);
15:         SquareRootServer srs = service.getPort(SquareRootServer.class);
16:
17:         System.out.println(srs.getTime());
18:         System.out.println(srs.getSquareRoot(625D));
19:    }
20: }

When you run the client application, you see the output shown in Figure 22.1 if the SquareRootPublisher application is running.

Figure 22.1. Calling a web service and displaying the response.

Summary

The JAX-WS set of packages and classes is the successor to the Java API for XML-based RPC (JAX-RPC), a technology for making remote procedure calls from one Java object to another over the Internet.

The ability to call other software, regardless of its location and the programming language in which it’s written, is one of the building blocks of a software development trend called Web 2.0.

Web 2.0 enables software to take as much advantage of the Internet’s ubiquitous connectivity as humans have enjoyed since the Web became popular in the mid-1990s.

This hour’s covered all four steps of creating and using a web service using JAX-WS. You can create an interface for the service (a Service Endpoint Interface), implement the service (a Service Implementation Bean), publish the service on the Internet, and create a client to access it.

Many programming tools, including NetBeans and the JDK, make it possible to create code automatically to simplify the job of creating and accessing web services.

Q&A

Q. How does XML-RPC fit in with SOAP web services?

A. XML-RPC is a protocol for calling methods and receiving data in an XML format over HTTP, the protocol of the Web. SOAP is all those things as well, and in fact the two web service protocols share a common origin.

XML-RPC was created from a draft version of the protocol that eventually became SOAP. Because XML-RPC was out first and is simpler to implement, it developed its own following and remains popular today. The Apache XML-RPC Java library, available from http://ws.apache.org/xmlrpc, supports the creation of web services and clients that employ XML-RPC.

SOAP’s a more sophisticated web service protocol that supports a wider range of client/service interactions.

Q. I’m not clear on why a package named com.java24hours.ws is associated with the Internet host ws.java24hours.com. How does that work?

A. Java package names are created by the programmers who developed the package. Oracle starts the names of Java packages from the Java class library with either java or javax, such as java.util and javax.swing. When other programmers create package, they follow a convention that prevents two entities from choosing the same package name and being confused with each other.

The convention is to choose a package name that’s based on something the entity owns—a domain name. As the owner of the domain name cadenhead.org, I’ve created Java classes with package names that begin with org.cadenhead, such as org.cadenhead.web. The Apache Software Foundation, which owns apache.org, calls its XML-RPC package org.apache.xmlrpc.

Q. What was the first website on the Internet?

A. The first site was http://info.cern.ch, which is still online today. Tim Berners-Lee, a physicist at the European Organization for Nuclear Research (CERN), used the site to describe his new invention, the World Wide Web.

The first webpage was at http://info.cern.ch/hypertext/WWW/TheProject.html and was updated daily as the Web attracted users, publishers, and software developers.

The site defined the web as a “a wide-area hypermedia information retrieval initiative aiming to give universal access to a large universe of documents.”

Workshop

See how many facts about web services have filled your bean by answering the following questions.

Quiz

1. What is a Service Implementation Bean?

A. An interface that identifies the methods reachable over a web service

B. A class that implements a web service

C. A service contract between a web service and clients that call the service

2. When text such as @WebMethod or @Override appears in a method declaration, what is it called?

A. An annotation

B. An assertion

C. An aggravation

3. What does WSDL stand for?

A. Web Services Deployment Language

B. Web Services Description Language

C. Lucy in the Sky with Diamonds

Answers

1. B. Answer A. refers to a Service Endpoint Interface.

2. A. Though I guess answer C. is also potentially true, depending on how much trouble you had in that section of the hour.

3. B. It’s often mistakenly called Web Services Definition Language.

Activities

To further service your knowledge of this hour’s topic, do the following activities:

• Add a method to the square root web service that multiplies a number by 10, and modify the SquareRootClient application to call that method.

• Create a new web service that uses the WeatherStation class from Hour 21, “Reading and Writing XML Data,” and makes the current high temperature, low temperature, and weather conditions accessible through a web service.

To see Java programs that implement these activities, visit the book’s website at www.java24hours.com.