If you want to find out more about this sample read on.

Introducing the sample

The sample is based on the famous address book from the axonframework project. We reuse the axon sample and create a rest like interface that returns json to the clients. The source code is in the rest-ui project within the axonframework source tree under samples. This project also contains the listener code for the Contact and Address based events. The listeners listen for events and publish content from these events to the redis pub/sub mechanism. More on this in the later sections.

The other part of the sample is a node.js application. This application makes use of the rest api to obtain the data via http requests. Events about data changes are received through redis, using the pub/sub mechanism. The node.js application is available on Github. If you want to follow along, you can find the sources here:

https://github.com/jettro/axon-addressbook-nodejs

http://code.google.com/p/axonframework/source/browse/trunk#trunk%2Fsample%2Faddressbook%2Frest-ui

The following screen dump gives you an idea about the application.

In the screen you see the list of contacts. You can add a new contact, change the name of a contact and add addresses to contacts. On the right you see the messages pane. Here you receive messages about new contacts that have been created, changed or deleted.

Now let us have a look at some of the code. We start with the java backend and then continue with the node.js part.

The java part of the sample

Numerous blogs have been written about rest based clients using spring mvc. Therefore I do not want to lose to much time in that area. Most important spring configuration is within the web.xml and the dispatcher-config.xml. In the web.xml we configure that every request is going to the spring dispatcher. We do not have status resources, only json responses. Within spring we make use of annotation to configure the beans. To be able to respond with json we make us of Jackson to transform beans into json objects. All pretty straightforward spring. Check the config file for yourself if you want to see how it works.

Next step is the controller that handles all the requests.

Handling requests in the Cntroller

The Controller handles the following requests:

• /contacts : GET, returns the list of all contacts
• /contacts : POST, creates a new contact
• /contacts : PUT, changes an existing contact
• /contacts : DELETE, removes a contact
• /contacts/{identifier} : GET, returns the details of a contact
• /contacts/{identifier}/address : PUT, creates a new address or updates an existing one based on address type
• /contacts/{identifier}/address : DELETE, removes the address of provided type

Let us have a look at one of the requests to show the flow. For example we take the request for details. The following code block shows the complete method.

@RequestMapping(value = "{identifier}", method = RequestMethod.GET)
public @ResponseBody Map<String, Object> details(@PathVariable String identifier) {
    List<AddressEntry> addressesForContact = repository.findAllAddressesForContact(identifier);
    String name;
    if (addressesForContact.size() > 0) {
        name = addressesForContact.get(0).getName();
    } else {
        name = repository.loadContactDetails(identifier).getName();
    }
    Map<String, Object> map = new HashMap<String, Object>();
    map.put("addresses", addressesForContact);
    map.put("identifier", identifier);
    map.put("name", name);
    return map;
}

The RequestMapping annotation tells spring which requests need to be mapped to this method. The controller already maps all /contacts to this controller. The {identifier} now maps everything with a url like /contacts/{identifier} to this method, as long as it is a GET request. This identifier is also used as a parameter for the method. With the @PathVariable we tell spring to take the value for this parameter from the url or Path that was requested. The final annotation in the method declaration is the @ResponseBody. This tells spring to use the return value as the response body, so not as the name of the view to use. We have already configured to use jackson to transform the response body into json. In the code of the controller you see we return a map with three objects in it. A list of addresses, an identifier of the contact and the name of the contact. The json coming out of this is:

{
"name":"Jettro",
"addresses":[
{
"name":"Jettro",
"identifier":"82b4fef5-3389-440d-8893-6831a64e200d",
"addressType":"PRIVATE",
"streetAndNumber":"Feyenoordlaan 010",
"zipCode":"3000AA",
"city":"Rotterdam"
}],
"identifier":"82b4fef5-3389-440d-8893-6831a64e200d"
}

That is what you need to know about the rest api that I have created. If you want to have a look at the controller, check here. The next step is about the listeners that listen for axon events related to the contacts and addresses and store information in redis.

Listening for events

We register listeners with axon for the contact related events as well as address related events. This is very easy with the annotations provided by the axonframework. The following code block shows how we register an event listener for the ContactCreatedEvent.

@EventHandler
public void handleContactCreatedEvent(ContactCreatedEvent event) {
    ContactEntry value = new ContactEntry();
    value.setName(event.getName());
    value.setIdentifier(event.getContactIdentifier());
    Message<ContactEntry> message = new Message<ContactEntry>("contact-created", value);
    publisher.publish(message);
}

Notice the @EventHandler annotation. This registers the listener with axon. As you can see we take the information from the provided event and put it in a Message object. The message object contains a type and the content. The type can be used at the receiving side to better understand how to handle the received event. The publisher is auto injected by spring. In my case it is a redis publisher.

Publishing to redis

A library to talk with redis is jedis. Jedis makes use of a pool which is configured in spring. Check the listener-context.xml to see how it works. Jedis does not have the most obvious api but it works. The following code block shows how a message is published to redis.

public void publish(Message<?> message) {
    StringWriter writer = new StringWriter();
    try {
        mapper.writeValue(writer, message);
    } catch (IOException e) {
        logger.warn("Problem while writing ContactEntry to a string writer", e);
        return;
    }

    Jedis jedis;
    try {
        jedis = jedisPool.getResource();
    } catch (JedisConnectionException e) {
        logger.debug("Could not obtain redis connection from the pool");
        return;
    }
    try {
        jedis.publish("nl.axonframework.examples.addressbook", writer.toString());
    } finally {
        jedisPool.returnResource(jedis);
    }
}

The code is not very complicated. The important part here is that we use a jackson provided ObjectMapper to map the provided message to a json representation. Then you can see the nice jedis api at work. As you can see we publish a message to a queue. Our node.js client will subscribe to this queue. That is have the redis publish/subscribe works. Not very hard is it?

That is it for the java side. We now know how to get data using the rest api and we know where to get information about events that take place. Let us move on to the node.js side of the application.

The Node.js part of the sample

I do not want to go in setting up a node.js project. Do not want to explain all the different libraries that I use. I have written other blog posts on node.js that I do not want to copy. The most important one is this:

http://blog.jteam.nl/2011/04/18/learning-node-js/

The node.js project uses 4 libraries:

• express – doing the mvc part of the web application
• jade – view templating
• now – server push to the client (will explain this in a bit more detail)
• redis – for redis interaction




Project layout

The public folder contains all the client related files like javascript, css and images. I will explain one file in here later on when discussing node.js. The test folder contains the test for the ContactRepository. Using this test helped me to verify that the integration between the java backend and the node.js application is working without having to start the application and go through the browser to check all requests. The views folder contains all the jade templates. Check mentioned blog post to find more information on jade. The app.’s initializes the application and maps all possible requests to methods in the ContactController. The controller knows where to get the data from and what page to render. The repository is responsible for obtaining data from the rest api on the java side.

Initializing the node.js application

As mentioned the app.js is the start of the application. Let us have a look at the different parts.

var ContactController = require('./ContactController');
var repository = require('./ContactRepository').createRepo('localhost',8080);
var contactController = new ContactController(repository);

This part initializes our components. We will have a look at the createRepo method later on. But notice that we initialize the controller with an instance of the repository.

app.get('/', contactController.listContacts);
app.get('/contact/new', contactController.newContactShowForm);
app.post('/contact/new', contactController.newContactPostForm);
app.get('/contact/:identifier',contactController.contact);
app.get('/contact/:identifier/edit',contactController.changeContactShowForm);
app.post('/contact/:identifier/edit',contactController.changeContactPostForm);
app.get('/contact/:identifier/delete',contactController.deleteContactShowForm);
app.post('/contact/:identifier/delete',contactController.deleteContactPostForm);
app.get('/contact/:identifier/address/new',contactController.newAddressShowForm);
app.post('/contact/:identifier/address/new',contactController.newAddressPostForm);
app.get('/contact/:identifier/address/:addressType/edit',contactController.changeAddressShowForm);
app.post('/contact/:identifier/address/:addressType/edit',contactController.changeAddressPostForm);
app.get('/contact/:identifier/address/:addressType/delete',contactController.deleteAddressShowForm);
app.post('/contact/:identifier/address/:addressType/delete',contactController.deleteAddressPostForm);

These are all the possible requests. The urls are easy to understand. As you can see, all urls are mapped to a method of the contactController

var Now = require('now');
var everyone = Now.initialize(app);

var redis = require("redis"),
    client = redis.createClient();

client.on("error", function (err) {
    console.log("Error %s", err);
});

client.on("message", function (channel, message) {
    everyone.now.receiveContact(message);
});
client.subscribe("nl.axonframework.examples.addressbook");

This is the harder bit. This has to do with receiving messages using the redis pub/sub mechanism and sending it to all connected clients using the nowjs library. I’ll discuss the now.js part later on.

Request handling

By using the repository object the controller becomes very easy. We only have to obtain the right data and render the right view. The most basic method is showing a list of contacts. The following code block shows the complete method.

ContactController.prototype.listContacts = function(req, res) {
    repository.listContacts(function(contacts) {
        res.render('index', {locals: {contacts: contacts, nowjs: true}});
    });
};

Notice that we use a callback that is provided to the repository listContact method. Check that we provide the list of contacts to the view, together with a second parameter called nowjs. Remember this, on this page we enable nowjs, meaning that we can receive messages when looking at this page. Other methods are similar, have a look at the method that handles submitting a form to create a new contact.

ContactController.prototype.newContactPostForm = function(req, res) {
    repository.newContact(req.body.new_name, function(code, message) {
        if (code == "ok") {
            res.redirect("/");
        } else {
            res.render('newcontact', {locals: {error:message}});
        }
    });
};

In line 2 we obtain the form parameter new_name from the request body. Than we create a new contact. The callback method expects a code indicating whether the submission of the new contact was ok. If not, we render the form again with the error message. This happens when we try to create a contact with a name that already exists. The following image shows the screen with an error message.

Next up is the communication with a rest based application

The Repository as a client to a rest application

During the initialization of the application I already mentioned the createRepo method of the ContactRepository. The following code block shows the method. As you can see it initializes a repository with the default values for host and port.

ContactRepository.createRepo = function(host, port) {
    var repo = new ContactRepository();
    repo.host = host;
    repo.port = port;
    return repo;
};

Again most of the interaction with the backend is the same. Therefore I use the create contact again as an example. I have created tests for all the repository methods. Let us have a look at the test first.

function testNewContact() {
    logTestName("New contact");
    repository.newContact("My Test", function(code, message) {
        assert.equal("ok", code, "This should be no problem and an ok should be returned: " + code);
        // Check if the amount of contacts is increased
        repository.listContacts(function(contacts) {
            assert.equal(numContacts + 1, contacts.length, "Number of contacts is not right, create did not work: " + contacts.length);
            testAddAddress();
        });
    });
}

Notice that we check the return code and that the amount of contacts is increased. The following code block shows the implementation of the method of the repository.

ContactRepository.prototype.newContact = function(name, callback) {
    var opts = createHttpRequestOpts('/contacts', 'POST');

    var req = http.request(opts, function(res) {
        res.setEncoding('utf8');
        res.on('data', function(data) {
            if (res.statusCode != 200) {
                console.log(data);
                callback('error', 'Maybe the name is already taken?');
            } else {
                callback('ok', 'The new contact has been send')
            }
        });
    });

    var contact = {};
    contact.name = name;

    req.write(JSON.stringify(contact));
    req.end();
};

function createHttpRequestOpts(path, method) {
    return {
        host: host,
        port: port,
        path:path,
        headers:{'Accept':'application/json','Content-Type':'application/json'},
        method: method
    };
}

I use the nodejs provided http request. Within the help function the opts object is created with the host, port, path, method and the headers. The headers are important to request json. Of course we provide a callback to handle the http response. Everything not 200 is an error as a response code. Here we call the provided callback to the repository method with the ok or error code. At the end of the method we do the actual request creation with the json request.

The final bit is the server push using the now.js library.

Server push using now.js

Node.js comes with a socket.io library. This makes server push very easy. Still it can be a lot easier. That is when using now.js. Now.js enables you to call methods on the client that are actually on the server and vise versa. Let us have a look at the code for sending messages to the client when a redis event is received again.

var Now = require('now');
var everyone = Now.initialize(app);
client.on("message", function (channel, message) {
    console.log("Received message: %s", message);
    everyone.now.receiveContact(message);
});

The important part here is the initialization of now and the line with everyone.now.receiveContact. Now we will call the connected clients method receiveContact and provide the message. Of course we need some client code for this. This code is available in the local.js file in the public folder.

$(document).ready(function() {
    now.receiveContact = function(data) {
        var message = JSON.parse(data);
        var toWrite;
        switch(message.type) {
            case 'contact-removed':
                toWrite = "Contact removed";
                break;
            case 'contact-created':
                toWrite = "Contact with name " + message.content.name + " created";
                break;
            case 'contact-changed':
                toWrite = "Contact changed name to " + message.content.name;
                break;
            case 'address-created':
                toWrite = "Added address of type " + message.content.addressType + " to contact " + message.content.name;
                break;
            case 'address-removed':
                toWrite = "Removed address of type " + message.content.addressType + " to contact " + message.content.contact.name;
                break;
        }
        $("#messages").prepend("<div>" + toWrite + " </div>");
    };
});

As you can see, we construct the message based on the type of the message and prepend a new div within the #messages div. Really that is all there is to it.

Last remarks

That is it. Again a long blog item. Hope you got some new knowledge out of it. Feel free to post comments if you have questions or even better improvements.

Read on to find out more…

CQRS

I will refrain from giving a detailed description about CQRS. There is a lot of information to be found, of which this article by Greg Young, and Udi Dahan’s article here are must-reads for all who want to know more about CQRS.

In my eyes, the very simple concept of CQRS opens up very powerful opportunities in terms of application maintenance, testing, integration and scalability. But don’t let all these opportunities fool you: with a basic setup, using CQRS is not any more complex than the layered architecture most developers are used to. However, when an application grows (which in the end, all applications do), the complexity of a layered-architecture increases rapidly and definitively becomes more complex than one based on CQRS.

Why? Simply because CQRS makes a separation between Command and Query processing in an application. Typically, each of those aspects has to deal with different functional and technical requirements. If you merge the two, you would have to deal with all these aspects in a single component. That makes the component unnecessarily complex.

Axon Framework

When building an application according to the CQRS pattern, you will most likely have to build some components that actually have nothing to do with the functional requirements you have. This plumbing is the reason I started the Axon Framework. The goal of the Axon Framework is to provide the most common building blocks found in CQRS based architectures, such as a Command Bus, Event Bus, Event Sourcing repositories, etc.

Axon makes it easy to choose the type of configuration you would like to use. Whether you want to use event sourcing or not, eventual consistency or full transactional, or maybe a combination of the two, Axon makes it a matter of configuration to switch between these options. You can set up a complete baseline architecture within an hour and get started with the actual business logic.

I have released the 0.4 version little over a month ago and am working hard to get the 0.5 version out. This version will be nearly feature-complete.

You can find more information about Axon Framework and track my progress on axonframework.org.

InfoQ interview

A few weeks ago, InfoQ approached me for an interview. After some emailing between myself and InfoQ author Josh Long, InfoQ published an interview with me about the Axon Framework. You can read the interview here: http://www.infoq.com/articles/cqrs_with_axon_framework

Presentations

The coming month, I will be giving 2 presentations about CQRS and the Axon Framework. The first is on JTeam’s tech evening on May 6th. The tech meeting starts at 16:00 in JTeam’s head office in Amsterdam. See www.jteam.nl/contact.html for directions. Please subscribe to the event using the contact form if you like to join this free event.

My next presentation, about the same topic is on the Domain Driven Design Netherlands User Group (www.DDDnl.org). In the May meetup we will spend time on CQRS and I will give a presentation about the practical aspects of CQRS and Axon. The meetup is held on May 11th at JTeam’s office in Amsterdam. The meetup starts at 18:00. If you want to join, send an email to info@dddnl.org to confirm your attendance.

CQRS and Axon Workshop

If a 1 hour presentation is not enough of an immersion for you, I will also give a CQRS Workshop soon. On may 21st, JTeam organizes a one-day workshop where you will learn to apply CQRS in your own projects. The workshop is very much focused on practical aspects and making pragmatic decisions when it comes to the different possibilities CQRS offers. We will cover the different building blocks in a typical CQRS architecture, as well as testing, and scalability scenario’s.

For more information, visit the workshop page: http://www.jteam.nl/training/workshop/cqrs-axon-framework-training-workshop.html.

Conclusion

So, if you’re wondering why I haven’t been blogging much lately, you can blame the Axon Framework. Open source is nice, but it just takes a lot of time. Time I gladly spend…

What does grails do in this picture. Isn’t grails about rapid application creation? Well, yes. It is a good platform to rapidly create web applications using the groovy language and still be able to use existing libraries. Personally I really like the Gorm library of grails. I think that gorm would be an excellent choice to wrap the query datasource. Of course the gsp technology and the groovy language are nice to have when working with the web applications as well.

In this blog post I’ll discuss the integration between grails and axon. How can we create an application with grails that makes use of Axon to implement CQRS. I’ll discuss the way to create commands and send these to axon. I’ll also discuss responding to events coming from axon. First I have to show some aspects of a grails project that you need to know before you can use Axon. I’ll try to take you with me when I take the steps to create a good integration between Axon and Grails.

Sources

The sample I am using is the same sample that is provided by axon with a flex client. The AddressBook is used to show the different possibilities of axon and a client. You can create contacts, and register addresses of a certain type for contacts. You can register home, work and holiday addresses.

You can find the sources of the sample at github:

http://github.com/jettro/axon-addressbook-grails

Configure grails to use Axon

Grails has a pretty elegant way to configure libraries to be used by the project. You can make grails look for libraries in remote maven repositories as well as your local repository. I need to enable the local repository since I am working with a SNAPSHOT version of axon at the moment of writing.

Each normal grails project contains a folder grails-app/conf. In this folder is a file called BuildConfig.groovy. This file contains the build configuration, you did not see that one coming did you? In this file there is a closure called grails.project.dependency.resolution. Within this closure you can configure the repositories and the dependencies. As I said before you need to uncomment the mavenLocal() and add the following two lines to the dependencies.

compile 'org.axonframework:axon-core:0.5-SNAPSHOT'
runtime 'com.thoughtworks.xstream:xstream:1.3.1'

I did not get the grails project to work in a way that SNAPSHOT dependencies are updated. So if I compile a new version of axon, I manually delete the library in the grails cache. The libraries are stored in the ivy cache on your computer. In my case the jars are in the folder:

<user_home>/.ivy2/cache/org.axonframework/axon-core/jars/axon-core-0.5-SNAPSHOT.jar

Structure of the project

If you create a normal grails application you usually stick to the conventional project setup. Within the grails-app folder you have folders for domain classes, controllers, services, and others.

The domain model

When creating a CQRS application the domain becomes a different beast. It is the domain that commands act upon and the events are generated by the domain. For now let us call the domain from CQRS perspective the core-domain and the grails domain classes the query domain. The query domain resides in the normal grails location. Each grails project also contains a src folder with the groovy and java classes. This is where we will store the core domain.

A very important thing to stick in your brain is that the controllers must not use the standard way of grails to save domain objects. If you would do that, you only update the query database and no commands are created and send to the Axon backend.

Grails services and axon commands

We interact with axon by making use of command objects. To make this easy from the grails perspective we create a service class around the command creation. This makes it easier to create a transactional scope and to have just one location where we actually send data to axon. This service is more like a proxy to the Axon command bus.

Grails controllers

The controllers are normal grails controllers, they make use of services to send data to the backend and they use gorm to query the data.

Axon event listeners

The event listeners are used to receive updates about the core domain and reflect this in the query domain. The listeners make extensive use of gorm to update data in the query domain.

The following image gives you an idea about the directory layout of the project.

Scaffolding

One of the nice options of grails to create applications very fast is to use scaffolding. When using axon this is still possible, but only to do the first steps very fast. I recommend creating your own views and controllers when you know what you want and you need to create better useable screens. You cannot use the scaffolding controllers. They would only use the query domain. We need to call the services from the controllers. I do generate the controllers and then adjust them to my needs.

To get an idea what I reused from the generated controllers, let us have a look at the changes I made to the generated controller methods. For now I did not change views, so they are still using the scaffolding versions. Beware that this is not a final solution. To give you an idea, registering an address for a contact means that you have to manually copy the uuid of the contact to the create new address screen. Of course I will change this as well, but that will be the topic of a next blog post.

As a rule of thumb, all methods that actually change data need to be altered.

def save = {
    def contactEntryInstance = new ContactEntry(params)
    if (contactEntryInstance.validate()) {
        def uuid = contactCommandHandlerService.createContact(contactEntryInstance.name)
        def foundContact = ContactEntry.findByIdentifier(uuid)

        flash.message = "${message(code: 'default.created.message', args: [message(code: 'contactEntry.label', default: 'ContactEntry'), foundContact.name])}"
        redirect(action: "show", id: foundContact.id)
    }
    else {
        render(view: "create", model: [contactEntryInstance: contactEntryInstance])
    }
}

Line 4 show that we use the service instead of the query domain object. In line 5 we do use the query domain object to find the created contact.

Configuring the event and command bus using grails and spring

Grails uses a lot of spring udner the hood. But they also give you a very easy way to use spring yourself as well. Grails comes with a special domain specific language for configuring spring. You can find the file resources.groovy in the grails-app/conf/spring folder. In this file we configure the event bus, the command bus, the event listener and the command handlers. The following code block shows the beans, it should be straightforward and not to hard to understand.

beans = {
    contactRepository(ContactRepository) {
        eventBus = ref("eventBus")
        eventStore = ref("eventStore")
    }

    contactEventListener(ContactEventListener, ref("eventBus"))

    createContactCommandHandler(CreateContactCommandHandler, ref("contactRepository"), ref("commandBus"))
    updateContactCommandHandler(UpdateContactCommandHandler, ref("contactRepository"), ref("commandBus"))
    removeContactCommandHandler(RemoveContactCommandHandler, ref("contactRepository"), ref("commandBus"))
    registerAddressCommandHandler(RegisterAddressCommandHandler, ref("contactRepository"), ref("commandBus"))

    // axon beans
    commandBus(SimpleCommandBus)

    eventBus(SimpleEventBus)

    eventStore(FileSystemEventStore, ref("xstreamSerializer")) {
        baseDir = "file:/Users/jcoenradie/temp/axonrepo"
    }

    xstreamSerializer(XStreamEventSerializer)
}

Creating a bean is easy, some of the beans are direct axon classes. The contactRepository, contactEventListener and all the command handlers are not. These are groovy classes that reside in the src directory.

Axon components in groovy

I am not going to write extensively about Axon. The website from Axon does a much better job. I do want to mention the most important components and show some of the groovy code to make it work.

Sending data using commands

The data send is in the command objects. The commandBus is used to dispatch the commands. Each command must have a registered command handler. Axon provided a special mechanism to use annotations to register handlers. For now I register the handlers manually. Let us have a look at the handler for contact creation. The spring configuration already shows that the handlers use the contactRepository as well as the commandBus.

class CreateContactCommandHandler implements CommandHandler<CreateContactCommand> {
    ContactRepository contactRepository

    def CreateContactCommandHandler(contactRepository, commandBus) {
        this.contactRepository = contactRepository;
        commandBus.subscribe(CreateContactCommand.class, this)
    }

    Object handle(CreateContactCommand command) {
        ContactAggregate contact = new ContactAggregate(command.newContactName)
        contactRepository.save contact
        return contact.identifier.toString()
    }
}

As you can see we need to implement the interface CommandHandler. In the constructor we subscribe the handler with the command bus. Now focus on the handle method. We create the contact aggregate and store it in the repository by calling the save method.

Core domain

Now the contact is created, but we also must update our query database. To understand what happens there, we must have a look at the core domain class. The following code block shows the constructor and that it applies an event for a contact being created.

    ContactAggregate(String name) {
        apply(new ContactCreatedEvent(name))
    }

Event listener

Now that we have the events, we want to listen for them and update our query database. When creating the event listener, we need to provide the eventBus. In the constructor of the listener we register the listener with the eventBus. The handle method receives the events. In this method we check if we support the provided event. If we support it, we call one of the available doHandle methods that make use of overloading to determine the right method. The following code block shows the handle method and two of the doHandle methods.

void handle(Event event) {
    println "Contact event listener recevied an event : ${event.class.simpleName}"
    if (event.class in [ContactCreatedEvent, ContactNameChangedEvent, ContactDeletedEvent, AddressAddedEvent]) {
        doHandle(event)
    } else {
        println "Event not supported"
    }
}

private void doHandle(ContactCreatedEvent event) {
    def contact = new ContactEntry(name: event.name, identifier: event.aggregateIdentifier.toString())
    contact.save()
}

private void doHandle(ContactNameChangedEvent event) {
    ContactEntry foundContact = ContactEntry.findByIdentifier(event.aggregateIdentifier.toString())
    foundContact.name = event.newName
    foundContact.save()
}

The ContactEntry is the query domain object. See how we query for an existing contact and how we store the new or updated contact in the query database.

Summary

That is about it for now. I have showed you some basic Axon components in groovy. I introduced you to the concept of a state datastore and a query datastore. Next to that I also told you about the commands. I did not tell you anything about the datastore used for storing the state. The sample makes use of the file based event sourcing datastore. Check the Axon documentation to find out more.

In the following blog posts I will improve the sample by making better screens and controllers. i will also talk more about the axon options. Try to use annotations to see if that makes the event listeners and the command handlers easier to understan.

Hope to see yo back.

This post is mainly about flex and Parsley. We will go into depth of the architecture of the client and how to talk to the server. I will describe the communication with the application that makes use of the axon framework, but I will not go into a lot of details. If you want more information about the Axon Framework I suggest you go to the website http://www.axonframework.org. There is good documentation available in the reference manual. If you want to learn about flex and the Parsley framework in general, please read on.

What is Parsley and why use it?

Parsley is all about decoupling. It is a dependency injection framework and is has strong support for messaging. I like the way the dependency injection as well as message handling is configured. By using [INJECT] on a parameter, you tell parsley to inject an object of the type as specified by the parameter. We will see examples of the usage later on. Other things to inject are the [MessageDispatcher] that enables dispatching messages from each component.

The final component I want to mention is the DynamicCommand object. I use it more as a controller, still it is an interesting concept. We create one component that receives a message, does a remote call and handles the result of that call. All in one object. Again, an example will follow later on.

Structure of the Parsley solution

The following image gives you an idea of the overall solution of parsley. The image shows you the relationship between the view components, the controllers and the model. Messages are send from the view to the controller. The controller interacts with the remote components, updates the model and determines which view should be active. The controllers can also respond to remote push notifications, more on that later on.

Configure parsley

To enable injection and message handling, parsley needs it’s own context to be setup. The easiest way to do this is using an mxml object and an mxml ContextBuilder object. The next code block shows you the complete configuration of the framework. Within the configuration you can see the controllers being configured as DynamicCommand objects. You also find there the RemoteObject, the Consumer and the model objects. They should all be familiar from the previous image.

<mx:Object xmlns:mx="http://www.adobe.com/2006/mxml"
           xmlns:sf="http://www.spicefactory.org/parsley"
           xmlns:commands="org.axonframework.examples.addressbook.commands.*"
           xmlns:model="org.axonframework.examples.addressbook.model.*"
           xmlns:cons="org.axonframework.examples.addressbook.consumer.*"
        >
    <mx:RemoteObject
            id="remoteAddressService"
            destination="addressService"
            endpoint="messagebroker/amf"
            showBusyCursor="true"/>
    <cons:Consumer/>

    <sf:DynamicCommand type="{NewAddressController}" messageType="{NewAddressMessage}"/>
    <sf:DynamicCommand type="{NewContactController}" messageType="{NewContactMessage}"/>
    <sf:DynamicCommand type="{SearchAddressController}" messageType="{SearchForAddressesMessage}"/>
    <sf:DynamicCommand type="{SelectContactController}" messageType="{SelectContactMessage}"/>
    <sf:DynamicCommand type="{ShowContactsController}" messageType="{ShowContactsMessage}"/>
    <sf:DynamicCommand type="{UpdatedContactController}" messageType="{UpdatedContactMessage}"/>
    <sf:DynamicCommand type="{UpdatedContactAddressController}" messageType="{UpdatedContactAddressMessage}"/>
    <sf:DynamicCommand type="{RemoveAddressController}" messageType="{RemoveAddressMessage}"/>
    <sf:DynamicCommand type="{RemovedItemController}" messageType="{RemovedItemMessage}"/>
    <sf:DynamicCommand type="{RemoveContactController}" messageType="{RemoveContactMessage}"/>

    <model:AddressModel/>
    <model:ContactModel/>

    <mx:Script><![CDATA[
        import org.axonframework.examples.addressbook.commands.*;
        import org.axonframework.examples.addressbook.messages.*;
        ]]></mx:Script>
</mx:Object>

That is all that parsley needs to know. The final step is to build the context using the special mxml tag. I have included the next tag in my Main.mxml.

	<sf:ContextBuilder config="ParsleyConfiguration"/>

Next we will focus on the different components

Messages

We make use of two types of messages:

• CommandMessage – tells the receiver to do something.
• NotificationMessage – tells the receiver that something happened

View

Each view component should focus on presenting data and sending messages. The data is injected as a model object. Messages can be dispatched by the special parsley provided dispatcher. Than parsley also provides a Context object that can be used when pop-ups are needed. The following code block shows you the configuration of these mentioned parameters from the ContactsView.mxml component. You can also find a function that is called by pushing a button to send a message to obtain details about a certain contact.

[Inject]
[Bindable]
public var contactModel:ContactModel;
[MessageDispatcher]
public var dispatcher:Function;
[Inject]
public var context:Context;

private function showContactDetails(event:ListEvent):void {
    dispatcher(new SelectContactCommandMessage(event.currentTarget.selectedItem as Contact));
    currentState = 'detail';
}

This is all pretty straightforward, if you need the code check out the sources from the google code project. Let us follow what happens when obtain details button is pushed and the SelectContactMessage is dispatched.

Controller

By dispatching this message, parsley selects the SelectContactController since the argument of the execute method is that exact message. The following code block gives you the complete implementation of the SelectContactController. The super class of all controllers contains a method to handle the faults coming from the remote calls and it makes the dispatcher as well as the remote object available. This class is also in the code block. In the code check how the dispatcher, the RemoteObject and the contactModel are injected. Another thing to notice here is that we only go to the server if we have not cached the contact details locally. So what if the contact details get updated on the server? Or if new contacts are added on the server? More on that in the next section.

public class BaseController {
    [MessageDispatcher]
    public var dispatcher:Function;

    [Inject(id="remoteAddressService")]
    public var addressService:RemoteObject;

    public function BaseController() {
        // default constructor
    }

    public function error(fault:Fault):void {
        dispatcher(new ErrorNotificationMessage(fault.faultString));
    }

}

public class SelectContactController extends BaseController {
    [Inject]
    public var contactModel:ContactModel;

    private var findAddressesFor:Contact;

    public function SelectContactController() {
        super();
    }

    public function execute(message:SelectContactCommandMessage):AsyncToken {
        var cachedContact:Contact = contactModel.findContactByIdentifier(message.contact.uuid);
        contactModel.selectedContact = cachedContact;
        findAddressesFor = cachedContact;

        if (!cachedContact.detailsLoaded) {
            return addressService.obtainContactAddresses(message.contact.uuid);
        }
        return null;
    }

    public function result(addresses:ArrayCollection):void {
        var cachedContact:Contact = contactModel.findContactByIdentifier(findAddressesFor.uuid);
        cachedContact.addresses = addresses;
        cachedContact.detailsLoaded = true;
    }
}

You have now seen the most important parts of the mechanism to go from a view to a controller. Did you notice that we send an ErrorNotificationMessage when something goes wrong in the server communication? The notification messages are handled in the OverallView component. Other notification messages are also handled in this component. The following code block gives a piece of code that handles the message.

[MessageHandler]
public function handleActivityLogEvent(message:NotificationMessage):void {
    createNotification(message.message, Notification.INFO);
}

Communication with the server

The server is used to send data to and of course to obtain data from. The easiest way is when the flex client takes control. As we saw in the parsley configuration, the remote object is configured as you would in any flex client. In the code from the SelectContactController we can see the call to the server. The result function is called when the server returns a result. This is not very complicated to understand.

Let us have a look at how this is handled on the server. Using spring blazeds integration this becomes very easy as well

BlazeDS and Spring BlazeDS Integration

Doing flex remoting with the Spring BlazeDS integration is so easy that anybody can use it. In the web.xml you configure the dispatcher servlet. The config file is loaded using the following tag in a spring configuration file.

<flex:message-broker services-config-path="classpath*:services-config.xml"/>

Now I use annotations to explicitly export some of the functions as remote services. The following code block gives you the example of obtaining address details for a contact. Notice that the name of the method is the same as the method call used in the flex code. By adding the annotation @RemotingInclude we tell spring to expose this as a remote service using BlazeDS.

    @RemotingInclude
    public List<AddressDTO> obtainContactAddresses(String contactIdentifier) {
        List<AddressDTO> foundAddresses = new ArrayList<AddressDTO>();

        List<AddressEntry> addressesForContact =
                repository.findAllAddressesForContact(UUID.fromString(contactIdentifier));
        for (AddressEntry entry : addressesForContact) {
            foundAddresses.add(AddressDTO.createFrom(entry));
        }
        return foundAddresses;
    }

The repository is based on the query database of Axon. I am not going into all the Axon Framework details here. Check the references if you want to learn more about Axon.

That is all there is to it, now you can obtain data from the server. Sending data to the server is done exactly the same.

Receiving events

I already mentioned that we cache data in the flex client. Still we want to have up-to-date data. Using the Axon framework and Spring BlazeDS integration it is not hard to push data to the client from the server when new or updated data is available. Again this blog does not have the intention to fully discuss the axon framework.

Catching and dispatching events on the server

We focus on the event that a new contact is created. The following code shows how you can register a listener for new contacts being created using the Axon framework. The listener makes use of the UpdateMessageProducerForFlex. Axon registers listeners based on the annotation @EventHandler and the argument of the method, in this case the ContactCreatedEvent.

private UpdateMessageProducerForFlex producer;
@EventHandler
public void handleContactCreatedEvent(ContactCreatedEvent event) {
    logger.debug("Received and event with name {} and identifier {}", event.getName(), event.getEventIdentifier());
    ContactDTO contactDTO = new ContactDTO();
    contactDTO.setName(event.getName());
    contactDTO.setUuid(event.getAggregateIdentifier().toString());
    producer.sendContactUpdate(contactDTO);
}

This is the Axon part, the producer is used to send the message to the clients. Sending the message to the flex client is done using the spring BlazeDS integration. The following piece of code shows the producer. After that the configuration of the server.

public class UpdateMessageProducerForFlex {
    private MessageTemplate template;

    @Autowired
    public UpdateMessageProducerForFlex(MessageTemplate template) {
        this.template = template;
    }

    public void sendContactUpdate(final ContactDTO contactDTO) {
        template.send(contactDTO);
    }
}

    <flex:message-destination id="event-bus"/>

    <bean id="defaultMessageTemplate" class="org.springframework.flex.messaging.MessageTemplate">
        <property name="defaultDestination" value="event-bus"/>
    </bean>

The value for the default destination “event-bus” is very important. This needs to be configured in the client as well. Speaking of the client …

Catching and dispatching events at the client

Within the parsley configuration we have configured an object called Consumer. This object configures the client side of the poller and registers it on startup. This registration needs to be done at the right time. Parsleys provides the [Init] notation for that.

The consumer receives messages from the server and dispatches new Notification messages to the client side application. Controller objects pick up these events and update the model. The following code block shows the complete consumer object. Notice the configuration of the ChannelSet and the consumer.

<mx:Object xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Script><![CDATA[
        [Init]
        public function init():void {
            consumer.subscribe();
        }

        [MessageDispatcher]
        public var dispatcher:Function;

        public function messageHandler(event:MessageEvent):void {
            if (event.message.body is Contact) {
                dispatcher(new UpdatedContactNotificationMessage(event.message.body as Contact));
            } else if (event.message.body is Address) {
                dispatcher(new UpdatedContactAddressNotificationMessage(event.message.body as Address))
            } else if (event.message.body is Removed) {
                dispatcher(new RemovedItemNotificationMessage(event.message.body as Removed));
            }

        }

        public function faultHandler(event:Event):void {
            dispatcher(new ErrorNotificationMessage("Fault while receiving message" + event.toString()))
        }

        ]]></mx:Script>
    <mx:Consumer id="consumer" destination="event-bus" channelSet="{cs}" message="messageHandler(event)"
                 fault=" faultHandler(event)"/>

    <mx:ChannelSet id="cs">
        <mx:AMFChannel url="messagebroker/pollingamf"/>
    </mx:ChannelSet>

</mx:Object>

Wrapping up

That is it. We have touched all components. I like how clean you can develop flex clients using Parsley and how easy it is to interact with a server using the Spring BlazeDS integration. Also the way to handle events using Axon makes this a very nice way to keep the data in your flex client up to date.

Hope you likes the sample, sources can be found in google code. Check the addressbook sample project of the axon framework.

The following image shows a screendump of the sample, after that are some references.

• http://code.google.com/p/axonframework/source/browse
• http://www.spicefactory.org/parsley/
• http://www.springsource.org/spring-flex
• http://www.axonframework.org