Quality of service: Qualifiers for mediation services

Quality of service (QoS) qualifiers can be specified when wiring components in the assembly editor. These qualifiers define how much management must be provided for a component at run time.

Service Components Architecture (SCA) allows QoS qualifiers, such as transactions, security, and reliable asynchronous invocation, to be applied to components without requiring programming or a change to the services implementation code. WebSphere Integration Developer gives you the tools to quickly and easily compose an integrated business application that wires together components in mediation modules that can be deployed to the WebSphere Enterprise Service Bus or to WebSphere Process Server. When wiring the components, you can specify qualifiers to provide extended quality of service to the components, as well as to the clients accessing the service. Sometimes, implementations require that qualifiers are set in particular ways; see the explanation of the join transaction qualifier later in this topic for one example.

Usually, you apply QoS qualifiers when you are ready to consider solution deployment. This topic provides a general overview of the possible QoS specifications of the wired components in the mediation module assembly. To help you specify these qualifiers, refer to the WebSphere Process Server QoS information:

Qualities of service qualifiers

Qualifiers are QoS specifications that define a set of communication characteristics required by an application for transmission priority, level of route reliability, transaction management, and security level. This topic discusses the qualifiers that are specified in these components:

At run time, these specifications determine how the clients interact with the target components. Depending on the qualifiers specified, the runtime environment supplies any required additional processing.

Qualifiers for implementation

Qualifiers for implementation identify the service's authority and express its requirements for a transactional environment. These are the qualifiers:

  • Activity session
  • Transaction
  • Security identity

Activity session

This qualifier determines if the component's processing will be executed under an activity session, which provides an alternate unit-of-work scope to the one provided by global transaction contexts. An activity session context can be longer lived than a global transaction context and can encapsulate global transactions. The activity session Value qualifier can have these settings:

  • True - There must be an established activity session in order to run this component. The run time may use the provided activity session for the execution of this implementation, or if none is provided, will create a new activity session.

  • False - The component does not run under an activity session (even if one is propagated to the hosting runtime environment); that is, it runs under a method-scoped local transaction containment (LTC) or a global transaction.

  • Any (default) - If an activity session has been propagated from the client, the runtime environment will dispatch methods from the component in the activity session; otherwise, the component will not run under any activity session.

Transaction

This qualifier determines the logical unit of work that the component's processing executes. For a logical unit of work, all of the data modifications made during a transaction are either committed together as a unit or rolled back as a unit. The transaction Value qualifier can have these settings:

Security identity

The security identity qualifier is a privilege specification that you can use to provide a logical name for the identity under which the implementation executes at run time. An implementation has to be created in order for this qualifier to be specified. If this qualifier is not specified, then the implementation executes under the identity of its caller, or under the hosting container’s identity if no caller identity is present. Roles are associated with the identity and the roles dictate if the implementation is authorized to invoke other components.

Qualifiers for interfaces

Interface qualifiers are used to advertise the qualifiers supported by a target service, and therefore represent a contract with a client of the service. These are the qualifiers:

  • Event sequencing
  • Join activity session
  • Join transaction
  • Security permission
You can only apply event sequencing for interface operations. Other interface qualifiers can be applied at three levels of a component or import:
  • For all of its interfaces
  • For an individual interface
  • For an individual operation of an interface

A deployment error occurs when the component's interface qualifier conflicts with its export interface's qualifier.

The qualifier of the operation overrides the qualifier of the interface; the qualifier of the interface overrides the qualifiers of all the interfaces for a component or import. Inherited qualifiers listed in the Properties view are grey and the assigned ones are in black. Also, inherited qualifiers cannot be changed unless you select the element on which they are defined.

The following shows two qualifiers for the CustomerInfoInterface interface; the Security permission qualifier is inherited from the Interfaces and the Join Transaction qualifier is specified for this interface:

Properties view showing quality of service qualifiers

Event sequencing

Event sequencing is done based on an event sequencing key definition that you specify for the qualifier. The event sequencing qualifier specifies the key value that you have defined for an operation. It tells the runtime environment to process the events defined for that key in a specific order.

Event sequencing is supported only for components that are invoked using the SCA asynchronous invocation style. Invocations have parameters, which are business objects or simple types. The key is a combination of one or more business object attributes. You can set the event sequencing qualifier after you develop the mediation logic; it is independent of the implementation. See the related tasks at the end of this topic for a link to information about using event sequencing.

Join activity session

The Join activity session qualifier can have these settings:

  • True - The hosting container will join any propagated (client) activity session.
    Note: Asynchronous component implementations should not expose Join activity session = True on any of its asynchronous interfaces.
  • False (default) - The hosting container will not join any propagated (client) activity session.

Join transaction

The Join transaction qualifier can have these settings:

  • True - The hosting container will join any propagated (client) transaction.
    Note: Asynchronous component implementations should not expose Join Transaction = True on any of its asynchronous interfaces in order to prevent deadlocks.
  • False (default) - The hosting container will not join any propagated (client) transaction.

The combination of the interface and implementation qualifiers defines the following behavior for the target component:

Table 1. Behavior of target component
Interface - Join Transaction qualifier Implementation - Transaction Value qualifier Result behavior of the target component
True Global The component runs in propagated transaction, if one is present; otherwise, a new global transaction is created.
True Local Error - These qualifier settings are incompatible.
True Any The component runs in a propagated transaction, if one is present; otherwise, it runs in a local transaction.
False Global The component runs in a new global transaction.
False Local The component runs in a local transaction.
False Any The component runs in a local transaction.

Security permission qualifier for interfaces

Use the security permission qualifier to specify a role, which is a semantic grouping of permissions that a given type of users must have to use an operation in an interface. The identity of the caller must have this role in order to be permitted to call the interface or operation. If no security permission is specified, then no permissions are checked and all callers are permitted to call the interface or operation.

Qualifiers for references

References qualifiers specify the reliability for asynchronous invocations and if a target component’s methods should be federated as part of any client transaction.

These are the reference qualifiers:

  • Asynchronous reliability
  • Suspend transaction
  • Asynchronous invocation
  • Suspend activity session

You can specify references qualifiers that would apply to all the references of a service component or the stand-alone references. If required, you can also specify these qualifiers for each individual reference, in which case they would override the overall qualifiers. Inherited qualifiers listed in the Properties view are grey and the assigned ones are in black. Also, inherited qualifiers cannot be changed unless you select the element on which they are defined.

The following Properties view shows two qualifiers for the CustomerInfoInterfacePartner reference; the Reliability qualifier is inherited from the References and the Suspend Transaction qualifier is specified for this reference:

Asynchronous reliability

To support asynchronous invocation of components, asynchronous reliability qualifiers can be specified for the reference. They only take effect when asynchronous programming calls are used by the client to invoke the service. These are the reliability qualifier specifications:
  • Reliability

    The reliability qualifier determines the quality of an asynchronous message delivery. In general, better performance usually means less reliable message delivery. With an Assured specification, the client application cannot tolerate the loss of a request or response message. With a Best effort specification, the client application can tolerate the possible loss of the request or response message.

  • Request expiration (milliseconds)

    Request expiration is the length of time after which an asynchronous request will be discarded if it has not been delivered, beginning from the time when the request is issued. A zero (0) denotes an indefinite expiration.

  • Response expiration (milliseconds)

    Response expiration is the length of time that the runtime environment must retain an asynchronous response or must provide a callback, beginning from the time when the request is issued. A zero (0) denotes an indefinite expiration.

Suspend transaction

The suspend transaction qualifier is ignored if the invocation occurs using any of the asynchronous interaction styles, or if the invocation occurs as a part of a local transaction. The qualifier does not affect the transactional environment of the target component. That is, the target component’s hosting container is still entirely responsible for providing the transactional environment required by the implementation.

Client global transaction context is always propagated to a target component when it is invoked using the synchronous programming model. (This qualifier only affects client global transactions because local transactions are never propagated to target components.) In order to address use cases where the client does not want a target component to federate with the client’s transaction, further qualification of the reference is required using the Suspend transaction qualifier, which can have these settings:

  • False (default) - Synchronous invocations run completely within any client global transaction.
  • True - Synchronous invocations occur outside any client global transaction. The target service's transactional environment is not affected by this qualifier.

Note, however, that with Suspend transaction for the reference, the target component’s effective transaction environment is either a new global transaction or a local transaction.

Suspend activity session

By default, activity session context is always propagated to a target component when it is invoked using the synchronous programming model. If the client does not want a target component to federate with the client’s activity session, further qualification of the reference is required using the Suspend activity session qualifier, which can have these settings:

  • False (default) - The target component's methods that are invoked using this reference will run as a part of any client activity session, but only if the target component also joins any client activity session.
  • True - The target component's methods that are invoked using this reference will not run as part of any client activity session.
  • This reference qualifier is ignored if the invocation occurs using any of the asynchronous interaction styles. The client activity session is not propagated if the client uses any asynchronous interaction styles. This reference qualifier is also ignored if the invocation occurs outside the scope of an activity session.
  • This qualifier does not affect the activity session environment of the target component. That is, the target component’s hosting container is still entirely responsible for providing the activity session environment that is required by the implementation.

Asynchronous invocation determines if asynchronous invocations should occur as part of any client transaction:

  • Commit - Asynchronous invocations using the reference will be transacted as a part of any client global transaction or extended local transaction (that is, where the transaction Value qualifier for the client implementation is local.
  • Call (default) - Asynchronous invocations using the reference will occur immediately. This is logically equivalent to suspending the current transaction and then invoking the target service.
Related concepts
Components and mediation modules
Approaches to assembling a mediation module
Using Java in a mediation module
Using Java in a mediation module
Related tasks
Creating a mediation module
Opening a mediation module assembly
Setting assembly editor preferences
Adding and wiring components
Editing the properties of elements in the mediation module assembly
Adding Qualities of Service (QoS) qualifiers
Processing events in a sequence
Working with implementations
Generating bindings for imports and exports
Invoking a module from another module
Interoperability with services from other vendors
Fixing errors in the assembly diagram
Best practice: Do not make changes to J2EE staging projects
Business services: Opening a module assembly
Related reference
Assembly editor for mediation modules

Related information

Tutorial: Wire components using the assembly editor
Tutorial: Create a mediation flow
Samples: Mediation Flow editor
Tutorial: Wire components using the assembly editor

Feedback
(C) Copyright IBM Corporation 2005, 2006. All Rights Reserved.