Mate: Event driven framework for Flex

Mate: Event driven framework for Flex

Mate: Event driven framework for Flex

This article will introduce you to the Mate framework for Adobe Flex. "Mate" (pronounced "mah-teh") is a tag based framework used to build Flex applications. Mate helps define the architecture of your application. Two important goals of the Mate framework are: simplicity and non-intrusiveness. Using the Mate framework will help you create a loosely coupled application. There is a companion Mate application along with this article available for download that demonstrates how to call a web service and render the services data to the applications view.

What is it?: Mate is a tag-based, event-driven Flex framework.
Platforms: Windows, Mac, Linux
Manufacturer: AsFusion
Website: http://mate.asfusion.com
Cost: $0.00 US / £0.00 UK
License: Apache License, Version 2.0

 

Mate: “A tag-based event-driven Flex framework”

Why you should consider using an application framework

Software development has been around for about 50 years and in this time it has gone through many phases of improvement.  Over time software engineers have faced many reoccurring problems and they noticed that reusable solutions can be applied at a high level to ease the task of developing these complex computer applications. One of the items that can assist software developers during the development process is the use of an application framework. Application frameworks provide a structured approach to software development. Application frameworks organize the source code for a software application and help to provide clarity for the development process. 

Why you should use Mate

Using Mate can help organize a codebase for an application. This enables the development team to focus on the business challenges of the application rather than spend time managing and navigating the structure of a constantly shifting, growing codebase. Mate also helps organize and abstract the source code of an application so that multiple developers can work simultaneously towards completing the application. Another very important benefit of using Mate is that it will help you create an application that is highly decoupled.

Your application isn’t tied to Mate

Some frameworks can enforce a certain approach and methodology to development. Sometimes you may wish to tailor the development process to your organizations style. Another issue that can arise is source code can become tied to a certain framework. Mate was designed to address these issues.  The communication throughout an application built with Mate is accomplished using standard Flash events.

Mate has great documentation

There is plenty of documentation and there are quite a few examples available for getting started with Mate.  The Getting Started page and the Overview page are two great places to begin learning about Mate. The StockQuote example is explained in the Getting Started section so you should take a moment to review its accompanying source code. Here are all of the top level pages of documentation that are available:

• Getting Started
• Overview
• Tags
• Best Practices
• How to
• Diagrams
• API Docs

Seven Mate Examples with source code

There are seven examples on the Mate website with source code. The Café Townsend and Stock Quotes examples have two sets of source code each so there are actually nine source code examples available. The existing samples are a great place to get started. There are solutions for several common tasks including retrieving and rendering data from multiple service layer types.

• Stock Quotes
  • ColdFusion version
  • WebService version
• Cafe Townsend
  • Mate style
  • Cairngorm style
• Hello World
• Flickr Book
• Weather Widget
• FlickWidget
• Style Loader

A note to Cairngorm developers: If you are already familiar with Cairngorm based Flex development you should take a moment to review the Café Townsend example. It demonstrates a side by side comparison of the same application built using both frameworks.

 

 

How Mate works

Events

Events are essential when developing applications with Mate. The events used in a Mate application simply extend flash.events.Event. This approach helps to retain the reusability and portability of an applications source code. Classes from a Mate application can be reused in applications that do not use a framework, such as a legacy application you have been asked to update. Events and event routing are managed by EventMaps in Mate.

EventMaps

EventMaps are a very important piece of a Mate application. The event map is a standalone MXML file that should be placed in a directory named maps. This class will manage and route the events for your application. This includes handling system and user generated events. Events in the EventMap can also trigger each other. A Mate based application can have more than one EventMap if desired. This can help organize your event routing and clarify the applications codebase.

EventHandlers

Every EventMap contains one or more set of EventHandlers tags. Each EventHandlers tag has a type attribute. The tags that are defined inside of the EventHandlers tag will be triggered any time an event with a matching type is dispatched. For example in the following EventHandlers tag the type is LoginEvent.LOGOUT:

 

<EventHandlers type="{LoginEvent.LOGOUT}">

 

In the application a LOGOUT event would be broadcast as follows:

 

dispatchEvent(new LoginEvent(LoginEvent.LOGOUT));

 

Each EventHandlers tag will typically contain one or more inner tags. The inner tags are processed when the event is run.

Inner tags for EventHandlers

The EventHandlers tag has a type attribute which matches the type property declared in the event class. The recommended best practice is to use a constant variable for the event type property. The event type property can be defined in the event class or in another location in your code if desired. Most Mate events are custom events however they can be any event, such as FlexEvent.APPLICATION_COMPLETE. Mate has built in debugging so you can also specify that the debugging should be enabled for this event type. If debugging is enabled Mate will write useful information to the Flex Output Console at runtime when the event is dispatched. The EventHandlers tag also needs one or more of the eleven currently supported inner tags.

• MethodInvoker
• EventAnnouncer
• RemoteObjectInvoker
• WebServiceInvoker
• HTTPServiceInvoker
• ObjectBuilder
• ResponseAnnouncer
• ServiceResponseAnnouncer
• CommandInvoker
• DataCopier
• StopHandlers
• InlineInvoker

The order of the inner tags is important. More information can be found on the Mate website under the entry for the EventHandlers tag.

Invokers

Mate provides a robust and rich approach to event management. To retrieve data from a web service a WebServiceInvoker can be defined and used. The accompanying example uses a WebServiceInvoker.  Other data service related Invokers available in Mate are the RemoteObjectInvoker and the HTTPServiceInvoker. Invokers need to have several attributes defined. The most important is the location of the data service. The WebServiceInvoker and RemoteObjectInvoker should also have the method attribute defined. The method attribute should match the method of the server side class being accessed. The attributes for each Invoker type are a little different. More information about the WebServiceInvoker will be provided in the MateCookCalc example section of this article.

Handlers

The WebServiceInvoker, RemoteObjectInvoker and HTTPServiceInvoker tags need to have resultHandlers tags defined. The resultHandlers tags will be executed when the data service returns a response to the service call that was made. To handle the result from the service call a MethodInvoker tag can be used. The MethodInvoker will call a custom data parser which can then massage the data and pass it along to a custom business manager.

Service parser

The results from a web service call usually need some type of processing. This data massaging is addressed using a service parser class.

Business manager

The business managers in a Mate application will store and manage business logic. Mate applications will almost always consist of multiple managers to handle the various data. This allows the data to be grouped with its business logic in the application.

Application view

The EventMap uses Injectors to pass data from your business managers into your applications view.

 

MateCookCalc example

Introduction

In a Mate application the view is responsible for collecting the data from the user. This is done simply by using the standard Flex UI controls. After collecting the data the view will create an instance of the GetCookingConversionEvent event and populate the properties of the event. Once the event has been instantiated and the appropriate data has been gathered the event is dispatched. After the event is dispatched the EventMap will take action because it has been set up to listen for this particular event.

The EventMap will call the web service and pass along the data sent by the view through the GetCookingConversionEvent event object. The web service will return a result which is handled by the services parser. The business manager will then store the data. The EventMap will use an Injector to send the data from the model to the view. In the MateCookCalc example this is accomplished using a PropertyInjector. The PropertyInjector will use the CookingCoversionManager class to populate the convertedCookingValue property defined in the MainView view.

The sourceKey attribute of the PropertyInjector defines the property on the CookingConversionManager class that should be used to populate the targetKey in the target property of the Injectors tag. The target is the view, MainView and the property is the public bindable property defined within MainView. Because the convertedCookingValue is a bindable property the Label within the MainView view will be update as the contents of the convertedCookingValue property are updated by the EventMap.

Events

Applications built using Mate are “driven” by events. The MateCookCalc example contains one custom event: GetCookingConversionEvent. The GetCookingConversionEvent event contains four public properties. The event type property is a static constant that uses a fully qualified class path. This is to help prevent collisions with other events potentially elsewhere in the application at a later point in time. The event classes in Mate can specify more than one event type. This approach helps to consolidate the number of classes used in your application.

The GetCookingConversionEvent event contains three other public properties. These properties represent data that will be sent along with the event when it is dispatched and as it is passed around the application at runtime. The event class’s constructor holds three arguments. It is important that the bubbles argument is set to true so the EventMap’s event handlers can listen for the event. 

EventMap

When an EventMap is created you need to extend Mate’s Event Map class and use the Mate namepace. Notice the namespace in the root tag of the MateCookCalc example’s CookCalcEventMap: xmlns=http://mate.asfusion.com/. This namespace must be added to the root element in every EventMap file for a Mate application. The EventMap cannot be named: “EventMap” because this will raise issues. To help other developers understand your codebase just name the file something specific to your application, such as: CookCalcEventMap. The MateCookCalc EventMap has debugging turned on. Enabling debugging will allow Mate to send valuable information to the Flex Output Console at runtime. This will help track down and locate potential issues in the application when it is executing. Debugging should always be disabled or removed in a production application.

EventHandlers

The EventHandlers tag in the MateCookCalc example’s CookCalcEventMap is set up to listen for the one and only GET event defined in the custom GetCookingConversionEvent event. Data binding is utilized so the public constant property can be used rather than a hard coded string. This is a great approach that can assist in preventing errors as you are developing. The Flex Compiler can catch a misspelling for you and circumvent runtime errors.  Debugging is also enabled for the EventHandlers tag. When debugging is enabled for the EventHandlers tag useful information pertaining to the event will be sent to the Flex Output Console at runtime. This is helpful for tracking down issues related to this particular event. If you enable debugging for the development process always remember to disable or remove the debugging before your application goes into production.

Inner tags for EventHandlers

There is one single inner tag for the CookCalcEventMap EventMap. Because the CookCalcEventMap example calls a preexisting web service a WebServiceInvoker is needed. The WSDL endpoint must be specified in the wsdl attribute. The ChangeCookingUnit method of the ConvertCooking web service is specified in the method attribute. The ConvertCooking web service requires three arguments that are passed to the service as an array. These arguments match the properties defined for the custom Mate GetCookingConversionEvent event . Debugging can also be enabled for the WebServiceInvoker tag. This will send useful information related to the connection and retrieval of data from the web service endpoint. This is a very useful feature and can help isolate issues related to the external web service as opposed to the Flex application.

Result Handlers

The CookCalcEventMap example has two result handlers that are defined in the resultHandlers tag. The result handlers are two MethodInvoker tags that reference two custom business manager classes.

Invokers

The two MethodInvoker tags reference two custom business manager classes that parse and store the data retrieved by the web service.  The MethodInvoker tags define for attributes each. The generator attribute uses data binding to reference the associated business manager class. The method attribute indicates the method of the business manager class that should be invoked. The arguments attribute is used to pass data to the business manager class.

Service parser

The service parser class is a business manager and should be considered part of the data model because it is responsible for massaging the data returned by the web service. The service parser class CookingConversionServiceParser accepts one argument which is the data passed to it from the EventMap through the resultObject property of the EventMap. This is the data that is returned by the web service assuming the web service call was successful. The CookingConversionServiceParser is a very simplistic example that creates a basic Object object, reads the value from the XML returned by the web service and then stores that value in a single property convertedCookingValue on the Object object. That generic object is then sent back to the EventMap and is available through the lastReturn object.

Business manager

The CookingCoversionManager class is the data model that the MateCookCalc example uses to store data returned by the ConvertCooking web service. The CookingCoversionManager has one property and a single method that is used to store the data in the convertedCookingValue property. Usually an application will have many services, parsers and managers.

Click here to download the example files.

 

Further exploration

Abstract the service definition

The service layer information does not need to be embedded into the EventMap. You can abstract this information for reuse across the application or the EventMap. Check out the documentation on the Mate website for information on how to approach this.

Multiple views

Implementing additional views into the example application is a great place to start expanding your knowledge and understanding of Mate. Check out the other example applications available on the Mate site to help guide you. Try to get a ViewStack control working in the same approach that is used in Cairngorm applications.

 

Conclusion

Use Mate for simplification and organization

Mate is a great framework for building robust, extensible applications with Adobe Flex. Feel free to use the example application for learning or as a template for your application. Mate has a wealth of fantastic documentation which helps when developing. Be sure to read through the rest of the documentation if you have any questions. Making the migration to a simplified application framework is a high priority for many developers. Hopefully this article has shown you why using an application framework is a good idea and how Mate is solving some of the issues faced by developers using other frameworks that are available at this time.

Disclaimer
The example application is simple for the purpose of clarity and ease of explanation, not because it's a good fit for using a framework. Frameworks are best suited for larger applications that will be maintained over time, not smaller applications with a limited lifespan. On larger applications, a framework will be a blessing as the project grows, but if used for the wrong kind of application it'll just be an annoyance.