 | Level: Introductory Rimas Rekasius (rimas@us.ibm.com), Senior Software Engineer, IBM
01 Mar 2003 Recently, WS-I, the Web Services Interoperability Organization, released public Working Group Drafts of the WS-I Sample Application Use Case and Architecture documents, showing the progress WS-I is making in developing its first major deliverable, the WS-I Basic Profile. This article provides a preview of the WS-I sample application.
About WS-I
The publication of the WS-I Sample Application Use Case and Architecture documents comes on the heels of the release of the first public Working Group Draft of the WS-I Basic Profile version 1.0 specification, which was described in Chris Ferris' excellent article "First look at the WS-I Basic Profile 1.0," and the WS-I Usage Scenarios document, which was the subject of my previous article "First look at the WS-I Usage Scenarios" (For more information and links to these documents and articles, see Resources). The Use Case and Architecture draft documents have gone through several cycles of review within the organization, and as such are considered to be quite stable by its authors, the members of the Scenarios & Sample Applications Working Group. However, further revision is possible as the documents complete the review process as prescribed by the WS-I organization's charter and by-laws.
The Web Services Interoperability Organization is a consortium of, at the time of this writing, about 160 companies representing a wide range of industries including automotive, consumer packaged goods, finance, government, insurance, media, telecommunications, travel, and of course, the computer industry. WS-I is focused on promoting the interoperability of Web services applications across different computing environments and programming languages. It does so by providing advice, best practices, and other resources intended to assist developers of Web services applications. More specifically, WS-I intends to develop what it refers to as profiles of interoperable Web services. So what exactly is a profile? The WS-I Glossary defines it as follows:
Profile: A collection of requirements to support interoperability. WS-I will deliver a collection of profiles that support technical requirements and specifications to achieve interoperable Web Services.
The first of these profiles, currently still under development, is referred to as WS-Basic Profile 1.0. It is focused on the core foundational technologies upon which Web services are based: HTTP, SOAP, WSDL, UDDI, XML, and XML Schema. WS-Basic Profile 1.0 will provide interoperability at the basic connectivity level. Once complete, WS-Basic Profile 1.0 will include the all of the following items:
-
Profile specification: The actual specification of the profile includes a list of non-proprietary Web services-related specifications at certain version levels, plus a list of clarifications and restrictions on those specifications. These clarifications and restrictions are intended to facilitate the development of interoperable Web services.
-
Usage scenarios: The usage scenarios that will be provided in conjunction with WS-Basic Profile 1.0 can be thought of as the technical requirements for using Web services in a profile-conformant manner. This does not imply that using Web services in different ways is not conformant with the profile. It simply means that following the guidelines of WS-I usage scenarios is one way to ensure profile conformance.
-
Sample application(s): In order to demonstrate to Web services developers how to use WS-Basic Profile 1.0 to develop interoperable Web services, WS-I chartered a working group to create a sample application. The sample application will portray a Supply Chain Management application for a fictitious consumer electronics retailer.
-
Testing tools: In addition to all of the above, WS-I will provide reference implementations of test tools that can be used by developers to test Web services for profile conformance. One tool will monitor all interactions between a Web service and its client, logging the information it captures to a file. A second tool analyzes the generated log file to determine if the messages exchanged, as well as other artifacts of the Web service (its WSDL and UDDI registration), conform to the guidelines specified in the profile.
 |
Sample application overview
In order to demonstrate to Web services developers how WS-Basic Profile 1.0 can be used to develop interoperable Web services, WS-I chartered a working group to create a sample application. One of the primary goals of the sample application is to provide as much coverage of the WS-I Basic Profile 1.0 specification (see Resources) as reasonably possible in a single application. This manifests itself in many ways, including the use of a variety of naming conventions in the schema and WSDL and the use of both SOAP message styles allowed by the profile (i.e. RPC/lit and doc/lit), etc. In other words, although the Web services designed and implemented in the sample application are interoperable, they do not necessarily represent best practices for designing and implementing Web services.
The sample application will portray a Supply Chain Management application for a fictitious consumer electronics retailer. Consumers go to a Web page provided by the retailer and order products. The products to be offered include TVs, DVD players and video cameras from each of the following manufacturers: Brand1, Brand2, and Brand3. The retailer keeps inventories across three warehouses. When processing an order from a customer, the retailer tries to ship the ordered products from each of its warehouses in succession. When a warehouse is asked to ship items from a customer order, it attempts to do so from its stock on hand. Each warehouse reports back to the retailer which portion (if any) of the customer order it was able to fulfil. The retailer aggregates the reports from its warehouses and presents the composite result back to the customer. Meanwhile, if a warehouse was able to supply some part of an order, and if doing so caused the warehouse's stock on hand for a certain item to drop below a minimum threshold level, it re-stocks its inventory by ordering finished goods from the appropriate manufacturer. Similarly, if a manufacturer's processing of an order for finished goods causes its stock on hand to drop below a minimum threshold level, it launches a production run.
|
Sample application development process
Before getting into the details of the sample application itself, I should probably go over the development process that was followed by the members of the Scenarios & Sample Applications Working Group. Two sub-groups performed the development of the sample application: the Use Case and Design (UCD) team and the implementation (and test) team. The UCD team started out by capturing the requirements in the form of use cases. The team chose to use the Unified Modeling Language (UML) for modeling the system as a majority of the team seemed to know and understand it. Capturing the requirements, although time-consuming, was actually rather straight-forward. The architecture and design were a little less straight-forward.
Once they resolved all of the issues with the use cases, the UCD team began work on the architecture and design of the sample application. The team started to produce a single, global object model for the entire Supply Chain Management sample application. However, the group quickly realized that not only was this not practical, it also was not very realistic: in the real world a supply-chain is made up of different companies, each with their own information processing systems. Thus they divided the sample application into three distinct logical systems: the Retailer System, the Manufacturing System, and the Demo System. [Note: A fourth system, the Part Supplier System, can easily extend the architecture of the sample application to address future profile requirements.]
They designed each system individually. Within each system, they typically identified first the cross-system interfaces. These interfaces then became the Web services in the application. Then an object model and sequence diagrams were created for each system. The purpose of the object models was more to help establish a common set of terms between the UCD and implementation teams, not necessarily to describe precise implementation details of the Web services. The working group found that in an application which spans system and organizational boundaries, clearly defined and agreed-to Web service interfaces are much more critical to the success of the application than highly detailed object models.
Another key insight that the working group had during the development of the sample application had to do with the sequence diagrams. The UCD team initially did the sequence diagrams with respect to the object diagrams. However, as the implementation team began to study the architecture and design of the sample application, they thought that the sequence diagrams would be more useful if they were done with respect to the Web services (i.e. operations on Web services, not methods on objects). Again, in an application which spans system and organizational boundaries, it is more important to define the order of operations between systems than within a system.
Use cases
During the requirements gathering phase of the development of the Supply Chain Management sample application, the group identified the following use cases:
- UC1: Purchase Goods
- UC2: Source Goods
- UC3: Replenish Stock
- UC4: Supply Finished Goods
- UC5: Manufacture Finished Goods
- UC6: Configure and run demo
- UC7: Log Events
- UC8: View Events
Figure 1 depicts these use cases in the UML use case diagram. Note that this figure may not exactly be pure UML, as UML is usually used to model a single system, whereas the sample application is really composed of three systems. Typically, actors are shown outside the box which represents the system being modeled. However, when working with Web services, one system is an actor to another system. This has been represented in Figure 1 by drawing an actor inside of the system which is acting with another system.
Figure 1. Use case diagram
The first three use cases (UC1: Purchase Goods, UC2: Source Goods, and UC3: Replenish Stock) are all related to the Retailer System. They represent the actions associated with buying consumer electronics from the retailer's Web site, shipping the purchased goods to the consumer from one or more warehouses, and replenishing the stock level of a warehouse if necessary.
The next two use cases (UC4: Supply Finished Goods and UC5: Manufacture Finished Goods) are related to the Manufacturing System. They represent the manufacturer of some consumer electronics product processing a purchase order from a retailer (or, more precisely, from one of its warehouses), as well as the production run which must occur when the manufacturer's stock of finished goods is depleted.
The final three use cases (UC6: Configure and run demo, UC7: Log Events, and UC8: View Events) are all related to the Demo System. They represent a user of the sample application demo configuring different implementations of the application's Web services and running the demo to see that the different implementations interoperate. During the execution of the sample application, events are logged so that the demo user can see the interactions of the various Web services behind the scenes.
Retailer system
The first system in the Supply Chain Management sample application is the Retailer System, illustrated in Figure 2.
Figure 2. Retailer system deployment diagram
The deployment diagram in Figure 2 shows that the Retailer System consists of the following three Web services:
- Retailer Service
- Warehouse Service
- Warehouse Callback Service
The Retailer Service has two operations: getCatalog and submitOrder. The first operation, getCatalog, is part of UC1. It returns a list of all the products that the retailer sells. the retailer's storefront Web site calls the operation, and the results are displayed to the consumer. The second operation, submitOrder, is also part of UC1. It takes as input information about the customer and the product(s) being ordered, and returns status information as to which of the ordered product(s) have been shipped. The architecture document provides a high-level description of the Retailer Service, but the details are available to the interested reader in the Retailer.wsdl file (and its associated includes -- see Resources).
The Warehouse Service has just one operation, ShipGoods, which is part of UC2. It takes as input a list of order items that have not yet been shipped, as well as a reference to the customer who placed the order. For each line item in the order, if the ordered quantity is available in the warehouse, the warehouse ships the item and reduces its inventory level. If the new inventory level is below a minimum threshold, the warehouse will place an order with the manufacturer to replenish its stock. The Retailer Service calls the operation, which returns a list with status as to which line items it was able to ship. The use case document includes a non-functional requirement which states that a Retailer owns exactly three warehouses (referred to as A, B and C for simplicity). Thus, the Retailer Service will call the ShipGoods operation of each warehouse in succession until the entire customer order is fulfilled. The definition of the Warehouse Service can be found in the Warehouse.wsdl file(see Resources).
The Warehouse Callback Service is actually defined as part of the Manufacturing System, but it is implemented by the Retail System. It has two operations: SubmitSN and ErrorPO. This service implements UC3. The Manufacturing System calls the SubmitSN operation of the Warehouse Callback Service to indicate that the manufacturer has successfully finished asynchronously processing a purchase order from the warehouse to replenish its stock. The input is a shipping notice document; the output is simply an indicator that the shipping notice was received. If, on the other hand, the manufacturer is unable to process the purchase order, it indicates so by calling the ErrorPO operation, providing the reason for the error. This is the final request/response portion of the Basic callback scenario described in the WS-I Usage Scenarios document. The Warehouse Callback Service is defined in the Manufacturer.wsdl file (see Resources).
Figure 3 shows a class diagram for the Retailer System. It captures the concepts discussed above, as well as indicates the relationships among the concepts.
Figure 3. Retailer system class diagram
Manufacturing system
The second system in the Supply Chain Management sample application is called the Manufacturing System, and it is illustrated in Figure 4.
Figure 4. Manufacturing system deployment diagram
The Manufacturing System consists of a single Web service:
The Manufacturer Service has but one operation, submitPO, which is related to UC4 and UC5. The purpose of the submitPO operation is to electronically send a purchase order for manufactured goods. A warehouse calls the submitPO operation when it has been determined that the inventory level has dropped below some minimum level. The input to the operation is a purchase order document, and the output is a response designating that the purchase order has been received and validated. This is the initial request/response portion of the Basic callback scenario described in the WS-I Usage Scenarios document. The Manufacturer Service is defined in the Manufacturer.wsdl file.
Note that the use case document includes a non-functional requirement which states that the Retailer sells exactly three types of consumer electronics items (namely TV, DVD player, and video camera), and that one of each type of item is produced by each of three different manufacturers (referred to as Brand1, Brand2 and Brand3 for simplicity). Thus, the Retailer offers nine distinct products:
- Brand1 TV
- Brand2 TV
- Brand3 TV
- Brand1 DVD player
- Brand2 DVD player
- Brand3 DVD player
- Brand1 video camera
- Brand2 video camera
- Brand3 video camera.
Figure 5 shows a class diagram for the Manufacturer System showing the relationships among many of the classes in the system's implementation.
Figure 5. Manufacturing system class diagram
Demo system
The third and final system in the Supply Chain Management sample application is the Demo System, which is depicted in Figure 6. The Demo System is not actually a part of the Supply Chain Management application; it contains infrastructure necessary to effectively demonstrate Web service interoperability using the Supply Chain Management application.
Figure 6. Demo system deployment diagram
The Demo System consists of a pair of Web services:
- Configurator
- Logging Facility
The Configurator Web service has a single operation, getConfigurationOptions, which is used in implementing UC6. The purpose of this operation is to return a list of all registered implementations of the Web services which make up the Supply Chain Management application. The only input is a flag which is used to denote that a UDDI lookup is required (as opposed to allowing cached values from a previous lookup to be returned). This operation is invoked by a demo Configuration Web page which precedes the Retailer's Web page. You can find the details of this Web service in the Configurator.wsdl file (see Resources).
The Logging Facility Web service contains two operations, logEvent and getEvents, which are used in implementing UC7 and UC8, respectively. The purpose of the logEvent operation is to log information about some event which has occurred as a result of executing the Supply Chain Management sample application. Each of the Web services in the sample application calls this operation. Conversely, the purpose of the getEvents operation is to retrieve previously logged events. All events associated with a single execution of the sample application are retrieved. This operation is called as a result of the demo user requesting to see the actions that occurred behind the scenes during the execution of the sample application. The Logging Facility Web service is defined in the LoggingFacility.wsdl file (see Resources).
A class diagram for the Demo System is shown in Figure 7. It shows the type of objects (and their relationships) that might be necessary in the system's implementation.
Figure 7. Demo system class diagram
Profile coverage
As mentioned earlier, one of the main goals of the sample application is to cover as much of the WS-Basic Profile 1.0 as possible. This goal is in many cases contradictory to another goal for the sample application which I have read in the press recently; namely to be a source of best practices for developing interoperable Web services. The best way to illustrate this is to summarize some of the various aspects of the Web services in the sample application, which I have done in Table 1.
As you can see, at least one Web service in the sample application implements each of the three usage scenarios defined by WS-I. All of the Web services use the Synchronous request/response usage scenario, the Manufacturer and Warehouse Callbacks implement the Basic Callback usage scenario, and the Logging Facility uses the One-way usage scenario.
The WS-Basic Profile 1.0 allows two styles of SOAP messages for Web services: RPC/literal and Doc/literal. The sample application Web services use a mixture of both. The WS-Basic Profile 1.0 allows conformant Web services to use SOAP headers for application-specific purposes. Again, some of the sample application Web services use SOAP headers and some do not.
Data types is one area where profile coverage had to be balanced with some semblance of reality in the sample application: after all, not many real-world applications use each and every data type that the programming language or runtime environment allows. The Scenarios & Sample Applications Working Group chose what it thought were some of the most commonly used data types.
Likewise, there was a mixture of XML attribute usage (or not), SOAP action specification (or not), and the use of a variety of different naming conventions in the WSDL and XML schema files. It may seem like the Scenarios & Sample Applications Working Group suffered from a lack of consistency, but this was done intentionally in order to stress interoperability. It can be argued, especially in a B2B (business-to-business) environment, that consistency across different organizations is unlikely. In fact, even within a single organization it can be difficult to maintain consistency. This is precisely why interoperability is so important.
External view
Up until now you have seen the WS-I Sample Application from an internal perspective. Figure 8 attempts to show the sample application from an external viewpoint.
Figure 8. Sample application flow
In addition to providing the requirements (use case document), design (architecture document), and source code for the sample application, members of the Scenarios & Sample Applications Working Group plan to showcase the sample application as a live interoperability demo. As depicted in Figure 8, when using the demo, you will start at the public WS-I.org Web site. On the public WS-I.org Web site there will be a link to another Web page which describes the sample application and how to run the demo. This Web page will also contain link(s) to at least one Scenarios & Sample Applications Working Group member's Web site hosting the user interface (UI) of the interoperability demo and Supply Chain Management sample application. This Web page is referred to as the Configuration Web page since this is where you will configure the interoperability demo. Configuring the interoperability demo consists of selecting an implementation of each of the Web services in the sample application: Retailer, Warehouse A, Warehouse B, Warehouse C, Manufacturer 1, Manufacturer 2, Manufacturer 3, and Logging Facility. Note that Warehouse X actually refers to a pair of Web services: Warehouse and Warehouse Callback. Also note that the Configurator Web service itself is not configurable; rather it is hard-coded in the UI.
Having configured the demo, you proceed to the next Web page, which is called the ShoppingCart page. This is where you select the items to be purchased and the quantity of each item. When you have made your final selections, you submit the order to the retailer. The retailer consults its warehouses, which in turn may (asynchronously) submit its own orders to one or more manufacturers. When processing of your (the consumer's) order is complete, you are presented with the OrderStatus Web page, where you will be informed whether any part of your order could not be fulfilled by the retailer. At this point you will most likely visit the TrackOrder Web page, where the system will display a log of the events which transpired during the processing of the order. This is not so much order tracking as it is viewing the interactions between the Web services which comprise the sample application.
Summary
The primary goal of the Web Services Interoperability Organization is to ensure that Web services can interoperate seamlessly, regardless of the language they were written in and the platform they are deployed on. In support of this goal, WS-I is developing profiles of interoperable Web services, the first of which is the WS-Basic Profile 1.0. While the profile specification is intended to define what to do (and not to do) to ensure the interoperability of Web services, the sample application is intended to provide an example of Web services which conform to the WS-Basic Profile specification, and thus have easily achieved interoperability. In addition to the sample application, WS-I will also provide reference implementations of test tools which can be used to test the conformance of your own Web services to the WS-Basic Profile specification. This will be the topic of a future article.
Resources
About the author | | | Rimas is currently an architect with IBM's Emerging e-business Industry Standards Architecture group, where he represents IBM as a member of the Scenarios and Sample Applications Working Group in WS-I. Prior to his current assignment, Rimas spent many years working with IBM's customers to help them implement distributed computing technologies in their enterprises. You can contact Rimas at rimas@us.ibm.com. |
Rate this page
| |
