On September 11, 2011 christopher wrote: ActiveMQ, JMS & Ajax: Involving the Browser in Event-Driven Systems

Event-driven archi­tec­ture is a big topic these days and with good rea­son. Aside from pro­vid­ing sig­nif­i­cant oppor­tu­ni­ties to increase scale and per­for­mance, given the right approach it can also make it eas­ier to divide sys­tems up into log­i­cal com­po­nents. The basic prin­ci­ple behind “event-driven” archi­tec­tures, as one might expect from the name, is asyn­chronic­ity: rather than view­ing your appli­ca­tion as a rigid sequence of processes, each being called in order as the result of a user action or sched­uled exe­cu­tion, com­po­nents pub­lish seman­tic events to which one or more other com­po­nents may be sub­scrib­ing and to which they may exe­cute logic (and per­haps pub­lish sub­se­quent events) in response. So, as you can prob­a­bly tell, like most buzz­words, “event-driven” really just tries to put a catchy name to an age-old con­cept; in this case “publish-subscribe” — but it does so, I would sug­gest, with the intent of help­ing devel­op­ers to get their head into the right space to think about how to actu­ally build sys­tems that are con­structed around such a mechanism.

In Java-land, we are for­tu­nate to have a sta­ble API with a num­ber of proven imple­men­ta­tions for publish-subscribe mes­sag­ing; namely: JMS, my favourite provider for which is Apache’s ActiveMQ. This is all well-and-good for han­dling our needs in this area on the server-side, but what about the user (sit­ting there with their browser) as an actor in this sys­tem? This ques­tion becomes very impor­tant when you con­sider that, described in abstract terms, the pri­mary use case, in my expe­ri­ence, for event-based mes­sag­ing sys­tems comes when you have users sub­mit­ting batches of work that demand inten­sive pro­cess­ing and require noti­fi­ca­tion of its completion.

In the past, one might have han­dled such sit­u­a­tions syn­chro­nously: the user would make the request through their browser, they would then sit and watch the “wheel of death” go around and around until, even­tu­ally, hope­fully, the request would be com­pleted. Of course, as soon as you got a few users doing this at the same time, your server became over­loaded and the whole thing ground to a halt. So you might have got as far as mak­ing this pro­cess­ing asyn­chro­nous, but then user instead would have to resort hit­ting the refresh but­ton and going “Is it done yet? Is it done yet? Is it done yet?” … or, worse, you would resort to that bête noire of office “noti­fi­ca­tion meth­ods”: email. Yuck!

Nowa­days, this kind of behav­iour is totally unnec­es­sary. Mak­ing the browser part of your event-driven sys­tem is a dod­dle and requires zero-alterations to your exist­ing JMS-based code (assum­ing that is what you are using). In this post, I would like to pro­vide a really basic exam­ple of how to send and receive JMS mes­sages using Active MQ’s Ajax sup­port. (Whilst there are bet­ter solu­tions on the hori­zon — most notably, in my view, Web­Sock­ets and STOMP — I have found them more than a lit­tle bit painful to inte­grate with exist­ing code to date, so I will focus on the more sta­ble solu­tion for the time being.)

Let’s begin by assum­ing that we have an appli­ca­tion that con­tains 1 “pro­cess­ing queue” and 1 “event topic”. With ActiveMQ, I can setup both a mes­sage bro­ker, the queue and the topic in a Spring appli­ca­tion con­text file:

    <amq:topic id="eventTopic" name="topic.events" />

    <amq:queue id="processingQueue" name="queue.process" />

    <amq:connectionFactory id="connectionFactory" brokerURL="vm://localhost" />

    <bean id="eventTopicTemplate" class="org.springframework.jms.core.JmsTemplate">
        <property name="connectionFactory" ref="connectionFactory" />
        <property name="defaultDestinationName" value="topic.events" />
    </bean>

Now, let’s say we have some kind of “ser­vice” that is respon­si­ble for doing this “inten­sive” asyn­chro­nous pro­cess­ing. The ser­vice will pick up mes­sages from the pro­cess­ing queue and, when the pro­cess­ing is com­plete, it will pub­lish a mes­sage to any inter­ested sub­scribers on the event topic say­ing that pro­cess­ing is com­plete. The API might look some­thing like this:

package com.christophertownson.foo;

public interface SomeService {

    void doProcessing(String msg);

}

For now, let’s make the most basic imple­men­ta­tion possible:

@Service("someService") public class SomeServiceImpl implements SomeService {

    private final JmsTemplate jms;

    @Autowired public SomeServiceImpl(@Qualifier("eventTopicTemplate") JmsTemplate eventTopicTemplate) {
        jms = eventTopicTemplate;
    }

    public void doProcessing(String msg) {
        jms.convertAndSend("We did something with your message: " + msg);
    }

}

All our imple­men­ta­tion does for now is send a mes­sage to the event topic to indi­cate that pro­cess­ing is “com­plete”. Any num­ber of com­po­nents may sub­scribe to this topic. In our case, the browser will ini­ti­ate pro­cess­ing requests by send­ing mes­sages to the pro­cess­ing queue and will sub­scribe to the event topic so that it can be noti­fied when the pro­cess­ing is com­plete and dis­play this to the user. But first we will wire up our ser­vice imple­men­ta­tion so that it will receive mes­sages sent to the pro­cess­ing queue:

    <jms:listener-container connection-factory="connectionFactory">
        <jms:listener destination="queue.process" ref="someService" method="doProcessing" />
    </jms:listener-container>

And that is it for the JMS-stuff on the server-side. Now let’s turn our atten­tion to the browser. I am going to assume that our user is inter­act­ing with our appli­ca­tion with some kind of “dash­board” web page. I am going to make my extremely beau­ti­ful (not!) dash­board look like this:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <title>Dashboard : Browser JMS Demo</title>
        <link rel="stylesheet" href="/resources/style.css" />
        <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.3/jquery.min.js" type="text/javascript"></script>
        <script type="text/javascript" src="/resources/amq_jquery_adapter.js"></script>
        <script type="text/javascript" src="/resources/amq.js"></script>
        <script type="text/javascript" src="/resources/behaviour.js"></script>
    </head>
    <body>
        <header>
            <hgroup>
                <h1>Browser JMS Demo Dashboard</h1>
            </hgroup>
        </header>
        <section id="send">
            <hgroup>
                <h1>Make something happen</h1>
                <form id="sendMessage" action="/process" method="post">
                    <fieldset>
                        <legend>Send a message to the processing queue.</legend>
                        <label for="msg">Message</label> <input type="text" id="msg" name="msg" maxlength="255" /> <input type="submit" value="Send" />
                    </fieldset>
                </form>
            </hgroup>
        </section>
        <section id="receive">
            <hgroup>
                <h1>Messages sent to the event topic</h1>
                <ol id="messages">
                </ol>
            </hgroup>
        </section>
        <footer>
            <p>Copyright &copy; Christopher Townson 2011</p><!-- yeah, that's right maaan: hands off my design! :p -->
        </footer>
    </body>
</html>

Note the use of the ActiveMQ JavaScript files on lines 8–9: these are pro­vided as part of any ActiveMQ dis­tri­b­u­tion pack­age, if you were won­der­ing where they come from. “Adapters” are also pro­vided for Pro­to­type and Dojo, but I am using JQuery in my exam­ple so opted for the JQuery adapter.

I will assume for now that you know how to setup some kind of con­troller to deliver this HTML file and will not go into the details of that here. As usual, I am using a Spring-Velocity setup to achieve this. How­ever, in this instance, that is not impor­tant because “con­trollers” are not really being used at all in this example.

So, let’s take a look at that behaviour.js file ref­er­enced on line 10. This is where I am putting the impor­tant stuff to actu­ally send and receive JMS messages …

function init() {
    var amq = org.activemq.Amq;
    amq.init({
        uri: 'amq',
        logging: true,
        timeout: 20
    });

    amq.addListener('theBrowser', 'topic.events', function(msg) {
        $('#messages').append('<li>' + msg.textContent + '</li>')
    });

    $('#sendMessage').submit(function() {
        var msg = $('#msg').val();
        amq.sendMessage('queue.process', msg);
        $('#sendMessage').after('<p id="ack">Sent message: "' + msg + '"');
        $("#ack").fadeOut(2000, function () {
            $("#ack").remove();
        });
        return false;
    });
}

$(document).ready(init);

Let’s go through this step-by-step …

  1. On lines 2–7, we instan­ti­ate and ini­tialise ActiveMQ.
  2. On lines 9–11, we setup lis­ten­ing for mes­sages on the event topic, pass­ing a client ID, the name of the des­ti­na­tion we want to lis­ten to (i.e. the event topic in this case) and a call­back to exe­cute when a mes­sage is received … I am just going to add the mes­sage to a list on the page for now.
  3. On lines 13–21, I inter­cept mes­sage form sub­mis­sions, send­ing a JMS mes­sage rather than con­tin­u­ing with a nor­mal HTTP form sub­mis­sion. As a lit­tle piece of sugar, I have a fade ani­ma­tion alert to say that the mes­sage has been sent after you sub­mit the form. (In real life, you should make this degrade grace­fully by hav­ing a han­dler on the server-side to send the JMS mes­sage and mak­ing your JavaScript code per­form an asyn­chro­nous request to that han­dler, rather than send­ing the mes­sage directly as I am doing here.)

The final piece of the jig­saw puz­zle is the ActiveMQ AjaxServlet. This is part of the activemq-web, which you will need to declare as a depen­dency in addi­tion to the usual activemq-core. Then we just need to declare this servlet in our web.xml as follows:

    <servlet>
        <servlet-name>amq</servlet-name>
        <servlet-class>org.apache.activemq.web.AjaxServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>amq</servlet-name>
        <url-pattern>/amq/*</url-pattern>
    </servlet-mapping>

And, Lo and behold! Our dash­board page receives event noti­fi­ca­tions in the page with­out reload. Isn’t JavaScript magic?! Now, of course, there are all kinds of sub­tleties and sophis­ti­ca­tions that one can intro­duce, includ­ing mes­sage fil­ter­ing, brows­ing, con­ver­sion and so on. How­ever, first you need to con­sider care­fully what type of mes­sages you are send­ing to the browser. Ide­ally, in my view, these should nor­mally only con­sti­tute events that lead a call­back han­dler to update the data dis­played about some under­ly­ing per­sis­tent entity (because you don’t get these mes­sages again when the page is reloaded, obvi­ously). Also, there is much to con­sider about the for­mat of such mes­sages: using JSON as a JMS text mes­sage for­mat, rather than map or object mes­sages, makes a lot of sense when you look at things from this angle because it is then very easy to serialize/deserialize mes­sages in both the browser and in a MessageConverter in your Java code. Finally, as with all event-driven sys­tems, pay very close atten­tion to the point in time at which mes­sages are sent. For exam­ple, if, as I sug­gest, you are using these events to trig­ger an update to dis­played per­sis­tent state, you need to be damned sure that this state has actu­ally been updated before you pub­lish the “update your dis­play” event.

You can down­load the Maven project with the com­plete code for this demo. You can, of course, dis­trib­ute and change it in any way you like … but do share the results if you do. Enjoy!

On July 25, 2011 christopher wrote: Delineating Architectures By Extending Spring Stereotypes

In ver­sion 2.5, released in Novem­ber 2007, Spring intro­duced annotation-based appli­ca­tion con­text con­fig­u­ra­tion ori­ented pri­mar­ily around the org.springframework.stereotype pack­age. Clearly, anno­ta­tions have been around in the Java and Spring world for quite some time now. Leav­ing aside the ques­tion of the pros and cons of anno­ta­tions them­selves for another time, it occurs to me that most devel­op­ers still tend to treat them as if they were a slightly mys­te­ri­ous form of code: they are reluc­tant to imple­ment their own and tend to use those that exist in only the most nor­ma­tive and mun­dane ways. There­fore, I would like to go through a very sim­ple exam­ple of how to take advan­tage of Spring’s stereo­type anno­ta­tions to sup­port and enhance your own appli­ca­tion architecture.

Out of the box, Spring pro­vides 4 basic archi­tec­tural stereo­types used com­monly by n-tier applications:

@Component
Used to indi­cate that the anno­tated class encap­su­lates a generic appli­ca­tion com­po­nent of an essen­tially unde­fined type.
@Repository
Used to indi­cate that the anno­tated class enca­pu­lates access to a sys­tem of record (e.g. a data accessor).
@Service
Used to indi­cate that the anno­tated class encap­su­lates a “ser­vice”; com­monly defined in terms of an API the under­ly­ing imple­men­ta­tion of which organ­ises sequences of lower-level tech­ni­cal logic into a call sequence within a trans­ac­tion bound­ary with the aim of deliv­er­ing a func­tional requirement.
@Controller
Used to indi­cate that the anno­tated class is a con­troller within an MVC application.

With the excep­tion of the @Component anno­ta­tion (which is the base type used to deter­mine that a class is a Spring bean dur­ing con­text ini­tial­i­sa­tion) and the @Controller anno­ta­tion (which is key when using Spring’s MVC sup­port), the spe­cial­i­sa­tions indi­cated serve lit­tle func­tional use on the whole. In most appli­ca­tions, it would be absolutely equiv­a­lent to mark a class as @Component in pref­er­ence to @Service, for exam­ple. How­ever, it need not be that way as not only can this meta­data be utilised for func­tional ends but also extend­ing these stereo­types pro­vides an excel­lent way to clar­ify the archi­tec­tural role of a given unit of code when none of the pre-existing spe­cial­i­sa­tions are appropriate.

For exam­ple, in my lit­tle hobby-project “Appo­site” (which I have men­tioned in pre­vi­ous posts), I have a num­ber of require­ments around ensur­ing state on appli­ca­tion startup (i.e. bootstrapping).

Now, boot­strap­ping is a clas­sic “non-functional” prob­lem (in so far as it usu­ally does not pro­vide func­tion­al­ity to an end user, merely ensur­ing that the appli­ca­tion is in an ade­quate state to be capa­ble of sub­se­quently deliv­er­ing this) … and, by no coin­ci­dence, it is also the kind of thing that there­fore also often gets left to the end and piled into some unread­able file that suf­fers from vir­u­lent bit-rot.

Alter­na­tively (and a slight improve­ment), the more organised-of-mind will retain the basic script­ing approach but struc­ture it via the use of the Tem­plate Pat­tern:

// abstract class with public *final* method defining algorithm, the individual methods for which may or may not also be abstract
public abstract class AbstractTemplatePattern {

    public final void doSomething() {
        doStepOne();
        Foo resultOfStepTwo = doStepTwo();
        doStepThree(resultOfStepTwo);
    }

    protected void doStepOne() {
        // maybe a default implementation here ...
    }

    protected abstracted Foo doStepTwo();

    protected abstracted void doStepThree(Foo foo);

}

How­ever, whilst this is slightly prefer­able, it is still not really ideal for the boot­strap­ping use case. This is because we expect the “algo­rithm” (i.e. “what needs to be done when boot­strap­ping”) to change with some fre­quency … this is usu­ally the cause of the main­te­nance night­mares that can some­times occur around such activ­i­ties. Whilst scripts can become illeg­i­ble under such cir­cum­stances, the tem­plate pat­tern becomes dif­fi­cult to main­tain because it is pre­cisely intended to rep­re­sent a sta­tic algo­rithm with chang­ing imple­men­ta­tions, whereas our boot­strap is the inverse: a chang­ing algo­rithm with sta­tic imple­men­ta­tions. In both cases, the code unit(s) involved are become sub­ject to change and, con­se­quently, bugs are liable to be intro­duced in the process of change. Asso­ci­ated tests may start to fail, and col­lab­o­ra­tors or sub­classes may be affected in all kinds of ways that are, to put it bluntly, a painful waste of time to deal with.

To talk in terms of pat­terns again, what we really want here are com­mands and a com­mand execu­tor. What we want to be able to do is sim­ply “drop-in” a new chunk of “stuff to do” and be com­fort­able in the knowl­edge that it will get done.

NB. It is not nec­es­sary to cre­ate your own inter­face for the com­mand pat­tern: java.lang.Runnable should always suf­fice, in my view. Use the stan­dard libraries when­ever possible!

We could, of course, use the JSR-250 @PostConstruct anno­ta­tion, sup­ported by Spring, wher­ever we wanted to do some kind of “boot­strap­ping”. How­ever, if we do so in an ad hoc fash­ion, (a) this logic becomes scat­tered through­out the code­base under generic meta­data that makes it more dif­fi­cult to iso­late in the process (b) frag­ment­ing this respon­si­bil­ity and (c) hin­der­ing re-use. There­fore, my approach was as follows …

First, cre­ate an org.apposite.command pack­age as the name­space for all code units that con­sti­tute a com­mand (i.e. they are an imple­men­ta­tion of java.lang.runnable and achieve some given tech­ni­cal require­ment (i.e. guar­an­tee state on com­ple­tion or throw an IllegalStateException on post-condition failure).

Sec­ond, extend the @Component stereo­type to intro­duce a new spe­cial­i­sa­tion, which I decided to call @StartupCommand:

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Component
public @interface StartupCommand {

    String value() default "";
}

Sec­ond, imple­ment a java.lang.Runnable for each “thing” that needs to be done on startup. For exam­ple, in Appo­site, for var­i­ous rea­sons I will not bore you with here, I want to “reg­is­ter” the run­time instance that is in the pro­ces of start­ing up with a repository:

@StartupCommand public class RegisterRuntimeInstanceCommand implements Runnable {

    private final AppositeRuntimeInstanceDAO ridao;

    private final String riname;

    @Autowired public DetermineRuntimeInstanceCommand(@Value("${apposite.runtime.instance.name}") String instanceName, AppositeRuntimeInstanceDAO appositeRuntimeInstanceDAO) {
        riname = instanceName;
        ridao = appositeRuntimeInstanceDAO;
    }

    @Override public void run() {
        try {
            InetAddress localhost = InetAddress.getLocalHost();
            ridao.insertOrUpdate(riname, localhost.getHostName(), localhost.getHostAddress());
        } catch (Exception e) {
            throw new IllegalStateException("Runtime instance registration failure", e);
        }
    }

}

Now, for the com­mand execu­tor, we needn’t do any­thing nearly so fancy: we can encap­su­late our boos­t­rap logic (@PostConstruct) into a nor­mal Spring bean which, for the sake of argu­ment, I am going to call a boot­strap “service” …

public interface BootstrapService {

    void startup();

}

My imple­men­ta­tion of which is as follows:

@Service public class BootstrapSpringService implements BootstrapService {

    private static final Logger LOG = getLogger(BootstrapSpringService.class);

    private boolean bootstrap = true;

    private List<Runnable> startupCommands = new ArrayList<Runnable>();

    private final PlatformTransactionManager txmanager;

    @Autowired public BootstrapSpringService(PlatformTransactionManager transactionManager) {
        txmanager = transactionManager;
    }

    @Autowired public void setBootstrap(@Value("${apposite.bootstrap}") boolean bootstrap) {
        this.bootstrap = bootstrap;
    }

    @Autowired(required = false) public void setCommands(List<Runnable> commands) {
        for (Runnable command : commands) {
            if (AnnotationUtils.findAnnotation(command.getClass(), StartupCommand.class) != null) startupCommands.add(command);
        }
    }

    // NB. we cannot use @Transactional here because this is called *before* the creation of the transaction proxies
    @PostConstruct @Override public void startup() {
        if (bootstrap) {
            LOG.info("Bootstrapping Apposite ...");
            TransactionStatus tx = txmanager.getTransaction(new DefaultTransactionDefinition());
            for (Runnable command : startupCommands) {
                LOG.info("Running startup action: " + command.getClass().getName());
                long start = System.currentTimeMillis();
                command.run();
                LOG.info(command.getClass().getName() + " completed in " + (System.currentTimeMillis() - start) + "ms");
            }
            txmanager.commit(tx);
            LOG.info("Bootstrap complete.");
        }
    }

}

As a result, I can very eas­ily deter­mine what is sup­posed to hap­pen at startup and where. More­over, nei­ther the boot­strap “ser­vice” nor any of the indi­vid­ual com­mands will be sub­ject to change when, as I expect, addi­tional boot­strap logic is added in future. As a fringe ben­e­fit, the intent of the code is described with greater seman­tic force through the util­i­sa­tion of a spe­cific spe­cial­i­sa­tion annotation.