ActiveMQ Message Broker Configuration

Geronimo utilizes its GBean architecture to manage the lifecycle of services in the Geronimo server. As described in Chapter 9, XML deployment descriptor files (known as deployment plans, or simply plans) contain all metadata about GBeans and their dependencies. This file is used by an assembly to discover all the dependencies for the ActiveMQ broker to be sure those are all available before attempting to start up an ActiveMQ broker instance. As long as all dependencies are available, the ActiveMQ broker is started and a message is printed to the terminal indicating that the ActiveMQ broker is running. See the bold text in the following example output when starting Geronimo to see this message:

 $ ./bin/geronimo.sh run  Using GERONIMO_BASE:    /Users/bsnyder/geronimo-1.1 Using GERONIMO_HOME:    /Users/bsnyder/geronimo-1.1 Using GERONIMO_TMPDIR:  /Users/bsnyder/geronimo-1.1/var/temp Using JRE_HOME: /System/Library/Frameworks/JavaVM.framework/Versions/1.4/Home Booting Geronimo Kernel (in Java 1.4.2_09)... Starting Geronimo Application Server v1.1 [**********************] 100%  87s Startup complete   Listening on Ports:     1099 0.0.0.0 RMI Naming     1527 0.0.0.0 Derby Connector     4201 0.0.0.0 ActiveIO Connector EJB     4242 0.0.0.0 Remote Login Listener     8009 0.0.0.0 Jetty Connector AJP13     8080 0.0.0.0 Jetty Connector HTTP     8443 0.0.0.0 Jetty Connector HTTPS     9999 0.0.0.0 JMX Remoting Connector    61616 0.0.0.0 ActiveMQ Message Broker Connector   Started Application Modules:     EAR: geronimo/webconsole-jetty/1.1/car     RAR: geronimo/activemq/1.1/car     RAR: geronimo/system-database/1.1/car     WAR: geronimo/remote-deploy-jetty/1.1/car     WAR: geronimo/welcome-jetty/1.1/car   Web Applications:     http://rattlesnake:8080/     http://rattlesnake:8080/console     http://rattlesnake:8080/console-standard     http://rattlesnake:8080/remote-deploy Geronimo Application Server started 

The bold text indicates that the ActiveMQ broker has been started and is running on port 61616. This is simply the default port on which the ActiveMQ broker typically runs and can be changed as needed via the var/config/config.xml file.

Listing 16-1 shows the deployment plan for the ActiveMQ broker inside of Geronimo. Note that none of the deployment plans for any specific modules are included in the 1.1 binary download of Geronimo. To see this and other deployment plans, you will need to see the Geronimo Subversion repository (http://svn.apache.org/repos/asf/geronimo). As of this writing, the deployment plan below is located in configs/activemq-broker/target/plan/plan.xml, but only after a clean build of Geronimo.

Listing 16-1: The ActiveMQ Broker Plan

 <?xml version="1.0" encoding="UTF-8"?> <module xmlns="http://geronimo.apache.org/xml/ns/deployment-1.1">   <!--management-->   <environment>     <moduleId>       <groupId>geronimo</groupId>       <artifactId>activemq-broker</artifactId>       <version>1.1</version>       <type>car</type>     </moduleId>     <dependencies>       <dependency>         <groupId>geronimo</groupId>         <artifactId>system-database</artifactId>         <type>car</type>       </dependency>       <dependency>         <groupId>activemq</groupId>         <artifactId>activemq-core</artifactId>         <type>jar</type>         <import>classes</import>       </dependency>       <dependency>         <groupId>activemq</groupId>         <artifactId>activemq-gbean-g1_1</artifactId>         <type>jar</type>         <import>classes</import>       </dependency>       <dependency>         <groupId>activemq</groupId>         <artifactId>activemq-gbean-management-g1_1</artifactId>         <type>jar</type>         <import>classes</import>       </dependency>       <dependency>         <groupId>activeio</groupId>         <artifactId>activeio</artifactId>         <type>jar</type>         <import>classes</import>       </dependency>     </dependencies>       <hidden-classes/>       <non-overridable-classes/>     </environment>     <gbean name="ActiveMQManager" />   <!--message broker-->   <gbean name="ActiveMQ" >     <attribute name="brokerName">possibly-unique-broker</attribute>     <reference name="persistenceAdapter">       <name>ActiveMQ.cache</name>     </reference>     <reference name="JMSManager">       <name>ActiveMQManager</name>     </reference>     <dependency>       <name>SystemProperties</name>     </dependency>   </gbean>   <gbean name="ActiveMQ.cache" >     <attribute name="cacheSize">10000</attribute>     <reference name="longTermPersistence">       <name>ActiveMQ.journal</name>     </reference>   </gbean>   <gbean name="ActiveMQ.journal" >     <reference name="serverInfo">       <name>ServerInfo</name>     </reference>     <attribute name="directory">var/activemq/journal</attribute>     <attribute name="journalType">default</attribute>     <reference name="longTermPersistence">       <name>ActiveMQ.jdbc</name>     </reference>   </gbean>   <gbean name="ActiveMQ.jdbc" >     <reference name="dataSource">       <name>SystemDatasource</name>     </reference>   </gbean>   <gbean name="ActiveMQ.tcp.default" >     <attribute name="protocol">tcp</attribute>     <attribute name="host">localhost</attribute>     <attribute name="port">61616</attribute>     <reference name="activeMQContainer">       <name>ActiveMQ</name>     </reference>   </gbean>   <gbean name="ActiveMQ.vm.localhost" >     <attribute name="protocol">vm</attribute>     <attribute name="host">localhost</attribute>     <attribute name="port">-1</attribute>     <reference name="activeMQContainer">       <name>ActiveMQ</name>     </reference>   </gbean>   <gbean name="SystemProperties" >     <attribute name="systemProperties">activemq.broker.disable-clean shutdown=true</attribute>   </gbean> </module>

The deployment plan for the ActiveMQ displayed in Listing 16-1 focuses on the definition of the GBeans used by the Geronimo kernel to start the ActiveMQ broker. For more information on GBeans, see Chapter 5. Understanding the plan in Listing 16-1 will assist you in understanding the ActiveMQ broker configuration for Geronimo. Table 16-1 provides a description of the ActiveMQ plan in Listing 16-1.

Table 16-1: Overview of the ActiveMQ Broker Plan
Open table as spreadsheet

Component/GBean	Name Description
environment	An encapsulating root element for the module plan file.
moduleId	A container element for the groupId, artifactId, and version of the module. Together these items form the moduleId.
dependencies	This element holds all dependency and class loader information for the module.
hidden-classes	A list of classes that will never be loaded from parent Class-Loaders of this module. The classes are specified in zero or more child filter elements, where each filter element specifies a fully qualified class name or prefix. Essentially, any class that starts with one of the prefixes listed here will be treated as hidden.
non-overridable-classes	A list of classes that will only be loaded from parent Class-Loaders of this module (never from the module’s own ClassLoader). Just as with the hidden-classes element, the classes are specified in zero or more child filter elements, where each filter element specifies a fully qualified class name or prefix. Essentially, any class that starts with one of the prefixes listed here will be treated as hidden.
ActiveMQManager	The ActiveMQManager is a management interface for the ActiveMQ message broker.
ActiveMQ	The ActiveMQ GBean wraps the ActiveMQ message broker to handle its lifecycle. This GBean defines a reference element, namely the persistenceAdapter. Notice the gbean-name for the persistenceAdapter. It's a reference to another GBean. It’s pointing to a GBean whose name begins with the string ActiveMQ.cache. This resolves to the GBean element whose name is ActiveMQ.cache.
ActiveMQ.cache	The ActiveMQ.cache GBean sits above the persistence GBean (ActiveMQ.jdbc) to providing caching facilities. It defines an attribute named cacheSize and a reference to the ActiveMQ.journal GBean.
ActiveMQ.journal	The ActiveMQ.journal is used for short-term, high-performance persistence and is checkpointed to the database periodically. It defines an attributes named directory and journalType, and also a reference to the ActiveMQ.jdbc GBean.
ActiveMQ.jdbc	The ActiveMQ.jdbc GBean identifies the long-term message persistence configuration using a JDBC data source. It simply refers to another GBean whose unique ID is SystemDatabase.
geronimo.tcp.default	A J2EE connector providing a TCP-based connection to the ActiveMQ message broker.
geronimo.vm.localhost	A J2EE connector providing a local connection to the ActiveMQ message broker.
SystemProperties	A convenience component to handle system properties. This component allows system properties to be set in deployment plans instead of in a very long string on the command line when starting the JVM. For ActiveMQ, there is a property listed here named activemq.broker.disable-clean-shutdown and it is set to true. This property tells the Geronimo lifecycle to not perform a clean shutdown on ActiveMQ.

This plan controls how the message broker is configured by default. You can customize this default configuration using the config.xml file, covered next.

Customizing the Message Broker

In Geronimo 1.1, there are two ways to make customizations to any module:

• Using the config.xml file

• Using the deployment plan for the given module

Each method of customization has its advantages and disadvantages.

Important-When Does the config.xml File Not Take Precedence?

Under most circumstances, the config.xml file rules supreme when it comes to customizing a given module. But there are times when changes to the config.xml will not have the desired affect. An example of this is the removal of a dependency that is defined in a configuration’s plan.

For example, removing the SystemDatabase dependency from the ActiveMQ broker by removing it from the config.xml will be overridden by the ActiveMQ broker configuration’s explicit dependency on it from within its plan. In other words, since the dependency on the SystemDatabase already exists from within the ActiveMQ broker module’s deployment plan, it cannot be removed per se. It can, however, be redefined in the config.xml by creating an entirely new definition for a configuration matching the SystemDatabase’s exact configuration name.

Customization Using the config.xml File

The binary distribution for Geronimo contains a file in the var/config directory named config.xml (var/config/config.xml) that is specifically for customizing module configurations. No matter whether a module is customized through the use of the config.xml or the module’s corresponding deployment plan, the config.xml takes precedence unless the module’s deployment plan contains dependencies that may override changes to the given plan. For more information on this, see the sidebar “When Does the config.xml File Not Take Precedence?”

The following example is an excerpt from the default config.xml file that controls the ActiveMQ broker configuration:

 ...     <module name="geronimo/activemq-broker/1.1-rc1/car">         <gbean name="ActiveMQ.tcp.default">             <attribute name="host">0.0.0.0</attribute>             <attribute name="port">61616</attribute>         </gbean>     </module> ...

The portion of the config.xml displayed here applies to a module with the unique ID of geronimo/activemq-broker/1.1/car. This is just a simple unique string ID that points to the ActiveMQ broker module. It comes directly from the module’s deployment plan, which is discussed in the next section. Next is a GBean whose name is ActiveMQ.tcp.default. This is the unique name for a particular GBean in the ActiveMQ broker configuration in Listing 16-1. The attribute elements defined within the GBean element apply to properties in the ActiveMQ.tcp.default GBean. Any attributes listed here can be customized manually. For example, if the port attribute must be changed, this is the place to do it. For example, to change the port number used by ActiveMQ from 61616 to 31313, just override the necessary attribute, like this:

 ... <module name="geronimo/activemq-broker/1.1-rc1/car">         <gbean name="ActiveMQ.tcp.default">             <attribute name="protocol">tcp</attribute>             <attribute name="host">localhost</attribute>             <attribute name="port">31313</attribute>       </gbean>       </module> ...

Now, when Geronimo is started up, the port on which ActiveMQ runs is 31313:

 Using GERONIMO_BASE:    /Users/bsnyder/geronimo-1.1 Using GERONIMO_HOME:    /Users/bsnyder/geronimo-1.1 Using GERONIMO_TMPDIR: /Users/bsnyder/geronimo-1.1/var/temp Using JRE_HOME: /System/Library/Frameworks/JavaVM.framework/Versions/1.4/Home Booting Geronimo Kernel (in Java 1.4.2_09)... Starting Geronimo Application Server v1.1 [**********************] 100%  87s Startup complete   Listening on Ports:     1099 0.0.0.0 RMI Naming     1527 0.0.0.0 Derby Connector     4201 0.0.0.0 ActiveIO Connector EJB     4242 0.0.0.0 Remote Login Listener     8009 0.0.0.0 Jetty Connector AJP13     8080 0.0.0.0 Jetty Connector HTTP     8443 0.0.0.0 Jetty Connector HTTPS     9999 0.0.0.0 JMX Remoting Connector    31313 0.0.0.0 ActiveMQ Message Broker Connector   Started Application Modules:     EAR: geronimo/webconsole-jetty/1.1/car     RAR: geronimo/activemq/1.1/car     RAR: geronimo/system-database/1.1/car     WAR: geronimo/remote-deploy-jetty/1.1/car     WAR: geronimo/welcome-jetty/1.1/car   Web Applications:     http://rattlesnake:8080/     http://rattlesnake:8080/console     http://rattlesnake:8080/console-standard     http://rattlesnake:8080/remote-deploy Geronimo Application Server started 

This is just a simple example of changing an attribute that has little impact on the actual GBean that’s running in Geronimo to control the ActiveMQ broker because it just changes an integer. If the protocol must be changed, then further customization in the config.xml file is necessary.

In addition to customizing attributes on a GBean, new GBeans can also be defined in the config.xml. By default, there are two network connectors installed for the ActiveMQ broker: an in-VM connector (whose name is ActiveMQ.vm.localhost) and a TCP connector (whose name is ActiveMQ.tcp.default). Additional connectors can be added via the config.xml. However, as noted earlier, adding a new network connector (or even changing an existing one) requires additional customization. For example, a new connector for the STOMP protocol can be added, but it requires more than the previous example. Following is an example of defining a new network connector to provide the STOMP protocol for ActiveMQ:

 ... <module name="geronimo/activemq-broker/1.1/car">   <gbean gbeanInfo="org.activemq.gbean.ActiveMQConnectorGBean" name="geronimo/activemq broker/1.1/car?JMSServer=ActiveMQ,ServiceModule=geronimo/activemq-broker/1.1/car,j2 eeType=GBean,name=ActiveMQ.stomp">       <attribute name="protocol">stomp</attribute>       <attribute name="host">localhost</attribute>       <attribute name="port">21212</attribute>       <reference name="activeMQContainer">         <pattern>           <groupId>geronimo</groupId>           <artifactId>activemq-broker</artifactId>           <version>1.1</version>           <type>car</type>           <name>ActiveMQ</name>         </pattern>       </reference>     </gbean> </module> ...

This example defines a new GBean for a new connector to make use of the STOMP protocol. By adding this definition to the config.xml, the new connector is deployed to handle JMS requests over STOMP on port 21212.

Deploying Customizations to the config.xml File

To apply changes to the config.xml file, simply cycle the server. When working from the Geronimo source code, beware that the config.xml file is regenerated during every build, and any changes made to it will be overwritten upon recompile. Be sure to back up any changes before rebuilding from source.

The other prescribed manner in which to change a module configuration is to use the module’s deployment plan.

Customization Using the Deployment Plan

The configuration of the ActiveMQ broker is housed entirely in the deployment plan that is displayed in Listing 16-1 and is described in Table 16-1. The plan is an XML descriptor that contains the necessary dependencies in the form of both JARs and other GBeans. However, this plan file is not included in the 1.1 binary download of Geronimo. This file can be found in the Geronimo source code, but full customization using this file requires a rebuild of the configuration from the source.

For the purposes of customizing the message broker, the procedure outlined using the config.xml file in the previous section should be sufficient.

Important-Where Are the Module Deployment Plans?

In Geronimo 1.1, the module deployment plans are not included in the binary download. These files are only found in the source download because they need to be recompiled using the Geronimo build.

Deploying a Message Broker Configuration

Although changes to the config.xml only require the server to be cycled, there are situations where ActiveMQ may need to be deployed. There are two ways to deploy the ActiveMQ Message Broker in Geronimo:

• Via the command line using the Geronimo deployer

• Via the Geronimo console

Actually, any JMS 1.1–compliant broker can be deployed in Geronimo. All that is required is to create the proper GBeans to wrap it and make it part of the Geronimo lifecycle. Let’s examine these two deployment techniques.

Deploying ActiveMQ Using the Command-Line Deployer

Deploying the ActiveMQ module may be necessary if, for some reason, it is undeployed. Using the command-line deployer is rather straightforward, and there is a convenience script for this very purpose. Using the deploy.sh script in the bin directory, modules can be easily deployed via the command line. Most typically, a module will have a deployment plan, but there are cases where the deployment plan is actually contained inside the module.

Following is an example of using the deploy.sh script to stop, and then start, the ActiveMQ module. First, you must determine the name of the module you’d like to stop. This can be done using the deployer’s list-modules function, as demonstrated here:

 $ ./bin/deploy.sh --user system --password manager list-modules  Using GERONIMO_BASE:    /Users/bsnyder/geronimo-1.1 Using GERONIMO_HOME:    /Users/bsnyder/geronimo-1.1 Using GERONIMO_TMPDIR: /Users/bsnyder/geronimo-1.1/var/temp Using JRE_HOME: /System/Library/Frameworks/JavaVM.framework/Versions/1.4/Home Found 32 modules   + geronimo/activemq-broker/1.1/car   + geronimo/axis/1.1/car   + geronimo/axis-deployer/1.1/car   + geronimo/client-deployer/1.1/car   + geronimo/geronimo-gbean-deployer/1.1/car   + geronimo/hot-deployer/1.1/car   + geronimo/j2ee-deployer/1.1/car   + geronimo/j2ee-security/1.1/car   + geronimo/j2ee-server/1.1/car + geronimo/j2ee-system/1.1/car + geronimo/jetty/1.1/car + geronimo/jetty-deployer/1.1/car + geronimo/openejb/1.1/car + geronimo/openejb-deployer/1.1/car + geronimo/remote-deploy-jetty/1.1/car @ http://rattlesnake:8080/remote-deploy + geronimo/rmi-naming/1.1/car + geronimo/sharedlib/1.1/car + geronimo/system-database/1.1/car + geronimo/webconsole-jetty/1.1/car     `-> framework.war @ http://rattlesnake:8080/console     `-> standard.war @ http://rattlesnake:8080/console-standard + geronimo/welcome-jetty/1.1/car @ http://rattlesnake:8080/   geronimo/activemq/1.1/car   geronimo/client/1.1/car   geronimo/client-corba/1.1/car   geronimo/client-security/1.1/car   geronimo/client-system/1.1/car   geronimo/j2ee-corba/1.1/car   geronimo/javamail/1.1/car   geronimo/online-deployer/1.1/car   geronimo/shutdown/1.1/car   geronimo/uddi-jetty/1.1/car   geronimo/upgrade/1.1/car   geronimo/upgrade-cli/1.1/car

The list-modules function states that it found 32 modules, but only those with a preceding plus sign (+) are actually started. In this case, the goal here is to stop the ActiveMQ broker, which happens to be the first module listed. Now, the module can be stopped using its unique name:

 $ ./bin/deploy.sh --user system --password manager stop geronimo/activemq- broker/1.1/car Using GERONIMO_BASE:    /Users/bsnyder/geronimo-1.1 Using GERONIMO_HOME:    /Users/bsnyder/geronimo-1.1 Using GERONIMO_TMPDIR:  /Users/bsnyder/geronimo-1.1/var/temp Using JRE_HOME: /System/Library/Frameworks/JavaVM.framework/Versions/1.4/Home     Stopped geronimo/activemq-broker/1.1/car

Once the module has been stopped, it can easily be started again, as shown here:

 $ ./bin/deploy.sh --user system --password manager start geronimo/activemq- broker/1.1/car Using GERONIMO_BASE:    /Users/bsnyder/geronimo-1.1 Using GERONIMO_HOME:    /Users/bsnyder/geronimo-1.1 Using GERONIMO_TMPDIR: /Users/bsnyder/geronimo-1.1/var/temp Using JRE_HOME: /System/Library/Frameworks/JavaVM.framework/Versions/1.4/Home     Started geronimo/activemq-broker/1.1/car

Important-What Do the Contents of the Module Look Like?

Following are the contents of the activemq-broker module:

 activemq-broker-1.1.car activemq-broker-1.1.car/META-INF activemq-broker-1.1.car/META-INF/config.info activemq-broker-1.1.car/META-INF/config.ser activemq-broker-1.1.car/META-INF/config.ser.sha1

Notice that the module itself contains a serialized copy of the module, along with some metadata and a Secure Hash Algorithm (SHA) cryptographic file for validation purposes. This module can be found in the repository directory once the module is deployed within Geronimo.

The deployer can also be used to deploy and undeploy modules within Geronimo. As an example, to undeploy the ActiveMQ module, simply use its deployment plan, as demonstrated here:

 $ ./bin/deploy.sh --user system --password manager undeploy geronimo/activemq- broker/1.1/car Using GERONIMO_BASE:   /Users/bsnyder/geronimo-1.1 Using GERONIMO_HOME:   /Users/bsnyder/geronimo-1.1 Using GERONIMO_TMPDIR: /Users/bsnyder/geronimo-1.1/var/temp Using JRE_HOME: /System/Library/Frameworks/JavaVM.framework/Versions/1.4/Home     Module geronimo/activemq-broker/1.1/car unloaded.     Module geronimo/activemq-broker/1.1/car uninstalled.     Undeployed geronimo/activemq-broker/1.1/car

Note that undeploying any module actually deletes that module, and it cannot be recovered. To deploy the module, both the module itself and its deployment plan are required by the deployer. As long as these two items are present, they can be fed to the deployer using the deploy function:

 $ ./bin/deploy.sh --user system --password manager deploy /path/to/activemq-broker- 1.1.car /path/to/activemq-broker-plan.xml Using GERONIMO_BASE:   /Users/bsnyder/geronimo-1.1 Using GERONIMO_HOME:   /Users/bsnyder/geronimo-1.1 Using GERONIMO_TMPDIR: /Users/bsnyder/geronimo-1.1/var/temp Using JRE_HOME: /System/Library/Frameworks/JavaVM.framework/Versions/1.4/Home     Deployed geronimo/activemq-broker/1.1/car

Now, the ActiveMQ broker is deployed again and ready to be used.

The Geronimo deployer is a very powerful tool for working with modules.

The second method of deploying the ActiveMQ module is via the Web-based management console that ships with Geronimo.

Deploying ActiveMQ Using the Management Console

Once ActiveMQ is started up, its configuration can be managed from the Geronimo Web console. When you click the link under the Applications category named System Modules, the screen shown in Figure 16-2 is what will appear.

Figure 16-2: A listing of the system modules with the ActiveMQ module in a running state

This screen lists all modules that are currently deployed in Geronimo. Notice that each module’s state is listed under the column aptly named State. The ActiveMQ module is deployed as can be seen by its unique ID of geronimo/activemq-broker/1.1/car and whose state is listed as running. To stop this module, simply click the link named Stop. Upon doing so, the module will be stopped and the screen refreshed to reveal the new state of the ActiveMQ module, as shown in Figure 16-3.

Figure 16-3: A listing of the system modules with the ActiveMQ module in a stopped state

Notice the change in state for the ActiveMQ module. To start it up again, simply click the link named Start and the screen will be refreshed to again match that of Figure 16-2.

Managing ActiveMQ from the Geronimo Console

The Geronimo console has a surprising amount of functionality. One of the features within the console is the capability to add network connectors (or JMS network listeners). Figure 16-4 displays the network listeners available to be created from within the JMS Server screen.

Figure 16-4: The JMS Server screen provides the ability to manage network listeners within ActiveMQ

For example, to add a jabber network listener, simply click on the peer link and fill in the form. Figure 16-5 shows an example of this.

Figure 16-5: Adding a jabber network listener

Ensure that you give the network listener a unique name and port number so that it doesn’t clash with one that is already deployed within Geronimo. After you add the peer network listener, it is made available for use within Geronimo. Adding other types of network listeners is the same as this example but will use whatever protocol is selected.