×
☰ See All Chapters

SOAP Example

In this tutorial we will learn simple example of SOAP using JAX-WS. JAX-WS SOAP example must follow these requirements:

The implementing class must be annotated with either the javax.jws.WebService or javax.xml.ws.WebServiceProvider annotation. The implementing class may explicitly reference an SEI (Service Endpoint Interface) through the endpointInterface element of the @WebService annotation, but is not required to do so. If no endpoint interface is specified in @WebService annotation, an SEI is implicitly defined for the implementing class. But as the best practices tell us, we should first define an interface that declares all the methods to be exposed as a Web Service, and its implementation should define those methods.

  soap-example-0
 

If any TO (transfer Objects) type is used in web service methods then those TO classes must implement Serializable interface.

public class Employee implements Serializable {

        private String name;

            private int age;

            private int id;

            //setters and getters

}

Using javax.jws.soap.SOAPBinding annotation we can define the message exchanging formats. SOAPBinding annotation specifies the mapping of the Web Service onto the SOAP message protocol.

import javax.jws.WebService;

import javax.jws.soap.SOAPBinding;

import javax.jws.soap.SOAPBinding.Style;

 

@WebService

@SOAPBinding(style = Style.RPC)

//@SOAPBinding(style = Style.DOCUMENT)

public interface HelloWorld{

……

}

  • The business methods of implementing class must be public, and must not be declared as static or final. 

  • The business methods that are exposed to web services clients must be annotated with javax.jws.WebMethod 

  • The business methods that are exposed to web services clients must have JAX-B compatible parameters and return type. 

  • The implementing class must not be declared final and must not be abstract. 

  • The implementing class must have a default public constructor. 

  • The implementing class must not define finalize method. 

  • The implementing class may use javax.annotation.PostConstruct or javax.annotation.PreDestroy annotations on its methods for lifecycle events callbacks. 

  • The @PostConstruct method is called by the container before the implementing class begins responding to web service clients. 

  • The @PreDestroy method is called by the container before the endpoint is removed from the operation. 

HelloWorld.java

package com.java4coding;

 

import javax.jws.WebMethod;

import javax.jws.WebService;

import javax.jws.soap.SOAPBinding;

import javax.jws.soap.SOAPBinding.Style;

 

@WebService

@SOAPBinding(style = Style.RPC)

// @SOAPBinding(style = Style.DOCUMENT)

public interface HelloWorld {

        @WebMethod

        String getHelloWorldAsString(String name);

}

HelloWorldImpl.java

package com.java4coding;

 

import javax.jws.WebService;

 

//Service Implementation

@WebService(endpointInterface = "com.java4coding.HelloWorld")

public class HelloWorldImpl implements HelloWorld{

        @Override

        public String getHelloWorldAsString(String name) {

                return "Hello World JAX-WS " + name;

        }

}

HelloWorldPublisher.java

package com.java4coding;

 

import javax.xml.ws.Endpoint;

 

//Endpoint publisher

public class HelloWorldPublisher {

        public static void main(String[] args) {

                Endpoint.publish("https://localhost:7779/ws/hello", new HelloWorldImpl());

                System.out.println("done");

        }

}

Project directory structure

soap-example-1
 

How to view generated WSDL?

After running the HelloWorldPublisher code, we can see the generated WSDL file by visiting the URL:

https://localhost:7779/ws/hello?wsdl

Note: SOAP web services URL always ends with ‘?wsdl’

soap-example-2
 

How to stop web service published using javax.xml.ws.Endpoint?

We can stop web service published using javax.xml.ws.Endpoint using stop() method of  Endpoint as below:

Endpoint ep = Endpoint.create(new HelloWorldImpl());

ep.publish("https://localhost:7779/ws/hello ");

..

ep.stop();

But since stop method is called as after publishing the web service, we can no longer access the web service. If service is meant to be running always, we should not call stop() method. Once publish() method is called, the web service will run in a separate thread. Later on to stop the web service we cannot get that instance of Endpoint. Executing the above publisher code will execute with new instance of Endpoint, hence calling stop() method of this new Endpoint instance will not stop web service which is published earlier.

To stop the web service published using Endpoint we need to kill javaw.exe process running in the computer system.

How to test web service?

To learn to test web service follow our next chapter Testing web service.

How do I end javaw.exe process to end the web service published on javax.xml.ws.Endpoint?

  1. Right click on the taskbar (or press Ctrl+Alt+Delete) & click on the start task manager 

  2. On the opened window click on the process tab 

  3. Select the javaw.exe file right click on it and click end process tree 

Or in eclipse stop the javaw.exe process by clicking on stop button as show in below screenshot.

soap-example-3
 

Does Endpoint.publish use the tomcat server to host this or is it a mini glassfish kind of server?

JAX-WS RI Endpoint.publish API uses by default a light-weight HTTP server implementation that is included in Sun's Java SE 6. So no, it does not use an embedded GlassFish nor an embedded Tomcat and even less your existing Tomcat install: it uses an embedded container i.e. something running inside the same JVM. Just FYI, it is however possible to plug other implementations as long as they provide a Service Provider Implementation (SPI). For example, Jetty 6 does so, see J2se6HttpServerSPI.

It uses its own server and allows you to deploy your web service without having to package and deploy your app. It is especially useful during development (as it speeds up things). Actually, it's extremely handy.

Now, if you have a Tomcat server running on port 8082 and if you try to publish your Endpoint using the same port, things won't work. Use a different (and unused) port during development.

And if you want to deploy your web services to your existing Tomcat install, then you'll have to package them in a war and to deploy this war on Tomcat. But this is totally different and doesn't have anything to do with using the Endpoint.publish API.

The JAX-WS Example we provided in this chapter is just running in JVM, if we want a JAX-WS web service to be deployed in app servers we have separate architecture to be followed. We have to generate ties and stubs before packaging the application. wsimport, wsgen are the tools used to generate ties and stubs.

Below section details the ties and stubs concepts. We will study wsimport, wsgen tools in the coming chapters.

All Chapters
Author