Chapter 14. Mediation Patterns
The next set of design patterns we will consider addresses mediation: the insertion of some simple intervening logic between a service consumer and a service provider. As the name implies, mediation activities modify, but do not fundamentally alter, the interactions between the two primary parties. Typical mediation activities include mapping one interface to another, transforming message content, routing requests, and enhancing message content.
Figure 14-1 shows the basic ActiveMatrix mediation architecture pattern that we will discuss. In this pattern the mediator is an ActiveMatrix composite, and it does not matter whether the service consumer and service provider reside within ActiveMatrix or outside the environment. There are variants of this pattern in which the service consumer and/or service provider are also resident within the composite, but these variants become obvious once the basic pattern is understood.
Figure 14-1. Mediation Architecture Pattern
Straight-Wire Mapping
The simplest form of mediation is the straight-wire mapping of a service to a reference (Figure 14-2). There are no activities involved in this mediation, only the connection between the service and the reference. A prerequisite for this type of mediation is that the port types (interfaces) of both the service and reference must be identical.
Figure 14-2. Straight-Wire Architecture Pattern
Given the simplicity of this mapping, it might occur to you to ask why you cannot simply wire the composite’s service directly to its reference. The answer is that the SCA Assembly Model does not permit such wiring within a composite. A promoted service can only be wired to a service on a component within the composite. Similarly, a promoted reference can only be wired to a reference on a component within the composite. Thus, a component is required in order to implement this mapping.
Any of the ActiveMatrix implementation types could potentially be used for this purpose, but one in particular is designed for this task: the Mediation implementation type. Mediation is a lightweight (small footprint, low overhead) implementation type that is easily configured to perform the most common mediation activities—including straight-through wiring. Figure 14-3 shows a mediation implementation type playing this role in a composite.
Figure 14-3. Mediation Implementation Type in a Composite
Mediation Flow Design
Looking into the design of the mediation implementation type (Figure 14-4) you will see that there are different views for the input, output, and fault flows. The input and output flows are exactly what you would expect: straight wires. The mediation input maps directly to the target input and the target output maps directly to the mediation output.
Figure 14-4. Mediation Design Interface
The fault flow, on the other hand, surfaces one of the complexities of mediation: Faults can arise for a number of reasons. The call to the target interface could timeout. The target interface might throw an undeclared fault or throw the fault its interface explicitly declares. A task in the mediation flow itself (like one of the mappings in one of the other fault paths!) might throw a fault, or the mediation component as a whole might throw a run-time fault. For now, don’t worry about the icons on the paths here; these will be explained in due course.
The mediation implementation type has built-in features for handling all of these variations. If you were to use another implementation type for this or any other mediation purpose you would, at a minimum, have to replicate all of this functionality. This would require considerable design effort. This is the reason for having the mediation implementation type.
Use Case: Access Control
You might be asking yourself why you would ever want to wire a service to a reference in this manner rather than have the service consumer directly access the service provider. The answer is that both the services and references are policy enforcement points. Using this pattern makes it possible to insert access control policies into the dialog between service consumer and service provider. Furthermore, it allows you to hide the actual service provider interface from the service consumer.
Use Case: Transport Mapping
Another situation in which this pattern is useful arises when the service consumer and service provider want to use different transports for the exchange. Both parties use the same SOAP port type (interface) definition, but one may want to use a different transport than the other. Remember that ActiveMatrix provides three SOAP transports: HTTP, JMS, and Virtualization. Using the straight-wire pattern, the promoted service and promoted reference can each be configured to provide a different transport. This is a common situation when in-house service access is being provided via JMS or Virtualization transports but externally exposed services are being provided via HTTP.
A variation on this occurs when you would like to provide the same service via two different transports (Figure 14-5). Here you have two different promoted services, each with a different transport, wired to the same mediation service. The mediation design is exactly the same—only the additional promoted service binding has been added.
Figure 14-5. Accessing the Same Service via Two Different Transports
Content Transformation
The straight-wire pattern required that both parties have identical logical interfaces, but it is to be expected that parties not having identical interfaces will still want to interact. The data transformation architecture pattern (Figure 14-6) provides a solution to this problem. A component within the data transformation composite is providing the data transformation.
Figure 14-6. Data Transformation Architecture Pattern
Once again, any of the implementation types could be used to implement this component, but it is particularly easy and efficient to use the Mediation implementation type for this purpose. Figure 14-7 shows a mediation flow in which a data transformation activity has been dropped (literally) on the wire between the two service operations. The lower half of the window shows the drag-and-drop configuration of the mapping between the two interfaces. Mappings in the output direction and for faults are configured in a similar manner.
Figure 14-7. Configuring the Data Transformation in a Mediation Flow
Although the Mediation implementation type is flexible, it is not always suitable for every application. When additional logic is required, such as updates to other systems, the invocation of packaged libraries, or the execution of complex algorithms, other implementation types will likely be more suitable. TIBCO ActiveMatrix Business-Works, for example, provides the design convenience of the Mediation implementation type coupled with a broad range of communication and functional capabilities. Its power and flexibility warrant first consideration if the requirements exceed the Mediation capabilities.
Data Augmentation
Sometimes you will find that you need information to call the referenced service that is not present in the inbound request. Very often you will need to look up that extra information in an external system and then combine it with the incoming information to create the target service’s request. The resulting architecture pattern is shown in Figure 14-8.
Figure 14-8. Data Augmentation Architecture Pattern
For similar reasons, additional work may be required when handling the response and exceptions as well. The full process is shown in Figure 14-9.
Figure 14-9. Data Augmentation Process
Building this composite in ActiveMatrix will yield a design similar to that of Figure 14-10.
Figure 14-10. The Data Augmentation Composite
Although any of the implementation types could potentially be used for the mediating component, Mediation again simplifies implementation, since it provides separate configurations for the input, output, and exception flows. Figure 14-11 shows an example implementation for the input flow.
Figure 14-11. Augmentation Input Flow Implementation
The mediation flow design interface provides several activities that can be used to obtain augmenting information. These include:
• A call to a SOAP service operation
• A JDBC query to a database
• A custom Java task
Routing
In complex environments there may be more than one implementation of a service, or two different services providing essentially the same functionality. In such cases, a request from a service consumer must be routed to the appropriate service provider. The architecture pattern for this is shown in Figure 14-12.
Figure 14-12. Routing Architecture Pattern
When you implement this composite in ActiveMatrix the result will be similar to the composite shown in Figure 14-13.
Figure 14-13. Routing Composite
Once again, any of the ActiveMatrix implementation types can be used for the router component, but Mediation is specifically designed for such cases. An example input flow is shown in Figure 14-14. Here, transactions are being routed based on whether they are domestic or foreign. United States transactions are routed to the second service, while all others are routed to the third service. Note that transformations are generally required when routing.
Figure 14-14. Routing Input Flow Implementation
There are three routing options available in the mediation flow. The basic Route activity allows you to define simple conditions on one or more variables. The XPath Route enables you to use XPath expressions and more complex logic to determine the choices.
The third option, dynamic routing, is only available when using the ActiveMatrix Virtualization transport (Figure 14-15). It allows you to compute the name of the service that is going to be invoked. Let’s assume that you have a service for each foreign country, with the service named Transaction.Country. You also want the ability to dynamically add new countries without having to redesign the mediation flow each time. In this case you would modify the target interface for the “Otherwise” case to be a dynamic service reference. In the “Otherwise” path you would add a Set Dynamic Reference activity to compute the name of the target service. Of course, you would also want to add an appropriate fault handler for the case in which the target service does not exist.
Mediation Capabilities and Limitations
As this chapter has illustrated, the Mediation implementation type has a broad set of capabilities commonly required when implementing mediation patterns. Its capabilities include:
• Accessing external systems: SOAP operation calls and JDBC database queries
• Making log entries
• Manipulating data: XML parsing, rendering, and validation
• Routing: based on Xpath or other criteria, or dynamically setting reference destinations
• Synthesizing replies
• Managing context between requests and replies
• Throwing faults
The Mediation implementation type does have some limitations. Chief among these is that it can only support the In-Only and In-Out interaction patterns. The use of Out-Only or Out-In patterns thus requires another implementation type to be used.
Summary
Mediation is required when there is logic that must be inserted between a service consumer and a service provider. Mediation logic typically does not produce side-effect changes in other systems as part of the interaction.
The simplest ActiveMatrix mediation pattern is a straight-wire connection between a service consumer and a service provider. This affords the opportunity to change transports and apply access control policies to the interactions. Straight-wire mediation requires that both the consumer and provider have identical logical interfaces. The Mediation implementation type provides the simplest possible implementation of this pattern.
Content transformation is another common mediation requirement. This requirement arises when the interface being used by the service consumer differs from that of the service provider. In such cases both the input and output data structures typically need to be mapped, as well as the exceptions that may be raised. The Mediation data transformation activities provide a simple approach to satisfying such requirements.
Data augmentation is another common requirement. Sometimes data (e.g., an identifier) from the service consumer needs to be cross-referenced to obtain the appropriate data for the service provider. In other cases, additional information needs to be looked up in an external system and added to the service provider input. The Mediation SOAP operation call and JDBC query activities provide convenient means for satisfying these requirements.
Requirements for routing arise when two or more service providers can satisfy a request. In the simplest scenarios, there is information in the input sufficient to determine which service provider should receive the request. In more complex scenarios a lookup in an external system may be necessary to determine the appropriate recipient. The Mediation Route, Xpath Route, and Set Dynamic Reference activities provide flexible mechanisms to implement routing.
The Mediation implementation type provides a broad range of functionality commonly required for mediation. It provides an easy-to-configure interface and efficient execution. However, it can only participate in In-Only and In-Out interaction patterns. Out-Only and Out-In patterns require the use of other implementation types for the mediation role.