Sample Use Case

Listing 9 presents two SQL tables Orders and OrderItems. Sample application enables end user to navigate from order to order, editing the master information (order) as well as details (order items). All interactive changes are accumulated in Flex – until button “Commit” is clicked. That’s exactly when deep sync happens – in one transaction, i.e. all or nothing, “commit” of all changes or complete “rollback”:

Figure 1. Order-OrderItems application snapshot


Client Data Persistance

Two DataCollections – OrderCollection, Listing 2 and OrderItemCollection, Listing 3 – assist in persisting the data on the client; they remote to the methods of the Java class OrderAssembler generated by the ClearDataBuilder given SQL-annotated abstract class Order.java, Listing 8. Each item of the OrderCollection carries orderItems referring to the child collection of line items of this order. At the application level, Listing 1 below, we expose only the master collection orders, which holds the entire hierarchy:

<?xml version="1.0" encoding="UTF-8"?>
<!--OrderEntryDemo.mxml -->
<mx:Application  
	xmlns:mx="http://www.adobe.com/2006/mxml" 
	xmlns="*" xmlns:collections="collections.*">
	<collections:OrderCollection id="orders"/>
	<mx:ControlBar>
		<mx:Button label="Fill"  click="selectedOrder=null;orders.fill()"  />
		<mx:Button label="Commit"  click="orders.sync(true)" 
			enabled="{orders.commitRequired}" />		
	</mx:ControlBar>
	<mx:VDividedBox  >
		<OrdersPanel id="master" orders="{orders}" 
			orderSelectionChange="selectedOrder = event.order"
		/>
		<OrderItemsPanel id="detail" width="100%"	
			selectedOrder="{selectedOrder}"
		/>
	</mx:VDividedBox>
	<mx:Script>
		<![CDATA[
			import com.farata.test.dto.OrderDTO;
			[Bindable] private var selectedOrder:OrderDTO;
		]]>
	</mx:Script>
</mx:Application>

Hierarchical DTO Items

Not that you would not have to write any code. For one, you would have to make sure that your DTOs implements com.farata.collections.dto.IHierarchicalDTO interface, i.e. “get” accessor of childCollections. One way to do it is via helper class com.farata.collections.dto.HierarchicalDTOAdapter. Please note OrderDTO in the snippet below extends the similarly named class prefixed with the “_” symbol. This is how, by default, CDB names a pair of generated ActionScript DTOs: the class with the “_” gets regenerated by CDB on every “Clean” of the project, while the extending class is preserving manual edits. Also, do notice how child collection orderItems – for each item – gets filled asynchronously, on order_id setter:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

package com.farata.test.dto{
import collections.OrderItemCollection;
import com.farata.collections.dto.HierarchicalDTOAdapter;
import com.farata.collections.dto.IHierarchicalDTO;
 
[RemoteClass(alias="com.farata.test.dto.OrderDTO")]
public class OrderDTO extends _OrderDTO implements IHierarchicalDTO{
[Transient] [Bindable] public var orderItems:OrderItemCollection;
[Transient] public var adapter:HierarchicalDTOAdapter;
 
public function OrderDTO() {
    super();
    adapter = new HierarchicalDTOAdapter(this);
    orderItems = new OrderItemCollection();
    adapter.addCollection(orderItems);
}
 
public function get childCollections():Array {
    return adapter.childCollections;
}
 
public override function set order_id(orderId:String):void {
    if (orderId !== super.order_id) {
         super.order_id = orderId;			
         orderItems.fill(order_id);	
    }			
} 
}//OrderDTO
}

Browse Listings 1-8: except “view”-Panel components there is no other code you would need to write. As long a you start with the SQL-annotated abstract Java source everything else gets code generated by the CDB.


What if you use CDB with the existing DAO, i.e. IJavaDAO?

You are not confined to SQL-annotations to use the fill() and sync(), of course. CDB allows your DataCollections to remote to any Java class implementing com.farata.daoflex.IJavaDAO interface (see CDB documentation for more details):

package com.farata.daoflex;
import java.util.List;
import flex.data.ChangeObject;
 
public interface IJavaDAO {
    List fill();
    List<ChangeObject> sync(List<ChangeObject> items);
}

In addition to IJavaDAO, participation in the deep sync requires your Java class to implement IBatchTransactionServiceSupport. Methods of this interface allow to synchronize changes accumulated by the DataCollection in three independent steps: all deletes, all updates and all inserts:

package com.farata.daoflex;
import java.util.List;
import flex.data.ChangeObject;
 
public interface IBatchServiceTransactionSupport  {
    List<ChangeObject> deleteItems(List<ChangeObject> items);
    List<ChangeObject> updateItems(List<ChangeObject> items);
    List<ChangeObject> insertItems(List<ChangeObject> items);
}

BatchService

Splitting of monolythic sync() into three steps is required to support the referential integrity of data: children have to be deleted prior to parents and parents need to be inserted prior to children. And yet we can not addord three remoting calls instead of one (sync()), six calls altogether in our Orders-OrderItems scenario, because server-side transaction can not be spawned across several remoting calls.

That’s where BatchService class from clear.swc comes in play. It refers to sequence of several remote method calls-to-do as a “batch”, or, simply array of BatchMember elements: destination name, method name, array of arguments. Instead of multiple remote calls it sends the “batch” as argument of one remote call – to Java class com.farata.remoting.BatchGateway (daoflex-runtime.jar). In turn, BatchGateway’s method execute(List<BatchMember>) invokes the required remote calls sequentially, wrapping the entire sequence in the JTA begin/commit/rollback.

Here is a snippet illustrating the work of the BatchService:

  var bs: com.farata.remoting.BatchService;
  .  .  .
  bs = new BatchService();
  bs.addEventListener(FaultEvent.FAULT, onFault);
  bs.registerCollection(orders, 0); //0 - default (top) priority, parent
  bs.registerCollection(orderItems,1); //1 - priority, child of "0"
  .  .  .
  var batch:Array = bs.batchRegisteredCollections();
  bs.send(batch);

As you can see, BatchService batch is not confined to DataCollections: you can batch for synchronical server-side execution any sequence of remote calls. While BatchService has been around since 2006. the dataCollection.sync(true) further reduces the amount of code required to transactionally update associated collections. Users of SQL-based branch of the CDB benefit from automatic generation of the required Java functions. Otherwise, your Java DAO has to implement IBatchTransactionServiceSupport.

package collections {
import com.farata.collections.DataCollection;
 
public class OrderCollection extends DataCollection {
    public function OrderCollection(source:Array=null) {
        super(source);
        destination="com.farata.test.Order";
        method="getOrders";
    }
}
}

package collections {
import com.farata.collections.DataCollection;
 
public class OrderItemCollection extends DataCollection {
 
   public function OrderItemCollection(source:Array=null) {
        super(source);
        destination="com.farata.test.Order";
        method="getOrderItems";
   }
}
}

<?xml version="1.0" encoding="UTF-8"?>
<!-- OrdersPanel.mxml -->
<mx:Panel title="Orders" 
	xmlns:mx="http://www.adobe.com/2006/mxml" >
 
    <mx:Metadata> 
        [Event(name="orderSelectionChange", type="events.OrderEvent")] 
    </mx:Metadata> 
 
	<mx:DataGrid id="dg" dataProvider="{orders}" editable="true"  change="onChange()" height="100%" >
		<mx:columns>
			<mx:DataGridColumn dataField="order_id" headerText="Order Id" />
			<mx:DataGridColumn dataField="customer_first_name" headerText="First Name" />
			<mx:DataGridColumn dataField="customer_last_name" headerText="Last Name" />
			<mx:DataGridColumn dataField="order_date" headerText="Order Date"  itemEditor="mx.controls.DateField" editorDataField="selectedDate"/>
		</mx:columns>
	</mx:DataGrid>
	<mx:ControlBar width="100%">
		<mx:Button label="Remove" click="onRemove(dg.selectedIndex)" enabled="{dg.selectedIndex != -1}"/>
		<mx:Button label="Add" click="onAdd(Math.max(0,dg.selectedIndex+1)); "/>
		<mx:Label text="Deleted: {orders.deletedCount}"/>
		<mx:Label text="Modified: {orders.modifiedCount}"/>
	</mx:ControlBar>
	<mx:Script>
	<![CDATA[
	import events.OrderEvent;
	import com.farata.test.dto.OrderDTO;
	import com.farata.collections.DataCollection;
 
	[Bindable] 	public var orders:DataCollection;
 
	private function onAdd(position:int):void	{
		var item:OrderDTO = new OrderDTO();
		item.order_id = "###" + String(orders.length + 1);	
		item.order_date = new Date();
 
		orders.addItemAt(item, position);
		dg.selectedIndex = position;
		onChange();
	}	
	private function onRemove(position:int):void {
		orders.removeItemAt(position);
	}
 
	private function onChange():void {
		var event:OrderEvent = new OrderEvent(OrderEvent.ORDER_SELECTION_CHANGE);
		event.order = dg.selectedItem as OrderDTO;
		dispatchEvent(event);
	}	
 
	]]>
	</mx:Script>
</mx:Panel>

<?xml version="1.0" encoding="utf-8"?>
<!-- OrderItemsPanel.mxml -->
<mx:Panel title="OrderItems" xmlns:mx="http://www.adobe.com/2006/mxml" >
	<mx:DataGrid id="dg" dataProvider="{orderItems}" editable="true" height="100%">
		<mx:columns>
			<mx:DataGridColumn dataField="order_id" headerText="Order Id" />
			<mx:DataGridColumn dataField="item_id" headerText="Item Id" />
			<mx:DataGridColumn dataField="product_name" headerText="Product" />
			<mx:DataGridColumn dataField="quantity" headerText="Quantity" />
		</mx:columns>
	</mx:DataGrid>
	<mx:ControlBar width="100%">
		<mx:Button label="Remove" click="onRemove(dg.selectedIndex);" enabled="{dg.selectedIndex != -1}"/>
		<mx:Button label="Add" click="onAdd(Math.max(0,dg.selectedIndex + 1)); " enabled="{selectedOrder!=null}"/>
		<mx:Label text="Deleted: {orderItems.deletedCount}"/>
		<mx:Label text="Modified: {orderItems.modifiedCount}"/>
	</mx:ControlBar>
	<mx:Script>
		<![CDATA[
		import com.farata.test.dto.OrderItemDTO;
		import com.farata.test.dto.OrderDTO;
		import com.farata.collections.DataCollection;
 
	    [Bindable]private var orderItems:DataCollection ;
 
		private var _selectedOrder:OrderDTO;
		[Bindable]
		public function set selectedOrder(order:OrderDTO):void {
			_selectedOrder = order;
			if (order != null) {
				orderItems = order.orderItems;
			} else 
			 	orderItems = null; 
		}
		public function get selectedOrder():OrderDTO {
			return _selectedOrder;
		}
 
		private function onAdd(position:int):void	{
			var item:OrderItemDTO = new OrderItemDTO();
			item.order_id = selectedOrder.order_id;			
			if (item.quantity ==0) item.quantity = 1;
 
			orderItems.addItemAt(item, position);
			dg.selectedIndex = position;
		}
		private function onRemove(position:int):void {
			orderItems.removeItemAt(position);
		}
	]]>
	</mx:Script>	
</mx:Panel>

package events{
import com.farata.test.dto.OrderDTO;
import flash.events.Event;
public class OrderEvent extends Event {
    public static const ORDER_SELECTION_CHANGE:String ="orderSelectionChange";
 
    public var order:OrderDTO;
    public function OrderEvent(type:String, bubbles:Boolean=false, cancelable:Boolean=false){
        super(type, bubbles, cancelable);
    }
}
}

/* Generated only when absent by ClearDataBuilder according to UserActionScriptDTO.xsl */
package com.farata.test.dto{
import collections.OrderItemCollection;
import com.farata.collections.dto.HierarchicalDTOAdapter;
import com.farata.collections.dto.IHierarchicalDTO;
 
[RemoteClass(alias="com.farata.test.dto.OrderDTO")]
public class OrderDTO extends _OrderDTO implements IHierarchicalDTO{
//--------------------------------------------//
// Your custom code goes here                       //
//--------------------------------------------//
 
[Transient] [Bindable] public var orderItems:OrderItemCollection;
[Transient] public var adapter:HierarchicalDTOAdapter;
 
public function OrderDTO() {
    super();
    adapter = new HierarchicalDTOAdapter(this);
    orderItems = new OrderItemCollection();
    adapter.addCollection(orderItems);
}
 
public function get childCollections():Array {
    return adapter.childCollections;
}
 
public override function set order_id(orderId:String):void {
    if (orderId !== super.order_id) {
        super.order_id = orderId;
        orderItems.fill(order_id);
    }
}
}//OrderDTO
}

package com.farata.test;
import java.util.List;
/**
* @daoflex:webservice
* pool=jdbc/test
*/
public abstract class Order
{
/**
* @daoflex:sql
* sql=:: select order_id, customer_first_name,
* customer_last_name, order_date from simple_order
* ::
* transferType=OrderDTO[]
* keyColumns=order_id
* updateTable=simple_order
* autoSyncEnabled=true
*/
public abstract List getOrders();
 
/**
* @daoflex:sql
* sql=select * from simple_order_item WHERE ORDER_ID=:orderId
* transferType=OrderItemDTO[]
* updateTable=simple_order_item
* keyColumns=order_id,item_id,product_name
* autoSyncEnabled=true
*/
public abstract List getOrderItems(String orderId);
}

CREATE TABLE `simple_order` (
`order_id` char(32) NOT NULL default '',
`customer_first_name` varchar(32) NOT NULL default '',
`customer_last_name` varchar(32) NOT NULL default '',
`order_date` datetime NOT NULL default '0000-00-00 00:00:00',
PRIMARY KEY (`order_id`)
) ENGINE=InnoDB DEFAULT CHARSET=latin1$$
 
INSERT INTO `simple_order` (`order_id`,`customer_first_name`,`customer_last_name`,`order_date`) VALUES
('###1','Victor','Rasputnis','2006-02-04 00:00:00'),
('###2','Yakov','Fain','2006-09-25 00:00:00'),
('###3','Anatole','Tartakovsky','2006-07-01 00:00:00')$$
 
CREATE TABLE `simple_order_item` (
`order_id` char(32) NOT NULL default '',
`item_id` char(32) NOT NULL default '',
`product_name` varchar(32) NOT NULL default '',
`quantity` int(11) NOT NULL default '1',
PRIMARY KEY (`order_id`,`item_id`,`product_name`)
) ENGINE=InnoDB DEFAULT CHARSET=latin1$$
 
INSERT INTO `simple_order_item` (`order_id`,`item_id`,`product_name`,`quantity`) VALUES
('###1','1','Laptop',1),
('###1','2','Battery',1),
('###1','3','Laptop Backpack',1),
('###3','1','Apple',1),
('###3','2','Orange',1)

Victor Rasputnis

The Wiki page of Clear Toolkit is http://cleartoolkit.wiki.sourceforge.net/

The lates build, documentation and the source code of all Clear Toolkit components you can find at https://sourceforge.net/projects/cleartoolkit/

Victor

Details and registration at http://www.eventbrite.com/event/202308109.

Have you used your training budget of 2008 yet?

Victor

I, for one, would walk around Notre-Dame, and the point I am going to make is about Flex:

If I could pass just one Flex advice that would be: Use Data Transfer Objects.

Use Data Transfer Objects and NOT the dynamic Objects, and NOT the XML to pass data between your server and Flash tiers. If you are working with a Java Server, make your Java (methods) accept/return custom classes and NOT Map objects.

With this keystone your architecture will be reliable and performing. You will save tons of time and energy. What do you do with these savings – none of my business.

Here are the details:

1. _DO_ define similar classes on Java and ActionScript. See details of Java/ActionScript type mapping in the Flex documentation.

2. _DO_ declare these classes as [Bindable] if you envision dynamic updates to the data. Further, _DO_ use collections of these Bindable instances as dataProviders for your DataGrid and let Flex do the miracle: all changes to the data will be reflected by the visual control. There are no miracles, of course: [Bindable] is a shortcut to dispatch event on a data change, the very same event that is expected by ArrayCollection. The collection in turn, dispatches a (different) event on its change. Importantly – the very same event that is expected by the DataGrid.

Let me put it another way: have you ever used collection.itemUpdated()? Well, once you start DTO’s “itemUpdated” will sound to you like the name of the undocumented event

OK, I will rub it in further: if you marshall (property) Array of Objects, the Array itself is Bindable, but none of the items are.

3. Make sure that your server-side and client-side DTOs _DO_ provide unique! set/get uuid property. Flex loves this property, do get in love with it too. Flex is using it to identify elements of data presented by the list-based controls. You will find numerous uses for it as well. For instance, instead of sorting by industry, ticker you would sort by industry, ticker and uuid. Why? Because then the hash value will be unique for each record, which would result in substantially better performance.

4. _DO NOT_ hunt for value change on the visual controls (aka View). This task belongs to the data layer (aka Model). Consider replacing [Bindable] public var with the get/set property pair and dispatching the event (PropertyChange) yourself:

private var _amount:Number;
public function get amount() : String{
return _amount;
}
public function set amount( value : Number ):void{
var oldValue:Object = this._amount;
if (oldValue !== value) {
this._amount = value;
dispatchUpdateEvent(“amount”, oldValue, value);
}
}
private function dispatchUpdateEvent(propertyName:String, oldValue:Object, value:Object):void {
dispatchEvent(
PropertyChangeEvent.createUpdateEvent(this, propertyName, oldValue, value)
); �
}

Then, to act on value change, consider customizing the set method. Better yet, consider extending your ActionScript DTO with another class: leave basic layer of DTOs untouched, do customization in the extension. One more gain right here: now you can intercept (breakpoint) whenever your data changes.

5. _DO_ use extension of DTO class (above) to introduce “computed columns”:

public function get unrealizedGain():Number {
return lastPrice – costBasis; �
}

Again, _DO NOT_ use itemEditEnd of the control for these and similar purposes.

_DO NOT_ be afraid of two [RemoteClass] pointing to the same Java DTO: Flex will resolve the reference in favor of the extension layer.

6. Over your project lifespan, you will see many additional fits for DTOs: custom serialization, custom toString() and toXML() methods.

Now, you may say that all these recommendation are way too obvious.

Then I just take off my hat and … see you around Notre-Dame, perhaps.
Otherwise, keep coding.

Victor

Log4Fx is an advanced yet very simple to use logger component for Adobe Flex applications that use Java application servers. You can set up the logging on the client or server sides, and you can redirect the output of the log messages to local log windows or make the log output easily available to the production support teams located remotely. Think of a production situation when a particular client complains that the application runs slow. Log4Fx allows you to turn on the logging just for this client and you can do it remotely with Web-browser access to the log output.

Log4Fx comes with several convenient and easy to use display panels with log messages. This manual also covers techniques of logging mixed Flex/Java projects with or without Flex Builder.

USING LOG4FX

If you’ve been using other loggers like log4j, you’ll be pleasantly surprised seeing how Log4Fx automatically inserts required logging code in your existing Flex project. It comes down to memorizing a couple of keystroke combinations as explained below. But first, you need to install Log4Fx, and then add it to your Flex project.
Just right-click on your Flex Project, select Log4Fx > Add Dependency Files from the popup menu.This action will add several new artifacts to your project:

• A new Flex component Log4FxLoggingTarget.mxml, will be automatically added to your project directory
• An extra tag <Log4FxLoggingTarget xmlns=”*”> will be added at the end of the source code of your default Flex application
• A new application RemoteLogReceiver.mxml is added to the project to provide remote access to the log messages
• The Log4Fx.swc is added to your project’s build path
• A small file log4flex.jar is added to the your Java server’s lib folder

Now you can use the hot keys to add required log lines to your application code. You can see the list of available hot keys by pressing CTRL + R.

For example, let’s say you are considering adding a line to the application called MyStockProtflio:

trace(“Entered the method getPriceQuotes”);

Just press the cursor in the script section of your application and press Ctrl+R followed by M, which will insert the following lines in your program:

import mx.logging.Log;
import mx.logging.ILogger;
private var logger:ILogger = Log.getLogger(“MyStockPortfolio”);

Now place the cursor, say in the function getPriceQuotes() and press Ctrl+R followed by D and the following line will be added at your cursor location:

if (Log.isDebug()) logger.debug(“”);

Enter the text between the double quotes, and if you’ll set the level of logging to Debug, this message will be sent to the specified destination selected with the Logging Manager as explained below.
If you need to write a log message that will deliver fatal errors, press Ctrl+R, F , and you’ll see a new line in your code:

if (Log.isFatal()) logger.fatal(“”);

Just enter appropriate error information inside the quotes, and Log4Fx will send the information of this error to the selected log target.
Here’s a code of the HelloWorld application with highlighted inserts from Log4Fx:

<?xml version=”1.0″ encoding=”UTF-8″?><mx:Application xmlns:mx=”http://www.adobe.com/2006/mxml” layout=”absolute”>
<mx:Grid>
<mx:GridRow>
<mx:GridItem>
<mx:LinkButton label=”Hello world!”
click=”logger.warn(‘Warning’);”/>
</mx:GridItem>
</mx:GridRow>
<mx:GridRow>
<mx:GridItem>
<mx:LinkButton label=”Hello world again!”
click=”logger.info(‘Info’);”/>
</mx:GridItem>
</mx:GridRow>
</mx:Grid>
<mx:Script>
<![CDATA[
import mx.logging.Log;
import mx.logging.ILogger;
private var logger:ILogger = Log.getLogger("com.farata.samples");
]]>
</mx:Script>

<Log4FlexLoggingTarget xmlns=”*”/>
</mx:Application>

You still need to take care of two more items:

1. Define the destination of log messages by specifying the logging target.
2. Using Logging Manager, define the properties for various logging categories, set the default logging level et al.

Using Logging Manager

The logging manager is a part of Log4Fx, and it allows you to change the logging settings on the fly while debugging the application is in progress. During the lifespan of the application, you may need to be able to redirect the log messages to a different target(s). This functionality is implemented in Logging Manager, which is a UI component that supports interactive control levels, categories, and targets. This is what you can do with the Logging Manager on the client side:
• Automatically discover and list logging categories, and allow changing of the logging level for each logical category or a package.
• List registered targets/destinations, and set default logging level and other common parameters.
• Store the logging settings on the client’s computer.

To see this panel, start the application that uses Log4Fx and press CTRL+SHIFT+BACKSPACE – the logging manager will pop-up on top of your application window. The following screenshot shows the logging manager panel on top of the HelloWorld application after the user pressed CTRL+SHIFT+BACKSPACE.

You can change the logging level at any time while your application is running. This feature is crucial for mission-critical production applications, where you can’t ask the user to stop the application (i.e. financial trading systems), but need to obtain the logging information to help the customer on the live system.
Even if the user is not an IT professional, s/he can do this by following directions of the production support engineer.
You can also change the default log level by selecting the required log level from the dropdown box. The destination (target) of your log messages can be selected from another dropdown as described in the section Working with Log targets.

WORKING WITH LOG TARGETS

Trace
If you set the target Trace on the Logging Manager panel, all program messages will be output using the class from Flex framework called TraceTarget as if you’ve been using the function trace().

Socket
Setting the target to Socket will engage SocketTarget class for logging your program messages via HTTP connection.

If your Flex project was configured to work with Java Servlet container, i.e. Apache Tomcat, adding Log4Fx dependency files creates a small file on the server side log4flex.jar, which contains two Java classes – FlexLoggerServlet and ServerFlexLogger. The file web.xml will be automatically modified to add a section that maps the requests that contain the url-pattern “logging” to FlexLoggerServlet.

You can also use this reference implementation if you decide to customize the logger to utilize non-Java Web servers, i.e. PHP or .Net.

Server
This option can be used by applications that utilize Flex remoting via LiveCycle Data Services ES (LCDS), OpenAMF, or any other remoting transport. If you want to send the log output to the server, create a Java class that will support logging on the server side. Here’s the sample version of a class that uses popular Log4J component:

package com.theriabook.logging;
import org.apache.log4j.Logger;
import org.apache.log4j.Level;

public class ServerFlexLogger {

static public void log(String levelStr, String message)
{
logger.log(Level.toLevel(levelStr), message);
}
static Logger logger;
static
{
logger = Logger.getLogger(“MyFlexLogger”);
logger.setLevel(Level.ALL);
}
}

In Logging Manager, as soon as you select Server as target, a text field will be shown where you need to enter the name of the server side destination that is mapped to the class com.theriabook.logging.ServerFlexLogger.

Now the log messages from your Flex programs will be sent to the server destination ServerFlexLogger and logged there. The section 5.4 shows an example of how such communication could have been programmed manually, but Log4Fx spares you from this. Just configure the Flex remoting destination and enter its name in the Destination field as shown above.

Local Panel

Flex developers who spend most of the time “inside” Eclipse IDE send the log output to the local panel, which is nothing else but yet another Eclipse View.
Right-click on your Flex Project, select Log4Fx > Show Workbench Viewer from the popup menu. You’ll see a new view panel in your Eclipse workbench:

Select Local Panel as target, and now you can your log messages will be sent to a new Farata Logger View:

The push buttons on the toolbar allow you to turn on/off the output of debug, info, warning, fatal and error messages. You can also sort the messages by level, time, category, and message text.

XPanel

The XPanel target allows to trace Flex/Flash applications interactively in a separate window. It also gives you native platform features like ability to save log to a file, keep the log window always on top and redirect the output to platform-specific debugging API. XPanel runs on Windows 95/98/Me, NT/2000/XP/Vista. To configure output to the external XPanel, just right-click on your Flex Project, and select Log4Fx > Show External Viewer from the popup menu. You’ll see an empty XPanel window will be displayed. Ensure that the target on the Logging Monitor is set to XPanel. Now your log messages will be streamed to an external XPanel window:

XPanel’s toolbar provides quick access to Exit, Save Log, Start/Stop Logging, Clear Log, independent logging levels, Text/DataGrid Mode and “About” menu options.

Log4FlexLoggingTarget Explained

When you first added the Log4Fx dependency files , the file Log4FlexLoggingTarget.mxml was automatically added to your application project. It allows setting default targets for Log4Fx. In this section we’ll discuss code of the Log4FlexLoggingTarget.mxml:

<fx:LoggingTarget
xmlns:fx=”http://www.faratasystems.com/2006/components”
xmlns:mx=”http://www.adobe.com/2006/mxml”
defaultLoggerLevel=”{LogEventLevel.INFO}”>

<mx:Script>
import mx.logging.LogEventLevel;
</mx:Script>

<!– Setting default output to XPanel –>
<fx:XPanelLogOutput
fieldSeparator=” -> ” />
<!– Setting special popup window for filtering –>
<fx:adjustmentManager>
<fx:LoggingAdjustmentManager
keyCode=”{Keyboard.BACKSPACE}”
shiftKey=”true”
ctrlKey=”true”>
<mx:Array>
<!– List of available outputs (with their own settings) –>
<fx:XPanelOutputDescription />
<fx:TraceOutputDescription
fieldSeparator=” -> ”
includeCategory=”true”
includeDate=”true”
includeLevel=”true”
includeTime=”true” />
<fx:SocketOutputDescription />
<fx:ServerOutputDescription/>
<fx:LocalConnectionOutputDescription/>
<fx:RemoteOutputDescription/>
</mx:Array>
</fx:LoggingAdjustmentManager>
</fx:adjustmentManager>
</fx:LoggingTarget>
This code performs the following actions:
1. Set the default logger level. You can change it by modifying the value of the property defaultLoggerLevel, which has a default value of LogEventLevel.INFO, and we’ve included this code for illustration purposes.
2. Set the destination of the default output of the logger. By default, the log info goes to XPanel. You can change the default value either by assigning appropriate value to XPanelLogOutput, (for example, LocalConnectionOutput) or by using Logging Manager. You can also specify additional parameters for targets, for example, fieldSeparator, which denotes the field delimiter to be used in log files. All available parameters are listed in Eclipse Help (see, com.theriabook.util.XPanelTarget or other targets). The next section of this document describes how to set such parameters.
3. You can redefine the hot keys that bring up the Logging Settings panel by changing the values of the properties keyCode, shiftKey and/or ctrlKey. For example, if you use the combination keyCode=“{Keyboard.ESCAPE}”, ctrlKey=”false” and shiftKey=”true” in the code, pressing SHIFT + ESC will open the Logging Monitor window. If none of these properties are set, you can open the Logging Monitor by pressing F12.
4. In the code section “List of available outputs” you can change the list of available logging targets in the Logging Manager panel. By default, it shows XPanelOutput, TraceOutput, SocketOutput, ServerOutput, LocalConnectionOutput ? RemoteOutput, which were described above. If you do not need all targets, remove some of the available outputs from Log4FlexLoggingTarget.mxml.
You can set the default logging level is defined in the file Log4FlexLoggingTarget.mxml and in the Logging Manager panel. The latter has higher priority over the settings specified in Log4FlexLoggingTarget.mxml. For example, after adding Log4Fx to your project, you can specify LogEventLevel.WARN as the default logger level that will take effect on the application startup. But if you change this level to ERROR using the Logging Manager panel, it’ll remember the ERROR level till the next start of your application despite the fact that the file Log4FlexLoggingTarget.mxml still has the WARN level. To remove all logger settings made from the panel, press the button Clear Local Storage on the Logging Manager panel. After that, the settings from the file Log4FlexLoggingTarget.mxml will be in effect again.

Remote Logging

Adding dependency file described above created a new application in your project – RemoteLogReceiver.mxml, which can be used by a remote production support crew.
Let’s say the user’s application is deployed at the following URL:

http://230.123.12.10:8080/myapplication.html

By pressing the CTRL-SHIFT-BACKSPACE, the user brings the Logging Manager and selects the target Remote Logging.

The destination RemoteLogging is selected automatically, and the user needs to input a password, which he will share with the production support engineer.
Since the RemoteLogReceiver.mxml is also an application that is sitting right next to your main application in Flex Builder’s project, it’ll also will get compiled into an SWF file, the html wrapper will be generated too, and it will be deployed in the Web server of your choice too. The end users will never use it, and they won’t even know that it exists. But production engineer can enter its URL in his browser when needed:

http://230.123.12.10:8080/RemoteLogReceiver.html

Think of an undercover informant who just lives in the neighborhood, but when engaged, it immediately starts sending the information out.
After entering the password provided by the user and pressing the button Connect, he’ll start receiving Log messages sent by the user’s application.

The buttons on the toolbar allow selective output of log messages – it works the same way as with XPanel.

Farata’s own Yakov Fain will participate in this discussion. If your firm is considering various tools and techniques for development of your next RIA, this show will definitely help you with making the right decision. This show will feature an interactive Q&A session from viewers during its final segment.

This free event will start at 1PM EST, and you can register at http://web2.sys-con.com/read/375328.htm

Enjoy the show,
Victor

Update: The short (edited) version of the podcast is available at http://tv.sys-con.com/read/385147.htm

A very typical approach.

First of all, Adobe engineers have elaborated enough on the subject, the latest and very detailed answer being provide by Kevin Hoyt in this link http://weblogs.macromedia.com/khoyt/archives/2007/01/context_menus_r.cfm. Add items, remove items, globally or per object, but you won’t be able to get rid of the two – About and Settings… – in Flash Player Virtual Machine as you won’t be able to get rid of the brakes in your car. Buy it with the brakes or don’t drive until Apollo arrives. Period.

But let’s look at the bigger issue. There is a legacy client/server application that for a _business reasons_ needs to be ported to the net. Having spent almost 6 years in Client/Server to Ajax/J2EE conversion projects, I observed that setting the expectations right is the key here: move from Swing or any C/S to browser GUI – changing a technology platform – results in a redesign and re-architecture. I would certainly pose the following row of question:

During the re-design, which features of the original system, including, but not limited to UI should be retained? Which features should go? Which features should be added?

I am not even relating to the fact that if we were to disable Settings… we could forfeit ability to save application data to the local storage. In the intranet scenario we can, theoretically, assume that Flash Player settings are correct to begin with. It is obvious anyway, that Flex allows much friendlier and less-clicky UI then the one centered around context menus. No need to wait for the user to right-click and _discover_ the choices, we could have proactively display them as soon as the user moves over the object. Besides UI, lots of things change when you move from 2 tiers to 3. You can not map them one to one, so the ContextMenu might be the least of your worries.

Re-training costs? Sure. Not to mention that you’d have to justify the very cost of the port. But if the _business goal_ it to increasing the user base/revenue, you would not have to concentrate on the ContextMenu. Technology is not the problem here, it’s a business issue.

I am not saying that there is no way that  ContextMenu can be possibly hidden and overlapped with your own, especially in the Intranet. My point is that it might not be even worth it.

Victor

Ask me what is the easiest way to build RIA apps and you do not have to wait for the answer: it’s Flex, of course. Ask me is it fast to develop in Flex and I will say “it depends”.

First, it depends where are you coming from. Literally. I’ve seen enough places where Struts/HTML is the only known UI technology. Meanwhile the business is running a huge VB app that changed hands 6 times before last developer left during the .com days.  Now everyone wants it on the Web, but expectations of the development complexity are distorted by the culture of straw houses.

“Nevermind that legacy Client/Server system took 10 man years to build. We have never done Struts/HTML app in more then 6 months and Flex is a “better HTML” so it should take 3 months in Flex, should it not?”

This rhetorical question brings me to the second point.

What is simple and straightforward in Flex, has been often out of the question, unthinkable in Web 1.0 applications. The paradox, that I call the “Home Depot Effect”, is that once the threshold of “possible” has changed, you want it all. It is easy to put the tiles, it is easy to do the lights, it is easy to build the patio, etc. Does it mean you are going to rebuild that old house in the same time you used to paint your Struts/HTML appartment?

Now you know what I meant by “it depends”.

Victor

Flex compilers support -link-report option. It let’s you produce a file of the linker dependencies found during the build of your SWF. Then there is a matching -load-externs option that let you specify the classes you do not want to link, but rather prefer to extern. Conveniently, -load-externs anticipates the input to be in exactly the same XML format as is produced by -link-report.

Speaking of modules and applications – just as an example case – this pair of options enables you to extern for the module everything, that will be loaded by the application. You build your application producing -link-report, then apply it for the module (see Flex docs for exact details). However, if you plan to ever reuse the same module for the different hosting application, this technique is not applicable. You’d need to rebuild the module.

There is an opposite way of using -link-report option. If you use compiler’s option –include you can have application merge-in all classes required by your libraries .

In this scenario, you run -link-report on the module and instead of optimizing the module, you optimize the application. No need to rebuild your modules to satisfy every individual application – they stay 100% reusable. Instead you tune your applications.

And, speaking of size, do not forget the -debug option. By turning it to false you may strip up to 30% of size taken by debugging information. By the same token, you may want to recompile framework.swf from Adobe Flex Framework source files to take it’s size down in the first place, prior to resorting to –include.

Keep it small.

Victor

Preventing the user from closing the browser window has been traditionally done via onbeforeunload event.
Here is the snippet of JavaScript code, which, once you put it in
./html-template/index.template.html will (IE & Mozilla)

1. resolve reference to Flash control;
2. tentatively invoke ActionScript method getUnsavedDataWarning() ;
3. force browser to popup the alert “Are you sure you want to navigate away? ….. OK/Cancel”; with your custom text in the middle:

<!– index.template.html –>
. . . . .
<script language=”JavaScript” type=”text/javascript”>
<!–
// Give user a chance to save modified data
window.onbeforeunload = function() {
var warning=”";
var fxControl = document.${application} || window.${application};
if (typeof fxControl.getUnsavedDataWarning==”function”) {
warning = fxControl.getUnsavedDataWarning();
}
if (warning!=”)
return warning;
else
return;
}
// –>
</script>
Now, all of this is in vain, of course, if your Flex application does not advertise the method
getUnsavedDataWarning(). And here is where Flash ExternalInterface API comes very handy. You can
expose any method: static, instance or anonymous, like the one below:

import flash.external.ExternalInterface;

private const UNSAVED_DATA_WARNING:String = ‘You have unsaved changes. You will lose them if you continue.’;

if ( ExternalInterface.available ) {
ExternalInterface.addCallback(
“getUnsavedDataWarning”,
function():String {
if (commitRequired) return UNSAVED_DATA_WARNING;
else return ”;
}
);
}

The complete MXML application is listed below. Do not forget to paste the JavaScript stuff in ./html-template/index.template.html:

<?xml version=”1.0″ encoding=”utf-8″?>
<mx:Application xmlns:mx=”http://www.adobe.com/2006/mxml”
layout=”vertical” creationComplete=”onCreationComplete()”>
<mx:Script><![CDATA[

import flash.external.ExternalInterface;
private const UNSAVED_DATA_WARNING:String = 'You have unsaved changes. You will lose them if you continue.';
[Bindable] private var commitRequired:Boolean;

private function onCreationComplete():void {
if ( ExternalInterface.available ) {
ExternalInterface.addCallback(
“getUnsavedDataWarning”,
function():String {
if (commitRequired) return UNSAVED_DATA_WARNING;
else return ”;
}
);
}
}
]]></mx:Script>
<mx:Text text=”Type something below to test” />
<mx:TextInput id=”input” change=”commitRequired=(input.text!=”)”/>
<mx:Text text=”Close window and you will{commitRequired?’ ‘:’ not’} be prompted” />

</mx:Application>

WM_CLOSE, windowClosing, closeQuery, onbeforeunload… Tell me who your friends are … ; )

Victor

private var usStates:Array=[
    {label:"New York", data:"NY"},
    {Colorado", data:"CO"},
    {Texas", data:"TX"}
];
. . . . . . . .
   <mx:ComboBox id=”cbx_states” dataProvider=”{usStates}”/>To force Texas to the visible portion of the ComboBox you can write the following index-fetching loop, comparing val against the label of each element of dataProvider:

var val:String; val= ’Texas’ ;
for (var i: int = 0; i < cbx.dataProdider.length; i++) {
    if ( val == cbx_states.dataProvider[i].label) {
      cbx_states.selectedIndex = i;
      break;
  }
}

Alternatively, you could look up the data of dataProvider’s elements :
var val:String; val= ‘TX’ ;
for (var i: int = 0; i < cbx.dataProdider.length; i++) {
    if ( val == cbx.dataProvider[i].data) {
      cbx_states.selectedIndex = i;
      break;
    }
}

Either way these index-fetching loops will clutter the application code instead of simple cbx_states.value=‘Texas’. But wait, there is value property: if a selected object has something in the data property, value refers to data, otherwise value refers to the label:mx.control.Alert.show(cbx_states.value); // displays ‘NY’

Alas, standard value is read-only. In the following part of the post we will turn value into a read-write property. Then index-fetching loops to modify the ComboBox selection will be history.

Let’s extend the original ComboBox so that derived class provides a special setter for the value property. The setter attempts to match the value with either data or label properties of the dataProvider. Once a match is found, it modifies the selectedIndex, which should cause the ComboBox to select the matching object:

<?xml version=”1.0″ encoding=”utf-8?>
<mx:ComboBox xmlns:mx=”http://www.adobe.com/2006/mxml” >
<mx:Script>
<![CDATA[
   public function set value(val:Object) : void {
    if ( val != null ) {
    for (var i : int = 0; i < dataProvider.length; i++) {
    if ( val == dataProvider[i].data || val == dataProvider[i].label) {
    selectedIndex = i;
    return;
    } } }
    selectedIndex = -1;
    }
 ]]>
<mx:Script>
<mx:ComboBox>

Listing 1. ComboBox.mxml – Making the value property writeable

If the ComboBox.mxml is located under the com/theriabook/controls, its test application can look as in Listing 2 below.

<?xml version=”1.0″ encoding=”utf-8″?>
<mx:Application xmlns:mx=”http://www.adobe.com/2006/mxml” xmlns:fx=”com.theriabook.controls.*”>
   <mx:ArrayCollection id=”comboData”>
       <mx:Array>
           <mx:Object label=”New York” data=”NY”/>
           <mx:Object label=”Connecticut” data=”CT”/>
           <mx:Object label=”Illinois” data=”IL”/>
       </mx:Array>
   </mx:ArrayCollection>
   <mx:Label text=”Current bound value is ‘{cbx_1.value}’ ” />
   <fx:ComboBox id=”cbx_1″ value=”IL” width=”150″ dataProvider=”{comboData}”/>
<mx:Application>

Listing 2. Using our new ComboBox

Run this application, and you’ll see the ComboBox displaying the value New York… while we would expect Illinois. We forgot about the order in which objects’ properties (cbx_1) get initialized. In particular, the value property is initialized before the dataProvider. And, since during dataProvider initialization ComboBox, by default, selects the first item, the work performed by our value setter is wasted. You can prove the point by just trading places of value and dataProvider in the above application code.

Should I rely on the order of attributes in MXML components? Apparently not. Especially when Flex offers an excellent mechanism to coordinate the updates to multiple properties of the control – the commitProperties() method.

Here is how it works: whenever you need to modify a property raise some indicator, store the value in the temporary variable and call invalidateProperties(), like in the following snippet:

 private var candidateValue:Object;
 private var valueDirty:Boolean = false; public function set value(val:Object) : void {
   candidateValue = val;
   valueDirty = true;
   invalidateProperties();
   }

In response to invalidateProperties() Flex will guarantee a call of commitProperties() at a later time, so that all property changes deferred in the above manner can be consolidated in a single place and in the pre-determined order:

override protected function commitProperties():void {
    super.commitProperties();      if (dataProviderDirty) {
      super.dataProvider = candidateDataProvider;
      dataProviderDirty = false;
   }

Aside of co-ordinating updates to different properties, this coding pattern helps to avoid multiple updates to the same property and, in general, allows setter methods to return faster, improving the overall performance of the control. The entire code of our “value-aware” ComboBox is presented in Listing 3:

<?xml version=”1.0″ encoding=”utf-8″?>
<mx:ComboBox xmlns:mx=”http://www.adobe.com/2006/mxml”>
<mx:Script>
<![DATA[

Listing 3. The value-aware ComboBox

Now everything works as expected. If you change the ComboBox selection, the top label, which initially contains Current bound value is “IL” will change accordingly. No miracles here, a regular Flex data binding one would say. Indeed, good things are easy to take for granted. Still, we have not provided any binding declarations or binding code in our ComboBox. So why does it work? It works because the original Flex definition of value getter ComboBox has already been marked with metadata tag [“Bindable”], which makes the property bindable (you do not have to have a setter to be bindable):

[Bindable("change")]
[Bindable("valueCommitted")]

But wait, you may say, these binding definitions contract us to trigger events change and valueCommitted. Yet our value setter does not contain a single dispatchEvent call. Where is the catch? Events are dispatched inside the code that assigns selectedIndex. This assignment results in invocation of selectedIndex setter, which ultimately dispatches events.

Remember, Flex is a framework.Read the code

Victor

The easiest way to row-by-row disable editing is via itemEditBeginning event:

 mx:DataGrid itemBeginning=”onItemEditBeginning(event)” …

 public function onItemEditBeginning(event:DataGridEvent):void {
  if (event.itemRenderer) {
  // do something to determine whether item is editable, preventDefault otherwise
 }
}

Now let’s fantasize that items populating your dataProvider might be implementing IEditableItem, which mandates method isFieldEditable():

 function isFieldEditable(dataField:String):Boolean;

Then you can write something like

Variant1:
 var item:Object = event.itemRenderer.data ;
 if (item is IEditableItem) {
  if (!item.isFieldEditable(dataField)) {
   event.preventDefault();
  }
 }

OR – Variant2:
 var item:Object = event.itemRenderer.data ;
  if (item is IEditableItem) {
    if (!IEditableItem(item).isFieldEditable(dataField)) {
     event.preventDefault();
    }
  }

OR – Variant3:
 var item:IEditableItem = event.itemRenderer.data as IEditableItem;
 if (item) {
  if (!item.isFieldEditable(dataField)) {
     event.preventDefault();
  }
 }
Variant1 looks simple, but may cost you some sleep when another developer redefines IEditableItem, which won’t be discovered during compilation. Variant2 applies regular casting to take care of that potential re-factoring and … gets annoying with IEditableItem/IEditableItem. Variant 3 combines clarity of 1 with reliability of 3: when item is not IEditableItem “as” casting returns null, otherwise we are already strongly typed. Call it hair splitting and I won’t argue much. After all, this does the job too:

 if (typeof item["isFieldEditable"]==”function”) {
  if (!item["isFieldEditable"](dataField)) {
   event.preventDefault();
  }
 }

Victor

What’s cool in this release? We now support complete data synchronization via Flex Remoting. Here is how: we’ve created a ActionScript class DataCollection that descends from ArrayCollection, but it is “destination-aware” and has its own methods fill() and sync(). DataCollection knows how many elements have been modified, created, deleted, etc. and can manipulate them freely.

ActionScript class BatchService allows sending updates done to multiple DataCollections in our batch. We wrote a small BatchGateway destination which applies such batch as a unit of work (JTA transaction). More, you can batch arbitrary remote calls, say invoking a stored procedure in the same transaction. And watch this: you can do this without writing a single line in Java, except defining annotated abstract classes.

So now you can use Flex Remoting for your data synchronization with back-end on par with Flex Data Services. These technologies are complementary to each other. Use Flex Data Services when you need the server push and pagination. For all other use cases Remoting is sufficient. Classes generated by daoFlex are universal for either solution. You take the side, we will supply the ammo

If you are in Vegas this week, I’ll be showing it in action at MAXUP.

Victor Rasputnis

public static function calcTax(… taxParams):Number{
for (uint i=0; i< taxParams.length; i++){
trace(taxParams[i]);
}
}

Java programmers may find the … (rest) similar to the varargs notation. You can mix the … (rest) with other function parameters as long as it’s the last parameter listed.

Unless you use the rest parameter, AS3 creates in memory a special object called arguments, which is an array that include references to each of the arguments and a reference to function itself (arguments.callee). AS3 allows you to call a function with more parameters than were included in the function declaration, and each of the parameters can be access by using the arguments[i] notation.

Here’s an idea of using … (rest) parameter to overcome the absence of overloaded constructors in AS3:

public function MyCLass(…args) {
switch (args.length) {
case 0: constructor1(); return;
case 1: constructor2(args[0]); return;
case 2: constructor3(args[0], args[1]); return;
…
} }

This sample covers the case of constructors having different number of parameters. But if you want this solution to work with functions having the same number of parameters but different types, you’d need to add the type check to each of these cases above, i.e.

if(args[0] is String) {
//do one thing
}else if (args[0] is Number){
// do another thing
}