Overview
Service specifications, which are modeled using SoaML ServiceInterfaces, are the central structural concept of the service model. We do the following in this tool mentor:
Model element creation techniques are described in Tool Mentor: Create SoaML Model Elements. Those instructions are not repeated here.
The instructions in this tool mentor apply to Rational Software Architect for WebSphere Software, Version 7.5.4 and
later.
The following diagram illustrates the portions of the service model structure that are used in this tool mentor.
Notable aspects include:
-
Service Collaborations provide significant input into ServiceInterface specification.
-
Service Contracts can be created to document the behavioral protocols to which
service consumers and providers must conform when a service is being used.
-
Specifications for collaborative services -- those which interact with consumers using more that a simple
request-response protocol -- can be involved. These specifications commonly include:
-
Protocols, which either are owned directly by the ServiceInterface or are defined using
ServiceContracts
-
Provided and required interfaces
-
Overview and structure diagrams to help describe the ServiceInterface
-
The data content of the service operations is expressed in terms of enums, parameter types, and messages. These can be derived from information types, which represent information stores which are maintained
within service providers, or from domain types. The service data model elements can be shared elements (as is
done here) or elements which are private to each service provider. See Pattern 9, Pattern 10, and Pattern 11 for considerations regarding service operation signatures
and the service data model.

Review each "simple" ServiceInterface to ensure that it should be simply a stereotyped UML Interface. Examine each
"collaborating" ServiceInterface to identify its provided and required interfaces.
For each ServiceInterface in the implementation package structure, do the following:
A. Confirm appropriate ServiceInterface type -- "Simple" or "Collaborating"
-
Select the ServiceInterface in Project Explorer. Right-click and select Modeling References > Enclosing
Model.
-
In the list of search results, identify each property and each role. If the instructions defined in Tool Mentor: Analyze Service Collaborations were followed, these represent
instances of the ServiceInterface which were used in Service Collaborations. Navigate in turn to each
property and role in Project Explorer.
-
Examine the Activities and Interactions in which the property and role appeared. Use the rules provided in Guideline: Identify Service Interfaces from Collaboration Role Interaction Patterns and its five associated examples to identify whether the ServiceInterface is a "simple"
ServiceInterface, with a single provided (realized) interface, or whether it is a collaborating
ServiceInterface with a provided interface and one or more required (used) interfaces. If necessary,
create a new ServiceInterface with the correct metaclass and fix up the model so that the new
ServiceInterface is referenced wherever the old ServiceInterface was referenced. Then, delete the old
ServiceInterface.
B. Create UML interfaces
-
For each collaborating ServiceInterface, begin by creating a single provided (realized) UML Interface and a
single required (used) UML Interface.
-
Create appropriate relationships (realization and uses) between the ServiceInterface and its interfaces.
-
Begin to build the Service Spec diagram, located under the ServiceInterface's package, so that it contains the
ServiceInterface, its interfaces, and their relationships.
C. Add operations to interfaces
-
Revisit the Service Collaborations and identify each operation that needs to be allocated to a provided interface
and each operation that needs to be allocated to a required operation. Briefly:
-
Activity diagram Call Operation actions and messages that are received on sequence diagrams map to
operations on provided interfaces.
-
Activity diagram Accept Event or Accept Call actions and callBack messages on sequence diagrams map to
operations on required interfaces.
-
Create the appropriate operations on the provided and/or required interfaces for each ServiceInterface.
D. Refactor the interfaces and ServiceInterfaces if necessary
-
After all the operations have been allocated to the provided and required interfaces, check to ensure that the
assigned operations are cohesive.
-
If the operations on a provided interface span a greater range of functionality than one service could be
expected to support, refactor the provided interface into multiple interfaces, each of which offers a cohesive
subset of the original operations.
-
Create additional ServiceInterfaces, enough to support the total number of provided interfaces. Have each
ServiceInterface realize one of the refactored interfaces.
-
Revisit the service collaborations to determine which of the callBack operations supports each of the new
ServiceInterfaces.
-
Assign those operations to interfaces that are used by the appropriate ServiceInterface.
-
If the operations on a required interface aren't cohesive, refactor the interface into multiple interfaces and
distribute the initial set of operations to the new interfaces, such that each allocated set is now cohesive.
-
Create a <<usage>> dependency from the original
ServiceInterface to each of the new required interfaces.
Based upon considerations presented in Patterns 10 and 11, determine whether you will use shared or private enums,
parameter types, and messages to define the data types that are used to pass information between services. If
you will be using private data types, postpone the description of the services data model until you have created the
SoaML Participants which will provision the services. After you do that, revisit this step and the one that immediately
follows.
-
Assuming that shared service data types are to be used, create a package structure, within the implementation
packages, which will contain the shared elements. Use the "common" building block in the <<modelLibrary>> to create this package structure.
-
Create the services data model in line with the discussion on pages 368 - 375 of IBM Redbook: Building SOA Solutions Using the Rational SDP. Keep these guidelines in
mind:
-
Model domain types using UML DataTypes or classes, and then use "domainType" as the key word.
-
Derive information types from domain types. Model these using UML DataTypes or classes,
with "InfoType" as the key word.
-
Derive parameter types from PrimitiveTypes, domain types, InfoTypes, or other parameter types. Model these
using UML DataTypes with "ParamType" as the key word.
-
Build messages from PrimitiveTypes, domainTypes, ParamTypes, and other messages. Model messages by using
SoaML MessageTypes.
-
Illustrate the data model using Free Form diagrams. Use one or more such diagrams under each of the packages that
are used to organize your data model. Example: Parameter Types Derived from Domain Types presents the ParamType
diagram for the sample SoaML design model.
Complete the service operation signatures by adding appropriate in, out, inout, and return parameters. These can be
typed using PrimitiveTypes, ParamTypes, or MessageTypes.
-
Select the operation either in Project Explorer or on a diagram.
-
Select the Properties view, then the Parameters tab.
-
Add necessary parameters, typed appropriately.
Examine your Service Collaboration results to check that the parameters which have been assigned to the service
operations are sufficient to satisfy the required information flows through the behaviors.
Building locally owned service protocols
For each collaborating ServiceInterface, create Behaviors (Activities or Interactions) that describe the
protocols service consumers and service providers must conform to during use of a service. If the
protocol involves only a single consumer, then a simple ownedBehavior, such as the InvoicingService Activity that
appears in the above diagram, normally suffices. The objective is to create a ServiceInterface specification that
is similar to what appears in the second diagram of Example: ServiceInterface (SoaML). Do this by following these steps:
-
Create a new structure diagram under the ServiceInterface.
-
Drag each interface that is involved in the protocol into the structure diagram. This creates a new property (part)
under the ServiceInterface. Connect the new parts appropriately, using the Connector element in the drawing
palette.
-
Create the ownedBehavior -- either an Activity or an Interaction -- under the ServiceInterface. If you are using an
Interaction, create a Sequence diagram under that.
-
For Activity modeling, create partitions and type each one with a property.
-
For Sequence diagram modeling, drag the properties onto the diagram to create the Lifelines.
-
Model the Behavior, using the previous results of service collaboration modeling to guide your understanding of how
the service provider (which will realize the provided interface) and the service consumer (which will realize the
ServiceInterface's required interface) must interact with each other. Follow the guidance in "Modeling user
workflow by using activity diagrams" if you are modeling behavior using Activities. Use "Modeling the interactions
between objects in UML" if you are using interactions.
Now, complete the build-out of the Service Spec diagram for the ServiceInterface. This is precreated under the
ServiceInterface as part of the building block.
-
Drag the ServiceInterface and its UML Interfaces onto the diagram. The realization and usage relationships
should automatically appear. If they don't, make certain that you have created them in the model.
-
Select the ServiceInterface, then select Filters > Show/Hide Compartment > Structure
Compartment.
-
Drag the ServiceInterface's Activity (or Interaction) onto the diagram. If you are dragging an Activity and
its activity diagram compartment appears, it will display the Activity Diagram in a disorganized state. You
can manually reorganize this if you wish. As an alternative, do the following:
-
Select the Activity, right-click, and select Filters > Show/Hide Compartment > Name
Compartment Only.
-
Drag the Activity diagram from the Project Explorer and place its icon close to the Activity.
Building a ServiceContract
For more complex protocols -- perhaps involving a provider and multiple consumers -- a ServiceContract usually is created. The general approaches for building a locally
owned service protocol and a ServiceContract are similar. We highlight the differences here.
-
To create a new ServiceContract, select the 3 - Service Contracts package, right-click, and select
Add Services Model > ServiceContract. Name the new ServiceContract appropriately.
-
For each interface that is involved in the ServiceContract, create a new Role (Property) under the
ServiceContract and type it with the interface.
-
Select the ServiceContract, right-click, and select Add Diagram > Activity Diagram (or Sequence
Diagram).
Perform behavioral modeling as is described for the locally owned protocol.
Create a structural diagram in general accordance with the above instructions for the locally-owned protocol.
Create an Overview diagram that is similar to what is described for the locally owned protocol. In this case, drag the
Collaboration, rather than the ServiceInterface, onto the diagram and expose its structure compartment.
|