Future direction and state of the WSDLDefinitions API
Part of the JAX-WS work I did involved revamping the WSDLDefinitions API to be more accurate with WSDL 1.1 (there were many problems with the previous design that made it impossible to represent the mappings required by JAX-WS). I also brought the API inline with the current version of the WSDL 2.0, as many elements are missing. So basically the current version in trunk is highly focused towards WSDL 2.0. The reason for this is that we now only have one component that generates the model (WSDLGenerator), and the resulting model is capable of serializing to both 1.1 and 2.0 (as soon as the 2.0 writer is fully implemented[further down the roadmap]). This allows for interesting applications. For example, it would theoretically be possible to provide a conversion utility that would read a WSDL 1.1 file, and produce a WSDL 2.0 file by just reading it using WSDL11Reader, and writing it using the final WSDL20Writer. There is only one major difference that has to be accounted for, and that is the change of the RPC style in WSDL 2.0 to be the document/literal wrapped style. So basically the difference here is that there is no equivalent of a message in WSDL 2.0, which means that everything has to be expressed using schema. Therefore anything that used the RPC style in WSDL 1.1 would have to have its parts converted to a schema complexType before it could be serialized correctly.
So when using this API, everything operates mainly from the 2.0 perspective. So I would recommend that anyone doing work on this API, or using it take a brief look at WSDL 2.0 spec to get an idea of how it should be used. All of the metadata builders can be looked at for examples as well.
There also is some information that is needed for WSDL 1.1 that can't be expressed in 2.0, so in order to have a model that is capable of being serialized to both, you need to provide the extra 1.1 information, which would be ignored when producing a WSDL 2.0 document. For example, since WSDL 2.0 does not have a message component, the message name, and the part names are not used. So in this example, the WSDLInteraceMessageReference object (which is a WSDL 2.0 concept) contains additional properties for the WSDL 1.1 message name, and the part name.
As mentioned above the RPC style in WSDL 2.0 is basically document/literal wrapped. This means there is conceptionally only once "part" as you think of it in WSDL 1.1 terms, and that one part maps to a complexType that contains the multiple "parameters". So to support serialization to 1.1 RPC style, there is the notion of a WSDLRPCPart. This is capable of being mapped to both. For WSDL 1.1 this would translate to a message part element, and for WSDL 2.0 this is just extra information about the schema element that represents the "part".
Another difference is that headers were designed to be binding only, and are not part of the formal abstract contract which is represented in schema. So when using headers (or attachments) they must be represented directly on the binding API elements of WSDLDefinitions, and not the WSDLInterface. This is actually a loss of information in WSDL 2.0 that prevents determining whether a header is implicit or explicit. In WSDL 1.1 if the header was part of the message containing the body parts, it was assumed that the resulting java code should have this header bound to a parameter(explicit). If it was in a different message it was assumed to not be part of the main contract, and thus not bound to a java parameter, and instead up to a handler or the like to provide it. So in order to allow this information to be maintained when serializing/deserializing to WSDL 1.1 set/getIncludeInSignature is used on the WSDLSOAPHeader to indicate wheter or not it is implicit or explicit.
There are a couple of things that still need to be improved. Originally the WSDLDefinitions API was designed to represent a single WSDL 2.0 file, so everything used NCNames. It has since been update to be a final infoset, and uses QNames, but the NCNames are still used in some places. These should all be removed. Also the writers should be updated to use either DOM, JDOM or StAX for writing the document. Currently they serialize everything on their own, which is a potential problem with character escaping. Also the code would be simpler and more maintainable if it relied on a framework to do the heavy lifting. Also everything is ran through DOM to pretty print the output anyway, so this would eliminate an extra parse phase.
-Jason