Swordfish Documentation: Architecture: Parameter Propagation

Overview

In a SOA environment service consumers and service providers need the ability to communicate technical parameters additional to the message payload. Swordfish supports this requirement by providing an API which allow service participants (consumer/provider) to set and read technical properties either directly or via a callback mechanism. These properties can be context or message specific and are propagated together with the message payload.

CXF, which is currently used by Swordfish to support the implementation of service participants via JAX-WS provides such capabilities only for specific technical properties, for security related properties see

• [1] and
• [2].

Swordfish aims at generalizing the propagation of technical parameters. Other application areas are for instance policy-, correlation- and participant-ids and parameters for policy driven message interceptors. Requirements for the Swordfish participant-parameter-API are:

• Dependencies to specific JAX-WS implementations (like CXF) should be hidden from the Swordish user.
• Extendability: Later addition of other parameters should be easy.
• Parameters related to security, policy handling, correlation, participant identification and configuration of interceptors should be supported out of the box.
• Standards (like WS-Security) should be supported to enable the communication with non-Swordfish participants. This means that standard parameters should be transferred as part of the SOAP message header as specified by the standard.

Description

The following picture illustrates the message flow between a Swordfish service consumer and a Swordfish service provider.

If the communication partner is not realized using Swordfish, its internal structure is irrelevant for the following discussion.

A Swordfish service participant (consumer/provider) uses JAX-WS to call / privide web services. Swordfish currently uses CXF to implement JAX-WS and provides hooks for message handling via interceptors which run inside the Servicemix 4 NMR. Implementing additional Swordfish NMR-interceptors is the standard way how functionality is realized in Swordfish. This principle will also guide the design of the parameter transport mechanism.

Technical Parameter Propagation API

The Technical Parameter Propagation API will be used by the Swordfish service consumer/provider to set and retrieve parameters to be transferred together with the message content. Beside generic parameters the API supports standard parameters (security credentials, policy id, participant id, correlation id) and uses standardized parameter names if possible (WS-Security). The API allows the definition of a callback to retrieve security credentials.

Technical Parameter Propagation OSGI Service

The Technical Parameter Propagation API will be realized as a Swordfish OSGI service for storing and retrieving arbitrary parameters to be transferred. This service is called by the consumer/provider which set and read the parameters they need. Parameters may also be specified as part of the Spring configuration of the parameter service or provided via a property file in an related fragment bundle. Additional framework specific parameters (correlation-id,...) will be set automatically by the framework.

Technical Parameter Propagation NMR-Interceptor

On both sides of the communication (consumer+provider) a Swordfish Servicemix 4 NMR-Interceptor is responsible for transferring the properties to be transferred between the Technical Parameter Propagation OSGI Service and the properties of the normalized message. The only difficulty here is to identify the correct service instance if multiple consumers are installed at the same machine. We have two options:

• Explicit reference of the service instance as Spring bean reference in the Spring configuration. Both the NMR-Interceptor and the OSGI-Service are Spring beans and therefore a reference can explicitely be defined.
• Implicit reference by using a static InheritableThreadLocal variable (see [3]) holding a reference to the service. This option requires an additional CXF-interceptor which stores a service id as message property. The NMR-interceptor reads this property from the message and uses it to identify the correct OSGI-service. Therefore the Technical Parameter Propagation OSGI services need to be registered at the OSGI service registry using the service id as service property. This option is CXF-dependend and relies on the fact that the CXF-interceptor runs in the same thread as the consumer/provider code, but avoids the need to define an explicit reference in the Spring configuration.

Either one of these options or both (with the second option as fallback, if no explicit reference is given) could be chosen, we should vote here.

Consumer side

The parameters will be set by the Swordfish parameter interceptor running inside the NMR. This interceptor will store the properties in the message via NormalizedMessage.setProperty() (JBI) or Message.setHeaders() (SMIX4-NMR-API). Since the policy-id parameter is needed for endpoint resolution the parameter interceptor will be the first in the Swordfish interceptor chain. The NMR-interceptor will identify the correct Technical Parameter Propagation OSGI Service using one of the options above and use it to retrieve the parameters which were set by the consumer.

Provider side

The parameters will be read by the Swordfish parameter interceptor running inside the NMR. This interceptor will read the properties from the transferred message via NormalizedMessage.readProperty() (JBI) or Message.getHeaders() (SMIX4-NMR-API). The NMR-interceptor will identify the correct Technical Parameter Propagation OSGI Service using one of the options above and use it to store the parameters to be read by the provider.

API

TBD

Processing sequence

The parameter propagation process from the service consumer side is described by the following scenario:

The parameter propagation process from the service provider side is described by the following scenario:

See also

Eclipse Swordfish – an Open Source SOA Runtime Framework for the Enterprise

Swordfish JavaDoc