I have blogged about the new data-centric features in Flash Builder 4 here and here. One question people often ask me is: “Can I use this feature if I use a Framework (Cairngorm, Mate, Parsley, Spring ActionScript, Swiz, etc)?”

The answer is yes: The classes generated by Flash Builder (Value Objects and Service Stubs) are standard building blocks that are part of most RIA design patterns, regardless of whether or not you use a framework.

The way you leverage these classes in your application may differ slightly depending on the framework you are using. For example, each framework may have a different approach to configure service endpoints or to instantiate generated service stubs.

To demonstrate this, I built a version of my “Contacts” application (also known as InSync) using the Flash Builder 4 data-centric features and the Parsley Framework.

Configuring Service Endpoints

By default, an application built using a BlazeDS or LCDS project determines its service endpoints using a combination of assumptions made at runtime and hardcoded references baked into the swf at compile time. Read my Externalizing Service Configuration blog post for more information on this topic. The bottom line is that this default behavior is insufficient for any application other than a simple demo: you want endpoints to be fully configurable so that you can move services around without having to recompile your application.

Using Parsley, I inject the service endpoint configuration (in the form of a ChannelSet) in the generated service stubs as follows:

public class ContactService extends _Super_ContactService
{
	[Inject]
	override public function set channelSet(cs:ChannelSet):void
	{
		super.channelSet = cs;
	}
}

Note that I added this code in ContactService.as and not _Super_ContactService.as. Contrary to _Super_ContactService.as, ContactService.as will never be regenerated and is therefore the right place to add your custom code.

The injected ChannelSet is defined in my own channels-config.xml configuration file as follows:

<object type="mx.messaging.ChannelSet">
 	<property name="channels">
    		<array>
		    	<object type="mx.messaging.channels.AMFChannel">
		        	<property name="uri" value="http://localhost:8400/testdrive/messagebroker/amf"/>
		        </object>
	        </array>
	</property>
</object>

Note: Unlike the BlazeDS/LCDS services-config.xml file, channels-config.xml is read at runtime.

Because the ChannelSet is configured in an xml file, you can easily change the channel’s endpoint URI without recompiling the application. You could also add failoverURIs to this channel, or add completely new fall back channels to the ChannelSet.

Instantiating Service Stubs

As we already alluded to, Parsley is a dependency injection framework: Instead of letting a component instantiate its dependencies, those dependencies are injected in the component at runtime. For example, in ContactForm, instead of instantiating a ContactService as follows:

<services:ContactService/>

… I simply defined a contactService reference variable that I annotated with [Inject] to let Parsley inject a ContactService instance a runtime.

[Inject]
public var contactService:ContactService

The instance of ContactService that Parsley injects is defined in Config.mxml and has itself been injected with a ChannelSet. Object configuration in Parsley is very flexible. In this application I combine the xml and mxml configuration options. I use the xml configuration option for the things I don’t want to hardcode in my application, and the mxml configuration for traditional object instantiation and configuration.

Note: Parsley doesn’t force you to use any specific design pattern. For simplicity in this sample application, I inject a service directly into the view. You can of course use other patterns (like the Presentation Model) to achieve a greater level of abstraction. The Dependency Injection and Messaging infrastructure of Parsley will make the implementation of these patterns easier.

Installation Instructions

1. Download and install BlazeDS 4
2. Make a copy the blazeds web application in blazeds/tomcat/webapps, and call the new web application contacts
3. Download contacts.zip, and unzip it anywhere on your file system.
4. Overlay contacts/webapps/contacts (from contacts.zip) on top of blazeds/webapps/contacts
5. Start the server
6. Open a Command Window or Shell, navigate to /blazeds/tomcat/bin, and start Tomcat (for instance: catalina run).
7. Open a browser and access http://localhost:8400/contacts/ContactsParsley/ContactsParsley.html.

Note: The web application also include a plain (framework-less) version of the application available at this URL: http://localhost:8400/contacts/Contacts/Contacts.html

Importing the projects in Flash Builder 4

1. In Flash Builder 4, click File > Import > General > Existing Projects into Workspace.
2. Specify contacts/projects as the root directory and click finish.
3. Explore the projects: Contacts is the Flex project for the plain version of the application, ContactsParsley is the version discussed in this article, and java-testdrive is the Java project for the server-side classes.

Parsley is primarily a Dependency Injection framework. It also offers a very interesting messaging infrastructure. I won’t get into the details of dependency injection here: My previous Swiz and Spring ActionScript articles provide some background information, and there are also plenty of detailed resources out there.

If you just want to run the application and dive into the code, here are the links:

• Click here to run the application.
• Click here to view the source code.

Object Configuration

Parsley allows you to configure the core objects of your application (the objects other components depend on) in MXML (like Swiz), in XML (like Spring ActionScript), in ActionScript, or using any combination of these approaches. You can also extend the framework and create your own configuration mechanism.

For the inSync application, I used a simple MXML configuration (Config.mxml) defined as follows:

<?xml version="1.0" encoding="utf-8"?>
<Object xmlns="*" xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:services="insync.parsley.services.*">

    <mx:RemoteObject
            id="contactRO"
            destination="contacts"
            endpoint="http://localhost:8400/samples/messagebroker/amf"
            showBusyCursor="true" />

    <services:ContactService />

</Object>

Note: In a real life application, you would not want to hardcode the endpoints of your services in your source code. You could use the XML configuration option to configure your endpoints in a more “externalized” fashion. More on this topic here.

Framework Initialization

You initialize the Parsley framework using the ContextBuilder class corresponding to the configuration approach you chose. Here is the main application file for the inSync application. Parsley is initialized in the preinitialize event of the application.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:views="insync.parsley.views.*"
	paddingTop="0" paddingLeft="0" paddingRight="0" paddingBottom="0"
	preinitialize="FlexContextBuilder.build(Config)">

	<mx:Script>
		<![CDATA[
			import org.spicefactory.parsley.flex.FlexContextBuilder;
		]]>
	</mx:Script>

	<mx:Style source="styles.css" />

	<views:MainView />

</mx:Application>

Dependency Injection

Parsley supports constructor injection, method injection, and property injection (by type or by id).

In the following example (ContactForm.mxml), the framework will inject a specific implementation of the IContactService interface. In this case, the ContactService instance created in Config.mxml will be injected. This is an example of injection by type. Coding to the interface allows us to keep the view decoupled from a specific implementation of IContactService.

Note: Parsley doesn’t force you to use any specific design pattern. For simplicity in this sample application, I inject a service directly into the view. The use of an interface provides some level of decoupling, but you can of course use other patterns (like the Presentation Model) to achieve a greater level of abstraction. The Dependency Injection and Messaging infrastructure of Parsley will make the implementation of these patterns easier.

<?xml version="1.0" encoding="utf-8"?>
<mx:Canvas xmlns:mx="http://www.adobe.com/2006/mxml"
	addedToStage="dispatchEvent(new Event('configureIOC', true))">

	<mx:Script>
		<![CDATA[

		import insync.parsley.model.Contact;
		import insync.parsley.services.IContactService;

		[Inject]
		public var service:IContactService;

		[Bindable]
		public var contact:Contact;

		private function save():void
		{
			contact.firstName = firstName.text;
			contact.lastName = lastName.text;
			contact.email = email.text;
			service.save(contact);
		}

		private function remove():void
		{
			service.remove(contact);
		}

		]]>
	</mx:Script>

	<mx:Form>
		<mx:FormItem label="Id">
			<mx:TextInput text="{contact.id}" enabled="false"/>
		</mx:FormItem>
		<mx:FormItem label="First Name">
			<mx:TextInput id="firstName" text="{contact.firstName}"/>
		</mx:FormItem>
		<mx:FormItem label="Last Name">
			<mx:TextInput id="lastName" text="{contact.lastName}"/>
		</mx:FormItem>
		<mx:FormItem label="Email">
			<mx:TextInput id="email" text="{contact.email}"/>
		</mx:FormItem>
	</mx:Form>

	<mx:HBox left="12" bottom="12">
		<mx:Button label="Save" click="save()"/>
		<mx:Button label="Delete" click="remove()"/>
	</mx:HBox>

</mx:Canvas>

Note that in order to get its dependencies injected when it’s added to the stage, a view has to dispatch the “configureIOC” event.

Messaging

Parsley provides a generic Messaging infrastructure that allows you to exchange messages between objects in a decoupled, flexible, and easy-to-use manner:

• The event dispatcher and the event handler don’t know about each other.
• The event dispatcher and the event handler are decoupled from the framework: You dispatch events the Flex way.

Let’s look at the Search feature inSync as an example:

• The Toolbar class includes a simple TextInput that allows the user to specify a search criterion.
• The ContactList class displays the Search Results in a DataGrid.

The Toolbar class is defined as follows (non essential code removed for clarity):

<?xml version="1.0" encoding="utf-8"?>
<mx:Canvas xmlns:mx="http://www.adobe.com/2006/mxml" width="100%"
	addedToStage="dispatchEvent(new Event('configureIOC', true))">

	<mx:Metadata>
		[ManagedEvents("search")]
	</mx:Metadata>

	<mx:Script>
		<![CDATA[
			import insync.parsley.events.SearchEvent;
		]]>
	</mx:Script>

	<mx:Label text="Search:" top="18" right="164"/>

	<mx:TextInput id="searchBox" right="0" top="16"
		change="dispatchEvent(new SearchEvent(SearchEvent.SEARCH, searchBox.text))"/>

</mx:Canvas>

Note that it dispatches a SearchEvent when the content of the search input field changes.

That event is defined as a managed event (using the ManagedEvents annotation), meaning that the framework will make sure that all the parties interested in that event will receive it.

How do you register as a listener for a managed event? You simply annotate a function with [MessageHandler], and it automatically becomes an event handler for that event, regardless of the display object hierarchy or whether the event bubbles or not.

Here is how it’s done in ContactList (non essential code removed for clarity):

<?xml version="1.0" encoding="utf-8"?>
<mx:Canvas xmlns:mx="http://www.adobe.com/2006/mxml" width="100%" height="100%"
	addedToStage="dispatchEvent(new Event('configureIOC', true))">

	<mx:Script>
		<![CDATA[

			import mx.controls.Alert;
			import mx.collections.ArrayCollection;
			import mx.rpc.events.FaultEvent;
			import mx.rpc.AsyncToken;
			import mx.rpc.AsyncResponder;
			import mx.rpc.events.ResultEvent;

			import insync.parsley.events.SearchEvent;
			import insync.parsley.services.IContactService;			

			[Inject]
			[Bindable]
			public var service:IContactService;

			[Bindable]
			public var contacts:ArrayCollection;

			[MessageHandler]
			public function searchHanlder(event:SearchEvent):void
			{
				service.getContactsByName(searchStr).addResponder(new AsyncResponder(getContacts_result, faultHandler));
			}

			private function getContacts_result(event:ResultEvent, token:AsyncToken):void
			{
				contacts = event.result as ArrayCollection;
			}	

			private function faultHandler(event:FaultEvent):void
			{
				Alert.show(event.fault.faultString);
			}		

		]]>
	</mx:Script>

	<mx:DataGrid id="dg" dataProvider="{contacts}" width="100%" top="0" left="0" right="0" bottom="0"/>

</mx:Canvas>

With the simple [MessageHandler] annotation, the handler will be invoked every time an event of the function argument’s data type is dispatched in the application. If you need finer control, you can use the selector notation to specify the event type. For example in MainView.mxml, we register the contactDeleted function as a handler for the ContactEvent.DELETED event as follows.

[MessageHandler(selector="contactDeleted")]
public function contactDeletedHandler(event:ContactEvent):void
{
}

There is more to the Messaging capabilities of the Parsley framework. For example, you can use [MessageBinding] to bind a property of an object to the property of an event.

[MessageBinding(messageProperty="result",type=" mx.rpc.events.ResultEvent")]
public var contacts:ArrayCollection;

Installation Instructions

1. Download the project here
2. Import it in Flex Builder
3. Run the application. The application is configured to use the MockService (ContactServiceMock) by default, so it will run without any back-end.

If you want to use the Remoting service instead of the MockService:

1. Replace <services:ContactServiceMock/> with <services:ContactServiceRemote/> in Config.mxml
2. Install the BlazeDS turnkey server.
3. Download insync-parsley-java.zip, and unzip it on your local file system.
4. Copy classes/insync to blazeds/tomcat/webapps/samples/WEB-INF/classes/insync.
5. Add the following destination to blazeds/tomcat/webapps/samples/WEB-INF/flex/remoting-config.xml:

<destination id="contacts">
        <properties>
            <source>insync.dao.ContactDAO</source>
            <scope>application</scope>
        </properties>
</destination>

6. Copy insync/sampledb/insync to blazeds/sampledb/insync
7. Edit server.properties in blazeds/sampledb, and modify the file as follows to add the insync database to the startup procedure.

   server.database.0=file:flexdemodb/flexdemodb
   server.dbname.0=flexdemodb
   server.database.1=file:insync/insync
   server.dbname.1=insync
   server.port=9002
   server.silent=true
   server.trace=false
   

8. Start the database (startdb.bat or startdb.sh)
9. Start BlazeDS
10. Run the application