servicemix-jms

ServiceMix ships with a JBI compliant JMS binding component named servicemix-jms.

Here are the main features:

  • JBI compliant Binding Component
  • Usable in a lightweight mode in servicemix.xml configuration files
  • SOAP 1.1 and 1.2 support
  • MIME attachments
  • WS-Addressing support
  • WSDL based and XBean based deployments
  • Support for all MEPs as consumers or providers
Newer JMS Endpoints Available

There are newer JMS endpoints available. See the servicemix-jms new endpoints document for more information.

Installation

Installing the servicemix-jms component can be done in several ways:

  • drop the installer zip in an hotdeploy directory monitored by ServiceMix
  • using ant tasks

Note that when using ant tasks, the component is not started, you will have to start it manually using ant tasks or a console.

Configuration

Several parameters can be configured using a JMX console.

Configuration
Name Type Description Default
userName String UserName used to create a connection  
password String Password used to create a connection  
jndiInitialContextFactory String Default JNDI InitialContext factory false
jndiProviderUrl String Default JNDI provider url  
jndiName String Default JNDI name to lookup the JMS ConnectionFactory  

 
 

XBean deployment

You can deploy Service Units containing a file named xbean.xml for activating consumer and provider endpoints.

This xml file should respect the given syntax, though this is a spring based xml configuration file from where all beans of class JmsEndpoint are retrieved.
See a full example here.  Note that you have to define the jms namespace with

<beans xmlns:jms="http://servicemix.apache.org/jms/1.0">
    ...
</beans>

Any numbers of endpoints can be specified in the xbean.xml file.

ServiceMix >= 3.2 ships with new endpoints. We encourage all users to use those. They are described at servicemix-jms new endpoints.

Consumer endpoint

A consumer endpoint is a server-side http endpoint that will consume plain JMS, or JMS+SOAP requests and send them into the NMR to a given JBI endpoint, which is called the proxied endpoint.

Following is an example of an jms consumer endpoint.

<jms:endpoint service="test:MyConsumerService"
              endpoint="jms"
              targetService="test:MyConsumerService"
              targetEndpoint="myConsumer"
              role="consumer" 
              destinationStyle="queue"
              jmsProviderDestinationName="queue/A"
              jndiConnectionFactoryName="ConnectionFactory"
              defaultMep="http://www.w3.org/2004/08/wsdl/in-out"
              defaultOperation="test:Echo" />
Consumer endpoint attributes
Name Type Description Required
service QName the service name of the proxied endpoint yes
endpoint String the endpoint name of the proxied endpoint yes
interfaceName QName the interface name of the proxied endpoint  
targetService QName the service name of the target endpoint no (defaults to the service attribute)
targetEndpoint String the endpoint name of the target endpoint no (defaults to the endpoint attribute)
targetInterfaceName QName the interface name of the target endpoint  
role String must be 'consumer' yes
defaultMEP URI the default MEP uri to use no
defaultOperation QName the default operation name to set on the JBI exchange. if not set, it defaults to the QName of the root xml element no
soap boolean if set, the component will parse the soap requests and send the content into the NMR no (defaults to false)
soapVersion string can be set to '1.1' to force the use of SOAP 1.1 messages no
wsdlResource Spring resource if set, the wsdl will be retrieved from the given Spring resource no
initialContextFactory String the JNDI context factory class name no
jndiProviderURL String the JNDI provide url no
connectionFactory javax.jms.ConnectionFactory the connectionFactory to use. This optional property can be used instead of using JNDI configuration no
jndiConnectionFactoryName String the JNDI name of the JMS ConnectionFactory to lookup yes (unless a default one is provided on the jms component configuration)
destination javax.jms.Destination the Destination to use. This optional property can be use instead of jndiDestinationName or jmsProviderDestinationName no (one of destination, jndiDestinationName or jmsProviderDestinationName)
jndiDestinationName String the JNDI name of the destination to look up yes (unless destination or jmsProviderDestinationName is set)
jmsProviderDestinationName String if used, the target JMS destination will be created by the JMS provider by calling Session.createQueue or Session.createTopic no (one of destination, jndiDestinationName or jmsProviderDestinationName)
destinationStyle String used to select the destination type used with the jmsProviderDestinationName no (unless jmsProviderDestinationName is used)
useMsgIdInResponse boolean true indicates that the JMS correlation id will be set to the id of the JMS request message; false indicates that an artificial correlation id will be used instead no (in this case the default behaviour is to use the message exchange id as the correlation id)

The targetService, targetEndpoint and targetInterfaceName attributes can be used to specify the routing method to use (routing by interface, service or endpoint) and is also useful to allow several proxy endpoints to be created for the same JBI endpoint. For example to create an JMS only endpoint and an JMS+SOAP endpoint, both jms endpoints will have the same targetEndpoint and targetService, but they must have different endpoint names.

Provider endpoint

A provider endpoint is a client-side jbi endpoint which can receive requests from the NMR and send them to a given url where the service is provided.

Here is an example of an jms provider endpoint:

<jms:endpoint service="test:MyProviderService"
              endpoint="myProvider"
              role="provider" 
              destinationStyle="queue"
              jmsProviderDestinationName="queue/A"
              jndiConnectionFactoryName="ConnectionFactory"
              wsdlResource="classpath:provider.wsdl" />
Provider endpoint attributes
Name Type Description Required
service QName the service name of the exposed jbi endpoint yes
endpoint String the endpoint name of the exposed jbi endpoint yes
interfaceName QName the interface name of the exposed jbi endpoint no
role String must be 'provider' yes
locationURI URI the http url of the target service yes
soap boolean if set, the component will parse the message from the NMR and wrap it in a SOAP envilope no (defaults to false)
wsdlResource Spring resource if set, the wsdl will be retrieved from the given Spring resource no
initialContextFactory String the JNDI context factory class name no
jndiProviderURL String the JNDI provide url no
connectionFactory javax.jms.ConnectionFactory the connectionFactory to use. This optional property can be used instead of using JNDI configuration no
jndiConnectionFactoryName String the JNDI name of the JMS ConnectionFactory to lookup yes (unless a default one is provided on the jms component configuration)
destination javax.jms.Destination the Destination to use. This optional property can be use instead of jndiDestinationName or jmsProviderDestinationName no (one of destination, jndiDestinationName or jmsProviderDestinationName)
jndiDestinationName String the JNDI name of the destination to look up yes (unless destination or jmsProviderDestinationName is set)
jmsProviderDestinationName String if used, the target JMS destination will be created by the JMS provider by calling Session.createQueue or Session.createTopic no (one of destination, jndiDestinationName or jmsProviderDestinationName)
destinationStyle String used to select the destination type used with the jmsProviderDestinationName no (unless jmsProviderDestinationName is used)
needJavaIdentifiers boolean (defaults to false) indicates that the jms provider does not support extented syntax for JMS properties and only support valid java identifiers. In such a case, all non conformant properties will not be set on the JMS message.

Processors

Several types of processors are defined to configure the behavior of servicemix-jms endpoints. These are:

  • multiplexing (default) is optimized for ActiveMQ
  • standard which is best suited for other JMS providers
  • jca can be used for transacted deliveries

The processor used on a given endpoint can be configured using the processorName attribute on the endpoint.

JCA enabled endpoints need specific configuration. A full example is available here

Configuring the ConnectionFactory and Destination

JNDI configuration

When the ConnectionFactory or the Destination is lookup in JNDI, the JNDI context will be created in the following order:

  • using the initialContextFactory and jndiProviderURL
  • using the initialContextFactory and jndiProviderURL configured on the component configuration
  • using the default context provided by the JBI container

ConnectionFactory

The JMS ConnectionFactory is retrieved using the properties defined on the endpoint in the following order:

  • using connectionFactory
  • using jndiConnectionFactoryName to lookup the ConnectionFactory in JNDI
  • using the connectionFactory configured on the component configuration
  • using the jndiConnectionFactoryName configured on the component configuration to lookup the ConnectionFactory in JNDI

Destination

The JMS Destination is retrieved in the following order:

  • using destination
  • using jndiDestinationName
  • using jmsProviderDestinationName and destinationStyle

Examples

Using JNDI

<jms:endpoint ...
    jndiConnectionFactoryName="java:comp/env/jms/ConnectionFactory"
    jndiDestinationName="java:comp/env/jms/MyQueue" />

If you use ActiveMQ, you can use the following definition:

<jms:endpoint ...
    connectionFactory="#connectionFactory"
    destinationStyle="queue"
    jmsProviderDestinationName="MyQueue" />

<bean id="connectionFactory" class="org.apache.activemq.ActiveMQConnectionFactory">
    <property name="brokerURL" value="tcp://localhost:61216" />
</bean>

WSDL Deployment

In addition to xbean based deployment, the component accepts WSDL-based deployment.
The service unit may contain any number of WSDL files, each one being parsed and activating the specified endpoints.
To retrieve the necessary informations from the wsdl, the component can recognize a jms extension to provide JNDI informations and a jbi extension which specifies the role of the component and the default MEP to use for JBI exchanges.

Here is an example of a WSDL:

<definitions name='Echo' 
             targetNamespace='http://jms.servicemix.org/Test' 
             xmlns:tns='http://jms.servicemix.org/Test' 
             xmlns:jms='http://servicemix.org/wsdl/jms/' 
             xmlns='http://schemas.xmlsoap.org/wsdl/'
             xmlns:jbi='http://servicemix.org/wsdl/jbi/'>

    <portType name='EchoInterface'>
    </portType>

    <binding name='EchoJmsBinding' type='tns:EchoInterface'>
        <jms:binding />
    </binding>

    <service name='Echo'>
        <port name='EchoEndpoint' binding='tns:EchoJmsBinding'>
            <jms:address destinationStyle="queue"
                         jmsProviderDestinationName="queue/A"
                         jndiConnectionFactoryName="ConnectionFactory"/>
            <jbi:endpoint role="consumer"
                          defaultOperation="tns:Echo"/>
        </port>
    </service>
</definitions>

Lightweight mode

The servicemix-jms component can also be configured in a spring/xbean configuration file, for use in an embedded ServiceMix.
Here is an example of such a configuration:

<sm:activationSpec>
  <sm:component>
    <jms:component>
      <jms:endpoints>
        <jms:endpoint service="test:MyConsumerService"
                      endpoint="myConsumer"
                      role="consumer" 
                      defaultMep="http://www.w3.org/2004/08/wsdl/in-out"
                      destinationStyle="queue"
                      jmsProviderDestinationName="queue/A"
                      jndiConnectionFactoryName="jms/ConnectionFactory" />

        <jms:endpoint service="test:MyProviderService"
                      endpoint="myProvider"
                      role="provider" 
                      destinationStyle="queue"
                      jmsProviderDestinationName="queue/A"
                      connectionFactory="#connectionFactory" />
      </jms:endpoints>
    </jms:component>
  </sm:component>
</sm:activationSpec>
Classpath issues when embedding servicemix-jms component

When using the servicemix.xml configuration file to create jms endpoints, you must include the servicemix-jms-xxx.jar in your classpath.
You will find this file inside the component installer (./components/servicemix-jms-xxx.zip).
Failing this, an IllegalArgumentException will be thrown with the following message:
Component name: xxxxxx is bound to an object which is not a JBI component, it is of type: javax.xml.namespace.QName

Accessing WSDLs

WSDLs for consumer endpoints are retrieved using the following method:

  • for a WSDL based deployed endpoint, the WSL will be used as is
  • for an XBean based deployed endpoint, the WSDL will be retrieved from the wsdlResource attribute
  • if this information is not provided, the component will try to generate a WSDL by retrieving the target endpoint WSDL and adding the relevant informations to it.

WSDLs are accessible on the MBean for the Endpoint using a JMX console.

WS-Addressing

When used on a SOAP consumer endpoint, servicemix-jms handles the WS-Adressing Action and To headers.

wsa:Action

The wsa:Action header can be used to specify the target interface name and operation to use for the JBI exchange.

The header uses the following syntax:

[target namespace][delimiter][interface name][delimiter][operation name]

where:

  • [delimiter] is ":" when the [target namespace] is a URN, otherwise "/".
  • [target namespace] is the namespace of the interface.
  • [interface name] is the name of the interface.
  • [operation name] is the name of the operation.

For example, the following header

<wsa:Action>http://example.com/stockquote/StockQuoteInterface/GetLastTradePrice</wsa:Action>

will be used to address the JBI exchange with the following properties:

wsa:To

The wsa:To header specifies the target JBI service name and endpoint name.

The header uses the following syntax:

[target namespace][delimiter][service name][delimiter][endpoint name]

where:

  • [delimiter] is ":" when the [target namespace] is a URN, otherwise "/".
  • [target namespace] is the namespace of the interface.
  • [service name] is the name of the service.
  • [endpoint name] is the name of the endpoint.

For example, the following header

<wsa:To>urn:example:stockquote:StockQuoteService:JBIEndpoint</wsa:To>

will be used to address the JBI exchange with the following properties:

  • service name: {urn:example:stockquote}StockQuoteService
  • endpoint name: JBIEndpoint