I have to agree. Do not ignore
3.4.1 Designing the Interface. Here are the pertinent points:
With the Java-to-WSDL approach, it may be hard to evolve the service interface without forcing a change in the corresponding WSDL document, and changing the WSDL might require rewriting the service's clients. These changes, and the accompanying instability, can affect the interoperability of the service itself. Since achieving interoperability is a prime reason to use Web services, the instability of the Java-to-WSDL approach is a major drawback. The WSDL-to-Java approach gives you a powerful way to expose a stable service interface that you can evolve with relative ease. Not only does it give you greater design flexibility, the WSDL-to-Java approach also provides an ideal way for you to finalize all service details. Java-to-WSDL tools are great for prototyping, especially if you need to quickly bring up a proof-of-concept for existing functionality - however when designing and implementing something for production it�s best to start designing a proper XML Schema (especially if your data is complex) for the data to be exchanged, then devising WSDL operations that will be used to
exchange the data. That doesn't mean you have to do it manually - you can and should use (visual) tools to design your XML Schemas and WSDL documents - however you need to be thinking in terms of the strengths and weaknesses of XML Schema and WSDL and not about
Java objects (or worse object graphs).
If your data exchange is simple enough you could start by designing
Transfer Objects that follow the guidelines of JAX-RPC Value Types (
Java API for XML-Based RPC (JAX-RPC) Specification 1.1: 5.4 JAX-RPC Value Type) and then use those as parameters and return values in your endpoint interface. Finally you would use Java-to-WSDL to come up with you first pass at the WSDL (making sure that you specify WS-I compatibility for your tool).
Java-to-WSDL tends to give developers the illusion that everything is transparent - and that they don't need to deal with XML Schema and WSDL - sometimes with the effect that in the generated output there are some "little details" they are unable to discern - details that can have undesirable consequences down the road.
The convenience of Java-to-WSDL also may lead some developers to "forget" the cost of crossing that great divide. The blueprints clearly recommends the separation of a "service interaction" layer and a "processing layer" (
3.3 Key Web Services Design Decisions). The section elaborates that the service interaction layer also contains the developer supplied logic (i.e. in addition to the generated code) to map business objects:
This mapping of incoming XML documents to business objects is not the same as the JAX-RPC runtime mapping between XML documents and Java objects. Although the container performs the JAX-RPC runtime mapping for all requests and responses, the developer chooses the mapping of incoming XML documents to business objects.
This expresses the expectation that business objects will be converted to XML Documents, JAX-RPC Value types (Transfer Objects) or JAX-RPC mapped standard Java types, then sent over the wire and then reconstituted on the other side; it also indicates that those mappings are the developer�s job. The existence of Java-to-WSDL tools has created the expectation in some people that
you should be able to simply stuff an arbitrary custom object down the pipe.
Java-to-WSDL tools also make it all too easy to expose fine-grained object methods (not that you could'nt do the same with WSDL-to-Java tools - but at least WSDL serves as a reminder that "you are not in Kansas anymore") - tools that make it too easy to abuse a technology can end up giving the technology a bad name.
