TECHIE KERNEL: AXIS2

JAX-WS stands for Java API for XML Web Services. JAX-WS is a technology for building web services and clients that communicate using XML. JAX-WS allows developers to write message-oriented as well as RPC-oriented web services.

In JAX-WS, a web service operation invocation is represented by an XML-based protocol such as SOAP. The SOAP specification defines the envelope structure, encoding rules, and conventions for representing web service invocations and responses. These calls and responses are transmitted as SOAP messages (XML files) over HTTP.

Although SOAP messages are complex, the JAX-WS API hides this complexity from the application developer. On the server side, the developer specifies the web service operations by defining methods in an interface written in the Java programming language. The developer also codes one or more classes that implement those methods. Client programs are also easy to code. A client creates a proxy (a local object representing the service) and then simply invokes methods on the proxy. With JAX-WS, the developer does not generate or parse SOAP messages. It is the JAX-WS runtime system that converts the API calls and responses to and from SOAP messages.

With JAX-WS, clients and web services have a big advantage: the platform independence of the Java programming language. In addition, JAX-WS is not restrictive: a JAX-WS client can access a web service that is not running on the Java platform, and vice versa. This flexibility is possible because JAX-WS uses technologies defined by the World Wide Web Consortium (W3C): HTTP, SOAP, and the Web Service Description Language (WSDL). WSDL specifies an XML format for describing a service as a set of endpoints operating on messages.

I suggest to read the following two article before start learing the JAX-WS (SOAP) web service. I wrote these articles keeping in mind atleast you get a over all idea of web service.

Before Learning Java Web Service

XML Parsing using Java

1. JAX-WS (SOAP) Web Services:

1.1 Web Service using JAX-WS (RPC Style)

1.2 Web Service using JAX-WS (Document Style)

1.3 RPC-style vs Document-Style Web Service

1.4 Web Service using JAX-WS (MTOM)

2. Web Integration:

2.1 JAX-WS Web Integration (Glassfish Metro)

2.2 JAX-WS Web Integration (Apache Axis2)

3. Web Service Client:

3.1 Web Service Client

4. Web Service Handler:

4.1 JAX-WS Web Service Handler (Server)

4.2 JAX-WS Web Service Handler (Client)

4.3 JAX-WS Web Service with Spring

5. Problems And Tips:

5.1 Have you run APT to generate them?

5.2 Embedded error: com/sun/mirror/apt/AnnotationProce...

5.3 Cannot construct org.apache.maven.plugin.war.util....

5.4 annotations are not supported in -source 1.3

6. References:

6.1 http://jax-ws.java.net/
6.2 http://wso2.org/library/
6.3 http://javajazzup.com/
6.4 http://axis.apache.org/
6.5 http://www.mkyong.com/
6.6 http://www.vogella.com/
6.7 http://jax-ws.java.net/

Here I will demonstrate web integration of web services. I have created document style, RPC style and MTOM web services in the tutorials Web Service using JAX-WS (RPC Style), Web Service using JAX-WS (Document Style) and Web Service using JAX-WS (MTOM) respectively. Here in this tutorial, I am going to demonstrate the document style web service. I will be using the Apache Axis2 which is one of the implementation of JAX-WS. Unlike Glassfish Metro, using Apache Axis2, it is bit different and complicated.

For this tutorial I will be using the following tools

1. JDK 7

2. Eclipse Juno

3. Maven2

4. Apache Axis2
5. Tomcat 7

Most of the time web services are part of web applications, so let's deploy a web service in application server. I will not be explaining much about web services here, as I have already explained in my previous posts. In JAX-WS Web Integration (Glassfish Metro), I have discussed some of the concept about RPC and Document style web services.

This tutorial shows you how to do the following tasks:

1. Create a web service Apache Axis2.
2. Deployment in Tomcat 7.

As I told before Creating a web service using Apache Axis2 is a bit complected process, so let me provide the steps, what we are going to do exactly.

1. End Point Class Creation
2. From End point Class to WSDL generation using maven plugin
3. From WSDL to Artifact Class Generation
4. Mapping of End Point in services.xml
5. Front Controller Configuration in web.xml

Before start coding let's create a java project using the following maven command.

1	mvn archetype:generate -DgroupId=com.techiekernel -DartifactId=webservice-JAX-WS-Web-Axis2 -Dpackagename=com.techiekernel -DarchetypeArtifactId=maven-archetype-webapp

After you execute, the project will be get created with pom.xml file. As I am using JDK 7 and annotations, I have to specify the updated maven plugin. So the final pom.xml is shown bellow.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
 <modelVersion>4.0.0</modelVersion>
 <groupId>com.techiekernel</groupId>
 <artifactId>webservice-JAX-WS-Web-Axis2</artifactId>
 <packaging>war</packaging>
 <version>1.0-SNAPSHOT</version>
 <name>webservice-JAX-WS-Web-Axis2 Maven Webapp</name>
 <url>http://maven.apache.org</url>
 <dependencies>
  <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
     <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
 </dependencies>
 <build>
  <plugins>
   <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-war-plugin</artifactId>
    <version>2.0.2</version>
   </plugin>
   <plugin>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>2.5.1</version>
    <configuration>
     <source>1.6</source>
     <target>1.6</target>
    </configuration>
   </plugin>
  </plugins>
  <finalName>webservice-JAX-WS-Web-Axis2</finalName>
 </build>
</project>

End Point Class Creation:

package com.techiekernel.ws.jaxws.document;

import javax.jws.WebMethod;
import javax.jws.WebService;

public class FooBarImpl{

 public String callFooBar(String name) {
  // TODO Auto-generated method stub
  return "FooBar called by " + name;
 }

 public Server getServerDetail(String client) {
  // TODO Auto-generated method stub
  Server server = new Server();
  server.setName("Techie Kernel");
  server.setIp("192.168.1.0");
  server.setMac("12-75-61-09-12-22");
  server.setOs("Ubuntu");
  return server;
 }
}

From End point Class to WSDL generation using maven plugin:

Here we are going to use the following maven plugin to create the WSDL. Once you add the plugin to your pom.xml, you can run mvn clean install to generate the WSDL.

<plugin>
    <groupId>org.apache.axis2</groupId>
    <artifactId>axis2-java2wsdl-maven-plugin</artifactId>
    <version>1.5.4</version>
    <executions>
     <execution>
      <phase>process-classes</phase>
      <goals>
       <goal>java2wsdl</goal>
      </goals>
     </execution>
    </executions>
    <configuration>
     <className>com.techiekernel.ws.jaxws.document.FooBarImpl</className>
     <outputFileName>src/main/webapp/FooBarImpl.wsdl</outputFileName>
    </configuration>
   </plugin>

From WSDL to Artifact Class Generation:

Even for generating the artifact classes, we are going to use the maven plugin. To generate the artifact classes we have to run the same mvn clean install command. But not now.

<plugin>
 <groupId>org.apache.axis2</groupId>
 <artifactId>axis2-wsdl2code-maven-plugin</artifactId>
 <version>1.5.4</version>
 <executions>
  <execution>
   <phase>generate-sources</phase>
   <goals>
    <goal>wsdl2code</goal>
   </goals>
  </execution>
 </executions>
 <configuration>
  <classpathElements>${project.build.outputDirectory}</classpathElements>
  <wsdlFile>src/main/webapp/FooBarImpl.wsdl</wsdlFile>
  <databindingName>xmlbeans</databindingName>
  <packageName>com.techiekernel.ws.jaxws.document</packageName>
 </configuration>
</plugin>
 <plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>build-helper-maven-plugin</artifactId>
  <executions>
   <execution>
    <phase>generate-sources</phase>
    <goals>
     <goal>add-source</goal>
    </goals>
    <configuration>
     <sources>
      <source>${project.build.directory}/webservice-JAX-WS-Web-Axis2/wsdl2code/src</source>
     </sources>
    </configuration>
   </execution>
  </executions>
 </plugin>

Mapping of End Point in services.xml:

Once you map the end point, you have to place the services.xml to /webapp/WEB-INF/services/FooBarImpl/. The services.xml looks as bellow.

<serviceGroup>
 <service name="FooBarImpl" targetNamespace="http://document.jaxws.ws.techiekernel.com/">>
  <description>FooBarWsDocument</description>
  <schema schemaNamespace="http://document.jaxws.ws.techiekernel.com/" />
  <parameter name="ServiceClass" locked="false">com.techiekernel.ws.jaxws.document.FooBarImpl
  </parameter>
  <operation name="callFooBar">
   <messageReceiver class="org.apache.axis2.rpc.receivers.RPCMessageReceiver" />
  </operation>
  <operation name="getServerDetail">
   <messageReceiver class="org.apache.axis2.rpc.receivers.RPCMessageReceiver" />
  </operation>
 </service>
</serviceGroup>

Front Controller Configuration in web.xml:

We have to declare a servlet from Axis2 in web.xml, which will be acting as front controller for all the web services.

<!DOCTYPE web-app PUBLIC
 "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
 "http://java.sun.com/dtd/web-app_2_3.dtd" >

<web-app>
  <display-name>webservice-JAX-WS-Web-Axis2</display-name>
  <servlet>
        <servlet-name>AxisServlet</servlet-name>
        <display-name>Apache-Axis Servlet</display-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>
</web-app>

Now every thing is ready, so we can run the mvn clean install command to generate the war file. Let's deploy the generated war in to tomcat container. By hitting the following url, we can see the WSDL.

1	http://localhost:8080/webservice-JAX-WS-Web-Axis2/services/FooBarImpl?wsdl

Code Base:

You can download the source code from GitHub.

TECHIE KERNEL

A Technology Blog About Code Development, Architecture, Operating System, Hardware, Tips and Tutorials for Developers.

Wednesday, December 5, 2012

SOAP (JAX-WS) Web Service

Thursday, November 29, 2012

JAX-WS Web Integration (Apache Axis2)