It’s interesting to see how many hours java developers spend these days writing Xmls. I can hardly imagine writing java server-side applications without a single xml document nowadays. All those configuration files, deployment descriptors, schema files, mappings, etc. Has anybody tried to count those hours?
The things are getting worse when you work within SOA. The number of xml-based specifications and standards to deal with is just tremendous. When too much goes to Xml you start loosing some neat features that you already might be accustomed to like autocomplete/codesense or re-factorings in your favorite IDE. Some IDEs solve that problem providing support for widely used frameworks and tools like Spring.
But things are getting scattered all over the place, now you have to look into a bunch of files to figure out what the code does and what the all dependencies are. It’s not only Java anymore.

For the last few years I’ve been mostly working with SOA, writing back-end logic and providing SOAP interface to it. The most common approach these days to write web-services, I think, is using frameworks like Axis. It allows you to develop services from top-down or bottom-up. First one implies that you have a WSDL document for which you write/generate your skeletons classes and then wire them with the business logic. Second one goes from your classes to the WSDL. The framework hides all the web-services interaction and communication details. And you basically operate in RPC-style model.

In my two previous projects we decided to go another way. We chose document-oriented type of interaction between our web-services where the document in SOAP represents a complete unit of information and may be completely self-describing.
We’ve been using Soatoolkits (Alex: this is a plug for you) which is really great tool for rapid development that supports JSR 181, XPath 2.0 and provides some other neat features.

I can turn my java class into a web-service very quickly:

public void recover(@XmlParam(xpath = "//Email/text()") final String email,
         @XmlParam(xpath = "//Answer/text()") final String securityQuestionAnswer,
         @XmlParam(xpath = BODY_XP) final Xml xmlBody) throws Fault {
    if (xmlBody != null) {
        XmlValidator.validateSenderInput(xmlBody, GET_SEC_QUESTION_VALID_SCHM);

All three parameters in the method signature get their values assigned in runtime when the message comes in to the service.
The third param xmlBody is an Xml class instance that contains following xml:


If you want that method to call directly from API you certainly can do that just passing null for xmlBody as it is used in that method only for incoming SOAP validation according to our Schematron rules.

But… here things can go wrong. Some people started using it like:

public String getWhatImLookingFor(@XmlParam(xpath = BODY_XP) Xml xmlBody) throws Fault {
    try {
        return whatImLookingForManger.getTheThing(xmlBody);

Thus an xml in SOAP body goes all the way down to the business logic where it is parsed and required values are extracted from the xml.
That is totally wrong to me. Now your business object’s interface is an xml document that I have no idea about. What structure of that xml is, what elements are required, what types of those fields are and so on and so forth until I go deeply inside that object and try to figure out based on Xpath statements what the xml looks like. And I’m not talking about testing and how odd it is when you have to create that xml in first place and then pass it to the method that needs just two values from it. You loose to much and gain too little passing an xml around in your classes.

So what’s the solution?

Try to make your services the only one place that deals with Xml directly. Parse messages in the services, get parameters you need in native java data-types or map Xml directly to an abstract data structure and pass it to your internal business logic. Now you have clear API, you have type safety, basically you have created a contract. Another benefit is that your code is testable. When in a couple of months you’ll get back to your or someone else’s code you can see the contract clearly, all the parameters and types. Hopefully, you won’t be pulling hairs out of your head trying to figure out what xml document is expected in the methods and classes.