What is SOAP according to W3C Definition
“SOAP is a lightweight protocol intended for exchanging structured information in a decentralised, distributed environment. It uses XML technologies to define and extensible messaging framework providing a message construct that can be exchanged over a variety of underlying protocols. The framework has been design to be independent of any particular programming model and other implementation specific semantics.”
Simple Object Access Protocol
- Wire protocol similar to IIOP for CORBA and JRMP for RMI
- XML is used for data encoding – text and binary based protocol
- Supports XML-based RPC (Remote Procedure Call) to ease the migration of existing RPC distribution schemes to SOAP based system (note that this approach is not being used anymore because of the introduction of RMI.
It is extremely important that any Java/J2EE developers understand the concept of how SOAP works as this will allow them to build better application that communicates and integrates with other systems. Like any other fundamentals, it is better to understand the underlying concepts.
Most of the time though, developers will be using a high-level API (JAX-WS) implementations to build these services thus the actual mechanism of SOAP is hidden.
Characteristic of SOAP
- By default, SOAP is stateless but ultimately can be used to do stateful transactions (pass the state data to the object).
- One way message exchange paradigm: Applications can create more complex interaction patterns by combining such one way exchange with features provided by underlying protocol (http), application specific information and higher level standard (such as “WS-Addressing”).
- SOAP is silent on the semantics of any application-specific data it conveys. It doesn’t really care what kind of data (XML is only a recommendation as it’s a universal format – meaning any platform understands and can parse this kind of structure).
Design Goals of SOAP
- Simplicity
- Extensibility
- Although it does offer the above, it doesn’t support advance support distributing features such as distributed GC, object by reference, activation and message batching.
SOAP Message Structure
SOAP Message Envelope
- Embedded information includes the namespace and encoding information
- Header (Optional)
- Body (Mandatory) – handled by the receiver
SOAP Header (<env:header>)
- Used for extension (context, authentication, transaction, management)
- Made of header blocks (composition of header blocks)
- Most Web Service standard activities are basically defining standard header entries for a particular domain.
SOAP Header Blocks (Entries)
- Child Elements of SOAP Header
- Designed in anticpation of arious uses for SOAP
- Inspected, inserted, deleted or forwarded by SOAP nodes encountered on the SOAP Message Path.
SOAP Body (<env:Body>)
- Composition of body blocks
- consumed by SOAP receiver
- Carry end to end information (XML, RPC Methods and Parameters, SOAP Fault – exceptions)
- SOAP Fault Messages
Fault Messages
If there are any errors encountered during the communication or any exceptions, a fault message will be thrown back to the client to allow it to handle the issue gracefully. There are pre-defined SOAP fault code values.
- VersionMisMatch (invalid namespace in SOAP envelope of version mismatch)
- MustUnderstand (Receiver does not understand and therefore cannot handle the mustUnderstand SOAP header block)
- Client (client side communication error)
- Server (server side communication error)
This can be used to return any readable exceptions to the client. This is extremely useful and a must do for anyone who creates web services.
Code Example
Concepts aside, let’s deep dive on the code example. I used NetBeans to create the example.
Tech Stack: NetBeans IDE with Java/Java EE, Glassfish Application Server
These are all bundled with NetBeans IDE if you download it from their site.
Project: Download it here.
The Web Service
Create a new Web Application Project.
Create a simple Java Class and #Annotate
@WebService
public class SampleWebService {
/**
* Show Message
* @param message
* @return
*/
@WebMethod
public String showMessage(String message){
return message;
}
}Deploy the Web Service Application to Glassfish
Test the Web Service using the “Test Web Service” option
After clicking the test below, a web page will be launched that will allow you to test the actual WebService method.
You can test the actual service by passing a value and clicking on the “showMessage” button.
You can also access the WSDL file from the link provided. You can see the SOAP definitions, namespaces and entries.
The Client
Not that hard to expose a service but what will it be without any clients using it? Let’s build a client that will actually call the Web Service. Once again, NetBeans provides us with a facility to create stubs and objects given a WSDL URL. Allowing use to focus on consuming the service.
Create a new Java Project
Create a new Web Service Client within the Java Project
NetBeans IDE has a great feature to create Web Service Client. Beautifully and Gracefully creates the necessary objects given your WSDL.
Provide the WSDL URL and your set.
Generated Source Code that your client can use
Call Web Service from the Client
After the stubs are generated, you can now call it from your project
/**
*
* @author alvinreyes
*/
public class SampleWebServiceClient {
/**
* @param args the command line arguments
*/
public static void main(String[] args) {
System.out.println(showMessage("Hello"));
}
private static String showMessage(java.lang.String arg0) {
com.areyes.soap.sample.SampleWebServiceService service = new com.areyes.soap.sample.SampleWebServiceService();
com.areyes.soap.sample.SampleWebService port = service.getSampleWebServicePort();
return port.showMessage(arg0);
}
}
Build your project before running the client. This will allow your project to recognize the new Java classes and packages.
wsimport-client-SampleWebServiceService: files are up to date wsimport-client-generate: Compiling 1 source file to /Users/alvinreyes/NetBeansProjects/SampleWebServiceClient/build/classes compile-single: run-single: Hello BUILD SUCCESSFUL (total time: 3 seconds)
You can download the actual project here
| Reference: | SOAP Web Services from our JCG partner Alvin Reyes at the Alvin “Jay” Reyes Blog blog. |
