Red Hat Training

A Red Hat training course is available for Red Hat Fuse

15.2. Using the Generic Endpoint or the SOAP Endpoint

15.2.1. Basic Configuration

Procedure

To configure a generic consumer or a SOAP consumer do the following:
  1. Decide what type of consumer endpoint to use.
    See the section called “Types of consumer endpoints”.
  2. Specify the name of the service for which this endpoint is acting as a proxy.
    This is specified using the service attribute.
    Tip
    If you are using a SOAP consumer and your WSDL file only has one service defined, you do not need to specify the service name.
  3. Specify the name of the endpoint for which this endpoint is acting as a proxy.
    This is specified using the endpoint attribute.
    Tip
    If you are using a SOAP consumer and your WSDL file only has one endpoint defined, you do not need to specify the endpoint name.
  4. Specify the connection factory the endpoint will use.
    The endpoint's connection factory is configured using the endpoint's connectionFactory attribute. The connectionFactory attribute's value is a reference to the bean that configures the connection factory. For example, if the connection factory configuration bean is named widgetConnectionFactory, the value of the connectionFactory attribute would be #widgetConnectionFactory.
    For information on configuring a connection factory see Chapter 14, Configuring the Connection Factory.
  5. Specify the destination onto which the endpoint will place messages.
    For more information see the section called “Configuring a destination”.
  6. Specify the ESB endpoint to which incoming messages are targeted.
    For more information see the section called “Specifying the target endpoint”.
  7. If you are using a JMS SOAP consumer, specify the location of the WSDL defining the message exchange using the wsdl attribute.
  8. If your JMS destination is a topic, set the pubSubDomaim attribute to true.
  9. If your endpoint is interacting with a broker that only supports JMS 1.0.2, set the jms102 attribute to true.

Configuring a destination

A consumer endpoint chooses the destination to use for sending messages with the following algorithm:
  1. The endpoint will check to see if you configured the destination explicitly.
    You configure a destination using a Spring bean. You can add the bean directly to the endpoint by wrapping it in a jms:destination child element. You can also configure the bean separately and refer the bean using the endpoint's destination attribute as shown in Example 15.1, “Configuring a Consumer's Destination”.

    Example 15.1. Configuring a Consumer's Destination

    <beans xmlns:jms="http://servicemix.apache.org/jms/1.0"
       ... >
  ...
  <jms:consumer service="my:widgetService"
                 endpoint="jbiWidget"
                 destination="#widgetQueue"
                 ... />
  ...
  <jee:jndi-lookup id="widgetQueue" jndi-name="my.widget.queue">
    <jee:environment>
      java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory
      java.naming.provider.url=t3://localhost:7001
    </jee:environment>
  </jee:jndi-lookup>
  ...
</beans>
  2. If you did not explicitly configure a destination, the endpoint will use the value of the destinationName attribute to choose its destination.
    The value of the destinationName attribute is a string that will be used as the name for the JMS destination. The binding component's default behavior when you provide a destination name is to resolve the destination using the standard JMS Session.createTopic() and Session.createQueue() methods.
    Note
    You can override the binding component's default behavior by providing a custom DestinationResolver implementation. See Section 19.2, “Using a Custom Destination Resolver”.

Specifying the target endpoint

There are a number of attributes available for configuring the endpoint to which the generated messages are sent. The poller endpoint will determine the target endpoint in the following manner:
  1. If you explicitly specify an endpoint using both the targetService attribute and the targetEndpoint attribute, the ESB will use that endpoint.
    The targetService attribute specifies the QName of a service deployed into the ESB. The targetEndpoint attribute specifies the name of an endpoint deployed by the service specified by the targetService attribute.
  2. If you only specify a value for the targetService attribute, the ESB will attempt to find an appropriate endpoint on the specified service.
  3. If you do not specify a service name or an endpoint name, you must specify an the name of an interface that can accept the message using the targetInterface attribute. The ESB will attempt to locate an endpoint that implements the specified interface and direct the messages to it.
    Interface names are specified as QNames. They correspond to the value of the name attribute of either a WSDL 1.1 serviceType element or a WSDL 2.0 interface element.
Important
If you specify values for more than one of the target attributes, the consumer endpoint will use the most specific information.

Examples

Example 15.2, “Basic Configuration for a Generic Consumer Endpoint” shows the basic configuration for a plain JMS provider endpoint.

Example 15.2. Basic Configuration for a Generic Consumer Endpoint

<beans xmlns:jms="http://servicemix.apache.org/jms/1.0"
       ... >
  ...
  <jms:consumer service="my:widgetService"
                endpoint="jbiWidget"
                destinationName="widgetQueue"
                connectionFactory="#connectionFactory"
                targetService="my:targetService" />
  ...
</beans>
Example 15.3, “Basic Configuration for a SOAP Consumer Endpoint” shows the basic configuration for a SOAP JMS provider endpoint.

Example 15.3. Basic Configuration for a SOAP Consumer Endpoint

<beans xmlns:jms="http://servicemix.apache.org/jms/1.0"
       ... >
  ...
  <jms:soap-consumer wsdl="classpath:widgets.wsdl"
                     destinationName="widgetQueue"
                     connectionFactory="#connectionFactory"
                     targetService="my:targetService" />
  ...
</beans>

15.2.2. Listener Containers

Overview

Both the generic consumer endpoint and the SOAP consumer endpoint use Spring listener containers to handle incoming messages. The listener container handles the details of receiving messages from the destination, participating in transactions, and controlling the threads used to dispatch messages to the endpoint.

Types of listener containers

Red Hat JBoss Fuse's JMS consumer endpoints support three types of listener containers:
Simple
The simple listener container creates a fixed number of JMS sessions at startup and uses them throughout the lifespan of the container. It cannot dynamically adapt to runtime conditions nor participate in externally managed transactions.
Default
The default listener container provides the best balance between placing requirements on the JMS provider and features. Because of this, it is the default listerner container for Red Hat JBoss Fuse JMS consumer endpoints. The default listener container can adapt to changing runtime demands. It is also capable of participating in externally managed transactions.
Server session
The server session listener container leverages the JMS ServerSessionPool SPI to allow for dynamic management of JMS sessions. It provides the best runtime scaling and supports externally managed transactions. However, it requires that your JMS provider supports the JMS ServerSessionPool SPI.

Specifying an endpoint's listener container

By default, consumer endpoints use the default listener container. If you want to configure the an endpoint to use a different listener container, you specify that using the endpoint's listenerType attribute. Table 15.1, “Values for Configuring a Consumer's Listener Container” lists the values for the listenerType attribute.

Table 15.1. Values for Configuring a Consumer's Listener Container

ValueDescription
simple Specifies that the endpoint will use the simple listener container.
default Specifies that the endpoint will use the default listener container.
server Specifies that the endpoint will use the server session listener container.
Example 15.4, “Configuring a SOAP Consumer to Use the Simple Listener Container” shows configuration for SOAP consumer that uses the simple listener container.

Example 15.4. Configuring a SOAP Consumer to Use the Simple Listener Container

<beans xmlns:jms="http://servicemix.apache.org/jms/1.0"
       ... >
  ...
  <jms:soap-consumer wsdl="classpath:widgets.wsdl"
                     destinationName="widgetQueue"
                     connectionFactory="#connectionFactory"
                     listenerType="simple" />
  ...
</beans>

Performace tuning using the listener container

There are several ways of tuning the performance of a generic consumer endpoint or a SOAP consumer endpoint. They are all controlled by the listener container used by the endpoint.
Table 15.2, “Attributes Used to Performance Tune Standard JMS Consumers and SOAP JMS Consumers” describes the attributes used to tune endpoint performance.

Table 15.2. Attributes Used to Performance Tune Standard JMS Consumers and SOAP JMS Consumers

AttributeTypeListener(s)DescriptionDefault
cacheLevel intdefaultSpecifies the level of caching allowed by the listener. Valid values are 0(CACHE_NONE), 1(CACHE_CONNECTION), 2(CACHE_SESSION), and 3(CACHE_CONSUMER).0
clientId stringallSpecifies the ID to be used for the shared Connection object used by the listener container.Uses provider assigned ID
concurrentConsumers int
default
simple
Specifies the number of concurrent consumers created by the listener.1
maxMessagesPerTask int
default
server
Specifies the number of attempts to receive messages per task.-1(unlimited)
receiveTimeout longdefaultSpecifies the timeout for receiving a message in milliseconds.1000
recoveryIntervallongdefaultSpecifies the interval, in milliseconds, between attempts to recover after a failed listener set-up.5000
Example 15.5, “Tuning a Generic Consumer Endpoint” shows an example of a generic consumer that allows consumer level message caching and only tries once to receive a message.

Example 15.5. Tuning a Generic Consumer Endpoint

<beans xmlns:jms="http://servicemix.apache.org/jms/1.0"
       ... >
  ...
  <jms:consumer service="my:widgetService"
                endpoint="jbiWidget"
                destinationName="widgetQueue"
                connectionFactory="#connectionFactory" 
                cacheLevel="3"
                maxMessagesPerTask="1"/>
  ...
</beans>

Configuring the server session listener container's session factory

The server session listener container uses the JMS ServerSessionPool SPI to tune an endpoint's performance. In order for the listener container to function,k it uses a ServerSessionFactory object. By default, the Red Hat JBoss Fuse JMS BC uses the Spring framework's SimpleServerSessionFactory object. This server session factory creates a new JMS ServerSession object with a new JMS session everytime it is called.
You can configure the endpoint to use a different server session factory using the serverSessionFactory attribute. This attribute provides a reference to the bean configuring the ServerSessionFactory object.
Note
You can also explicitly configure the endpoint's ServerSessionFactory object by adding a serverSessionFactory child element to the endpoint's configuration. This element would wrap the ServerSessionFactory object's configuration bean.
Example 15.6, “Configuring a Consumer to Use a Pooled Session Factory” shows an example of configuring an endpoint to use the Spring framework's CommonsPoolServerSessionFactory object as a session factory.

Example 15.6. Configuring a Consumer to Use a Pooled Session Factory

<beans xmlns:jms="http://servicemix.apache.org/jms/1.0"
       ... >
  ...
  <jms:consumer service="my:widgetService"
                endpoint="jbiWidget"
                destinationName="widgetQueue"
                connectionFactory="#connectionFactory" 
                listenerType="server"
                serverSessionFactory="#pooledSessionFactory"/>

  <bean id="pooledSessionFactory"
         class="org.springframework.jms.listener.serversession.CommonsPoolServerSessionFactory" />
  ...
</beans>

15.2.3. Advanced Configuration

Using transactions

By default, generic consumers and SOAP consumers do not wrap message exchanges in transactions. If there is a failure during the exchange, you have no guarantee that resending the request will not result in duplicating a task that has already been completed.
If your application requires message exchanges to be wrapped in a transaction, you can use the endpoint's transacted attribute to specify the type of transactions to use. Table 15.3, “Consumer Transaction Support” describes the possible values for the transacted attribute.

Table 15.3. Consumer Transaction Support

ValueDescription
noneSpecifies that message exchanges are not wrapped in a transaction. This is the default setting.
jmsSpecifies that message exchanges are wrapped in local JMS transactions.
xaSpecifies that message exchanges will be wrapped in an externally managed XA transaction. You must also provide a transaction manager when using XA transactions.
Important
Only the default listener container can support XA transactions.

Using message selectors

If you want to configure your consumer to use a JMS message selector, you can set the optional messageSelector attribute. The value of the attribute is the string value of the selector. For more information on the syntax used to specify message selectors, see the JMS 1.1 specification.

Using durable subscriptions

If you want to configure your server to use durable subscriptions, you need to set values for two attributes. To indicate that the consumer uses a durable subscription you set the subscriptionDurable attribute to true. You specify the name used to register the durable subscription using the durableSubscriberName attribute.
Example 15.7, “Consumer using a Durable Subscription” shows a configuration snipit for a consumer that registers for a durable subscription.

Example 15.7. Consumer using a Durable Subscription

<beans xmlns:jms="http://servicemix.apache.org/jms/1.0"
       ... >
  ...
  <jms:soap-consumer wsdl="classpath:widgets.wsdl"
                     destinationName="widgetQueue"
                     connectionFactory="#connectionFactory"
                     subscriptionDurable="true"
                     durableSubscriberName="widgetSubscriber" />
  ...
</beans>

15.2.4. SOAP Specific Configuration

Overview

The SOAP consumer has two specialized configuration properties. One controls if the endpoint needs to use the JBI wrapper to make messages consumable. The other determines if the endpoint checks its WSDL for compliance with the WS-I basic profile.

Using the JBI wrapper

There are instances when a JBI component cannot consume a native SOAP message. For instance, SOAP headers pose difficulty for JBI components. The JBI specification defines a JBI wrapper that can be used to make SOAP messages, or any message defined in WSDL 1.1, conform to the expectations of a JBI component.
To configure a SOAP consumer to wrap messages in the JBI wrapper you set its useJbiWrapper attribute to true.
Example 15.8, “Configuring a SOAP Consumer to Use the JBI Wrapper” shows a configuration fragment for configuring a SOAP consumer to use the JBI wrapper.

Example 15.8. Configuring a SOAP Consumer to Use the JBI Wrapper

<beans xmlns:jms="http://servicemix.apache.org/jms/1.0"
       ... >
  ...
  <jms:soap-consumer wsdl="classpath:widgets.wsdl"
                     destinationName="widgetQueue"
                     connectionFactory="#connectionFactory"
                     useJbiWrapper="true" />
  ...
</beans>

WSDL verification

The WS-I basic profile is a specification describing the minimum set of requirements for a Web service to be considered interoperable. The requirement of the specification mostly constrain the binding of messages into SOAP containers.
By default, SOAP consumers will verify that their WSDL complies to the WS-I basic profile before starting up. If the WSDL does not comply, the endpoint will not start up.
If you want to skip the WS-I basic profile verification, you can set the consumer's validateWsdl attribute to false.