Web services SOAP message validation

Using the Web services validation tool for WSDL and SOAP

Learn the history and the underlying technologies of Web services.Build a Web service using bottom-up development method. Transmit, receive, decrypt, validate SOAP messages and verify digital signatures of SOAP messages with the Web services validation tool for WSDL and SOAP. Explore a real world Web service such as the U.S. National Weather Service with the Web services validation tool for WSDL and SOAP.

Share:

Jinwoo Hwang (jinwoo@us.ibm.com), Software Engineer, IBM

Jinwoo HwangJinwoo Hwang is a software engineer, an inventor, an author, and a technical leader within IBM WebSphere Application Server Technical Support in Research Triangle Park, North Carolina. He is the architect and creator of the IBM HeapAnalyzer (http://www.alphaworks.ibm.com/tech/heapanalyzer) and many other technologies. He is the author of the book C Programming for Novices (ISBN:9788985553643, Yonam Press, 1995) as well as many other webcasts and articles (http://jinwoohwang.sys-con.com). He is an IBM Certified Solution Developer and IBM Certified WebSphere Application Server System Administrator as well as a SUN Certified Programmer for the Java platform.



19 May 2010

Also available in Russian Japanese

Introduction

It seems that Web Services assured a place in the pantheon of internet innovations with the advent of new technologies and standards, such as XML and HTTP. But where did the innovation originate?

The basic concept of Web Services can be traced back to the mid-1960s in the United States. The transport industry, such as railroad and shipping companies, introduced a new concept of electronic data interchange among computers, which later evolved into Electronic Data Interchange (EDI). I first heard about EDI from a business school professor in the 1980s.

In 1996, the U.S. National Institute of Standards and Technology announced the standard for Electronic Data Interchange (EDI) in the Federal Information Processing Standards Publications (FIPS PUB 161-2). According to the issued publication, EDI is the computer-to-computer interchange of strictly formatted messages. The processing of the received messages is by computer only, and is not normally intended for human interpretation. That is exactly what Web services are all about, except that they did not have XML, the Internet, or the World Wide Web back in the mid-1960s.

For those who are not so familiar with Web Services, let me briefly summarize definitions and major components of Web Services.


What are Web services?

A Web service is a software system to support interoperable machine-to-machine interaction between computational resources over a network using Simple Object Access Protocol (SOAP) messages defined by the World Wide Web Consortium.

Simple Object Access Protocol (SOAP) is a simple and extensible protocol by which structured and typed messages are exchanged in a decentralized, distributed network environment. The format of a SOAP message is written in the Extensible Markup Language (XML), a simple, flexible text format derived from the Standard Generalized Markup Language (SGML) which is developed by the International Organization for Standardization (ISO 8879:1986).

Web Services Description Language (WSDL) is an XML-based language in which an interface of a Web service is described.

What would happen if wrong SOAP messages are exchanged? What would happen if the wrong SOAP messages are processed unnoticed and even used to generate information for decision makers?

Practically, you cannot tell whether the data in a SOAP message, is correct or not. You can at least check whether a SOAP message is valid or not by looking up its interface definition, or its WSDL.

In reality, it is very challenging to debug problems in SOAP messages. If something is wrong in a SOAP message, you will receive a HTTP response code: 500 from a Web Service server. Web Services servers do not provide you with detailed information about which part of your SOAP message has problems. You could face even worse situations where you receive valid SOAP response messages from Web Services servers without any error messages but both you and Web Services servers do not realize problems in your SOAP request messages and SOAP response messages. For example, you request a stock quote of company B at a given moment but you misspell tags and send a SOAP message to a Web Services server. The Web Services server could disregard the misspelled tags and provide you with a default value such as the stock quote of company A in a SOAP response message. If this is unnoticed, this could lead to a disaster.

You can prevent these kinds of problems well ahead of time with the Web Services Validation Tool for WSDL and SOAP. You can validate SOAP messages with Web Service Definition Language (WSDL) even before Web Service applications are deployed. The tool will analyze, parse, validate your SOAP messages with WSDLs, and pinpoint problems with detailed error messages and line numbers. No more daunting HTTP response code: 500. Your SOAP messages are encrypted? No problem. The tool will decrypt them and validate decrypted SOAP messages for you.

This tool has been created to help the IBM Web Services support team that solves Web Services related problems on IBM® WebSphere Application Server reported by clients from all over the world. The tool can validate SOAP messages. If your SOAP message is encrypted, it can decrypt it and validate a decrypted message. If your SOAP message is digitally signed, it will verify the signature for you. You can even send SOAP messages to Web service servers and receive response SOAP messages with the Web Services Validation Tool for WSDL and SOAP. The tool was created to assist with avoiding production issues by using it as early as development cycle and reducing time to resolution when issues are encountered in production.

We will build a very simple Web service. First we will create a simple Java™ application. After we verify that the Java application works fine, we will use IBM Rational® Application Developer for WebSphere® Software to generate a Web service. Then we will make some changes in the generated Web service. Finally we will use the Web Services Validation Tool for WSDL and SOAP to create, validate, transmit and receive SOAP messages.

You can build a simple Web Service using the IBM Rational Application Developer for WebSphere Software. Web services can be built using 2 methods:

  1. Top-down development in which Web Service implementation Java™ classes are generated from a WSDL.
  2. Bottom-up development in which a Web Service is generated from a Java bean or enterprise Java bean.

The following example will take you through implementing a Web service using bottom up development. You will first build a simple Java application. Then, you will generate a bottom-up Java bean Web Service from the Java application using the IBM Rational Application Developer for WebSphere Software.


Creating a Java application

First, you will create a Java application that greets you. If your name is not provided, the application will return "Hello, buddy!". If your name is provided, the application will return "Hello," followed by your name. The following is the Java application DemoWebService in the package demo. The method hello() will return a string based on your name.

Listing 1. DemoWebService.java
 /*
 * @author: Jinwoo Hwang
 * Copyright 2010 IBM Corporation
 */

package demo;

public class DemoWebService {
	public String hello(String name) {
		if (name == null)
			return "Hello, buddy!";
		else
			return "Hello, " + name + "!";
	}
}

Testing a Java application

It is very important to test out the Java application before you create a Web Service from the Java application. You can write a class with a main() method to run the application. You can also utilize the Universal Test Client that is provided by IBM Rational Application Developer v7 for a quick testing without writing any test code. All you need to do is just click on the Universal Test Client from the context menu of the Java class in order to launch the Test Client.

  1. In the Universal Test Client, expand Objects > DemoWebService.
  2. Select the method hello.
  3. Enter a string or your name into the Value field and click Invoke.
Figure 1. Universal Test Client
Universal Test Client

You can also test with a null parameter to see what happens. If a null parameter is passed to the method hello(), "Hello, buddy!" is returned as expected.

Figure 2. Universal Test Client with a null parameter
Universal Test Client with a null parameter

Creating a Web service

Everything works fine so far. It is time for generating a Web service from the Java class using the bottom-up Web service development method.

  1. Select the Java application, DemoWebService and create a new Web Service from IBM Rational Application Developer.
Figure 3. Create a new XML Web service
Create a new XML web service
  1. Since you have created a Java class, select Bottom up Java bean Web service for the Web service type. Select Start client and click Finish. You could also write a Java Enterprise bean (EJB) to generate a Web service if you have an EJB class.
Figure 4. Select a service implementation
Select a service implementation

If everything goes well, you will find DemoWebServiceDelegate.java is generated in the Java Resources right next to DemoWebService.java

Figure 5. DemoWebService.java
DemoWebService.java

When taking a look at DemoWebServiceDelegate.java, you can find a Java Web service annotation, @javax.jws.WebService that specifies targetNamespace, serviceName and portName in the class DemoWebServiceDelegate. An instance of the DemoWebService is created and another method hello() is defined from the hello() method of DemoWebService. If you would like to learn more about Java Web service annotations, refer to the Java Specification Request(JSR) 181: Web Services Metadata for the Java Platform.

Listing 2. DemoWebServiceDelegate.java
/*
 * @author: Jinwoo Hwang
 * Copyright 2010 IBM Corporation
 */
package demo;

@javax.jws.WebService(targetNamespace = "http://demo/", 
        serviceName = "DemoWebServiceService", 
        portName = "DemoWebServicePort")
public class DemoWebServiceDelegate {

	demo.DemoWebService _demoWebService = new demo.DemoWebService();

	public String hello(String name) {
		return _demoWebService.hello(name);
	}

}

Creating a WSDL

In the client project, you will also find that DemoWebServiceService.wsdl and DemoWebServiceService_schema1.xsd are generated. DemoWebServiceService.wsdl contains Web Service Definition Language that describes network services for the Java application that you built previously. DemoWebServiceService_schema1.xsd contains XML schema that describes the structure of the date types used in SOAP messages.

Figure 6. DemoWebServiceService.wsdl
DemoWebServiceService.wsdl

When taking a look at DemoWebServiceService.wsdl, you can see that it has a set of definitions elements at the root. Inside of the definitions element, we can find 6 elements:

  • types
  • message
  • portType
  • binding
  • service
  • port

Types: defines data types used in message exchange. In DemoWebServiceService.wsdl, you import DemoWebServiceService_schema1.xsd instead of defining data types in the WSDL file.

Message: defines messages that are exchanged. You have 2 messages, "hello" and "helloResponse". The message hello has a part called "parameters". The part has an element "tns:hello". The message helloResponse has a part called "parameters" which happens to be the same as hello's. The part has an element "tns:helloResponse". The elements, hello and helloResponse are defined in DemoWebServiceService_schema1.xsd. You will take a look at it very soon.

Port Type: supported operations by endpoints. An operation provides an input message and output messages. You have an operation called "hello" which consists of an input message, "tns:hello" and an output message, "tns:helloResponse". It is a request-response transmission. A WSDL provides 4 different transmission primitives for an endpoint:

  • one-way
  • request-response
  • solicit-response
  • notification

In one-way transmission, an endpoint only receives a message. In request-response transmission, an endpoint receives a message and sends a corresponding message. In solicit-response, an endpoint sends a message and receives a corresponding message. In notification transmission, an endpoint only sends a message.

Binding: defines protocol details and message format specifications for operations and messages defined by a port type. You have "document" for the style attribute. The style attribute provides 2 different styles of a message, rpc and document. In rpc style, messages contain parameters and return values. In document style, messages contain documents. The value of transport attribute has the URI for the transport of SOAP. http://schemas.xmlsoap.org/soap/http means you will use the HTTP binding in the SOAP specification. You specify the URI for the SOAPAction HTTP header for the HTTP binding of SOAP in the soapAction attribute. Since you use an HTTP protocol binding of SOAP, the value of the soapAction attribute is required. You use an empty string, "" for the soapAction attribute. The soap:body element specifies how to assemble the message parts inside the body element of the SOAP message. The use attribute provides 2 different options, literal and encoded. You use literal, which means you choose a concrete schema definition using either the element or type attribute. If use is encoded, you use an abstract type with encoding rules.

Service: defines a set of related ports.

Port: defines a communication endpoint by specifying a network address for a binding.

http://localhost:9081/HelloWorldWSProject/DemoWebServiceService is the address for the SOAP endpoint.

Listing 3. DemoWebServiceService.wsdl
<?xml version="1.0" encoding="UTF-8"?> 
<definitions name="DemoWebServiceService" targetNamespace="http://demo/"
	xmlns="http://schemas.xmlsoap.org/wsdl/" 
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
	xmlns:tns="http://demo/" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<types>
		<xsd:schema>
			<xsd:import namespace="http://demo/" 
                schemaLocation="DemoWebServiceService_schema1.xsd" />
		</xsd:schema>
	</types>
	<message name="hello">
		<part element="tns:hello" name="parameters" />
	</message>
	<message name="helloResponse">
		<part element="tns:helloResponse" name="parameters" />
	</message>
	<portType name="DemoWebServiceDelegate">
		<operation name="hello">
			<input message="tns:hello" />
			<output message="tns:helloResponse" />
		</operation>
	</portType>
	<binding name="DemoWebServicePortBinding" type="tns:DemoWebServiceDelegate">
		<soap:binding style="document"
			transport="http://schemas.xmlsoap.org/soap/http" />
		<operation name="hello">
			<soap:operation soapAction="" />
			<input>
				<soap:body use="literal" />
			</input>
			<output>
				<soap:body use="literal" />
			</output>
		</operation>
	</binding>
	<service name="DemoWebServiceService">
		<port binding="tns:DemoWebServicePortBinding" name="DemoWebServicePort">
			<soap:address
				location=
                "http://localhost:9081/HelloWorldWSProject/DemoWebServiceService" />
		</port>
	</service>
</definitions>

Creating a schema

You import DemoWebServiceService_schema1.xsd from DemoWebServiceService.wsdl. Now take a look at DemoWebServiceService_schema1.xsd. It is written in the XML Schema definition language to describe the structure and constrain the content of XML documents. You have 2 elements, hello and helloResponse. Each element has a type. The hello type has an element "arg0" which is a string. The element "arg0" is optional because the value of the minOccurs attribute in its declaration is 0. If 1 or more is used for the minOccurs attribute, an element is required to appear. The same goes with the element “return” in the type helloResponse.

Listing 4. DemoWebServiceService_schema1.xsd
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="http://demo/" version="1.0"
	xmlns:tns="http://demo/" xmlns:xs="http://www.w3.org/2001/XMLSchema">

	<xs:element name="hello" type="tns:hello" />

	<xs:element name="helloResponse" type="tns:helloResponse" />

	<xs:complexType name="hello">
		<xs:sequence>
			<xs:element minOccurs="0" name="arg0" type="xs:string" />
		</xs:sequence>
	</xs:complexType>

	<xs:complexType name="helloResponse">
		<xs:sequence>
			<xs:element minOccurs="0" name="return" type="xs:string" />
		</xs:sequence>
	</xs:complexType>
</xs:schema>

Starting the Web services validation tool for WSDL and SOAP

So far you have reviewed the WSDL and the schema. Next, start the Web Service server so that you can invoke the Web Service from the Web Services Validation Tool for WSDL and SOAP.

In order to run the Web Services Validation Tool for WSDL and SOAP, you need a Java 6 (or higher) runtime environment and XML digital encryption and decryption APIs based on the World Wide Web Consortium's XML Encryption Syntax and processing specification (http://www.w3.org/TR/xmlenc-core/).

IBM Java 6 provides the implementation of JSR 106: XML Digital Encryption APIs. If you have IBM Java 6, you are ready to go and you do not need to install anything else.

If you have a Java 6 runtime environment, such as Sun Microsystems™ Java 6, and it does not provide XML Digital Encryption APIs, you need to install libraries that implement JSR 106 or the Apache™ XML Security version 1.4.3 available at (http://santuario.apache.org/). You can just download a copy of the binary distribution, uncompress it to a directory and let the tool know where the directory is using –vmargs and –DAXS command-line options.

As of this writing, the Web Services Validation Tool for WSDL and SOAP supports JSR 106 and the Apache XML Security version 1.4.3 for XML Digital Encryption and Decryption. If you want to verify digital signatures in SOAP messages, you need libraries that implement JSR 105: XML Digital Signature APIs. Fortunately, Java 6 virtual machines from Sun Microsystems and IBM provide the implementations of JSR 105. That is why Java 6 was chosen as a minimum Java runtime environment. If your Java 6 does not provide the libraries that implement JSR 105, you will need to find the libraries that support JSR 105.

You can get a copy of the Web Services Validation Tool for WSDL and SOAP at http://www.alphaworks.ibm.com/tech/wsvt for free. Installation is very simple. Uncompress the package to a directory and run wsvt.exe. If your default Java virtual machine is not the Java 6 that supports XML digital signature and digital encryption and decryption, you need to specify the location of the Java 6 with the option -vm, for example:

wsvt –vm c:\IBMjava6\bin\java.exe

Again, if you have IBM Java 6, you do not need to install anything else. Everything you need is included in IBM Java 6. If you have Java 6 from Sun Microsystems, you need to let the tool know the location of the Apache XML Security in order to decrypt encrypted SOAP messages.

For example, the following will start the tool with Sun Java 6 with the Apache XML Security library version 1.4.3, which is in the directory C:\xml-security-1_4_3\libs: wsvt –vm c:\SUNjava6\bin\java.exe –vmargs –DAXS=C:\xml-security-1_4_3\libs

The following is the list of the Apache XML security library files actually used by the Web Services Validation Tool for WSDL and SOAP even though the Apache XML security version 1.4.3 comes with 9 jar files:
commons-logging.jar
serializer.jar
xalan.jar
xmlsec-1.4.3.jar

In the MANIFEST.MF of the Web Services Validation Tool for WSDL and SOAP, we can find the following:
Bundle-ActivationPolicy: lazy
Bundle-ClassPath: .,
external:$AXS$/commons-logging.jar,
external:$AXS$/serializer.jar,
external:$AXS$/xalan.jar,
external:$AXS$/xmlsec-1.4.3.jar

That is why you needed –vmargs –DAXS=C:\xml-security-1_4_3\libs for Sun Java 6 environment to decrypt encrypted SOAP messages.

I had to spend a fairly large amount of time to resolve class loading conflict and incompatibility among the XML related classes which were found in Sun Java runtime environment, the Apache XML Security and some Eclipse plug-ins. IBM Java runtime environment was a breeze because it shipped with a JSR 106 implementation and it did not require the Apache XML Security.


Creating a project

Next, you can create a new project once the tool is up and running. You can have a WSDL file, multiple schema files associated with the WSDL file, and SOAP messages in XML files in a project. If multiple WSDL files exist in a project, only 1 WSDL file is used and other WSDL files are disregarded when a SOAP message XML file is validated. You need to create a separate project to use another WSDL file. Each SOAP message should be in a file with a .xml file extension. Otherwise it will not be treated as a SOAP message.

  1. Select New > Project to create a new project with a right-click on your mouse.
Figure 7. Create a new project
Create a new project
  1. Select Project under General.
Figure 8. Select a wizard
Select a wizard
  1. Enter "Test Project" in the Project name and click Finish.
Figure 9. Project name
Project name

Importing a WSDL and a schema

You have created a project, "Test Project". Now you can import the WSDL and the XSD into the project.

  1. Select the project and click Import from a context menu.
Figure 10. Import
Import
  1. Select File System under General.
Figure 11. Select an import source
Select an import source
  1. Select the directory where the WSDL and the XSD are stored.
  2. Select the 2 files (DemoWebServiceService.wsdl and DemoWebServiceService_schema1.xsd) and click Finish.
Figure 12. Import from file system
Import from file system

Reviewing the WSDL and the schema

Now you have a project with the WSDL and the XSD. You can double-click on the WSDL to review the WSDL in the Design mode and the Source mode. In the Design mode, you can visualize the Web Service with input and output.

Figure 13. Design mode
Design mode

In the Source mode, you can view and edit the WSDL with a text editor.

Figure 14. Source mode
Source mode

If you cannot open XSD files with an XSD Editor, you can open the XSD files with an XML Editor by selecting Open With > XML Editor from the context menu of your XSD file.

Figure 15. Open with XML Editor
Open with XML Editor

You opened the DemoWebServiceService_schema1.xsd with an XML Editor.

Figure 16. XML Editor
XML Editor

Creating a SOAP message

You have the WSDL and the schema ready for validating SOAP messages. It is time for testing out the Web Services Validation Tool for WSDL and SOAP with a SOAP message. You need to have a SOAP message in the project. The SOAP message should be in a file with a .xml file extension to be validated.

  1. Select New > XML to create a SOAP message in the project.
Figure 17. New XML
New XML
  1. Select Test Project for the parent folder of a new SOAP message. If it is not already selected, enter "DemoSOAPMessage.xml" in the File name field and click Finish.
Figure 18. Enter the parent folder
Enter the parent folder

The tool automatically brings up an XML editor with a new XML file. You have nothing but a line that has xml version and xml encoding. It is a good thing that at least you have something before creating a SOAP message from scratch. You do not know how to compose a SOAP message? Do not worry. The next section will take you through the steps of creating one.

Figure 19. New XML file
New XML file

To build a SOAP message, you can invoke the service "hello" using a parameter "parameters" with "Jinwoo" that happens to be my name. You can use your own name of course. You use the name space "http://demo/". Be careful. It is "http://demo/" not "http://demo". Yes, that makes a huge difference.

Listing 5. HelloWorldSOAPmessage.xml
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:ns0="http://demo/">
	<soapenv:Body>
		<ns0:hello>
			<parameters>Jinwoo</parameters>
		</ns0:hello>
	</soapenv:Body>
</soapenv:Envelope>

Does anyone find any problems in the SOAP message? If you do find a problem, do not worry. You will get to that later in this article.

Figure 20. DemoSOAPMessage.xml
DemoSOAPMessage.xml

Transmitting a SOAP message

Are you ready to send the message to the Web services server?

  1. Select the SOAP message and click Transmit SOAP Request and Receive SOAP Response from the Web Services Validation Tool for WSDL and SOAP.
Figure 21. Transmit SOAP Request and Receive SOAP Response
Transmit SOAP Request and Receive SOAP Response
  1. In the Transmit SOAP Request and Receive SOAP Response window, you can fill in the Service Address, SOAPAction and Content-Type. You do not need SOAPAction in this application because you used an empty string,"" for the soapAction attribute in the binding section of the DemoWebServiceService.wsdl.
  2. Enter http://localhost:9081/HelloWorldWSProject/DemoWebServiceService in Service Address if the server is on localhost:9081. Otherwise, you need to put a correct address where the Web Service is available.
  3. Select text/html for the Content-Type.
  4. Click OK to transmit the SOAP message to the server.
Figure 22. Enter service end point address
Enter service end point address

Receiving a SOAP message

If the server is up and running, you should be able to receive a SOAP response. If you do not receive any response, make sure you have a correct address and a correct content type.

Figure 23. Response
Response

Validating a SOAP message

Great. You received a SOAP response. It is also saved in the project. But wait. Do you see that something is not right? You got "Hello, buddy!" instead of "Hello, Jinwoo!". What went wrong? No clue?

Unfortunately, the Web services server did not let you know what went wrong. No error messages. No warning messages. This could lead to a very dangerous situation where unexpected SOAP responses are sent out and the Web Services server has no idea about what is wrong. Even the recipients of the SOAP responses might not notice problems in the SOAP message in question.

The Web Services Validation Tool for WSDL and SOAP will find out what is wrong.

Listing 6. Response
<?xml version="1.0" encoding="UTF-8"?>
        <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
    <ns2:helloResponse xmlns:ns2="http://demo/">
      <return>Hello, buddy!</return>
    </ns2:helloResponse>
  </soapenv:Body>
</soapenv:Envelope>

The following steps will show you how to validate the DemoSOAPMessage.xml file to see if there is any problem with the request SOAP message.

  1. Select the request SOAP message and click Validate.
Figure 24. Validate the request SOAP message
Validate the request SOAP message

The Web Services Validation Tool for WSDL and SOAP found what was wrong with the SOAP message.

Invalid SOAP message:cvc-complex-type.2.4.a:Invalid
content was found starting with element 'parameters'. One of '{arg0} is expected.
Figure 25. Invalid SOAP message
Invalid SOAP message

Editing a SOAP message

  1. The tool is complaining about "parameters". Change it to arg0 and save.
Listing 7. Edited SOAP message
<?xml version="1.0" encoding="UTF-8"?>
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
        xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 	
        xmlns:ns0="http://demo/">
	<soapenv:Body>
		<ns0:hello>
			<arg0>Jinwoo</arg0>
		</ns0:hello>
	</soapenv:Body>
</soapenv:Envelope>
  1. Validate the modified SOAP request message. You do not see the error message any more.
Figure 26. Editing a SOAP message
Editing a SOAP message
  1. You are now ready to send the modified request message to the server. Select the SOAP message and click Transmit SOAP Request and Receive SOAP Response.
Figure 27. Transmit SOAP Request and Receive SOAP Response
Transmit SOAP Request and Receive SOAP Response
  1. In the Transmit SOAP Request and Receive SOAP Response window, enter http://localhost:9081/HelloWorldWSProject/DemoWebServiceService in the Service Address field if the server is on localhost:9081.
  2. Select text/html for the Content-Type and click OK.
Figure 28. Transmit SOAP request
Transmit SOAP request

This time you got the right response that you expected.

Figure 29. Correct response
Correct response
Listing 8. SOAP response
<?xml version="1.0" encoding="UTF-8"?>
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
    <ns2:helloResponse xmlns:ns2="http://demo/">
      <return>Hello, Jinwoo!</return>
    </ns2:helloResponse>
  </soapenv:Body>
</soapenv:Envelope>

Detection of an incorrect name space

What would happen if you send an incorrect name space?

  1. Change the name space to "http://demo2/" and save.
Figure 30. Change name space
Change name space
Listing 9. Name space change
<?xml version="1.0" encoding="UTF-8"?>
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 	
    xmlns:ns0="http://demo2/">
	<soapenv:Body>
		<ns0:hello>
			<arg0>Jinwoo</arg0>
		</ns0:hello>
	</soapenv:Body>
</soapenv:Envelope>
  1. Then, you can send the request to the server.
Figure 31. Transmit message
Transmit message

You see an IOException : Server returned HTTP response code:500 for URI: http://localhost:9081/HelloWorldWSProject/DemoWebServiceService.

Figure 32. IOException
IOException

The Web services server did respond with an IOException, but that was not enough information for you to find out what went wrong. Validate the message with the tool to see if you can get better information to solve the problem.

Figure 33. Validate message
Validate message

The tool says "Invalid SOAP message:cvc-complex-type.2.4.a:Invalid content was found starting with element ‘ns0:hello'. One of '{"http://demo/":hello,"http://demo/":helloResponse}' is expected."

It points out that "http://demo/" is expected. That is exactly what you wanted to know, not the HTTP response code 500.

Figure 34. Invalid SOAP message
Invalid SOAP message

Validating encrypted SOAP Messages

What if your SOAP messages are encrypted? That is not a problem at all as long as you have keys and passwords. Just select your SOAP message and click Validate just like any other plain SOAP messages. If your SOAP message is encrypted, you will be prompted with a screen similar to the following:

Figure 35. Keystore selection
Keystore selection

As of this writing, 3 types of keystore are supported:

  1. Java Key Store (JKS)
  2. Java Cryptography Extension Key Store (JCEKS)
  3. Personal Information Exchange Syntax Standard (Public Key Cryptography Standards #12)

You need to provide information about your keystore: file name, file type and password. If the information is correct, you need to select a key and a password. You can also find the information about your keystores and list of keys and certificates in the keystore such as keystore type, provider name, provider version, provider information, key type, creation date, certificate type, algorithm and format.

Figure 36. Key selection
Key selection

If all information is correct, the tool will generate a decrypted SOAP message and validate the message for you.

Figure 37. Decrypted SOAP message
Decrypted SOAP message

Currently the following encryption algorithms are supported:

  • If Advanced Encryption Standard (AES) in the Cipher Block Chaining (CBC) mode with an initialization vector (128/192/256 bit)
  • Advanced Encryption Standard (AES) Key Encryption (128/192/256 bit)
  • Triple Data Encryption Algorithm Modes of Operation (triple-DES) Key Encryption
  • Triple Data Encryption Algorithm Modes of Operation (triple-DES) Key Encryption in the Cipher Block Chaining (CBC) mode
  • RSA Cryptography Specifications Version 1.5
  • RSA Optimal Asymmetric Encryption Padding (OAEP) method with mask generation function

Verifying digitally signed SOAP messages

What if your SOAP message is digitally signed? Just select the SOAP message and click SOAP Message Digital Signature Verification.

Figure 38. SOAP Message Digital Signature Verification
SOAP Message Digital Signature Verification

If the digital signature is valid, you will find the following screen:

Figure 39. Valid SOAP Message Digital Signature
Valid SOAP Message Digital Signature

Otherwise, the tool will tell you that the signature is invalid. Currently the following digital signature algorithms and specifications are supported:

  • Secure Hash Algorithm 1 (SHA-1)
  • Hash Message Authentication Code (HMAC)
  • Digital Signature Algorithm (DSA)
  • Public-Key Cryptography Standards (PKCS #1)
  • RSA Encryption Algorithm with Secure Hash Algorithm (SHA-1)
  • Canonical XML Version 1.0 and 1.1
  • XSL Transformations (XSLT) Version 1.0
  • XML Path Language (XPath) Version 1.0
  • Base64

Accessing the U.S. National Weather Service with a SOAP message

Everything looks good with the simple Web Service you created and tested. Can you use this tool in "real" environment? You can try a production Web Service which is provided by the U.S. National Oceanic and Atmospheric Administration (NOAA)'s National Weather Service.

  1. Create a project.
Figure 40. Create a project
Create a project
  1. Create a SOAP message XML.
Figure 41. Enter the parent folder
Enter the parent folder
Figure 42. New XML file
New XML file

The U.S. National Weather Service operates the National Digital Forecast Database (NDFD) which can be retrieved via Simple Object Access Protocol (SOAP) Web Service. Detailed information can be found at http://www.weather.gov/forecasts/xml/.

There are a lot of different Web Services provided by the U.S. National Weather. You can try a service called NDFDgenByDay which offers weather forecasts for a given location identified by latitude and longitude.

In order to access NDFDgenByDay, you need to provide the following information:

Table 1. NDFDgenByDay
Service NameNDFDgenByDay
Endpointhttp://www.weather.gov/forecasts/xml/SOAP_server/ndfdXMLserver.php
SoapActionhttp://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl#NDFDgenByDay
encodingStylehttp://schemas.xmlsoap.org/soap/encoding/
Namespacehttp://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl
latitudeDecimal
longitudeDecimal
startDateDate
numDaysInteger
formatString

In this example, you want to build a request SOAP message that gets a 7 day forecast for a location (LAT38.9,LON-77.01) starting 2010-07-23 with 24 hourly format:

Listing 10. Request SOAP message
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
	<SOAP-ENV:Body>
		<ns6244:NDFDgenByDay>
			<latitude xsi:type="xsd:string">38.99</latitude>
			<longitude xsi:type="xsd:string">-77.01</longitude>
			<startDate xsi:type="xsd:string">2010-07-23</startDate>
			<numDays xsi:type="xsd:string">7</numDays>
			<format xsi:type="xsd:string">24 hourly</format>
		</ns6244:NDFDgenByDay>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

You did not define the namespace because it worked without the namespace. If you encounter any namespace problems, make sure to define the namespace.

Figure 43. Created SOAP the namespace
Created SOAP the namespace

Select the message and click Transmit SOAP Request and Receive SOAP Responsefrom the Web Services Validation Tool for WSDL and SOAP.

Table 2. Request information
NameValue
Endpoint http://www.weather.gov/forecasts/xml/SOAP_server/ndfdXMLserver.php
SoapAction http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl#NDFDgenByDay
Content-typetext/xml; charset=utf-8
Figure 44. Transmit request
Transmit request

You received weather forecast data from the U.S. National Weather Service! It is hard to read because of the HTML special entities.

Figure 45. Response message
Response message

You can change the file extension to .html and view it with a Web browser to convert the HTML special entities.

Figure 46. Renaming xml file
Renaming xml file
Figure 47. New name
New name

Then open the HTML with a Web browser.

Figure 48. Open with a Web browser
Open with a Web browser

Now you can see the XML output. However, it is still challenging to read the content because it is not formatted.

Figure 49. XML output
XML output

You can just copy the content and create a new XML document to format.

Figure 50. Copying XML
Copying XML

Create a new XML file, paste and format.

Figure 51. New XML file
New XML file

Finally, the forecast data is much easier to read.

Figure 52. Formatted message
Formatted message

If you find that this tip is not your favorite one, you can use your own method to format the HTML output. Most Web Services offer XML output so you do not need to do this trick all the time.


Conclusion

We have created, transmitted, received and validated SOAP messages using the Web Services Validation Tool for WSDL and SOAP. The Web Services Validation Tool for WSDL and SOAP can pinpoint problems that most Web Service Servers do not even detect, which could lead to a serious disaster in real world. If this tool is used in development stage, we can reduce to resolution when issues are encountered in production.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into SOA and web services on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=SOA and web services
ArticleID=489490
ArticleTitle=Web services SOAP message validation
publish-date=05192010