...
Before diving into the details of send and receive, it is helpful to understand how message buses are configured for an application. Message buses are resources that are shared between applications. In configuration a message buses are defined independently of applications to provide the common connection details and the set of channels that they provide for applications. Applications will reference the buses that they will use to collaborate with other applications along with a subset of the channels that they will work with. Applications work abstractly with buses and channel to send and receive messages, allowing configuration changes at runtime to augment
- The messaging provider (for example to switch from ActiveMQ to Solace)
- The message bus connection details in the form of an address and optionally a port (for example to switch from a message broker in a test environment to one in production).
- Bus connection properties, a combination of properties that are common to all bus providers and configuration specific to the type of bus provider being used.
- Topic structure by modifying the channels' configured keys.
- Application subscriptions by modifying the applications' configured filters.
| Code Block | ||||
|---|---|---|---|---|
| ||||
<model>
<!-- Define buses and channels that will be shared between applications-->
<buses>
<bus name="sample-bus">
<provider>activemq</provider>
<address>localhost</address>
<port>61616</port>
<properties>
<set_key_on_receipt>true</set_key_on_receipt>
<properties>
<channels>
<channel name="new-orders-channel">
<qos>Guaranteed</qos>
<key>NEWORDERS/${Region}/${Department}
</channel>
<channel name="order-events">
<qos>Guaranteed</qos>
<key>ORDEREVENTS/${Region}/${EventType}/${Department}
</channel>
<channels>
</bus>
</buses>
<!-- Apps will reference the buses they use in their messaging config -->
<apps>
<app name="sample-app" mainClass="com.sample.SampleApp">
<messaging>
<factories>
<factory name="com.sample.messages.OrderMessagesFactory" />
</factories>
<buses>
<bus name="sample-bus">
<channel name="new-orders-channel" join="true">
<filter>Region=US|Canada</filter>
</channel>
</bus>
</buses>
<messaging>
</app>
</apps>
</model> |
The above configuration is an example of configuraring a bus in its decomposed prroperty form. A message bus can alternatively be configured using the bus descriptor attribute as shown in the following example.
| Code Block | ||
|---|---|---|
| ||
<buses>
<bus name="sample-bus" descriptor="activemq://localhost:61616&set_key_on_receipt=true">
<channels>
...
</channels>
</bus>
</buses> |
The bus descriptor format is useful in cases where the descriptor name may be supplied as an external configuration property that is substituted. In the following example the bus descriptor defaults to using a loopback bus which is useful for unit testing, and configured with the myBusDescriptor environment property in other environments.
| Code Block | ||
|---|---|---|
| ||
<buses>
<bus name="sample-bus" descriptor="${myBusDescriptor::loopback://mybus">
<channels>
...
</channels>
</bus>
</buses> |
Common Bus Configuration Properties
The follow propeties are common to all bus implementations (unless specifically noted otherwise) and can be specified in a bus descriptor either as parameters in a descriptor url or as properties in the the buses' configuration settings when specified in decomposed form.
| Property Name | Default Value | Description |
|---|---|---|
| set_bus_and_channel_on_receipt | false | Controls whether the bus and channel name are set on received messages. Setting the channel and bus name on inbound messages incurs performance overhead. Performance sensitive applications should avoid enabling this property. |
| set_key_on_receipt | false | Controls whether the message key is set on received messages. Not all binding implementations transport the key on the wire, this property has no effect for binding that don't transport the key. Setting the key on inbound message incurs a performance overhead. Performance sensitive applications should avoid enabling this property. |
| topic_starts_with_channel | false | Controls whether topic names start with the channel name for the bus. For bus bindings that support topic routing this property controls whether or not the resolved key is prefixed with the channel name. |
Most bus implementations support additional properties specifid to the messaging provider. Consult the documentation for the bus provider to learn about the properties it supports.
Sending Messages
Understanding Message Sends
...