Testing web services. Validating a SOAP Message
SOAP (Simple Object Access Protocol) is a standardized protocol for transmitting messages between a client and a server. It is typically used in conjunction with HTTP(S), but can also work with other application layer protocols (such as SMTP and FTP).
Testing SOAP from the point of view of testing techniques is no fundamentally different from working with other APIs, but it requires preliminary preparation (in terms of protocol theory) and special testing tools. In this article, I would like to formulate a small checklist of necessary knowledge and skills, which will be equally useful both to a SOAP tester (who often has no idea what to grab hold of after setting the task) and to a manager who is forced to evaluate the knowledge of testers and develop plans for training.
Theoretical basis
The fact that SOAP is a protocol has a lot of implications for testing: you need to study the protocol itself, the "primary" standards and protocols on which it is based, and (as necessary) existing extensions.
XML
XML is a markup language similar to HTML. Any message sent/received via SOAP is an XML document in which the data is conveniently structured and easy to read, for example:
Don't forget to write an article!
You can learn more about XML at w3schools or codenet (in Russian). Be sure to pay attention to the description of namespaces (a method for resolving conflicts when describing elements in XML) - their use is required in SOAP.
XSD
When working, it is always convenient to have a standardized description of possible XML documents and check them for correct filling. There is an XML Schema Definition (or XSD for short) for this purpose. The two main features of XSD for a tester are the description of data types and the imposition of restrictions on possible values. For example, the element from the previous example can be made optional and limited to 255 characters using XSD:
...
...
SOAP Extensions
In your work, you may also come across various “extensions” of SOAP - standards like WS-*. One of the most common is WS-Security, which allows you to work with encryption and electronic signatures. Often, WS-Policy is used along with it, with which you can manage the rights to use your service.
Example of using WS-Security:
All these extensions are quite complex structures that are not used in every SOAP service; their detailed study at the initial stage of mastering SOAP testing is unlikely to be relevant.
Tools
As you already understand, SOAP is a serious matter; to work with it you need to know the theory and numerous standards. In practice, such complexity would lead to very significant labor costs (for example, you would have to look at the diagram in a notebook every time and send requests with curl). Therefore, tools have been created to make working with SOAP easier.
XML/XSD editors
A good tester begins testing at the stage of writing documentation, so it is convenient to use special editors to test circuits. The two most famous are Oxygen (cross-platform) and Altova (Windows only); both of them are paid. These are very powerful programs that analysts actively use when describing services.
In my practice, three editor features turned out to be useful: XSD visualization, XML generation based on XSD, and XML validation based on XSD.
1. XSD visualization needed for a visual representation of the diagram, allowing you to quickly identify the required elements and attributes, as well as existing restrictions. For example, for a CheckTextRequest, the text element is required, and all three attributes are optional (with the options attribute having a default value of zero).
Visualization is necessary when there are many types and restrictions in the diagram. If you only need this and don't want to pay for special editors, then you can consider free alternatives (for example, JDeveloper).
2. XML generation based on XSD useful when you want to see a valid example of a message. I use it to quickly experiment with possible message completions and test the nuances of how restrictions work.
3. After using the feature from point 2, it is useful to carry out XML validation against XSD– that is, check the message for correctness. Together, features 2 and 3 allow you to catch tricky defects in XSD even when the service itself is under development.
Testing Tool – SoapUI
SOAP testing almost always involves using SoapUI. You can read about using this tool in various sources (,), but it will be most effective to read the official documentation. I identify 8 conditional levels of SoapUI proficiency:
Level 1 – I can send requests
Learn to create a project based on WSDL. SoapUI can generate all the necessary queries for you; you just have to check the correctness of their filling and click the "Send" button. After you have mastered the art of making valid queries, you must master the art of making invalid queries that cause errors.
Level 2 – I can do Test Suites and Test Cases
Start doing mini-autotests. Test suites and test cases allow you to create API test scripts, prepare data for requests, and automatically check the received response against the expected one. At first, they can be used simply as collections of queries. For example, if you have a defect and want to quickly check it after a fix, you can allocate a separate test suite specifically for defect requests.
Level 3 – I can write Assertions
After mastering test cases, it will be useful for you to learn how to make them automatically verifiable. After that, you will no longer need to look for information about the answer with your “eyes”: if there is an automatic check, the cases will be marked green (if the check is passed) or red (if it is not passed). SoapUI provides a large set of possible checks (assertions), but the most convenient and simple are Contains and Not Contains. With their help, you can check the presence of a particular text in the received response. These checks also support regular expression searches.
Level 4 – use XPath and/or XQuery in Assertions
For those who are a little familiar with UI using Selenium, the XPath language is a familiar thing. Roughly speaking, XPath allows you to search for elements in an XML document. XQuery is a similar technology that can use XPath internally; this language is much more powerful, it resembles SQL. Both of these languages can be used in Assertions. Checks with their help are more targeted and stable, so your cases will be more credible.
Level 5 – I can write complex tests using special steps
Test cases can contain not only one request, but also several (for example, when you want to emulate the standard user scenario “create entity” → “export entity”). There may be other special steps between requests, for example:
- Properties and Property Transfer (help reuse data and transfer it between requests);
- JDBC Request (used to retrieve data from the database);
- Conditional Goto (allows you to make branches or loops in the test case);
- Run TestCase (helps to put some typical queries into separate test cases and call them where needed).
Level 6 – using Groovy scripts
SoapUI allows you to write Groovy scripts in a variety of places. The simplest case is to generate data in the query itself using $(=) inserts. I use these inserts all the time:
- $(=new Date().format(“yyyy-MM-dd’T’HH:mm:ss”))– to insert the current date and time in the required format;
- $(=java.util.UUID.randomUUID())– to insert a correctly formed random GUID.
Full-fledged scripts can be used as steps in cases and checks. At some point, you will discover that several special steps from the fifth level can be replaced with one script.
Level 7 – using MockServices
WSDL-based SoapUI can generate Mock objects. A mock object is the simplest simulation of a service. With the help of “mocks” you can start writing and debugging test cases even before the service is actually available for testing. They can also be used as “stubs” for temporarily unavailable services.
Level 8 – SoapUI God
You know the difference between the paid and free versions of SoapUI and use the SoapUI API in your code. You use plugins and run cases through the command line and/or CI. Your test cases are simple and easy to maintain. In general, you "ate the dog" on this instrument. I would love to talk to someone who has mastered SoapUI at this level. If you are one, sign up in the comments!
Testing with Programming Languages
Here's an example of what a request to the YandexSpeller API looks like, made using groovy-wslite:
import wslite.soap.*
def client = new SOAPClient("http://speller.yandex.net/services/spellservice?WSDL")
def response = client.send(SOAPAction: "http://speller.yandex.net/services/spellservice/checkText") (
body(
CheckTextRequest("lang": "ru", "xmlns":"http://speller.yandex.net/services/spellservice") (
text("error")
}
}
}
assert "error" == response.CheckTextResponse.SpellResult.error.s.text()
assert "1" == [email protected]()
As far as I know, there are no high-level frameworks (like Rest-assured) for SOAP testing yet, but an interesting tool has recently appeared - karate. With its help, you can describe cases for testing SOAP and REST in the form of scripts like Cucumber / Gherkin. For many testers, turning to karate will be an ideal solution, because such scenarios, in terms of the complexity of writing and supporting cases, will lie somewhere in the middle between using SoapUI and writing your own framework for testing SOAP.
Conclusion
It is unlikely that you will ever want to test SOAP just for yourself (as you might with REST). This is a heavyweight protocol that is used in serious enterprise solutions. But its heaviness is at the same time a gift to the tester: all the technologies used are standardized, and there are high-quality tools for work. All that is required from the tester is the desire to learn and use them.
Let's put together the same checklist of necessary skills for a tester. So, if you are just starting to test SOAP services, you need to know and be able to use:
- WSDL.
- SOAP.
- XML/XSD editors (at the XSD visualization level).
- SoapUI at level 1.
As you can see, the main emphasis is on learning the standards; in SoapUI it’s enough just to be able to execute queries. As you dive into SOAP testing, you will encounter tasks that will require more serious skills and knowledge, but you should not try to learn everything at once. Consistency in increasing the level of complexity of the tasks performed is much more important. By following this recommendation, one day you will realize that you have become a good specialist in this field!
Nowadays, it is rare for a modern application to function without an API. This is true both for a simple website and for highly loaded distributed systems. API testing is one of the main tasks in the quality assurance process. It is not surprising that the demand for testers who know how to test APIs is increasing day by day. In this course, you will gain an understanding of methods, tools and approaches in API testing, and acquire the necessary knowledge, which will undoubtedly have a positive effect on your value as a testing specialist.
This course will be useful for students familiar with the basics of software testing who want to grow further and improve their skills.
Course program:
Lesson 1. Introductory. SOAP protocol
- Briefly about the lecturer;
- Course objectives;
- What is API, WS and why are they needed;
- The role of API testing in the quality assurance process;
- Review of WS testing tools;
- Methods used in WS testing;
- History of SOAP;
- Terminology and main concepts (XML, XSD, Endpoint, WSDL).
Lesson 2: SOAP Protocol. REST architecture
- Terminology and main concepts (UDDI, XSLT, XPath, XQuery, HTTP methods, HTTP statuses);
- Structure and main components of SOAP;
- Scope of application;
- Features of work;
- Advantages and disadvantages;
- Features of REST architecture;
- Terminology and main concepts (WADL, RESTful, JSON, JSONPath);
- REST principles;
- Status code and main statuses;
- CRUD verbs;
- Advantages and disadvantages.
Lesson 3. Introducing SoapUI. Working with a REST project
- Java installation;
- Installing SoapUI;
- Overview of the main interface elements;
- Connecting an educational project;
- Review of project methods;
- Sending a request and analyzing the received response;
- Studying the available web services of the project;
- Drawing up a test plan;
- Writing test cases;
- Elements “TestSuite”, “TestCase”, “TestSteps”.
Lesson 4. Working with REST project (XML)
- “Assertions” block;
- Running tests at various levels;
- Element “Properties”, main capabilities;
- Working with Properties;
- “Property Transfer” element;
- Working with Assertions.
Lesson 5. Working with REST project (JSON)
- Conditions and branches;
- Working with Assertions;
- TestRunner, features of work;
- Launch TS, TC from the command line;
- Working with Test runner;
- Working with Groovy scripts.
Lesson 6. Working with Groovy scripts
- Working with static and dynamic data;
- Generating test data;
- We get data from “Properties”;
- Data recording and transfer;
- Conditions and branches;
- Script Assertion.
Lesson 7. Additional features
- Connecting external libraries and custom classes;
- Mock services;
- Why do we need Mock services?
- An example of working with a Mock service;
- What about CI?
- Install Jenkins;
- Launching a project on Jenkins.
Web services in 1C
This article will consider the integration of 1C with existing web services and the use of 1C itself as a web service.
At the same time, web services will be understood as systems operating on the Internet and providing interaction with them not only via SOAP (which is exactly a web service), but also in other ways, including ordinary HTTP (S) requests.
Risks of using 1C web services
The 1C81 platform introduced the implementation of web services.
But their use is fraught with risks:
- 1C8 does not work well over HTTPS, there are no diagnostic tools, so it is sometimes impossible to understand why, if a service has a certificate, it does not want to work through HTTPS. The solution is to implement web services via CURL or raise an HTTPS tunnel.
- 1C8 adheres to its rules for validating WSDL schemas. Sometimes, for inexplicable reasons, the WSDL schema does not want to be loaded into the WS link. You can find out the reason only on the partner forum from one specialist. There are no diagnostic tools for the WSDL schema, not even a reason or a line at which the schema load is interrupted.
Rules for building sales services
The client is issued a document of sale (receipt) only if the transaction for the service was successful. Otherwise, a situation is possible when the client will receive a check and be sure that he received the service, but in fact it is not.
Using external SOAP services
SOAP web services use WSDL schemas and XDTO objects to represent data.
Loading WSDL
In order to use an external service, you need to download its WSDL schema.
Checking the validity of the WSDL schema
Sometimes the WSDL schema does not load into 1C. You can check the validity (correctness) of the schema with any WSDL schema validator, for example http://www.validwsdl.com/ .
You need to upload the scheme to some http site (you can use ftp) and specify the address of the file where the scheme is loaded:
Features of loading WSDL in 1C
The peculiarity of loading WSDL in 1C is that valid schemas may not be loaded. There is no built-in validator, so you have to look for an error using the destructive analysis method, successively reducing the number of elements in the schema. You can, for example, delete the web service description.
Processing for testing a running external web service
To test a running external web service, use the "TestArbitraryWebService.epf" processing from the package for this article.
Testing can be used on the example of the Morpher service that declines names (service address http://www.morpher.ru/WebServices/Morpher.asmx?WSDL):
In this way, you can test any service that has simple entry points containing parameters of simple types: number, date, string.
In processing, you can also specify the login and password that are required to authorize access to the web service.
Standard tools for debugging services
For debugging, you can use the SoapUI program, which can send an arbitrary request to a web service and receive a response from it.
SOAP and HTTPS
Unfortunately, SOAP in 1C behaves rather capriciously when working through the HTTPS protocol, practice shows that it is impossible to achieve an HTTPS connection, although the possibility is declared in the platform. There is a lack of diagnostic and debugging tools to find out the reasons why the connection is not established. Therefore, it is convenient to use SOAP via CURL.
The built-in mechanism for using HTTPS implies that all certificates must be published in a common pem file in the 1C program directory.
Using 1C as a service
Rules for developing a service based on 1C
Operation Hello
It is good practice to create an operation in the service that informs that the service is available. This makes life easier for integrators, it will be easier for them to check whether the connection with the service is established.
For example, you can use the Hello operation with no parameters, which simply returns the boolean value True.
Publishing a web service
The procedure is well described in the documentation: file:///C:/Program%20Files/1cv81/AddDoc/RU/V8AddDoc81.htm#_Toc176167634 :
The task of publishing Web services comes down to placing the *.1cws configuration files of Web services in the appropriate directory of the web server with the appropriate settings for the web server. In order to publish Web services, you should execute the menu command “Administration | Publishing Web services."
As a result of executing this command, the Web services publishing window will open.
The Web services publishing window contains the path to the web server and two lists:
- “Web services” - list of configuration web services;
- “Publication” - a list of Web services published on the specified web server.
Using the "Connection..." button, you should specify the web server on which you want to publish Web services.
The web server path selection window allows you to specify the path in two ways:
- on the “Files” tab - this method is used when publishing is performed on the same computer on which the web server is installed. The path is a local directory corresponding to the Internet page from which the published Web server will be called;
- on the “FTP site” tab - this method is used when you need to publish a Web service on a remote computer. To publish, you must specify the parameters of the FTP connection to the remote computer and the directory in which the Web service will be published.
The selected Web service is published using the “Publish” button
To cancel publishing a Web service, use the “Delete” button.
You can publish to a local directory or via FTP. You can also publish to a remote server via a UNC path if the remote server is part of the local network.
After publication, the web service is available at the address “http://localhost/test.1cws” or “http://xxx.ru/test.1cws”, where xxx.ru is the address of the remote server and localhost is the typical address of the local server.
Authorization to the 1C web service
To access the service you need to pass authentication.
Authorization issues are well addressed here: http://www.forum.mista.ru/topic.php?id=341168 and in the documentation file:///c:/Program%20Files/1cv81/AddDoc/RU/V8AddDoc81.htm
Typically, a web service runs under one specific user (usually a specially created one). You can “attach” a 1C user using Windows authentication to the Windows user IUSR_ (disable 1C authorization for the user). Alternatively, you can clear the list of 1C users, then authorization is not required.
If several users are required, then you can create several logins for the web server, bind a Windows user to each of them and, accordingly, register access to Windows users in 1C.
The User and Password properties of the WSProxy object do not use the 1C login, but the login of the web server user.
Testing 1C web service
To test 1C as a web service, use the "TestArbitraryWebService.epf" processing, as described in the "Testing a working external web service" section.
The 1cws file is a WSDL description of the 1C web service.
Using services in Retail
Typically, in retail, services are used to provide various services to the population - accepting payments, repaying loans, money transfers, buying software, etc.
At the same time, a receipt is generated for the service rendered in 1C, in which the transaction parameters are stored. After which this receipt is printed to the client with detailed information about the service provided. It is possible to print a preliminary check so that the client confirms the data entered from his words with his signature.
The service can be integrated in different ways into a retail program written in the 1C language (UT, Retail and others):
- Processing or code can be written in 1C language, which performs all the work with the service.
- A program can be used that works with the service, and in 1C only transmits information for punching checks.
Organization of service data in 1C
To store information about a transaction in a receipt, you need to create an additional tabular part “Complex sales” with the details:
- Nomenclature - link to the nomenclature of the check.
- Parameter - link to the “Complex sales: Parameters” reference book.
- Value - the value of the parameter, a complex type. The string representation must be quite long (1024 characters) to accommodate the check text.
The “Complex Sales: Parameters” directory contains a list of transaction parameters.
It is more profitable to use the tabular part than a set of details, because a transaction may have a lot of them, and in other checks not related to the service, these details will not be used and will take up extra space. In addition, such a solution is universal for any service and does not require data restructuring after the implementation of a new service.
The seller is given a separate bookmark (or a printed form, so as not to change the configuration), in which he can view the transaction details plate for the check.
Using processing in 1C language
Let's look at the example of the Paym conditional service for the “Retail” configuration.
- Let’s create a predefined element of the nomenclature directory “Paym” in 1C. In 1C:Enterprise mode, after updating the configuration, it needs to be assigned the product type “Service”.
- In the procedure “Add item to table. part" of the "Sales Registration" form module, we call processing of work with the service, written in the 1C language. If the payment is successful, we record and post the check:
- Processing should print the preliminary receipt (if required), fill out the tabular part of complex sales and prepare the check printing text in the predefined “PaymCheckText” attribute.
- In the “Post and print a receipt” procedure of the receipt module, we replace the name of the product with the one saved in the details for the receipt. The text is replaced only for sales; for returns, simply the name of the service is printed, as usual.
A separate question is how to ensure the completion of the transaction. Those. If the transaction took place in the service, how to make sure it is not lost in 1C. The most optimal way is to reconcile the registers. But this is a subject for separate consideration.
Using programs that integrate with 1C
XDTO
XDTO is often used in web services. Here are the most important tips and recipes for using XDTO in 1C.
XDTO in the 1C platform
XDTO packages, described in the “XDTO objects” branch of the configuration, are available for creating types and objects in the global factory XDTO Factory. This is not immediately obvious.
Some types in the schema do not have a name; to get them, you need to go through the type hierarchy.
The example described a System list containing XDTO structures. To create the structure itself, you had to get its type like this:
Type = Factory.Type("urn:my.ru:MasterData:Business", "Business").Properties.Get("System").Type;
Common problems with XDTO
Different XSD Schema Formats
In some formats, tags are called xs:, in some xsd:, but 1C safely understands both formats. Once there was a situation where XSD was imported into 1C normally without errors, but did not create a single package. The reason was the absence of an attribute targetNamespace at the tag, accordingly, 1C did not know which package to place the diagram in, but it did not generate errors.
Service support
Considering that the service is a combination of two systems - 1C and external, errors can occur in both systems, which reduces the overall reliability of operation.
To make it easier to understand the reasons for service failures, it is recommended to use a set of measures.
Logging requests
Links
- XDTO
- Good description of XDTO http://pro1c.org.ua/index.php?showtopic=214
- Free interesting web services:
- Aeroflot - information on flight schedules
- Morpher - declension of names http://www.morpher.ru/WebServices/Morpher.aspx
- Unassembled:
- Installing and using Web services
- v8: how to change apache configuration file?
- v8: continuation of the topic with web services - I can’t connect the web service
- v8: I continue to crawl through web services - I can’t create a proxy...
- Knowledge Book: v8: Using external web services in 1C:Enterprise 8;
- Installing and using Web services
Using the Web Services Validation Tool for WSDL and SOAP
It appears that with the advent of new technologies and standards such as XML and HTTP, Web services have secured their place in the pantheon of Internet innovation. But how did this innovation come about?
The basic concept of Web services can be traced back to the mid-1960s in the United States. In the transport industry, for example, in railway and shipping companies, a new concept of electronic data exchange between computers was introduced, which further developed into EDI (Electronic Data Interchange) technology. I first heard about EDI from a business school professor in 1980.
In 1996, the US National Institute of Standards and Technology announced a standard for EDI in the Federal Information Processing Standards Publications (FIPS PUB 161-2). According to the published specification, EDI is a standard for exchanging strictly formatted messages between computers. Received messages are processed only by the computer, and these messages are generally not intended for human interpretation. That's exactly what Web services do, except that XML, the Internet, and the World Wide Web didn't exist in the mid-1960s.
For those who are not very familiar with Web services, I will briefly review the definitions and main components of Web services.
What are Web services
A Web service is a software system designed to support machine-to-machine interactions between computing resources over a network and using SOAP (Simple Object Access Protocol) messages defined by the World Wide Web Consortium.
Simple Object Access Protocol (SOAP) is a simple, extensible protocol that exchanges structured and typed messages in a decentralized, distributed network environment. SOAP messages are written in Extensible Markup Language (XML), a simple and flexible text format derived from the Standard Generalized Markup Language (SGML), which was developed by the International Organization for Standardization (ISO 8879:1986).
Web Services Description Language (WSDL) is an XML-based language that describes the interface of Web services.
What happens when invalid SOAP messages are exchanged? What would happen if an erroneous SOAP message were processed without warning and even used to generate decision-making information?
In practice, it is impossible to tell whether the data in a SOAP message is correct or not. However, you can check that a SOAP message is correct by looking at its interface definition or WSDL.
In real life, debugging problems in SOAP messages is very difficult. If there is any error in the SOAP message, an HTTP response code of 500 is received from the Web services server. Web services servers do not provide detailed information about which part of the SOAP message has a problem. You may encounter an even worse situation where valid SOAP responses are received from the Web services server without any error messages, and neither you nor your Web services servers can understand the problems in your SOAP requests and responses. For example, you wanted to request current stock quotes for Company B, but you sent a SOAP message with incorrectly written tags to the Web services server. The Web services server could ignore incorrect tags and provide a default value in the SOAP response message, such as the stock price of Company A. If this goes undetected, the consequences can be disastrous.
These types of problems can be proactively prevented by using the Web Services Validation Tool for WSDL and SOAP. It allows you to validate SOAP messages using Web Service Definition Language (WSDL) before deploying applications that use the Web service. The program analyzes the syntax and correctness of your SOAP messages with WSDL and flags problems by reporting errors and line numbers in detail. As a result, you no longer receive annoying HTTP 500 messages. Are your SOAP messages encrypted? No problem. The program will decrypt them and check for you the correctness of the decrypted SOAP messages.
This program was created to help IBM Web Services support staff resolve Web services-related issues on IBM® WebSphere Application Server reported by customers around the world. The program is designed to check the correctness of SOAP messages. If the SOAP message has a digital signature, the program will check that as well. With the Web Services Validation Tool for WSDL and SOAP, you can even send SOAP messages to Web services servers and receive SOAP response messages. The program was created in order to eliminate problems during industrial operation by using it in the early stages of development, as well as to reduce the time for solving problems that arise during operation.
We'll create a very simple Web service. First we'll create a simple Java™ application. After testing the Java application, we will use IBM Rational® Application Developer for WebSphere® Software to generate a Web service. Next we will make some changes to the generated Web service. Finally, we use the Web Services Validation Tool for WSDL and SOAP to create, validate, send, and receive SOAP messages.
You can create a simple Web service using IBM Rational Application Developer for WebSphere Software. Web services can be created in two ways:
- Top-down development is development in which Java classes that implement Web services are generated from WSDL.
- Bottom-up development, in which a Web service is generated from a Java bean or an enterprise Java bean.
In the following example, we implement a Web service using the bottom-up development method. First we will create a simple Java application. Next, we will generate a Java Web service bean from a Java application using IBM Rational Application Developer for WebSphere Software.
Creating a Java Application
First we will create a Java application that issues a greeting. If no name is specified, the application will return the text "Hello, buddy!" If a name is provided, the application will return the text "Hello," followed by that name. Below is the code for the DemoWebService Java application included in the demo package. The hello() method returns a string depending on the 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 a Java application before creating a Web service from it. To run the application, you can write a class with a main() method. You can also use the Universal Test Client functionality provided by IBM Rational Application Developer v7 to quickly test without writing test code. Simply select Universal Test Client from the context menu of the Java class to launch the Test Client.
- In Universal Test Client, expand Objects > DemoWebService.
- Select method hello.
- Enter a string or your name in the field Value and press the button Invoke.
You can also run a test with a null parameter and see what happens. If a null parameter is passed to the hello() method, the string "Hello, buddy!" is returned, as expected.
Creating a Web Service
So far everything is working well. Let's start generating a Web service from a Java class using the bottom-up Web service development method.
- Select the DemoWebService Java application and create a new Web service from IBM Rational Application Developer.
- Since we have created a Java class, select Bottom up Java bean Web service in the Web service type list. Select Start client and press the button Finish. If we had an EJB class, we could also write an EJB (Java Enterprise bean) to generate a Web service.
If everything went fine, you will see the generated DemoWebServiceDelegate.java in Java Resources next to DemoWebService.java.
When viewing DemoWebServiceDelegate.java, you can find the Java Web service annotation @javax.jws.WebService, which specifies the targetNamespace, serviceName, and portName in the DemoWebServiceDelegate class. An instance of DemoWebService is created and another hello() method is created from the DemoWebService hello() method. If you would like to learn more about Java Web services annotations, see 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 WSDL
In the client program project, you may also notice that the files DemoWebServiceService.wsdl and DemoWebServiceService_schema1.xsd were generated. DemoWebServiceService.wsdl contains information in the Web Service Definition Language that describes the network services for the Java application you created earlier. DemoWebServiceService_schema1.xsd contains an XML schema that describes the structure of data types used in SOAP messages.
When you look at the DemoWebServiceService.wsdl file, you can see that it has a set of definitions element at its root. The definitions element has 6 elements:
- types (types);
- message (message);
- portType(port type);
- binding;
- service (service);
- port (port).
Types defines the data types used in message exchange. In DemoWebServiceService.wsdl we import DemoWebServiceService_schema1.xsd instead of defining the data types in the WSDL file.
Message defines the messages that are exchanged. We have 2 messages: "hello" and "helloResponse". The hello message has a part called "parameters". This part has a "tns:hello" element. The helloResponse message has a part called "parameters" which is similar to hello. This part has a "tns:helloResponse" element. The hello and helloResponse elements are defined in the DemoWebServiceService_schema1.xsd file. We'll look at them shortly.
Port Type– operations supported by endpoints. Each operation provides an input and an output message. Our "hello" operation consists of an input message "tns:hello" and an output message "tns:helloResponse". These operations correspond to a request-response exchange. WSDL provides 4 different exchange primitives for an endpoint:
- one-way (unidirectional);
- request-response (request-response);
- solicit-response (demand-response);
- notification.
In a unidirectional exchange, the endpoint only receives the message. In a request-response exchange, the endpoint receives the message and sends a corresponding message. In a request-response exchange, an endpoint sends a message and receives a corresponding message. In a "notification" exchange, the endpoint only sends the message.
Binding defines protocol details and message format specifications for port type-specific operations and messages. For the style attribute we use the document value. The style attribute provides 2 different message styles: rpc and document. In rpc style, messages contain parameters and return values. In the document style, messages contain documents. The transport attribute specifies the URI for SOAP transport. The specified value http://schemas.xmlsoap.org/soap/http means that the SOAP specification will use HTTP binding. The URI for the SOAPAction HTTP header for SOAP HTTP binding is specified in the soapAction attribute. Because SOAP HTTP binding is used, the value of the soapAction attribute is required. For the soapAction attribute we use the empty string "". The soap:body element defines how the message parts are assembled within the body element of the SOAP message. The use attribute provides 2 different options: literal (literal) and encoded (encoded). We use literal. This means that we have chosen to define a particular schema using either the type attribute or the element. When using the encoded option, an abstract type with encoding rules is used.
Service defines the set of ports to use.
Port defines the communication endpoint by specifying the network address to bind to.
network address for binding. In our case, the SOAP endpoint address is http://localhost:9081/HelloWorldWSProject/DemoWebServiceService.
Listing 3. DemoWebServiceService.wsdl
Create a schema
We import DemoWebServiceService_schema1.xsd from DemoWebServiceService.wsdl. Let's look at the file DemoWebServiceService_schema1.xsd. It is written in the XML Schema definition language to describe the structure and limitations of the content of XML documents. We have 2 elements: hello and helloResponse. Each element has a type. The hello type has an element "arg0" which is a string. The "arg0" element is optional because the value of the minOccurs attribute in its declaration is 0. If the minOccurs attribute is set to 1 or greater, the element must be specified. The same goes for the "return" element in the helloResponse type.
Listing 4. DemoWebServiceService_schema1.xsd
Getting started with Web Services Validation Tool for WSDL and SOAP
So far we've looked at the WSDL and schema. Let's start the Web services server so that we can invoke the Web service from the Web Services Validation Tool for WSDL and SOAP.
Running the Web Services Validation Tool for WSDL and SOAP requires a Java 6 (or higher) runtime and an XML digital encoding and decoding API that conforms to the World Wide Web Consortium "XML Encryption Syntax and processing" specifications (http://www. w3.org/TR/xmlenc-core/).
IBM Java 6 provides an implementation of JSR 106: XML Digital Encryption APIs. If you have IBM Java 6 installed, then everything is ready to go and you don't need to install anything else.
If your Java 6 runtime environment, such as Sun Microsystems™ Java 6, does not have XML Digital Encryption APIs, you must install libraries that implement JSR 106 or the Apache™ XML Security version 1.4.3 package, which can be downloaded from http:/ /santuario.apache.org/. Simply download the binary distribution, unzip it into a directory, and tell the tooling program where that directory is located using the -vmargs and -DAXS command line options.
As of this writing, the Web Services Validation Tool for WSDL and SOAP supports JSR 106 and 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 the JSR 105: XML Digital Signature APIs. Fortunately, Java 6 virtual machines from Sun Microsystems and IBM provide implementations of JSR 105. This is why Java 6 was chosen as the minimum requirement for the Java runtime environment. If your Java 6 environment does not provide libraries that implement JSR 105, you will need to find them.
The Web Services Validation Tool for WSDL and SOAP can be downloaded for free here. Its installation is very simple. Unzip the package into a directory and run wsvt.exe. If your default Java Virtual Machine is not a Java 6 environment that supports XML digital signatures and digital encryption and decryption, you must specify the Java 6 location with the -vm option, for example:
wsvt –vm c:\IBMjava6\bin\java.exe
Again, if you have IBM Java 6, you don't need to install anything else. Everything you need is already included in IBM Java 6. If you are using Java 6 from Sun Microsystems, you must point the program to the location of Apache XML Security to decrypt encrypted SOAP messages.
For example, the following command will run a program with Sun Java 6 and Apache XML Security library version 1.4.3 located in the C:\xml-security-1_4_3\libs directory:
wsvt –vm c:\SUNjava6\bin\java.exe –vmargs –DAXS=C:\xml-security-1_4_3\libs
Below is a list of the Apache XML security library files actually used by the Web Services Validation Tool for WSDL and SOAP, although Apache XML security version 1.4.3 ships with 9 jar files:
commons-logging.jar;
serializer.jar;
xalan.jar;
xmlsec-1.4.3.jar.
The Web Services Validation Tool for WSDL and SOAP program's MANIFEST.MF contains the following information:
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
This is why it was necessary to specify –vmargs –DAXS=C:\xml-security-1_4_3\libs in order for Sun Java 6 to decrypt encrypted SOAP messages.
I've spent quite a bit of time troubleshooting class loading conflicts and incompatibilities among XML-related classes found in the Sun Java runtime, Apache XML Security, and some Eclipse plugins. Setting up the IBM Java runtime was easy because the runtime comes with a JSR 106 implementation and does not require Apache XML Security.
Creating a Project
Now, after setting up and running the tool program, you can create a new project. A project can contain a WSDL file, multiple schema files associated with the WSDL file, and SOAP messages in XML files. If there are multiple WSDL files in a project, only one of them is used and the others are ignored when validating the SOAP message XML file. To use a different WSDL file, you must create a separate project. Every SOAP message must be contained in a file with a .xml extension, otherwise it will not be considered a SOAP message.
- Right click and select New > Project.
- Select Project V General.
- Enter "Test Project" in the field Project name and press the button Finish.
Import WSDL and Schema
We created the "Test Project". Now you can import WSDL and XSD into it.
- Select the project and then from the context menu select Import.
- Select File System V General.
- Select the directory where the WSDL and XSD are stored.
- Select 2 files (DemoWebServiceService.wsdl and DemoWebServiceService_schema1.xsd) and click the button Finish.
WSDL and Schema Overview
Now we have a project with WSDL and XSD. You can double-click the left mouse button on the WSDL to view the WSDL in Design and Source mode. In Design mode, you can visualize a Web service with input and output data.
In Source mode, you can view and edit WSDL in a text editor.
If XSD files cannot be opened in the XSD editor, they can be opened in the XML editor by selecting Open With > XML Editor in the context menu of this XSD file.
We opened DemoWebServiceService_schema1.xsd in an XML editor.
Creating a SOAP Message
So now we have the WSDL and schema ready to validate SOAP messages. Let's start testing the Web Services Validation Tool for WSDL and SOAP program with a SOAP message. You must include a SOAP message in your project. The SOAP message must be contained in a file with a .xml extension so that its correctness can be verified.
- Select New > XML to create a SOAP message in a project.
- Select Test Project for the parent folder of the new SOAP message. If the file is not already selected, enter "DemoSOAPMessage.xml" in the field Filename and press the button Finish.
The program automatically calls the XML editor with a new XML file. There is nothing in it except a line with the version and xml encoding. It's good that we have at least something before we start creating a SOAP message from scratch. Do you know how to compose a SOAP message? Do not worry. In the next section, we will go through the steps to create it step by step.
To create a SOAP message, you can activate the service's "hello" using the "parameters" parameter with my name - "Jinwoo". Of course, you can use your own name. The namespace used is http://demo/. Be careful - it is written as http://demo/, not http://demo, this is important.
Listing 5. HelloWorldSOAPmessage.xml
Do you see any problems with this SOAP message? If yes, don't worry. We'll deal with this later.
Sending a SOAP Message
Are you ready to send a message to the Web services server?
- Select SOAP message and select
- In the Transmit SOAP Request and Receive SOAP Response window, you can fill in Service Address, SOAPAction And Content-Type. In this application, we don't need to specify SOAPAction because we used the empty string "" for the soapAction attribute in the binding section of the DemoWebServiceService.wsdl file.
- Enter http://localhost:9081/HelloWorldWSProject/DemoWebServiceService in the field Service Address, if the server is running on a local computer on port localhost:9081. Otherwise, you must enter the real address where the Web service is available.
- Select text/html for field Content-Type.
- Click the button OK to send a SOAP message to the server.
Receiving a SOAP message
If the server is up and running, you should receive a SOAP response. If you do not receive a response, check that the address and content type are correct.
Validating a SOAP Message
Great! We accepted the SOAP response. It is also saved in the project. But wait. Do you see something is wrong? We got "Hello, buddy!" instead of "Hello, Jinwoo!" Something went wrong? Don't have a clue?
Unfortunately, the Web services server didn't let us know what was wrong. No warnings. A situation where unpredictable SOAP responses are sent and the Web services server has no idea what is going wrong can be very dangerous. Even recipients of SOAP responses may not notice problems in the SOAP message in question.
The Web Services Validation Tool for WSDL and SOAP helps you determine what's going wrong.
Listing 6. Response
- Select the SOAP response message and click the button Validate.
The Web Services Validation Tool for WSDL and SOAP found an error in 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.
Editing a SOAP Message
- The program complains about the value of "parameters". Change it to arg0 and save.
Listing 7. Modified SOAP message
- Verify that the modified SOAP response message is correct. No more error messages appear.
- Now we are ready to send the modified response message to the server. Select SOAP message and then select Transmit SOAP Request and Receive SOAP Response.
- In the Transmit SOAP Request and Receive SOAP Response window, enter http://localhost:9081/HelloWorldWSProject/DemoWebServiceService in the Service Address, if the server is running on port localhost:9081.
- Select text/html for field Content-Type and press the button OK.
This time, as expected, the correct answer comes.
Listing 8. SOAP response
Invalid namespace detection
What happens if you send a message with the wrong namespace?
- Change the namespace to http://demo2/ and save the message.
Listing 9. Changing the namespace
- You can then send a request to the server.
You will see an IOException: Server returned HTTP response code:500 for URI: http://localhost:9081/HelloWorldWSProject/DemoWebServiceService .
The Web services server sent information about the IOException exception in the response, but this information is not enough to detect the error. Check the correctness of the message using the tool if you want more detailed information to resolve the problem.
The program reports: "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".
This message indicates that the value http://demo/ is expected. It is this, not the HTTP 500 response code, that we need to know.
Validation of encrypted SOAP messages
What if your SOAP messages are encrypted? No problem if you have keys and passwords. Just select the SOAP message and Validate just like you would for any other regular SOAP message. If your SOAP message is encrypted, you will see a prompt similar to the one shown in Figure 35.
At the time of writing this article, 3 types of keystores are supported:
- Java Key Store (JKS).
- Java Cryptography Extension Key Store (JCEKS).
- Personal Information Exchange Syntax Standard (Public Key Cryptography Standards #12).
You must provide information about your keystore: file name, file type, and password. If the information is correct, you must select a key and password. You can also find information about your keystores and the 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.
If all the information is correct, the program will generate a decrypted SOAP message and check its correctness.
The following encryption algorithms are currently supported:
- Advanced Encryption Standard (AES) in Cipher Block Chaining (CBC) mode with initialization vector (128/192/256 bits).
- Advanced Encryption Standard (AES) Key Encryption (128/192/256 bits).
- Triple Data Encryption Algorithm Modes of Operation (triple-DES) Key Encryption.
- Triple Data Encryption Algorithm Modes of Operation (triple-DES) Key Encryption in Cipher Block Chaining (CBC) mode.
- RSA Cryptography Specifications Version 1.5.
- RSA Optimal Asymmetric Encryption Padding (OAEP) is a method with a mask generation function.
Validation of digitally signed SOAP messages
What if your SOAP message is digitally signed? Just select the SOAP message and then select SOAP Message Digital Signature Verification.
If the digital signature is correct, you will see the following screen:
Otherwise, the program will report an error in the signature. The following digital signature specifications and algorithms are currently 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 US National Weather Bureau service using a SOAP message
The simple Web service we created and tested works fine. Can this program be used in a "real" environment? You can try working with a real US National Weather Bureau Web service provided by the U.S. National Oceanic and Atmospheric Administration (NOAA).
- Create a project.
- Create the SOAP message XML.
The US National Weather Bureau provides many different Web services. You can try working with the NDFDgenByDay service, which provides weather forecasts for a point with a given latitude and longitude.
To access NDFDgenByDay you must provide the following information:
Table 1. NDFDgenByDay
| Service Name | NDFDgenByDay |
|---|---|
| Endpoint | http://www.weather.gov/forecasts/xml/SOAP_server/ndfdXMLserver.php |
| SoapAction (SOAP action) | http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl#NDFDgenByDay |
| encodingStyle (encoding style) | http://schemas.xmlsoap.org/soap/encoding/ |
| Namespace | http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl |
| latitude (latitude) | Decimal number |
| longitude (longitude) | Decimal number |
| startDate (start date) | date |
| numDays (number of days) | Integer |
| format | Line |
In this example, we want to create a SOAP request to obtain a weekly forecast for an area with coordinates (LAT38.9,LON-77.01), starting from 2010-07-23 in 24-hour format:
Listing 10. SOAP request
We didn't specify a namespace because the service worked without it. If you have any problems with the namespace, ask it.
Select a message and Transmit SOAP Request and Receive SOAP Response in the Web Services Validation Tool for WSDL and SOAP.
Table 2. Request for information
| Name | Meaning |
|---|---|
| Endpoint | http://www.weather.gov/forecasts/xml/SOAP_server/ndfdXMLserver.php |
| SoapAction (SOAP action) | http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl#NDFDgenByDay |
| Content-type | text/xml; charset=utf-8 |
Now the forecast data has become much easier to read.
If this advice doesn't seem very convenient to you, you can use your own HTML formatting method. Most Web services offer results in XML format, so you won't have to resort to this technique all the time.
Conclusion
We created, transformed, accepted, and validated SOAP messages using the Web Services Validation Tool for WSDL and SOAP. This program allows you to pinpoint problems that most Web services servers are not even able to detect, which can lead to serious consequences in real life. Using this program at the development stage allows you to reduce the time it takes to troubleshoot problems during operation.
Loading...