JBI Support deprecated in Apache ServiceMix 4

JBI 1.0 support is available in Apache ServiceMix 4 to allow existing users to migrate more easily to this latest version - if you're a new user, you should consider JBI deprecated and not use it for your project. Take a look at our technology selection guidelines for more information.

servicemix-jms

Overview

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

Namespace and xbean.xml

The namespace URI for the servicemix-bean JBI component is http://servicemix.apache.org/jms/1.0. This is an example of an xbean.xml file with a namespace definition with prefix bean.

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

  <!-- add jms:consumer, jms:soap-consumer, jms:jca-consumer,
           jms:provider, jms:soap-provider and jms:jca-provider definitions here -->

</beans>

Endpoint types

The servicemix-jms component defines six endpoint type:

  • jms:consumer :: This endpoint allows you to expose a service in the ESB to the outside world over JMS. Whenever it receives a JMS message, it will interact with the configured services on the ESB.

  • jms:soap-consumer :: Similar to jms:consumer, but specifically geared towards handing SOAP requests and responses

  • jms:jca-consumer :: Similar to jms:consumer, but adds the possibility of using a JCA resource adapter

  • jms:provider :: This endpoint allows you to access remote services from within the ESB. It will send a JMS message whenever it receives a JBI MessageExchange

  • jms:soap-provider :: Similar to jms:provider, but specifically geared towards performing SOAP requests

  • jms:jca-provider :: Similar to jms:provider, but adds the possibility of using a JCA resource adapter

It also provides one additional legacy endpoints, which are still available to ease migration from ServiceMix 3:

  • jms:endpoint :: (Deprecated) Legacy endpoint, capable to acting as a consumer or provider based on the configuration

jms:endpoint

Endpoint properties

Property Name Type Description
activationSpec javax.resource.spi.ActivationSpec The ActivationSpec to use on a JCA consumer endpoint.
bootstrapContext javax.resource.spi.BootstrapContext The BootstrapContext to use for a JCA consumer endpoint.
connectionFactory javax.jms.ConnectionFactory A configured ConnectionFactory to use on this endpoint.
defaultMep java.net.URI
defaultOperation javax.xml.namespace.QName
description org.w3c.dom.Document
destination javax.jms.Destination A configured Destination to use on this endpoint.
destinationStyle java.lang.String Specifies the destination type used with the jmsProviderDestinationName. Can be <code>queue</code> or <code>topic</code>.
dynamic boolean
endpoint java.lang.String <p> Get the endpoint implementation. </p>
initialContextFactory java.lang.String The class name of the JNDI InitialContextFactory to use.
interfaceName javax.xml.namespace.QName <p> Get the qualified name of the endpoint interface. </p>
jmsProviderDestinationName java.lang.String The name of the destination created by a call to <code>Session.createQueue</code> or <code>Session.createTopic</code>. This property is used when <code>destination</code> and <code>jndiDestinationName</code> are both <code>null</code>.
jmsProviderReplyToName java.lang.String The name of the reply destination created by a call to <code>Session.createQueue</code> or <code>Session.createTopic</code>. This property is used when <code>jndiReplyToName</code> is <code>null</code>. A temporary queue will be used if a replyTo is not provided.
jndiConnectionFactoryName java.lang.String The name of the JMS ConnectionFactory to lookup in JNDI. Used if <code>connectionFactory</code> is <code>null</code>
jndiDestinationName java.lang.String The name of the JMS Destination to lookup in JNDI. Used if <code>destination</code> is <code>null</code>.
jndiProviderURL java.lang.String The provider URL used to create the JNDI context.
jndiReplyToName java.lang.String The name of the JMS Reply-to destination to lookup in JNDI. If this property is not set a temporary replyTo queue is used.
marshaler org.apache.servicemix.jms.JmsMarshaler Specifies the class implementing the logic for marshaling and unmarshaling messages between the JMS destination and the endpoint. Defaults to <code>DefaultJmsMarshaler</code>.
needJavaIdentifiers boolean Indicates if the JMS properties used by the endpoint need to be spec compliant.
policies (java.lang.Object)\*
processorName java.lang.String Specifies the processor family to use for this endpoint. Can be: <ul> <li><code>multiplexing</code> (default)</li> <li><code>standard</code></li> <li><code>jca</code></li> </ul>
resourceAdapter javax.resource.spi.ResourceAdapter The ResourceAdapter to use on a JCA consumer endpoint.
role java.lang.String Specifies the role of this endpoint. Endpoints can be <code>consumer</code> or <code>provider</code>.
roleAsString java.lang.String
rollbackOnError boolean Indicates if the JBI exchange is rolled back if an error is encountered.
service javax.xml.namespace.QName <p> Get the service qualified name of the endpoint. </p>
soap boolean
soapVersion java.lang.String
store org.apache.servicemix.store.Store Specifies a persistent data store to hold pending exchanges for the endpoint.
storeFactory org.apache.servicemix.store.StoreFactory Specifies the factory used to create presistent data stores for this endpoint.
synchronous boolean Indicates if a JCA consumer endpoint sends the JBI exchange synchronously or asynchronously. This changes the transaction boundary.
targetEndpoint java.lang.String
targetInterfaceName javax.xml.namespace.QName
targetService javax.xml.namespace.QName
useMsgIdInResponse boolean Indicates whether the message id of the request message should be used as the correlation id in the response or the correlation id of the request.
wsdlResource org.springframework.core.io.Resource

jms:consumer

Endpoint properties

Property Name Type Description
cacheLevel int Specifies the level of caching allowed by the listener. Valid values are 0 through 3. The values map to the following: <ul> <li>0 - <code>CACHE_NONE</code></li> <li>1 - <code>CACHE_CONNECTION</code></li> <li>2 - <code>CACHE_SESSION</code></li> <li>3 - <code>CACHE_CONSUMER</code></li> </ul> The default is <code>CACHE_NONE</code>.<br/> This property only effects consumers whose <code>listenerType</code> property is set to <code>default</code>.
clientId java.lang.String Specifies the JMS client id for a shared <code>Connection</code> created and used by this listener.
component org.apache.servicemix.common.DefaultComponent
concurrentConsumers int Specifies the number of concurrent consumers created by the listener. This property is only used for consumers whose <code>listenerType</code> property is set to either <code>simple</code> or <code>default</code>.
connectionFactory javax.jms.ConnectionFactory Specifies the <code>ConnectionFactory</code> used by the endpoint.
destination javax.jms.Destination Specifies the JMS <code>Destination</code> used to receive messages.
destinationChooser org.apache.servicemix.jms.endpoints.DestinationChooser Specifies a class implementing logic for choosing reply destinations.
destinationName java.lang.String Specifies a string identifying the JMS destination used to recieve messages. The destination is resolved using the <code>DesitinationResolver</code>.
destinationResolver org.springframework.jms.support.destination.DestinationResolver Specifies the class implementing logic for converting strings into destinations. The default is <code>DynamicDestinationResolver</code>.
durableSubscriptionName java.lang.String Specifies the name used to register the durable subscription.
endpoint java.lang.String <p> Get the endpoint implementation. </p>
exceptionListener javax.jms.ExceptionListener Specifies an <code>ExceptionListener</code> to notify in case of a <code>JMSException</code> is thrown by the registered message listener or the invocation infrastructure.
idleTaskExecutionLimit int Specifies the limit for idle executions of a receive task, not having received any message within its execution. If this limit is reached, the task will shut down and leave receiving to other executing tasks (in case of dynamic scheduling; see the "maxConcurrentConsumers" setting). Within each task execution, a number of message reception attempts (according to the "maxMessagesPerTask" setting) will each wait for an incoming message (according to the "receiveTimeout" setting). If all of those receive attempts in a given task return without a message, the task is considered idle with respect to received messages. Such a task may still be rescheduled; however, once it reached the specified "idleTaskExecutionLimit", it will shut down (in case of dynamic scaling). Raise this limit if you encounter too frequent scaling up and down. With this limit being higher, an idle consumer will be kept around longer, avoiding the restart of a consumer once a new load of messages comes in. Alternatively, specify a higher "maxMessagePerTask" and/or "receiveTimeout" value, which will also lead to idle consumers being kept around for a longer time (while also increasing the average execution time of each scheduled task).

jms:provider

Endpoint properties

Property Name Type Description
connectionFactory javax.jms.ConnectionFactory Specifies the <code>ConnectionFactory</code> used by the endpoint.
deliveryMode int Specifies the JMS delivery mode used for the reply. Defaults to (2)(<code>PERSISTENT</code>).
destination javax.jms.Destination Specifies the JMS <code>Destination</code> used to send messages.
destinationChooser org.apache.servicemix.jms.endpoints.DestinationChooser Specifies a class implementing logic for choosing the destination used to send messages.
destinationName java.lang.String Specifies a string identifying the JMS destination used to send messages. The destination is resolved using the <code>DesitinationResolver</code>.
destinationResolver org.springframework.jms.support.destination.DestinationResolver Specifies the class implementing logic for converting strings into destinations. The default is <code>DynamicDestinationResolver</code>.
endpoint java.lang.String <p> Get the endpoint implementation. </p>
explicitQosEnabled boolean Specifies if the QoS values specified for the endpoint are explicitly used when a messages is sent. The default is <code>false</code>.
interfaceName javax.xml.namespace.QName <p> Get the qualified name of the endpoint interface. </p>
jms102 boolean Determines if the provider used JMS 1.0.2 compliant APIs.
marshaler org.apache.servicemix.jms.endpoints.JmsProviderMarshaler Specifies the class implementing the message marshaler. The message marshaller is responsible for marshalling and unmarshalling JMS messages. The default is <code>DefaultProviderMarshaler</code>.
messageIdEnabled boolean Specifies if your endpoint requires JMS message IDs. Setting the <code>messageIdEnabled</code> property to <code>false</code> causes the endpoint to call its message producer's <code>setDisableMessageID() </code> with a value of <code>true</code>. The JMS broker is then given a hint that it does not need to generate message IDs or add them to the messages from the endpoint. The JMS broker can choose to accept the hint or ignore it.
messageTimestampEnabled boolean Specifies if your endpoints requires time stamps on its messages. Setting the <code>messageTimeStampEnabled</code> property to <code>false</code> causes the endpoint to call its message producer's <code>setDisableMessageTimestamp() </code> method with a value of <code>true</code>. The JMS broker is then given a hint that it does not need to generate message IDs or add them to the messages from the endpoint. The JMS broker can choose to accept the hint or ignore it.
preserveMessageQos boolean Specifies whether we want to send message using the QoS settings specified on the message instead in order to preserve message QoS. The default is <code>false</code>.
priority int Specifies the priority assigned to the JMS messages. Defaults to 4.
pubSubDomain boolean Specifies if the destination is a topic. <code>true</code> means the destination is a topic. <code>false</code> means the destination is a queue.
pubSubNoLocal boolean Specifies if messages published by the listener's <code>Connection</code> are suppressed. The default is <code>false</code>.
receiveTimeout long Specifies the timeout for receiving a message in milliseconds.
replyDestination javax.jms.Destination Sets the reply destination. This JMS destination will be used as the default destination for the response messages when using an InOut JBI exchange. It will be used if the <code>replyDestinationChooser</code> does not return any value.
replyDestinationChooser org.apache.servicemix.jms.endpoints.DestinationChooser Specifies a class implementing logic for choosing the destination used to recieve replies.
replyDestinationName java.lang.String Sets the name of the reply destination. This property will be used to create the <code>replyDestination</code> using the <code>destinationResolver</code> when the endpoint starts if the <code>replyDestination</code> has not been set.
service javax.xml.namespace.QName <p> Get the service qualified name of the endpoint. </p>
store org.apache.servicemix.store.Store Sets the store used to store JBI exchanges that are waiting for a response JMS message. The store will be automatically created if not set.
storeFactory org.apache.servicemix.store.StoreFactory Sets the store factory used to create the store. If none is set, a {@link MemoryStoreFactory} will be created and used instead.
timeToLive long Specifies the number of milliseconds a message is valid.

jms:soap-consumer

Endpoint properties

Property Name Type Description
cacheLevel int Specifies the level of caching allowed by the listener. Valid values are 0 through 3. The values map to the following: <ul> <li>0 - <code>CACHE_NONE</code></li> <li>1 - <code>CACHE_CONNECTION</code></li> <li>2 - <code>CACHE_SESSION</code></li> <li>3 - <code>CACHE_CONSUMER</code></li> </ul> The default is <code>CACHE_NONE</code>.<br/> This property only effects consumers whose <code>listenerType</code> property is set to <code>default</code>.
clientId java.lang.String Specifies the JMS client id for a shared <code>Connection</code> created and used by this listener.
component org.apache.servicemix.common.DefaultComponent
concurrentConsumers int Specifies the number of concurrent consumers created by the listener. This property is only used for consumers whose <code>listenerType</code> property is set to either <code>simple</code> or <code>default</code>.
connectionFactory javax.jms.ConnectionFactory Specifies the <code>ConnectionFactory</code> used by the endpoint.
destination javax.jms.Destination Specifies the JMS <code>Destination</code> used to receive messages.
destinationChooser org.apache.servicemix.jms.endpoints.DestinationChooser Specifies a class implementing logic for choosing reply destinations.
destinationName java.lang.String Specifies a string identifying the JMS destination used to recieve messages. The destination is resolved using the <code>DesitinationResolver</code>.
destinationResolver org.springframework.jms.support.destination.DestinationResolver Specifies the class implementing logic for converting strings into destinations. The default is <code>DynamicDestinationResolver</code>.
durableSubscriptionName java.lang.String Specifies the name used to register the durable subscription.
endpoint java.lang.String <p> Get the endpoint implementation. </p>
exceptionListener javax.jms.ExceptionListener Specifies an <code>ExceptionListener</code> to notify in case of a <code>JMSException</code> is thrown by the registered message listener or the invocation infrastructure.
idleTaskExecutionLimit int Specifies the limit for idle executions of a receive task, not having received any message within its execution. If this limit is reached, the task will shut down and leave receiving to other executing tasks (in case of dynamic scheduling; see the "maxConcurrentConsumers" setting). Within each task execution, a number of message reception attempts (according to the "maxMessagesPerTask" setting) will each wait for an incoming message (according to the "receiveTimeout" setting). If all of those receive attempts in a given task return without a message, the task is considered idle with respect to received messages. Such a task may still be rescheduled; however, once it reached the specified "idleTaskExecutionLimit", it will shut down (in case of dynamic scaling). Raise this limit if you encounter too frequent scaling up and down. With this limit being higher, an idle consumer will be kept around longer, avoiding the restart of a consumer once a new load of messages comes in. Alternatively, specify a higher "maxMessagePerTask" and/or "receiveTimeout" value, which will also lead to idle consumers being kept around for a longer time (while also increasing the average execution time of each scheduled task).

jms:soap-provider

Endpoint properties

Property Name Type Description
connectionFactory javax.jms.ConnectionFactory Specifies the <code>ConnectionFactory</code> used by the endpoint.
deliveryMode int Specifies the JMS delivery mode used for the reply. Defaults to (2)(<code>PERSISTENT</code>).
destination javax.jms.Destination Specifies the JMS <code>Destination</code> used to send messages.
destinationChooser org.apache.servicemix.jms.endpoints.DestinationChooser Specifies a class implementing logic for choosing the destination used to send messages.
destinationName java.lang.String Specifies a string identifying the JMS destination used to send messages. The destination is resolved using the <code>DesitinationResolver</code>.
destinationResolver org.springframework.jms.support.destination.DestinationResolver Specifies the class implementing logic for converting strings into destinations. The default is <code>DynamicDestinationResolver</code>.
endpoint java.lang.String <p> Get the endpoint implementation. </p>
explicitQosEnabled boolean Specifies if the QoS values specified for the endpoint are explicitly used when a messages is sent. The default is <code>false</code>.
interfaceName javax.xml.namespace.QName <p> Get the qualified name of the endpoint interface. </p>
jms102 boolean Determines if the provider used JMS 1.0.2 compliant APIs.
marshaler org.apache.servicemix.jms.endpoints.JmsProviderMarshaler Specifies the class implementing the message marshaler. The message marshaller is responsible for marshalling and unmarshalling JMS messages. The default is <code>DefaultProviderMarshaler</code>.
messageIdEnabled boolean Specifies if your endpoint requires JMS message IDs. Setting the <code>messageIdEnabled</code> property to <code>false</code> causes the endpoint to call its message producer's <code>setDisableMessageID() </code> with a value of <code>true</code>. The JMS broker is then given a hint that it does not need to generate message IDs or add them to the messages from the endpoint. The JMS broker can choose to accept the hint or ignore it.
messageTimestampEnabled boolean Specifies if your endpoints requires time stamps on its messages. Setting the <code>messageTimeStampEnabled</code> property to <code>false</code> causes the endpoint to call its message producer's <code>setDisableMessageTimestamp() </code> method with a value of <code>true</code>. The JMS broker is then given a hint that it does not need to generate message IDs or add them to the messages from the endpoint. The JMS broker can choose to accept the hint or ignore it.
policies (org.apache.servicemix.soap.api.Policy)\* Specifies an array of interceptors used to process SOAP messages.
preserveMessageQos boolean Specifies whether we want to send message using the QoS settings specified on the message instead in order to preserve message QoS. The default is <code>false</code>.
priority int Specifies the priority assigned to the JMS messages. Defaults to 4.
pubSubDomain boolean Specifies if the destination is a topic. <code>true</code> means the destination is a topic. <code>false</code> means the destination is a queue.
pubSubNoLocal boolean Specifies if messages published by the listener's <code>Connection</code> are suppressed. The default is <code>false</code>.
receiveTimeout long Specifies the timeout for receiving a message in milliseconds.
replyDestination javax.jms.Destination Sets the reply destination. This JMS destination will be used as the default destination for the response messages when using an InOut JBI exchange. It will be used if the <code>replyDestinationChooser</code> does not return any value.
replyDestinationChooser org.apache.servicemix.jms.endpoints.DestinationChooser Specifies a class implementing logic for choosing the destination used to recieve replies.
replyDestinationName java.lang.String Sets the name of the reply destination. This property will be used to create the <code>replyDestination</code> using the <code>destinationResolver</code> when the endpoint starts if the <code>replyDestination</code> has not been set.
service javax.xml.namespace.QName <p> Get the service qualified name of the endpoint. </p>
store org.apache.servicemix.store.Store Sets the store used to store JBI exchanges that are waiting for a response JMS message. The store will be automatically created if not set.
storeFactory org.apache.servicemix.store.StoreFactory Sets the store factory used to create the store. If none is set, a {@link MemoryStoreFactory} will be created and used instead.
timeToLive long Specifies the number of milliseconds a message is valid.
useJbiWrapper boolean Specifies if the endpoint expects SOAP messages to be wrapped in the JBI wrapper. Defaults to <code>true</code>.
validateWsdl boolean Specifies if the WSDL is checked WSI-BP compliance. Defaults to <code>true</code>.
wsdl org.springframework.core.io.Resource Specifies the WSDL document describing the service's interface.

jms:jca-consumer

Endpoint properties

Property Name Type Description
activationSpec javax.resource.spi.ActivationSpec Specifies the activation information needed by the endpoint.
bootstrapContext javax.resource.spi.BootstrapContext Specifies the <code>BootStrapContext</code> used to start the resource adapter. If this property is not set, a default <code>BootstrpContext</code> will be created.
connectionFactory javax.jms.ConnectionFactory Specifies the <code>ConnectionFactory</code> used by the endpoint.
destinationChooser org.apache.servicemix.jms.endpoints.DestinationChooser Specifies a class implementing logic for choosing reply destinations.
destinationResolver org.springframework.jms.support.destination.DestinationResolver Specifies the class implementing logic for converting strings into destinations. The default is <code>DynamicDestinationResolver</code>.
endpoint java.lang.String <p> Get the endpoint implementation. </p>
interfaceName javax.xml.namespace.QName <p> Get the qualified name of the endpoint interface. </p>
jms102 boolean Specifies if the consumer uses JMS 1.0.2 compliant APIs. Defaults to <code>false</code>.
marshaler org.apache.servicemix.jms.endpoints.JmsConsumerMarshaler Specifies the class implementing the message marshaler. The message marshaller is responsible for marshalling and unmarshalling JMS messages. The default is <code>DefaultConsumerMarshaler</code>.
pubSubDomain boolean Specifies if the destination is a topic. <code>true</code> means the destination is a topic. <code>false</code> means the destination is a queue.
replyDeliveryMode int Specifies the JMS delivery mode used for the reply. Defaults to 2(<code>PERSISTENT</code>).
replyDestination javax.jms.Destination Specifies the JMS <code>Destination</code> for the replies. If this value is not set the endpoint will use the <code>destinationChooser</code> property or the <code>replyDestinationName</code> property to determine the desitination to use.
replyDestinationName java.lang.String Specifies the name of the JMS destination to use for the reply. The actual JMS destination is resolved using the <code>DestinationResolver</code> specified by the <code>.destinationResolver</code> property.
replyExplicitQosEnabled boolean Specifies if the QoS values specified for the endpoint are explicitly used when the reply is sent. The default is <code>false</code>.
replyPriority int Specifies the JMS message priority of the reply. Defaults to 4.
replyProperties java.util.Map Specifies custom properties to be placed in the reply's JMS header.
replyTimeToLive long Specifies the number of milliseconds the reply message is valid. The default is unlimited.
resourceAdapter javax.resource.spi.ResourceAdapter Specifies the resource adapter used for the endpoint.
service javax.xml.namespace.QName <p> Get the service qualified name of the endpoint. </p>
stateless boolean Specifies if the consumer retains state information about the message exchange while it is in process.
store org.apache.servicemix.store.Store Specifies the persistent store used to store JBI exchanges that are waiting to be processed. The store will be automatically created if not set and the endpoint's <code>stateless</code> property is set to <code>false</code>.
storeFactory org.apache.servicemix.store.StoreFactory Specifies the store factory used to create the store. If none is set and the endpoint's <code>stateless</code> property is set to <code>false</code>, a {@link MemoryStoreFactory} will be created and used instead.
synchronous boolean Specifies if the consumer will block while waiting for a response. This means the consumer can only process one message at a time. Defaults to <code>true</code>.
targetEndpoint java.lang.String the name of the endpoint to which requests are sent
targetInterface javax.xml.namespace.QName the QName of the interface to which requests are sent
targetOperation javax.xml.namespace.QName the QName of the operation to which requests are sent
targetService javax.xml.namespace.QName the QName of the service to which requests are sent
targetUri java.lang.String <p> Gets the target URI of the consumer endpoint. </p>
useMessageIdInResponse java.lang.Boolean Specifies if the request message's ID is used as the reply's correlation ID. The default behavior is to use the request's correlation ID. Setting this to <code>true</code> means the request's message ID will be used instead.