Thursday, August 01, 2013

Meteorite test set

In a previous post I wrote about impact analysis of modifying a web service contract. In this post I will provide you with a small test set, and guide you through the process of impact analysis.

First you need to download the sample archive file. You can unpack it and open it in your favourite XML and WSDL editor to examine the details. I will describe it here briefly.

There are two SOAP web services, the nothing service and the something service. The nothing service only has a single operation, doNothing(), whereas the something service has two operations, getSomething() and searchSomething().

Both services require a custom SOAP header element with some token inside. Otherwise the service won't work.

The web service contracts defined in the WSDLs follow the document literal pattern, and the message bodies for the input and output messages of each operation are defined in separate XML files. These XML files and their namespaces are imported in the WSDLs.

The nothing service does basically nothing. That is, it will simply return a fixed string, no matter what string you input.

The something service on the other hand can search for something, and it can get something. Something is defined in its own XML schema file, which is imported in the message XML schema file.

In case you search for something, you will receive a list of somethings, each with an ID and a name. If you want more details of something, you need to get the something directly via its ID, and you get some more details. A detailed something is an extension of a basic something in the XML schema.

Suppose the nothing service and the something service are successfully serving multiple clients, but a change in configuration requires that the header must be adapted and a unique ID must be added to it, and there is a new optional detail in something that we would like to return in the getSomething() operation. What is the impact of these two small changes?

To find out, we upload the archive to Meteorite. Logon, select the archive, and upload it. After uploading, you will see a collapsed data tree. This is the tree of files and the WSDL and XML schema nodes.

First we will examine the impact of modifying the header. It's the "MeteoriteHeaderType" node in .../header.xsd which we want to modify with an extra element. Open the tree to find it, and then click on the control button on the right to perform an impact analysis.

We are now back at the collapsed data tree. The impact analysis is done, and we now have four views with which we can examine the impact. The data tree is the first of the four views.

Data Tree View.
This is the default view because it is so close to your input hierarchy. Expand all nodes and scroll a bit down. In red is the node which is the subject of the impact analysis. In blue all nodes that somehow are impacted by a change. Scroll down further and you will see that both services are impacted, but the impact is limited to the headers only. Because both input and output header are impacted, this change is not backwards compatible, and thus all clients of the web service are impacted.

Impact Report View.
This view only lists the WSDL files with impact. It ignores all XML schema files. So it provides a high-level overview of services that are impacted. However, header impact is not shown. Impact is limited to the bodies of the SOAP messages. (This is by design, as header fields are handled differently from body fields in most XML binding frameworks.)

Export the Impact to Text
This view shows you a text file with all the paths from the impacted node upward to the web service contract. For example, one of the six different paths is this one:
"(MeteoriteHeaderType)<--[INHERITS_FROM]--(meteoriteHeader)<--[USES_ELEMENT]--(header)<--[CONTAINS]--(headerResponse)<--[CONTAINS]--(schemas/com/archimiddle/meteorite/sampleServices/wsdl/somethingService.wsdl)<--[CONTAINS]--(<--[IS_PARENT]--(Project - meteorite-test.rar)"
The notation is based on the Cypher query language for graph databases. Nodes are between brackets and relationships are between square brackets and form a directed arrow. Note that the file names as well as the namespaces are also considered nodes in the graph. After all, they are relevant through the import and schemaLocation elements and attributes.

Export the Impact to Image
This view shows you the impact graph as an image. Open it and you will something like this:
(Click on the image to enlarge)
Here we see the six paths again.

Next we want to add an optional detail to something. What is the impact of that?

Go back to "View the Data Tree." (Not the one from the impact menu, the other one) We have now cleared the previous impact analysis, and we can start with a new one.

In the search box upper right, start typing SomethingDetailsType and pick it once it shows. Click on the search button and you have your node on the screen. Now click the impact analysis button on the right of it.

Go to the impact report view and we see that only the something service is impacted. The nothing service is not affected by this change.

Export to image and you will get this impact graph:

We see that only the getSomething() operation is affected, not the searchSomething() operation. This is so because the search will only return basic something, not the detailed something.

This concludes the short tutorial for Meteorite. You can modify the schemas and experiment with it yourself. It is something surprising what impact a small and seemingly innocent change in a schema can have!

Now try to analyze the impact of a change without using the Meteorite tool. Did you find all nodes that are impacted? How long did it take you?

Meteorite uses a graph database (Neo4J) to traverse the impact graph and is therefore very fast. This is just a simple example of the power of graph databases in performing impact analysis in complex structures.

No comments:

Post a Comment