extending-guide.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd">  <html lang="en"> <head> <meta content="text/html; charset=utf-8" http-equiv="Content-Type"/> <meta content="ActiveMQ's next generation of messaging" name="description"/> <meta content="messaging,stomp,jms,activemq,apollo" name="keywords"/> <meta content="Apollo" name="author"/> <script src="../scripts/jquery.js"></script> <link type="text/css" rel="stylesheet" href="../styles/impact/css/pygmentize.css"/> <link type="text/css" rel="stylesheet" href="../styles/impact/css/site.css"/> <title></title> </head> <body> <div id="navigation"> <div class="wrapper"> <ul> <li><a href="../index.html">Apollo 1.7.1</a></li> <li><a href="../community/developers.html">Developers</a></li> <li><a href="../community/index.html">Community</a></li> <li><a href="../download.html">Download</a></li> </ul> <div></div> </div> </div> <div id="content"> <div class="wrapper"> <h1 id = "Apollo_1_7_1_Extending_Guide">Apollo 1.7.1 Extending Guide</h1> <p><div class="toc"><ul style="list-style:none;"> <li><a href="#Overview">Overview</a></li> <li><ul style="list-style:none;"> <li><a href="#Adding_your_Extensions_to_the_Apollo_Class_Path">Adding your Extensions to the Apollo Class Path</a></li> <li><a href="#Extension_Discovery">Extension Discovery</a></li> <li><a href="#Extending_the_Data_Model">Extending the Data Model</a></li> <li><ul style="list-style:none;"> <li><a href="#Polymorphic_Data_Configuraiton_objects_Objects">Polymorphic Data/Configuraiton objects Objects</a></li> </ul></li> <li><a href="#Using_a_custom__code_VirtualHost__code__implementation">Using a custom <code>VirtualHost</code> implementation</a></li> <li><a href="#Plugging_into_the_Broker_Lifecycle">Plugging into the Broker Lifecycle</a></li> </ul></li> </ul></div></p> <h2 id = "Overview">Overview</h2> <p>Apollo support being extended in several ways. This guide documents all the supported extension points.</p> <h3 id = "Adding_your_Extensions_to_the_Apollo_Class_Path">Adding your Extensions to the Apollo Class Path</h3> <p>Just create a <code>.jar</code> out of out code and add it to the <code>${apollo.home}/lib</code> directory. When Apollo restarts it will add the new jar to it's class path.</p> <h3 id = "Extension_Discovery">Extension Discovery</h3> <p>Apollo discovers your extensions by looking for extension resource files in all the jar files in it's classpath. For example, the <code>apollo-broker</code> jar file contains the following a resource file <code>META-INF/services/org.apache.activemq.apollo/protocol-codec-factory.index</code> It contains the class names of the protocol codec factories that are implemented in the <code>broker-core</code> module. It's contents are:</p> <pre><code>org.apache.activemq.apollo.broker.protocol.AnyProtocolFactory org.apache.activemq.apollo.broker.protocol.UdpProtocolFactory org.apache.activemq.apollo.broker.protocol.RawProtocolFactory</code></pre> <p>All three of the the listed classes implement the <a href="api/apollo-broker/index.html#org.apache.activemq.apollo.broker.protocol.ProtocolFactory"><code>ProtocolFactory</code></a> interface. Here's a list of extension points supported by Apollo:</p> <ul> <li><p>Data Model: <code>META-INF/services/org.apache.activemq.apollo/dto-module.index</code> → <a href="api/apollo-util/index.html#org.apache.activemq.apollo.util.DtoModule"><code>org.apache.activemq.apollo.util.DtoModule</code></a></p></li> <li><p>Transports: <code>META-INF/services/org.apache.activemq.apollo/transport-factory.index</code> → <a href="api/apollo-broker/index.html#org.apache.activemq.apollo.broker.transport.TransportFactory$$Provider"><code>org.apache.activemq.apollo.broker.transport.TransportFactory.Provider</code></a></p></li> <li><p>Protocols: <code>META-INF/services/org.apache.activemq.apollo/protocol-factory.index</code> → <a href="api/apollo-broker/index.html#org.apache.activemq.apollo.broker.protocol.ProtocolFactory"><code>org.apache.activemq.apollo.broker.protocol.ProtocolFactory</code></a></p></li> <li><p>Broker Factories: <code>META-INF/services/org.apache.activemq.apollo/broker-factory.index</code> → <a href="api/apollo-broker/index.html#org.apache.activemq.apollo.broker.BrokerFactoryTrait"><code>org.apache.activemq.apollo.broker.BrokerFactoryTrait</code></a></p></li> <li><p>Connectors: <code>META-INF/services/org.apache.activemq.apollo/connector-factory.index</code> → <a href="api/apollo-broker/index.html#org.apache.activemq.apollo.broker.ConnectorFactory"><code>org.apache.activemq.apollo.broker.ConnectorFactory</code></a></p></li> <li><p>Virtual Hosts: <code>META-INF/services/org.apache.activemq.apollo/virtual-host-factory.index</code> → <a href="api/apollo-broker/index.html#org.apache.activemq.apollo.broker.VirtualHostFactory"><code>org.apache.activemq.apollo.broker.VirtualHostFactory</code></a></p></li> <li><p>Route Listeners: <code>META-INF/services/org.apache.activemq.apollo/router-listener-factory.index</code> → <a href="api/apollo-broker/index.html#org.apache.activemq.apollo.broker.RouterListenerFactory"><code>org.apache.activemq.apollo.broker.RouterListenerFactory</code></a></p></li> <li><p>Stores: <code>META-INF/services/org.apache.activemq.apollo/store-factory.index</code> → <a href="api/apollo-broker/index.html#org.apache.activemq.apollo.broker.store.StoreFactory"><code>org.apache.activemq.apollo.broker.store.StoreFactory</code></a></p></li> <li><p>Web Admin Components: <code>META-INF/services/org.apache.activemq.apollo/web-module.index</code> → <code>org.apache.activemq.apollo.web.WebModule</code></p></li> <li><p>Web Servers → <code>META-INF/services/org.apache.activemq.apollo/web-server-factory.index</code>→ <a href="api/apollo-broker/index.html#org.apache.activemq.apollo.broker.web.WebServerFactory"><code>org.apache.activemq.apollo.broker.web.WebServerFactory</code></a></p></li> </ul>  <h3 id = "Extending_the_Data_Model">Extending the Data Model</h3> <p>If you want to extend the Apollo xml configuration model to understand some custom JAXB object you have defined in your own packages, then you need to implement a <code>Module</code> class and then create a <code>META-INF/services/org.apache.activemq.apollo/dto-module.index</code> resource file in which you list it's class name.</p> <p>Example module class:</p> <div class="syntax"><pre name='code' class='brush: scala; gutter: false;'><code> package org.example import org.apache.activemq.apollo.util.DtoModule class Module extends DtoModule { def dto_package = "org.apache.activemq.apollo.broker.store.leveldb.dto" def extension_classes = Array(classOf[LevelDBStoreDTO], classOf[LevelDBStoreStatusDTO]) } </code></pre></div> <p>Example <code>META-INF/services/org.apache.activemq.apollo/dto-module.index</code> resource:</p> <pre><code>org.example.Module</code></pre> <h4 id = "Polymorphic_Data_Configuraiton_objects_Objects">Polymorphic Data/Configuraiton objects Objects</h4> <p>The following objects in the Apollo data model can be extended:</p> <ul> <li><a href="api/apollo-dto/org/apache/activemq/apollo/dto/VirtualHostDTO.html"><code>VirtualHostDTO</code></a></li> <li><a href="api/apollo-dto/org/apache/activemq/apollo/dto/ConnectorTypeDTO.html"><code>ConnectorTypeDTO</code></a></li> <li><a href="api/apollo-dto/org/apache/activemq/apollo/dto/ConnectionStatusDTO.html"><code>ConnectionStatusDTO</code></a></li> <li><a href="api/apollo-dto/org/apache/activemq/apollo/dto/ProtocolDTO.html"><code>ProtocolDTO</code></a></li> <li><a href="api/apollo-dto/org/apache/activemq/apollo/dto/StoreDTO.html"><code>StoreDTO</code></a></li> <li><a href="api/apollo-dto/org/apache/activemq/apollo/dto/StoreStatusDTO.html"><code>StoreStatusDTO</code></a></li> </ul>  <h3 id = "Using_a_custom__code_VirtualHost__code__implementation">Using a custom <code>VirtualHost</code> implementation</h3> <p>Virtual hosts control the lifescycle of destinations and how producers and consumers are connected to those destinations. You can subclass the default virtual host implemenation to override the default behaviour that Apollo provides.</p> <p>To create your own VirtualHost extension, you first extend the <a href="api/apollo-broker/index.html#org.apache.activemq.apollo.broker.VirtualHost"><code>org.apache.activemq.apollo.broker.VirtualHost</code></a> class and override it's implemenation suite your needs. Example:</p> <pre><code>package example; class MyVirtualHost(broker: Broker, id:String) extends VirtualHost(broker, id) { // ... todo: override }</code></pre> <p>Then, to allow an <code>apollo.xml</code> configration file you your extended version of the virtual host you need to extend the <a href="api/apollo-dto/org/apache/activemq/apollo/dto/VirtualHostDTO.html"><code>VirtualHostDTO</code></a> class to define a new XML emlement for your new virtual host type. </p> <pre><code>package example; @XmlRootElement(name = "my_virtual_host") @XmlAccessorType(XmlAccessType.FIELD) class MyVirtualHostDTO extends VirtualHostDTO { // example config attribute @XmlAttribute(name="trace") public Boolean trace; }</code></pre> <p>Since this is extending the data model, we follow the direction in the <a href="#Extending_the_Data_Model">'Extending the Data Model'</a> section of this guide and add a <code>Module</code> class:</p> <pre><code>package example; class Module extends DtoModule { def dto_package = "example" def extension_classes = Array(classOf[MyVirtualHostDTO]) }</code></pre> <p>and a <code>META-INF/services/org.apache.activemq.apollo/dto-module.index</code> resource file containing:</p> <pre><code>example.Module</code></pre> <p>Now that we can define an XML element to configure the custom virtual host and create it, lets define a factory class which will be used to create a <code>MyVirtualHost</code> when a <code><my_virtual_host></code> xml element is used in the configuration file:</p> <pre><code>package example; object MyVirtualHostFactory extends VirtualHostFactory { def create(broker: Broker, dto: VirtualHostDTO): VirtualHost = dto match { case dto:MyVirtualHostDTO => val rc = new MyVirtualHostDTO(broker, dto.id) rc.config = dto rc case _ => null } }</code></pre> <p>and a <code>META-INF/services/org.apache.activemq.apollo/virtual-host-factory.index</code> resource file containing:</p> <pre><code>example.MyVirtualHostFactory</code></pre> <h3 id = "Plugging_into_the_Broker_Lifecycle">Plugging into the Broker Lifecycle</h3> <p>You can implement custom <a href="api/apollo-util/index.html#org.apache.activemq.apollo.util.Service">Service</a> objects which get started / stopped when the broker starts and stops. Once you have packaged your custom service, and added it to the Apollo class path, you can update the <code>apollo.xml</code> to add the service so it gets started when apollo starts:</p> <div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code> <service id='myservice' kind='org.example.MyService'/> </code></pre></div> <p>The <code>id</code> attribute is a unique service name of your service, and the <code>kind</code> attribute is the class name of your service. </p> <p>If your service needs a reference to the Broker object which is running in, add the following field definition to your class:</p> <div class="syntax"><pre name='code' class='brush: scala; gutter: false;'><code> var broker:Broker = null </code></pre></div> <p>The broker instance will be injected into your class instance before it gets started.</p> <p>Your service can also get reference to to the configuration element used to define it if it defines the following field.</p> <div class="syntax"><pre name='code' class='brush: scala; gutter: false;'><code> var config: CustomServiceDTO </code></pre></div> <p>This field will also get injected before getting started. The <code>CustomServiceDTO.other</code> field will contain any additional configuration elements defined within service element. For example, if you configured the service as follows:</p> <div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code> <service id='myservice' kind='org.example.MyService'/> <options xmlns="http://example.org/myservice"> <search>google.com</search> </options> </service> </code></pre></div> <p>Then you could access the options DOM element using:</p> <div class="syntax"><pre name='code' class='brush: scala; gutter: false;'><code> val options = config.other.get(1).asInstanceOf[Element] </code></pre></div> <p>If you had defined JAXB object mappings for the <code><options></code> class then <code>config</code> will hold that object instead of generic DOM <code>Element</code>.</p> <div></div> </div> </div> </body> </html>

extending-guide.html (196 lines of code) (raw):