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 | The name of the endpoint. |
| initialContextFactory | java.lang.String | The class name of the JNDI InitialContextFactory to use. |
| interfaceName | javax.xml.namespace.QName | The qualified name of the interface exposed by the endpoint. |
| 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 | The qualified name of the service the endpoint exposes. |
| 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 | The name of the endpoint. |
| 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 | The name of the endpoint. |
| 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 | The qualified name of the interface exposed by the endpoint. |
| 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 | The qualified name of the service the endpoint exposes. |
| 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 | The name of the endpoint. |
| 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 | The name of the endpoint. |
| 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 | The qualified name of the interface exposed by the endpoint. |
| 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 | The qualified name of the service the endpoint exposes. |
| 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 | The name of the endpoint. |
| interfaceName | javax.xml.namespace.QName | The qualified name of the interface exposed by the endpoint. |
| 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 | The qualified name of the service the endpoint exposes. |
| 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 | Set the target service/endpoint/interface using a URI. |
| 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. |