UML for Web Services

Will Provost

Originally published at XML.com, August 5, 2003

You've heard the hype, you've read the literature, and you're convinced that Web services is the natural next step. You know your SOAP and your WSDL, and you're ready to build something. It's time to take Web services to the whiteboard. You don't want to go plunging into your first Web-services project without a proper design process, right? Enter the Unified Modeling Language, or UML, which is the whiteboard notation for object-oriented analysis and design (and much more), and offers a natural fit to RPC-style service design.

In a recent article I've been ranting 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 (Java, C#, etc.) and generating WSDL as well as SOAP code. This is right and good, but WSDL is neither comprehensive nor facile 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:

  1. design in UML;
  2. express service semantics in WSDL and WXS;
  3. implement in a supporting programming language.
Development process

One big advantage of a UML design process is that UML — through stereotypes, mostly — can express designs over all three important domains: WSDL for messaging semantics, WXS for serializable types, and the OO language itself for service or client implementations. In a less recent article, I've already laid out a convenient UML notation (a "profile," technically) for WXS types, and so 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 thus far. I won't restate the notation for this here; one might refer to the original article or simply intuit the meanings of notations as I use them in the rest of this piece, as they are straightforward. 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 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:

UML depiction of WSDL metamodel

What I'm about to develop is a notation for WSDL descriptors, not just WXS schema: 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 for Web services 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:

  1. Query the database for matches, receiving a result set of member profiles.
  2. Send a love note to one or more members as found in the result set, passing in name, e-mail 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 specialized interfaces.

«wsdl:portType» stereotype
Expresses a WSDL portType component and supporting operations, messages, and parts by the usual notation for «interface» types. Supporting WXS types are either built-in simple types or are identified elsewhere in the design using the WXS stereotypes.

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.

Abstract model in UML

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" />

      <complexType name="Characteristics" >
          <element name="sex" type="LIB:Sex" />
          <element name="age" type="positiveInteger" />
          <element name="interests" type="LIB:StringArray" />
  <message name="findTrueLoveRequest" >
    <part name="desires" type="LIB:Characteristics" />
  <portType name="WalkIn" >
    <operation name="findTrueLove" >
      <input message="LIB:findTrueLoveRequest" />
      <output message="LIB:findTrueLoveResponse" />
    <operation name="sendLoveNote" 
        parameterOrder="memberID note" >
      <input message="LIB:sendLoveNoteRequest" />
      <output message="LIB:sendLoveNoteResponse" />

The message and operation names are implicit and would be handled by a UML or other code-generating tool. Also, 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 — the first of our goals. How does the «wsdl:portType» integrate with ordinary OO types? First, and most simply, 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.)

Typical client dependency

Now 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

«wsdl:port» stereotype
Encapsulates a WSDL port, the implementation-language class that implements it, and server-side wiring from the port URI to that class. Thus, unlike a «wsdl:portType», instances of this stereotype can be actors in the service implementation, collaborating with domain classes. Service-relative URI can be expressed as a tagged value.

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:

Concrete model in UML

The corresponding WSDL production is small, and in fact invalid until 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, tie classes perhaps.

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 tack I'm taking. (By the same philosophy, 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.

«wsdl:service» stereotype
Encapsulates a WSDL service as a collection of ports, along with the server-side wiring to support the running service. Context URI for a service (again, minus host and port at least) can be tagged, as with «wsdl: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:

Complete model in UML

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, I believe, 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 vs. 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:

UML interaction diagram