<div class="wiki-content maincontent"><h1>ActiveMQ WebLogic Integration</h1>

<p>ActiveMQ clients and brokers can be run in WebLogic Server or WebLogic Express.  This is usually done for licensing reasons:</p>
<ul><li>WebLogic Server includes JMS client and server features, but it may cost extra to use these JMS features to connect multiple servers together (as opposed to only using JMS internally within one server)</li><li>WebLogic Express disables the JMS features via the license, so while JMS classes are on the class path, there are no JMS features available.<br clear="none">
An ActiveMQ broker may be run within WebLogic to provide JMS features while avoiding these issues.  As well, an ActiveMQ client may be run within WebLogic to connect to either an ActiveMQ broker running in the same WebLogic instance, and ActiveMQ broker running in a remote WebLogic instance, or a standalone ActiveMQ broker running elsewhere on the network.</li></ul>


<h2>ActiveMQ Clients in WebLogic</h2>

<p>An ActiveMQ client can be run in any recent version of WebLogic.  However, the specifics depend on which revision of JMS is supported by your version of WebLogic.</p>


<h3>WebLogic Server/Express versions including JMS 1.0.x</h3>

<p>This is known to include <strong>WebLogic 8.1</strong> and all previous versions.</p>

<p><strong>Note:</strong> ActiveMQ cannot deliver messages to message-driven beans in this version of WebLogic.  You will need to create JMS clients manually to send and receive JMS messages.</p>

<p>To work with ActiveMQ from one of these releases of WebLogic, you should not include any <code>javax.jms</code> classes with your application, but should instead use the JMS 1.0.x classes distributed with WebLogic.  This means you should not use a fully-aggregated ActiveMQ JAR such as <code>activemq-4.0.1/incubator-activemq-4.0.1.jar</code> but instead, individual ActiveMQ JARs such as <code>activemq-4.0.1/lib/activeio-core-3.0-beta3.jar</code> and <code>activemq-4.0.1/lib/activemq-core-4.0.1.jar</code>.</p>

<p>Further, your code should use only JMS 1.0.x versions of the JMS interfaces (such as <code>javax.jms.Session</code>).  Note that JMS 1.1 uses many of the same interfaces, but has added numerous methods to them, and if you use the new methods your code will not run in this version of WebLogic.  Try to ensure you're compiling your client code against the <code>weblogic.jar</code> from the correct version of WebLogic, or else a dedicated JMS 1.0.x JAR such as the one you can download from Sun.  <em>Do not compile against a JAR like <code>activemq-4.0.1/incubator-activemq-4.0.1.jar</code> because that JAR includes JMS 1.1!</em></p>

<p>Finally, you can connect to ActiveMQ using the normal ActiveMQ JNDI settings including a connect URL.  Do not attempt to use WebLogic JNDI to connect to ActiveMQ, and do not use the WebLogic host name or listen port in the ActiveMQ connect URL &#8211; even if the ActiveMQ broker is run within WebLogic it will listen on a separate network port from the one that WebLogic uses.</p>

<p><strong>TODO:</strong> Add sample JMS 1.0.x code</p>

<h3>WebLogic Server versions including JMS 1.1</h3>

<p><strong>WebLogic 9.2</strong> and above are known to support JMS 1.1.  (I don't know what JMS release WebLogic 9.0-9.1 support)</p>

<p>To work with ActiveMQ in one of these release of WebLogic Server, you can use the J2EE Connector included with ActiveMQ (known as ActiveMQ-RA).  This will provide full ActiveMQ support to J2EE applications &#8211; ActiveMQ can be used to both send messages and to deliver incoming messages to message-driven beans.  Your J2EE applications can map connection factory and destination references in JNDI.</p>

<p><em>I don't have an example of using the J2EE Connector from a J2EE 1.4 application in WebLogic.  If someone can contribute one that would be great!</em></p>

<p>If you're using Spring or another non-J2EE architecture in your application, you may choose to skip the J2EE Connector and just connect directly to ActiveMQ using the technique described in the next section.</p>

<h3>WebLogic Express versions including JMS 1.1</h3>

<p><strong>WebLogic 9.2</strong> and above are known to support JMS 1.1.  (I don't know what JMS release WebLogic 9.0-9.1 support)</p>

<p>J2EE Connectors are not supported in WebLogic Express, so that approach is out.  Instead, any components that want to connect to ActiveMQ need to manually create the connection (or use a technique like Spring message-driven POJOs to manage it).  However, this should be relatively trouble-free since ActiveMQ and WebLogic support the same JMS release.</p>

<p><strong>TODO:</strong> Example of JMS 1.1 client and Spring Message-Driven POJO client for WebLogic</p>

<h2>ActiveMQ Brokers in WebLogic</h2>

<p>On the surface it's not obvious why you might want to run an ActiveMQ broker within WebLogic instead of standalone, but the considerations include:</p>
<ul><li>When ActiveMQ is run within WebLogic, it can be deployed, started, stopped, and redeployed like other applications, using the WebLogic console or other tools, while the JVM and WebLogic are still running</li><li>ActiveMQ can hook into the WebLogic JMX management system (as well as e.g. JRockit) to provide a single management interface to the app server, applications, ActiveMQ, and even the JVM.</li><li>ActiveMQ can leverage WebLogic security realms for authentication and authorization &#8211; not only are there more security realm types available for WebLogic, but they're also easier to configure via the WebLogic console</li></ul>


<p>If you decide to run ActiveMQ standalone, that's fine, you can skip this section.  Otherwise, read on.</p>

<p>The specific integration techniques depend on whether you're using WebLogic Server or WebLogic Express, and whether your version supports JMS 1.0.x or JMS 1.1.</p>

<h3>WebLogic Server/Express versions including JMS 1.0.x</h3>

<p>Deploying an ActiveMQ broker in a release of WebLogic Server or WebLogic Express that supports only JMS 1.0.x has not been tested.  This is known to include <strong>WebLogic 8.1</strong> and all previous versions.  It will probably have trouble due to conflicting versions of JMS used by ActiveMQ and by WebLogic.</p>

<p><em>Please report your results if you try this</em></p>

<h3>WebLogic Server versions including JMS 1.1</h3>

<p><strong>WebLogic 9.2</strong> and above are known to support JMS 1.1.  (I don't know what JMS release WebLogic 9.0-9.1 support)</p>

<p>It is possible to deploy ActiveMQ in WebLogic Server in one of two ways:</p>
<ul><li><strong>Using the ActiveMQ-RA J2EE Connector</strong> &#8211; ActiveMQ provides a J2EE Connector that is normally used by clients to connect to a separate ActiveMQ broker.  However, the J2EE Connector accepts arguments to run an embedded broker and provide the location of an XML config file for an embedded broker.  This is probably the best way to deploy an ActiveMQ broker in WebLogic Server, because ActiveMQ then has access to WebLogic thread pools and other resources.</li><li><strong>Deploying an ActiveMQ Broker as a WebLogic Application</strong> &#8211; This is the technique described below for WebLogic Express.  It works equally well in WebLogic Server.</li></ul>


<p>The J2EE Connector approach has not be specifically tested, but should work well.  It would need some additional classes to support the security and management integration as described in the next section, so those would need to be added to a JAR which is in turn added to the J2EE Connector RAR file.  <em>Please report your results if you try this</em></p>

<h3>WebLogic Express versions including JMS 1.1</h3>

<p><strong>WebLogic 9.2</strong> and above are known to support JMS 1.1.  (I don't know what JMS release WebLogic 9.0-9.1 support)</p>

<p>Since WebLogic Express does not support J2EE Connectors, it is necessary to deploy ActiveMQ wrapped in an application that is deployed to WebLogic.  Note that ActiveMQ runs in the XBean container, so XBean must be pointed to an appropriate configuration file to start up and it will then configure and start all the ActiveMQ components.  The first challenge is then to construct an application that locates the right config file(s) and starts the ActiveMQ broker when it is deployed.</p>

<h4>ActiveMQ as a WebLogic Application</h4>

<p>The easiest type of WebLogic application to configure with all the needed ActiveMQ libraries and configuration and not much else is a web application.  The JARs go in <code>WEB-INF/lib/</code> and config files typically in <code>WEB-INF/</code>.  The only necessary configuration for the web application itself is to install a listener that will start and stop ActiveMQ when the web application is started and stopped.  There are also a couple optional classes that can be used to integrate ActiveMQ with WebLogic's security system.  Additionally, in this example, a simple web page included in the WAR will be available whenever ActiveMQ is running, so a simple HTTP request can determine whether the ActiveMQ module has been started.</p>

<h4>Management Options</h4>

<p>ActiveMQ exposes a number of management and monitoring features via JMX.  There are three ways to expose these JMX objects:</p>
<ol><li>Have ActiveMQ start its own JMX MBeanServer and network connector (typically on port 1099)</li><li>Have ActiveMQ use the JVM's MBeanServer (for Java 5 and higher, either Sun VM or JRockit VM)</li><li>Have ActiveMQ use the MBeanServer provided by a runtime environment such as WebLogic</li></ol>


<p>Each approach has its advantages and disadvantages.  A few things to note:</p>
<ul><li>Make sure that each ActiveMQ instance on the same machine uses a separate network port to handle JMX requests.  This is set in the config file when using the ActiveMQ MBeanServer, in a system property (command-line argument) when using the JVM's MBeanServer, and it uses the standard WebLogic listen port for WebLogic JMX</li><li>JRockit appears to require a runtime license to use the embedded MBeanServer, while the Sun JVM provides it for free</li></ul>


<p>The sample below includes an optional configuration block that lets ActiveMQ hook into the WebLogic runtime MBeanServer.  This means ActiveMQ MBeans will appear alongside WebLogic MBeans (and even JVM MBeans if they are enabled).  With this approach, management clients will access ActiveMQ MBeans through the normal WebLogic listen port (e.g. 7001) rather than using a dedicated JMX port, though IIOP must be enabled for this to work.  However, note that this is optional, and you can skip that configuration block and use one of the other approaches (JVM or embedded MBeanServer) to expose the ActiveMQ MBeans.</p>

<h4>Security Options</h4>

<p>ActiveMQ has optional authentication and authorization plugins, which are based on JAAS.  Fortunately, WebLogic provides a JAAS LoginModule that performs the authentication against the default WebLogic security realm, and returns the appropriate principals for authorization.  Unfortunately, by default, ActiveMQ cannot authorize access to specific users within the security realm based on WebLogic principals, meaning either there's no security or a login is required but any user with a valid login has full access to ActiveMQ.  However, with custom security classes like the ones shown below, ActiveMQ can use the WebLogic security realm to process a login and then you can configure the WebLogic principals (users and/or groups) that should be allowed to perform read/write/create/remove actions on a per-broker or per-destination basis.</p>

<p>You may choose to use authentication only, in which case any user with a valid WebLogic login can access ActiveMQ, and no custom code is necessary.  You may also add authorization to that using some custom code, to apply specific security constraints to specific users or destinations.  For purposes of this example, we have only implemented an authorization approach that allows any member of a single specific WebLogic group to access all resources in ActiveMQ.  Between the authorization plugin provided here and the default one provided with ActiveMQ, you should have the foundation to enhance this if more feature-rich authorization is required.</p>

<h4>Persistence Options</h4>

<p>ActiveMQ uses a combination of a local journal (files on the file system) and a backing database by default.  In the standard configuration, an embedded Derby database is used.  This runs fine in WebLogic, but it's also possible to have ActiveMQ use a database connection pool defined in WebLogic, rather than using a separate Derby database.  The configuration files shown later have commented-out sections referring to a WebLogic database connection pool &#8211; if you want to use those, you'll just need to set the correct JNDI name that was used for the database connection pool.</p>

<p>Note that ActiveMQ will create the tables it needs the first time it connects to a database, so no particular preparation is required for the database.</p>

<h4>ActiveMQ Integration Architecture</h4>

<p>The ActiveMQ-in-WebLogic combination looks like this:</p>

<p><image><attachment ri:filename="activemq-in-weblogic.png"></attachment></image></p>

<p>To summarize this diagram:</p>
<ul><li>ActiveMQ runs as a web application, which runs in the web container inside WebLogic Express</li><li>ActiveMQ reads two configuration files from a directory on the WebLogic class path &#8211; one to configure ActiveMQ itself, and one to configure its logging output</li><li>ActiveMQ uses two main resources from WebLogic Express &#8211; the JMX management server (MBeanServer) and the WebLogic security realm (in the form of a JAAS LoginModule).</li><li>In order to start ActiveMQ when the web application is deployed, the <code>web.xml</code> includes a context listener for Spring, and the Spring <code>applicationContext.xml</code> file loads the ActiveMQ broker and points it to the ActiveMQ configuration file (which as mentioned above, is stored in a directory on the class path).</li><li>Within ActiveMQ:
	<ul><li>A configuration block in the ActiveMQ configuration file causes ActiveMQ to register all its JMX MBeans with the WebLogic JMX MBeanServer</li><li>A security plugin causes all clients to authenticate against the WebLogic security realm</li><li>The security plugin also reads the name of a WebLogic group from the ActiveMQ configuration file, and requires that any client must be a member of that group (when WebLogic processed the login, it must have created a principal for that group for the user)</li><li>The ActiveMQ configuration file also identifies a network listen port that ActiveMQ will listen on for JMS clients.  Any clients must include the server's hostname and this listen port in their connect URL.</li><li>The ActiveMQ logging system (Log4J) outputs log message in the format specified in and to the destinations specified in the logging configuration file</li><li>Persistent messages are stored to the journal in the ActiveMQ Data Directory and periodically spooled to a remote database (database not shown in diagram)</li></ul>
	</li><li>Note that ActiveMQ uses its own threads; since WebLogic Express does not support J2EE Connectors, it is not possible for ActiveMQ to access a WebLogic thread pool without more extensive customization</li></ul>


<h4>Building the ActiveMQ to WebLogic Integration WAR</h4>

<p>This section discusses the code, libraries, and configuration files necessary to build the ActiveMQ web application that will be deployed in WebLogic Express.</p>

<h5>Starting and Stopping ActiveMQ</h5>

<p>ActiveMQ needs to start when the web application is deployed or started, and stop when the web application is stopped or undeployed.  The easiest way to do this is to a use the commonly available Spring listeners, which start a Spring context, which can point ActiveMQ to an XBean configuration file, which starts ActiveMQ.  A little roundabout, but it works well in practice with very little configuration.</p>

<p><strong>J2EE WEB-INF/web.xml</strong></p>
<structured-macro ac:macro-id="05b618ba-3964-4b87-92a9-9f730a3b31d9" ac:name="code" ac:schema-version="1"><parameter ac:name="">xml</parameter><plain-text-body>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;

&lt;web-app version="2.4"
         xmlns="http://java.sun.com/xml/ns/j2ee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" &gt;
    &lt;listener&gt;
        &lt;listener-class&gt;org.springframework.web.context.ContextLoaderListener&lt;/listener-class&gt;
    &lt;/listener&gt;
&lt;/web-app&gt;
</plain-text-body></structured-macro>
<p><strong>Spring WEB-INF/applicationContext.xml</strong></p>
<structured-macro ac:macro-id="b38d9c7f-bdb3-4ded-b1ef-16960374bd59" ac:name="code" ac:schema-version="1"><parameter ac:name="">xml</parameter><plain-text-body>
&lt;?xml version="1.0" encoding="UTF-8" ?&gt;
&lt;!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd"&gt;
&lt;beans&gt;
    &lt;bean id="brokerService" class="org.apache.activemq.xbean.BrokerFactoryBean"&gt;
        &lt;property name="config" value="classpath:activemq-config.xml"/&gt;
    &lt;/bean&gt;
&lt;/beans&gt;
</plain-text-body></structured-macro>
<p>Again, the <code>web.xml</code> listener starts Spring and reads the Spring <code>META-INF/applicationContext.xml</code> file (the default location used by the <code>ContextLoaderListener</code>), and the <code>applicationContext.xml</code> indicates that the ActiveMQ configuration file should be read from the class path with the name <code>activemq-config.xml</code>.  That file could be placed in <code>WEB-INF/classes</code> or in a directory on the file system that is added to the WebLogic class path (for ease of editing).</p>

<p>With this approach, the normal WebLogic deployment tools, admin console, etc. can be used to deploy, start, stop, and restart ActiveMQ (packaged into a web application WAR).</p>

<h5>Required Libraries</h5>

<p>ActiveMQ required a number of JARs which should be included in the web application <code>WEB-INF/lib</code> directory.  </p>

<p>This list was generated for ActiveMQ 4.0.1:</p>
<ul><li><code>activemq-core</code> (basic ActiveMQ code)</li><li><code>activemq-jaas</code> (ActiveMQ security code)</li><li><code>activeio-core</code> (ActiveMQ networking layer)</li><li><code>derby</code> (embedded DB for persistent messages)</li><li><code>commons-logging</code> (logging abstraction library)</li><li><code>log4j</code> (actual logging package used)</li><li><code>backport-util-concurrent</code> (concurrency utility library)</li><li><code>spring</code> (used to configure and start ActiveMQ)</li><li><code>xbean-spring</code> (used to configure ActiveMQ)</li></ul>


<p>Additionally, to build the custom security plugins, the WebLogic <code>server/lib/weblogic.jar</code> is presently required at compile time.</p>

<p>Of these, Derby could be omitted if ActiveMQ was configured to not use a database for persistence or to use a separate database (e.g. a WebLogic database pool) for persistence.  The WebLogic JAR is needed only at build time (it's provided by the server at runtime).  Spring could be omitted if a different strategy was used to start and stop ActiveMQ when the web app was started or stopped (a little custom code could replace this dependency).  The rest are probably unavoidable, unless ActiveMQ changes its dependencies in a future version.</p>

<h5>WebLogic Integration Code</h5>

<p>There are two custom classes used for this example.  We'll show in a minute how to configure ActiveMQ to use these.  Note that these are optional &#8211; if you don't want to leverage WebLogic's security realm, you can skip these.</p>

<p>The first class makes ActiveMQ use the WebLogic security realm for authentication, and lets you specify a single WebLogic group to use for authorization (only members of that group can access ActiveMQ, though group members have full access to ActiveMQ).</p>

<p><strong>ActiveMQToWebLogicSecurity.java</strong></p>

<p>This class is an ActiveMQ "plugin", which installs two filters (authorization and authentication) which will be invoked on every request.  This is similar to the default behavior provided by ActiveMQ's <code>JaasAuthenticationPlugin</code> and <code>AuthorizationPlugin</code>.</p>

<structured-macro ac:macro-id="bf4bb8ea-f777-40b5-893d-f98a0b1a12ae" ac:name="code" ac:schema-version="1"><parameter ac:name="">java</parameter><plain-text-body>
/**
 * An ActiveMQ security plugin that installs two security filters
 * (authentication and authorization) that use WebLogic security realms to
 * handle the login and provide user and group principals.
 */
public class ActiveMQToWebLogicSecurity implements BrokerPlugin {
    private String authorizedGroup;

    public Broker installPlugin(Broker broker) {
        // Install the first filter for authentication
        Broker first = new ActiveMQWebLogicAuthenticationFilter(broker);
        // Configure and install the second filter for authorization
        AuthorizationEntry entry = new AuthorizationEntry();
        Set acls = new HashSet();
        acls.add(new WLSGroupImpl(authorizedGroup));
        entry.setAdminACLs(acls);
        entry.setReadACLs(acls);
        entry.setWriteACLs(acls);
        DefaultAuthorizationMap map = new DefaultAuthorizationMap();
        map.setDefaultEntry(entry);
        //todo: if finer-grained access is required, add more entries to the authorization map
        Broker second = new AuthorizationBroker(first, map);
        return second;
    }

    public String getAuthorizedGroup() {
        return authorizedGroup;
    }

    /**
     * Called by XBean at configuration time to set the authorized group from a
     * property in the main ActiveMQ configuration file.
     */
    public void setAuthorizedGroup(String authorizedGroup) {
        this.authorizedGroup = authorizedGroup;
    }
}
</plain-text-body></structured-macro>

<p>The second class is the authentication filter used by the class above to authenticate all logins against the WebLogic default security realm.</p>

<p><strong>ActiveMQWebLogicAuthenticationFilter.java</strong></p>

<structured-macro ac:macro-id="07bc33d8-59bf-43bf-9a76-3944357daa97" ac:name="code" ac:schema-version="1"><parameter ac:name="">java</parameter><plain-text-body>
/**
 * A broker filter that authenticates callers against WebLogic security.
 * This is similar to the ActiveMQ JaasAuthenticationBroker except for two
 * things:
 * &lt;ul&gt;
 *   &lt;li&gt;Instead of reading a JAAS configuration file, it hardcodes the JAAS
 *     configuration to require authentication against WebLogic&lt;/li&gt;
 *
 *   &lt;li&gt;The SecurityContext implementation overrides the method used to
 *     compare actual and eligible principals in order to handle the fact
 *     that WebLogic principals (WLSGroupImpl in particular) do not seem
 *     to match according to equals and hashCode even if the principal class
 *     and principal name are the same (perhaps having to do with the
 *     signature data on the WLSAbstractPrincipal).&lt;/li&gt;
 * &lt;/ul&gt;
 */
public class ActiveMQWebLogicAuthenticationFilter extends BrokerFilter {
    private final static Configuration WEBLOGIC_JAAS_CONFIGURATION = new Configuration() {
        public AppConfigurationEntry[] getAppConfigurationEntry(String name) {
            return new AppConfigurationEntry[]{
                    new AppConfigurationEntry("weblogic.security.auth.login.UsernamePasswordLoginModule",
                            AppConfigurationEntry.LoginModuleControlFlag.REQUIRED, Collections.EMPTY_MAP)
            };
        }

        public void refresh() {
        }
    };
    private final CopyOnWriteArrayList securityContexts = new CopyOnWriteArrayList();

    public ActiveMQWebLogicAuthenticationFilter(Broker next) {
        super(next);
    }

    static class JaasSecurityContext extends SecurityContext {

        private final Subject subject;

        public JaasSecurityContext(String userName, Subject subject) {
            super(userName);
            this.subject = subject;
        }

        public Set getPrincipals() {
            return subject.getPrincipals();
        }

        /**
         * This is necessary because WebLogic uses extra logic when comparing principals,
         * probably to check whether they are cryptographically signed (which WebLogic
         * supports).  We skip that test because ActiveMQ does not sign the principals
         * it deals with.
         */
        public boolean isInOneOf(Set eligiblePrincipals) {
            for (Iterator it = getPrincipals().iterator(); it.hasNext();) {
                Principal test = (Principal) it.next();
                for (Iterator el = eligiblePrincipals.iterator(); el.hasNext();) {
                    Principal eligible = (Principal) el.next();
                    if(test.getName().equals(eligible.getName()) &amp;&amp;
                            test.getClass().getName().equals(eligible.getClass().getName())) {
                        return true;
                    }
                }
            }
            return false;
        }
    }

    public void addConnection(ConnectionContext context, ConnectionInfo info) throws Exception {
        if( context.getSecurityContext()==null ) {
            // Do the login.
            try {
                LoginContext lc = new LoginContext("ActiveMQ", new Subject(),
                        new URLCallbackHandler(info.getUserName(), info.getPassword()),
                        WEBLOGIC_JAAS_CONFIGURATION);
                lc.login();
                Subject subject = lc.getSubject();

                SecurityContext s = new JaasSecurityContext(info.getUserName(), subject);
                context.setSecurityContext(s);
                securityContexts.add(s);
            } catch (Exception e) {
                throw (SecurityException)new SecurityException("User name or password is invalid.").initCause(e);
            }
        }
        super.addConnection(context, info);
    }

    public void removeConnection(ConnectionContext context, ConnectionInfo info, Throwable error) throws Exception {
        super.removeConnection(context, info, error);
        if( securityContexts.remove(context.getSecurityContext()) ) {
            context.setSecurityContext(null);
        }
    }

    /**
     * Previously logged in users may no longer have the same access anymore.  Refresh
     * all the logged into users.
     */
    public void refresh() {
        for (Iterator iter = securityContexts.iterator(); iter.hasNext();) {
            SecurityContext sc = (SecurityContext) iter.next();
            sc.getAuthorizedReadDests().clear();
            sc.getAuthorizedWriteDests().clear();
        }
    }
}
</plain-text-body></structured-macro>

<h5>Sample ActiveMQ Configuration Files</h5>

<p>This section shows three sample ActiveMQ configuration files &#8211; one for a single broker with the security and management plugins listed above, and one for a network of two brokers with the security and management plugins listed above.  If you want to skip the security and management plugins, you can remove those attributes from the main <code>&lt;broker&gt;</code> element and remove the <code>&lt;bean&gt;</code> definitions for them below.</p>

<p>It also shows a Log4J configuration file, which controls the ActiveMQ log output.</p>

<p><strong>Single Broker</strong></p>
<structured-macro ac:macro-id="6047c8fc-df5e-4cc8-8b72-e9ec9817cd34" ac:name="code" ac:schema-version="1"><parameter ac:name="">xml</parameter><plain-text-body>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;beans xmlns="http://activemq.org/config/1.0"&gt;
  &lt;!-- Allows us to use system properties as variables in this configuration file --&gt;
  &lt;bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"/&gt;
  
  &lt;broker useJmx="true" brokerName="MyBroker" useShutdownHook="false"
          plugins="#WebLogicSecurity"&gt;

    &lt;!-- Register all ActiveMQ MBeans with the WebLogic runtime MBeanServer --&gt;
    &lt;managementContext&gt;
      &lt;managementContext&gt;
          &lt;MBeanServer&gt;
             &lt;bean class="org.springframework.jndi.JndiObjectFactoryBean" xmlns=""&gt;
                &lt;property name="jndiName" value="java:comp/env/jmx/runtime" /&gt;
                &lt;property name="lookupOnStartup" value="true" /&gt;
                &lt;property name="expectedType" value="javax.management.MBeanServer" /&gt;
             &lt;/bean&gt;
          &lt;/MBeanServer&gt;
      &lt;/managementContext&gt;
    &lt;/managementContext&gt;
  
    &lt;persistenceAdapter&gt;
      &lt;!-- By default, use an embedded Derby database --&gt;
        &lt;journaledJDBC journalLogFiles="5"
                       dataDirectory="/server/bea/weblogic920/domains/jms/activemq-data"/&gt;
      &lt;!-- Use this with the WebLogicDataSource below to use a WebLogic
           database connection pool instead of the embedded Derby database
        &lt;journaledJDBC journalLogFiles="5"
                       dataDirectory="/server/bea/weblogic920/domains/jms/activemq-data"
                       dataSource="#WebLogicDataSource" /&gt;

      --&gt;
    &lt;/persistenceAdapter&gt;
  
    &lt;transportConnectors&gt;
        &lt;transportConnector name="MyBrokerTCP" uri="tcp://0.0.0.0:61616" /&gt;
    &lt;/transportConnectors&gt;
  &lt;/broker&gt;

  &lt;bean id="WebLogicSecurity"
        class="com.example.activemq.weblogic.ActiveMQToWebLogicSecurity"&gt;
      &lt;property name="authorizedGroup" value="ActiveMQUsers" /&gt;
  &lt;/bean&gt;

&lt;!-- Uncomment and configure this if you want to use a WebLogic database
     connection pool for persistent messages
  &lt;bean id="WebLogicDataSource"
        class="org.springframework.jndi.JndiObjectFactoryBean"&gt;
     &lt;property name="jndiName" value="db/pool/jndi/name"/&gt;
  &lt;/bean&gt;
--&gt;
&lt;/beans&gt;
</plain-text-body></structured-macro>

<p><strong>Network of Brokers (Broker 1/2)</strong></p>
<structured-macro ac:macro-id="da8c3f84-e89b-40b6-b997-434fbeabfa67" ac:name="code" ac:schema-version="1"><parameter ac:name="">xml</parameter><plain-text-body>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;beans xmlns="http://activemq.org/config/1.0"&gt;
  &lt;!-- Allows us to use system properties as variables in this configuration file --&gt;
  &lt;bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"/&gt;
  
  &lt;broker useJmx="true" brokerName="FirstBroker" useShutdownHook="false"
          plugins="#WebLogicSecurity"&gt;

    &lt;!-- Register all ActiveMQ MBeans with the WebLogic runtime MBeanServer --&gt;
    &lt;managementContext&gt;
      &lt;managementContext&gt;
          &lt;MBeanServer&gt;
             &lt;bean class="org.springframework.jndi.JndiObjectFactoryBean" xmlns=""&gt;
                &lt;property name="jndiName" value="java:comp/env/jmx/runtime" /&gt;
                &lt;property name="lookupOnStartup" value="true" /&gt;
                &lt;property name="expectedType" value="javax.management.MBeanServer" /&gt;
             &lt;/bean&gt;
          &lt;/MBeanServer&gt;
      &lt;/managementContext&gt;
    &lt;/managementContext&gt;
  
    &lt;persistenceAdapter&gt;
      &lt;!-- By default, use an embedded Derby database --&gt;
        &lt;journaledJDBC journalLogFiles="5"
                       dataDirectory="/server/bea/weblogic920/domains/jms/activemq-b1-data"/&gt;
      &lt;!-- Use this with the WebLogicDataSource below to use a WebLogic
           database connection pool instead of the embedded Derby database
        &lt;journaledJDBC journalLogFiles="5"
                       dataDirectory="/server/bea/weblogic920/domains/jms/activemq-b1-data"
                       dataSource="#WebLogicDataSource" /&gt;

      --&gt;
    &lt;/persistenceAdapter&gt;
  
    &lt;transportConnectors&gt;
        &lt;transportConnector name="FirstBrokerTCP" uri="tcp://0.0.0.0:60010" /&gt;
    &lt;/transportConnectors&gt;
    
    &lt;networkConnectors&gt;
        &lt;networkConnector name="Broker1ToBroker2"
                          uri="static://(tcp://localhost:60011)" failover="true"
                          userName="fixme" password="fixme"/&gt;
    &lt;/networkConnectors&gt;
  &lt;/broker&gt;

  &lt;bean id="WebLogicSecurity"
        class="com.example.activemq.weblogic.ActiveMQToWebLogicSecurity"&gt;
      &lt;property name="authorizedGroup" value="ActiveMQUsers" /&gt;
  &lt;/bean&gt;

&lt;!-- Uncomment and configure this if you want to use a WebLogic database
     connection pool for persistent messages
  &lt;bean id="WebLogicDataSource"
        class="org.springframework.jndi.JndiObjectFactoryBean"&gt;
     &lt;property name="jndiName" value="db/pool/jndi/name"/&gt;
  &lt;/bean&gt;
--&gt;
&lt;/beans&gt;
</plain-text-body></structured-macro>

<p><strong>Network of Brokers (Broker 2/2)</strong></p>
<structured-macro ac:macro-id="e01f5ebf-021d-470d-9558-a4ceb9913054" ac:name="code" ac:schema-version="1"><parameter ac:name="">xml</parameter><plain-text-body>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;beans xmlns="http://activemq.org/config/1.0"&gt;
  &lt;!-- Allows us to use system properties as variables in this configuration file --&gt;
  &lt;bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"/&gt;
  
  &lt;broker useJmx="true" brokerName="SecondBroker" useShutdownHook="false"
          plugins="#WebLogicSecurity"&gt;

    &lt;!-- Register all ActiveMQ MBeans with the WebLogic runtime MBeanServer --&gt;
    &lt;managementContext&gt;
      &lt;managementContext&gt;
          &lt;MBeanServer&gt;
             &lt;bean class="org.springframework.jndi.JndiObjectFactoryBean" xmlns=""&gt;
                &lt;property name="jndiName" value="java:comp/env/jmx/runtime" /&gt;
                &lt;property name="lookupOnStartup" value="true" /&gt;
                &lt;property name="expectedType" value="javax.management.MBeanServer" /&gt;
             &lt;/bean&gt;
          &lt;/MBeanServer&gt;
      &lt;/managementContext&gt;
    &lt;/managementContext&gt;
  
    &lt;persistenceAdapter&gt;
      &lt;!-- By default, use an embedded Derby database --&gt;
        &lt;journaledJDBC journalLogFiles="5"
                       dataDirectory="/server/bea/weblogic920/domains/jms/activemq-b2-data"/&gt;
      &lt;!-- Use this with the WebLogicDataSource below to use a WebLogic
           database connection pool instead of the embedded Derby database
        &lt;journaledJDBC journalLogFiles="5"
                       dataDirectory="/server/bea/weblogic920/domains/jms/activemq-b2-data"
                       dataSource="#WebLogicDataSource" /&gt;

      --&gt;
    &lt;/persistenceAdapter&gt;
  
    &lt;transportConnectors&gt;
        &lt;transportConnector name="SecondBrokerTCP" uri="tcp://0.0.0.0:60011" /&gt;
    &lt;/transportConnectors&gt;
    
    &lt;networkConnectors&gt;
        &lt;networkConnector name="Broker2ToBroker1"
                          uri="static://(tcp://localhost:60010)" failover="true"
                          userName="fixme" password="fixme" /&gt;
    &lt;/networkConnectors&gt;
  &lt;/broker&gt;

  &lt;bean id="WebLogicSecurity"
        class="com.example.activemq.weblogic.ActiveMQToWebLogicSecurity"&gt;
      &lt;property name="authorizedGroup" value="activemq" /&gt;
  &lt;/bean&gt;

&lt;!-- Uncomment and configure this if you want to use a WebLogic database
     connection pool for persistent messages
  &lt;bean id="WebLogicDataSource"
        class="org.springframework.jndi.JndiObjectFactoryBean"&gt;
     &lt;property name="jndiName" value="db/pool/jndi/name"/&gt;
  &lt;/bean&gt;
--&gt;
&lt;/beans&gt;
</plain-text-body></structured-macro>

<p><strong>Log4J Configuration File (<code>log4j.properties</code>)</strong></p>
<structured-macro ac:macro-id="28f18411-225c-4d43-9dac-267f83691154" ac:name="code" ac:schema-version="1"><plain-text-body>
# Can change this to "INFO, out" or "INFO, out, stdout"
# to enable logging to the file defined down below
log4j.rootLogger=INFO, stdout
log4j.logger.org.apache.activemq.spring=WARN
log4j.logger.org.springframework=WARN
log4j.logger.org.apache.xbean.spring=WARN

# Configuration to log to stdout
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%-5p %-30.30c{1} - %m%n
log4j.appender.stdout.threshold=INFO

# Configuration for a log file (in addition to or instead of stdout)
log4j.appender.out=org.apache.log4j.RollingFileAppender
log4j.appender.out.file=/server/bea/weblogic920/domains/test/activemq.log
log4j.appender.out.maxFileSize=1024KB
log4j.appender.out.maxBackupIndex=5
log4j.appender.out.append=true
log4j.appender.out.layout=org.apache.log4j.PatternLayout
log4j.appender.out.layout.ConversionPattern=%d [%-15.15t] %-5p %-30.30c{1} - %m%n
</plain-text-body></structured-macro>

<h4>Installation Procedure</h4>

<p>This procedure makes the following assumptions:</p>
<ul><li>The ActiveMQ configuration file and Log4J configuration file will be stored in a subdirectory of the WebLogic domain directory for ease of editing.  They may be packaged into <code>WEB-INF/classes</code> in the WAR for ease of distribution instead.</li><li>The ActiveMQ JMX management features will be exposed via the WebLogic runtime JMX MBeanServer.  This is not required, but it should allow existing WebLogic management scripts to see the ActiveMQ MBeans. <em>NOTE: Additional configuration is required if the Sun JVM JMX server or JRockit management server will be used instead, or if the embedded ActiveMQ JMX server will be used instead and more than one ActiveMQ instance will be run on the same server.</em></li><li>ActiveMQ will be installed on a single WebLogic instance or on two WebLogic instances in a Network-of-Brokers configuration.
	<ul><li>In a (Network-of-Brokers) cluster, the two ActiveMQ instances will use specific URLs to locate each other, rather than attempting runtime discovery of arbitrary brokers that may be present on the network.</li></ul>
	</li><li>Either ActiveMQ security is disabled, or ActiveMQ logins are validated against the WebLogic default security realm and a login is required and any member of a designated WebLogic group can access ActiveMQ.</li></ul>


<p>Prerequisites</p>
<ul><li>WebLogic Express 9.2 has been installed</li><li>A simple WebLogic domain has been created</li><li>If the JRockit VM will be used on Linux, the file handle limit of the user running WebLogic may be important (test with <code>ulimit -n</code>).  A recommended value would be at least twice the expected maximum number of JMS clients.</li><li>The ActiveMQ web application WAR (<code>activemq-4.0.1-web.war</code>)</li><li>The ActiveMQ configuration file (<code>activemq-config.xml</code>)</li><li>The Log4J configuration file (<code>log4j.properties</code>)</li></ul>


<p>Installation Procedure</p>
<ol><li>Create a subdirectory of the WebLogic domain directory to hold ActiveMQ config files (e.g. <code>domain-dir/activemq/config</code>)</li><li>Create a subdirectory of the WebLogic domain directory to hold ActiveMQ runtime data &#8211; persistent messages, etc. (e.g. <code>domain-dir/activemq/data</code>)</li><li>Edit the <code>activemq-config.xml</code> to point to the correct runtime data directory created in step 2 (look for the part of the file that reads <code>dataDirectory="..."</code>)</li><li>In <code>activemq-config.xml</code>, review the port for the current ActiveMQ server defined in the <code>&lt;transportConnector .../&gt;</code> line, if ActiveMQ clustering will be used, review the hostname and port for the other ActiveMQ server(s) in the cluster defined in the <code>&lt;networkConnector .../&gt;</code> line.</li><li>If ActiveMQ clustering and security are both enabled, in <code>activemq-config.xml</code>, find (or add) the <code>userName</code> and <code>password</code> settings on the <code>&lt;networkConnector .../&gt;</code> and change them to valid values.  (When security is enabled, the ActiveMQ brokers in a cluster require valid logins to connect to each other to form the cluster.)</li><li>If security is enabled, in <code>activemq-config.xml</code>, find the <code>authorizedGroup</code> setting on the <code>WebLogicSecurity</code> bean and set that to the name of the WebLogic group whose members should be able to access ActiveMQ.  Note that the account used by the network connectors in the previous step must be members of this group.  (This entry in the config file is described in the previous section)</li><li>(Optional) Update the <code>log4j.properties</code> file to save ActiveMQ logs to a file rather than just emitting to the WebLogic server's standard output (e.g. change the first line to <code>log4j.rootLogger=INFO, out, stdout</code> and change the destination file in the <code>log4j.appender.out.file=...</code> line)</li><li>Save the <code>activemq-config.xml</code> and <code>log4j.properties</code> files to the ActiveMQ configuration directory created in step 1</li><li>Edit the <code>startWebLogic.sh</code> file in the domain directory and add the following line to the top (immediately after the <code>DOMAIN_HOME=...</code> line), adjusting the line to use the directory created in step 1:
<structured-macro ac:macro-id="2329189d-2639-4c66-9828-e82e68691b27" ac:name="noformat" ac:schema-version="1"><plain-text-body>
export EXT_POST_CLASSPATH=${DOMAIN_HOME}/activemq/config
</plain-text-body></structured-macro></li><li>Start WebLogic</li><li>Deploy the <code>activemq-4.0.1-web.war</code> file, by copying it to the <code>domain-dir/autodeploy</code> directory or using the deployment tools in the WebLogic console.</li><li>Verify that the WebLogic server standard output (or the ActiveMQ log file configured in step 5) shows that ActiveMQ started, with output like this:
<structured-macro ac:macro-id="a4b30fd3-4026-4386-beac-742f6f8ce5f6" ac:name="noformat" ac:schema-version="1"><plain-text-body>
INFO  BrokerService                  - ActiveMQ 4.0.1 JMS Message Broker (localhost) is starting
INFO  BrokerService                  - For help or more information please see:
                                       http://incubator.apache.org/activemq/
INFO  JDBCPersistenceAdapter         - Database driver recognized: [apache_derby_embedded_jdbc_driver]
INFO  JournalPersistenceAdapter      - Journal Recovery Started from: Active Journal: using 5 x 20.0 Megs at:
                                       /data/server/bea/weblogic920/domains/test/activemq-data/journal
INFO  JournalPersistenceAdapter      - Journal Recovered: 0 message(s) in transactions recovered.
INFO  TransportServerThreadSupport   - Listening for connections at: tcp://0.0.0.0:60010
INFO  TransportConnector             - Connector default Started
INFO  BrokerService                  - ActiveMQ JMS Message Broker
                                       (localhost, ID:remus-28763-1156532531109-1:0) started
</plain-text-body></structured-macro></li><li>Test a management connection by running the <code>jconsole</code> tool distributed with Java 5, using an advanced connection, entering the URL <code>service:jmx:rmi:///jndi/iiop://localhost:7001/weblogic.management.mbeanservers.runtime</code> (adjusting <code>localhost:7001</code> to the WebLogic server hostname and port) and the WebLogic administrator username and password.  Once connected, on the MBeans tab, there should be entries under <code>org/activemq</code></li><li>Test a security if desired by running the example producer and consumer from an ActiveMQ 4.0.1 distribution.  Note that the connect URL is in <code>examples/build.xml</code> while the connect username and password need to be added to <code>examples/src/ConsumerTool.java</code> and <code>examples/src/ProducerTool.java</code> to connect successfully to a secure instance.</li><li>If ActiveMQ clustering will be used, repeat this process for the other WebLogic/ActiveMQ instance in the cluster.  This should set up the two ActiveMQ servers to connect to each other.  Confirm this by looking for output like this once both brokers are running:
<structured-macro ac:macro-id="dfcfe7a8-5052-46e8-bec0-5e4a85b635d2" ac:name="noformat" ac:schema-version="1"><plain-text-body>
INFO  DemandForwardingBridge         - Network connection between vm://FirstBroker#0 and
                                       tcp://localhost:63222(SecondBroker) has been established.
</plain-text-body></structured-macro></li></ol>
</div>