10.9. Implementing a Transport-Specific Configuration

The JBoss Enterprise SOA Platform configuration model has transport-specific variants for <provider>, <bus> and <listener> (that is, JMS, SQL and so forth.) Using one of these special variants allows you to have stronger validation on the configuration. These specializations explicitly define the configuration requirements for each of the transports supported by the product out-of-the-box.

Note

Using one of these specific implementations also makes configuration easier if you are using an XSD-aware XML editor (such as JBoss Developer Studio).

Important

Red Hat recommends you use these specialized types instead of the “base” types when creating JBoss ESB configurations. The only variation is when a new transport is being supported outside an official product release.
The same basic principals that apply when creating configurations from the “base” types also apply when creating configurations from the transport-specific alternatives:
  1. Define the provider configuration e.g. <jms-provider>.
  2. Add the bus configurations to the new provider (for example, <jms-bus>), and assign a unique busid attribute value.
  3. Define your <services> as "normal," adding transport-specific listener configurations (such as <jms-listener>) that reference (using busidref) the new bus configurations you just made. (For example, <jms-listener> referencing a <jms-bus>.)
The only rule that applies when using these transport-specific types is that you cannot cross-reference from a listener of one type, to a bus of another. In other words, you can only reference a <jms-bus> from a <jms-listener>. A runtime error will result where cross-references are made.
So the transport specific implementations that are in place in this product are as follows:
  1. JMS: <jms-provider>, <jms-bus>, <jms-listener> and <jms-message-filter>: The <jms-message-filter> can be added to either the <jms-bus> or <jms-listener> elements. Where the <jms-provider> and <jms-bus> specify the JMS connection properties, the <jms-message-filter> specifies the actual message QUEUE/TOPIC and selector details.
  2. SQL: <sql-provider>, <sql-bus>, <sql-listener> and <sql-message-filter>: The <sql-message-filter> can be added to either the <sql-bus> or <sql-listener> elements. Where the <sql-provider> and <sql-bus> specify the JDBC connection properties, the <sql-message-filter> specifies the message/row selection and processing properties.
  3. FTP: <ftp-provider>, <ftp-bus>, <ftp-listener> and <ftp-message-filter>: The <ftp-message-filter> can be added to either the <ftp-bus> or <ftp-listener> elements. Where the <ftp-provider> and <ftp-bus> specify the FTP access properties, the <ftp-message-filter> specifies the message/file selection and processing properties
  4. Hibernate: <hibernate-provider>, <hibernate-bus>, <hibernate-listener> : The <hibernate-message-filter> can be added to either the <hibernate-bus> or <hibernate-listener> elements. Where the <hibernate-provider> specifies file system access properties like the location of the hibernate configuration property, the <hibernate-message-filter> specifies what classnames and events should be listened to.
  5. File system: <fs-provider>, <fs-bus>, <fs-listener> and <fs-message-filter> The <fs-message-filter> can be added to either the <fs-bus> or <fs-listener> elements. Where the <fs-provider> and <fs-bus> specify the File System access properties, the <fs-message-filter> specifies the message/file selection and processing properties.
  6. schedule: <schedule-provider>. This is a special type of provider and differs from the bus based providers listed above. See Scheduling for more.
  7. JMS/JCA Integration : <jms-jca-provider>: This provider can be used in place of the <jms-provider> to enable delivery of incoming messages using JCA inflow. This introduces a transacted flow to the action pipeline, and thereby encompasses actions within a JTA transaction.
Each of the transport-specific types include an additional element not present in the “base”, this being <*-message-filter>. This element can be added inside either the <*-bus> or <*-listener>. If you use this element in both places you can specify message-filtering globally for the bus (in other words, for every listeners using that bus) or locally (that is, on a listener-by-listener basis).

Table 10.4. JMS Message Filter Configuration

Property Name Description Required
dest-type The type of destination, either QUEUE or TOPIC Yes
dest-name The name of the Queue or Topic Yes
selector Allows multiple listeners to register with the same queue/topic which will filter on this message-selector. No
persistent Indicates if the delivery mode for JMS should be persistent or not. Set as true or false. (Default is true.) No
acknowledge-mode The JMS Session acknowledge mode. Can be one of AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE. Default is AUTO_ACKNOWLEDGE No
jms-security-principal JMS destination username. This will be used when creating a connection to the destination. No
jms-security-credential JMS destination password. This will be used when creating a connection to the destination. No

Here is an example configuration:
 <jms-bus busid="quickstartGwChannel">
     <jms-message-filter
         dest-type="QUEUE"
         dest-name="queue/quickstart_jms_secured_Request_gw"
         jms-security-principal="esbuser"
         jms-security-credential="esbpassword"/>
</jms-bus>

Table 10.5. JMS Listener configuration

Property Name Description Required
name The listener name. Yes
busrefid The ID of the JMS bus on which to listen. No
is-gateway Is this JMS Listener instance a gateway, or is it a message aware listener. No. Default is false.
maxThreads The maximum number of threads to use when listening for messages on the JMS bus. Only relevant if is-gateway is false. No. Default is 1
clientId Client ID to be associated with the JMS connection. Used to associate a connection and its objects with state maintained on behalf of the client by a provider. (For example, durable subscriptions.) No. If a clientId is required (e.g. when a durableSubscriptionName is specified), but is not specified, it will default to the listener name.
durableSubscriptionName Durable subscription name. No. Only relevant for JMS Topics.