Network connectors define the broker-to-broker links that are the basis of a broker network. This section defines the basic options for configuring network connectors and explains the concepts that underlie them.

In the context of a broker network, a subscription is a block of data that represents an active consumer's interest in receiving messages on a particular queue or on a particular topic. Brokers use the subscription data to decide what messages to send where. Subscriptions, therefore, encapsulate all of the information that a broker might need to route messages to a consumer, including JMS selectors and which route to take through the broker network.

Subscriptions are inherently dynamic. If a given consumer disconnects from the broker network (thus becoming inactive), its associated subscriptions are automatically cancelled throughout the network.

	Note
	This usage of the term, subscription, deviates from standard JMS terminology, where there can be topic subscriptions but there is no such thing as a queue subscription. In the context of broker networks, however, we speak of both topic subscriptions and queue subscriptions.

Both topic subscriptions and queue subscriptions propagate automatically through a broker network. That is, when a consumer connects to a broker, it passes its subscriptions to the local broker and the local broker then forwards the subscriptions to neighbouring brokers. This process continues until the subscriptions are propagated throughout the broker network.

Under the hood, Fuse Message Broker implements subscription propagation using advisory messages, where an advisory message is a message sent through one of the special channels known as an advisory topic. An advisory topic is essentially a reserved JMS topic used for transmitting administrative messages. All advisory topics have names that start with the prefix, ActiveMQ.Advisory.

Warning

In order for dynamic broker networks to function correctly, it is essential that advisory messages are enabled (which they are by default). Make sure that you do not disable advisory messages on any broker in the network. For example, if you are configuring your brokers using XML, make sure that the advisorySupport attribute on the broker element is not set to false. In principle, it is possible to configure a static broker network when advisory messages are disabled. See Dynamic and Static Propagation for details.

A broker network is built up by defining directed connections from one broker to another, using network connectors. The broker that establishes the connection passes messages to the broker it is connected to. In XML, a network connector is defined using the networkConnector element, which is a child of the networkConnectors element.

Figure 2.1 shows a single network connector from broker A to broker B. The arrow on the connector indicates the direction of message propagation (from A to B). Subscriptions propagate in the opposite direction (from B to A). Because of the restriction on the direction of message flow in this network, it is advisable to connect producers only to broker A and consumers only to broker B. Otherwise, some messages might not be able to reach the intended consumers.

Figure 2.1. Single Connector

<beans ...>
    <broker xmlns="http://activemq.apache.org/schema/core"
            brokerName="brokerA" brokerId="A" ... >
        ...
        <networkConnectors>
            <networkConnector name="linkToBrokerB"
                uri="static:(tcp://localhost:61002)"
                networkTTL="3"
            />            
        </networkConnectors>
        ...
        <transportConnectors>
            <transportConnector name="openwire" uri="tcp://0.0.0.0:61001"/>
        </transportConnectors>
    </broker>
</beans>

Figure 2.1 shows a pair of network connectors in each direction: one from broker A to broker B, and one from broker B to broker A. In this network, there is no restriction on the direction of message flow and messages can propagate freely in either direction. It follows that producers and consumers can arbitrarily connect to either broker in this network.

Figure 2.2. Connectors in Each Direction

<beans ...>
    <broker xmlns="http://activemq.apache.org/schema/core"
            brokerName="brokerB" brokerId="B"... >
        ...
        <networkConnectors>
            <networkConnector name="linkToBrokerA"
                uri="static:(tcp://localhost:61001)"
                networkTTL="3" />            
        </networkConnectors>
        ...
        <transportConnectors>
            <transportConnector name="openwire" uri="tcp://0.0.0.0:61002" />
        </transportConnectors>
    </broker>
</beans>

An easier way to enable message propagation in both directions is by enabling duplex mode on an existing connector. Figure 2.3 shows a duplex network connector defined on broker A (where the dot indicates which broker defines the network connector in the figure). The duplex connector allows messages to propagate in both directions, but only one network connector needs to be defined and only one network connection is created.

Figure 2.3. Duplex Connector

<networkConnectors>
   <networkConnector name="linkToBrokerB"
       uri="static:(tcp://localhost:61002)"
       networkTTL="3"
       duplex="true" />
</networkConnectors>

	Tip
	Duplex mode is particularly useful for cases where a network connection must be established across a firewall, because only one port need be opened on the firewall to enable bi-directional traffic.

	Tip
	Duplex mode works particularly well in a hub and spoke network. The spokes only need to know about one hub port and the hub does not need to know any of the spoke addresses (each spoke opens a duplex network connector to the hub).

It is also possible to establish multiple connectors between brokers, as long as you observe the rule that each connector has a unique name. Figure 2.4 shows an example where three network connectors are established from broker A to broker B.

Figure 2.4. Multiple Connectors

<networkConnectors>
   <networkConnector name="link01ToBrokerB"
       uri="static:(tcp://localhost:61002)"
       networkTTL="3"
   />
   <networkConnector name="link02ToBrokerB"
       uri="static:(tcp://localhost:61002)"
       networkTTL="3"
   />
   <networkConnector name="link03ToBrokerB"
       uri="static:(tcp://localhost:61002)"
       networkTTL="3"
   />
</networkConnectors>

By default, after passing through a network connector, subscriptions to the same queue or subscriptions to the same topic are automatically consolidated into a single subscription known as a conduit subscription. Figure 2.5 shows an overview of how the topic subscriptions from two consumers, C1 and C2, are consolidated into a single conduit subscription after propagating from broker B to broker A.

Figure 2.5. Conduit Subscriptions

It is essential to enable conduit subscription in order to avoid duplication of topic messages. Consider what would happen in Figure 2.5 if conduit subscription was disabled. In this scenario, two subscriptions, B:C1:t and B:C2:t, would be registered in broker A. Now, if a message on topic t is sent to broker A, broker A would send two copies of the message to broker B, to honor the topic subscriptions, B:C1:t and B:C2:t. Broker B would then send two copies of the message to each consumer, to honor the topic subscriptions, C1:t and C2:t. In other words, each consumer would receive the topic message twice.

Conduit subscriptions can optionally be disabled by setting the conduitSubscriptions attribute to false on the networkConnector element. See Balancing Consumer Load for more details.