Tool Mentor: Specify Service Interfaces
Specify the simple interfaces, operations, parameters, return types, and interaction protocols associated with each service interface.
Tool: Rational Software Architect
Relationships
Main Description

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.

Review the model structure

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.    
 

Identify and create provided and required interfaces

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"

  1. Select the ServiceInterface in Project Explorer. Right-click and select Modeling References > Enclosing Model.
  2. 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.
  3. 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

  1. For each collaborating ServiceInterface, begin by creating a single provided (realized) UML Interface and a single required (used) UML Interface.  
  2. Create appropriate relationships (realization and uses) between the ServiceInterface and its interfaces.
  3. 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

  1. 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.
  2. Create the appropriate operations on the provided and/or required interfaces for each ServiceInterface.

D. Refactor the interfaces and ServiceInterfaces if necessary

  1. After all the operations have been allocated to the provided and required interfaces, check to ensure that the assigned operations are cohesive.  
  2. 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.
  3. Create additional ServiceInterfaces, enough to support the total number of provided interfaces. Have each ServiceInterface realize one of the refactored interfaces.  
  4. Revisit the service collaborations to determine which of the callBack operations supports each of the new ServiceInterfaces.  
  5. Assign those operations to interfaces that are used by the appropriate ServiceInterface.
  6. 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.  
  7. Create a <<usage>> dependency from the original ServiceInterface to each of the new required interfaces.

Describe the services data model

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.

  1. 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.
  2. 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.
  3. Build messages from PrimitiveTypes, domainTypes, ParamTypes, and other messages. Model messages by using SoaML MessageTypes.
  4. 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 service operation signatures

Complete the service operation signatures by adding appropriate in, out, inout, and return parameters. These can be typed using PrimitiveTypes, ParamTypes, or MessageTypes.  

  1. Select the operation either in Project Explorer or on a diagram.
  2. Select the Properties view, then the Parameters tab.
  3. 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.

Specify service protocols

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:

  1. Create a new structure diagram under the ServiceInterface.
  2. 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.
  3. Create the ownedBehavior -- either an Activity or an Interaction -- under the ServiceInterface. If you are using an Interaction, create a Sequence diagram under that.
  4. For Activity modeling, create partitions and type each one with a property.
  5. For Sequence diagram modeling, drag the properties onto the diagram to create the Lifelines.
  6. 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.

  1. 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.
  2. Select the ServiceInterface, then select Filters > Show/Hide Compartment > Structure Compartment.
  3. 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.

More Information