Creating a Simple Web Service and Clients with JAX-WS

This section shows how to build and deploy a simple web service and an application client.

The starting point for developing a JAX-WS web service is a Java class annotated with the javax.jws.WebService annotation. The @WebService annotation defines the class as a web service endpoint.

A service endpoint interface or service endpoint implementation (SEI) is a Java interface or class, respectively, that declares the methods that a client can invoke on the service. An interface is not required when building a JAX-WS endpoint. The web service implementation class implicitly defines an SEI.

You may specify an explicit interface by adding the endpointInterface element to the @WebService annotation in the implementation class. You must then provide an interface that defines the public methods made available in the endpoint implementation class.

Here’s a guide to show you how to deploy JAX-WS web services on Tomcat servlet container. See following summary steps of a web service deployment.

1. Create a web service(WebService).
2. Create a sun-jaxws.xml, defines web service implementation class.
3. Create a standard web.xml, defines WSServletContextListener, WSServlet and structure of a web project.
4. Build tool to generate WAR file.
5. Copy JAX-WS dependencies to “${Tomcat}/lib” folder.
6. Copy WAR to “${Tomcat}/webapp” folder.
7. Start It.

Directory structure of this example, so that you know where to put your files.

1. WebServices-Create a Web Service Endpoint Interface
A simple JAX-WS hello world example.
File : HelloWorld.java

package com.dineshonjava.ws;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
import javax.jws.soap.SOAPBinding.Style;

/**
 * @author Dinesh Rajput
 * Service Endpoint Interface
 */

@WebService
@SOAPBinding(style = Style.RPC)
public interface HelloWorld {
 @WebMethod 
 String sayHelloWorld();
}

Create a Web Service Endpoint Implementation
File : HelloWorldImpl.java

package com.dineshonjava.ws;

import javax.jws.WebService;

/**
 * @author Dinesh Rajput
 * Service Implementation Bean
 */

@WebService(endpointInterface = "com.dineshonjava.ws.HelloWorld")
public class HelloWorldImpl implements HelloWorld {

 @Override
 public String sayHelloWorld() {
  return "Hello World!! Dinesh on Java!!";
 }
}

Create a Endpoint Publisher-

package com.dineshonjava.endpoint;

import javax.xml.ws.Endpoint;

import com.dineshonjava.ws.HelloWorldImpl;

/**
 * @author Dinesh Rajput
 * Endpoint publisher
 */
public class HelloWorldPublisher {

 /**
  * @param args
  */
 public static void main(String[] args) {
  Endpoint.publish("http://localhost:8181/sdnext/hello", new HelloWorldImpl());
 }

}

2. sun-jaxws.xml
Create a web service deployment descriptor, which is also known as JAX-WS RI deployment descriptor – sun-jaxws.xml.
File : sun-jaxws.xml

<?xml version="1.0" encoding="UTF-8"?>
<endpoints  xmlns="http://java.sun.com/xml/ns/jax-ws/ri/runtime" version="2.0">
  <endpoint name="HelloWorld" implementation="com.dineshonjava.ws.HelloWorldImpl"
      url-pattern="/hello"/>
</endpoints>

When user access /hello/ URL path, it will fire the declared web service, which is HelloWorldImpl.java.

3. web.xml
Create a standard web.xml deployment descriptor for the deployment. Defines WSServletContextListener as listener class, WSServlet as your hello servlet.
File : web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" id="WebApp_ID" version="3.0">
  <display-name>WebService</display-name>
  <listener>
        <listener-class>
               com.sun.xml.ws.transport.http.servlet.WSServletContextListener
        </listener-class>
    </listener>
    <servlet>
        <servlet-name>hello</servlet-name>
        <servlet-class>
         com.sun.xml.ws.transport.http.servlet.WSServlet
        </servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>hello</servlet-name>
        <url-pattern>/hello</url-pattern>
    </servlet-mapping>
    <session-config>
        <session-timeout>120</session-timeout>
    </session-config>
 </web-app>

4. WAR Content
Use Ant, Maven or JAR command to build a WAR file to include everything inside. The WAR content should look like this :

WEB-INF/classes/com/dineshonjava/ws/HelloWorld.class
WEB-INF/classes/com/dineshonjava/ws/HelloWorldImpl.class
WEB-INF/web.xml
WEB-INF/sun-jaxws.xml
OR
right click to project and export as war file with name "WebService.war" and deploy it to tomcat web server.

5. JAX-WS Dependencies
By default, Tomcat does not comes with any JAX-WS dependencies, So, you have to include it manually.
1. Go here http://jax-ws.java.net/.
2. Download JAX-WS RI distribution.
3. Unzip it and copy following JAX-WS dependencies to Tomcat library folder “{$TOMCAT}/lib“.
jaxb-impl.jar
jaxws-api.jar
jaxws-rt.jar
gmbal-api-only.jar
management-api.jar
stax-ex.jar
streambuffer.jar
policy.jar
ha-api.jar

6. Deployment

Copy the generated WAR file to {$TOMCAT}/webapps/ folder and start the Tomcat server.
For testing, you can access this URL : http://localhost:8181/sdnext/hello, if you see following page, it means web services are deploy successfully.


you can access this URL : http://localhost:8181/sdnext/hello?wsdl, if you see following page



Web Service Clients
Ok, web service is deployed properly, now let’s see how to create web service client to access to the published service.
1. Java Web Service Client
Without tool, you can create a Java web service client like this :

package com.dineshonjava.client;

import java.net.MalformedURLException;
import java.net.URL;

import javax.xml.namespace.QName;
import javax.xml.ws.Service;

import com.dineshonjava.ws.HelloWorld;

/**
 * @author Dinesh Rajput
 *
 */
public class HelloWorldClient {

 /**
  * @param args
  */
 public static void main(String[] args) {
  URL url;
  try {
   url = new URL("http://localhost:8181/sdnext/hello?wsdl");
   
         //1st argument service URI, refer to wsdl document above
   //2nd argument is service name, refer to wsdl document above
         QName qname = new QName("http://ws.dineshonjava.com/", "HelloWorldImplService");
  
         Service service = Service.create(url, qname);
  
         HelloWorld hello = service.getPort(HelloWorld.class);
  
         System.out.println(hello.sayHelloWorld());
  } catch (MalformedURLException e) {
   e.printStackTrace();
  }
 }

}

Output:


2. Java Web Service Client via wsimport tool
Alternative, you can use “wsimport” tool to parse the published wsdl file, and generate necessary client files (stub) to access the published web service.
Where is wsimport?
This wsimport tool is bundle with the JDK, you can find it at “JDK_PATH/bin” folder.
Use the following command for parsing the WSDL file...

 wsimport -keep http://localhost:8181/sdnext/hello?wsdl


It will generate necessary client files, which is depends on the provided wsdl file. In this case, it will generate one interface and one service implementation file.
1. HelloWorld.java

package com.dineshonjava.ws;

import javax.jws.WebMethod;
import javax.jws.WebResult;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
import javax.xml.ws.Action;


/**
 * This class was generated by the JAX-WS RI.
 * JAX-WS RI 2.2.2 in JDK 7
 * Generated source version: 2.2
 * 
 */
@WebService(name = "HelloWorld", targetNamespace = "http://ws.dineshonjava.com/")
@SOAPBinding(style = SOAPBinding.Style.RPC)
public interface HelloWorld {


    /**
     * 
     * @return
     *     returns java.lang.String
     */
    @WebMethod
    @WebResult(partName = "return")
    @Action(input = "http://ws.dineshonjava.com/HelloWorld/sayHelloWorldRequest", output = "http://ws.dineshonjava.com/HelloWorld/sayHelloWorldResponse")
    public String sayHelloWorld();

}

2. HelloWorldImplService.java

package com.dineshonjava.ws;

import java.net.MalformedURLException;
import java.net.URL;
import javax.xml.namespace.QName;
import javax.xml.ws.Service;
import javax.xml.ws.WebEndpoint;
import javax.xml.ws.WebServiceClient;
import javax.xml.ws.WebServiceException;
import javax.xml.ws.WebServiceFeature;


/**
 * This class was generated by the JAX-WS RI.
 * JAX-WS RI 2.2.2 in JDK 7
 * Generated source version: 2.2
 * 
 */
@WebServiceClient(name = "HelloWorldImplService", targetNamespace = "http://ws.dineshonjava.com/", wsdlLocation = "http://localhost:8181/sdnext/hello?wsdl")
public class HelloWorldImplService
    extends Service
{

    private final static URL HELLOWORLDIMPLSERVICE_WSDL_LOCATION;
    private final static WebServiceException HELLOWORLDIMPLSERVICE_EXCEPTION;
    private final static QName HELLOWORLDIMPLSERVICE_QNAME = new QName("http://ws.dineshonjava.com/", "HelloWorldImplService");

    static {
        URL url = null;
        WebServiceException e = null;
        try {
            url = new URL("http://localhost:8181/sdnext/hello?wsdl");
        } catch (MalformedURLException ex) {
            e = new WebServiceException(ex);
        }
        HELLOWORLDIMPLSERVICE_WSDL_LOCATION = url;
        HELLOWORLDIMPLSERVICE_EXCEPTION = e;
    }

    public HelloWorldImplService() {
        super(__getWsdlLocation(), HELLOWORLDIMPLSERVICE_QNAME);
    }

    public HelloWorldImplService(WebServiceFeature... features) {
        super(__getWsdlLocation(), HELLOWORLDIMPLSERVICE_QNAME, features);
    }

    public HelloWorldImplService(URL wsdlLocation) {
        super(wsdlLocation, HELLOWORLDIMPLSERVICE_QNAME);
    }

    public HelloWorldImplService(URL wsdlLocation, WebServiceFeature... features) {
        super(wsdlLocation, HELLOWORLDIMPLSERVICE_QNAME, features);
    }

    public HelloWorldImplService(URL wsdlLocation, QName serviceName) {
        super(wsdlLocation, serviceName);
    }

    public HelloWorldImplService(URL wsdlLocation, QName serviceName, WebServiceFeature... features) {
        super(wsdlLocation, serviceName, features);
    }

    /**
     * 
     * @return
     *     returns HelloWorld
     */
    @WebEndpoint(name = "HelloWorldImplPort")
    public HelloWorld getHelloWorldImplPort() {
        return super.getPort(new QName("http://ws.dineshonjava.com/", "HelloWorldImplPort"), HelloWorld.class);
    }

    /**
     * 
     * @param features
     *     A list of {@link javax.xml.ws.WebServiceFeature} to configure on the proxy.  Supported features not in the features parameter will have their default values.
     * @return
     *     returns HelloWorld
     */
    @WebEndpoint(name = "HelloWorldImplPort")
    public HelloWorld getHelloWorldImplPort(WebServiceFeature... features) {
        return super.getPort(new QName("http://ws.dineshonjava.com/", "HelloWorldImplPort"), HelloWorld.class, features);
    }

    private static URL __getWsdlLocation() {
        if (HELLOWORLDIMPLSERVICE_EXCEPTION!= null) {
            throw HELLOWORLDIMPLSERVICE_EXCEPTION;
        }
        return HELLOWORLDIMPLSERVICE_WSDL_LOCATION;
    }

}

Now, create a Java web service client which depends on the above generated files.

package com.dineshonjava.client;

import com.dineshonjava.ws.HelloWorld;
import com.dineshonjava.ws.HelloWorldImplService;

/**
 * @author Dinesh Rajput
 *
 */
public class HelloWorldClient {

 /**
  * @param args
  */
 public static void main(String[] args) {
  HelloWorldImplService helloService = new HelloWorldImplService();
  HelloWorld hello = helloService.getHelloWorldImplPort();
 
  System.out.println(hello.sayHelloWorld());
 }

}

Here’s the output

Download SourceCode
WebService.zip



References
Wikipedia for Web Service