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.

Thursday, May 16, 2013

Meteorite: Analyze the impact of changing a service contract

You have a web service which is used by many, but you need to change something in the web service contract. The technical contract is described by a WSDL and a number of imported, reused XML schemas. What is the impact of your change to the technical contract?

This seemingly simple question can be quite difficult to answer. A heavily reused XML element, buried deep down in the XML schemas, can have an enormous potential impact on the contract. Even with tiny, apparently harmless additions like a new optional attribute, the users of the web service may have to modify their web service client code.

In order to assess the impact correctly, we need to know all web service components that somehow depend on the component that we intend to change. It is not surprising that this dependency graph is, well, a graph. It is not a simple tree structure.

Most XML is shown top-down as a tree structure. But for an impact analysis of a change, we need to climb the "tree" from some leaf down the trunk.

In order to facilitate the process of impact analysis, we built a free on-line web application, based on a graph database, which does exactly that: find the impact graph of a proposed change.

You can find the application here:

You can upload WSDL and XML schema files, as a single zip archive, even if you only have a single file, then navigate to - or search for - the item you want to calculate the impact graph for. You can then view the impact graph visually, or textually as a list of impact paths. Try it!

(The tool uses HTML5 for the user interface, an embedded Neo4J graph database, and graphviz to visualize the impact graph.)