Guideline: Service Model Structure
This guideline provides advice for structuring a UML-based service model in Rational Software Architect, so that (1) it can be evolved in a team environment, (2) it is organized to facilitate communication, and (3) its contents can be used effectively as inputs to the Rational Software Architect SOA transforms.
Relationships
Main Description

In this guideline, we provide advice for structuring a UML model created to support an SOA service discovery, specification, realization, and implementation effort.  In the rest of this guideline, such a model will be referred to as a "service model".  The specific modeling product addressed here is Rational Software Architect for WebSphere Software, Version 7.5.4 or higher.  This product will be referred to as "Rational Software Architect" in the rest of this guideline.

Service models need to be structured for at least three purposes:

  • To enable a team of designers, rather than just a single designer, to evolve the model effectively.
  • To enable the model to scale well, conceptually, as the size of the service modeling effort increases.
  • To support the automatic generation of downstream service artifacts, such as XSDs, WSDLs, and BPEL.

We will address each of these issues in this guideline.

Structure the model to support team development

UML models can be considered from at least two perspectives, those being:

  • The logical content (packages, classes, relationships, etc.) of the model.
  • The physical elements (flat files, databases, etc.) that are used to persist the model.

Rational Software Architect persists the logical content of models into one or more physical files.  The question naturally arises -- what is the best way to organize the logical content, and to persist the logical content into files, so that there is minimal conflict when designers/developers work on different parts of the logical model?

There is no universally right answer.  However, this subject has been addressed in great detail in IBM developerWorks papers authored by Kim Letkeman and by William T. Smith.  Please refer to the references at the bottom of this guideline for further information.

Structure the model to support large-scale models

As time goes on, the service model will grow.  If this growth is not disciplined, it will become increasingly difficult to navigate the model, and model maintenance can become more difficult.  Further, if there is no consistent growth plan, it will become difficult to partition the model for effective team development.

With these concerns in mind, we suggest a few rules, which are based in part upon 12 proven SOA Architectural Patterns.  Our rules are:

  • Manage complexity using architectural constructs larger than simple ServiceInterfaces and Participants.  Larger-scale constructs help lift the level of abstraction in the model and promote understanding.
  • Provide "homes" in your model for meaningful architectural viewpoints.  These viewpoints help summarize similar information (such as the messages which have been defined) which might be scattered throughout the model.
  • Package together the model elements that are used to describe a given concept.  Effective packaging helps reduce the clutter of model elements that might otherwise appear in the Rational Software Architect Project Explorer -- and it also assists in model partitioning for team development.
  • Make it easy to support either (1) shared messages and data types -- which supports reuse but which adds coupling into the system, or (2) locally owned messages and data types -- which supports decoupling, but which increases maintenance.

Executing these rules is supported by using the SoaML design template model.  This template model includes the following features:

  • A series of <<perspective>> packages to serve as the home for architectural viewpoints and for architecturally-significant model constructs.  As an example of the former, the template provides <<perspective>> packages for cross-cutting views of services and messages.  As examples of the latter, the template provides <<perspective>> packages for ServicesArchitectures, ServiceContracts, and Service Collaborations, which describe the relationships and dynamic interactions between ServiceInterfaces and/or Participants that might be owned by packages which are located in widely varying locations within the model.
  • Pre-defined package structures to logically group model elements, diagrams, and relationships that describe a given concept.  For example, well-defined package structures are provided for, among other items,
  1. Organizing the business-related and system elements that are commonly examined to identify candidate services.
  2. Elements used to describe ServiceInterfaces.  We recommend that each ServiceInterface, plus all supporting elements such as diagrams, be packaged together.
  3. Elements used to describe service Participants.  We recommend that each Participant, plus all supporting elements such as diagrams, be packaged together.
  • Reusable package structures for describing data elements that are used to define either data that is passed between service operations or data that is internally managed by service implementations.  These package structures can be used to define either local data or shared data.

Structure the model to support the automatic generation of downstream artifacts (XSDs, WSDLs, etc.)

Rational Software Architect provides several transforms to automate the generation of relevant SOA artifacts, such as XSDs, WSDLs, BPEL, and SCA components, from UML models.  The transforms are documented within Rational Software Architect Help.  Their use is further described in:

The transforms mainly touch the following types of model elements:

  • UML-to-XSD:  Packages, Classes, Signals, Enumerations, Data Types, and the relationships between them.
  • UML-to-WSDL:  UML-to-XSD content; Components stereotyped as <<Participant>> or which offer a provided interface; Interfaces; Classes stereotyped as <<ServiceInterface>>.
  • UML-to-SOA:  UML-to-WSDL content, plus structured Activities that are owned by a component and which model the implementation of a service operation.
  • UML-to-SCA:  UML-to-WSDL content plus SCA-specific model markup.

We provide these guidelines to facilitate meaningful execution of these transforms.

  • In addition to the <<perspective>> packages in the SoaML template model, create additional package structures that model the directory structures into which you want your artifacts to be generated.  For example, create root level packages named "com", "org", etc., build package structures under these, and create the UML source elements that are to be transformed within this package structure.  We often refer to this package structure as the "implementation" package structure.
  • Ensure that appropriate package import relationships are defined, so as to support necessary visibility.  For example, if you are using shared messages, the package that owns a ServiceInterface needs to import the package that owns the message types the ServiceInterface operations reference.
  • Ensure that SoaML Participants own the structured Activities that model the implementations of the service operations that the Participant provides.  It is necessary to follow this rule in order to generate BPEL (Business Process Execution Language) code during execution of the UML-to-SOA transform.  This BPEL can be consumed by process choreography tools, such as WebSphere Integration Developer.

The SoaML sample model, usable with Rational Software Architect 7.5.4 and higher, is an exemplar that illustrates the use of these best practices.

References

Kim Letkeman's IBM developerWorks series on "Comparing and Merging UML Models in Rational Software Architect" is the most in-depth set of references on using the model management capabilities that are built into Rational Software Architect.  Parts 3 and 5 provide excellent guidance regarding model partitioning schemes.

William T. Smith's IBM developerWorks series on "IBM Rational Architecture Management Software model structure guidelines" provides excellent conceptual information on the definitions of, and the relationships between, logical models and physical models.  Smith also talks the reader through several issues that need to be considered when developing a model structuring scheme.



 

More Information