SOAP-based Web Services in Java: A start-up Primer

I feel compelled to share a simple Web Service program in Java as I see this is quite an old technology that only advanced things are found everywhere - lot of generated code etc.. but the fundamentals are lost in the process...

1.     Create a SOAP-based Web Service

2.     Look at WSDL

3.     Generate Proxies

4.     Create a Web Services client

Pre-requisites:

1.     Eclipse installed with J2EE support

Not Required:

1.     Any web server as this is pure Java based

Basics:

The fundamental elements are to create:

1.     An interface

2.     An implementation class

3.     A webservice publisher

Here is the interface Definition:

package com.sai.ws;




import javax.jws.WebService;

import javax.jws.WebMethod;

import javax.jws.soap.SOAPBinding;

import javax.jws.soap.SOAPBinding.Style;

@WebService

@SOAPBinding(style = Style.RPC)

public interface EchoServer {

     @WebMethod

     String echoMessage(String strMsg);

    

}

Here using annotations, we are declaring that this is a WebService Interface with SOAPBinding following the simple RPC style.

Now to the class that implements this interface:

@WebService(endpointInterface = "com.sai.ws.EchoServer")

public class EchoServerImpl implements EchoServer{

     @Override

     public String echoMessage(String strMsg) {

          String capitalizedMsg;

         

          System.out.println("Server: EchoMessage() invoked...");

          System.out.println("Server: Message> " + strMsg);

          capitalizedMsg = strMsg.toUpperCase();

          return capitalizedMsg;

     }

}

The implementation merely capitalizes the message and return he same. Note here that the annotation @WebService needs to declare that this is an implementation of the interface “com.sai.ws.EchoServer” which is the endpointInterface of the service.

Now we are done. Implemented the Service. We need to publish this service. We can publish it locally by the following:

public class EchoServerPublisher {

     public static void main(String args[]) {

          Endpoint.publish("http://localhost:9876/es",new EchoServerImpl());

     }

}

Now, you execute the above java program and your Webservice is running. Endpoint creates and publishes an endpoint for the specified implementor object (EchoServerImpl) at the given address (http://localhost:9876/es). The necessary server infrastructure will be created and configured by the JAX-WS internal implementation using some default configuration.

So far, we have created a webservice interface, implementation and published it.

Now you can view the WSDL generated by accessing the URL: http://localhost:9876/es?wsdl

This is a verbose WSDL that describes the message style, the interface consisting of the request-response style, the bindings of ‘how’ to acess the service and the ‘where’ to access it finally (the URL).

The various components of the WSDL may be summarized as follows:

How do you consume this from a client. Let us write a simple client project named “WebServiceCLientExample”. Create a class “SimpleServiceClient” in that project.

Here is the method to access the Service within the client:

     public static void main (String args[]) throws Exception{

         

          final URL url = new URL("http://localhost:9876/es");

         

          final QName name = new QName("http://ws.sai.com/", "EchoServerImplService");

         

          final Service service = Service.create(url, name);

         

          final EchoServer simple = service.getPort(EchoServer.class);

         

          System.out.println(simple.echoMessage("Hello Everyone!"));

         

     }

As you see, from the client we need to specify the URL to access the service: http://localhost:9876/es

Then we need to specify the qualified namespace that consists of two things:

1. The URI is the value of the @namespace attribute in WSDL.
2. The local part is the value of the service[@name] attribute at the bottom of WSDL.

As shown here:

final QName name = new QName("http://ws.sai.com/", "EchoServerImplService");

Then, we create the service as in:

          final Service service = Service.create(url, name);

Finally get our port:

final EchoServer simple = service.getPort(EchoServer.class);

Then, call the methods on that port:

simple.echoMessage("Hello Everyone!")

This completes a simple webservice and a client to the webservice in plain java. However, not that for the client to work in the above format (without any proxy generation), you will have to include the webservice project in the classpath of the client project. If not, service.getPort(EchoServer.class) will throw an error as EchoServer.class cannot be found in the path.

So, in reality, you will not have the server classes available on the client side as Webservices are for remote access of the service. In that case, you will have to download the WSDL from the URL http://localhost:9876/es?wsdl and include into into the client project. Then, right click the file and select ‘Web Services - > Generate Client’. You get this dialog box:

Select only Develop client. If you use the slider, it will generate a lot more which you can explore if you are interested.  Click ‘next’ and finish.

You will have the following files (proxies generated)

Now, you should be able to compile the client and use it remotely.

Hope this helps in your first step to SOAP-based web services.