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.

In this blog post I will provided as much steps that I can remember and or wrote down while installing a node.js server on my Synology. This was not the easiest thing I have ever done. If I can help some others that want to get more out of their Synology my hours of work are worth it.

Terminal access

The Synology comes with an installed firmware. In my case I started with the 3.1 DSM software.

Tweaking you Synology starts with obtaining Terminal access. You can enable this in the configuration panel of DSM. By default you can access your synology using DiskStation.local with the admin or root account. For the things we are going to do I recommend using the root account. The password for the root account is the same as for the admin account. Just so you know. Go on check if you have access

# ssh root@DiskStation.local

ipkg

The next step is to install ipkg, the package manager for you synology. There are multiple resources on the web that explain how to do this. Most of them point to this wiki page. It is important to take the right version of the bootstrap for your synology system. The variations in processors used are big, therefore you have to use the right software. The processor can be obtained using this page. You can also find out more about your system from the command line.

DiskStation> uname -a
Linux DiskStation 2.6.32.12 #1605 Thu Mar 24 02:12:03 CST 2011 armv5tel GNU/Linux

For the DS211+ I needed the Marvel Kirkwood mv6282 ARM. The easiest way to get in onto your system is to use wget. Remember that tool, we will talk more about it.

wget http://wizjos.endofinternet.net/synology/archief/syno-mvkw-bootstrap_1.2-7_arm-ds111.xsh

I created a downloads folder in the home folder of root. Executing the script is very easy

sh syno-mvkw-bootstrap_1.2-7_arm-ds111.xsh

Now we have ipkg installed. The best way to check if it works is to update and upgrade.

DiskStation> ipkg update
Downloading http://ipkg.nslu2-linux.org/feeds/optware/cs08q1armel/cross/unstable/Packages.gz
Inflating http://ipkg.nslu2-linux.org/feeds/optware/cs08q1armel/cross/unstable/Packages.gz
Updated list of available packages in /opt/lib/ipkg/lists/cross
Successfully terminated.
DiskStation> ipkg upgrade
Nothing to be done
Successfully terminated.

If you just want to install software that is available via ipkg, this is it. In my case I want to install node.js. This is not available via ipkg, therefore we need to compile it ourselves. This is where the problem starts. So in the next section we will have a look what you need to compile stuff.

Compile from source

Compiling source code on linus needs compilers (gcc) and headers files. The header files contain information about the libraries that are required during compilation of code that makes use of these libraries. Ipkg has the option to install development libraries that are required to compile source. To bad the current version does not work out of the box. With the help of some resources on the web and a lot of experimentation I finally got a working system. This part is the most important part of getting your system ready to compile node.js.

Usually you would install optware-devel with ipkg. But we start off with some other libraries that will not work with optware-devel.

ipkg remove wget
wget http://ipkg.nslu2-linux.org/feeds/optware/cs08q1armel/cross/unstable/wget-ssl_1.12-2_arm.ipk
wget http://ipkg.nslu2-linux.org/feeds/optware/cs08q1armel/cross/unstable/openssl_0.9.8p-1_arm.ipk
wget http://ipkg.nslu2-linux.org/feeds/optware/cs08q1armel/cross/unstable/libidn_1.19-1_arm.ipk
ipkg install libidn_1.19-1_arm.ipk
ipkg install openssl_0.9.8p-1_arm.ipk
ipkg install wget-ssl_1.12-2_arm.ipk
ipkg install openssl-dev

We are almost set, now I have a problem with my limited linux knowledge. I found some resources on the web and in the end I had to copy some resources around. So these steps might not be optimal, but they did work for me.

I took the first step from this post.

mkdir /opt/arm-none-linux-gnueabi/lib_disabled
mv /opt/arm-none-linux-gnueabi/lib/libpthread* /opt/arm-none-linux-gnueabi/lib_disabled
cp /lib/libpthread.so.0 /opt/arm-none-linux-gnueabi/lib/
cd /opt/arm-none-linux-gnueabi/lib/
ln -s libpthread.so.0 libpthread.so
ln -s libpthread.so.0 libpthread-2.5.so

The final copying you need to do actually only appeared to me when running node.js. Therefore I am not completely sure if this is right, but again it works for me.

cp /opt/lib/libssl.so.0.9.8 /usr/lib
cp /opt/lib/libcrypto.so.0.9.8 /usr/lib

If I remember correct, now is the time to start downloading node.js and start compiling.

Compiling node.js

Before we start compiling we need to have some source. This page describes what you need to do:

https://github.com/joyent/node/wiki/Installation

I downloaded node in the /root folder, called ./configure and put the results in /opt/node. Before you can do that you need to install git first. This is easily done using ipkg. Now the steps to perform:

ipkg install git
cd /root
git clone https://github.com/joyent/node.git
cd node
./configure --prefix=/opt/node
make
make install

Hope it all goes as aspected and no errors arise. Beware the make step can take a long time (15-30 minutes or something). The next step is to add node.js to your path. In the root folder you can find the .profile file. In here you will find a PATH variable. Change it to include the folder /opt/node/bin. Something like this

PATH="/opt/node/bin:$PATH:/bin:/sbin:/usr/bin:/usr/sbin:/usr/syno/bin:/usr/syno/sbin:/usr/local/bin:/usr/local/sbin"

That is the end of the journey. Now you can do your node things like install npm, express, jade, sass, socket.io, etc. If you have an application running you can execute it from the shell. The problem is that it does not keep running when you logout. There are multiple mechanisms to keep the process running. I found one that is actually itself a node.js application. It seems to do the trick for me.

https://github.com/indexzero/forever

That is it, node.js running on your synology. if you want more information about what I am running on my synology, check the sources on Github or check my previous blog post.

http://www.gridshore.nl/2011/03/16/first-steps-with-node-js/

https://github.com/jettro/nodejstryout

In this blog item I want to show you the steps I took, the resources I found useful and some improvements to the article that seems a bit outdated. It is not an explanation of what Node.js is, but it does provide some help to get started on your own.

The source

I took the sources from the article of Ciaran Jessup as my basis. So a lot of credits go to him. You can find my sources over at github:

https://github.com/jettro/nodejstryout

Setting up my environment

If you want to do something with nodejs, you have to install it first. I used MacPorts to install it, but lots of other ways are documented on the wiki. Using MacPorts all you have to do is:

sudo port install nodejs

The next step is to install a package manager. The mentioned article uses kiwi, but the node.js documentation recommends npm. Therefore I chose to use npm as well. Installing npm is documented well on the website: https://github.com/isaacs/npm. To be honest I am not sure anymore whether I installed using curl or using the download/make procedure. But in the end you should be able to install dependencies using npm. I just love the way npm is used to update modules. Not easy when using multiple projects that need different versions. But maybe there is a solution to that as well. For now, lets focus on installing some modules or dependencies. Everything needs to be done with sudo, just so you know. No worries, I’ll explain the different modules later on.

# sudo npm install express
# sudo npm install jade
# sudo npm install sass

Time to check if your environment works, try to execute the famous HelloWorld sample. But first issue the command: node –version. The following code block shows the sample as presented on the Node.js homepage.

var http = require('http');
http.createServer(function (req, res) {
  res.writeHead(200, {'Content-Type': 'text/plain'});
  res.end('Hello World\n');
}).listen(8124, "127.0.0.1");
console.log('Server running at http://127.0.0.1:8124/');

Now start the server with node using : node helloworld.sh and point your browser to http://127.0.0.1:8124/.

Now you have your http server running, nice stuff.

The sample

The sample is all about providing a blog. The structure of the sample is based on the original sample. We have a public folder, a views folder and the application js files are in the root. These folders are used later on in the express code. Express is a web modules for Node.js. You can find out more about the module here: http://expressjs.com/. The next section explains a bit more about using expressjs.

The sample can be started using the app.js file by calling node app.js. We start by analyzing the app.js file.

var express = require('express');
var pub = __dirname + '/public';
var app = express.createServer();
var ArticleProvider = require('./articleprovider-memory').ArticleProvider;
var articleProvider = new ArticleProvider();
// ... more express stuff, will be discussed later on
app.listen(3000);
console.log('Express server started on port %s', app.address().port);

First we obtain the express modules, then we define a folder called pub that points to the public folder as mentioned before. In line 3 we create the express server and an ArticleProvider. The ArticleProvider is copied 1-on-1 from the article that was mentioned before. It is an in memory implementation for the datastore of the blog items. Check the sourcecode if you want to learn more about it. The final two lines are setting the port for the server to start, start the server and print a line to the console that the server has been started.

In the next section we will configure the express server.

Express

More information : http://expressjs.com/.

The following code block is the remainder of the application. There are two parts in the code block. The first part is the configuration of the server, the second part configures the url handling. Within the server configuration we define the view engine (jade) and the folder where the views can be found. Another thing is the folder where the stylesheets in sass format are that need to be compiled. We also define the folder where the public files are using the static method. The last configuration is the bodyParser. This is required for handling the post. The second part about url handling is covered after the code.

app.configure(function() {
    app.set('view engine', 'jade');
    app.set('views', __dirname + '/views');
    app.use(express.compiler({ src: pub, enable: ['sass'] }))
    app.use(express.methodOverride());
    app.use(express.static(pub));
    app.use(express.logger());
    app.use(express.bodyParser());
});

app.get('/', function(req, res) {
    articleProvider.findAll(function(error, docs) {
        res.render('blog', {locals: {docs: docs}});
    });
});

app.get('/blog/new', function (req, res) {
    res.render('blog_new', {locals: {title: 'New Blog Item'}});
});

app.post('/blog/new', function (req, res) {
    console.log('The provided title is : %s',req.body.new_title);
    articleProvider.save({title: req.body.new_title, body: req.body.new_body},
            function(error, docs) {
                res.redirect('/');
            });
});

Within the sourcecode you can identify three urls that are handled: /, /blog/new and a post to /blog/new. Notice that we use callbacks? This is what Node.js is all about, handling async callbacks. If you look at the app.get method for ‘/’ you’ll see that we call the findAll method of the ArticleProvider. The result is used to render a view with the name blog. The part with locals is used to provide parameters to the view. In this case we provide the returned docs to the view. The next section will show you the very basics of jade, a template engine.

Jade

More information can be found here: https://github.com/visionmedia/jade.

Jade is a high performance template engine heavily influenced by Haml and implemented with JavaScript for node.

I am not going to give a lot of details about jade here. The following code block shows you the view with all the blog items.

h1 My blog
div
    a(href='/blog/new') New blog item
div#articles
    - each blog in docs
        div.article
            div.title #{blog.title}
            div.created_at #{blog.created_at}
            div.body #{blog.body}

As you can see, the code is very condensed. A good tool with code completion would be nice though. Still if you have some programming experience it should not be to hard to read. Check the mechanism for making a distinction between a class and an id. # is used to represent an idea and a ‘.’ for a class. These both will be good to use in a stylesheet. Which is a nice bridge to the next section. This section is about sass that needs to be compiled in a stylesheet. The following code block shows the layout.jade file. This file contains the main template with the header of all pages. Check the way to define we use html 5.

!!! 5
html(lang="en")
  head
    title My Blog
    link(href="/style/style.css", media="screen", rel="stylesheet", type="text/css")
  body
    div!= body

Sass

More information can be found here: https://github.com/visionmedia/sass.js.

Is a condensed way of writing stylesheets. Before the stylesheets can actually be user they need to be compiled. This is done by express, check one of the earlier sections. The following codeblock shows the complete stylesheet. I guess it should not be to hard to follow if you have stylesheet experience.

body
  :font-family "Helvetica Neue", "Lucida Grande", "Arial"
  :font-size 13px
  :text-align center
  =text-stroke 1px rgba(255, 255, 255, 0.1)
  :color #555
h1, h2
  :margin 0
  :font-size 22px
  :color #343434
h1
  :text-shadow 1px 2px 2px #ddd
  :font-size 60px
#articles
  :text-align left
  :margin-left auto
  :margin-right auto
  :width 320px
  .article
    :margin 20px
    .created_at
      :display none
    .title
      :font-weight bold
      :text-decoration underline
      :background-color #eee
    .body
      :background-color #ffa

Concluding

There you have it, my first try on Node.js with extensive help of Ciaran Jessup. I do like Node.js., I love the speed of development. Would be nice to have some IDE support. I tried WebStorm, but it does not have Node.js support. It does help with the JavaScript coding. I will definitely continue playing around with Node.js. The next step is have a look at Rabbitmq.js. Finally I want to extend another sample of mine that makes use of the Axon framework with rabbitmq and Node.js for the front end. I also want to have a good look ar Socket.IO. So stay tuned for more blogs on this topic.

Resources

• https://github.com/jettro/nodejstryout
• http://howtonode.org/express-mongodb
• http://nodejs.org/
• https://github.com/isaacs/npm
• http://expressjs.com/guide.html
• https://github.com/visionmedia/jade
• https://github.com/visionmedia/sass.js




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

I was some time a go I had a look at the sample, since than a lot of people keep coming back to it. I still get questions about it. Therefore I decided to upgrade the sample. This blog post is about the upgrade I did which are mainly upgrades in versions of the libraries and the build configuration. Still I think it is worthwhile to have a look at it.

Before I start with this blog post I need to warn you that I am not going to explain a lot of the internals. Please browse my other flex 3 blog items to find out more.

Library upgrade

The client (flex) side

For the flex building I use Mate. I think mate is a nice framework, but it is not very active. Not many improvements are created. Still it does the job. I am also creating a flex sample for the Axon Framework using Parsley. Stay tuned for a blog post that is around the corner about this sample. I upgrade the mate to release 0.8.9

Another framework I use on the flex side is the spring-actionscript project. This project changed a lot since the last time I used it. I am now using version 0.8.1. This project is now split up into a few other modules. I did have a problem with the StringUtils class. This is in as3commons:as3commons-lang. By transitive dependecy you get 0.1 of this library. I had to upgrade to version 0.2 to make it work.

The serverside

I did not upgrade a lot on the serverside. I could have upgrade to spring 3, I’ll wait till it becomes the default for the spring blazeds integration project. They still use version 2.5.6, so I’ll stick with that. I did upgrade the Spring Blazeds Integration project to the latest release: 1.0.2.RELEASE.

Building and developing

The biggest change was in the maven configuration. Flex-mojos made a lot of improvements and is now tightly integrated with Intellij. To me that is incredibly important. My development speed with flex has enormously increased.

I use flex-mojos version 3.5.0. The configuration is now very easy. For the war project you just need to add the following plugin plus configuration:

<plugin>
    <groupId>org.sonatype.flexmojos</groupId>
    <artifactId>flexmojos-maven-plugin</artifactId>
    <version>${flex-mojos.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>copy-flex-resources</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Now let us have a look at the configuration of the swf file. Again it is pretty straightforward. You have to add the flex-framework as a dependency.

<dependency>
    <groupId>com.adobe.flex.framework</groupId>
    <artifactId>flex-framework</artifactId>
    <version>${flex.sdk.version}</version>
    <type>pom</type>
</dependency>

Finally we have to configure the flex-mojos compiler plugin.

<plugin>
    <groupId>org.sonatype.flexmojos</groupId>
    <artifactId>flexmojos-maven-plugin</artifactId>
    <version>${flex-mojos.version}</version>
    <extensions>true</extensions>
    <configuration>
        <debug>true</debug>
        <configurationReport>true</configurationReport>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>com.adobe.flex</groupId>
            <artifactId>compiler</artifactId>
            <version>${flex.sdk.version}</version>
            <type>pom</type>
        </dependency>
        <dependency>
            <groupId>com.adobe.flex.compiler</groupId>
            <artifactId>asdoc</artifactId>
            <version>${flex.sdk.version}</version>
            <classifier>template</classifier>
            <type>zip</type>
        </dependency>
    </dependencies>
</plugin>

The configurationReport parameter is used by intellij. This creates an xml file that intellij uses to set you compiler properties in intellij. Very nice.

Repositories

I also want to mention the additional repositories I configured. I added a repository for libraries coming from flex-mojos and another library for the spring-actionscript libraries.

<repository>
    <id>flexmojos-repository</id>
    <url>http://repository.sonatype.org/content/groups/flexgroup/</url>
</repository>
<repository>
    <id>yoolab.org-releases</id>
    <url>http://projects.yoolab.org/maven/content/repositories/releases</url>
    <releases>
        <enabled>true</enabled>
    </releases>
</repository>

The only library I still cannot find online is Mate. Therefore I added it to my google code repository. Please do the same thing if you need it for your own project. Do not use my repository because I will reach my maximum bandwidth and then I have to take it away again.

If you want to check out the state of the project while I was writing this blog, use the following tag:

http://code.google.com/p/gridshore/source/browse/#svn/tags/books-overview-1.0.0

Hope this is helpfull when exploring my sample, feel free to post remarks, improvements and questions.

The following screen gives an idea about the look and feel of the sortable list of stories.

jQuery Sortable component

Let us start to have a look at the front end. I am using jQuery together with jQuery-ui. Everybody doing series web development (should) know jQuery. I have written about jQuery before, but other have as well. Just do a search on google and the amount of articles is massive. Dzone also contains a few items each day about top 5 plugins for jQuery. I think the power of jQuery-ui is not known that much. If you have not seen it before, be sure to check it out. It can help you a lot in creating websites that look sharp with icons and colors that are well balanced. The ui framework contains a lot of interaction components, widgets and effects. This blog posts focus is on the Sortable interaction component.

With the sortable component you can actually drag the components in order. You get notified of the change.

Setting op de component

Before we can use the component we need to download the jquery-ui component. The jQuery UI project contains a download function to create your customized download. Don’t forget to include at least the sortable function. You can also follow a long with the sources I use in the your-scrum project. Now include the js files in your page. I use the script.js file to set generic libraries. (webapp/includes folder). Now open up the stories.jsp file under webapp/WEB-INF/jsp/story folder.

We begin by creating the list of items and use jQuery to make a sortable list out of it.

<ul id="sortable">
    <c:forEach items="${stories}" var="story">
        <li id="story_${story.id}" class="ui-state-default"><span class="listItemLabel">${story.name}</span></li>
    </c:forEach>
</ul>

Within the script block we now have to initialize the sortable component.

var idsOldOrder;
$(function() {
    $("#sortable").sortable();
    idsOldOrder = $("#sortable").sortable('serialize').toString();
    $("#sortable").disableSelection();
    $("#sortable").bind('sortupdate', function(event, ui) {
        var ids = $("#sortable").sortable('serialize').toString();
        $.post('/story/reorder', {ids: ids, oldIds: idsOldOrder}, function(data) {
            // nothing special
            window.alert(data);
        });
        idsOldOrder = ids;
    });
});

This code might look more difficult than you did expect. That is because more is happening here than you expect. Within this code we need only the first line to show the sortable items. The other lines are for notification of changes. Don’t worry we explain them as well. Time to move on.

Capturing change events

Have a look at the previous code block. The second line stories a special form of presentation in a string. We need this on the server to actually determine the change. Than in line 4, we bind a function to the sortupdate event. Again a string containing the ids in the new order is created. Using the jQuery Ajax tooling we send a request to the server. The POST is done to the url /story/reorder with two parameters: ids and idsOldOrder. The result is shown in an alert box, which is not nice, but it works for now.

From the client side perspective, that is all there is to it. I actually wanted to have a real change from the library, like this item is moved before that item. But I could not find how to do just that. Therefore I had to do the trick with the old order and the new order. Now the server has to take care of finding the actual change. More on that later.

Add task button

One of the stories for our project is to add a new task to a story. If you have a look at the image containing a screen dump (the first image of this blog post) you see on each story the amount of tasks and an orange plus sign. The plus sign is something we use from the jquery-ui project as well. How to do this.

First we must add the content to the html using the jsp. So we have to extend the jsp with a text containing the number of tasks and a link that we can click to go to the add task form. The jsp now becomes:

<ul id="sortable">
    <c:forEach items="${stories}" var="story">
        <li id="story_${story.id}" class="ui-state-default"><span
                class="listItemLabel">${story.name}</span><span
                class="listItemAdd"><a
                href="/story/${story.id}/task/form" title="add task"><spring:message code="generic.add"/></a></span><span
                class="listItemChilds">tasks(${story.numberOfTasks})</span></li>
    </c:forEach>
</ul>

Have a good look at the classes of the span elements. We are going to use them to change the appearance of the add link into that nice plus sign button. We are replacing the link with an image, clicking the image will call the function myClick which uses the actual link from the a element and opens that url. Have a look at the changes in the code.

var myClick = function (event) {
    var location = $(event.target).children("a")[0].href;
    window.location = location;
};
$(function() {
    // only show changes, refer to previous code block for other lines
    $("#sortable li span.listItemAdd").addClass("ui-icon ui-icon-circle-plus").click(myClick);
});

Getting the icon with the plus sign is a jQuery trick as well. There are some style sheets that contain all the icons. You just need to find the right class to add to a span and you are done. I used the ui-icon ui-icon-circle-plus. More on the available icons can be found in the documentation.

Other jQuery things

There are other things I use from jQuery. Check the references section for documentation. I use the corner plugin for the navigation. If you like the navigation implementation have a look at the main.jsp file in webapp/decorators. The final jQuery thing I want to mention is the hotkeys plugin. You can create hotkeys to be used on your page. I created a hotkey ctrl+s to open up the new story screen. The following code block shows the implementation.

var newStory = function (event) {
    window.location = '/story/form';
    event.stopPropagation();
    event.preventDefault();
    return false;
};
$(function() {
    $(document).bind('keydown', 'ctrl+S', newStory);
});

Finding the change on the server component

The current status is that we have a POST to the server with two string containing ids in the old and the new order. Now we have to find the change. On the server I use Spring 3 to handle requests. I am not going to explain all the spring 3 configuration in this post. If you want to learn about spring 3 I advise you to go over the reference documentation.

Handling the POST consists of two parts. The first part is finding the change from the two mentioned strings. The second part is communicate the change to the domain and persisting the change. In a next post I’ll focus more on the domain and the persistence part. For now have a look at the complete method that accepts the POST and handles it.

    @RequestMapping(value = "/story/reorder", method = RequestMethod.POST)
    public String reorderStories(@RequestParam("ids") String ids,
                                 @RequestParam("oldIds") String oldIds, ModelMap modelMap) {
        ItemSorter itemSorter = new ItemSorter();
        ChangedSortOfItems changedSortOfItems = itemSorter.determineChangeInStoryOrdering(strip(ids), strip(oldIds));

        Long movedItemId = null;
        try {
            if (StringUtils.hasText(changedSortOfItems.movedItem())) {
                movedItemId = Long.parseLong(changedSortOfItems.movedItem());
            }
        } catch (NumberFormatException e) {
            logger.warn("Number format exception of id from story to be planned while nog expected : "
                    + changedSortOfItems.movedItem());
        }

        Long beforeItemId = null;
        try {
            beforeItemId = Long.parseLong(changedSortOfItems.beforeItem());
        } catch (NumberFormatException e) {
            logger.warn("NUmber format exception while nog expected");
        }
        backlogService.plan(movedItemId, BEFORE, beforeItemId);

        modelMap.addAttribute("message", "story.order.changed");
        return "message";
    }

This code should not be to hard to follow, now lets have a look at the ItemSorter class. This class uses the string to find differences. An instance of ChangedSortOfItems is returned that contains information about the items that have changed. In the end it is all about going through the list of items to find the first that changed from position. The first item that is different does not have to be the actual item that is moved. We can check that by looking at the next item. Have a look at the code if you can see what happens.

    public ChangedSortOfItems determineChangeInStoryOrdering(String ids, String oldIds) {
        validateInput(ids, oldIds);

        if (ids.equals(oldIds)) {
            return ChangedSortOfItems.nothingChanged();
        }

        String[] arrayOfCurrentIds = StringUtils.delimitedListToStringArray(ids, delimiter);
        String[] arrayOfOldIds = StringUtils.delimitedListToStringArray(oldIds, delimiter);

        // A change must be found since the items are not equal
        ChangedSortOfItems change = null;
        int indexFirstChangedItem = findchangeInItems(arrayOfCurrentIds, arrayOfOldIds);
        // If you start at the beginning, the last item can never be the first item to change position
        String nextOfFirstChangedItem = arrayOfCurrentIds[indexFirstChangedItem + 1];

        if (nextOfFirstChangedItem.equals(arrayOfOldIds[indexFirstChangedItem])) {
            change = ChangedSortOfItems.movedBefore(arrayOfCurrentIds[indexFirstChangedItem],
                    arrayOfOldIds[indexFirstChangedItem]);
        } else {
            int lastitem = arrayOfCurrentIds.length - 1;
            for (int indexMovedBefore = indexFirstChangedItem; indexMovedBefore < arrayOfCurrentIds.length;
                 indexMovedBefore++) {
                String movedItem = arrayOfCurrentIds[indexMovedBefore];
                if (indexMovedBefore == lastitem) {
                    change = ChangedSortOfItems.movedToEnd(movedItem);
                    break;
                } else {
                    String aNextOldItem = arrayOfOldIds[indexMovedBefore + 1];
                    if (!movedItem.equals(aNextOldItem)) {
                        change = ChangedSortOfItems.movedBefore(movedItem, aNextOldItem);
                        break;
                    }
                }
            }
        }
        return change;
    }
    private int findchangeInItems(String[] arrayOfCurrentIds, String[] arrayOfOldIds) {
        for (int i = 0; i < arrayOfCurrentIds.length; i++) {
            String possibleMovedItem = arrayOfCurrentIds[i];
            String originalItem = arrayOfOldIds[i];
            if (!possibleMovedItem.equals(originalItem)) {
                return i;
            }
        }
        throw new NoChangeInSortFoundException();
    }

I hope the code is understandable. If not, questions can be asked in the comments .

Concluding

Again I have to conclude that jQuery is a fantastic framework for client side development. I also have to conclude that the documentation and available samples are not always thorough enough. I am still not sure if there is no easier way to find the actual change. But maybe one of the readers of this blog out there can help me out. I do love the extendibility of the jQuery components.

If you liked this post, please push me up at dzone, if you have questions or remarks do not hesitate to use the comments.

References

• http://code.google.com/p/your-scrum/
• http://jqueryui.com/demos/sortable/
• http://jquery.malsup.com/corner/
• http://code.google.com/p/js-hotkeys/
• http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html

With the next posts I moved on to use maven, which in the beginning was not easy, but thanks to the excellent flex-mojos plugin from velo. In the beginning of this year I started blogging about the springsource coming into the flex domain for real. Two projects, one for the spring style of programming in the ActionScript language. The other one for integrating BlazeDS and the spring framework. I wrote multiple posts about the new spring project. This post will probably not be the last. But if you are using Mate as well as the spring BlazeDS Integration project. This is a must read post. Maybe only to laugh at what I have done, but I hope to be amazed how simple a full flexed application can be when you combine all these technologies.

Kind of a long introduction, but what is this post really about? I have been using a sample application called books-overview that I have been using for flex based applications. I have been adding stuff to it once in while, but now I have completely refactored it. I am using a framework called Mate, have made it modular using the flex-mojos plugin and I have adopted the Spring BlazeDS integration project. Time to explain the way I handle security now, how I am using maven and show the extension to Mate for security.

Read on to find out how I did it and like always leave a comment if you like it or if you have improvements.

The books-overview sample

The books overview sample is a very easy application. You need to login to get access to the application. You can get two different roles. A normal user can look at the books, and admin user can also add books. The domain model is very easy. There are two entities; book and author. A book can have multiple authors and an author can write multiple books. I think the architecture is pretty straightforward. The basic business layer, dao layer, domain component and a web project containing the BlazeDS and flex components. We use spring-security to implement authentication as well as authorization. All data is stored in an in memory database and everything is build using maven. You can find the code in google code, checkout the trunk with the following command:

svn checkout http://gridshore.googlecode.com/svn/trunk/books-overview gridshore-books-overview

To tests if it works, you can use the following commands:

• step into the directory where you just checked out the sample
• mvn clean install (you might have to install some artifacts yourself that are not available in a repository)
• cd books-web
• mvn clean jetty:run-war
• open your browser with the url: http://localhost:8080/books-web

You should see the login screen, enter user admin with password admin and you should see the following screen:

It looks like a pretty easy screen, but a lot has happened before this screen is presented to you. Most important to know for now is that the New Book button is only available when logged in as admin. The name can be seen in the logout button on the right. This time with the label logout admin. You can now experiment with the application a bit. That way you will better understand what is happening in the code.

Setting up the maven build

For my development I use a combination of building with maven and writing code within intellij. Maybe I should invest more time to build with intellij as well, but I keep having problems with it. The workflow of building with maven in a command line is now so easy that I settle with that. Though I do miss the debugging, maybe I’ll step into it once more. A very cool feature of intellij is that it can group projects into modules. You can make intellij create these modules automatically based on maven structures. Pom projects become modules. That way grouping your flex projects to give them common dependencies becomes very easy. That is what I have done for the sample.

Lets have a look at the dependencies and some build specifics. The parent pom contains the following dependencies: flex.sdk.version=3.2.0.3958, spring-actionscript=0.7.1, mate.version=0.8.7.1, flex-mojos.version=3.2.0

<dependency>
    <groupId>com.adobe.flex.framework</groupId>
    <artifactId>flex-framework</artifactId>
    <version>${flex.sdk.version}</version>
    <type>pom</type>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-actionscript</artifactId>
    <version>${spring-actionscript.version}</version>
    <type>swc</type>
</dependency>
<dependency>
    <groupId>com.asfusion</groupId>
    <artifactId>mate</artifactId>
    <version>${mate.version}</version>
    <type>swc</type>
</dependency>
<!-- testing -->
<dependency>
    <groupId>org.sonatype.flexmojos</groupId>
    <artifactId>flexmojos-unittest-support</artifactId>
    <version>${flex-mojos.version}</version>
    <type>swc</type>
    <scope>test</scope>
</dependency>

The build section for both of the flex modules is the same. The only difference is the packaging. For the security model it is swc and for the mate module it is swf. The mate modules is actually not a very good name, it contains the application, maybe I should call it main or so. The build section of the pom looks like this:

    <build>
        <sourceDirectory>src/main/flex</sourceDirectory>
        <testSourceDirectory>src/test/flex</testSourceDirectory>
        <plugins>
            <plugin>
                <groupId>org.sonatype.flexmojos</groupId>
                <artifactId>flexmojos-maven-plugin</artifactId>
                <version>${flex-mojos.version}</version>
                <extensions>true</extensions>
                <configuration>
                    <contextRoot>/books-web</contextRoot>
                    <mergeResourceBundle>true</mergeResourceBundle>
                    <resourceBundlePath>${basedir}/src/main/locale/{locale}</resourceBundlePath>
                    <locales>
                        <locale>en_US</locale>
                        <!--<locale>nl_NL</locale>-->
                    </locales>
                </configuration>
            </plugin>
        </plugins>
        <defaultGoal>install</defaultGoal>
        <resources>
            <resource>
                <directory>${basedir}/src/main/resources</directory>
            </resource>
        </resources>
    </build>

The other big maven thing to configure is the server side. This you can find in the books-web project. There are dependencies for BlazeDS and the spring-flex project containing the BlazeDS spring integration. Please check the code if you want to see more of it. The last thing I want to show about maven are the repositories I use to find most of the artifacts. You do need to install some manually, but most of them come from an existing repository:

    <repositories>
        <repository>
            <id>flex-mojos-repository</id>
            <url>http://repository.sonatype.org/content/groups/public</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
        <repository>
            <id>fnh</id>
            <url>http://fna.googlecode.com/svn/trunk/fna/fna_m2_repository/</url>
        </repository>
        <repository>
            <id>Servebox</id>
            <url>http://maven.servebox.org/repository</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>

        <repository>
            <id>spring-milestone</id>
            <name>Spring Portfolio Milestone Repository</name>
            <url>http://maven.springframework.org/milestone</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
    </repositories>
    <pluginRepositories>
        <pluginRepository>
            <id>flex-mojos-repository</id>
            <url>http://repository.sonatype.org/content/groups/public</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </pluginRepository>
    </pluginRepositories>

Enough about maven, lets move on to the flex side.

Introducing Mate, a flex framework

Mate is a tag-based, event-driven Flex framework. At least that is what the website states. Event driven is very important. If you follow the recommended way to create your application you get a clean separation of front end components that show data, forms and interaction components. Each action should lead to an event, which is handled by Mate. Most of the logic is put into manager components.

Lets have a look at what happens when you click on the All Books button. The MainNavigation.mxml contains a button that calls the following code when the button is clicked.

private function doObtainAllBooks():void {
    var event:BooksEvent = new BooksEvent(BooksEvent.OBTAIN_ALL_BOOKS);
    dispatchEvent(event);
}

As you can see, this only dispatches and event. Mate uses an mxml component with a lot of special tags to handle events. This handling can result in calling remote services, manager classes, dispatching new events and injecting data into view components. The following code block shows the capturing of this event, calling a remote service to obtain the books, giving the books to a manager, injecting the results into the AllBooks.mxml view component. Finally a new navigation event is dispatched to open the view component. The names of the tags give a clear description of what is going on.

<EventMap xmlns:mx="http://www.adobe.com/2006/mxml" xmlns="http://mate.asfusion.com/">
    ...
    <mx:RemoteObject id="booksService"
                     endpoint="http://{props.host}:{props.port}/{props.webcontext}/messagebroker/amf"
                     destination="remoteBookManager"/>

    <EventHandlers type="{BooksEvent.OBTAIN_ALL_BOOKS}" debug="true">
        <RemoteObjectInvoker instance="{booksService}" method="obtainAllBooks">
            <resultHandlers>
                <MethodInvoker generator="{BooksManager}" method="storeBooks" arguments="{resultObject}"/>
                <EventAnnouncer generator="{MainNavigationEvent}" type="{MainNavigationEvent.NAVIGATION}">
                    <Properties navigationId="{MainNavigationEvent.ALL_BOOKS}"/>
                </EventAnnouncer>
            </resultHandlers>
        </RemoteObjectInvoker>
    </EventHandlers>
    <Injectors target="{AllBooks}">
        <PropertyInjector source="{BooksManager}" sourceKey="books" targetKey="books"/>
    </Injectors>
    ...
</EventMap>

Now have a look at the code of the BooksManager component. Calling the actual remote object and transforming java objects into flex objects is done using BlazeDS. More on this later on. The objects that you get back are Books.

public class BooksManager {
    [Bindable]public var books:ArrayCollection = new ArrayCollection();

    public function storeBooks(obj:Object):void {
        books = ArrayCollection(obj);
    }
}

[Bindable]
[RemoteClass(alias="nl.gridshore.samples.books.domain.Book")]
public class Book {
    public var id:Number;
    public var title:String;
    public var isbn:String;
    public var authors:ArrayCollection = new ArrayCollection();

    public function Book() {
    }

    public function addAuthor(author:Author):void {
        authors.addItem(author);
    }
}

That was your crash coarse in Mate. If you want to know more about the basics, be sure to check out their website. A lot of links to other good resources are available. Time to move on. For the security part I need to extend Mate. That is what the next section is about

Implementing authentication in the flex client

With respect to the authentication there are three different events that take place:

• Check if needs authentication – If the current client is not authenticated the login form must be presented
• Try authentication – check the provided credentials, show an error message if authentication fails or go to the initial screen.
• Logout – logout from the client

The handling of these three events can be found in the SecurityEventMap.mxml component. This part of the solution has changed the most with respect to previous versions of the sample. In the current release I make use of the standard capabilities of the flex class mx.messaging.ChannelSet. I have created an extension to interact with this channelset using tags, the ChannelSetInvoker. Creating this class was not easy to me, there is a document that can help and the source code from existing tags is very helpful. I run by some things I learned while creating the extension.

A very important part is to make a difference to properties that you need to configure the component and arguments to the methods being called. The ChannelSet will not change and can be provided as a property. The username and password for the login method are arguments to the method and need to be provided as arguments. Within the source code you can see the difference as well, the ChannelSet is a property of the component, while username and password are not really visible in the code. The ChannelSetInvoker component uses the ResultEvent and the FaultEvent to communicate with handlers. You can register handlers in the Mate event mapping component. Of course we need to registers these handlers within the component. This is done in the complete function

    override protected function complete(scope:IScope):void {
        if (this.resultHandlers && resultHandlers.length > 0) {
            this.createInnerHandlers(scope, ResultEvent.RESULT, resultHandlers);
        }
        if (this.faultHandlers && faultHandlers.length > 0) {
            this.createInnerHandlers(scope, FaultEvent.FAULT, faultHandlers);
        }
    }

Time to move on to the fun part, the actual interaction with the ChannelSet. The components supports three methods (think about the three events we needed): login, logout and authenticated. The magic takes place in the run function.

    override protected function run(scope:IScope):void {
        var argumentList:Array = (new SmartArguments()).getRealArguments(scope, this.arguments);
        innerHandlersDispatcher = channelSet;

        if (method == "login") {
            if (!channelSet.authenticated) {
                var loginToken:AsyncToken = channelSet.login(argumentList[0], argumentList[1]);
                loginToken.addResponder(new AsyncResponder(
                        function(event:ResultEvent, token:Object = null):void {
                            scope.lastReturn = event.result;
                            innerHandlersDispatcher.dispatchEvent(event);
                        },
                        function(event:FaultEvent, token:Object = null):void {
                            scope.lastReturn = event.fault;
                            innerHandlersDispatcher.dispatchEvent(event);
                        }));
            }
        } else if (method == "logout") {
            var logoutToken:AsyncToken = channelSet.logout();
            logoutToken.addResponder(new AsyncResponder(
                    function(event:ResultEvent, token:Object = null):void {
                        innerHandlersDispatcher.dispatchEvent(event);
                    },
                    function(event:FaultEvent, token:Object = null):void {
                        innerHandlersDispatcher.dispatchEvent(event);
                    }));
        } else if (method == "authenticated") {
            var isAuthenticated:Boolean = channelSet.authenticated;
            scope.lastReturn = isAuthenticated;
            var event:ResultEvent = new ResultEvent("user is authenticated?", false, true, isAuthenticated);
            innerHandlersDispatcher.dispatchEvent(event);
        }
    }

Check how we use the provided arguments in the login method handling. AsyncToken objects are used to handle the asynchronous results of the login and logout methods. Finally the innerHandlerDispatcher is used to notify the registered handlers of new results. For the final piece of the puzzle, have a look at the implementation of the event handling. Due to the names of the tags the code is self explanatory.

<EventMap xmlns:mx="http://www.adobe.com/2006/mxml" xmlns="http://mate.asfusion.com/"
          xmlns:extensions="extensions.*">
    <mx:ChannelSet id="authenticationChannelSet">
        <mx:AMFChannel id="myAmf" uri="http://{props.host}:{props.port}/{props.webcontext}/messagebroker/amf"/>
    </mx:ChannelSet>

    <!-- Event handlers -->
    <EventHandlers type="{AuthenticationEvent.TRY}" debug="true">
        <extensions:ChannelSetInvoker method="login"
                                      channelSet="{authenticationChannelSet}"
                                      arguments="{[event.username,event.password]}">
            <extensions:resultHandlers>
                <MethodInvoker generator="{AuthenticationManager}" method="logInSuccess"
                               arguments="{currentEvent.result}"/>
            </extensions:resultHandlers>
            <extensions:faultHandlers>
                <MethodInvoker generator="{AuthenticationManager}" method="storeAuthenticationProblem"
                               arguments="{currentEvent.fault}"/>
            </extensions:faultHandlers>
        </extensions:ChannelSetInvoker>
    </EventHandlers>

    <EventHandlers type="{AuthenticationEvent.CHECK_NEEDS}" debug="true">
        <extensions:ChannelSetInvoker method="authenticated" channelSet="{authenticationChannelSet}">
            <extensions:resultHandlers>
                <MethodInvoker generator="{AuthenticationManager}" method="isAuthenticated"
                               arguments="{currentEvent.result}"/>
            </extensions:resultHandlers>
        </extensions:ChannelSetInvoker>
    </EventHandlers>

    <EventHandlers type="{AuthenticationEvent.LOGOUT}" debug="true">
        <extensions:ChannelSetInvoker method="logout" channelSet="{authenticationChannelSet}">
            <extensions:resultHandlers>
                <MethodInvoker generator="{AuthenticationManager}" method="logout"/>
            </extensions:resultHandlers>
        </extensions:ChannelSetInvoker>
    </EventHandlers>
</EventMap>

To be able to actually authenticate, we need a server component as well. With the RC2 release of the spring-flex project this has become incredibly easy. The next section talks about that part of the application.

Spring-flex, how easy can it be.

I do want to stress that the documentation coming with spring-flex is a good read. I recommend to read it to see all options that you have. For now I discuss only the basic steps.

http://static.springframework.org/spring-flex/docs/1.0.x/reference/html/ch04s02.html

• Configure the web.xml, add the dispatcher servlet and the springSecurityFilterChain for the initialization of spring security.
• I added one servlet mapping for *.properties. This is for loading the config.properties file through a spring bean. Check my post flex remoting without configuring the client to find out more on this topic.
• Configure BlazeDS using the services-config.xml file in the default location WEB-INF/flex. Remember that we do not need this file in the flex client anymore like we did in the past. It is also this file where you configure BlazeDS logging.
• Configure the security, be sure to look good before it is over.

    <!-- Bootstraps and exposes the BlazeDS MessageBroker -->
    <flex:message-broker>
        <flex:secured />
    </flex:message-broker>

    <!-- remote proxies -->
    <flex:remoting-destination destination-id="remoteBookManager" ref="bookManager" exclude-methods="internalUseStoreBook"/>

    <security:http entry-point-ref="preAuthenticatedEntryPoint"/>

    <bean id="preAuthenticatedEntryPoint"
        class="org.springframework.security.ui.preauth.PreAuthenticatedProcessingFilterEntryPoint" />

    <security:global-method-security>
        <security:protect-pointcut
            expression="execution(* nl.gridshore.samples.books.business.*Manager.store*(..))"
            access="ROLE_ADMIN"/>
        <security:protect-pointcut
            expression="execution(* nl.gridshore.samples.books.business.*Manager.obtain*(..))"
            access="ROLE_USER"/>
    </security:global-method-security>

    <security:authentication-provider>
        <security:user-service>
            <security:user name="admin" password="admin" authorities="ROLE_USER, ROLE_ADMIN"/>
            <security:user name="user" password="user" authorities="ROLE_USER"/>
        </security:user-service>
    </security:authentication-provider>

As you can see, most of the configuration deals with method-security and the authentication provider. It takes around 5 lines of code to configure spring security to receive all incoming authentication requests and connect to BlazeDS security. I think this is pretty amazing. During the refactoring I could remove a lot of configuration and a java class. Also the client code has become a lot easier and adheres to standards of flex remoting.

Concluding

That is it, now we have a much cleaner sample. Be sure to check out the code and of course the referring frameworks. I also want to mention the extendability of the Mate framework. At first I had to understand some basic concepts, but than it become easy to write an extension. I hope you like the blog. Questions and commands are welcome.

See you again next time.

• flex-mojos (3.1) – the maven flex plugin
• Mate (0.8.7.1) – a flex framework
• Spring BlazeDS Integration 1.0.0.RC1

Read on to find out the changes I had to make, the problems I ran into (not that much actually).

Maven build

Let us start with the build system. I want to upgrade to the latest and greatest 3.1 version of the flex-mojos plugin. This is not hard, there is excellent documentation available in the form of this open source book.

I did not have to make a lot of changes, the groupId and the artifactId of the plugin have changed, but that is easy. I do have problems running the tests on a mac. The mentioned book does give a method to make the flex unit tests work, but it does not work for me like I would have wanted it to. It seems that the call to the flash executable is wrong. The suggested way is to cp the Flash Player.app to the /Applications folder. Please do not do this using sudo, I prefer to do it by hand using the Finder. Another problem is the call from the plugin. It calls FlashPlayer.app, I think It should be Flash\ Player. Therefore I add the following directive to the maven command:

-DflashPlayer.command=Flash\ Player

This only works if you make sure the player is on the path, I included the following line in my .bash_profile file:

export PATH=$PATH:/Applications/Flash\ Player.app/Contents/MacOS

Now the application is running again. Time to move on.

Mate

Mate is now upgraded to the released version 0.8.7.1. I did not find a good repository containing this release for maven. Therefore I had to add it manually. I did not really go into the new features. I see there are mock objects now for services. I have not come up with the right way to use them without changing my code in for instance unit tests. Therefore there are no exiting things to do for mate. Feel free to add a comment if I missed something.

Spring BlazeDS Integration

It seems to be a small step, but I had to make some adjusments. I had to change the bean from flex:remote-service into flex:remoting-destination. Beware to change the service-id into destination-id if you need another name of the destination than the default name deduced from the exposed bean. This was not right at the moment in the documentation.

The flex:remoting-destination configuration than becomes:

<flex:remoting-destination destination-id="remoteBookManager" ref="bookManager" exclude-methods="internalUseStoreBook"/>

To make this all work, I had to add a dependency which is optional by default but I did need it. Not sure why.

<dependency>
    <groupId>org.codehaus.jackson</groupId>
    <artifactId>jackson-core-asl</artifactId>
    <version>0.9.9-6</version>
</dependency>

The next problem I ran into, had to do with the following error message. I do only show the first line, not the complete stacktrace.

Problem with the : org.springframework.beans.factory.NoSuchBeanDefinitionException:
        No bean named '_filterChainList' is defined

As described is this forum post, this can be resolved by disabling session fixation in the http configuration of spring security. Jeremy has tested this as well and stated it is indeed a bug. A fix is committed and will be in the next release.

Now everything is working again. I am personally not fond of the spring dependencies labelled 2.5.6.A. These have to do with the special OSGi enabled jars. But they give a lot of double dependencies on external jars. Luckily Jeremy has promised to create a version without the OSGi versions as well. Check this post. The responsiveness of the community and the committers is great, this is what I like so much about the spring framework. I had to say it

Some additional remarks

Next to the framework upgrades I also want to mention some things you can find in the sample. I added a unit test based on FlexUnit. I took the flex security out of the normal project and placed it into a seperate swc project.

What is left? Well I need to add the old features in the new mate version. You cannot add new books at the moment. I also want to have a good look at the security integration in the BlazeDS integration project of the spring framework. I also want to do some messaging, which I have done already in another project. Finally I have a nice maven solution to print a build version number in the flex application. If you like that idea, be patient. I’ll try to write my next post about that topic.

Thanks for reading, hope to see you back soon. Do not forget to connect to me via linkedin, gridshore has it’s own group. You can also stay up to date using twitter.

References

• http://www.sonatype.com/books/maven-book-stage/reference/ch20.html – reference manual for the flex maven build plugin.
• http://www.statusq.org/archives/2008/07/30/1954/ – reference to the easiest way to get wget on your machine.