<div class="wiki-content maincontent"><h1 id="CodeOverview-Architecture">Architecture</h1>

<p>The following section walks through the main parts of Apache ActiveMQ and links to the code to help you understand the layout</p>

<p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource" src="http://activemq.apache.org/images/BrokerDiagram.png" data-image-src="http://activemq.apache.org/images/BrokerDiagram.png"></span></p>

<h2 id="CodeOverview-JMSClient">JMS Client</h2>

<p>The <a shape="rect" class="external-link" href="http://incubator.apache.org/activemq/maven/activemq-core/apidocs/org/apache/activemq/package-summary.html">org.apache.activemq</a> package defines the core JMS client.</p>

<h2 id="CodeOverview-Transport">Transport</h2>

<p>The JMS client and the message broker use the <a shape="rect" class="external-link" href="http://incubator.apache.org/activemq/maven/activemq-core/apidocs/org/apache/activemq/transport/Transport.html">Transport</a> abstraction for sending around command objects (like a distributed <em>Command Pattern</em>). A TransportChannel typically deals with some kind of networking mechanism (TCP sockets using BIO, using NIO, UDP / multicast, SSL over sockets, JXTA, EmberIO etc). See the <a shape="rect" class="external-link" href="http://incubator.apache.org/activemq/maven/activemq-core/apidocs/org/apache/activemq/transport/package-summary.html">org.apache.activemq.transport</a> package for more details</p>

<p>So the TransportChannel is basically concerned with sending and receiving <a shape="rect" class="external-link" href="http://incubator.apache.org/activemq/maven/activemq-core/apidocs/org/apache/activemq/command/Command.html">Command</a> objects (each instance represents some kind of <em>command</em>). Packet is defined in the <a shape="rect" class="external-link" href="http://incubator.apache.org/activemq/maven/activemq-core/apidocs/org/apache/activemq/command/package-summary.html">org.apache.activemq.command</a> package which defines all the JMS Message implementations classes (which are Commands) along with a number of other kinds of packets, like subsciptions, message acknowledgements, transactions and so forth.</p>

<h2 id="CodeOverview-WireFormat">WireFormat</h2>

<p>There are various possible ways of encoding messages onto a stream. We may wish to adapt to various different encoding mechanisms - such as to provide simpler wire formats for talking to C / JavaScript or to make a C# friendly encoding.</p>

<p>So all the Transport&#160; implementations take a pluggable WireFormat implementation class - which is a <em>Strategy Pattern</em> for deciding how to write the Command to a DataIn / DataOut stream or Datagram.</p>

<p>So if you wish to provide your own binary, <em>on the wire</em> protocol then we just need a WireFormat implementation of your protocol, then we can use this with any transport (TCP BIO, NIO, JXTA etc).</p>

<p>We use <a shape="rect" class="external-link" href="http://incubator.apache.org/activemq/maven/activemq-core/apidocs/org/apache/activemq/openwire/OpenWireFormat.html">OpenWireFormat</a> by default which is the most efficient &amp; easiest format to use from Java code - so if both ends of the wire are Java then its highly recommended. Though other WireFormats are most welcome.</p>

<h2 id="CodeOverview-DefaultWireFormat">Default Wire Format</h2>

<p>The default wire format writes a byte which indicates the kind of Command which is being sent (see the <a shape="rect" class="external-link" href="http://activemq.apache.org/maven/5.5.0/activemq-core/apidocs/org/apache/activemq/command/CommandTypes.html">CommandTypes</a> interface which defines all the int constants for each type of command.</p>

<p>The core JMS Message types each have a unique byte ID for</p>
<ul><li>Message</li><li>ObjectMessage</li><li>TextMessage</li><li>MapMessage</li><li>BytesMessage</li><li>StreamMessage</li></ul>


<p>Then in addition there are various other <a shape="rect" class="external-link" href="http://incubator.apache.org/activemq/maven/activemq-core/apidocs/org/apache/activemq/command/package-summary.html">types of command</a> such as</p>
<ul><li><a shape="rect" class="external-link" href="http://incubator.apache.org/activemq/maven/activemq-core/apidocs/org/apache/activemq/command/ConnectionInfo.html">ConnectionInfo </a> for when a new connection is established with a message broker</li><li><a shape="rect" class="external-link" href="http://incubator.apache.org/activemq/maven/activemq-core/apidocs/org/apache/activemq/command/ConsumerInfo.html">ConsumerInfo</a> when a new consumer is created on a connection</li><li><a shape="rect" class="external-link" href="http://incubator.apache.org/activemq/maven/activemq-core/apidocs/org/apache/activemq/command/MessageAck.html">MessageAck</a> to acknowledge a message ID</li><li><a shape="rect" class="external-link" href="http://incubator.apache.org/activemq/maven/activemq-core/apidocs/org/apache/activemq/command/TransactionInfo.html">TransactionInfo</a> to denote a transaction</li></ul>


<p>There are a few others; the <a shape="rect" class="external-link" href="http://incubator.apache.org/activemq/maven/activemq-core/apidocs/org/apache/activemq/command/package-summary.html">org.apache.activemq.command</a> package describes them in their gory detail.</p>

<p>Basically the DefaultWireFormat has a default encoding of each of these commands. So after the first byte which indicates the type of packet is written, there is a specific wire format per packet type.</p>

<p>For new wire formats it may be that you only need to support a small subset of these types. e.g. you might just have a simple publish message, consume message &amp; message ack.</p>

<h1 id="CodeOverview-MessageBroker">Message Broker</h1>

<p>The APIs for the message broker (server side of the JMS client) are defined in the <a shape="rect" class="external-link" href="http://incubator.apache.org/activemq/maven/activemq-core/apidocs/org/apache/activemq/broker/package-summary.html">org.apache.activemq.broker</a>. There are various other packages which define different parts, from the message stores to the message routing and so forth. </p>

<p>To see an overview of these packages try the <a shape="rect" href="javadocs.html">JavaDocs</a></p>

<hr>

<p></p><p>
</p><h1>ActiveMQ System Overview</h1>

<h2>Introduction</h2>

<p>ActiveMQ is the system responsible for creating and managing network connections used for communication between clients and the broker. This document hopes to outline the inner workings of this system with in order to make it easier to understand for future developers. It will give a high-level overview of the system and outline the major players. We will also cover a few other interesting classes that may be useful to others working on the system. Most of this document is written with the server side code in mind. This is because the client-side communication systems are architecturally simple and understanding the server will make understanding clients trivial by comparison.</p>

<p>We assume the reader has basic understanding of JMS. Refer to the official Java docs for more information.</p>

<h2>Overview: The Big Players</h2>

<p>The core classes involved in the ActiveMQ communication system are Transports. These include the <code>Transport</code>, <code>TransportServer</code>, and <code>TransportFactory</code> hierarchies. <code>Transport</code>s and <code>TransportServer</code>s are wrappers around sockets and server sockets respectively. <code>TransportFactory</code>s (as you may have guessed) are factories that create <code>Transport</code>s and <code>TransportServers</code>. <code>Transport</code>s are connected to <code>Broker</code>s and transmit <code>Command</code>s, which represent all major actions to be taken by ActiveMQ (more on this later). The following example illustrates how these pieces fit together.</p>

<p>The primary class needed to create a JMS "provider" application is the <code>Broker</code> class. The default ActiveMQ binary will use a <code>BrokerService</code> class to wrap around <code>Broker</code>s. When the application is started, it instantiates a <code>BrokerService</code> and instructs it to bind to a specific (local) address, say "tcp://localhost:61616". The <code>Broker</code> will use the scheme in the given address and find the proper <code>TransportFactory</code>, <code>TcpTransportFactory</code> in this example. This factory will then be used to create a <code>TcpTransportServer</code> that will be bound to "localhost:61616". Once the <code>TransportServer</code> is started, it will continually pole its socket for incoming connections. Successfully connected incoming sockets will be wrapped in a <code>TcpTransport</code> instance and passed back (indirectly) to the <code>Broker</code>. The <code>Broker</code> will then start polling the new <code>Transport</code> for incoming <code>Command</code>s to process.</p>

<p>The final pieces missing from the above example are the <code>TransportConnection</code> and <code>TransportConnector</code> classes. These classes are used to connect <code>Broker</code>s to <code>Transport</code>s and <code>TransportServer</code>s respectively.</p>

<h2>Class Details</h2>

<p>This section will explain some of the more interesting details of the mentioned classes separately.

</p><h3>Transports, TransportServers, and TransportFactories</h3>

<p>The basic principles of how these classes operate are very simple: <code>Transport</code>s and <code>TransportServer</code>s are wrappers around sockets and server sockets used to hide implementation, and <code>TransportFactory</code>s are factory classes for the mentioned classes. The only caveats are how <code>TransportFactory</code>s are chosen and configured based on URIs they are supplied.</p>

<p>The <code>TransportFactory</code> class is abstract and incapable of creating <code>Transport</code> or <code>TransportServer</code> classes directly. It, nevertheless, is the class used to create <code>Transport</code>s and <code>TransportServer</code>s. <code>TransportFactory</code> delegates its responsibilities to its subclasses based on the choice of subclass provided by the <code>FactoryFinder</code> class, which uses the URI's scheme to find a matching factory classes based on text files stored under the META-INF directory.</p>

<p>Configuration of the created <code>Transport</code>s is done entirely to reflection. <code>Transport</code>s are configured through calls to <code>compositeConfigure</code>, which are made by the factory at the time of the <code>Transport</code>'s creation. <code>compositeConfigure</code> uses the <code>IntrospectionSupport</code> class to call setters for parameters passed in through the URI. For example, creating a <code>Transport</code> using the URI "ssl://localhost:61616/?needClientAuth=true" would result in the creation of an <code>SslTransport</code> object whose <code>setNeedClientAuth</code> method (if it exists) is called with the value of <code>true</code> immediately after its creation. <code>TransportServer</code>s operate in a similar fashion. The only difference is that the call to <code>IntrospectionSupport</code> is made from the <code>doBind</code> method of the <code>TransportFactory</code>.</p>

<h3>Commands</h3>

<p><code>Command</code>s are the main means for communication within <code>Broker</code>s. Each <code>Command</code> represents an action to be taken. <code>Command</code> subclasses include <code>ConnectionInfo</code>, <code>KeepAliveInfo</code>, and <code>Message</code>, which result in processing of new connections, maintenance of old connections, and processing of user messages respectively. These classes are de-serialized from <code>Transport</code>s using Marshalers. Whenever new data is found in a socket, the first byte is read to determine what type of <code>Command</code> being received. The proper Marshaller is then selected to de-serialize the <code>Command</code> (e.g. to de-serialize a <code>ConnectionInfo</code>, the <code>ConnectionInfoMarshaller</code> is used).</p>

<h3>TransportConnections and TransportConnectors</h3>

<p>Every <code>TransportServer</code> is connected to a <code>Broker</code> using a <code>TransportConnector</code>. The server's accept listener (which is called when a new <code>Transport</code> is constructed) is set to call the given <code>TransportConnector</code>'s <code>createConnection</code> method with the new <code>Transport</code>. When called, <code>createConnection</code> creates a new <code>TransportConnection</code> that links the given <code>Transport</code> and the supporting <code>Broker</code> together; the <code>Transport</code>'s transport listener is set to the <code>TransportConnection</code>'s <code>onCommand</code> method, which is then called whenever a new <code>Command</code> is received.</p>

<p><code>Command</code>s and <code>AbstractConnection</code> (the superclass of <code>TransportConnection</code>) form a visitor pattern. <code>onCommand</code> will call <code>AbstractConnection</code>'s service method which will make a series of calls in line with the visitor patter and eventually, the proper <code>Command</code> subclass to be passed to the corresponding method of the <code>Broker</code> for processing.</p>

<h3>BrokerFilters and BrokerPlugins</h3>

<p>While not used directly by the communication system, <code>BrokerFilter</code>s and <code>BrokerPlugin</code>s provide an effective and easy to use way of modifying Broker behavior. <code>BrokerFilter</code>s allow for one to modify a few <code>Broker</code> methods without touching the rest (as the name suggests). The <code>BrokerFilter</code> passes on all of its responsibilities to a <code>Broker</code> it receives in its constructor. Subclassing <code>BrokerFilter</code> allows us to perform additional actions before passing the work down to the underlying <code>Broker</code>.</p>

<p>The power of the <code>BrokerFilter</code> class comes from the fact that multiple filters can be cascaded to create different functional combinations. As an example, the <code>JaasAuthenticationBroker</code> is a subclass of <code>BrokerFilter</code> that modifies the methods used for adding and removing connections to allow for JAAS authentication. <code>AuthorizationBroker</code> is another subclass of <code>BrokerFilter</code>. This class modifies the destination regulation methods to enforce access levels. With this architecture, one can create a <code>JaasAuthenticationBroker</code> and have it use an <code>AuthorizationBroker</code> as its underlying broker (which would use another broker itself, etc.).</p>

<p><code>BrokerPlugin</code>s are simple classes that will wrap their corresponding <code>Brokers</code> around the one they are given. i.e. "installing" an <code>AuthorizationPlugin</code> on an existing <code>Broker</code> will create an <code>AuthorizationBroker</code> that uses the original <code>Broker</code> internally. The main reason for the existence of <code>BrokerPlugin</code>s is to allow for one to configure the <code>Broker</code> used by the <code>BrokerService</code> class (either through code or XML configuration and spring).</p>
<p></p></div>