Whereas Flash provides an animation-centric environment with support for creating timelines and importing graphics and the like (with the expectation that script that was added would be done so as event handling logic in ActionScript), Flex is a code-centric platform. The two source artifacts of a Flex application are the ActionScript files (ending in .as) and the .mxml files.

ActionScript files can contain classes, public functions and variables, and annotations. Indeed, ActionScript files may house any number of public classes. The look and feel of the language will feel familiar to anyone who's used Java, C#, or Scala.

MXML files are an XML variant that describe the UI components and provide a DOM. Scripts may be inline, which we will do for this chapter's trivial examples in the name of expediency. Each tag in MXML describes a component or object that is registered with its container. In the case of Flex applications, the outermost tag is the <mx:Application/> tag; in AIR, it's <mx:WindowedApplication/>. These tags describe containers that themselves handle all the minutiae of creating components on the Flash Stage object.

You can use MXML to instantiate regular ActionScript objects, like you might in Spring, but you'll find that some uses will more naturally lend themselves to code and some to MXML. You could create an entire Flex application using only ActionScript with no MXML. When the MXML files are compiled, they are converted to ActionScript expressions as an intermediary format, and that is what is ultimately compiled. MXML files support a limited form of expression language binding (limited when compared to the EL support in frameworks like Tapestry or JSF, anyway). Flex components are wired together using the expression binding support, as well as with powerful event mechanism.

Let's look at a simple MXML file:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application
xmlns:mx="http://www.adobe.com/2006/mxml"
applicationComplete="applicationCompleteCallback(event)">

    <mx:Script>
        <![CDATA[

             import mx.events.FlexEvent;
             import mx.controls.Alert;

             public function applicationCompleteCallback(fe:FlexEvent):void
             {
                 Alert.show('Hello World!'),
             }

        ]]>
    </mx:Script>

</mx:Application>

This MXML describes the simplest possible Flex application. As soon as the application has been loaded and all the objects configured, an event will be fired—the applicationComplete event. Just as you can in the browser, you have two choices for listening to events in Flex: programmatic registration and through MXML attributes on the component that fires the event. Here, we've installed our listener using the applicationComplete attribute on the mx:Application tag. It's very convenient to use MXML event subscription in most cases, though sometimes, you want to programmatically register listeners.

Let's try another example with a button that displays an alert when clicked. We'll register the event through ActionScript, instead.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application
        xmlns:mx="http://www.adobe.com/2006/mxml"
        applicationComplete="applicationCompleteHandler(event)">

    <mx:Script>
        <![CDATA[

        import mx.controls.Alert;
        import mx.events.FlexEvent;

        private function applicationCompleteHandler(evt:FlexEvent):void
        {
            button.addEventListener(MouseEvent.CLICK, onClick);
        }

        private function onClick(me:MouseEvent):void
        {
            Alert.show('Hello, world!'),
        }

        ]]>
    </mx:Script>
    <mx:Button id="button" label="Say Hello"/>
</mx:Application>

I won't belabor the point but for one more example; this is a JavaScript variant, after all! The previous example could have been rewritten to use an anonymous function:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application
        xmlns:mx="http://www.adobe.com/2006/mxml"
        applicationComplete="applicationCompleteHandler(event)">

    <mx:Script>
        <![CDATA[

        import mx.controls.Alert;
        import mx.events.FlexEvent;

private function applicationCompleteHandler(evt:FlexEvent):void
        {
            button.addEventListener(MouseEvent.CLICK,
            function (me:MouseEvent):void  {
              Alert.show('Hello, world!'),
            });
        }

        ]]>
    </mx:Script>
    <mx:Button id="button" label="Say Hello"/>
</mx:Application>

In the preceding examples, we did nothing special to access the object created by the <mx:Button /> tag, except to refer to it by its id attribute, button. We didn't need to use something like document.getElementById(String), as you might expect from the browser.

Now, let's look at a simple ActionScript class. We'll flesh out this class more later, but for now, it's helpful to see what it looks like to define a Plain Old ActionScript Object (yes, Virginia, that is what it's called!):

package com.apress.springwebrecipes.auction.model
{
public class Item
{
    private var _sellerEmail:String;
    private var _basePrice:Number;
    private var _sold:Date;
    private var _description:String;
    private var _id:Number;

    public function get id():Number {
        return _id;
    }

    public function set id(value:Number):void {
        _id = value;
    }

    // ...

}
}

This should seem pretty intuitive. Most striking is the C++/C#–style package syntax; the package declaration wraps the classes. Here, we only have one, but we could have as easily defined 20. We won't get into the gory details of visibility rules, but suffice it to say that public and private work pretty much the way you'd expect them to. The next element to note is that ActionScript has a proper property syntax. We declared a private class variable _id, of type Number. Then, we declared two functions that look a little different than the other functions you've seen thus far. These functions have the keyword get and set and share the same function name. This is the language support for defining accessors and mutators, just like with Java's JavaBeans. Unlike JavaBeans, however, there is syntactic support to let the users manipulate properties like they would public instance variables. To use the preceding class, we could write something like this:

package com.apress.springwebrecipes
{
    import com.apress.springwebrecipes.auction.model.Item;

    public class ItemDemo
    {
        public function ItemDemo()
        {
            var item:Item = new Item();
            item.id = 232;
        }
    }
}

The most common tool for building Flex applications, by far, is Adobe's Flex Builder tooling. It is what we'll use in this chapter. Flex Builder is an Eclipse-based IDE. The IDE provides compilation, debugging, and wizard support for developing ActionScript- and Flex-based applications. It also has a visual designer, but experience has shown that it serves little purpose for moderate-sized applications. Flex Builder features support for working with other tools in the Adobe Creative Suite, including Flash Professional (which, as indicated previously, is useful for timeline based applications and components), Photoshop, and Illustrator.

Arguably, Flex's most powerful feature is its integration with other Adobe tools, in support of Adobe's vision of the designer/developer workflow.

Flex supports the concept of states. With a state, you can assign arbitrary names to given sets of components and configuration and, by setting the currentState property, have the engine activate that state. A state can prescribe that components be added or removed a display. It can also outright replace the current display. There is a lot of potential here. These states are used to describe a widget's state on screen, too. The Adobe Creative Suite facilitates exporting Photoshop or Illustrator assets, for example, and mapping the layers of those assets to states in a Flex component. You might imagine a button whose mouse-over, mouse-down, mouse-up, hover, focus, and other states each are each assigned a layer in a Photoshop file—a layer for the focus state might render the button with a glow; the layer for mouse down might darken the colors, and so on.

There are many other such niceties, but ultimately, they are all available even without Flex Builder, using the stand-alone compiler, if you know where to look.

Indeed, the single simplest and most cost-effective way to get started with Flex is to use the SDK. You can download the SDK from Adobe's site for free. At the time of this writing, the most current version of the SDK is 3.5. You may download it at http://www.adobe.com/cfusion/entitlement/index.cfm?e=flex3sdk.

To use the SDK, download it, and extract the archive. Put the bin folder inside the SDK on your system's PATH variable, just as you might with Ant, Maven, and the Java SDK. The Flex SDK offers two compilers: one for components, and one for Flex applications. If you want to compile components, you will use compc. If you want to compile an application, you will use mxmlc. An example invocation of the mxmlc says it all:

mxmlc main.mxml

The Flex SDK compilers are written in Java, so you could also invoke them using the java command. What follows is an invocation of the compiler using Java. This does the same thing as the preceding command. The following invocation is assumed to be in the bin directory of the SDK. There should be no breaks in your command, though; it should all be on one line.

java -jar ../lib/mxmlc.jar +flexlib ../frameworks test1.mxml

Another approach for developing application is to use Maven. The FlexMojos project (http://flexmojos.sonatype.org/) is a set of plug-ins supporting building Flex projects and handing dependency resolution, just as Maven does for Java projects.

Because the runtime and compiler are available, other IDEs have built support for Flex. One very good integration is IntelliJ's IDEA 9.0. It supports coding, compiling, refactoring, debugging, and all the basics you'd expect of a good IDE. While it doesn't support the visual design mechanism or many of the wizards that Flex Builder has, it does excel in some areas where Flex Builder falls short: IDEA supports formatting code, for example, import of Maven FlexMojos projects, and refactoring (renaming) of MXML fragments. Flex Builder is a set of plug-ins built on Eclipse. You may run Flex Builder stand-alone or integrated with an existing Eclipse installation. By itself, Flex Builder lacks an XML editor, support for Subversion, and any kind of support for Java. Additionally, Flex Builder is usually coupled with an older revision of Eclipse.

Clearly, there is no shortage of ways to approach the problem. If you can swing it, the Flex Builder tooling will be familiar to Adobe users. IntelliJ users have no need to switch. Failing those options, the SDK and various build systems welcome any would-be Flex developers.

Let's start with the simplest option: talking to the host page. Often, a Flex application will need to be configured at launch. You can launch a Flash application using FlashVars as parameters, just as you can launch a Java application with arguments.

Before diving into that, let's talk about Flex deployment. To deploy a Flex application, you need to embed markup in the browser to enable the browser to display the Flash content, since it is not part of browser's native capabilities. There are many ways to generate this configuration. The configuration for the embed and object tags can be quite convoluted because no single configuration works reliably over the many target browsers. Flex Builder will generate a default version, but this markup is fragile and can quickly become unmaintainable. To save space, we won't bother reprinting it. Instead, we recommend using the SWF Object JavaScript library (http://code.google.com/p/swfobject/wiki/documentation). Simply download the JavaScript library and put it in your web application. The library dynamically generates the relevant object and plugin tags, along with the FlashVars parameters. Because the JavaScript library dynamically adds the plug-in content to the page, it triggered the "Dynamic Content" warning in Internet Explorer 6 for a few years. This is, in practice, less and less of an issue now that newer versions of Internet Explorer 6 (and indeed, all subsequent versions, too) no longer have this issue.

Here is a minimalistic use:

<html>
    <head>
        <title> Hello World </title>
        <meta http-equiv="Content-Type"
              content="text/html; charset=iso-8859-1" />
        <style>
            body,html { padding:0; margin:0 }
        </style>
        <script type="text/javascript" src="swfobject/swfobject.js"> </script>
        <script type="text/javascript">
            var flashVars = {
              parameter1: 'parameter1',
              parameter2: 'parameter2'
            };
            swfobject.embedSWF(
              "helloworld.swf",
              "helloworld",
              "500",
              "500",
              "9.0.0",
              "swfobject/expressInstall.swf",
              flashVars );
        </script>
    </head>

<body>
        <div id="helloworld"></div>
    </body>
</html>

The first bold line shows the inclusion of the script. Further down, you see the invocation of the swfobject.embedSWF method. The first parameter is the name of the SWF asset (relative to the current page, of course). The second parameter is the id of the HTML element on the page that should be replaced when the SWFObject tries to paint the Flex application. Here, we want the Flash application to render where the div element with the ID of "helloworld" is, which is shown further in the following example in bold. The plug-in and object instances will be created with an ID of helloworld.

Finally, coming around to the original point, toward the top, we define a variable (flashVars) that is an associative array of keys and values. These keys and values are passed as parameters to the Flex application (note that it is passed as the last parameter to the swfobject.embedSWF method). The Flex application may get at these variables from inside using the Application instance:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application
        xmlns:mx="http://www.adobe.com/2006/mxml"
        applicationComplete="setup(event)">

    <mx:Script>
        <![CDATA[

        import mx.controls.Alert;
        import mx.events.FlexEvent;

        private function setup(evt:FlexEvent):void
        {
           Alert.show (
' param1='+Application.application.parameters['parameter1'] +
' param2='+Application.application.parameters['parameter2'] );

        }
        ]]>
    </mx:Script>
</mx:Application>

You can use these variables to configure the state of your Flash (and Flex) applications. This works well for configuration options—which may be all you need to communicate from the host application. It is, tragically, only a one-way solution. If you want a bi-directional channel from the containing application (in our case, a Spring web application) to the Flex application, you need to pursue other options.

Because Flex lives inside the Flash VM, it's easy to think of it as being confined, when in fact, it is freely able to talk to the host environment. To talk to the containing HTML page, you can use the flash.external.ExternalInterface class. This class defines two static methods, call() (which lets the Flex application talk to the host) and addCallback() (which lets the host talk to Flex). The ExternalInterface class provides a communication line going both directions: Flex-to-host and host-to-Flex. This solution is appropriate when you don't have a lot you need to inside the Flex environment—perhaps you need to notify the host page of some events when drawing some graph, or perhaps your Flex environment only needs to make one Ajax call. Similarly, perhaps you're embedding Flex to take advantage of its multimedia support or its rendering capabilities, but you want to drive that rendering through events in the host container. This indirection is slower (naturally) than doing something directly from the host page or directly from the Flex application, but it can be quite appropriate in many situations.

If we want to talk to the host environment, we can use the call() method on ExternalInterface. It is a blocking call. Assume we have a function defined in the host HTML page called updateStatus:

<html>
  <head><title>Addition</title></head>
 <body>
  <div id ='status'></div>
  <script language='JavaScript'>
   function updateStatus (msg){
      document.getElementById('status').innerHTML = msg;
   }
  </script>

  <!--
    ...
    Flex/flash
    ...
  -->
 </body>
</html>

We could, of course, call methods that are already in the host environment, like window.alert(String). To call the updateStatus function from within Flex, you might do something like the following:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application
        xmlns:mx="http://www.adobe.com/2006/mxml"
        applicationComplete="setup(event)">

    <mx:Script>
        <![CDATA[
        import mx.events.FlexEvent;

private function setup(evt:FlexEvent):void
        {
             ExternalInterface.call(
               'updateStatus',
               'Hello, from the future! '+
               'The Flex application has '+
               'finished loading.'),
        }
        ]]>
    </mx:Script>
</mx:Application>

Now, to go the other way—from the host environment to the Flex application—you have to register the functions that you want the host environment to see using the ExternalInterface's addCallback method. Perhaps we surface a method in our Flex application to play a track of music given the String path to an .mp3 file. Let's first build the Flex code:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application
        xmlns:mx="http://www.adobe.com/2006/mxml"
        applicationComplete="setup(event)">

    <mx:Script>
        <![CDATA[
        import mx.events.FlexEvent;

        public function enqueueMP3Track( trackName:String) : void
        {
            //...
        }

        private function setup(evt:FlexEvent):void
        {
             ExternalInterface.addCallback('playTrack', enqueueMP3Track );
        }
        ]]>
    </mx:Script>
</mx:Application>

The first parameter to ExternalInterface.addCallback is the alias used to reference the function from the host page. On the host, calling the function should be pretty easy, but isn't, unless you're aware of the nuances between browsers. The following is a fairly fail-safe way of invoking the playTrack function from the host page:

<html>

  <head>
  <title>Our Jukebox</title>
  <script language='JavaScript'>
   function getFlexApplicationReference( flexAppId ){
      return navigator.appName.indexOf('Microsoft')!= −1 ?
        window[flexAppId] : document[flexAppId];
   }

   function startTheMusic(evt){
        getFlexApplicationReference('jukebox').playTrack(
                        'La_Camisa_Negra.mp3'),
   }
  </script>

  </head>

  <body onload='startTheMusic(event)'>

  <!--
    ...
    Flex/flash setup using the swfobject
      as before, with an ID of 'jukebox'
    ...
  -->
 </body>
</html>

This option works well when you need to expose functionality in one direction or another. You might have an application that's predominantly built using conventional web frameworks (Struts, Spring MVC, JSF, etc.) and Ajax (perhaps you've exposed Spring services using DWR). If you have an island of functionality that's better suited to Flex, you can use this integration to provide the few touch points your application needs to talk to the containing application.

Talking to HTTP or HTTPS resources is one of the simplest mechanisms for talking to other systems, yet it remains one of the most powerful. With the rapid adoption of REST-based services, HTTP is even more powerful an option for many architectures. Additionally, HTTP support opens the door to the numerous services exposing JSON or XML data. Fortunately, Flex provides robust support HTTP. Actually, it provides two robust options for HTTP.

The first option is the Flex class mx.rpc.http.HTTPService. You can employ the HTTPService using ActionScript or using MXML. The HTTPService works like wget or curl. You specify a URL (or a resource) to request and then specify a listener to react to the retrieved data. The HTTPService supports GET and POST methods. If you use a proxy, you can also use PUT and DELETE (which you're more likely to use when consuming REST-ian services.) You cannot request an HTTP resource unless the resource is on the same domain as the .SWF or that resource's domain's crossdomain.xml file is open to requests from your domain.

To use the object from code, you create an instance of mx.rpc.http.HTTPService. Let's look at an example usage:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application
        xmlns:mx="http://www.adobe.com/2006/mxml"
        applicationComplete="applicationCompleteHandler(event)">

    <mx:Script>
        <![CDATA[
        import mx.controls.Alert;
        import mx.events.FlexEvent;
        import mx.rpc.events.FaultEvent;
        import mx.rpc.events.ResultEvent;
        import mx.rpc.http.HTTPService;

        private function applicationCompleteHandler(evt:FlexEvent):void
        {
             var service:HTTPService = new HTTPService('http://127.0.0.1:8080/'),
             service.url = 'test.txt';
             service.method ='GET'; // redundant
             service.addEventListener(ResultEvent.RESULT,
              function(re:ResultEvent):void {
                Alert.show('the response is ' + re.result);
             });
             service.addEventListener(FaultEvent.FAULT,
 function(fe:FaultEvent):void {
   Alert.show('the error is ' + fe.fault.content);
             });
             service.send();
        }
        ]]>
    </mx:Script>
</mx:Application>

Here, we construct an instance of HTTPService and pass the root URL against which subsequent requests should be evaluated. You can, of course, leave this blank and specify an absolute URL for the url property. We're using relative requests, so the url, which is test.txt, is relative to http://127.0.0.1:8080. Therefore, the fully qualified URL for the asset is http://127.0.0.1:8080/test.txt. If you have placed the web application under a different context than the root one (/), be sure to prefix test.txt. Here, the method property lets us specify which HTTP verb to use. There's no need to specify GET though, because it's redundant. To receive notification that the HTTP request was successful, we configure an event listener (for the result event). From this listener, we can access the payload of the response via the ResultEvent object instance's result property, re. If the request is not successful, we can get a notification by specifying an event listener for the fault event. Here, we interrogate the fault from the FaultEvent instance's fault property. Finally, we send the request. We could optionally specify headers as parameter to the send method using an associative array. Thus:

...
service.send({customerID: '23232432sssh543'});

There are other options available, including support for HTTPS, cookies, more sophisticated encoding of requests and responses, and so on.

If you prefer a more declarative approach, there is MXML support for declaring and configuring an HTTPService. To do what we did previously, we might configure the following:

<mx:HTTPService
id="service"
   rootURL="http://127.0.0.1:8080/"
   url="test.txt"
   method="GET"
   result="Alert.show( 'the response is ' + event.result )"
   fault="Alert.show('the error is ' + event.fault.content )"
/>

The HTTPService can now be referenced using the id property. Invoke the request just as you did before, in ActionScript code: the event listeners (for a result or a fault) specified in MXML will be invoked.

...
service.send();

The second option for creating HTTP requests is to use the class flash.net.URLLoader. There is little difference between the two options, but both are worth knowing about. To use flash.net.URLLoader, instantiate an instance, configure it, and invoke the load method with a parameter of type flash.net.URLRequest, in much the same way as you used the HTTPService.

To access the same resource as in the HTTPService examples, we might write the following:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application
        xmlns:mx="http://www.adobe.com/2006/mxml"
        applicationComplete="applicationCompleteHandler(event)">

    <mx:Script>
        <![CDATA[
        import mx.controls.Alert;
        import mx.events.FlexEvent;

        private function applicationCompleteHandler(evt:FlexEvent):void
        {
             var urlLoader:URLLoader = new URLLoader();
                urlLoader.addEventListener(Event.COMPLETE, function(evt:Event):void  {
                Alert.show('the response is ' + urlLoader.data);
             });
             urlLoader.load(
                 new URLRequest('http://127.0.0.1:8080/test.txt'));
        }
        ]]>
    </mx:Script>
</mx:Application>

There are a few key differences here. First, the reference to the result data came from the urlLoader variable itself, and not as a reference on the event dispatched when result data became available. Second, instead of configuring the URL to be accessed on the urlLoader, we passed it as a parameter to the urlLoader.load method. Depending on your tastes, this API may feel more natural to use. It's a slightly more lower level API and slightly less verbose.

HTTP services provide a generic mechanism to talk to many other resources, including REST services. You might also prefer REST—generic and platform neutral—to exposing AMF- and Flex-specific services. With Java EE 6.0 and/or Spring 3.0, creating REST services is a snap, and you may prefer to interact with them over traditional remoting APIs like SOAP going forward.

If you do need to interface with SOAP services, however, manually consuming XML resources and parsing them using ActionScript's XML support can be tedious. Instead, it's better to use something more suited to the task.

Sometimes, you need to consume SOAP. It happens. Spring makes it dead simple to expose SOAP services. If your application is charged with consuming them, then you'll find the Flex framework is well equipped to do so. It works very much like the HTTPService: instantiate an instance, configure it, and then send a request.

Using the WebService object from MXML is only a bit more tedious than using the HTTPService. Here, we have to enumerate which operations on the SOAP endpoint to expose.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application
        xmlns:mx="http://www.adobe.com/2006/mxml"
        applicationComplete="applicationCompleteHandler(event)">


    <mx:WebService id="echoService"
                   wsdl="http://localhost:8080/echoService?wsdl">
        <mx:operation name="echo"/>
    </mx:WebService>

    <mx:Script>
        <![CDATA[
        import mx.controls.Alert;
        import mx.events.FlexEvent;
        import mx.rpc.AsyncToken;
        import mx.rpc.events.FaultEvent;
        import mx.rpc.events.ResultEvent;

        private function applicationCompleteHandler(evt:FlexEvent):void
        {
            var at:AsyncToken =
                   echoService.echo.send('Hello, World!'),
            at.addEventListener(ResultEvent.RESULT,
              function(re:ResultEvent) :void {
                Alert.show('the result is ' + re.result + ''),
                // 'Echo: Hello, World!'
            });

at.addEventListener(FaultEvent.FAULT,
              function(fe:FaultEvent) :void {
                Alert.show(fe.fault.toString());
            });
        }
        ]]>
    </mx:Script>
</mx:Application>

Using the WebService functionality from JavaScript is plain and fundamentally the same.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application
        xmlns:mx="http://www.adobe.com/2006/mxml"
        applicationComplete="setup(event)">
    <mx:Script>
        <![CDATA[
        import mx.controls.Alert;
        import mx.events.FlexEvent;
        import mx.rpc.AsyncToken;
        import mx.rpc.events.FaultEvent;
        import mx.rpc.events.ResultEvent;
        import mx.rpc.soap.WebService;

        private function setup(evt:FlexEvent):void
        {
            var echoService:WebService = new WebService();
            echoService.wsdl = 'http://localhost:8080/echoService?wsdl';
            echoService.loadWSDL();

            var at:AsyncToken = echoService.echo.send('Hello, World!'),

            at.addEventListener(ResultEvent.RESULT,
                function(re:ResultEvent):void {
                Alert.show('the result is ' + re.result + ''),
                        // 'Echo: Hello, World!'
            });
            at.addEventListener(FaultEvent.FAULT,
                function(fe:FaultEvent):void {
                Alert.show(fe.fault.toString());
            });
        }
        ]]>
    </mx:Script>
</mx:Application>

Here, we import the base class (whereas the first example uses an MXML-friendly subclass) and have to remember to call loadWSDL() once we've configured the WebService. SOAP services work fine for integrating legacy systems, but we think few people would be interested in setting them up for new projects, specifically for Flex, if there's a better alternative. What's required is something really quick and compressed with binary, something that plays well with Flex and Flash itself so that marshalling complex types isn't an issue. It should also be easy to support from the Java end. Creating SOAP is decidedly not easy to support.

This is where AMF comes in.

This is the most powerful option. AMF is a format that Flash clients can read efficiently. Because it's just binary data, it's efficient when sent across the wire (especially when compared to porous text formats like SOAP, XML, or JSON). Basically, AMF is everything you could ask for! It's compact, efficient, plays well with Flash, and it's easy to use. It's got everything! Well, almost everything, anyway. The first problem is that AMF services aren't ubiquitous, and even if they were, that doesn't mean you're exposing AMF services inside the enterprise. We'll discuss solving that problem in recipes to come, but first, let's look at how we might consume an AMF endpoint in Flex, both in MXML, and ActionScript.

Using an AMF service from MXML is a matter of configuring it and sending requests, similar to the other options you've seen so far.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application
        xmlns:mx="http://www.adobe.com/2006/mxml"
        applicationComplete="setup(event)">

    <mx:RemoteObject
     endpoint="http://yourhost:8080/mb/amf"
     showBusyCursor="true"
     destination="auctionService"
     id="auctionService"
    />

    <mx:Script>
        <![CDATA[
        import mx.controls.Alert;
        import mx.events.FlexEvent;
        import mx.rpc.AsyncResponder;
        import mx.rpc.AsyncToken;
        import mx.rpc.events.FaultEvent;
        import mx.rpc.events.ResultEvent;

        private function setup(evt:FlexEvent):void
        {

            var resultHandler:Function = function(
                resultEvent:ResultEvent, asyncToken:AsyncToken) :void {
                Alert.show('result = ' + resultEvent.result);
            };
            var faultHandler:Function = function(
                faultEvent:FaultEvent, asyncToken:AsyncToken) :void {
                Alert.show('fault = ' + faultEvent.fault);
            };

auctionService.getItemsForAuction().addResponder(
                new AsyncResponder(resultHandler, faultHandler));
        }
        ]]>
    </mx:Script>
</mx:Application>

Toward the top, we configure an instance of a <mx:RemoteObject />. We don't tell it specifically which service endpoint to connect to. Instead, we tell it the address of the broker (in this case, BlazeDS) and the destination (the destination is, roughly, the abstract name of the resource that's exposed). A destination is where we send messages. Whether the message is ultimately routed to a service or a JMS queue, for example, is configured on the server, but the client doesn't necessarily know either way. IN the following example, we invoke services by calling them asynchronously. To be notified of a result or of a remoting fault, we configure callback functions. The functions are used as arguments for the AsyncResponder. It is the responder that ultimately handles the results of an invocation of a method. There are two callbacks: one to receive notifications that a result was returned from the server and another to receive notifications of errors in the messaging.

To achieve the same thing using ActionScript, we need only move the configuration of the objet from MXML to ActionScript code. This, as usual, involves removing "mxml" from the package name and simply constructing the object in ActionScript.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application
        xmlns:mx="http://www.adobe.com/2006/mxml"
        applicationComplete="setup(event)">

    <mx:Script>
        <![CDATA[
        import mx.controls.Alert;
        import mx.events.FlexEvent;
        import mx.rpc.AsyncResponder;
        import mx.rpc.AsyncToken;
        import mx.rpc.events.FaultEvent;
        import mx.rpc.events.ResultEvent;
        import mx.rpc.remoting.RemoteObject;

        private function setup(evt:FlexEvent):void
        {

            var auctionService:RemoteObject = new RemoteObject();
            auctionService.endpoint = 'http://localhost:8080/mb/amf';
            auctionService.showBusyCursor = true;
            auctionService.destination = 'auctionService';

            var resultHandler:Function = function(
                resultEvent:ResultEvent, asyncToken:AsyncToken) :void {
                Alert.show('result = ' + resultEvent.result);
            };

var faultHandler:Function = function(
                faultEvent:FaultEvent, asyncToken:AsyncToken) :void {
                Alert.show('fault = ' + faultEvent.fault);
            };

                auctionService.getItemsForAuction().addResponder(
                        new AsyncResponder(resultHandler, faultHandler));
        }
        ]]>
    </mx:Script>
</mx:Application>

So, AMF is a very convenient protocol. If you've got an easy connectivity layer that works with one of the protocols described in this recipe, then you might consider using those. In all other cases, AMF is a very solid option. The issue is then, "how do I expose my services in AMF?" You can expose an AMF endpoint using a broker like Adobe's LiveCycle Data Services product, a commercial offering; an open source offering like Granite DS; or as we'll discuss in this chapter, an open source project that is a subset of Lifecycle Data Services called BlazeDS. BlazeDS sits on your domain and can be used to expose Java objects and services as AMF-friendly services. It can also expose messaging middleware (like JMS) in such a way that a Flex client can consume messages asynchronously, very much in the same way Ajax clients can use Comet to receive messages pushed from the server. Finally, it can be used to simply proxy other services on other domains if required. There are servers like this that implement the AMF endpoint functionality for most platforms, including Python, PHP, Perl, and Ruby.

If you're using Java, and Spring, you may want to consider BlazeDS. It's a very powerful broker, has good support, and—as you'll see—is an absolute breeze to configure. BlazeDS can actually be downloaded and run stand-alone as a .war project. But, this introduces at minimum an unnecessary deployment into your architecture and at worse an extra server. So, most people tend to pick apart BlazeDS and install the relevant bits in their own web applications. This process was tedious, but worked. It didn't play well with Spring or EJB, however, so other brokers like GraniteDS presented a stronger alternative. Now, with the Spring BlazeDS integration, you can have your cake and eat it too: the Spring BlazeDS integration lets you easily install BlazeDS into your application and works perfectly with all the things you can imagine wanting to work with from Spring: messaging (both straight JMS and with the Spring Integration service bus) and Spring components or services.

The Spring BlazeDS integration requires us to set up the same infrastructure we'd set up if we were using Spring Faces, Spring Web Flow, Spring MVC, and so on: the DispatchServlet. There is no need for any custom BlazeDS servlet or web.xml configuration at all. The configuration lives in the web.xml file, and we provide a mapping so that we know where to send Flex requests. Note that the following configuration could be used in setting up Spring MVC or Spring Web Flow, too! There is nothing BlazeDS-specific, or even specific to the Spring BlazeDS integration, in the following code:

<web-app version="2.4"
xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
     http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

   <display-name>Spring Flex BlazeDS integration example</display-name>

   <servlet>
      <servlet-name>spring-flex</servlet-name>
      <servlet-class>
         org.springframework.web.servlet.DispatcherServlet
      </servlet-class>
      <init-param>
         <param-name>contextConfigLocation</param-name>
         <param-value>/WEB-INF/auction-flex-context.xml</param-value>
      </init-param>
      <load-on-startup>1</load-on-startup>
   </servlet>

    <servlet-mapping>
        <servlet-name>spring-flex</servlet-name>
        <url-pattern>/mb/*</url-pattern>
    </servlet-mapping>
</web-app>

This configuration is the simplest configuration possible, but it is enough to install support for Spring in your web application. You need to set up the Flex message broker and so forth, which we do inside a Spring context file. Here, we reference /WEB-INF/auction-flex-context.xml, where we set up the message broker.

The contents of the auction-flex-context.xml file follow. We won't expose any services or messaging endpoints, yet. Let's leave those for the next few recipes.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns:file= http://www.springframework.org/schema/integration/file
xmlns:integration="http://www.springframework.org/schema/integration"
xmlns="http://www.springframework.org/schema/beans"
xmlns:context="http://www.springframework.org/schema/context"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:p="http://www.springframework.org/schema/p"
xmlns:util="http://www.springframework.org/schema/util"
xmlns:tool="http://www.springframework.org/schema/tool"
xmlns:lang="http://www.springframework.org/schema/lang"
xmlns:jms="http://www.springframework.org/schema/integration/jms"
xmlns:amq="http://activemq.apache.org/schema/core"
xmlns:flex="http://www.springframework.org/schema/flex"
xsi:schemaLocation="
    http://www.springframework.org/schema/util
    http://www.springframework.org/schema/util/spring-util-3.0.xsd
    http://www.springframework.org/schema/tool
    http://www.springframework.org/schema/tool/spring-tool-3.0.xsd
    http://www.springframework.org/schema/lang
    http://www.springframework.org/schema/lang/spring-lang-3.0.xsd
    http://www.springframework.org/schema/beans
    http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
    http://www.springframework.org/schema/context
    http://www.springframework.org/schema/context/spring-context-3.0.xsd
    http://www.springframework.org/schema/integration
    http://www.springframework.org/schema/integration/spring-integration-1.0.xsd
    http://www.springframework.org/schema/integration/file
    http://www.springframework.org/schema/integration/file/spring-integration-file-1.0.xsd
    http://www.springframework.org/schema/integration/jms
    http://www.springframework.org/schema/integration/jms/spring-integration-jms-1.0.xsd
    http://activemq.apache.org/schema/core
    http://activemq.apache.org/schema/core/activemq-core-5.3.0.xsd
    http://www.springframework.org/schema/flex
    http://www.springframework.org/schema/flex/spring-flex-1.0.xsd
">

    <context:annotation-config />
    <context:component-scan base-package="com.apress.springwebrecipes.flex.auction" />

    <flex:message-broker services-config-path="/WEB-INF/flex/services-config.xml">
        <flex:message-service default-channels="my-amf" />
    </flex:message-broker>

</beans>

This context file imports quite a few namespaces because we'll use them later as we integrate services and messaging channels. Technically, though, you don't need them right now. You could import the context namespace and the flex namespace and be done with it.

Here, we use the context element to enable annotation configuration and to tell the Spring framework in which package to scan for, and automatically register, components (beans). Again, we'll use those as part of using standard Spring. So, the only thing we've configured of any interest here is the BlazeDS message broker. The message broker, in turn, creates channels, which are like named ports where messages may be sent or received from. We configure the specifics of the channel—like polling frequency, timeout settings, the specific sub-URL, streaming, and so on, all from the services configuration file. The message broker will, by default, look for the services-config.xml file in /WEB-INF/flex/services-config.xml. You can thus remove our explicit declaration, as it is redundant. We only mention it because you may want to vary that location, though the default (WEB-INF/flex) is a very broad de-facto standard.

Let's look at a very sophisticated services-config.xml configuration file. We'll reuse only a very small subset of all of the configuration in this file throughout this chapter. There are numerous configurations, some of which you may reuse to great effect. It will give you an idea of some of the things that you can support, however, to study this file.

<?xml version="1.0" encoding="UTF-8"?>
<services-config>
    <services>
        <default-channels>
           <channel ref="my-amf"/>
        </default-channels>
    </services>

    <channels>
        <channel-definition id="my-amf" class="mx.messaging.channels.AMFChannel">
            <endpoint url="http://{server.name}:{server.port}/{context.root}/mb/amf"
                      class="flex.messaging.endpoints.AMFEndpoint"/>
        </channel-definition>
        <channel-definition id="my-secure-amf"
                 class="mx.messaging.channels.SecureAMFChannel">
            <endpoint url="https://{server.name}:{server.port}/{context.root}/mb/amfsecure"
                      class="flex.messaging.endpoints.SecureAMFEndpoint"/>
            <properties>
                <add-no-cache-headers>false</add-no-cache-headers>
            </properties>
        </channel-definition>
        <channel-definition id="my-polling-amf" class="mx.messaging.channels.AMFChannel">
            <endpoint url="http://{server.name}:{server.port}/{context.root}/mb/amfpolling"
                      class="flex.messaging.endpoints.AMFEndpoint"/>
            <properties>
                <polling-enabled>true</polling-enabled>
                <polling-interval-seconds>4</polling-interval-seconds>
            </properties>
        </channel-definition>
        <channel-definition id="my-longpolling-amf"
                            class="mx.messaging.channels.AMFChannel">
            <endpoint
                url="http://{server.name}:{server.port}/{context.root}/mb/amflongpolling"
                class="flex.messaging.endpoints.AMFEndpoint"/>

<properties>
                <polling-enabled>true</polling-enabled>
                <polling-interval-seconds>5</polling-interval-seconds>
                <wait-interval-millis>60000</wait-interval-millis>
                <client-wait-interval-millis>1</client-wait-interval-millis>
                <max-waiting-poll-requests>200</max-waiting-poll-requests>
            </properties>
        </channel-definition>
        <channel-definition id="my-streaming-amf"
                            class="mx.messaging.channels.StreamingAMFChannel">
            <endpoint
                 url="http://{server.name}:{server.port}/{context.root}/mb/streamingamf"
                 class="flex.messaging.endpoints.StreamingAMFEndpoint"/>
        </channel-definition>
     </channels>

    <logging>
        <target class="flex.messaging.log.ConsoleTarget" level="Warn">
            <properties>
                <prefix>[BlazeDS] </prefix>
                <includeDate>false</includeDate>
                <includeTime>false</includeTime>
                <includeLevel>false</includeLevel>
                <includeCategory>false</includeCategory>
            </properties>
            <filters>
                <pattern>Endpoint.*</pattern>
                <pattern>Service.*</pattern>
                <pattern>Configuration</pattern>
            </filters>
        </target>
    </logging>

    <system>
        <redeploy>
            <enabled>false</enabled>
        </redeploy>
    </system>
</services-config>

We won't review every line here. You may look into these options specifically in greater detail on your own, as required. For our purposes, we can use the following configuration, which comes in at a staggering dozen or so lines of XML!

<?xml version="1.0" encoding="UTF-8"?>
<services-config>
    <channels>
        <channel-definition id="my-amf" class="mx.messaging.channels.AMFChannel">
            <endpoint url="http://{server.name}:{server.port}/{context.root}/mb/amf"
                      class="flex.messaging.endpoints.AMFEndpoint"/>
        </channel-definition>
     </channels>
</services-config>

The endpoint's url attribute defines where we should expect this service to be mounted. Any service that's exposed using the my-amf channel will be available via that URL. You'll need this value in the client Flex application. For the sample auction application we'll develop in this chapter, we deploy the application at the root web context. You'll use the URL http://127.0.0.1:8080/mb/amf in your Flex client code.

To keep our code as ready-to-deploy as possible, you should parameterize the URL of the service in the client. Alternatively, if you know the domain name for your application, you might add an entry to your /etc/hosts file on Unix derivatives or, on Windows, to your C:WINDOWSsystem32driversetchosts file mapping 127.0.0.1 to your target domain. Thus, all references to the server—whether in production or in development—will resolve to the correct host. In this chapter, we are explicitly referencing localhost, but only because we're writing a book and don't have a separate domain we control the rights to that we can print here.

Our sample application's interface is very simple (see Figure 10-1). We'll use two synchronous services and consume one asynchronous message. Our application displays a UI with items in a grid. We also have a form with which new items may be posted. As soon as the items are posted, an asynchronous message will trigger an update of the view on all the clients who are looking at the grid, so that their display updates immediately.

Figure 10.1. This is the UI of the Flex client. On the left is the form with which clients may post new items that appear in the grid (to the right), and they appear nearly instantly thanks to our integration with Spring BlazeDS's messaging support.

With our message broker up and running, we'll look next at how to create those services and how to build the Flex client above to consume them.

The support for JMS on the BlazeDS involves configuring a JMS connection factory in Spring. We want to ensure we are using a javax.jms.Topic, and not a javax.jms.Queue, so we will use the ActiveMQ library namespace support for Spring to create it. This is standard configuration that you will do no matter what your ultimate use is for JMS.

Add the following to the /WEB-INF/auction-flex-context.xml file that we defined in the previous recipe. We have already imported the amq (Active MQ) namespace in that file.

<bean id="connectionFactory"
  class="org.springframework.jms.connection.CachingConnectionFactory"
  p:sessionCacheSize="10"
  p:cacheProducers="false">
      <property name="targetConnectionFactory">
          <amq:connectionFactory brokerURL="tcp://localhost:61616" />
      </property>
</bean>

The inner amq:connectionFactory element defines a org.apache.activemq.spring.ActiveMQConnectionFactory instance. This defines the connection factory, but to add an extra layer of robustness, we create a connection factoring pool, org.springframework.jms.connection.CachingConnectionFactory.

To be able to work with the JMS connection factory from our services, we create a JmsTemplate, wiring in the connection factory proxy that we've just configured.

<bean id="jmsTemplate"
      class="org.springframework.jms.core.JmsTemplate"
      p:connectionFactory-ref="connectionFactory" />

Finally, we use the ActiveMQ namespace support to create the javax.jms.Topic instances that we'll need (if they don't already exist).

<amq:topic id="itemPosted" name="itemPosted" physicalName="itemPosted" />
<amq:topic id="bidPosted" name="bidPosted" physicalName="bidPosted" />
<amq:topic id="bidAccepted" name="bidAccepted" physicalName="bidAccepted" />

With all this in place, our service has what it needs to be able to talk to JMS. We've not configured any piece that's specific to Flex. Let's get that out of the way now. Add the following, near where you defined the message broker previously:

<flex:jms-message-destination id="itemPostedDestination"
             jms-destination="itemPosted" channels="my-amf"
             connection-factory="connectionFactory"  />

And that's it! The id defines the string that we use to connect to the JMS destination from the Flex client. That's the only part that permeates your code. The jms-destination attribute correlates to an ID used in defining the topics with the amq:topic element. So, the form to post a new item is completed and submitted. The form invokes the postItem method on the Spring service, which in turn sends a message, using the jmsTemplate, out to the itemPosted destination. We've then configured Flex to listen for that message here using the flex:jms-message-destination. Because it's being sent on a Topic, it will multicast the message, so that everyone who's using the application will see the message. To try it, open the Flex application from multiple browsers, or computers, and log in. You want to use different browsers so you can avoid reusing the same session. Post an Item from one of them. Watch as all the others are updated instantaneously. You should see an alert message saying, "A new item has arrived!"

In the previous example, we used JMS to create a publish-and-subscribe style architecture. Because it was a sort of circuit, it worked fine. However, there is often a requirement to have Flex user interfaces be aware of other events besides ones that the Flex UI itself generates—events that are either specific to your business or don't talk to JMS by default. The list of such applications is infinite. You don't have to think long before the possibilities become overwhelming, and exciting. What if you could have your user-interface update each time e-mail arrives? Or an RSS feed updates? Or what if somebody logged in via a Jabber server (XMPP; for example, using Google Talk)? What if your Flex client was designed to facilitate an editorial workflow and needed to load up new entries from a content management system for approval when ever any changes were made? Or perhaps it is the user interface for an audit system, so new customer loan applications need to be reviewed as they arrive. Need to load up the contents of files dropped on a shared mount? What about reacting to Twitter or Facebook status updates? What about when new rows are inserted in a watched view on the database?

These kinds of integration problems require an extra piece of middleware to let our code consume these various events while remaining indifferent to their source. The prescription for these kinds of solutions is usually an enterprise service bus (ESB). So, we will use one too, of a sort. We will use Spring Integration. Spring Integration is great because it's not a proper server, but instead an embeddable set of components that you configure using Spring. It lets you consume and produce messages for arbitrary endpoints, and if there's no support out of the box, it's trivially easy to build your own.

In our example, we will simply rework the JMS example: instead of sending messages to the JMS topic and then consuming them in Flex, we'll provide two ways to add items: one from JMS, as before, and one from a shared file system where new files are to be processed and their contents transformed into new Items, which get added via a call to the service. Either input source will ultimately be sent to JMS, where Spring Integration will consume the messages and forward it to the BlazeDS destination. Our Flex client will consume messages from this destination, as usual, and remain unchanged. We'll work entirely in our Spring application context to achieve these changes, using Spring Integration.

The way Spring Integration works is it lets you establish a sort of gauntlet for your message to pass through. It has to go through each component until the goal is finished. It lets us configure as much as possible about the way messages get into a pipeline and about where they ultimately end up. You use adapters to read and write to external systems. You use other specialized components to handle transformation of the message and so on. Each component has an input message and an output message. Some components let you take an input and transform it, so the resulting output is different than the input. Others let you do things like forking control on the process: perhaps one message (a File object) enters and multiple messages (each line of the file) leave the component. Just as you do with Spring Web Flow or Struts, Spring Integration adds a layer of indirection between components. Given two components, component "a" and component "b," a product for component "a" may be passed to component "b." Perhaps in the future it's decided that there needs to be processing between the two components, so you introduce component "c" and stick it between them. In normal solutions, this would present a problem. With Spring Integration, however, there's a level of indirection. Components are connected by channels, which are basically named pipes. The pipe takes the output of a component and pipes it as the input of another. You can rearrange the components in a pipeline by simply changing the pipes going into and out of it, in much the same way that you can isolate your Spring Web Flow pages of the knowledge of what page will succeed the current one.

The files should have a payload with a well-known format: here, for the sake of simplicity, we'll assume that the contents of the file are on one line and that the line can be split into columns along comma (,) characters. The first column will be the seller's e-mail, the second will be the item, the third description, and the fourth the base price. We'll then call the service to add this item and send it to JMS, as usual. So, we have two contributories feeding into the JMS topic that eventually gets consumed and piped to the BlazeDS destination: the file system integration and the service, which sends the event directly to the JMS topic.

To make these changes, we'll configure a few Spring Integration components: We need a way of reading files from a well-known directory, so we'll use an inbound file adapter. We'll need a way to convert the java.io.File from the file system into a String with the contents of the java.io.File, so we'll use a file-to-string transformer. We'll need a way of converting the String into an Item that we can call the service with, so we'll create a transformer. We'll need a component to actually call the postItem method on the service, which will send the Item to JMS. We'll have a component consume all messages that come off the JMS topic—regardless of source—and then feed those to the BlazeDS destination. Should be simple enough! In this process, all that we need to do is tell the Spring Integration message bus how to convert our simple CSV format into an Item and how to invoke our service. For that purpose, we'll create two Java classes: FileToItemTransformer and ItemCreationServiceActivator to transform the CSV String and to invoke our service, respectively.

There is a lot of power here.

Let's look at our initial solution. First, we must declare the channels that connect the components.

<integration:channel id="inboundItemFiles"/>
    <integration:channel id="inboundItemFileStrings"/>
    <integration:channel id="inboundItems"/>
    <integration:channel id="inboundItemsPosted"/>
    <integration:publish-subscribe-channel id="inboundItemsAudited"/>

With the channels introduced, let's start analyzing the components that the channels connect.

<bean id="itemFilesMount"
      class="org.springframework.core.io.FileSystemResource"  >
   <constructor-arg
    value="#{ systemProperties['user.home']+'/flexCsvFiles' }"/>
</bean>

<file:inbound-channel-adapter
       auto-create-directory="true"
       directory="file:#{itemFilesMount.file.absolutePath}"
       channel="inboundItemFiles">
        <integration:poller>
<integration:interval-trigger interval="1000"/>
        </integration:poller>
</file:inbound-channel-adapter>

First, we create a Spring framework Resource to declare the directory where we will look for new files. We avail ourselves of the new Spring 3.0 expression language to use a standard System property, user.home, to determine the home directory of the current user. The folder we want will be in the home directory, under a folder named flexCsvFiles. Now, we can create a file:inbound-channel-adapter to poll that directory and consume new files as they become available. To ensure that the directory is created when the integration is deployed, we set the auto-create-directory attribute to true. To tell the adapter which directory to use, we again employ the Spring Expression Language to reference access the String representation of the Resource we created by dereferencing the Resource's file property, which we dereference again to get the absolutePath. The <file:inbound-channel-adapter /> is configured here to scan the directory at an interval of 1,000 milliseconds (every second) and if it sees any new files, it creates a message, which it puts through the inboundItemFiles channel. Note that you can also specify a glob for the inbound channel adapter, though we don't here.

<file:file-to-string-transformer
       input-channel="inboundItemFiles"
       output-channel="inboundItemFileStrings"
       delete-files="true" />

The next two components in the pipeline are instances of a standard Spring Integration component called a transformer. The first one, shown in the preceding snippet, is a standard transformer that we'll reuse. It knows how to take a java.io.File object and read its contents into a String. The String contents are returned on the inboundItemFileStrings channel where the next component, another transformer, will be expecting it. Since we don't want to throw the integration processing into an infinite loop, we use the delete-files option on the file-to-string-transformer component to remove the file from the directory once it has read the file and sent it.

<integration:transformer
     input-channel="inboundItemFileStrings"
     ref="fileToItemTransformer"
     output-channel="inboundItems"/>

The next component, shown in the preceding snippet, is a customer transformer because Spring Integration has no way of knowing how to transform that String into an Item object. It takes the input of the input-channel and transforms it using transformation logic that we supply.

package com.apress.springwebrecipes.flex.auction.integrations;

import com.apress.springwebrecipes.flex.auction.model.Item;
import org.apache.commons.lang.StringUtils;
import org.springframework.integration.annotation.Transformer;
import org.springframework.stereotype.Component;

import java.io.IOException;

@Component
public class FileToItemTransformer {

    @Transformer
    public Item transformFromFileStringToItem(String fileContent)
      throws IOException {


        if (StringUtils.isEmpty(fileContent))
            throw new RuntimeException(
                "the file content is empty; can't create Item");

String[] parts = fileContent.split(",");

        if (parts.length != 4)
            throw new RuntimeException(
             "couldn't parse the file; can't create Item");

        String seller = parts[0],
               item = parts[1],
               description = parts[2],
               basePrice = parts[3];

        Item itemObj = new Item();
        itemObj.setDescription(description);
        itemObj.setItem(item);
        itemObj.setSellerEmail(seller);
        itemObj.setBasePrice(Double.parseDouble(basePrice));
        return itemObj;
    }
}

Spring Integration looks at the Spring bean configured with the ref attribute—as in the preceding code—to get our transformation logic. It scans the class for any methods annotated with a @Transformer annotation, and it invokes that. It takes the result and sends it out on another channel, inboundItems. Because this is a simple demonstration, the code is intentionally and artificially optimistic and simple; no error handling or validation is done at all.

<integration:service-activator
        input-channel="inboundItems"
        ref="itemCreationServiceActivator"/>

The next component in the pipeline—in the preceding snippet—actually calls our Spring service, AuctionService, to insert the Item into our repository. Note that the component has no output-channel configured here. This is because we know that the service invokes JMS directly, sending the Item to the itemPosted javax.jms.Topic.

package com.apress.springwebrecipes.flex.auction.integrations;

import com.apress.springwebrecipes.flex.auction.AuctionService;
import com.apress.springwebrecipes.flex.auction.model.Item;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.integration.annotation.ServiceActivator;
import org.springframework.stereotype.Component;

@Component
public class ItemCreationServiceActivator {

    @Autowired
    private AuctionService auctionService;

@ServiceActivator
    public void postItem(Item item) throws RuntimeException {
        auctionService.postItem(
            item.getSellerEmail(),
            item.getItem(),
            item.getDescription(),
            item.getBasePrice(),
            null);
    }
}

The preceding code is very simple. It takes the input message, an Item, and uses it to call the postItem method on our AuctionService instance.

Our next step then is to consume those messages and funnel them to BlazeDS. We don't care if the JMS messages came from postings inside our Flex application or if they came from this file integration. We need to send them to the BlazeDS middleware, so it can publish the new Item to all the logged in Flex clients.

<jms:message-driven-channel-adapter
       connection-factory="connectionFactory"
       destination="itemPosted"
       channel="inboundItemsPosted"
    />

We'll set up a jms:message-driven-channel-adapter, as shown in the preceding code, which will consume messages and send them on the inboundItemsPosted channel, in much the same way as our file:inbound-channel-adapter consumed files and sent them out on its channel attribute. Because this is JMS-specific, we need to configure the connection factory, as well as what destination it should look at. We simply use references to the connection factory and ActiveMQ topics that we declared earlier.

Normally, we would send each message received from JMS directly to the BlazeDS integration. There is one small fly in the ointment, however. A Spring Integration pipeline works on the assumption that each component in the pipeline is available. In this case, we'll do all this processing and then send it to BlazeDS where we hope the event will be consumed. If there is no one logged into a Flex client consuming messages, then the message itself can't be consumed, and we get an exception. So, what we do is send the message ourselves and ignore the failure result. We don't actually care if BlazeDS consumes it. Remember, JMS is being used here to send event messages, not document messages that need to be consistent and honored. We can ignore the events, as we reload the UI with the latest data on the Flex client's load, anyway. So, we'll add a middleman who can swallow the error state for us:

<integration:service-activator
      input-channel="inboundItemsPosted"
      ref="messageAbsorber"
      output-channel="inboundItemsAudited"  />

Our component is a service-activator. As before, the service-activator takes input on the input-channel and delegates the heavy lifting to the Spring bean referenced by the ref attribute. Again, we could send the result out through an output-channel, but that may, in some cases, cause an Exception when there is no consumer on the other end. So, we'll cheat and simply handle the send operation by ourselves. You can inject any Spring Integration component just as you would any other bean. We use this to good effect to inject the implementation class for the inboundItemsAudited channel itself.

package com.apress.springwebrecipes.flex.auction.integrations;

import org.apache.commons.lang.builder.ToStringBuilder;
import org.springframework.integration.annotation.ServiceActivator;
import org.springframework.integration.core.Message;
import org.springframework.integration.core.MessageChannel;
import org.springframework.stereotype.Component;

import javax.annotation.Resource;
import java.util.Map;

@Component
public class MessageAbsorber {

    @Resource(name = "inboundItemsAudited")
    private MessageChannel publishSubscribeChannel;

    @ServiceActivator
    public void handle(Message<Map<String, Object>> msg) {
        boolean status = publishSubscribeChannel.send(msg);
        // do not care about status
    }
}

Here, we simply swallow the status—throwing no exceptions or anything. If there's a consumer for this message, then the status will be true. If not, it's no problem either.

Ultimately, the BlazeDS needs to know to look for messages coming from a Spring Integration channel. Just as we told BlazeDS where to look for new JMS messages, we will tell BlazeDS where to look for new messages coming from a Spring Integration channel.

<flex:integration-message-destination
     channels="my-amf"
     id="itemPostedDestination"
     message-channel="inboundItemsAudited"
    />

The channels attribute and the id attribute should appear familiar. The only thing different here is the use of the flex:integration-message-destination and the message-channel attribute. These simply tell BlazeDS to consume messages being sent from the MessageAbsorber.

You've seen the incredibly rich support the Spring BlazeDS project offers for tying your application to existing MOM and integrations. Sometimes, however, you have no other messaging middleware or integration processing. Sometimes, you simply want other Flex clients to be notified of something. BlazeDS supports this use case as well. To declare a destination that can only receive messages from Flex clients simply configure a <<flex:message-destination />.

<flex:message-destination channels="my-amf" id="myDestination"/>

Such a destination can only be used by clients who know how to talk to BlazeDS, like Flex. So, how does Flex send messages to this destination, or indeed any of the destinations you've seen? The API, like the one for consuming messages, is minimalistic. Let's walk through the nominal BlazeDS messaging example: the chat room!

<?xml version="1.0" encoding="iso-8859-1"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns="*"
                pageTitle="Chat" creationComplete="setup(event)">

    <mx:Panel title="Chat" >
        <mx:TextArea id="output" height="200" />
        <mx:TextInput id="input" />
        <mx:ControlBar horizontalAlign="center" >
            <mx:Button id="send" label="Send" click="sendChatMessage(event)"/>
            <mx:Button id="clear" label="Clear" click="output.text =''" />
        </mx:ControlBar>
    </mx:Panel>

    <mx:Script>
        <![CDATA[

        import mx.events.FlexEvent;
        import mx.messaging.ChannelSet;
        import mx.messaging.Consumer;
        import mx.messaging.Producer;
        import mx.messaging.channels.AMFChannel;
        import mx.messaging.events.MessageEvent;
        import mx.messaging.messages.AsyncMessage;

        private var chatPublisher:Producer;
        private var chatConsumer:Consumer ;

        public function setup(fe:FlexEvent):void
        {

            var chatDestination:String = 'chatDestination';

            var cs:ChannelSet = new ChannelSet();
            cs.channels=[ new AMFChannel(
                 'my-amf','http://localhost:8080/mb/amf') ];

            chatPublisher = new Producer();
            chatPublisher.channelSet =cs;
            chatPublisher.destination = chatDestination;
            chatPublisher.connect();

chatConsumer = new Consumer();
            chatConsumer.channelSet = cs;
            chatConsumer.destination = chatDestination;
            chatConsumer.addEventListener(MessageEvent.MESSAGE,
              function (msgEvent:MessageEvent):void {
                 var msg:AsyncMessage = msgEvent.message as AsyncMessage;
                 output.text += msg.body + "
";
              }
            );
            chatConsumer.subscribe();
        }

        private function sendChatMessage(me:MouseEvent):void
        {
            var msg:AsyncMessage = new AsyncMessage();
            msg.body = input.text;
            chatPublisher.send(msg);
            input.text = "";
        }
        ]]>
    </mx:Script>
</mx:Application>

This application connects a Consumer and a Producer to the same BlazeDS destination, chatDestination. The definition of the chatDestination in the Spring BlazeDS configuration is as follows:

<flex:message-destination channels="my-amf" id="chatDestination"/>

In the application, we set up a simple text area in which text may be entered. When the text is submitted, we use the Producer to send the message to BlazeDS. If you open up this example in multiple browsers, you'll see that all the other browsers update their view of the chat instantly.