213 lines
9.6 KiB
Markdown
213 lines
9.6 KiB
Markdown
# Core Bridges
|
|
|
|
The function of a bridge is to consume messages from a source queue, and
|
|
forward them to a target address, typically on a different Apache ActiveMQ
|
|
Artemis server.
|
|
|
|
The source and target servers do not have to be in the same cluster which makes
|
|
bridging suitable for reliably sending messages from one cluster to another,
|
|
for instance across a WAN, or internet and where the connection may be
|
|
unreliable.
|
|
|
|
The bridge has built in resilience to failure so if the target server
|
|
connection is lost, e.g. due to network failure, the bridge will retry
|
|
connecting to the target until it comes back online. When it comes back online
|
|
it will resume operation as normal.
|
|
|
|
In summary, bridges are a way to reliably connect two separate Apache ActiveMQ
|
|
Artemis servers together. With a core bridge both source and target servers
|
|
must be Apache ActiveMQ Artemis servers.
|
|
|
|
Bridges can be configured to provide *once and only once* delivery guarantees
|
|
even in the event of the failure of the source or the target server. They do
|
|
this by using duplicate detection (described in [Duplicate
|
|
Detection](duplicate-detection.md)).
|
|
|
|
> **Note:**
|
|
>
|
|
> Although they have similar function, don't confuse core bridges with JMS
|
|
> bridges!
|
|
>
|
|
> Core bridges are for linking an Apache ActiveMQ Artemis node with another
|
|
> Apache ActiveMQ Artemis node and do not use the JMS API. A JMS Bridge is used
|
|
> for linking any two JMS 1.1 compliant JMS providers. So, a JMS Bridge could
|
|
> be used for bridging to or from different JMS compliant messaging system.
|
|
> It's always preferable to use a core bridge if you can. Core bridges use
|
|
> duplicate detection to provide *once and only once* guarantees. To provide
|
|
> the same guarantee using a JMS bridge you would have to use XA which has a
|
|
> higher overhead and is more complex to configure.
|
|
|
|
## Configuring Bridges
|
|
|
|
Bridges are configured in `broker.xml`. Let's kick off with an example (this is
|
|
actually from the bridge example):
|
|
|
|
```xml
|
|
<bridge name="my-bridge">
|
|
<queue-name>sausage-factory</queue-name>
|
|
<forwarding-address>mincing-machine</forwarding-address>
|
|
<filter string="name='aardvark'"/>
|
|
<transformer-class-name>
|
|
org.apache.activemq.artemis.jms.example.HatColourChangeTransformer
|
|
</transformer-class-name>
|
|
<retry-interval>1000</retry-interval>
|
|
<ha>true</ha>
|
|
<retry-interval-multiplier>1.0</retry-interval-multiplier>
|
|
<initial-connect-attempts>-1</initial-connect-attempts>
|
|
<reconnect-attempts>-1</reconnect-attempts>
|
|
<failover-on-server-shutdown>false</failover-on-server-shutdown>
|
|
<use-duplicate-detection>true</use-duplicate-detection>
|
|
<confirmation-window-size>10000000</confirmation-window-size>
|
|
<user>foouser</user>
|
|
<password>foopassword</password>
|
|
<static-connectors>
|
|
<connector-ref>remote-connector</connector-ref>
|
|
</static-connectors>
|
|
<!-- alternative to static-connectors
|
|
<discovery-group-ref discovery-group-name="bridge-discovery-group"/>
|
|
-->
|
|
</bridge>
|
|
```
|
|
|
|
In the above example we have shown all the parameters its possible to configure
|
|
for a bridge. In practice you might use many of the defaults so it won't be
|
|
necessary to specify them all explicitly.
|
|
|
|
Let's take a look at all the parameters in turn:
|
|
|
|
- `name` attribute. All bridges must have a unique name in the server.
|
|
|
|
- `queue-name`. This is the unique name of the local queue that the bridge
|
|
consumes from, it's a mandatory parameter.
|
|
|
|
The queue must already exist by the time the bridge is instantiated at
|
|
start-up.
|
|
|
|
- `forwarding-address`. This is the address on the target server that the
|
|
message will be forwarded to. If a forwarding address is not specified, then
|
|
the original address of the message will be retained.
|
|
|
|
- `filter-string`. An optional filter string can be supplied. If specified then
|
|
only messages which match the filter expression specified in the filter
|
|
string will be forwarded. The filter string follows the ActiveMQ Artemis filter
|
|
expression syntax described in [Filter Expressions](filter-expressions.md).
|
|
|
|
- `transformer-class-name`. An optional transformer-class-name can be
|
|
specified. This is the name of a user-defined class which implements the
|
|
`org.apache.activemq.artemis.core.server.transformer.Transformer` interface.
|
|
|
|
If this is specified then the transformer's `transform()` method will be
|
|
invoked with the message before it is forwarded. This gives you the opportunity
|
|
to transform the message's header or body before forwarding it.
|
|
|
|
- `ha`. This optional parameter determines whether or not this bridge should
|
|
support high availability. True means it will connect to any available server
|
|
in a cluster and support failover. The default value is `false`.
|
|
|
|
- `retry-interval`. This optional parameter determines the period in
|
|
milliseconds between subsequent reconnection attempts, if the connection to
|
|
the target server has failed. The default value is `2000`milliseconds.
|
|
|
|
- `retry-interval-multiplier`. This optional parameter determines determines a
|
|
multiplier to apply to the time since the last retry to compute the time to
|
|
the next retry.
|
|
|
|
This allows you to implement an *exponential backoff* between retry
|
|
attempts.
|
|
|
|
Let's take an example:
|
|
|
|
If we set `retry-interval`to `1000` ms and we set `retry-interval-multiplier`
|
|
to `2.0`, then, if the first reconnect attempt fails, we will wait `1000` ms
|
|
then `2000` ms then `4000` ms between subsequent reconnection attempts.
|
|
|
|
The default value is `1.0` meaning each reconnect attempt is spaced at equal
|
|
intervals.
|
|
|
|
- `initial-connect-attempts`. This optional parameter determines the total
|
|
number of initial connect attempts the bridge will make before giving up and
|
|
shutting down. A value of `-1` signifies an unlimited number of attempts. The
|
|
default value is `-1`.
|
|
|
|
- `reconnect-attempts`. This optional parameter determines the total number of
|
|
reconnect attempts the bridge will make before giving up and shutting down. A
|
|
value of `-1` signifies an unlimited number of attempts. The default value is
|
|
`-1`.
|
|
|
|
- `failover-on-server-shutdown`. This optional parameter determines whether the
|
|
bridge will attempt to failover onto a backup server (if specified) when the
|
|
target server is cleanly shutdown rather than crashed.
|
|
|
|
The bridge connector can specify both a live and a backup server, if it
|
|
specifies a backup server and this parameter is set to `true` then if the
|
|
target server is *cleanly* shutdown the bridge connection will attempt to
|
|
failover onto its backup. If the bridge connector has no backup server
|
|
configured then this parameter has no effect.
|
|
|
|
Sometimes you want a bridge configured with a live and a backup target
|
|
server, but you don't want to failover to the backup if the live server is
|
|
simply taken down temporarily for maintenance, this is when this parameter
|
|
comes in handy.
|
|
|
|
The default value for this parameter is `false`.
|
|
|
|
- `use-duplicate-detection`. This optional parameter determines whether the
|
|
bridge will automatically insert a duplicate id property into each message
|
|
that it forwards.
|
|
|
|
Doing so, allows the target server to perform duplicate detection on messages
|
|
it receives from the source server. If the connection fails or server crashes,
|
|
then, when the bridge resumes it will resend unacknowledged messages. This
|
|
might result in duplicate messages being sent to the target server. By enabling
|
|
duplicate detection allows these duplicates to be screened out and ignored.
|
|
|
|
This allows the bridge to provide a *once and only once* delivery guarantee
|
|
without using heavyweight methods such as XA (see [Duplicate
|
|
Detection](duplicate-detection.md) for more information).
|
|
|
|
The default value for this parameter is `true`.
|
|
|
|
- `confirmation-window-size`. This optional parameter determines the
|
|
`confirmation-window-size` to use for the connection used to forward messages
|
|
to the target node. This attribute is described in section [Reconnection and
|
|
Session Reattachment](client-reconnection.md)
|
|
|
|
> **Warning**
|
|
>
|
|
> When using the bridge to forward messages to an address which uses the
|
|
> `BLOCK` `address-full-policy` from a queue which has a `max-size-bytes` set
|
|
> it's important that `confirmation-window-size` is less than or equal to
|
|
> `max-size-bytes` to prevent the flow of messages from ceasing.
|
|
|
|
- `producer-window-size`. This optional parameter determines the producer flow
|
|
control through the bridge. You usually leave this off unless you are dealing
|
|
with huge large messages.
|
|
|
|
Default=-1 (disabled)
|
|
|
|
- `user`. This optional parameter determines the user name to use when creating
|
|
the bridge connection to the remote server. If it is not specified the
|
|
default cluster user specified by `cluster-user` in `broker.xml` will be used.
|
|
|
|
- `password`. This optional parameter determines the password to use when
|
|
creating the bridge connection to the remote server. If it is not specified
|
|
the default cluster password specified by `cluster-password` in `broker.xml`
|
|
will be used.
|
|
|
|
- `static-connectors` or `discovery-group-ref`. Pick either of these options to
|
|
connect the bridge to the target server.
|
|
|
|
The `static-connectors` is a list of `connector-ref` elements pointing to
|
|
`connector` elements defined elsewhere. A *connector* encapsulates knowledge of
|
|
what transport to use (TCP, SSL, HTTP etc) as well as the server connection
|
|
parameters (host, port etc). For more information about what connectors are and
|
|
how to configure them, please see [Configuring the
|
|
Transport](configuring-transports.md).
|
|
|
|
The `discovery-group-ref` element has one attribute - `discovery-group-name`.
|
|
This attribute points to a `discovery-group` defined elsewhere. For more
|
|
information about what discovery-groups are and how to configure them, please
|
|
see [Discovery Groups](clusters.md).
|
|
|
|
|