# 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):

    <bridge name="my-bridge">
       <queue-name>jms.queue.sausage-factory</queue-name>
       <forwarding-address>jms.queue.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.

    > **Note**
    >
    > If you're using JMS then normally the JMS configuration
    > `activemq-jms.xml` is loaded after the core configuration file
    > `broker.xml` is loaded. If your bridge is
    > consuming from a JMS queue then you'll need to make sure the JMS
    > queue is also deployed as a core queue in the core configuration.
    > Take a look at the bridge example for an example of how this is
    > done.

-   `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.cluster.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).