 | Level: Introductory Simon Johnston (skjohn@us.ibm.com), STSM, IBM Rational
11 Apr 2006 This article is the second in a three-part series looking at the use of UML modeling (in particular, when using IBM Rational Software Architect) to model a detailed design of standardized Web services. This article describes modeling Web services and generating Web Service Definition Language (WSDL) using the UML 2.0 Profile for Software Services.
Introduction
This series of articles describes how to model, in detail, Web service-related structures, and how IBM® Rational® Software Architect (henceforth, Software Architect) can be used to realize these models in actual implementations. The series will look at the following topics:
- Part One: Modeling and generating XML Schema (see References [1]).
- Part Two: Modeling and generating WSDL.
- Part Three: Applying patterns to the generation of Web service artifacts.
This article builds upon the example introduced in Part One of this series. Specifically, the schema developed in the first article will be used in the examples in this article. All of the examples in this article have been developed with Software Architect version 6.0.1, although the downloadable transformations described below should also work with Software Architect version 6.0.0.1.
Modeling Web service definitions
The first article in this series answered the question of whether it provides value to model the details of Web service specifications, rather than directly editing the WSDL and XML Schema used to capture the service details. In particular, this was answered in terms of the application of a Model-Driven Development (MDD) approach, typified by the diagram shown in Figure 1.
Figure 1. An MDD configuration for Web service development
The focus of this article is on the modeling of service definitions, that is, the aspects of a service specification expressed using WSDL. In this respect it is concerned with the operations, messages, and interfaces provided and required by a service, something you would reasonably expect UML to be able to express. In fact there are certain elements of a service-oriented design that are actually better expressed in UML today than they are in the WS-* family of specifications. In looking at the way to model a service-oriented solution, we have to decide upon some guidance concerning the aspects of the design that are specific to a service-oriented view and how to model these. In Modeling for SOA [2], the CBDi Forum articulates the following guidelines for a model:
- Model Business Level Services
- Model Service Based Collaboration
- Explicit Separation of Interface from Implementation
- Explicit Separation between Provider and Consumer
To ensure that these guidelines are captured in the model, IBM has developed the UML 2.0 Profile for Software Services [3] (documented and published on the IBM® developerWorks® Website), and a Software Architect plug-in [4] that provides the capability to add this profile -- as well as a template model and some sample models -- to a Software Architect installation. This profile is also accompanied by an additional set of guidances that can be added to the IBM® Rational Unified Process® (RUP®) [5]. It is the combination of the UML profile that explicitly models service specifications -- as UML interfaces -- separately from providers (implementation), as well as the separation from service consumers and the guidance that describes how service collaborations can be used to describe business level services.
Once a service has been modeled using this profile, the sample UML to WSDL transformation can be used to generate WSDL source. It is important to realize that the Software Architect transformation itself does not require the application of the profile to the model; however, doing so makes the model unambiguous, and the selected profile elements provide the modeling style that is expected by the transformation. This profile is applied to both the design and the implementation model. The only real difference between these tends to be the amount of detail captured in the model, and often the design model is refined into the implementation model rather than being an entirely separate one.
Installing the UML to WSDL transformation
Before you begin it is important to note that, while the UML to XSD transformation (used in the first article in this series) is included in Software Architect 6.0.1, the UML to WSDL transformation is not currently a product feature. However, the transformation has been made available, as a sample, via the Software Architect developerWorks RAS (Reusable Asset Specification) repository. So before delving into modeling the service that manages the purchase order documents that were modeled in the first article, you need to install the transformation into Software Architect.
Create a connection
To install the UML to WSDL sample -- and the corresponding UML to XSD sample -- transformation, you have to first create a connection to the developerWorks RAS repository.
- From the Window menu, select Show View and then Other.
- Expand the RAS folder in the list and open the Asset Explorer view.
- If you do not have a connection already to the RSA developerWorks RAS repository, click the New Repository Connection button in the Asset Explorer view.
- In the resulting wizard, first select the developerWorks Repository entry (Figure 2) and then accept the default values for the connection (Figure 3).
Figure 2. Add a new Repository connection dialog
Figure 3. IBM Rational developerWorks connection properties
- Now, expand the new connection, and then expand the analysis folder until you see the two sample transformations as shown in Figure 4.
- Now, for both UML to XSD Transform and UML to WSDL Transform, right-click the asset and select Import, and follow the presented dialogs.
Figure 4. The IBM Rational repository
Add the samples to your workspace
Once you have completed these actions, both of these transformations are added to the samples gallery (these are samples, after all, and not directly installable features or plug-ins). The next step is to add the samples to your workspace. While this may seem like extra work, it does have one very important advantage: both of these transformations have been developed by the Software Architect team itself, and as samples they are provided in complete source form. In fact, the sample UML to XSD transform is actually an earlier version of the one provided in the current Software Architect product itself.
- Open the Samples Gallery from the Help menu.
- For each sample you can read the setup instructions, which should mirror the guidance here. More importantly, though, you can import the sample directly, as shown in Figure 5.
Figure 5. The Sample Gallery
Now that you have imported them, these samples are included as plug-in projects in your current workspace, which means that you cannot directly execute the transformations. To use the transformations, you have to start a runtime workbench, ensuring that the new plug-ins are included in its configuration. Once the new workbench is running, you can either import existing models into its workspace or create new models to work on. To ensure that you have correctly installed the plug-ins, right click on elements of your model. You should see a list in the Transform menu like that shown in Figure 6.
Figure 6. The Transformation Menu
If this is the case, you have successfully installed the plug-ins, and you can now start modeling your services.
Order processing example
The service specification you will develop in this article represents an order management service. This is an example service that accepts, cancels, and gets the status of a customer order, represented by the order schema developed in Part One of this series. This section will focus on the specification of the service itself, the external functionality. The modeling approach for software services is described in References [6], so neither the theory nor the installation of the Software Architect plug-in will be covered here.
Creating a service design model
Start by creating a new model following these steps.
- From the File menu, select New -> Other.
- In the resulting dialog, open the Modeling folder and then UML Model.
- Once you have selected this, you will be presented with the model details dialog.
- Select Service Design Model from the list of templates and name your model. In this example, the model is called Order Management Service Design.
- When you have created the model, open the diagram named Model Overview Diagram in the root of the model. You will see the default model structure provided by the template.
Take some time to explore the model structure, especially the Reusable Design Elements package, which contains useful modeling constructs that you will take advantage of later on. Figure 7 shows the diagram from the root of the resulting model.
Figure 7. Initial service design model
Copying the schema model
One issue you do face, unfortunately, is that the schema model you created in the first article is not directly reusable in this exercise. The problem is that in order to generate the schema in a WSDL file, the UML to WSDL transformation uses the sample UML to XSD transform (not the product UML to XSD transform used in the first article). What this means is that you will have to copy the schema package into your services model and reapply the sample XSD profile. This is not ideal, and somewhat time consuming, but here are the steps.
- Open the schema model created in the first article.
- Select the package po-2, right-click it, and Copy it to the clipboard.
- On the root of the new service design model, right-click and Paste from the clipboard.
- You need to remove the original profile and, selecting the po-2 package, add the sample XSD profile (SampleXSDProfile).
- You have to include a reference to the XSD library model. To do so, right-click the root of the new service design model, select Import Model Library, and then select the SampleXSDDataTypes entry.
- You now have to reapply the stereotype <<schema>> to the package, and set the correct properties.
- Referring back to the first article, you need to use the stereotypes $lt:$lt;simpleType$gt:$gt;, $lt:$lt;complexType$gt:$gt;, and $lt:$lt;attribute$gt:$gt;.
Figure 8 shows the result of all this hard work (note that there are some features in this diagram not present in the original PO schema: these will be introduced later).
Figure 8. The updated Purchase Order XSD model
While this is a challenge in the short term, you will not need to do this any more once the UML to WSDL transformation is included in the Software Architect product.
Now that you have reformatted the schema model, you should ensure that your services can reuse the schema elements. To do this, open the original diagram in the root of the model and drag your schema package onto the diagram. Once this is done, add two package import relationships from the Message and Services views to the schema package, as shown in Figure 9 below.
Figure 9. Including the schema package
Modeling a service specification
Modeling Web services focuses on the specification of a service: that is, the operations it responds to, the messages in and out, and the behavior of the service that a client can expect and rely upon. For this example, you are choosing to use a UML profile and the particular set of techniques described in [3] and [6], the first of which is a service specification. To help you create a new service specification, the model includes (as mentioned before) a set of reusable design elements. Follow these steps:
- Open this package.
- Copy and Paste the $I{service} element into the Package Service view.
- Right-click the newly created element and select Find/Replace
- Replace the text "${service}" with "OrderManagement"
This gives you a starting point. From a transformation point of view, this service specification maps to a WSDL port type, which at this time is an uninteresting port type because it has no operations or messages so far. So, just to prove the point, run the transformation now and see what happens. Figure 10 demonstrates this: basically, the transformation has a set of validation rules and will not execute from a specification that has no operations. Technically, WSDL does allow a port type to have no operations, but it's kind of hard to imagine why. In addition, note that there is a second error stating that the target of the transform is invalid. This is due to the fact that, in Software Architect terms, WSDL files belong in Web projects, and in this case you have already created the OrderManagementEARWeb project.
Figure 10. Transformation dialog error
Getting back to completing your service specification, add some basic operations (listed in Table 1, following) to it. You'll notice that it includes elements from the purchase order schema, including the POID element that was not a part of the original schema in Part One of this series. The issue is that you have no element in your purchase order that identifies it. So while it seems reasonable to send a purchase order as the input to CancelOrder (or even GetOrder and GetOrderStatus of), how do you correlate it to a previously accepted order? Therefore, you need to add an identifier to the order -- but then at what point is the order number assigned?
Table 1. Basic operations added to the service specification
| Operation Name | Parameter Name | Parameter Type | Return Type |
|---|
| AcceptOrder | Order | po-2::PurchaseOrder | | | CancelOrder | Order | po-2::PurchaseOrder | | | GetOrder | OrderID | po-2::POID | po-2::PurchaseOrder | | GetOrderStatus | OrderID | po-2::POID | |
You will have to make some changes to the schema itself, adding a simple type named POID (derived from NMTOKEN) with a pattern set to PO\d{2}-\d{8}. Now, add an attribute to the original purchaseOrderType, named purchaseOrderID, typed POID and stereotyped as «attribute», and finally, set the multiplicity to 0..1 (it has to be optional so that the client doesn't have to enter a value before submitting for acceptance). Next, in the message view, add an enumeration OrderState with literals Created, Accepting, Accepted, Canceling, Canceled, Picking, Shipping, Shipped, Fulfilled. Also add a complex type OrderStatus and an attribute state of type OrderState. The results should be similar to those shown in Figure 11.
Figure 11. Additions to the Schema and Message Views
All of this should leave you with a service specification like that shown in Figure 12.
Figure 12. Service specification so far
You can now re-run the transformation, using the service specification above as the source and a dynamic Web project as the target. The result of the transformation is the WSDL shown in Listing 1. Note that the schema definition has been elided, as it is the same as the schema produced in Part One.
Listing 1. Result of the re-run schema
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="IOrderManagement"
targetNamespace="http://tempuri.org/" xmlns:tns="http://tempuri.org/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns="http://schemas.xmlsoap.org/wsdl/">
<wsdl:types>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://tempuri.org/">
...
</xsd:schema>
</wsdl:types>
<wsdl:message name="IOrderManagement_GetOrderStatusResponse">
<wsdl:part name="ReturnResult" type="tns:OrderStatus" />
</wsdl:message>
<wsdl:message name="IOrderManagement_GetOrderResponse">
<wsdl:part name="ReturnResult" type="tns:purchaseOrderType" />
</wsdl:message>
<wsdl:message name="IOrderManagement_GetOrderStatusRequest">
<wsdl:part name="OrderID" type="tns:POID" />
</wsdl:message>
<wsdl:message name="IOrderManagement_CancelOrderRequest">
<wsdl:part name="Order" type="tns:purchaseOrderType" />
</wsdl:message>
<wsdl:message name="IOrderManagement_AcceptOrderRequest">
<wsdl:part name="Order" type="tns:purchaseOrderType" />
</wsdl:message>
<wsdl:message name="IOrderManagement_GetOrderRequest">
<wsdl:part name="OrderID" type="tns:POID" />
</wsdl:message>
<wsdl:portType name="IOrderManagement">
<wsdl:operation name="AcceptOrder">
<wsdl:input message="tns:IOrderManagement_AcceptOrderRequest" />
</wsdl:operation>
<wsdl:operation name="CancelOrder">
<wsdl:input message="tns:IOrderManagement_CancelOrderRequest" />
</wsdl:operation>
<wsdl:operation name="GetOrder">
<wsdl:input message="tns:IOrderManagement_GetOrderRequest" />
<wsdl:output message="tns:IOrderManagement_GetOrderResponse" />
</wsdl:operation>
<wsdl:operation name="GetOrderStatus">
<wsdl:input message="tns:IOrderManagement_GetOrderStatusRequest" />
<wsdl:output message="tns:IOrderManagement_GetOrderStatusResponse" />
</wsdl:operation>
</wsdl:portType>
</wsdl:definitions>
|
Another aspect of Software Architect that is worth bringing up at this point is the Process Advisor -- a view into the Rational Unified Process -- that you can access from the Help menu. The Process Advisor is context sensitive: it uses the model elements you manipulate as context to provide guidance on the usage of the model. In this case, since you are working on a service specification, you can see that this is already presented in the Advisor -- and at the top of the list. You can also see in Figure 13 that the Advisor has listed an activity from the process guidance -- Service Design -- worthy of review at this time.
Figure 13. The RSA Process Advisor
Modeling the callback specification
In the case of the order management service, you would like the acceptance and cancellation of an order to be asynchronous operations. To this end, you need to describe the specification to be implemented by a client for the service to callback to. To create the callback specification, you use the same process as above, but rename ${service} to OrderManagementCallback. Also, add the operations shown in Table 2 to the new specification.
Table 2. Operations added to the callback specification
| Operation Name | Input Name | Input Type | Result Type |
|---|
| OrderAccepted | Status | OrderStatus | N/A | | OrderAcceptedFault | Fault | OrderManagementFault | N/A | | OrderCanceled | Status | OrderStatus | N/A | | OrderCanceledFault | Fault | OrderManagementFault | N/A |
To complete the operations, you need a new message type, the order management fault. This is simply added to the model (in the Message View), as shown in Figure 14.
Figure 14. The OrderManagementFault message
Modeling the service provider
To model the service itself (that is, the software component that implements the service specifications just described), you will use UML Components and Ports. As with the service specifications before, you will use one of the reusable design elements, in this case called ${complexservice}Provider. Rename this element to OrderManagement and open up the nested elements. The result should be something like that shown in Figure 15. In this case, however, you have already modeled the IOrderManagement and callback service specifications, so you can delete the two that are created by the pattern.
Figure 15. The reusable Complex Service provider
To complete the model, recreate the implementation and usage relationships to the specifications you have already created. This will result in a complete service provider, as shown in Figure 16 (this diagram is part of the open OrderManagement Overview pattern).
Figure 16. The Complete Service provider
From this diagram, you can see the provided and required interfaces, but what you do not see is that the model also uses UML Ports to represent services (particular endpoints provided by the service provider). To visualize these, right-click the service provider and select Filters -> Show External View, and you will see a view like that in Figure 17.
Figure 17. The Service Provider External view
If you select the service provider and execute the WSDL transformation now, you will find a lot more detail in the resulting XML. Listing 2 demonstrates this, showing that you now have a service implementing the port type and a default binding for HTTP/SOAP. This completes the generation of the Web service specification, and while you do have the flexibility to add new bindings through the model, the use of HTTP/SOAP with doc-literal encoding is the most common.
Listing 2. Result of executing the latest WSDL transformation
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="OrderManagementProvider"
targetNamespace="http://tempuri.org/" xmlns:tns="http://tempuri.org/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns="http://schemas.xmlsoap.org/wsdl/">
<wsdl:types>
...
<wsdl:binding name="IOrderManagementBinding"
type="tns:IOrderManagement">
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />
<wsdl:operation name="AcceptOrder">
<soap:operation soapAction="http://tempuri.org/AcceptOrder/" />
<wsdl:input>
<soap:body use="literal" />
</wsdl:input>
</wsdl:operation>
<wsdl:operation name="CancelOrder">
<soap:operation soapAction="http://tempuri.org/CancelOrder/" />
<wsdl:input>
<soap:body use="literal" />
</wsdl:input>
</wsdl:operation>
<wsdl:operation name="GetOrder">
<soap:operation soapAction="http://tempuri.org/GetOrder/" />
<wsdl:input>
<soap:body use="literal" />
</wsdl:input>
<wsdl:output>
<soap:body use="literal" />
</wsdl:output>
</wsdl:operation>
<wsdl:operation name="GetOrderStatus">
<soap:operation soapAction="http://tempuri.org/GetOrderStatus/" />
<wsdl:input>
<soap:body use="literal" />
</wsdl:input>
<wsdl:output>
<soap:body use="literal" />
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="OrderManagement">
<wsdl:port name="IOrderManagementPort"
binding="tns:IOrderManagementBinding">
<soap:address location="http://tempuri.org/" />
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
|
Generating a Java implementation
From an implementation perspective, the next step is reasonably simple: run
the new Web Service Wizard (File -> New -> Other -> Web Service)
and select Skeleton Java bean Web Service as the type. The wizard will
ask you for the location of the WSDL, and you will need to have a configured
server on which to run the project (this example is using WebSphere v6.0 Server
running locally). This will create a skeleton service implementation that you
can complete with business logic. The opening page of the wizard is shown in
Figure 18. Once you have selected the type, the WSDL, and the project, you can
press Finish (most of the advanced settings can be safely ignored).
Figure 18. The first page of the Web Service Wizard
In the next part of this series, you will apply patterns to the service.
Resources Learn
Get products and technologies
-
IBM Rational Software Architect: Download a trial version from developerWorks. Provides the tools needed to view the Business Contract Model and develop service realization models that can be used to generate implementation code for different architectural styles.
Discuss
About the author | 
| | Simon is a Senior Technical Staff Member working in the SOA Solutions team within IBM Rational software and is responsible for strategy for SOA modeling tools. Simon has undertaken a number of standards-related activities for both Rational Software and now IBM in the area of XML (W3C Schema working group), Web Services (RosettaNet architecture team) and Modeling (OMG UML and OCL teams). Simon has also written articles on the subjects of business modeling, software modeling and SOA and is interested to see where and when these threads will combine.
|
Rate this page
| |
