Farata Systems      

The goal of this article is to give you a brief overview of some of the objects from clear.swc, which is a part of the open source Clear Toolkit framework available at https://sourceforge.net/projects/cleartoolkit.
Component library clear.swc includes a number of enhanced Flex components that software engineers of Farata Systems have been developing and using during the last three years in many enterprise projects. To better understand brief explanations given in this document, we strongly recommend to check out the source code from Sourceforge CVS repository and examine the source code of the classes mentioned below.
The ChangeObject Class

If you are familiar with LCDS, you know that Data Managemet Services use  ChangeObject, which is a special DTO that is used to propagate the changes between the server and the client.  Our component also includes such object but it can be used not only with LCDS but with BlazeDS too.

The class ChangeObject lives on the client side  – it is just a simple storage container for original and new versions of the record that is undergoing some changes:

package  com.farata.remoting {
[RemoteClass(alias="com.farata.remoting.ChangeObjectImpl")]
public class ChangeObject {

public var state:int;
public var newVersion:Object = null;
public var previousVersion:Object = null;
public var error:String = “”;
public var changedPropertyNames:Array= null;

public static const UPDATE:int=2;
public static const DELETE:int=3;
public static const CREATE:int=1;

public function ChangeObject(state:int=0,
newVersion:Object=null, previousVersion:Object = null) {
this.state = state;
this.newVersion = newVersion;
this.previousVersion = previousVersion;
}

public function isCreate():Boolean {
return state==ChangeObject.CREATE;
}
public function isUpdate():Boolean {
return state==ChangeObject.UPDATE;
}
public function isDelete():Boolean {
return state==ChangeObject.DELETE;
}
}

Every changed record can be in DELETE, UPDATE or CREATE state. The original version of the object is stored in the previousVersion property and current one is in the newVersion. That turns the ChangeObject into a lightweight implementation of the Assembler pattern, which offers a simple API to process all the data changes in a standard way similar to what’s done in Data Management Services that come with LCDS.

The DataCollection class that will be described below automatically keeps track of all the changes made by the use in the UI and sends a collection of the corresponding ChangeObject instances to the server.

On the server side, you can you need to separate a task into DAO and Assembler layers by introducing  external interfaces – the methods with  fill (retrieve) and sync (update) functionality (note the suffixes _fill and _sync in the Java code below).  Iterate through the collection of ChangeObject instances and call appropriate persistence functions:

/* Generated by ClearDB Utility (Dao.xsl) */
package com.farata.datasource;
import java.sql.*;
import java.util.*;
import flex.data.*;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.transaction.*;
import com.farata.daoflex.*;

public final class EmployeeDAO extends Employee {
public final List /*com.farata.datasource.dto.EmployeeDTO[]*/ fill{
return getEmployees_fill();
}

public final List getEmployees_sync(List items)    {
Coonection conn = null;
try  {
conn = JDBCConnection.getConnection(“jdbc/test”);
ChangeObject co = null;
for (int state=3;  state > 0; state–) { //DELETE, UPDATE, CREATE
Iterator iterator = items.iterator();
while (iterator.hasNext()) {   // Proceed to all updates next
co = (ChangeObject)iterator.next();
if(co.state == state && co.isUpdate())
doUpdate_getEmployees(conn, co);
if(co.state == state && co.isDelete())
doDelete_getEmployees(conn, co);
if(co.state == state && co.isCreate())
doCreate_getEmployees(conn, co);
}
}
} catch(DataSyncException dse) {
dse.printStackTrace();
throw dse;
} catch(Throwable te) {
te.printStackTrace();
throw new DAOException(te.getMessage(), te);
} finally {
JDBCConnection.releaseConnection(conn);
}
return items;
}
DataCollection class

This object keeps track of the changes on the client. For example, a user modifies the data in a DataGrid that has a collection of some objects used as a data provider. We’ve made a standard Flex ArrayCollection a little smarter so it’ll create a collection of ChangeObject instances for every modified, new, and deleted row. The class DataCollection will do exactly this.
Generate a sample CRUD application with Clear Data Builder and review the code of the generated sample Flex clients.  The code to populate DataCollection will look similar to this one:

[Bindable]
public var collection:DataCollection ;

collection = new DataCollection();
collection.destination=”myEmployeeDestination”;
collection.method=”getEmployees”;

collection.addEventListener( CollectionEvent.COLLECTION_CHANGE, logEvent);
collection.addEventListener(“fault”, logEvent);
collection.fill();
When the user is ready to submit the changes to the server, the following line will send a collection of ChangeObject instances to the server:
collection.sync();

Below are some relevant fragments from the class DataCollection. It offers an API for manipulating collection’s state. You can query the collection to find out if this particular object is new, updated or removed:

public function isItemNew(item:Object):Boolean {
var co: ChangeObject = modified[item] as ChangeObject;
return (co!=null && co.isCreate());
}
public function setItemNew(item:Object):void {
var co:com.farata.remoting.ChangeObject = modified[item] as ChangeObject;
if (co!=null){
co.state = ChangeObject.CREATE;
}
}
public function isItemModified(item:Object):Boolean {
var co: ChangeObject = modified[item] as ChangeObject;
return (co!=null && !co.isCreate());
}
public function setItemNotModified(item:Object):void {
var co: ChangeObject = modified[item] as ChangeObject;
if (co!=null) {
delete modified[item];
modifiedCount–;
}
}

private var _deletedCount : int = 0;
public function get deletedCount():uint {
return _deletedCount;
}

public function set deletedCount(val:uint):void {
var oldValue :uint = _deletedCount ;
_deletedCount = val;
commitRequired = (_modifiedCount>0 || deletedCount>0);
dispatchEvent(PropertyChangeEvent.createUpdateEvent(this, “deletedCount”, oldValue, _deletedCount));
}

private var _modifiedCount : int = 0;
public function get modifiedCount():uint {
return _modifiedCount;
}
public function set modifiedCount(val:uint ) : void{
var oldValue :uint = _modifiedCount ;
_modifiedCount = val;
commitRequired = (_modifiedCount>0 || deletedCount>0);
dispatchEvent(PropertyChangeEvent.createUpdateEvent(this, “modifiedCount”, oldValue, _modifiedCount));
}

private var _commitRequired:Boolean = false;
public function set commitRequired(val :Boolean) :void {
if (val!==_commitRequired) {
_commitRequired = val;
dispatchEvent(PropertyChangeEvent.createUpdateEvent(this, “commitRequired”, !_commitRequired, _commitRequired));
}
}
public function get commitRequired() :Boolean {
return _commitRequired;
}

public function resetState():void {
deleted = new Array();
modified = new Dictionary();
modifiedCount = 0;
deletedCount = 0;
}

All the changes are accessible as the properties deletes, inserts and updates:

public function get changes():Array {
var args:Array = deletes;
for ( var item:Object in modified) {
var co:com.farata.remoting.ChangeObject =
com.farata.remoting.ChangeObject(modified[item]);
co.newVersion = cloneItem(item);
args.push(co);
}
return args;
}

public function get deletes():Array {
var args:Array = [];
for ( var i :int = 0; i < deleted.length; i++) {
args.push(
new ChangeObject(
ChangeObject.DELETE, null,
ObjectUtils.cloneItem(deleted[i])
)
);
}
return args;
}
public function get inserts():Array {
var args:Array = [];
for ( var item:Object in modified) {
var co: ChangeObject = ChangeObject(modified[item]);
if (co.isCreate()) {
co.newVersion = ObjectUtils.cloneItem(item);
args.push( co );
}
}
return args;
}
public function get updates():Array {
var args:Array = [];
for ( var item:Object in modified) {
var co: ChangeObject = ChangeObject(modified[item]);
if (!co.isCreate()) {
// make up to date clone of the item
co.newVersion = ObjectUtils.cloneItem(item);
args.push( co );
}
}
return args;
}

This collection should also take care of the communication with the server and call the fill and sync methods:

public var _method : String = null;
public var syncMethod : String = null;

public function set method (newMethod:String):void {
_method = newMethod;
if (syncMethod==null)
syncMethod = newMethod + “_sync”;
}
public function get method():String {    return _method;        }

protected function createRemoteObject():RemoteObject {
var ro:RemoteObject = null;
if( destination==null || destination.length==0 )
throw new Error(“No destination specified”);

ro = new RemoteObject();
ro.destination    = destination;
ro.concurrency    = “last”;
ro.addEventListener(ResultEvent.RESULT, ro_onResult);
ro.addEventListener(FaultEvent.FAULT,   ro_onFault);
return ro;
}

public function fill(… args): AsyncToken {
var act:AsyncToken = invoke(method, args);
act.method = “fill”;
return act;
}

protected function invoke(method:String, args:Array):AsyncToken {
if( ro==null ) ro = createRemoteObject();
ro.showBusyCursor = true;
var operation:AbstractOperation = ro.getOperation(method);
operation.arguments = args;
var act:AsyncToken = operation.send();
return act;
}

protected function ro_onFault(evt:FaultEvent):void {
CursorManager.removeBusyCursor();
if (evt.token.method == “sync”) {
modified = evt.token.modified;
modifiedCount = evt.token.modifiedCount;
deleted = evt.token.deleted;
}
dispatchEvent(evt);
if( alertOnFault && !evt.isDefaultPrevented() ) {
var dst:String = evt.message.destination;
if( dst==null || (dst!=null && dst.length==0) )
try{ dst = evt.target.destination; } catch(e:*){};

var ue:UnhandledError = UnhandledError.create(null, evt,
DataCollection, this, evt.fault.faultString,
“Error on destination: ” + dst);
ue.report();
}
}

public function sync():AsyncToken {
var act:AsyncToken = invoke(syncMethod, [changes]);
act.method = “sync”;
act.modified = modified;
act.deleted = deleted;
act.modifiedCount=modifiedCount;
if (writeThrough)
resetState();
return act;
}

}
}

Data Styling with Resource Files

Resources are small files that can be attached as a property to a regular UI component as well as DataGrid column.  We call programming with resources data styling.
Again, start with examining the code of a sample project generated by Clear Data Builder. You can find a number of resource files under the folder flex_src\com\farata\resource.
Review the code of  YesNoCheckBoxResource.mxml:

<?xml version=”1.0″ encoding=”utf-8″?>
<fx:CheckBoxResource
xmlns=”com.farata.resources” xmlns:mx=”http://www.adobe.com/2006/mxml”
xmlns:resources=”com.theriabook.resources.*”
offValue = “N”
onValue = “Y”
textAlign=”center”
>

</fx:CheckBoxResource>

Doesn’t it look like a style to you? It can be specific to locale too. It makes it easy to change Y/N as on/off values to Д/Н, which means Да/Нет in Russian and Si/No in Spanish.
We’d like you to think of such resources as of entities that are separate from the application components. Isn’t such functionality similar to what CSS is about?
As a matter of fact, it’s more sophisticated than CSS because this resource is a mix of styles and properties. The next code example is yet another resource called StateComboBoxResource.mxml.  It demonstrates using properties (i.e. dataProvider) in such resource, which we also call  a Business Style Sheet. Such  resource can contain a list of values such as names and abbreviations of states:

<?xml version=”1.0″ encoding=”utf-8″?>
<fx:ComboBoxResource
xmlns=”com.farata.resources” xmlns:mx=”http://www.adobe.com/2006/mxml”
xmlns:resources=”com.theriabook.resources.*”
dropdownWidth=”160″
width=”160″
>
<fx:dataProvider>
<mx:Array>
<mx:Object data=”AL” label=”Alabama” />
<mx:Object data=”AZ” label=”Arizona” />
<mx:Object data=”CA” label=”California” />
<mx:Object data=”CO” label=”Colorado” />
<mx:Object data=”CT” label=”Connecticut” />
<mx:Object data=”DE” label=”Delaware” />
<mx:Object data=”FL” label=”Florida” />
<mx:Object data=”GA” label=”Georgia” />
<mx:Object data=”WY” label=”Wyoming” />
</mx:Array>
</fx:dataProvider>
</fx:ComboBoxResource>
Yet another example of a resource contains a reference to remote destination for automatic retrieval of dynamic data coming from, say  a DBMS:

<?xml version=”1.0″ encoding=”utf-8″?>
<fx:ComboBoxResource
xmlns=”com.farata.resources” xmlns:mx=”http://www.adobe.com/2006/mxml”
xmlns:resources=”com.theriabook.resources.*”
width=”160″
dropdownWidth=”160″
destination=”Employee”
keyField=”DEPT_ID”
labelField=”DEPT_NAME”
autoFill=”true”
method=”getDepartments”
>
</fx:ComboBoxResource>

As a matter of fact, you can’t say from this code if the data is coming from a DBMS or from somewhere else.  That data is cleanly separated from the instances of the ComboBox objects associated with this particular resource and can be cached either globally (if the data needs to be retrieved once) or according to the framework caching specifications. If you are developing a business framework, you may allow, say lookup objects to be loaded once per application or once per view.  This flexibility doesn’t exist in Singleton-based architectural frameworks.

Based on this resource file you can only say that the data comes back from a remote destination called Employee, which either a name of a class or a class factory. You can also see that the method getDepartments() will be returning the data containing DEPT_ID and DEPT_NAME that are going to be used with our enhanced ComboBox described earlier in this chapter.

OK, now we need to come up with a mechanism of attaching such resources to Flex UI components. To teach a Combobox working with resources, add a resource property to it:

private var _resource:Object;
public function get resource():Object
{
return _resource;
}

public function set resource(value:Object):void {
_resource = value;
var objInst:*  = ResourceBase.getResourceInstance(value);
if(objInst)
objInst.apply(this);
}

The resource property allows you to write something like this:

<fx:ComboBox resource=”{DepartmentComboResource}”

Each of the enhanced UI components that’s included in clear.swc includea such property.
Since interfaces don’t allow default implementation of such setter and getter and since ActionScript does not support multiple inheritance, the easiest way to include this implementation of the resource property to each control is by using the language compile-time directive #include, which includes the contents of the external file, say resource.as, into the code of your components:
#include “resource.as”

Check the code of Employee_getEmployee_GridFormTest.mxml generated by Clear Data Builder. You’ll find there several samples of using resources:

<fx:DataGrid dataProvider=”{collection}” doubleClick=”vs.selectedIndex=1″ doubleClickEnabled=”true” editable=”true” height=”100%” horizontalScrollPolicy=”auto” id=”dg” width=”100%”>
<fx:columns>
<fx:DataGridColumn dataField=”emp_id” editable=”false”
headerText=”Emp Id”/>
…
<fx:DataGridColumn dataField=”dept_id” editable=”false”
headerText=”Department”
resource=”{com.farata.resources.DepartmentComboResource}”/>
<fx:DataGridColumn dataField=”state” editable=”false”
headerText=”State”
resource=”{com.farata.resources.StateComboResource}”/>
<fx:DataGridColumn dataField=”bene_health_ins” editable=”false”
headerText=”Health”
resource=”{com.farata.resources.YesNoCheckBoxResource}”/>
<fx:DataGridColumn dataField=”bene_life_ins” editable=”false”
headerText=”Life”
resource=”{com.farata.resources.YesNoCheckBoxResource}”/>
<fx:DataGridColumn dataField=”bene_day_care” editable=”false”
headerText=”Day Care”
resource=”{com.farata.resources.YesNoCheckBoxResource}”/>
<fx:DataGridColumn dataField=”sex” editable=”false”
headerText=”Sex”
resource=”{com.farata.resources.SexRadioResource}”/>
</fx:columns>
</fx:DataGrid>

Using resources really boosts your productivity.

The DataForm Component

Almost every enterprise application uses forms.  Flex has the Form class that application programmers bind to an object representing data model. But the original Form class does not have means of tracking the data changes.

Since DataCollection is smart enough to automatically tracks the changes to the data on the client side, we found the way of enhancing the Form class so it works similarly to DataGrid/DataCollection duo. Yep, it has the dataProvider too.

Our DataForm control is bound to its model of type a DataCollection and it automatic tracks of all changes compatible with ChangeObject class that is implemented with remote data service.
The second improvement belongs to the domain of data validation. The DataForm can validate not just individual form items, but the form in its entirety too.  Our DataForm stores its validators inside the form rather than in an external global object.  The form becomes a self-contained black box that has everything it needs.

Software developers working on prototypes would appreciate if they should not be required to give definitive answers as to which control to put on the data form.  The first cut of the form may use a TextInput control, but the next version should use a ComboBox instead.
The third improvement should simplify the UI prototyping. We came up with a UI-neutral data form item that will allow not to be specific like, “I’m a TextInput”, or “I’m a ComboBox”. Instead, developers will be able to create prototypes with generic data items with easily attachable resources.

The DataForm is a subclass of a Flex Form, and its code implements two-way binding and includes a new property dataProvider. Its function validateAll()supports data validation. This DataForm component will properly respond to data changes propagating them to its data provider.
Review the code of the class DataForm available in Sourceforge CVS repository. Notice the setter dataProvider that always wraps up the provided data into a collection. This is needed to ensure that our DataForm supports working with remote data services the same way as DataGrid does.  It checks the data type of the value. It wraps an Array into an ArrayCollection, and XML turns into XMLListCollection. If you need to change the backing collection that store the data of a form, just point the collection variable at the new data.

If a single object is given as a dataProvider, turn it into a one-element array and then into a collection object. A good example of such case is an instance of a Model, which is an ObjectProxy  that knows how to dispatch events about changes of its properties.

Once in a while, application developers need to render non-editable forms hence the DataForm class defines the readOnly property.
The changes of the underlying data are propagated to the form in the method collectionChangeHandler().  The data can be modified either in the dataProvider on from the UI and the DataForm ensures that each visible  DataFormItem object (items[i]) knows about it. This is done in the function distributeData().

private function distributeData():void {
if((collection != null) && (collection.length > 0)) {
for (var i:int=0; i<items.length; i++)    {
DataFormItem(items[i]).data = this.collection[0];
}
}
}

Again, we need the data to be wrapped into a collection to support DataCollection or DataService from LCDS.

Technically, a DataForm class is a VBox that lays out its children vertically in two columns and automatically aligns the labels of the form items. But we’d like our DataForm to allow nesting – containing items that are also instances of the DataForm object. A recursive function enumerateChildren() loops through the children of the form, and if it finds a DataFormItem, it just adds it to the array items. But if the child is a container, the function loops through its children and adds them to the same items array. In the end, the property items contains all DataFormItems that have to be populated.

The DataForm has a function validateAll(), which in Flex framework is located in the class Validator. There, the validation functionality was external to   Form elements and you’d need to give an array of validators that were tightly coupled with specific form fields.

Enhancing Validation

It seems that validation in Flex has been designed with an assumption that software developers will mainly use it with forms and each validator class will be dependent only on one field it’s attached to.  Say, you have a form with two email fields. Flex framework forces you to create two instances of the EmailValidator object – one per field.
In the real life though, you may also need to come up with validating conditions based on relationships between multiple fields. You may also need to highlight invalid values in more than one field. For example, set the date validator to a field and check if the entered date falls into the time interval specified in  start and end date fields. If the date is invalid, you may want to highlight all form fields.

In other words, you may need not just to validate an object property, but also have an ability to write a number of validation rules in a function that can be associated not only with the UI control but also with the underlying data, i.e. with a data displayed in a row in a DataGrid.

Yet another issue of Flex Validator is its limitations when it comes to working with view states when the UI controls are created automatically. Everything would be a lot easier if validators could live inside the UI controls, in which case they would be automatically added to view states along with the hosting controls.
Having convenient means of validation on the client is an important part of the enterprise Flex framework.

Let’s consider a RIA for opening new customer accounts in a bank or an insurance company. This business process often starts with filling multiple sections in a mile-long application form. In Flex, such an application may turn into a ViewStack of custom components with, say five forms totaling 50 fields. These custom components and validators are physically stored in separate files. Each section in a paper form can be represented as a content of one section in an Accordion or other navigator. Say you have total of 50 validators, but realistically, you’d like to engage only those validators that are relevant to the open section of the Accordion.
If an application developer decides to move a field from one custom component to another, he needs to make appropriate changes in the code to synchronize the old validators with a relocated field.

What some of the form fields are used with view states? How would you validate these moving targets? If you are adding three fields when the currentState=”Details”, you’d need manually write AddChild statements in the state section Details.
Say 40 out of these 50 validators are permanent, and the other 10 are used once in a while.  But even these 40 you don’t want to use simultaneously hence you need to create, say two arrays having twenty elements each, and keep adding/removing temporary validators to these arrays according to view state changes.
Even though it seems that Flex separates validators and field to validate, this is not a real separation but rather a tight coupling.
During a conversation with a software developer, one manager said, “Don’t give me problems, give me solutions”.  OK, here comes the solution.
We’d like to make it clear – our goal in not to replace existing Flex validation routines, but rather offer you an alternative solution that can be used with forms and list-based controls.

We want to be able to have a ViewStack with five custom components, each of those has one DataForm whose elements have access to the entire set of 50 fields, but each will validate only its own set of 10.  In other words, all five forms will have access to the same 50-field dataProvider.  If during account opening the user entered 65 in the field age on the first form, the fifth form may show fields with options to open a pension plan account, which won’t be visible for young customers.
That’s why each form needs to have access to all data, but when you need to validate only the fields that are visible on the screen at the moment, you should be able to do this on behalf of this particular DataForm.

Clear component library includes the class ValidationRule.  We won’t go into details of this class here, but will rather tease you by showing a code snippet that illustrates how easy it is to embed a validator inside of the DataGridColumn:

<fx:DataGridColumn dataField=”PHONE” headerText=”Phone Number”
formatString=”phone”  >
<fx:validators>
<mx:Array>
<mx:PhoneNumberValidator  wrongLengthError=”Wrong
length, need 10 digit number”/>
</mx:Array>
</fx:validators>
</fx:DataGridColumn>

Needless to say that this is not an original Flex DataGridColumn, but its descendent.

Summary

In this writeup we’ve just touched upon the major players from the Clear component library. In the next article we’ll review the enhanecements made for the small guys like ComboBox or CheckBox.
We are also planning to record and publish a number of screencsasts that illustrate the use of various components of clear.swc. The process of creating enhanced library of Flex components will be described in greater detail in our upcoming O’Reilly book “Enterprise Development with Flex”.