Java SOAP Web Service Tutorial with Sample Case Study

This tutorial is purely on programming SOAP Web Services with JAVA. First of I will give a sample case study. Then I will implement the same. By reading this article, You can learn the implementation of SOAP web services with JAVA. You need to have Tomcat server configured Eclipse.

What is SOAP :

SOAP stands for Simple Object Access Protocol. We can send messages by using this Protocol. SOAP is based on XML, so it is independent of programming platform.
SOAP Message Syntax :

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

<soap:Header>
...
</soap:Header>

<soap:Body>
...
  <soap:Fault>
  ...
  </soap:Fault>
</soap:Body>

</soap:Envelope>

SOAP Body contains message
SOAP Header contains data other than message (Authentication info, Login User ID...etc)
SOAP Fault contains reason for failure.

Case Study :

This project is for maintaining Employee information. We have to convert below Case Study into Web Service project.

Create Employee Class
Create EmployeeService Class with methods createEmployee(String id, String name, String email), deleteEmployee(String id), selectEmployees()
Create one global HashMap to maintain Employee Info.
createEmployee is for creating employees, This method takes Employee object as input and returns String
deleteEmployee is for deleting employees, This method takes Employee ID (String) as input and returns String
selectEmployees is for reading all employee info. This method returns List of Employee details

Annotations :

@WebService Annotation

@WebService(
        portName = "EmployeePort",
        serviceName = "EmployeeService",
        targetNamespace = "http://blog.sodhanalibrary.com/wsdl",
        endpointInterface = "com.services.EmplyeeInterface"
)

This annotation is for java class which works as Sevice

portName - specifies wsdl:port

serviceName - specifies Service Name

targetNamespace - specifies Namespace for WSDL

endpointInterface - java interface class which Service class implements

@WebMethod Annotation

This annotation is for method in service class which implements functionality
action - specifies SOAP action
operationName - specifies soap:operation
exclude - exclude the method from Web Service

@WebMethod(action="create",
           operationName="createEmployee",
           exclude=false
          )

@WebParam Annotation

This annotation is for defining request parameters.

@WebParam(name = "i") int i

Setup Apache Axis2

Apache Axis 2 is Web Service engine which supports SOAP messages.

Axis2 Preferences

Download the Axis 2 binary distribution (here)
Extract it
Enter Eclipse and go to Window > Preferences > Web Services > Axis2 Preferences
In the Axis2 runtime location field, points to your Axis2 installation directory (the one you created in step 2)
Click Apply
Close Preferences and try again

Server and Runtime

Enter Eclipse and go to Window > Preferences > Web Services > Server and Runtime
In the Web Service runtime field, points to your Axis2 installation directory (the one you created in step 2)
Click Apply
Close Preferences and try again

Setup Chrome / Firefox SOAP Web Service Testing Plugin

Install Wizdler in chrome. You can find this plugin here

Install SOA Client for Firefox. You can find this plugin here

Implementation

Create New Dynamic Web Project SimpleSoapExample in Eclipse

Create com.services java package

Create Employee Pojo Class

package com.services;

public class Employee {
    String id;
    String name;
    String email;
    
    public String getId() {
        return id;
    }
    public void setId(String id) {
        this.id = id;
    }
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
    public String getEmail() {
        return email;
    }
    public void setEmail(String email) {
        this.email = email;
    }
}

Create EmployeeList Pojo class like below
Here I have used Employee Array because JAX-RPC doesn't support any collections. This class is for showing list of Employees

package com.services;

public class EmployeeList {
    private Employee[] employeeList;
    private int count;

    public Employee[] getEmployeeList() {
        return employeeList;
    }

    public void setEmployeeList(Employee[] employeeList) {
        this.employeeList = employeeList;
    }

    public int getCount() {
        return count;
    }

    public void setCount(int count) {
        this.count = count;
    }   
}

Create below EmployeeService class in the com.services package
This is Service class. We can access methods in this class through SOAP web service

package com.services;

import java.util.HashMap;
import java.util.Map.Entry;
import java.util.Set;
import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebResult;
import javax.jws.WebService;

@WebService(
        portName = "EmployeePort",
        serviceName = "EmployeeService",
        targetNamespace = "http://blog.sodhanalibrary.com/wsdl"
)
public class EmployeeService {
    private static HashMap<String,Employee> empData = new HashMap<String,Employee>();
    

    @WebMethod(action="create",
            operationName="createEmployee",
            exclude=false)
    @WebResult(targetNamespace = "http://blog.sodhanalibrary.com/wsdl")
    public String createEmp(@WebParam(name = "id") String id,@WebParam(name = "name") String name,@WebParam(name = "email") String email ) {
        Employee emp = new Employee();
        emp.setId(id);
        emp.setEmail(email);
        emp.setName(name);
        empData.put(emp.getId(), emp);
        return "success";
    }
    
    @WebMethod(action="delete",
            operationName="deleteEmployee",
            exclude=false)
    @WebResult(targetNamespace = "http://blog.sodhanalibrary.com/wsdl")
    public String deleteEmp(String empID) {
        empData.remove(empID);
        return "success";
    }
    
    @WebMethod(action="read",
            operationName="readEmployee",
            exclude=false)
    @WebResult(targetNamespace = "http://blog.sodhanalibrary.com/wsdl")
    public EmployeeList readEmp() {
        EmployeeList empListPojo = new EmployeeList();
        Set<Entry<String, Employee>> eset = empData.entrySet();
        int i=0;
        Employee[] empList = new Employee[empData.size()]; 
        for(Entry<String, Employee> en : eset) {
            empList[i] = en.getValue();
            i++;
        }
        empListPojo.setEmployeeList(empList);
        empListPojo.setCount(empData.size());
        return empListPojo;
    }    
}

Generate web service

Right click on the project, click on New > Web Service. Make web service configuration as like below.

Click on Browse and select EmployeeService class

Then click Finish

Test the Service

Add the project to tomcat and start the server. Open http://localhost:8080/SimpleSoapExample/services/EmployeeService?wsdl in chrome / firefox browser. Then you can see the SOAP Service testing plugin icon like below.

Click on those links and test respective web services.

SOAP UI Eclipse Plugin

Install plugin

Download SOAP UI Eclipse plugin from here.
Click on Help > Install New Software > Add
Enter "SOAP UI" in the name field.
Click on Archive.. and select downloaded eclipse plugin archive file

Create New SOAP UI Project

Click on Window > Open Perspective > Other > soapUI

Right click on Projects > New soapUI Project

Enter "http://localhost:8080/SimpleSoapExample/services/EmployeeService?wsdl" in the Initial WSDL/WADL

Click on OK

Test the web service

Now it will show all web methods to test (createEmployee, deleteEmployee, readEmployee).

→	Convert XML or JSON to Java Pojo Classes
→	Change Icon Color Online

SodhanaLibrary