Qualifiers
Qualifiers are an important part of SCA because they allow developers to place quality of service requirements on the IBM® Business Process Manager runtime.
There are several different categories of qualifiers available in SCA. These categories of qualifiers are transaction, activity session, security, and asynchronous reliability.
Each SCA qualifier has a particular scope within the SCDL definition
for a component where the qualifier can be specified. For example,
some qualifiers can be specified at the references level, while others
may only be valid at the interfaces or implementation level. The table
lists the various qualifiers that are available and the valid scope
for each. The qualifiers are sorted by the type of quality of service
they provide, such as transaction or security.
Tip: See Setting qualifiers and transactions for more detail.
| Type | Qualifier | Scope | Description |
|---|---|---|---|
| Transaction | transaction | Implementation | global - A global transaction must be
present to run the component local - A global transaction must not exist to run the component any - Component is unaffected by transactional state local application - Component processing occurs within a WebSphere® local transaction containment that is managed by the application |
| joinTransaction | Interface | true - Hosting container joins client
transaction false (default) - Hosting container does not join client transaction |
|
| suspendTransaction | Reference | true - Synchronous invocations of target
component do not run within client global transaction. false - Synchronous invocations of target component run within client global transaction |
|
| deliverAsyncAt | Reference | call - Asynchronous invocations of a
target service occur immediately commit - Asynchronous invocations of a target service occur as part of a global transaction |
|
| Asynchronous Response | reliability | Reference | Specifies the quality of service level for asynchronous message delivery. Reliability can be one of the following values: bestEffort or assured |
| requestExpiration | Reference | Specifies the length of time (milliseconds) after which an asynchronous request is to be discarded if not delivered | |
| responseExpiration | Reference | Specifies the duration (milliseconds) between the time a request is sent and the time a response or callback is received | |
| Security | securityIdentity | Implementation | The permission specifies a logical name for the identity under which the implementation executes at run time. |
| securityPermission | Interfaces, Interface, Method | The caller identity must have the role specified from this qualifier in order to have permission to run the interface or method | |
| Activity Session | activitySession | Implementation | true - There must be an ActivitySession
established in order to run this component false - The component runs under no Activity Session any - The component does not depend on the presence or absence of an ActivitySession |
| joinActivitySession | Interface | true - Hosting container joins client
ActivitySession false - Hosting container does not join client ActivitySession |
|
| suspendActivitySession | Reference | true - Methods on target component does
NOT run as part of any client ActivitySession false - Methods on target component run as part of any client ActivitySession |
Transaction qualifiers
Transaction qualifiers
allow developers to request a particular transactional environment
for the service components in an SCA module. The following is a summary
of these qualifiers:
- transaction
- The transaction qualifier is set at the implementation scope of n service component. This qualifier can be set to either 'global', 'local' (default), or 'any'. When set to global, the component runs in the context of a global transaction. If a global transaction is present on invocation, the component is added to this global transaction scope. If set to local, the component runs in the context of a local transaction. Finally, if the value is set to any then if a global transaction is present the component joins the current global transaction scope. However, if a global transaction is not present, the component runs in the context of a local transaction.
- joinTransaction
- The joinTransaction qualifier is set at the interface scope of a service component. This qualifier can be set to either true or false (false being the default). If set to true, it instructs the runtime not to suspend a global transaction (if present) at the interface boundary. If set to false, it instructs the runtime to suspend a global transaction (if present) at the interface boundary. Exposing the joinTransaction transactional qualifier on an interface provides metadata that can be used by assemblers and deployers to ensure that the assembled application behaves as required. It is up to the assembler and deployer in addition to dynamic runtimes to reason about whether a target component federates with a propagated transaction.
- suspendTransaction
- The suspendTransaction qualifier is set at the reference level of a service component and identifies whether a global transaction should be suspended before invoking the target service associated with the reference. This qualifier can be set to either true or false (default).
- deliveryAsyncAt
- The deliveryAsyncAt qualifier is like the suspendTransaction qualifier, except that it pertains to asynchronous interactions rather than synchronous types as is the case with suspendTransaction. The deliverAsyncAt qualifier can have the value of call (default) or commit. If set to call, it indicates to the runtime that the message for the asynchronous interaction should be committed to the queue immediately when the call has been made. The value of commit indicates that the message should be committed to the queue as part of a transaction associated with the current unit of work.
Asynchronous response qualifiers
There are
three qualifiers available for indicating quality of service for asynchronous
response. Each of the asynchronous response qualifiers are specified
at the reference scope. The following is a summary of asynchronous
response qualifiers:
- reliability
- The reliability qualifier is used to specify the quality of service level for asynchronous message delivery. The reliability can be set to either bestEffort or assured (default).
- requestExpiration
- The requestExpiration qualifier is used to specify the length of time the runtime should hold onto an asynchronous request if it has not yet been delivered. After the time indicated for this qualifier, given in milliseconds, this request is discarded.
- responseExpiration
- The responseExpiration qualifier is used to specify the length of time that the runtime must retain an asynchronous response or must provide a callback. The value for this qualifier is given in milliseconds.
Security qualifiers
There are two qualifiers
available for indicating quality of service related to security. The
following is a summary of these qualifiers:
- securityIdentity
- The securityIdentity qualifier is used to specify the security identity under which the implementation for the service component should run at run time. This qualifier must be placed at the implementation scope for the service component and the value given must match the logical name for the identity under which the component will run.
- securityPermission
- The securityPermission qualifier is specified at the interfaces level, including interface, or method level. The value for this qualifier indicates that a caller of this service must have the role that is specified in order to invoke the service.
For both the securityPermission and the securityIndentity, the underlying implementation for these qualifiers is based on existing Java™ EE concepts.
Activity session qualifiers
The set of activity
session qualifiers are similar to the transaction qualifiers introduced
earlier. The ActivitySession service is a WebSphere programming model extension that
can provide an alternative unit of work when compared with global
transactions. In fact, an activity session context can be longer lived
than a global transaction and can even include global transactions.
The following is a summary of the activity session qualifiers:
- joinActivitySession
- The joinActivitySession qualifier is set at the interface level, and indicates whether or not the component should join the activity session of a client caller. There are two values for this qualifier, true and false (default). If set to true it indicates that the runtime should not suspend an activity session if present when the component is invoked. If set to false it indicates that an activity session should be suspended before invoking the component.
- activitySession
- The activitySession qualifier is specified at the implementation level and is used to indicate whether or not an activity session should or should not exist in order to run the service component with which it is associated. This qualifier can be set to either 'true', 'false', or 'any' (default). If set to true, it indicates that the component will run as part of an activity session. If set to false, the component should not run as part of an activity session. This means that the joinActivitySession should also be set to false for any interfaces specified for the component. Finally, if this qualifier is set to any, the component will run as part of an activity session if it is present, otherwise it will not.
- suspendActivitySession
- The suspendActivitySession qualifier is set at the reference level and is used to indicate whether or not a target service associated with a reference will get called as part of the calling activity session or not. If set to true, the activity session is suspended and the methods on the target component will not run as part of the client activity session. If set to false (default) the activity session is not suspended and methods on the target component will run as part of the client ActivitySession.