UML for Web Services
August 5, 2003
You've heard the hype, you've read the literature, and you're convinced that web services is the next step. You know SOAP and WSDL, and you're ready to build something. It's time to take web services to the white board. You don't want to go plunging into your first web-services project without a proper design process, right? Enter the Unified Modeling Language, which is the white board notation for object-oriented analysis and design (and much more), offering a natural fit to RPC-style service design.
In a recent article I talked about the importance of working from WSDL and W3C XML Schema (WXS) as the source language for web-service development, as opposed to starting from a chosen implementation language and generating WSDL and SOAP code. This is right and good, but WSDL is neither comprehensive nor easy enough to work well as a design language. So the process we really want is not just WSDL-to-Impl, but UML-to-WSDL-to-Impl:
- design in UML;
- express service semantics in WSDL and WXS;
- implement in a supporting programming language.
One big advantage of a UML design process is that UML -- through stereotypes, mostly -- can express designs over three important domains: WSDL for messaging semantics, WXS for serializable types, and the OO service or client implementation language. In an older article, I laid out a convenient UML notation (known as a "profile") for WXS types; this article will focus on two new capabilities:
- Modeling WSDL components for service semantics, such as port types, ports and services
- Integrating WSDL, WXS, and traditional OO types for effective modeling of web services: interoperable description, service and client implementations in concise diagrams that explicitly relate these various types
Use of UML for WXS
Web-service designs will need to express certain WXS constructs frequently: complex types, built-in simple types, and enumerations are all most tools support so far. I won't restate the notation for this here; you can refer to the original article or simply intuit the meanings of notations as I use them in the rest of this piece. One refinement is that since I'll be combining types from three different profiles I'll apply the namespace prefix xs: to the stereotypes from the WXS notation. Similarly, for the few stereotypes I'm about to introduce I'll use wsdl:.
Also, instances of these xs: stereotypes will be understood to encapsulate not just the WXS component, but also the corresponding application-language artifact, such as a generated class for a serializable complex type or enumeration. This is a pattern we'll see replicated for the wsdl: stereotypes as well; it is key to the integration of WSDL, WXS, and a programming language.
Just for kicks, and perhaps to develop more familiarity with the WXS notation, here's a diagram of the WXS schema for WSDL itself:
What I'm about to develop is a notation for WSDL descriptors, not just WXS schema -- that is, a high-level model that maps wsdl: stereotypes to combinations of these WSDL components, so that web-service designs don't have to spell out every individual component for a given design concept.
Case Study: The Love Is Blind Dating Service
To illustrate the UML notation I'll build up a design for a simple service called Love Is Blind, which offers an online dating service based on simple matching queries over sex, age, and interest keywords. Members will be registered in a database with attributes for sex, age, interests, nickname, and picture; each will also have a unique member ID and a password. The service will offer a simple use case to walk-in clients:
- Query the database for matches, receiving a result set of member profiles.
- Send a love note to one or more members as found in the result set, passing in name, email address, and message text.
Other use cases for other roles such as members and administrators will be developed along the way. Our goal will be to develop a UML design document that expresses the WSDL description, including supporting WXS types, the service implementation, and client interactions with the service.
Expressing Service Interfaces
As a description of a service interface, the WSDL portType component is naturally similar to the UML interface: it is a collection of operations, which are just UML methods; each method signature must be spelled out as SOAP messages (input, output, and faults) rather than parameter lists, a return type and exceptions.
The exact mappings of portType, operation, message, part, and WXS types to programming languages are spelled out in language-specific standards such as JAX-RPC. We'll float above the gory details here and simply treat WSDL port types as realized interfaces.
|
So our first wsdl: stereotype is shown at right and a simple example follows. Note that I've conjured the supporting WXS complex types and an enumerated type as part of the design process for WalkIn.
Just a snippet of the total WSDL production from this design is shown below. (If there were any doubts about the possible choice of WSDL as a design language, they should be dispelled with one look at the complete listing, which is already unwieldy while the UML whence it came is elegant.)
...
<simpleType name="Sex" >
<restriction base="string" >
<enumeration value="Male" />
<enumeration value="Female" />
</restriction>
</simpleType>
<complexType name="Characteristics" >
<all>
<element name="sex" type="LIB:Sex" />
<element name="age" type="positiveInteger" />
<element name="interests" type="LIB:StringArray" />
</all>
</complexType>
...
<message name="findTrueLoveRequest" >
<part name="desires" type="LIB:Characteristics" />
</message>
...
<portType name="WalkIn" >
<operation name="findTrueLove" >
<input message="LIB:findTrueLoveRequest" />
<output message="LIB:findTrueLoveResponse" />
</operation>
<operation name="sendLoveNote"
parameterOrder="memberID note" >
<input message="LIB:sendLoveNoteRequest" />
<output message="LIB:sendLoveNoteResponse" />
</operation>
</portType>
The message and operation names are implicit and would be handled by a UML or other code-generating tool. Not shown is the use of exception signatures to express WSDL faults.
The case study thus far shows only the production of WSDL and WXS from UML designs, which is the first of our goals. How does the «wsdl:portType» integrate with ordinary OO types? First, client interaction with the service will be through the port type, so we'll see dependencies like those shown below. (Note that an implicit rule of interoperability can be stated for this notation: client dependencies should only flow to wsdl: and xs: types.)
The «wsdl:portType» stereotype is now seen to express more than just the literal WSDL portType component. It does double duty in encapsulating the (probably generated) application code for the interface. Thus the client dependency to the port type uses the native programming language on the client side, and a generated stub is understood to be translating this to SOAP messages. This integrated notation, then, assumes the interoperability inherent in web services.
To understand the other interesting integration point we'll need a mapping for the concrete service model --- ports, bindings, services --- where thus far we've been dealing only with the abstract model.
Expressing Services and Ports
|
A WSDL port "implements" a port type. Realization in UML expresses this relationship perfectly, though clearly the implementing type is more than just a class. Thus our second wsdl: stereotype, shown at right, and an expanded UML diagram for Love Is Blind, now including a port and drawing on additional implementation types from the implementation language. Thus the second point of integration, and a similar, implicit translation from SOAP to the native language:
The corresponding WSDL production is small and, in fact, invalid till we deal with WSDL service and binding components. «wsdl:port»s will also produce platform-specific artifacts to dispatch SOAP messages to application code: XML deployment descriptors, a skeleton implementation class, perhaps even tie classes.
But, indeed, what about the WSDL binding? This is an interesting question: should the SOAP binding of port to port type be expressed in UML at all? It's arguable that everything expressed there comes into play only in code generation -- that none of it, in other words, is really design information. As much for the sake of brevity as anything else, this is the road I'm taking. (By the same rationale, note that the URI value tagged to the «wsdl:port» is relative to the service; I assume that absolute location is external to the design.) If details such as use and style are considered important to design and documentation, one could certainly define a «wsdl-soap:binding» stereotype -- probably a stereotype of UML realization itself, as binding informs the realization of portType by port.
|
As shown at right, services are primarily collections of ports. They add URI context information, but not much else at the interoperable level.
The next step up from service is the WSDL descriptor itself, and the important implication this has on model content is the XML namespace in which all of the information we've discussed so far is contained. What more natural mapping is there to an XML namespace but from a UML package? Now a complete design for the WalkIn use case is feasible:
The complete WSDL descriptor is, again, only part of the production from this design. See also this expanded design for additional behaviors in the Love Is Blind service -- such as member login and administration -- and the corresponding, expanded WSDL descriptor.
Odds and Ends
This basic notation turns the interesting trick, which is to enable a visually-oriented design process that seamlessly expresses WSDL components, WXS types, and implementation types in integrated diagrams. The resulting UML can provide the clearest and cleanest pictures of a designed web service, for implementation as well as for documentation and communication outside the development team.
The framework can be expanded in a number of ways: stateful ports might express session-aware web services; behavior on serializable types might imply server-side-only validation or other logic. WSDL messaging scenarios other than request/response might be indicated in any number of ways.
Finally, an interesting complement to the class/component notation is the dynamic analysis it implies. UML interaction diagrams will work smoothly with this notation: method calls versus messages is actually a fine distinction in the UML sense. Different messaging scenarios (request/response, one-way, etc.) also imply different synchronization in the UML. Here's a simple example for the primary Love Is Blind use case:
