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

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