Java Client Server XML Web Services (JAX-WS) Tutorial
The application which we are going to build consists of two parts:
To start, let’s take a brief look at a Java technology which is built for web services.
1. Understand Java API for XML Web Services (JAX-WS)
There are several technologies that make up the Java web services technology which is a part of Java EE platform, and JAX-WS is the main technology that integrates other ones like JAXB (Java Architecture for XML Binding) and SAAJ (SOAP with Attachments API for Java). In other words, when working with web services in Java, we work with JAX-WS directly, which is in turn, works with dependent technologies like JAXB and SAAJ.
For Java SE, JAX-WS has been included since Java SE 6. That means we can write web service-based console applications from Java SE 6, without downloading JAX-WS implementation package.
-
- Home page: Java EE Web Services Technologies
- Latest version: JAX-WS 2.2 (as of Nov 2012)
- Download reference implementation: http://jax-ws.java.net
- API documentation: http://jax-ws.java.net/nonav/jaxws-api/2.2/index.html
-
- javax.xml.ws : the core package of JAX-WS.
- javax.jws : contains annotations to simplify writing code for web services, such as @WebService , @WebMethod , @WebParam …
In addition, Java SE comes with some command lines tools for simplifying generation of web services code: wgen , wsimport , schemagen and xjc . We will use the wsimport tool for generating some code for client part of the application.
2. Code the Java web service class
Now let’s create our web service class. The web service method returns a MD5-hahsed value of an input string. Using the annotations @WebService for the class and @WebMethod for the service method, create a class named MD5WebService.java as follows:
package net.codejava.webservices.server; import java.security.MessageDigest; import java.security.NoSuchAlgorithmException; import javax.jws.WebMethod; import javax.jws.WebService; @WebService public class MD5WebService < @WebMethod public String hashString(String input) < try < MessageDigest msgDigest = MessageDigest.getInstance("MD5"); byte[] inputBytes = input.getBytes(); byte[] hashedBytes = msgDigest.digest(inputBytes); StringBuffer sb = new StringBuffer(); for (int i = 0; i < hashedBytes.length; i++) < sb.append(Integer.toString((hashedBytes[i] & 0xff) + 0x100, 16) .substring(1)); >return sb.toString(); > catch (NoSuchAlgorithmException ex) < ex.printStackTrace(); return ""; >> >Type the following command to compile the web service class (suppose the current directory is parent of the directory structure for the package: net.codejava.webservices.server ):
javac net\codejava\webservices\server\MD5WebService.java
3. Code the server program for Java web service
To create a simple, lightweight server for deploying the web service, we use the method publish() of the javax.xml.ws.Endpoint class:
publish(String address, Object implementor)
-
- address : specifies an URI to which the web service is bound. The client will connect to the web service deployed on this server via this URI.
- implementor : specifies an instance of the web service class.
package net.codejava.webservices.server; import javax.xml.ws.Endpoint; public class WebServiceServer < /** * Starts a simple server to deploy the web service. */ public static void main(String[] args) < String bindingURI = "http://localhost:9898/md5WebService"; MD5WebService webService = new MD5WebService(); Endpoint.publish(bindingURI, webService); System.out.println("Server started at: " + bindingURI); >>The JAX-WS implementation will create necessary infrastructure to start the server using some default configuration. And once started, the server is ready to receiving client’s requests.
Type the following command to compile the server class:
javac net\codejava\webservices\server\WebServiceServer.java
Start the server program using the following command:
java net.codejava.webservices.server.WebServiceServer
We should see the server started and is waiting for client’s requests at the command prompt:
Open a web browser and type the following URI into its address bar:
http://localhost:9898/md5WebService?wsdl
The browser will receive an XML document that describes the web service, as shown in the following screenshot:
4. Code the client program for Java web service
Before writing code for the client program, we have to generate some metadata code for the web service, by using the wsimport tool. This tool imports metadata about a web service provided by a URI and generates Java source files required for a web service client. Syntax of the wsimport command is as follows:
-
- options : specifies some options when generating the client code. You can type only wsimport in the command prompt to see a list of options.
- WSDL_URI : specifies a URI that describes the web service.
wsimport -keep -p net.codejava.webservices.client http://localhost:9898/md5WebService?wsdl
Note that the URI has the parameter wsdl , while the URI in the server class has not. The option -keep is to keep generated Java source files, and the option –p specifies the package name for the generated files.
Based on the information obtained from the web service, the wsimport tool generates the following classes (both .java and .class files) and put them under package net.codejava.webservices.client :
-
- package-info.java
- ObjectFactory.java
- MD5WebServiceService.java
- MD5WebService.java
- HashStringResponse.java
- HashString.java
package net.codejava.webservices.client; public class WebServiceClient < /** * Starts the web service client. */ public static void main(String[] args) < MD5WebServiceService client = new MD5WebServiceService(); MD5WebService md5Webservice = client.getMD5WebServicePort(); String hash = md5Webservice.hashString("admin"); System.out.println("MD5 hash string: " + hash); >>This client program invokes the web service method hashString() and passes “admin” as an argument, and it will display the result received from web service server to the console. Type the following command to compile the web service client class:
javac net\codejava\webservices\client\WebServiceClient.java
And type this command to run the client program:
java net.codejava.webservices.client.WebServiceClient
The client connects to the server, invokes the remote method and receives the result, as shown in the following screenshot:
And that’s we have finished our journey on developing a fundamental client-server application for deploying and consuming a web service in Java.
NOTES: There is a small compatibility issue between JAX-WS 2.1 (Java SE 6) and JAX-WS 2.2 (Java SE 7), so the web service code compiled with Java SE 6 may not compile with Java SE 7, and vice versa.
You can also watch the video tutorial below:
Other Java Web Services Tutorial:
About the Author:
Nam Ha Minh is certified Java programmer (SCJP and SCWCD). He started programming with Java in the time of Java 1.4 and has been falling in love with Java since then. Make friend with him on Facebook and watch his Java videos you YouTube.
