Service integration bus configuration for the Web messaging service

The Web messaging service makes use of the service integration bus provided as part of WebSphere® Application Server V6.0.x and later to provide the underlying publish and subscribe capability required to support Bayeaux clients. To determine how Bayeaux publishers and subscribers interact with the service integration bus, it is necessary to provide some configuration parameters when deploying an application that provides Bayeaux capability.

The Bayeaux subscription channel concept is equivalent to a topic in the service integration bus such that it enables classification of events into related groups, for example /sports/football or /weather. In the service integration bus, topics exist within a topic space destination to which producers and consumers attach. Topics in one topic space are completely independent of topics, even potentially with the same name, that exist in a different topic space. Part of the configuration of the Feature Pack for Web 2.0 end of name->thus gives the application developer the ability to specify which service integration bus topic space is used by Bayeaux applications.

Additionally, events (messages) published to a service integration bus topic space have a reliability applied to them that determines how the messages are treated inside the bus. This includes the conditions under which the messages can be discarded by the messaging infrastructure. In some scenarios, it is acceptable for messages to be discarded if the server becomes resource constrained, possibly due to a high workload, while in others it is preferable to retain messages even at the risk of overloading the server.

When configuring advanced scenarios that include concepts such as workload management or security it is also necessary to consider the implications of those requirements on the service integration bus. Each of these concepts is described in further detail below.

The following option are available for configuring the way that Bayeaux applications interact with the service integration bus.

  busName

    A service integration bus is required for Web messaging operations. Clients can only connect to a single service integration bus through a single incoming URI. Connecting to multiple buses is only possible by creating a separate Web messaging configuration definition and specifying a different bus name, but the client will have to connect through separate URIs and use multiple connections. When using an Ajax client it is only feasible to make one Bayeux connection to a single server on a single Web page. Different pages can specifiy different URIs and connect to different buses.

Name: busName
Required or Optional: Required
Data type: String
Supported values: The name of any service integration bus
Default value: No default
Description:

The service integration bus that incoming Web messaging clients use for publish or subscribe operations.

  destination

    In the majority of scenarios a Bayeaux application needs to consume or produce messages from a single service integration bus topic space. The destination property enables the application developer to specify which topic space is used for all interactions with the service integration bus.

Name: destination
Required or Optional: Optional
Data type: String
Supported values: The name of any service integration bus topic space
Default value: Default.Topic.Space
Description:

This is the topic space on the service integration bus that the application consumes from or produce to.

The destination specified can be a real topic space, or alternatively it can be an alias (see Alias destinations Alias destinations ) to a topic space. Using an alias enables the application to be isolated from the actual name of the topic space.

When using this property to nominate the topic space that is used by Bayeaux applications, the name of the topic inside the topic space is determined by taking the Bayeaux subscription channel name and removing the leading slash for example a channel name of "/sports/football" maps to a service integration bus topic of "sports/football"

If the application developer is not aware of which topic space is used, then this property can be omitted and the default topic space is used.

Note that this property is overridden by the multipleDestinations property as described in a following section.


  multipleDestinations

    In advanced scenarios it might be necessary for a Bayeaux application to produce or consume with more than one service integration bus topic space, for example to display data from a range of disparate sources as part of a portlet environment. In this case, the application developer can enable the multipleDestinations property, which overrides the destination property and enables the developer to specify the name of the required topic space (or alias) destination as part of the Bayeaux subscription channel name.

Name: multipleDestinations
Required or Optional: Optional
Data type: Boolean
Supported values: true or false
Default value: false
Description:

Enables an alternate Bayeaux subscription channel syntax that supports specifying the name of the target service integration bus topic space as part of the channel name.

When enabled, this property causes the first channel segment is used to specify the name of the topic space. For example, to publish to a topic "track/relay4x100"in the topic space "OlympicResults", the application specifies the following Bayeaux subscription channel;

/OlympicResults/track/relay4x100

Note that if multipleDestinations is enabled, then the value of the 'destination' property is ignored.


  reliability

    Events (messages) published to a service integration bus topic space have a 'reliability' applied to them that determines how the messages are treated inside the bus. This includes the conditions under which the messages can be discarded by the messaging infrastructure. In some scenarios, it is acceptable for messages to be discarded if the server becomes resource constrained - possibly due to a high workload, while in others, it is preferable to retain messages even at the risk of overloading the server.

Name: reliability
Required or Optional: Optional
Data type: String
Supported values:
  • BestEffortNonPersistent
  • ExpressNonPersistent
  • ReliableNonPersistent
  • ReliablePersistent
  • AssuredPersistent
Default value: ExpressNonPersistent
Description:

Specifies the level of reliability that events (messages) published by Bayeaux applications are sent to the service integration bus.

Details on the behaviour of these options can be found in the following Message reliability levels section. Message reliability levels section.

Note that for non-durable subscriptions, messages are not available following a server restart because the subscription no longer exists. This means that there is limited benefit in choosing one of the two persistent reliability levels. In most cases, one of the non persistent values should be used.


  clientCanPublish

    The Bayeux protocol supports clients publishing to the service integration bus. Depending on the application that you are developing, you might not only allow messages to flow from the server to Web messaging clients. For example, you might prefer to require clients to publish through a Web application (servlet) and have greater control over inspecting the message contents before publishing the message to the service integration bus. By default, clients cannot publish through the Bayeux protocol.

Name: clientCanPublish
Required or Optional: Optional
Data type: Boolean
Supported values: true or false
Default value: false
Description:

Indicates whether Web messaging clients are permitted to publish. By default, clients cannot publish. You must explicitely set clientCanPublish to true to support client publishing.


  authType

    Incoming Web messaging clients must be authenticated and authorized to connect to the service integration bus when bus security is enabled. Refer to the Securing a Web messaging enabled application for more information.

Name: authType
Required or Optional: Optional
Data type: String
Supported values:
  • none
  • auth_alias
  • basic
  • sso
Default value: none
Description:

When bus security is enabled, incoming Web clients need an identity to authorize to the service integration bus. Specify this configuration parameter to determine where authentication information is obtained to login to the service integration bus.

  • The "none" option indicates no userid and password information is used to login to the service integration bus.
  • The "auth_alias" indicates the userid and password obtained from the authAlias configuration directive is used to login to the service integration bus.
  • The "basic" option can be used when web security is enabled for the application. The "basic" option uses the credentials from the basic authentication header to login to the service integration bus.
  • The "sso" option can be used when Web security is enabled for the application. The "sso" option uses the credentials from LTPA cookies to login to the service integration bus.

If any of the options fail to retrieve credentials, a login to the service integration bus with a blank userid and password is performed. If service integration bus security is enabled, Web clients are not able to connect for Web messaging operations.


useDurable

   A durable subscription to the service integration bus will be used for Bayeux subscribe requests when the useDurable configuration property is set to true. A durable subscription can be used to preserve messages published on a topic while a subscriber is inactive.

Name: useDurable
Required or Optional: Optional
Data Type: Boolean
Supported Values: true or false
Default Value: false
Description:

When durable subscriptions are used for Web messaging, Web clients will be able resume operations after a brief period of time without missing messages when aWeb client's subscriptions to the service integration bus become inactive. A subscription can become inactive for some of the following reasons: server failure, messaging engine failure, or connection failure to a messaging engine.

When running a Web messaging enabled application in a clustered environment, you should consider setting the useDurable and useDistributedSession configuration properties to true for optimal fail over results. When both of these properties are set to true, a Web messaging client will be able to fail over from one server to another and resume any durable subscriptions.

When durable subscriptions are used for Web messaging, each Web messaging client stays tied to the messaging engine in which it first connects. When a Web messaging client unsubscribes from a topic, whether it is a result of a specific Bayeux unsubscribe operation, a Bayeux disconnect operation, of Bayeux session expiration, the messaging engine must be running for the unsubscribe operation to complete. The Web messaging service tracks durable subscription information and expires it when possible, but there are times when this is not possible. In these situations, durable subscriptions must be deleted manually through administration procedures.

Many times there is a short delay before a Web Messaging client's durable subscriptions can be resumed. The Bayeux reconnect retry advice mechanism is used to direct Web messaging clients to reconnect after a short period of time to restore these durable subscriptions. The reconnection interval is controlled by the reinitInterval configuration property. The maximum amount of time to attempt to reconnect is controlled by the MaxReinitDuration configuration property.

Tthere is additional overhead when using durable subscriptions and planning should be considered before setting this property. Please refer to service integration bus documentation for more information.

autoReinit

     Web messaging clients will reconnect to the service integration bus and resubscribe to any topics when a problem communicating with a service integration bus is encountered if the autoReinit configuration property is set to true.

Name: autoReinit
Required or Optional: Optional
Data Type: Boolean
Supported Values: true or false
Default Value: false
Description:

When a Web messaging client encounters an error communicating with a service integration bus, the autoReinit property should be set to automatically reinitialize a connection to the service integration bus and resubscribe to any previously subscribed topics. During the interval between subscription loss and reinitialization, any messages published to a topic will be not reach the Web messaging client.

If both the useDurable and autoReinit properties are set to true, the useDurable property will take effect.

When running a Web messaging enabled application in a cluster, you can consider setting the autoReinit and useDistributedSession configuration properties to true. When both of these properties are set to true, a Web messaging client will be able to resume operations when a server fails and Web messaging operations are resumed on another server. If the autoReinit and useDurable propreties are both set to false, the Bayeux re-handshake advice is sent to the client indicating the client should re-handshake and initialize a new Bayeux session.

Many times there is a short delay before a Web Messaging client's connections and subscriptions can be re-initialized. The Bayeux reconnect retry advice mechanism is used to direct Web messaging clients to reconnect after a short period of time to reinitialize the client's subscriptions. This reconnect interval is controlled by the reinitInterval configuration property. The maximum amount of time to attempt to reconnect is controlled by the MaxReinitDuration configuration property.

reinitInterval

   When either the autoReinit or useDurable configuration properties are true and there is an error communicating with the service integration bus, the Web messaging client is directed to reconnect periodically to resume operations as specified by the reinitInterval configuration property.

Name: reinitInterval
Required or Optional: Optional
Data Type: Integer
Supported Values: Value specified in seconds between 1 and 300.
Default Value: 10
Description:

After a Web messaging client encounters an error communicating with a service integration bus, there may be a brief period of time before a Web messaging client can resume communications with a service integration bus. When this happens, the Bayeux reconnect retry with an interval advice is sent to the client to direct the client to reconnect according to the interval specified by the reinitInterval configuraiton property. . The Web messaging client will try to reconnect up to maximum time as specified by the maxReinitDuration configuration property.

maxReinitDuration

    The maxReinitDuration configuration property specifies the maximum amount of time a Web messaging client will attempt to resume operations with a service integration bus.

Name: maxReinitDuration
Required or Optional: Optional
Data Type: Integer
Supported Values: Value specified in seconds between 10-600
Default Value: 60
Description:

When the autoReinit or useDurable configuration properties are set to true, a Web messaging client will attempt to resume operations with the service integration bus. In some situations, it might not be possible to resume operations in a timely manner. After the maxReinitDuration time elapses, the Web messaging client will no longer try to resume operations with the service integration bus and the Bayeux session will be expired.