In the previous tip in this series, you learned how to identify the domain packages within the object-oriented application design for SWA Online, an online storefront that enables customers to place orders and have them shipped to their homes (see Resources). The next and final steps in this process are to identify domain package contracts and then to define the Web services interfaces.

Step 5: Define domain-package contracts

Domain-package contracts are those class contracts that are accessed by classes outside of a domain package. (Class contracts that are only used by classes within the subsystem are not domain-package contracts.) For example, the contracts for the Item package in Figure 1 would be the combination of the class contracts of the Item, ShippingContainer, and ShippingRestriction classes, because they were accessed from classes outside of the package. (Figure 1 and all other examples in this series are drawn from your SWA Online example.) Because ContainerType instances only collaborate with ShippingContainer objects, the class contracts of ContainerType can be ignored. As you would expect, the domain-package contracts form the collection of Web services that can potentially be provided by a package.

Were you to just combine the class contracts of the classes depicted in detail in Figure 2, you would have the following list:

• reorder()
• reserveItems()
• getPrice()
• getRestrictions()
• getContainer()
• getFullDescription()
• getVolume()

This list is interesting, but you should see if you can pare it down in order to reduce the number of Web services that you will eventually offer. To do this, let's examine why some of the contracts are invoked. For example, the contract getContainer() is invoked so that getVolume() can later be invoked by the Shipment class, presumably to determine shipping cost and packing requirements. Therefore, these two contracts could be combined, likely into a getShippingContainer() contract that would return an XML structure (more on this in a bit); they could perhaps even be rolled up into a getItem() contract that returns an XML structure containing all relevant item data. Similarly, getPrice(), getRestrictions(), and getFullDescription() could also be rolled up into getItem().

Here's the new, simplified list of contracts:

• reorder()
• reserveItems()
• getItem()

It's important to make sure that contracts of a package are cohesive -- that is, that it makes sense to put them together. If the contracts do not make sense as a group, then you should distribute them among multiple packages. If your initial contracts for the Order component include fufillOrder(), addItem(), removeItem(), and orderLunchForExecutives(), you likely have a problem, because the lunch ordering contract doesn't fit well with the others.

Back to top

Step 6: Define Web service signatures

What should the signatures be for the three Web services supported by the Item package? First, you know that they'll return XML structures, because that's the way that Web services work. You'll need to design those structures (see Resources for more information) to return the information that you require. In the case of getItem(), you would need to include basic information such as the item price, description, and number, as well as container information and any shipping restrictions.

Second, you need to identify the parameters passed to the Web services as well as the return values from them. To identify these parameters, you need to ask yourself what minimal information is required to fulfill the purpose of the Web service. For example, to reoder an item, you would need to identify which item you want to reorder and the number to reorder. Similarly, to identify the return value, you need to ask yourself what information the Web service should provide to the invoker. In the case of reordering, the invoker of that service would want to know whether the item was successfully reordered. For this case, the signatures are:

• reorder(int itemNumber, int orderAmount): ReturnStatusXML
• reserveItems(int itemNumber, int orderAmount, int orderNumber) : ReturnStatusXML
• getItem(int itemNumber) : ItemXML

A fundamental concept to remember is: At this point, you are no longer modeling objects; you're modeling functions. Thus, you need to pass such basic information as identifiers -- itemNumber and orderNumber, for example -- as parameters, so the Web service will act on the right objects within your system.

Back to top

Discover your applications' Web services potential

In The Unified Modeling Language User Guide (see Resources), Grady Booch, Ivar Jacobson, and James Rumbaugh, known as "The Three Amigos," suggest that you "manage the seams in your system" by defining the major interfaces for your components and packages. What they mean by this is that you want to define the interfaces -- in this case, the collection of Web services supported by each package -- early in the design process. That way, you are free to work on the internals of each package without having to worry about how you will affect other development efforts -- you just have to keep the defined interface stable.

This series of four articles presented a process, based on the techniques presented in Designing Object-Oriented Software and expanded upon in Building Object Applications That Work (see Resources for links to both) for refactoring a traditional object design for the purposes of deploying it to a distributed environment. To illustrate this process, you worked through the SWA Online case study, a simplistic e-commerce system whose initial high-level class diagram is depicted in Figure 3. By doing so, you discovered how to focus on the critical aspects of your design that were pertinent to identifying Web services. You also saw how to organize your design into domain packages, and then how to keep the number of Web services provided by your system to a minimum.

You can see how far we came by looking at the initial class model for SWA Online in Figure 3. Now you should be able to use the techniques outlined in this series to build your own Web services out of your existing object-oriented applications and models.

Resources

• Building Object Applications That Work: Your Step-by-Step Handbook for Developing Robust Systems with Object Technology, Scott W. Ambler (Cambridge University Press, 1997)
  
  
• The Object Primer 2nd Edition: The Application Developer's Guide to Object Orientation, Scott W. Ambler (Cambridge University Press, 2001)
  
  
• Agile Modeling: Best Practices for the Unified Process and Extreme Programming, Scott W. Ambler (John Wiley & Sons, 2002)
  
  
• The Unified Modeling Language User Guide, G. Booch, J. Rumbaugh, and I. Jacobson, (Addison Wesley Longman, 1999)
  
  
• Designing Object-Oriented Software, R. Wirfs-Brock, B. Wilkerson, and L. Wiener (Prentice Hall, 1990)
  
  
• Component Software: Beyond Object-Oriented Programming, C. Szyperski (ACM Press, 1998)
  
  
• The Object Management Group's Website provides the latest specification for UML.
  
  

• Learn more about using VisualAge UML Designer.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Step 5: Define domain-package contracts
• Step 6: Define Web service signatures
• Discover your applications' Web services potential
• Resources
• About the author
• Comments

Next steps from IBM

Rational Modeler is a free, UML 2.1 based environment that helps users to improve communication by specifying, visualizing and documenting their system, architecture and software designs using a standard graphical language.

---

• Try: Download a Rational Modeler, a free, UML 2.1 based environment for specifying systems, software, and architecture.
• Buy: Rational Modeler Rhapsody Corporate Edition

Dig deeper into SOA and Web services on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers