SOAP Implementation in JAVA

SOAP:

With SOAP implementations, client requests and web service responses are most often transmitted as Simple Object Access Protocol (SOAP) messages over HTTP to enable a completely interoperable exchange between clients and web services, all running on different platforms and at various locations on the Internet. HTTP is a familiar request-and response standard for sending messages over the Internet and SOAP is an XML-based protocol that follows the HTTP request-and-response model.

In SOAP 1.1, the SOAP portion of a transported message handles the following:

• Defines an XML-based envelope to describe what is in the message and how to process the message.
• Includes XML-based encoding rules to express instances of application-defined data types within the message.
• Defines an XML-based convention for representing the request to the remote service and the resulting response.
  

Role of XML as SOAP:

• XML doc is wrapped inside the SOAP body.
• SOAP body is wrapped inside SOAP envelope.
• Optional inclusion of SOAP header.
• Namespace declaration.
• Encoding style for serialization of data.
• Binding of whole thing to a protocol.

SOAP & Web Service

SOAP is normally used for web services and the web services can be developed on any platform but the communication is normally SOAP based.

Web service is nothing but a normal web application without presentation layer based on formal http request/response paradigm.

So we will concentrate on the Web Services which are widely used in every field of the web-based environments to make things more interoperable.

In short web service is XML based message binding mechanism via HTTP at TCP/IP level with some additional implementation to make data/message interoperable.

We need to understand two more terms ‘WSDL’, ‘UDDI’ along with ‘SOAP’ before going deeply in web services implementations.

WSDL (Web Services Definition Language):

WSDL is a standardized XML format for describing network services. The description includes the name of the service, the location of the service, and ways to communicate with the service, that is, what transport to use. WSDL descriptions can be stored in service registries (UDDI discussed below), published on the Internet, or both.

UDDI (Universal Description, Discovery & Integration):

UDDI provides a worldwide registry of web services or advertisement, discovery and integration purposes. Business analyst and technologists use UDDI to discover available web service by searching for names, identifiers, categories or specific types.

Relation between SOAP, WSDL and UDDI:

SOAP enabled client queries UDDI registry for service by name after locating.  Client obtains information about location of WSDL doc from UDDI registry.  WSDL contains information about how to contact web service and format of request messages in XML schema.  Then client creates a SOAP message according to XML schema found in WSDL & send a request to host.

Ok…  we had spent enough time on general conceptual aspects of SOAP, Web Service and related terminologies, now we will see how these are implemented in JAVA.

Web Service Implementation in Java:

First there was SOAP. But SOAP only described what the messages looked like. Then there was WSDL. But WSDL didn’t tell you how to write Web services in Java. Then along came JAX-RPC 1.0. After a few months of use, the Java Community Process (JCP) folks who wrote that specification realized that it needed a few tweaks, so out came JAX-RPC 1.1. After a year or so of using that specification, the JCP folks wanted to build a better version: JAX-RPC 2.0. A primary goal was to align with industry direction, but the industry was not merely doing RPC Web services, they were also doing message-oriented Web services. So "RPC" was removed from the name and replaced with "WS" (which stands for Web Services, of course). Thus the successor to JAX-RPC 1.1 is JAX-WS 2.0 – the Java API for XML-based Web services. So Currently JAX-WS is base of all java based web service implementations.

Reasons you may want to stay with JAX-RPC 1.1:

• If you want to stay with something that’s been around a while, JAX-RPC will continue to be supported for some time to come.
• If you don’t want to step up to Java 5.
• If you want to send SOAP encoded messages or create RPC/encoded style WSDL.

Reasons to step up to JAX-WS 2.0:

• If you want to use the new message-oriented APIs.
• If you want to use MTOM to send attachment data.
• If you want better support for XML schema through JAXB.
• If you want to use an asynchronous programming model in your Web service clients.
• If you need to have clients or services that can handle SOAP 1.2 messages.
• If you want to eliminate the need for SOAP in your Web services and just use the XML/HTTP binding.
• If you like playing with leading edge technology.

There are various web service engines overlaying on these specs or you can implement them directly to develop web services. But in my opinion web service engines help you out from all the complex implementations of web service request response mechanism and free you to focus on your business logic.

Currently Apache Axis2 web service engine is good and broadly used. It is based on JAX-WS spec.  Prior to this there was Apache Axis which was based on JAX-RPC.

I am using Apache Axis2 for my ongoing project to full feel all web service needs.

In this article I will demonstrate web service design/development/deployment using Apache axis2/JAVA.

Prerequisites:

JAVA 5.0

Apache Ant

Tomcat (we will use tomcat for our web service deployment)

Apache Axis2 ver.1.5 or later version (http://ws.apache.org/axis2/download.cgi)

Axis2 Setup & Configuration:

Download the current Apache axis2 version. Extract it and proceed to the webapp directory inside extracted directory. Run apache ant on the build.xml file inside the webapp.  You will see that there is a directory ‘dist’ inside axis2 home directory along with axis2.war inside it. Now deploy this axis2.war inside your tomcat webapps directory.

Actually this axis2.war file is containing all the configuration and environment for any web-based application.

After deploying the axis2.war in tomcat server and restarting the server, go inside the axis2 directory which is created by Tomcat after deployment. Go inside the WEB-INF, you will see six items there. Copy ‘conf’, ‘services’, ‘lib’ and ‘modules’ from there and copy them inside the WEB-INF of your web application.

Edit the web.xml of your web application and write following entries:

<servlet>

    <servlet-name>AxisServlet</servlet-name>

    <servlet-class>org.apache.axis2.transport.http.AxisServlet</servlet-class>

    <load-on-startup>1</load-on-startup>

  </servlet>

  <servlet-mapping>

    <servlet-name>AxisServlet</servlet-name>

    <url-pattern>/services/*</url-pattern>

  </servlet-mapping>

</servlet>

Save the web.xml and restart tomcat

Now your application is configured to handle axis2 enabled web-service.

WSDL URL (we will see the service example later) will look like this,

http://localhost:8080/yourmodule/services/servicename?wsdl

If you want to change the ‘services’ to any other term, then you will have to change it inside the web.xml and also axis2.xml file inside the WEB-INF/conf.

There is a config file axis2.xml inside conf folder of axis2 engine using which you can enable/disable/customize various activities of axis2 engine like enable/disable MTOM support/ enable/disable SWA (SOAP with Attachment), minimum time interval for timeout, and other things.

Now our web application is fully loaded with all settings to support axis2 enabled services so we will design a small web service for example.

Steps:

• Write a web-service which is having the business logic of your application.
• Compile it to generate class.
• Create an XML file (services.xml) mentioning the path of the web-service class, name of the web-service and other details about web-service.
• Put that xml file inside the directory META-INF and bundle up this directory and compile web-service into an .aar extension file.
• Put this .aar extension file inside the services directory of axis2-enabled web server

Restart the tomcat. Now our web-service is up, and ready to serve. For this to check, you can check the working web service after entering the WSDL URL in browser.

Code of the web service example:

Here we will develop a small class which will have only one public method (exposed through WSDL).This service simply except a string called name and response back a welcome message along with the name.

Compilation of this class will require you to set the class-path of the entire jar file available in the lib directory provided inside the axis2.war. So all these jar files must be in class path. However, we will recommend you to compile this class file through Apache Ant build Tool version 1.7. Because there is limitation with environment variable, that is you can put only certain numbers of jar file. So putting 56 or more jars in class path, you need some build tool like apache Ant.

After compilation, create an xml file naming ‘services.xml’ and put this xml file inside META-INF directory. On the same level as META-INF, put your compile class with entire path here.

For example,

Suppose E:\demo axis2 is the home directory.

Then, inside it two directories,

1. META-INF\services.xml
2. ws\ DemoWS.class

Now, run command prompt, and follow path ‘E:\demo axis2’

Here, we have to create .aar extension file.

So, our axis2demo.aar is complete to upload. Copy this .aar file in the tomcat server, in webapps/yourmodule/WEB-INF/services/ folder.

Restart tomcat, to test whether service is deployed successfully or not, just put the WSDL URL in the address bar of browser as follows.

http://localhost:8080/yourmodule/services/Axis2ServiceDemo?wsdl

You will see a following scene on the successful deployment

Additional

services.xml:

services.xml is nothing but a deployment descriptor for the web service. For example, the name of web-service through which it will be exposed to the client, method or operation’s name, path of the service class etc.

Following are the contents of the example of services.xml.

Running the Client:

Below is code for client application to access this web service. To compile this client, you must have all jar files (as they were needed for service) in your class-path. For this, you can also use apache ant utility.

You will see the following output as a result…

In this article we have tried to focus on basic understanding of SOAP and its implementations in web service using axis2. In next I will focus on file attachment feature using MTOM support via axis-2.Happy coding …