A little bit of history

When I first discovered Flex, one of my first obsessions was how to make it work with a Java backend. I’m a java developer at heart and my Java backend stack of choice back then was Spring/Hibernate-based. That’s why I published a series of full-stack articles that became quite popular. But another obsession of mine has always been productivity so when I discovered Grails, it became my new preferred environment and I started looking for ways to plug a Flex frontend into a Grails backend. All of this work culminated in the release of my Grails BlazeDS plugin which worked great but had a few limitations (only Java DTO’s, run-war instead of run-app, etc.). I mean, it worked great… until it didn’t. For some obscure reason, my plugin didn’t work at all with Grails 1.3.x. I fought with this for months, but there were just too many technologies involved (Groovy, Grails, BlazeDS, Spring-Flex, Spring, etc.) and my knowledge of some of those technologies was too shallow to really understand everything happening under the hood. That’s why I called upon SpringSource and/or Adobe to help me or provide the community with a decent Flex support for Grails. And guess what! They listened. A couple of months ago, I got in touch with Burt Beckwith, from SpringSource, who intended to work on that. So he asked me for feedback and really that’s all I did: I explained to him some of the issues I had with the plugin, the typical environment that we Flex developers work with, etc. And today… TADAAAA! The new Flex support plugins are here.

Yes, you read it right: there are several plugins. As there can be several options for working with Flex and Grails, we decided to split support into 3 main plugins:

• The rewritten BlazeDS plugin integrates BlazeDS 4 into Grails and handles all the AMF remoting. You can use it alone if you want to have a separate project for the Flex frontend, which is my preferred setup and what I’m going to illustrate in this tutorial.
• The rewritten Flex plugin allows you to mix your Flex sources right into your Grails project and compile your Flex code on the fly using the Flex compiler servlet. I think this is a good setup for prototypes and simple applications. It depends on BlazeDS plugin.
• The upcoming revamping of the Flex-Scaffold plugin will allow you to generate some CRUD UI for your domain. This one is still under work but it will probably depend on both BlazeDS and Flex plugins.

As I already said, my favorite setup for developing a Flex frontend on top of a Grails backend is to separate both into two different projects. Since the main artifact produced by Flex compilation is a single SWF file, I think it’s cleaner to have one module specifically for it. This vision probably comes from my Maven experience, where each package deserves its own module. Another positive aspects is that it’s very frequent to have several Flex widgets in a single webapp, so having a separate project for each widget and then bundle them all into the Grails webapp is obviously cleaner. Also, the preferred environment for working on Flex projects is definitely Flash Builder (and it hurts me to admit it because I really hate Eclipse with all my heart). Flash Builder has its own vision of a Flex project structure, and messing with it can be risky at times. So this split setup allows me to use the best tool for each job: I work on the Grails part in IntelliJ IDEA, and the Flex part in Flash Builder and everything runs smoothly.

So if you don’t agree with me and prefer to have everything in one place and/or use SpringSource Tool Suite for everything, be my guest. Otherwise, you will probably be interested in what follows.

Grails-BlazeDS 2.0

The new Grails BlazeDS plugin is a completely rewritten version of Grails BlazeDS 1.0, which I released in April this year. Let me say once again that I don’t have anything to do with the code of this new version and that I am very grateful to Burt Beckwith for taking over my work and making it so much better. Amongst all the issues he solved, here are the biggest ones:

• Obviously the first version worked with Grails up to version 1.2.x, but not with more recent 1.3.x versions. The new plugin works great with both 1.2.x and 1.3.x
• In the first version, you had to use Java classes for Data-Transfer Objects, which was obviously less productive than Groovy classes. This was because Flash Builder’s DCD generator didn’t like Groovy compiled classes and didn’t know how to generate ActionScript counterparts for those. This is completely solved with version 2.0 of the plugin.
• The BlazeDS DCD generator in Flash Builder also relies heavily on a certain web app directory structure which it couldn’t find with Grails run-app dynamic mode. So we had to use run-war instead, which was much less productive as we had to restart the application every time something changed. This is not the case anymore. Version 2.0 works great with run-app.
• In the old version, Spring-Flex’s dispatcher servlet was configured in a flex-servlet.xml file which was copied into your project when you installed the plugin, and that you had to maintain manually afterwards. This flex-servlet.xml has completely disappeared in version 2.0.
• Version 1.0 integrated with Grails Acegi plugin for security. But Burt Beckwith has also completely rewritten security support recently. Version 2.0 of Grails BlazeDS plugin integrates with those new Spring Security plugins for Grails.
• And of course this new version now includes the latest versions of BlazeDS and Spring BlazeDS Integration, which makes it possible to support the latest version of Flex (Flex 4.1).

As you can see, Grails finally has some decent Flex support and in the rest of this article, I will show you how to start using it for building a simple Grails/Flex application. Of course, this tutorial completely supersedes my previous posts about Grails BlazeDS 1.0.

Backend

First of all, you will need the latest version of Grails. As I said, Grails BlazeDS 2.0 works with Grails 1.2 and 1.3 alike, but we might as well use the latest version of Grails.

Apart from that, I’m gonna use IntelliJ IDEA and Flash Builder a lot in this tutorial. Nothing forces you to install them if you don’t have them already. If you’re already familiar with your own environment, feel free to adapt my instructions to it. Otherwise, this might be a good opportunity to test out this configuration. If you need it, a 60-day evaluation of IntelliJ IDEA Ultimate can be downloaded here (you will need the Ultimate version as the free Community edition doesn’t have Grails support built in).  In this tutorial I’m gonna use the latest EAP release so that my screenshots are consistent with IntelliJ IDEA X version that should be released in the coming weeks. But if you prefer, you can use IntelliJ IDEA 9.0.4.

As for Flash Builder 4, you can download it from here and any edition (normal or premium) will do it.

Once you’ve got everything set up, let’s create a new Grails application project and call it todolist. You can either run “grails create-app todolist” from the command line or create it within IntelliJ IDEA.

Choose Grails Application as your type of project and set the name of the project to be “todolist”.

Choose grails-1.3.5 as Grails SDK version. If you copied it to your system but never used it before, just click the “Create…” button and choose your grails-1.3.5 directory. You will be asked if you want to create a project-specific or a global library for Grails. Choose the global library option if you don’t want to reconfigure your Grails SDK for every new project. Then hit Finish.

Choose “Run ‘create-app’” option to create an application and not a plugin.

Once your project is created and all the background processes have finished running, we are going to create an entity called org.epseelon.todolist.domain.Task. To do that, you can either use the “grails create-domain-class org.epseelon.todolist.domain.Task” command, or right-click grails-app/domain directory and choose New/Grails Domain Class:

Once your Task class is created, make it look like the following:

[sourcecode language=”groovy”]
package org.epseelon.todolist.domain
class Task {
String title
static constraints = {
title blank:false
}
}
[/sourcecode]

We’ll keep it simple for now, you can add some more fields later. Once this class is created, let’s add a few lines to grails-app/conf/BootStrap.groovy in order to create a few test tasks when the application is started. Remember that by default, Grails runs on an in-memory database, so all your database will be dropped and recreated with our 3 test tasks every time the application restarts (which includes when a class is recompiled).

[sourcecode language=”groovy”]
import org.epseelon.todolist.domain.Task

class BootStrap {

def init = { servletContext ->
new Task(title:”Task 1″).save()
new Task(title:”Task 2″).save()
new Task(title:”Task 3″).save()
}

def destroy = {
}
}
[/sourcecode]

At this stage, you can already start your application if you want to make sure it runs alright before we install Grails BlazeDS plugin.

Now, let’s install Grails BlazeDS 2.0. You can use the command “grails install-plugin blazeds”, or you can right-click your project in IntelliJ and choose Grails/Plugins:

Make sure you reload the plugin list and check the box beside blazeds 2.0:

Then hit “Apply Changes” and then “OK” to install the latest 2.0 release. Wait for the plugin to be installed with all its dependencies, which include Spring Security Core and Spring Security ACL but we will configure those later. When you’re done, the todolist-grailsPlugins module should look like the following:

Next, we will create a simple DTO for the task entity. If you’ve read my previous posts, you know that I love DTO’s and I strongly discourage you to use domain entities as DTO’s for plenty of reasons, all the more so as they’re particularly easy and fast to create and manipulate with Groovy. Since there is no dedicated directory for DTO’s in Grails’ layout, we are going to create it under src/groovy:

Let’s call it org.epseelon.todolist.dto.TaskListItem:

When the class is created, make it look like the following:

[sourcecode language=”groovy”]
package org.epseelon.todolist.dto

class TaskListItem {
Long id
String title
}
[/sourcecode]

It has one more field than our Task entity because you don’t need to specify that an entity has an id. Grails creates it automatically for you.

The next thing to do is to create a simple TodoListService under grails-app/services. To do that you can use the following command: “grails create-service org.epseelon.todolist.business.TodoList” (no need to indicate the “Service” suffix, grails will add it automatically for you). You can also right-click your grails-app/services directory and choose New/Grails Service:

When your TodoListService class is created, make it look like the following:

[sourcecode language=”groovy”]
package org.epseelon.todolist.business

import org.epseelon.todolist.dto.TaskListItem
import org.epseelon.todolist.domain.Task
import org.springframework.flex.remoting.RemotingInclude
import org.springframework.flex.remoting.RemotingDestination

@RemotingDestination
class TodoListService {

static transactional = true

@RemotingInclude
List getAllTasks() {
return Task.findAll().collectAll {
new TaskListItem(
id: it.id,
title: it.title
)
}
}
}
[/sourcecode]

Note that normally, you don’t need to specify the return type of a service method in Groovy, but it’s always better practice to do it for API kinds of methods, and it’s mandatory in our case because Flash Builder needs to know argument and return types in order to generate ActionScript counterparts for them.

Also note the RemotingDestination and RemotingInclude annotations that BlazeDS uses to identify which services and which methods to expose over AMF remoting.

Once you have this class, everything is ready on the backend side, so you can start your application using "grails run-app" command or using the Grails:todolist Run/Debug configuration created by IntelliJ IDEA when you created the project. Make sure your console output ends with something like the following and that there is no exception:

[sourcecode language=”bash”]
Running Grails application..

Configuring Spring Security …
Configuring Spring Security ACL …
[BlazeDS]Endpoint ‘my-polling-amf’ created with security: None
at URL: http://{server.name}:{server.port}/{context.root}/messagebroker/amfpolling
[BlazeDS]Endpoint ‘my-longpolling-amf’ created with security: None
at URL: http://{server.name}:{server.port}/{context.root}/messagebroker/amflongpolling
[BlazeDS]Endpoint ‘my-amf’ created with security: None
at URL: http://{server.name}:{server.port}/{context.root}/messagebroker/amf
[BlazeDS]Endpoint ‘my-secure-amf’ created with security: None
at URL: https://{server.name}:{server.port}/{context.root}/messagebroker/amfsecure
Server running. Browse to http://localhost:8080/todolist
[/sourcecode]

Frontend

Now let’s switch over to Flash Builder. You can also use any other method to create a Flex project, but I’m gonna use Flash Builder here to show you how productive it can be.

First things first, let’s create a new Flex project:

Our project will be called todolist-flex. Make sure you select the right Flex SDK, in our case Flex 4.1. Also note that Application server type should be set to J2EE and BlazeDS should be used as a remote object access service.

Once you click Next, that where the little trick happens. It’s not always easy to figure out how to configure server settings. So just for your information:

• Root folder is where Flash Builder expects to find a services-config.xml file under WEB-INF/flex, so in our case that the web-app directory of our Grails application
• Root URL is the address that Flash Builder will go to when you run your Flex application, and where its debugger will start listening when you debug your app
• Context root is where your app is visible relative to your host name. I guess Flash Builder needs that to assign a value to the contextRoot token when compiling services-config.xml into your application, but I’m not sure about that.
• Output folder is where Flash Builder will compile your SWF and generate an HTML wrapper for it

Don’t worry about the warning. Flash Builder won’t delete everything there is already in your web-app folder, it will just add files to it.

Then click Finish directly. When your project is created and Main.mxml is open, let’s go to Design mode and add a simple List to it:

In the bottom part of Flash Builder window, activate the Data/Services tab and click the “Connect to Data/Service…” link:

In the dialog that appears, choose BlazeDS and click Next:

No authentication is required to access the RDS servlet in our application (that’s the servlet that allows Flash Builder to do its reverse-engineering wizardry to generate ActionScript stubs for our backend services), so check “No password required” and click OK. Remember that at this stage, your Grails application should be running or Flash Builder won’t find what it needs.

Now you should see our todoListService proudly appearing in the destination list. You can check the box next to it and click Finish to generate client stubs for our service.

The Data/Services view shows everything it knows about our service:

And Flash Builder generated a certain amount of code that will allow you to use the todoListService in a type-safe way:

What you should know is that all the files whose name starts with an underscore will be replaced every time your regenerate client stubs, and any custom code you write should go in the non-regenerated classes only (here TaskListItem.as and TodoListService.as).

Now let’s drag-and-drop our getAllTasks() operation from the Data/Services view onto our List in the Design view:

In the Bind To Data dialog that just appeared, simply select title as the label field for our List. As you can see Flash Builder understood that our List will display instances of TaskListItem and it identified possible fields for the displayed label of each item in the list.

Now if you go back to the Source mode of our Main.mxml file, here is what you should have:

[sourcecode language=”xml”]



[/sourcecode] As you can see, the generated code is pretty clean. Now just run your Flex application… and TADAAA! That’s it, you just created your first Grails/Flex application using Grails BlazeDS plugin version 2.0. It can’t be easier. I’ll leave you here for now. Next time, we will add an operation to create tasks and secure it with Spring Security ACL.