From commits-return-16771-apmail-activemq-commits-archive=activemq.apache.org@activemq.apache.org Thu Aug 11 17:44:35 2011 Return-Path: X-Original-To: apmail-activemq-commits-archive@www.apache.org Delivered-To: apmail-activemq-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 58DD475DD for ; Thu, 11 Aug 2011 17:44:35 +0000 (UTC) Received: (qmail 2831 invoked by uid 500); 11 Aug 2011 17:44:35 -0000 Delivered-To: apmail-activemq-commits-archive@activemq.apache.org Received: (qmail 2759 invoked by uid 500); 11 Aug 2011 17:44:34 -0000 Mailing-List: contact commits-help@activemq.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@activemq.apache.org Delivered-To: mailing list commits@activemq.apache.org Received: (qmail 2752 invoked by uid 99); 11 Aug 2011 17:44:34 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 11 Aug 2011 17:44:34 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 11 Aug 2011 17:44:32 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id 93DC5238897D for ; Thu, 11 Aug 2011 17:44:13 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1156699 - in /activemq/activemq-apollo/trunk/apollo-website/src/documentation: extending-guide.md index.page Date: Thu, 11 Aug 2011 17:44:13 -0000 To: commits@activemq.apache.org From: chirino@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20110811174413.93DC5238897D@eris.apache.org> Author: chirino Date: Thu Aug 11 17:44:13 2011 New Revision: 1156699 URL: http://svn.apache.org/viewvc?rev=1156699&view=rev Log: Making it possible to configure and update custom services. Also support holding additional configuration elements in key points in the broker configuration model. Added: activemq/activemq-apollo/trunk/apollo-website/src/documentation/extending-guide.md Modified: activemq/activemq-apollo/trunk/apollo-website/src/documentation/index.page Added: activemq/activemq-apollo/trunk/apollo-website/src/documentation/extending-guide.md URL: http://svn.apache.org/viewvc/activemq/activemq-apollo/trunk/apollo-website/src/documentation/extending-guide.md?rev=1156699&view=auto ============================================================================== --- activemq/activemq-apollo/trunk/apollo-website/src/documentation/extending-guide.md (added) +++ activemq/activemq-apollo/trunk/apollo-website/src/documentation/extending-guide.md Thu Aug 11 17:44:13 2011 @@ -0,0 +1,90 @@ +# Apollo ${project_version} Extending Guide + +{:toc:2-5} + +## Overview + +Apollo support being extended in several ways. This guide documents +all the supported extension points. + +### Adding your Extensions to the Apollo Class Path + +Just create a `.jar` out of out code and add it to the `${apollo.home}/lib` +directory. When Apollo restarts it will add the new jar to it's class path. + +### Extending the JAXB model with new Objects + +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 `Module` class and then create a `META-INF/services/org.apache.activemq.apollo/modules.index` +resource file in which you list it's class name. + +Example module class: + +{pygmentize:: scala} +package org.example +import org.apache.activemq.apollo.util.Module + +class ExtensionModule extends Module { + override def xml_packages = Array("org.example.dto") +} +{pygmentize} + + +Example `META-INF/services/org.apache.activemq.apollo/modules.index` resource: + + org.example.ExtensionModule + +### Plugging into the Broker Lifecycle + +You can implement custom [Service][] 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 `apollo.xml` to add the service so it gets started when +apollo starts: + +{pygmentize:: xml} + +{pygmentize} + +The `id` attribute is a unique service name of your service, and the +`kind` attribute is the class name of your service. + +If your service needs a reference to the Broker object which is running +in, add the following field definition to your class: + +{pygmentize:: scala} +var broker:Broker = null +{pygmentize} + +The broker instance will be injected into your class instance before it gets +started. + +Your service can also get reference to to the configuration element used +to define it if it defines the following field. + +{pygmentize:: scala} +var config: CustomServiceDTO +{pygmentize} + +This field will also get injected before getting started. The `CustomServiceDTO.other` +field will contain any additional configuration elements defined within service +element. For example, if you configured the service as follows: + +{pygmentize:: xml} + + + google.com + + +{pygmentize} + +Then you could access the options DOM element using: + +{pygmentize:: scala} + val options = config.other.get(1).asInstanceOf[Element] +{pygmentize} + +If you had defined JAXB object mappings for the `` class +then `config` will hold that object instead of generic +DOM `Element`. Modified: activemq/activemq-apollo/trunk/apollo-website/src/documentation/index.page URL: http://svn.apache.org/viewvc/activemq/activemq-apollo/trunk/apollo-website/src/documentation/index.page?rev=1156699&r1=1156698&r2=1156699&view=diff ============================================================================== --- activemq/activemq-apollo/trunk/apollo-website/src/documentation/index.page (original) +++ activemq/activemq-apollo/trunk/apollo-website/src/documentation/index.page Thu Aug 11 17:44:13 2011 @@ -27,4 +27,5 @@ ${project_slogan} * [User Manual](user-manual.html) * [Management API](management-api.html) * [Contributor Documentation](../community/developers.html) +* [Extending Guide](extending-guide.html)