Railo – BlazeDS

As promised here a first glimpse about the BlazeDS integration into the Railo 3.1 beta. We are not yet where we want to be, but you can already start to use BlazeDS in several ways. In this post I want to show you how BlazeDS is integrated into Railo and how and where it is pre-configured. I will also try to explain you which things do not yet work properly, so you don't need to file bugs for this cases. If you find bugs, of course please tell us.

For me, Railo is not only about cf but also about Java, therefore I plan to do several post about the Flex / Railo / JEE stack over the coming weeks. But first things first, let's start with an easy example based on which I intend to explain you the details of the configuration:
If you didn't have it already, download the actual version Railo Express, for me this is a "railo-3.1.0.012-railo-express-6.1.0-with-jre-windows.zip". This Railo version already includes the BlazeDS 3.2.0.3978 jars and the RailoAdapter which we need to communicate from Flex to Railo.
After you have unzipped Railo Express, you have to start Railo once, so that it is initialised properly and you should find the WEB-INF folder in the Railo [railo-install-dir]/ webroot. Inside the WEB-INF you will find a flex folder containing the BlazeDS configuration files.

As a side note for the java cracks, the BlazeDS jars can be found in the lib folder, while the MessageBroker Servlet is mapped and initialised in the webdefault.xml file which can be found in the etc folder. So if you want to update BlazeDS later or even want to use for example SpringBlazeDS these are the places where you have to look and make your changes. We will look at this in more detail later.

Let's do an easy example first. To keep things easy, let's now start with the example and just run it. To be sure that BlazeDS is already working as expected open a browser of your choice and browse to http://localhost:8888/flex2gateway. If anything went fine your result should be a white page without any errors.
Now put a Hello.cfc into the [railo-install-dir]/webroot containing following code:

I use Eclipse for both, the FlexBuilder plug-ins for Flex and CFEclipse for ColdFusion. One way to doe this easily in CFEclipse is to go to File -> New, create a new CFML Project and name if for example railo-blazeds-hello-cfml. After that, right click on you new project, go to New -> Folder, click on Advanced, check "Link to folder in the file system" and browse to your [railo-install-dir]/webroot. You can now add your cfc and also easily browse the WEB-INF folder.

The next step is to switch to FlexBilder or another IDE you use to program you Flex applications and make a small Flex app. In FlexBuilder go to Files -> New -> New FlexProject, enter a name for you project, for example railo-blazeds-hello-flex and click on Finish. You don't need to use and set the application server type to JEE or ColdFusion, we will give our RemoteObject anything it needs directly in the code.*
So, the following mxml should do the trick:
Run the Flex application, right click on main.mxml and choose Run As Flex Application and you should see the "Hello from Railo!" in your browser. Cool, what you hopefully successful could do was an rpc call through Flex over BlazeDS to Railo and back to Flash. Some troubles we still have

Of course there is much more to say about this than just a helloworld example. So after doing the easy part, let me try to explain what you can do already and for which parts you still have to wait. (we hope not al to long! :)
Unfortunately we weren't able to solve a last important piece before the launch of this beta. At the moment you can only serialize simple data types. If you try to load your own objects or other complex types you will run into a java exception. For the moment this is also a show stopper if you try to serialize Structs or Queries, at least if they contain something else than simple types. You will also notice that you receive some ObjectProxies instead of ArrayCollections etc. Sorry for this, we are sure to be able to solve all these problems in the very near future.

For those of you that want to update to Railo 3.1 now, I can only say that OpenAMF is still in place and can be used over /openamf/gateway/ (instead of /flashservices/gateway/). To stay backward compatible with FlashRemoting before the BlazeDS days, we plan to just keep and use OpenAMF. But if possible, we would like to run /flashservices/gateway/ over BlazeDS. Unfortunately, as someone on the Railo mailing list also already found out, if you call the /flashservices/gateway/ at the moment you also receive a java exception. So at the moment the solution is to use /openamf/gateway/ instead /flashservices/gateway/. Of course you can also use the HttpService and WebService objects in Flex, but why do so if we have BlazeDS? ;)

So, how does it work then and what do we have?

If you are not scared away by now and still follow along, go to railo-install-dir]/etc and open the webdefault.xml. You will find that the MessageBrokerServlet as well as the AMFServlet are started when Railo starts. The mappings point to the MessageBroker for /flex2gateway/, /messagebroker/ and /flashservices/gateway/ respectively, while /openamf/gateway/ points to the AMFServlet.
Now, go to [railo-install-dir]/webroot/WEB-INF/flex and take a look into remoting-config.xml. Under adapters you will find an adapter definition which uses the RailoAdapter and where default is set to true.
The RailoAdapter implements the hook into BlazeDS and calls Railo if the MessageBroker Servlet is requested. The default true means that the RailoAdapter is used as the default adapter for your destinations. You will find the ColdFusion destination already pre-configured. Also notice the * between the source tags. This means that you must set the source property in your Flex RemoteObject, as we did in the example above. So in your RemoteObject you need to set the destination to ColdFusion, the source to your path.to.cfc and the endpoint to the /flex2gateway/.
As you can see the JavaAdapter is still in place, so you could use BlazeDS to call Railo or a Java class in parallel. To do that, you need to add a new destination and enter the path to your class as the source. Because the RailoAdapter is the default adapter, you will have to add the JavaAdapter and the my-amf channel to your destination. Now you should be able to call your endpoint over /messagebroker/amf.
So, that's it for the first post on the subject. I think the BlazeDS integration is important step for Railo and will bring flexibility to applications which use Flex and Flash together with Railo and Java. At least it opens up a whole bunch of approaches how Railo can be used. For example, personally I like to use Railo in a double role as the web and html template server, but also as a service layer which delegates to my java backend.

Depending on the use case I can implement my delegates as cfc's or pojo's, so based on the situation, if my persistence mapping is already in place and I want to delegate to a backend facade I could just add a java delegate or if I want to do some rapid development directly in Railo I can use a cfc. The coming days we will focus to solve the last issues and I hope I will be able to write my next post about the successful serialization of all cf types. We should then also be able to look at these other nice things like push over http or messaging.
Stay tuned...

*To be honest, I configure my Flex application almost always at runtime and debug them directly on the file system (either with or without the html-template files), so normally I don't link to the service-config file in my Flex compiler arguments. Please tell me if you would like to have more information about how to configure the several application server types in FlexBuilder. If there is a need, I will do a post later explaining the different options which would be relevant for Railo.