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" />

<jms:provider/>

Name	Type	Default	Description	Required
preserveQos	boolean	`false`	When set to `true`, the JMS Priority and TimeToLive set on the Message will override the value set on the endpoint	false

<jms:provider/>

Name	Type	Default	Description	Required
preserveQos	boolean	`false`	When set to `true`, the JMS Priority and TimeToLive set on the Message will override the value set on the endpoint	false

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

Child pages

servicemix-jms new endpoints

New servicemix-jms Endpoints

Consumer Endpoints

Simple Examples

The Connection Factory

ActiveMQ

Other JMS providers

Tips

Using a Marshaler

Reference

Common Properties

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

Soap specific properties

<jms:jca-consumer/>

Provider Endpoints

Simple Examples

<jms:provider/>

<jms:provider/>

The Connection Factory

ActiveMQ

Other JMS providers

Tips

Using a Marshaler

Use a pooled connectionFactory for optimal jms:provider performance.

Reference

Common Properties

Attributes

Beans

SOAP Specific Properties

Attributes

Beans

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

`<jms:jca-consumer/>`