Overview

Search

Documentation

Community

Developers

Components list

Related Projects

New servicemix-jms Endpoints

These newer JMS endpoints reuse some of the Spring JMS features including the message listener container, JMS transactions and the JMS template. Using these new endpoints can be achieved by using the jms:consumer and jms:provider in the xbean.xml file for the servicemix-jms component. This page provides various examples of the syntax to access these newer endpoints.

Consumer Endpoints

Simple Examples

<jms:consumer service="my:ConsumerService"
              endpoint="jbi"
              destinationName="my.queue"
              connectionFactory="#connectionFactory"
              concurrentConsumers="8" />

<jms:soap-consumer wsdl="classpath:service.wsdl"
                   destinationName="my.queue"
                   connectionFactory="#connectionFactory"
                   concurrentConsumers="8" />

<jms:jca-consumer service="my:ConsumerService"
                  endpoint="jbi"
                  destinationName="my.queue"
                  connectionFactory="#connectionFactory"
                  resourceAdapter="#ra"
                  activationSpec="#as" />

The Connection Factory

ActiveMQ

If you're using ActiveMQ, the ActiveMQ connection pool from the Jencks AMQPool. Just add jencks-amqpool to your classpath. Then you can define a connection pool the following way:

<beans xmlns:amqpool="http://jencks.org/amqpool/2.0">
  <amqpool:xa-pool id="connectionFactory" 
                   url="tcp://localhost:61616"
                   transactionManager="#transactionManager" />
</beans>

See the Jencks AMQPool documentation from the Jencks project for more information.

Other JMS providers

For other JMS providers, the ConnectionFactory can be configured to be retrieved via JNDI:

<beans xmlns:jee="http://www.springframework.org/schema/jee">
  <jee:jndi-lookup id="connectionFactory" jndi-name="weblogic.jms.XAConnectionFactory">
    <jee:environment>
      java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory
      java.naming.provider.url=t3://localhost:7001
    </jee:environment>
  </jee:jndi-lookup>
<beans>

Or just configured as a Spring bean: 

<bean id="connectionFactory" class="com.ibm.mq.jms.MQQueueConnectionFactory">
     <property name="transportType">
         <util:constant static-field="com.ibm.mq.jms.JMSC.MQJMS_TP_CLIENT_MQ_TCPIP" />
     </property>
     <property name="queueManager" value="foo.queue.mgr" />
     <property name="hostName" value="hostname" />
     <property name="channel" value="channelname" />
     <property name="port" value="12345" />
</bean>

Check your JMS provider for any of the provider-specific configuration that might be needed.

Tips

Using a Marshaler

The org.apache.servicemix.jms.endpoints.JmsConsumerMarshaler interface defines the way the incoming JMS message is transformed. There are two implementations:

  • DefaultConsumerMarshaler for <jms:consumer/> and <jms:jca-consumer/> endpoints
  • JmsSoapConsumerMarshaler for <jms:soap-consumer/> endpoints

For SOAP enabled endpoints, there is not particular need to modify the way the marshaling is done. But the DefaultConsumerMarshaler does not support the whole range of messages. So from time to time, you will need to process JMS properties or receive a Map based message. In such a case, you would create your own class implementing the JmsConsumerMarshaler interface and configure it on the endpoint:

<jms:consumer service="my:ConsumerService"

              endpoint="jbi"
              destinationName="my.queue"
              connectionFactory="#connectionFactory"
              marshaler="#myMarshaler" />

<bean id="myMarshaler" class="my.package.MyMarshaler" />

OR

<jms:consumer service="foo:MyService"
  endpoint="blah"
  destinationName="FOO.BAR"
  connectionFactory="#connectionFactory"
  marshaler="#marshaler" />

<bean id="marshaler" class="org.apache.servicemix.jms.endpoints.DefaultConsumerMarshaler">
   <property name="mep" value="http://www.w3.org/2004/08/wsdl/in-out" />
</bean>

Reference

ServiceMix uses JMS support from the Spring Framework, hence most of the following properties are fully documented at the following locations:

Common Properties

Name Type Bean Description Required
service QName no The service name of the proxied endpoint yes
endpoint String no The endpoint name of the proxied endpoint yes
interfaceName QName no The interface name of the proxied endpoint no
       
targetService QName no The service name of the target endpoint no (defaults to the service attribute)
targetEndpoint String no The endpoint name of the target endpoint no (defaults to the endpoint attribute)
targetInterface QName no The interface name of the target endpoint no
targetUri String no The URI of the target endpoint no
       
marshaler JmsConsumerMarshaler yes The class implementing the message marshaler no (defaults to DefaultConsumerMarshaler)
synchronous boolean no Specifies if the consumer will block while waiting for a response no (defaults to true)
destinationChooser DestinationChooser yes A class implementing logic for choosing among JMS destinations no
destinationResolver DestinationResolver yes A class implementing logic for converting strings into destination IDs no (defaults to DynamicDestinationResolver)
pubSubDomain boolean no Specifies if the destination is a topic  
connectionFactory ConnectionFactory yes The ConnectionFactory used to connect with the destination yes
         
useMessageIdInResponse Boolean yes Specifies if the request message's ID is used as the reply's correlation ID no (if not set the request's correlation ID is used)
replyDestination Destination yes Specifies the JMS destination for the reply no (if not set either the replyDestination or the destinationChooser is used)
replyDestinationName String no Specifies the name of the JMS destination to use for the reply no (if not set the replyDestination or the destinationChooser is used)
replyExplicitQosEnabled boolean no Specifies if the QoS values specified for the endpoint are explicity used when the reply is sent no (default is false)
replyDeliveryMode int no Specifies the JMS delivery mode used for the reply no (defaults to persistent)
replyPriority int no Specifies the JMS message priority of the reply no (defaults to 4)
replyTimeToLive long no Specifies the number of milliseconds the reply message is valid no (defaults to unlimited)
replyProperties Map yes Specifies custom properties to be placed in the reply's JMS header no
         
storeFactory StoreFactory yes The factory class used to create the data store for state information no (defaults to MemoryStoreFactory)
store Store yes The data store used to store state information no

<jms:consumer/> and <jms:soap-consumer/>

Name Type Description Required
listenerType String Specifies the type of Spring JMS message listener to use default, simple, server (defaults to default)
jms102 boolean Specifies if the consumer is to be use JMS 1.0.2 no (defaults to false)
transacted String Specifies the type of transaction to wrap the message exchanges none, xa, jms (defaults to none)
Name Type Simple Default Server Description Required
clientId String X X X The JMS client id for a shared Connection created and used by this listener no
destination Destination X X X The destination used to receive messages no
destinationName String X X X The name of the destination used to receive messages no
durableSubscriptionName String X X X The durable subscriber name no
exceptionListener ExceptionListener X X X The ExceptionListener to notify in case of a JMSException thrown by the registered message listener or the invocation infrastructure no
messageSelector String X X X The message selector string to use no
sessionAcknowlegeMode int X X X The acknowledgment mode that is used when creating a Session to send a message no (defaults to Session.AUTO_ACKNOWLEDGE)
subscriptionDurable boolean X X X Specifies if the listener uses a durable subscription to listen form messages no (defaults to false)
pubSubNoLocal boolean X X   Specifies if messages published by the listener's Connection are suppressed no (defaults to false)
concurrentConsumers int X X   The number of concurrent consumers created by the listener no (defaults to 1)
cacheLevel int   X   The level of caching allowed by the listener no (defaults to CACHE_NONE)
receiveTimeout long   X   The timeout for receiving a message in milliseconds no (default is 1000)
recoveryInterval long   X   The interval, in milliseconds, between attempts to recover after a failed listener set-up no (defaults to 5000)
maxMessagesPerTask int   X X The number of attempts to receive messages per task no
serverSessionFactory ServerSessionFactory     X The ServerSessionFactory to use no (defaults to SimpleServerSessionFactory)
cacheLevel

The listener cacheLevel defaults to CACHE_NONE, which means no jms resources are cached at all. If your consumer consumes any volume of messages you should set this to at least CACHE_CONNECTION (cacheLevel="1") or for optimal consumer performance use CACHE_CONSUMER (cacheLevel="3")

Soap specific properties

Note that when deploying a soap consumer, the service and endpoint name are optional and can be inferred from the given WSDL (if the WSDL only contains a single port definition). If the service and/or endpoint attributes are given, they must match the service and port name of the WSDL.

Name Type Description Required
wsdl Resource WSDL describing the service yes
useJbiWrapper boolean Specifies if the JBI wrapper is sent in the body of the message no (defaults to true)
validateWsdl boolan Checks WSI-BP compliance no (defaults to true)
policies Policy[] A list of interceptors that will process the message no

<jms:jca-consumer/>

Name Type Description Required
resourceAdapter ResourceAdapter The resource adapter used for the endpoint yes
activationSpec ActivationSpec The activation information needed for the endpoint yes
bootstrapContext BootstrapContext The bootstrap context used when starting the resource adapter no (a default one will be created)

Provider Endpoints

Simple Examples

<jms:provider service="my:ProviderService"
              endpoint="jbi"
              destinationName="my.queue"
              connectionFactory="#connectionFactory" />

<jms:soap-provider wsdl="classpath:service.wsdl"
                   destinationName="my.queue"
                   connectionFactory="#connectionFactory" />

The Connection Factory

ActiveMQ

We recommend jencks specific ActiveMQ connection pool if you use ActiveMQ.
Just add jencks-amqpool to your classpath. Then you can define a connection pool the following way:

<beans xmlns:amqpool="http://jencks.org/amqpool/2.0">
  <amqpool:xa-pool id="connectionFactory" 
                   url="tcp://localhost:61616"
                   transactionManager="#transactionManager" />
</beans>

Take a look at the AMQPool documentation from the Jencks project for more information.

Other JMS providers

For other JMS providers, the ConnectionFactory can be configured to be retrieved via JNDI:

<beans xmlns:jee="http://www.springframework.org/schema/jee">
  <jee:jndi-lookup id="connectionFactory" jndi-name="weblogic.jms.XAConnectionFactory">
    <jee:environment>
      java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory
      java.naming.provider.url=t3://localhost:7001
    </jee:environment>
  </jee:jndi-lookup>
<beans>

Or just configured as a Spring bean: 

<bean id="connectionFactory" class="com.ibm.mq.jms.MQQueueConnectionFactory">
     <property name="transportType">
         <util:constant static-field="com.ibm.mq.jms.JMSC.MQJMS_TP_CLIENT_MQ_TCPIP" />
     </property>
     <property name="queueManager" value="foo.queue.mgr" />
     <property name="hostName" value="hostname" />
     <property name="channel" value="channelname" />
     <property name="port" value="12345" />
</bean>

Check your JMS provider for any of the provider-specific configuration that might be needed.

Tips

Using a Marshaler

The org.apache.servicemix.jms.endpoints.JmsProviderMarshaler interface defines the way incoming and outgoing JMS messages are transformed. There are two implementations:

  • DefaultProviderMarshaler for <jms:provider /> endpoints
  • JmsSoapProviderMarshaler for <jms:soap-provider /> endpoints

For SOAP enabled endpoints, there is no particular need to modify the way the marshaling is done. But the DefaultProviderMarshaler does not support the whole range of messages. So from time to time, you will need to process JMS properties or receive a Map based message. In such a case, you would create your own class implementing the JmsProviderMarshaler interface and configure it on the endpoint:

<jms:provider service="my:ProviderService"
              endpoint="jbi"
              destinationName="my.queue"
              connectionFactory="#connectionFactory"
              marshaler="#marshaler" />
<bean id="marshaler" class="my.package.MyMarshaler" />

Use a pooled connectionFactory for optimal jms:provider performance.

In order to optimize jms resource usage configure your jms:provider with a PooledConnectionFactory.

Example:

  <bean id="connectionFactory" class="org.apache.activemq.pool.PooledConnectionFactory">
    <property name="connectionFactory">
      <bean class="org.apache.activemq.ActiveMQConnectionFactory">
        <property name="brokerURL" value="tcp://localhost:61616" />
      </bean>
    </property>
    <!--Configure maximum connections used by the pool -->
    <property name="maxConnections" value="1" />
    <!--Configure maximum sessions per connection -->
    <property name="maximumActive" value="1" />
  </bean>

See: JMS Template Gotchas for additional background.

Reference

Common Properties

Attributes

Name Type Description Required
deliveryMode int The JMS delivery mode no (defaults to persistent)
destinationName String The JNDI name of the destination used to send messages no
endpoint String The endpoint name of the proxied endpoint yes
explicitQosEnabled boolean Specifies if the JMS messages have the specified properties explicitly applied no
interfaceName QName The interface name of the proxied endpoint no
jms102 boolean Specifies if the consumer is to be use JMS 1.0.2 no (defaults to false)
messageIdEnabled boolean Specifies if JMS message IDs are enabled no (defaults to true)
messageTimeStampEnabled boolean Specifies if JMS messages are time stamped no (defaults to true)
priority int The JMS message priority no (defaults to 4)
pubSubDomain boolean Specifies if the destination is a topic no
pubSubNoLocal boolean Specifies if messages published by the listener's Connection are suppressed no (defaults to false)
recieveTimeout long The timeout for receiving a message in milliseconds no (default is unlimited)
replyDestinationName String The JNDI name of the destination used to receive messages no
service QName The service name of the proxied endpoint yes
stateless boolean Specifies if the consumer retains state information about the message exchange while it is in process no
timeToLive long Specifies the number of milliseconds the message is valid no (defaults to unlimited)

Beans

Name Type Description Required
connectionFactory ConnectionFactory The ConnectionFactory used to connect with the destination yes
destination Destination The JMS destination used to send messages no
destinationChooser DestinationChooser A class implementing logic for choosing among JMS destinations no (defaults to SimpleDestinationChooser)
destinationResolver DestinationResolver A class implementing logic for converting strings into destination IDs no (defaults to DynamicDestinationResolver)
marshaler JmsProviderMarshaler The class implementing the message marshaler no (defaults to DefaultProviderMarshaler or JmsSoapProviderMarshaler)
replyDestination Destination The JMS destinations to receive messages no
storeFactory StoreFactory The factory class used to create the data store for state information no (defaults to MemoryStoreFactory)
store Store The data store used to store state information no

SOAP Specific Properties

The following are only applicable to <jms:soap-provider />.

Attributes

Name Type Description Required
useJbiWrapper boolean Specifies if the JBI wrapper is sent in the body of the message no (defaults to true)
validateWsdl boolan Specifies if the WSDL is checked for WSI-BP compliance no (defaults to true)
wsdl Resource WSDL describing the service yes

Beans

Name Type Description Required
policies Policy[] A list of interceptors that will process the message no