##
## $Rev$ $Date$
##

Overview
========

This document explains how to build ActiveMQ 4 support for Geronimo 1.1.x.  It is
not intended to be comprehensive on how to build an assembly with this support,
just enough to compile the modules and then install them into an official
assembly.

These modules provide functionality for basic/normal J2EE usage, but there are some
issues with console integration, and could be other issues as well.


Requirements
============

 * Maven 1 (last know working 1.1-beta-2): http://maven.apache.org/maven-1.x/start/download.html
 * Ant (latest should work, used by install bits)
 * JDK 1.4+
 * Subversion 1.2+ (1.4 recommended)
 * Some patience, maybe some beer


Preparing the Workspace
=======================

Several modules need to be checked out of source control to build AMQ 4 support.
The examples below use the Geronimo 1.1.1 release tag, but other 1.1.x *might*
work too.

    svn co http://svn.apache.org/repos/asf/geronimo/server/tags/1.1.1 server-1.1.1
    cd server-1.1.1
    svn co http://svn.apache.org/repos/asf/geronimo/server/branches/1.1/repository
    svn co http://svn.apache.org/repos/asf/geronimo/sandbox/g1.1-activemq4 activemq4

This will pull the server's tree, some additinal artifacts from the 1.1 branch,
since it appears that some artifacts are no longer on any public m1 repos, and
fetches the modules for ActiveMQ 4 support.


How to Compile
==============

Patch the server's build to it has better chances of actually working, plus includes
some bits to compile to new activemq4 stuff:

    patch -sp0 < activemq4/maven1-build.diff

Build the required modules:

    maven install-local-repository new1 new3 new4 activemq4 -Dmaven.test.skip=true

At this point, if the build reported "BUILD SUCCESSFUL" successful you should
have functional AciveMQ4 modules to install into your server.

If not... well, here is where the fun begins.  May need to run a few module
builds in isolation.  Sorry, no good answer here... the 1.1 build is a mess :-(

If you spend more than a few hours trying to get this stuff to build... you may
consider spending the time it might take for you to finish and upgrade to G 1.2 ;-)


How to Install
==============

Once all of the modules are built you can use the install.xml Ant script to
install the modules into the server's repository.

    ant -f activemq4/install.xml

This assumes you are using Geronimo 1.1.1 and have the assembly extracted
as a peer to the activemq4 directory.

To use a specific installation:

    cd activemq4
    ant -f install.xml -Dgeroniom.home=/where/g/is

This will install all of modules and dependencies into the server's repository.


How to Use
==========

To use the new modules, you need to edit the server's var/config/config.xml
and comment out the current activemq modules and add new modules for the amq4
bits:

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

<module name="geronimo/activemq/1.1.1/car"/>
-->

<module name="geronimo/geronimo-activemq-broker-config/1.1.1/car"/>

<module name="geronimo/geronimo-activemq-ra-config/1.1.1/car"/>
---->8----

And then update your plans to use the new external-path for the resource adapter:

----8<----
<ext-module>
    <connector>someJmsResource</connector>
    <external-path>geronimo/geronimo-activemq-ra/1.1.1/rar</external-path>
    <connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.1">
        <resourceadapter>
        ...
---->8----

If you run w/the old resource adapter you will probably get invalid wire format
looking ERROR messages from AMQ bits.

Also you will need to update admin objects to use the correct class names,
like org.activemq.message.ActiveMQQueue.


Known Issues
============

When shutting down the server a ClassNotFoundException is throw from AMQ:

<snip>
Stopping server...
Exception in thread "ActiveMQ Transport: tcp://localhost/127.0.0.1:61616" java.lang.NoClassDefFoundError: edu/emory/mathcs/backport/java/util/concurrent/ConcurrentHashMap$Values
        at edu.emory.mathcs.backport.java.util.concurrent.ConcurrentHashMap.values(ConcurrentHashMap.java:1012)
        at org.apache.activemq.transport.ResponseCorrelator.onException(ResponseCorrelator.java:106)
        at org.apache.activemq.transport.TransportFilter.onException(TransportFilter.java:96)
        at org.apache.activemq.transport.TransportFilter.onException(TransportFilter.java:96)
        at org.apache.activemq.transport.WireFormatNegotiator.onException(WireFormatNegotiator.java:147)
        at org.apache.activemq.transport.InactivityMonitor.onException(InactivityMonitor.java:150)
        at org.apache.activemq.transport.TransportSupport.onException(TransportSupport.java:97)
        at org.apache.activemq.transport.tcp.TcpTransport.run(TcpTransport.java:150)
        at java.lang.Thread.run(Thread.java:613)
</snip>

Adding/managing resources via the console will not work.  The console app needs
to be updated to use the new modules.

Shutdown from the console might spit up some exceptions for the same reason as above.