mxml.it

Flex and Jabber, a practical approach

Giorgio Natili — Fri, 07 May 2010 17:22:01 +0000

The widely adopted open protocol for instant messaging XMPP (also called Jabber) is a de facto standard used in various instant messaging systems. The aim of this article is to show how quick and easy it is to create a real time application using this protocol that relies on a restful architecture.

In order to start playing with Flex and the XMPP protocol you have to select the server you prefer and install it.
My choice is Open Fire (http://www.igniterealtime.org/), and the main reasons for this choice are:

•    It’s fully compliant to the standards
•    It’s very easy to install
•    It can work with several databases in addition to the built-in one (it supports MySQL, PostgressSQL, Oracle, SQLServer and IBM DB2)
•    It can interact with OpenLDAP and / or Active Directory
•    It can track all the IM traffic and store it as XML files
•    It has a great log panel
•    It can easily administer chats and rooms
•    Options allow control over room moderation, maximum occupancy, presence information, and more
•    There is a good ActionScript library that can interact with Open Fire

In order to setup your environment you have to follow the wizard provided with the Open Fire installer (I suggest you keep in place the built-in database and the default settings) and then you can login on your localhost to the administrative console.
Create a new Flex project with you favorite IDE and add the XIFF library (http://www.igniterealtime.org/downloads/download-landing.jsp?file=xiff/xiff_3_0_0-beta1.zip) to the project.
As you can see the XIFF library is very rich and it supports more or less all the features of the XMPP protocol.
In a project I worked on, some of the junior developers’ first reactions to the XIFF library and to the restful architecture you can get with the XMPP protocol was to interrupt development in order to study all the protocols and servers we were using for the project.
This reaction led me to write down a “driver” that can deal with the XIFF library and the XMPP protocol in order to avoid any panic in the development team and to prevent people from wasting time on a concept that was beyond the scope of the project itself.
Let’s think of this driver as a layer component that hides the complexity and the richness of the XIFF library to make things easier.
In order to show you how it works I created a very simple application with the following features:

•    Anonymous and registered login
•    Chat services discovery
•    Personal chat room creation and destruction
•    Room user list
•    Friends request support (accept and deny)
•    Messages broadcast

The user interface of this demo is quite simple and easy to understand, take a look to it on-line.

The driver is made up of several classes, events and value objects but it’s really simple to use because the two most important files you have to know are two interfaces and a class used to discover the available services

•    IRealTime
•    ServiceBrowser
•    IChatControls

The first one is responsible for the connection to the XMPP server and for the initialization of communication between client and server.
Available methods are:

•    init(port:int, resource:String):void;
// initialize the connection over a specific port and
// send the appropriate resource type the XIFF library
•    connect(domain:String, anonymous:Boolean, user:User = null):void;
// connect to a specific domain using anonymous login or an User object that is made up by username and password
•    disconnect():void;
// self explanatory
•    keepAlive(live:Boolean):void;
// keep the connection with the server alive also
// after long period of inactivity
•    connection():XMPPConnection
// return the established connection instance
•    startRealtime(room:OpenFireRoomEssentials):void
// create or join an existing room

The class that implements this interface is the RealtimeManager, each instance of which can dispatch some events. To keep things simple, the class actually wraps some events defined in the XIFF library using a custom event class. Dispatched events are:

•    UserAccessEvent.CONNECTED
•    UserAccessEvent.LOGIN
•    UserAccessEvent.LOGOUT

The ServiceBrowser class is responsible for discovering chat services, the rooms defined on each service and the details of each room.
All information is made available through a series of events. Events dispatched from the ServiceBrowser class are:

•    AvailableRoomsEvent
•    AvailableServicesEvents
•    DetailRoomEvent

Each event provides information about the services available on the server, the rooms that are active on a specific service and the detail of a specific room (needed in order to launch the realTime method).

The last interface you should know about is the IChatControls. Methods defined by this interface are:

•    updatePresence( show:String, status:String ):void;
// send to the roster the user status
•    joinRoom(room:Room, jid:UnescapedJID):void;
// join a specific room and using the JID initialize the loading of the roster
// and the set up of the room
•    isValidJID( jid:UnescapedJID):Boolean;
// check if the JID is valid or not
•    sendMessage(message:String = null, html:String = null):void;
// send a message in the joined room, it supports both html and plain text
•    sendMessageTo(text:String, tojid:EscapedJID):void;
// send a message to a specific user
•    createRoom(room:Room):void;
// create a personal room
•    destroyRoom(room:Room, reason:String = null):void;
// destroy the personal room the user has created
•    leave():void;
// allow the user to leave the current room
•    invite(userId:EscapedJID):void;
// invite a specific to the personal room
•    addFriend(user:RoomOccupant):void;
// add an user as a friends to the user roster
•    removeFriend( user:RosterItemVO ):void;
// remove a specific user from the friends list
•    grantSubscription(id:UnescapedJID, status:Boolean = true):void;
// grant to an user the request of subscription to the friends list
•    denySubscription(id:UnescapedJID):void;
// deny the subscription to a specific user
•    personalRoom():Room;
// recover the personal room created by the user
•    dispose();
// free the memory and the event listener

The class that implements this interface is the ChatManager, which can dispatch events in order to distribute the data recovered and managed internally, and the events are:

•    FriendsInvitation.FRIEND_REQUEST_INCOMING
•    FriendsEvent.LIST_RECOVERED
•    FriendsInvitation.FRIEND_REQUEST_DENIED
•    FriendsInvitation.FRIEND_REQUEST_ACCETPED
•    FriendsInvitation.FRIEND_LIST_REMOVED
•    ChatMessageEvent.GROUP_MESSAGE
•    PersonalRoomEvent.ROOM_DESTROYED
•    RoomUsersEvent.JOINED
•    RoomUsersEvent.LEFT
•    RoomUsersEvent.PRESENCE

As in the case of the RealtimeManager class, these events wrap some events defined in the XIFF library in order to keep things a little bit simpler and to prevent concepts like rosters, persistent rooms, etc. from becoming a problem during development.

Now you know everything you need to start using this driver that keeps things simpler and easier to understand.
Come back for one moment to the image that shows the user interface of our application, and let’s examine what we have to do to make it work.
In order to set up our application we have to put in place the following workflow:

•    Create an instance of the IChatControls interface implementer
•    Create an instance of the IRealTime interface implementer
•    Define the listeners for the UserAccessEvent.LOGIN event
•    Create an instance of the ServiceBrowser class in the UserAccessEvent.LOGIN handler and recover the services available through the currentServices() method
•    Handle through the user interface the data propagated through the events of the ServiceBrowser class
•    Invoke the joinRoom() method of the IChatControls interface implementer

Create a new Flex application, add the XIFF library to your libs folder and grab the source code of the driver you can get here www.mxml.it/tutorials/xiffdriver.zip.
First of all, define the user interface in the main MXML file of the project

Next, open a script tag and define the constants used inside the application:

private const SERVER_DEFAULT:String = "wip.gnstudio.com";
private const PERSONAL_ROOMS_SERVICE:String = "conference";
private const PERSONAL_ROOM_SUFFIX:String = "presenter";

The first one represents the address of your Open Fire installation, the second is the name of the service on which personal rooms will be created and the third is the suffix that will be added to all personal room names.

Create the class members you need to store an instance of the 3 main actors of the application

private var realtimeManager:IRealtime;
private var chatManager:IChatControls;
private var serviceBrowser:ServiceBrowser;

and the class members needed to store the details of the room the user is going to join, the unique identifier provided by the XMPP server (inject this in the chat manager to perform all operations related to a user) and the unique identifier of the user that performs a friend request

private var roomDetailsInfo:OpenFireRoomEssentials;
private var currentRequestId:UnescapedJID;
private var unescapedJID:UnescapedJID;

In order to start playing with the driver classes, perform the override of the childrenCreated method and define here both instances of the IRealTime implementer and of the IChatControls implement and the event handlers needed to manage the data propagated from these classes

override protected function childrenCreated():void {

super.childrenCreated();

connectionType = "ANONYMOUS";

chatManager = new ChatManager();
chatManager.addEventListener(RoomUsersEvent.JOINED, onRoomJoin);
chatManager.addEventListener(RoomUsersEvent.LEFT, onRoomLeft);
chatManager.addEventListener(RoomUsersEvent.PRESENCE, onRoomPresence);
chatManager.addEventListener(FriendsEvent.LIST_RECOVERED, onFriendsList);
chatManager.addEventListener(ChatMessageEvent.GROUP_MESSAGE, onGroupMessageReceived);
chatManager.addEventListener(FriendsInvitation.FRIEND_ADD_NOT_SUPPORTED, onFriendsNotSupported);
chatManager.addEventListener(FriendsInvitation.FRIEND_REQUEST_INCOMING, onFriendsRequest);
chatManager.addEventListener(FriendsInvitation.FRIEND_REQUEST_DENIED, onFriendsRequestDenied);
chatManager.addEventListener(FriendsInvitation.FRIEND_REQUEST_ACCETPED, onFriendsRequestAccepted);
chatManager.addEventListener(FriendsInvitation.FRIEND_LIST_REMOVED, onFriendsListRemoved);
chatManager.addEventListener(PersonalRoomEvent.ROOM_CREATED, onPersonalRoomCreated);
chatManager.addEventListener(PersonalRoomEvent.ROOM_EXISTS, onPersonalRoomExists);
chatManager.addEventListener(PersonalRoomEvent.ROOM_DESTROYED, onPersonalRoomDestroyed);

realtimeManager = new RealtimeManager();
realtimeManager.init(5222, "xiff");

realtimeManager.addEventListener(UserAccessEvent.LOGIN, onUserLogin);
realtimeManager.addEventListener(OpenFireErrorsEvent.ERROR, onOpenFireError);

}

Let’s start exploring one by one all the methods registered as listeners in the childrenCreated method.
The onRoomJoin listener handles the UI, enabling it after user login

private function onRoomJoin(e:RoomUsersEvent):void {

usersList.enabled = userStatus.enabled = roller.enabled = msg.enabled = send.enabled = friendsList.enabled = true;
requestsLog.enabled = accept.enabled = requestFrom.enabled = deny.enabled = true;
removeFriend.enabled = this.addFriend.enabled = true;

usersList.dataProvider = e.usersList;

}

The onRoomLeft method handles the UI, disabling controls after the user has left a room

private function onRoomLeft(e:RoomUsersEvent):void {

usersList.enabled = userStatus.enabled = roller.enabled = msg.enabled = send.enabled = friendsList.enabled = false;
requestsLog.enabled = accept.enabled = requestFrom.enabled = deny.enabled = false;
removeFriend.enabled = this.addFriend.enabled = false;

usersList.dataProvider = null;
friendsList.dataProvider = null;

}

The onRoomPresence method is the handler used to get the status of a specific user, in this sample it simply shows some logs, in a real implementation this is the method in which you have to update the status of a specific user in the room user list

private function onRoomPresence(e:RoomUsersEvent):void {

trace("Current user", e.userData.jid, "status:", e.userData.show, e.userData.status)

}

The onFriendsList method is responsible for populating the list of friends (i.e. the roster)

private function onFriendsList(e:FriendsEvent):void {

friendsList.dataProvider = e.freindsList;

}

the onGroupMessageReceived method handles all messages sent against the ‘general’ chat

private function onGroupMessageReceived(e:ChatMessageEvent):void {

roller.text += "[" + e.from + " @ " + (e.lastMessage.time || "") + "]:" + e.lastPlainMessage + "\n";
callLater(scrollText, [roller]);

}

The onFriendsNotSupported method catches the notification that anonymous users cannot add another user to their friends list

private function onFriendsNotSupported(e:FriendsInvitation):void {

Alert.show("Chat not configured for friends support...", "Attention!");

}

The onFriendsRequest method handles friend requests that come from another user, storing that user’s unique identifier and updating the user interface controls

private function onFriendsRequest(e:FriendsInvitation):void {

currentRequestId = e.jid;
requestFrom.text = "Friend request from " + e.jid.bareJID + ", accept?\n";

}

The onFriendsRequestDenied method notifies the application that a friend request has been denied by another user

private function onFriendsRequestDenied(e:FriendsInvitation):void {

requestsLog.text += "Friend request from " + e.jid.bareJID + ", DENIED!!!!!!!!\n";
callLater(scrollText, [requestsLog]);

}

The onFriendsRequestAccepted method notifies the application that a friend request has been accepted

private function onFriendsRequestAccepted(e:FriendsInvitation):void {

requestsLog.text += "Friend request from " + e.jid.bareJID + ", accepted!!!!!!!!\n";
callLater(scrollText, [requestsLog]);

}

The onFriendsListRemoved method handles the event that notifies the application that a user has been removed from the friends list

private function onFriendsListRemoved(e:FriendsInvitation):void {

requestsLog.text += "Removed from " + e.jid.bareJID + ", friend list!!!!!!!!\n";
callLater(scrollText, [requestsLog]);

}

The onPersonalRoomCreated method simply gives an Alert to notify the application that the personal room has been created

private function onPersonalRoomCreated(e:PersonalRoomEvent):void {

Alert.show("Your personal room has been created....", "Attention!");

}

The onPersonalRoomExists method notifies the user that his personal room already exists and that another one cannot be created (this is not a limitation of XMPP but only a feature of the driver that doesn’t allow more than one personal room per user)

private function onPersonalRoomExists(e:PersonalRoomEvent):void {

Alert.show("Sorry, you can have only one personal room....", "Attention!");

}

The onPersonalRoomDestroyed method handles notifications that the personal room a user joined has been destroyed

private function onPersonalRoomDestroyed(e:PersonalRoomEvent):void {

Alert.show("Sorry, the room you are chatting has been destroyed....", "Attention!");

}

The onOpenFireError method handles all errors; in this sample implementation it handles only the 401 error code that means that a registered user has inserted wrong username and password

private function onOpenFireError(e:OpenFireErrorsEvent):void {

if (e.errorCode == 401) {

userID.text = "wrong credentials";

}

}

The on method handles anonymous or registered logins and initializes the ServiceBrowser instance and all the listeners needed to recover the information from this class. It’s important to note here that the realtimeManager instance is finally connected, that the keepAlive property is set to true and that the ServiceBrowser instance uses the connection to the server to start exploring available services

private function onUserLogin(e:UserAccessEvent):void {

userID.text = "logged as " + e.username;
unescapedJID = e.unescapedJID;

var serverJID:EscapedJID = new EscapedJID(e.unescapedJID.domain);

serviceBrowser = new ServiceBrowser(serverJID, realtimeManager.connection);
serviceBrowser.addEventListener(AvailableServicesEvents.SERVICES_RECOVERED, onAvailableServices);
serviceBrowser.addEventListener(AvailableRoomsEvent.ROOMS_RECOVERED, onAvailableRooms);
serviceBrowser.addEventListener(DetailRoomEvent.ROOM_DETAILS, onDetailRoom);

serviceBrowser.currentServices();

connectButton.enabled = false;
disconnectButton.enabled = true;

realtimeManager.keepAlive = true;

}

The listeners registered to the events dispatched from the ServiceBrowser are those that populate the controls of the user interface (i.e. the list of services and available rooms) and that store information about the room the user is going to join

private function onAvailableServices(e:AvailableServicesEvents):void {

e.target.removeEventListener(e.type, arguments.callee);

chatServices.dataProvider = e.currentServices;

}

private function onAvailableRooms(e:AvailableRoomsEvent):void {

persitenteChats.dataProvider = e.currentRooms;

}

private function onDetailRoom(e:DetailRoomEvent):void {

roomDetailsInfo = e.details;

}

All the building blocks needed to handle the real time communication provided through XMPP are now in place. The following code list includes all the methods called from the user interface and it’s self-explanatory: you will now be able to run the application against your Open Fire installation

private function handleRequest(status:Boolean):void {

if (status) {

chatManager.grantSubscription(currentRequestId, true);

} else {

chatManager.denySubscription(currentRequestId);

}

currentRequestId = null;

}

private function chatDetails(e:ListEvent):void {

var jid:EscapedJID = new EscapedJID(e.itemRenderer.data.jid);

serviceBrowser.roomDetails(jid)

}

private function recoverChats(e:ListEvent):void {

var jid:EscapedJID = new EscapedJID(e.itemRenderer.data.jid);

serviceBrowser.currentChatRooms(jid)

}

private function leaveRoom():void {

chatManager.leave()

}

private function joinRoom():void {

chatManager.joinRoom(realtimeManager.startRealtime(roomDetailsInfo), unescapedJID);

}

private function updateStatus(e:ListEvent):void {

var item:Object = e.currentTarget.selectedItem;

chatManager.updatePresence(item.label, item.data);

}

private function removeUserAsFriend():void {

chatManager.removeFriend(friendsList.selectedItem as RosterItemVO);

}

private function addUserAsFriend():void {

chatManager.addFriend(usersList.selectedItem as RoomOccupant);

}

private function handleMethodChange():void {

if (method.selectedItem.value != "ANONYMOUS") {

username.enabled = true;
password.enabled = true;

} else {

username.enabled = false;
password.enabled = false;

}

connectionType = method.selectedItem.value;

}

private function connect():void {

if (connectionType == "ANONYMOUS") {

realtimeManager.connect(server.text, true);

} else {

var user:User = new User();

user.username = username.text;
user.password = password.text;

realtimeManager.connect(server.text, false, user);

}

}

private function destroyTemporaryRoom():void {

if (chatManager.personalRoom) {

chatManager.destroyRoom(chatManager.personalRoom);

}

}

private function createTemporaryRoom():void {

var roomDetails:OpenFireRoomEssentials = new OpenFireRoomEssentials();
roomDetails.name = PERSONAL_ROOM_SUFFIX + roomName.text;
roomDetails.category = PERSONAL_ROOMS_SERVICE;

chatManager.createRoom(realtimeManager.startRealtime(roomDetails));

}

private function disconnect():void {

realtimeManager.disconnect();
chatManager.dispose();

connectButton.enabled = true;
disconnectButton.enabled = false;

chatServices.dataProvider = [];
persitenteChats.dataProvider = [];

usersList.enabled = userStatus.enabled = roller.enabled = msg.enabled = send.enabled = friendsList.enabled = false;
requestsLog.enabled = accept.enabled = requestFrom.enabled = deny.enabled = false;
removeFriend.enabled = removeFriend.enabled = false;

}

internal function scrollText():void {

arguments[0].verticalScrollPosition = roller.verticalScrollPosition + 8;

}

Conclusion
The real time applications are really engaging, both for the end user and for a developer. Sometimes people can be afraid of the potential difficulties in this kind of application but, as you have seen in this article, you don’t have to be a rocket scientist to be able to start playing with it.
The XMPP standard is not the only one available for the Flash Platform; the great advantage that comes with this standard is that you can handle several client side applications (developed with different technologies) with the same back end logic.

Reading Exif data with ActionScript 3.0

Giorgio Natili — Mon, 04 Jan 2010 01:23:46 +0000

Most of the digital cameras use Exif file format to store images and through this format tons of information is available so that each software that deals with images can show relevant data loading few bytes.
The nice thing is that in the first 64 kbytes of an image all the information, thumbnail included, are stored in separate and well organized image file directories (IFDs), this is the reason why you don’t need to load a complete image to show it’s preview (if images are smaller than 64kbytes you can get anyway the information and there is no need to close the stream of data).
There are already some resources about exif data reading in ActionScript, you can get some great examples here:

• http://code.shichiseki.jp/as3/ExifInfo/
• http://patrickshyu.com/2009/04/jpg-exif-metadata-in-actionscript-3/

I wrote my own solution because the first one load all the image before starting to parse the data, because the second one created me some issues with a Motorola image and because I get also information for exif 1.1 data.
What I’m missing and I would like to improve is the visualization of thumbnails stored not with the JPG information and the visualization of GPS information that I already get but are not shown properly.
In order to avoid the issues I have had I would like to spent few words before getting you to the source code.

First of all in order to understand the format I really started to read the specification you can get here http://www.exif.org/Exif2-2.PDF. I know that it may not seem the most amazing piece of paper to read but was the only way to put in place a solution with all the comments needed to make people able to extend and improve it.

My second step was to find a good software able to read exif data in order to make a comparison between the information recovered from the Exif class I created and the ones recovered from a professional software, I get ACDSEE (http://www.acdsee.com/).
The third step was to get a lot of sample images and thankfully the exif official web site has a lot of them (by the way I embedded the images also in the sample application I did) available here http://www.exif.org/samples.html.
The last step was to get an hexadecimal reader to really parse and count the raw data I was going to play with, on Mac I found 0xED (http://www.suavetech.com/0xed/0xed.html), on Windows I get Hex Workshop (http://www.hexworkshop.com/).
Before starting to write down my solution I studied how other people implemented working solutions in other languages, two of the most inspiring for me were this one in Java http://www.java2s.com/Open-Source/Java-Document/Web-Server/Jigsaw/org.w3c.tools.jpeg.htm and this one http://mediachest.sourceforge.net/mediautil/javadocs/mediautil/image/jpeg/package-summary.html always written in Java.

Let’s start with some clarifications …

The Exif file format is based on the JPEG file format. Exif inserts some of image / digital camera information and thumbnail image to JPEG in conformity to JPEG specification. Therefore you can view Exif formatted image files by JPEG compliant Internet browser / Picture viewer / Photo retouch software etc. as normal JPEG image files.
Every JPEG file starts from binary value ‘0xFFD8′, ends with binary value ‘0xFFD9′. There are several binary 0xFFXX data in JPEG data, they are known as ‘Marker’, and it starts a new part of JPEG information. 0xFFD8 means SOI (Start of image), 0xFFD9 means EOI (End of image). These two special Markers have no data following, the other markers have data with it.
The marker 0xFFE0~0xFFEF is named ‘Application Marker’, not necessary for decoding JPEG image. They are used by user application. For example, older olympus / canon / casio / agfa digital camera use JFIF (JPEG File Interchange Format) for storing images. JFIF uses APP0 (0xFFE0) marker for inserting digital camera configuration data and thumbnail image.
Exif format contains a thumbnail of the image (except Ricoh RDC-300Z). Usually it is located next to the IFD1. There are 3 formats for thumbnails; JPEG format (JPEG uses YCbCr), RGB TIFF format, YCbCr TIFF format. It seems that JPEG format and 160×120 pixels of size are recommended thumbnail format for Exif2.1 or later. By the DCF specification, thumbnail image MUST use JPEG format and image size is fixed to 160×120 pixels. If the value of Compression (0×0103) Tag in IFD1 is ‘6′, thumbnail image format is JPEG. Most of Exif image uses JPEG format for thumbnail. In that case, you can get offset of thumbnail from JpegIFOffset (0×0201) Tag in IFD1, size of thumbnail from JpegIFByteCount (0×0202) Tag. Data format is ordinary JPEG format, starts from 0xFFD8 and ends by 0xFFD9.
The following terms and notation are used as follows in the exif standard:

•    “Tag” is used as a synonym of “field”,
•    “.H” appended to a numerical value means it is hexadecimal notation,
•    Unless otherwise indicated, other numerical values are given in decimal notation,
•    The initial IFD in a file is the “0th IFD,” with the next IFD being called the 1st IFD
•    The term Primary image refers to main image data
•    The term Thumbnail indicates a small image used to index the primary image
•    Exif is an abbreviation of Exchangeable image file format, used here as the general term for this standard and earlier versions of this standard

The main class of this solution is named Exif and contains all the exif tag uint values as class constants and a bunch of methods used to expose the data to the end user (i.g. the developer that use it in a project) and other methods to parse the information

The class extends the URLStream class so what you have to do in order to use it is creating and instance and load a valid URLRequest through it.
The events dispatched from the Exif class you have to aware of are

•    PARSE_COMPLETE
•    PARSE_FAILED
•    PARSING_ERRORS
•    DATA_READY
•    THUMBNAIL_READY

The first one is fired when the data are parsed completely, the second one indicates that a serious error happened (i.g, not a valid jpg, not valid exif data, etc.), the third one can be used to handle not serious errors (i.g. a tag is not properly recorded), the fourth one indicates that the exif data have been completely parsed and the last one is the event that inform you that the thumbnail is ready.
The public API can be used in order to get the thumbnail, the error logs, all the IFD recovered from the class and the amount of data loaded in order to parse the exif data.

The class usage is quite simple but the logic inside is a little bit more complex, in fact the core consists of two methods

• exploreEntries
• parseTag

The first one is the one that read all the entries (i.g. tags) stored in an IFD and that collaborates with the parseTag method in order to read the data as defined in the exif specification and with the Naming class used to handle a lot of situations like flash, orientation, etc. making these values human readable.

The following types are used in Exif (you see this types recovered in the first lines of the exploreEntries method):

•    1 = BYTE An 8-bit unsigned integer.,
•    2 = ASCII An 8-bit byte containing one 7-bit ASCII code. The final byte is terminated with NULL.,
•    3 = SHORT A 16-bit (2-byte) unsigned integer,
•    4 = LONG A 32-bit (4-byte) unsigned integer,
•    5 = RATIONAL Two LONGs. The first LONG is the numerator and the second LONG expresses the
denominator.,
•    7 = UNDEFINED An 8-bit byte that can take any value depending on the field definition,
•    9 = SLONG A 32-bit (4-byte) signed integer (2’s complement notation),
•    10 = SRATIONAL Two SLONGs. The first SLONG is the numerator and the second SLONG is the
denominator.

The Naming class can be passed to the Exif class in the constructor so that you can easily create your localized version of exif reader overriding the methods that initialize some arrays used to store values for the flash, the orientation, the exposure, etc.

Each time and IFD is found in the file the exif class create an IFD instance so that you can easily keep track of them and create customized helper classes to parse all these information, each time a valid exif tag is defined an instance of the ExfTag class is created, thorugh this class you can easily know the name and the value of a tag, use the public getTagValue method passing as an argument one of the 130 and more constants defined in the Exif class.

All these classes are available inside nabiro, the open source ActionScript library made up of a lot of components created during our daily job published here http://agile.gnstudio.com/nabiro.

Sample Usage
At the end of this post you find the sample application with the source code include, byt the way in order to use this tool you only need to instantiate the class, define a couple of event listeners and load a file

exif = new Exif();

exif.addEventListener(Exif.PARSING_ERRORS, onParsingErrors);
exif.addEventListener(Exif.DATA_READY, onExifDataRecovered);
exif.addEventListener(Exif.THUMBNAIL_READY, onThumbnailReady);

exif.load(new URLRequest(images.selectedItem.data));

The three event listeners populate a text area with the error log message, display a list of available data and load the image, so you can easily get this result

Download here the source and the application and please feel free to use it as you want but please provide me as much as possible your feedback.

Flex image manipulation

Giorgio Natili — Wed, 07 Oct 2009 01:56:45 +0000

Image file formats are standardized means of organizing and storing images, let’s start to recap the building blocks of them in order to move faster in our flex applications.

Image file size (expressed as the number of bytes) increases with the number of pixels composing an image, and the color depth of the pixels and we use the words color depth or bit depth (usually a computer graphics term) in order to descibe the number of bits used to represent the color of a single pixel in a bitmapped image.

The color depths are summarized as following:

1-bit color (21 = 2 colors) monochrome, often black and white
2-bit color (22 = 4 colors) CGA, gray-scale early
3-bit color (23 = 8 colors) many early home computers with TV displays
4-bit color (24 = 16 colors) as used by EGA and by the least common denominator VGA standard at higher resolution
5-bit color (25 = 32 colors) Original Amiga chipset
6-bit color (26 = 64 colors) Original Amiga chipset
8-bit color (28 = 256 colors) most early color Unix workstations, VGA at low resolution, Super VGA, AGA, color Macintoshes.
12-bit color (212 = 4096 colors) some Silicon Graphics systems, Neo Geo, Color NeXTstation systems, and Amiga systems in HAM mode.
16-bit color (216 = 65536 colors) some color Macintoshes.

You can easily understand by the following images list (tanks to wikipedia) how much the color depth can impact the quality of your images.

There are two types of image file compression algorithms, lossless and lossy.

Lossless compression algorithms reduce file size without losing image quality, though they are not compressed into as small a file as a lossy compression file (when image quality is valued above file size, lossless algorithms are typically chosen).
Lossy compression algorithms take advantage of the inherent limitations of the human eye and discard invisible information, most lossy compression algorithms allow for variable quality levels (compression) and as these levels are increased, file size is reduced.

The most common image formats you can deal with in order to create image manipulation algorithms are: JPEG, TIFF, PNG and GIF.

JPEG (Joint Photographic Experts Group) files are (in most cases) a lossy format, the DOS filename extension is JPG (other operating systems may use JPEG).
Nearly every digital camera can save images in the JPEG format, which supports 8 bits per color (red, green, blue) for a 24-bit total, producing relatively small files so it’s usual that an application acquires images in this format.
JPEG files suffer generational degradation when repeatedly edited and saved are increased, file size is reduced so be careful to save too often the changes you do in your application.
The Exif (Exchangeable image file format) is an algorithm incorporated in the JPEG software used in most cameras, its purpose is to record and to standardize the exchange of data between digital cameras and editing and viewing software.The data is recorded for individual images and includes such things as camera settings, time and date, shutter speed, exposure, image size, compression, name of camera, color information, etc.
When images are viewed or edited by image editing software, all of this image information can be displayed and you can use them to create faster visualization tools.

The TIFF (Tagged Image File Format) is a flexible format that normally saves 8 bits or 16 bits per color (red, green, blue) for 24-bit and 48-bit totals, respectively, using either the TIFF or the TIF file extension. TIFFs compression algorithm are lossy and lossless and some offer relatively good lossless compression for bi-level (black & white) images.
The TIFF can handle device-specific color spaces, such as the CMYK defined by a particular set of printing press inks and for this reason is quite diffused in printing and in the photographer world.

The PNG (Portable Network Graphics) file format was created as the free, open-source successor to the GIF that supports true color (16 million colors) while the GIF supports only 256 colors.
The PNG file excels when the image has large, uniformly colored areas, the lossless PNG format is best suited for editing pictures, and the lossy formats, like JPG, are best for the final distribution of photographic images, because JPG files are smaller than PNG files.

The GIF (Graphics Interchange Format) format is limited to an 8-bit palette, or 256 colors, this makes the GIF format suitable for storing graphics with relatively few colors such as simple diagrams, shapes, logos and cartoon style images.
It uses a lossless compression that is more effective when large areas have a single color, and ineffective for detailed images or dithered images.

Each format has it’s own structure and in order to be able to manipulate images deeply you have to refer to each specific format, here is a list of all the file format specifications http://www.martinreddy.net/gfx/2d-hi.html.

You can consider the image manipulation process divided into two separate steps, the image transformation (rotation, zoom, vertical flip, mirroring, etc.) and the pixel manipulation.
In order to perform transformation the most efficient in Flex and in ActionScript is the affine geometry.

Affine geometry is a form of geometry featuring the unique parallel line property where the notion of angle is undefined and lengths cannot be compared in different directions, it is a generalization of Euclidean geometry characterized by slant and scale distortions.
Affine geometry can be developed in terms of the geometry of vectors, with or without the notion of coordinates, so an affine space is distinguished from a vector space of the same dimension by ‘forgetting’ the origin (sometimes known as free vectors).
Affine geometry can be seen as part of linear algebra, re-open your high school books and take a deep breath!

In linear algebra, linear transformations can be represented by matrices.
Matrices allow arbitrary linear transformations to be represented in a consistent format, suitable for computation (i.e. your transformation data are represented in a way that can be used with any software)…this also allows transformations to be concatenated easily (by multiplying their matrices).

For rotation by an angle θ clockwise about the origin, the functional form is x’ = xcosθ − ysinθ and y’ = xsinθ + ycosθ

Written in matrix form, this becomes

To represent affine transformations with matrices, we must use homogeneous coordinates, this means representing a 2-vector (x, y) as a 3-vector (x, y, 1), and similarly for higher dimensions.
All ordinary linear transformations are included in the set of affine transformations, and can be described as a simplified form of affine transformations hence, any linear transformation can be also represented by a general transformation matrix.

A matrix is a rectangular array (or table) of numbers consisting of any number of rows and columns it consists of m rows and n columns is known as an m x n matrix, this value represents the matrix’s dimensions.
You’ll commonly seen matrices with numbers in rows and columns surrounded by two large bracket symbols

Affine transformations are transformations that preserve collinearity and relative distancing in a transformed coordinate space, this means points on a line will remain in a line after an affine transformation is applied to the coordinate space in which that line exists.
It also means parallel lines remain parallel and that relative spacing or distancing, though it may scale, will always maintain at a consistent ratio.

Flash provides a 3 x 3 matrix in which u,v,w are sort of dummy here though their values remain as 0, 0, 1
You can manipulate the others properties (a,c,c,d,tx and ty) in order to get a transformation, following some examples

Translation: tx or ty changes would move either x pixels or y pixels
Scale: a or d changes would affect xScale or yScale
Skew: b or c changes skew either parallel to the x or y axis
Rotation: a,b,c and d changes affect the rotation (for an angle θ a is cos(θ ), b is sin(θ ), c is -sin(θ ) and d is cos(θ ))

The properties of the Matrix class in ActionScript are basically just a collection of your main a, b, c, d, tx, and ty properties those you need to be concerned about when dealing with transformations, additional methods are also provided to make working with these matrices easier.
Some of the more common methods are:

translate(tx:Number, ty:Number) : voidscale(sx:Number, sy:Number) : void

rotate(angle:Number) : void

identity() : void

Flash Player 10 expands greatly on the drawing API in ActionScript, more so than any other version of the Flash Player since the initial introduction of the drawing API in Flash Player 6
New features include:

Use of vectors (typed arrays) for improved throughput and use of memory
Support for non-zero winding rules
An API for drawing triangles with support for 3D perspective rendering
Drawing API data objects

The introduction of vectors help a lot developers to make more efficient and powerful transformations

Vectors are almost exactly like arrays at their core, having pretty much the same API

There are only a few real differences:

Elements within a vector all share the same type
Vectors have an additional property, fixed, which determines whether or not the length of the vector can change dynamically
The vector constructor allows for two optional arguments, length and fixed
There is no equivalent to the bracket ([]) array constructor

The Graphics class contains now the drawTriangles method

public function drawTriangles(vertices:Vector., indices:Vector.=null, uvtData:Vector.=null, culling:String="none");

This method uses a Vector. to specify point locations for a path to be drawn, only with drawTriangles, the commands internally are predefined to use the point locations to draw triangles (Every 3 points, i.e. 6 numbers, represents a triangle path to be drawn)

It seems now that we are starting to talk about 3D because 3D models (in the end) are represented by a collection of triangles in space this is a good starting point for the 3D… Why talking about 3D in Flash if we are dealing with images manipulation?

Trough triangle the transformations are now faster and accurate, affine transformations and the division in triangles of an image help you to get a better image manipulation procedure, see the demo to understand that the drawing mechanism is totally different (no cutting on the sides of the image as if you are working with the classic bitmap transformation.

Let’s start now with some building blocks you need in order to play with pixels and better understand the code that is contained in the luminance, gray scale, tint and red eye correction demos you’ll get at the end of this post.

In order to perform advanced manipulation on an image you need to start to play with the pixels of an image, ActionScript provides a lot of class to help you on this task, the most relevant are

Bitmap
BitmapData

The Bitmap class represents display objects that represent bitmap images data, These can be images that you load with the flash.display.Loader class, or they can be images that you create with the Bitmap() constructor.

The Bitmap() constructor allows you to create a Bitmap object that contains a reference to a BitmapData object.
After you create a Bitmap object, use the addChild() or addChildAt() method of the parent DisplayObjectContainer instance to place the bitmap on the display list.
I said “image data”, the BitmapData class let you play with this data (i.e. pixels).
You can use the methods of the BitmapData class to create arbitrarily sized transparent or opaque bitmap images and manipulate them in various ways at runtime.
This class lets you separate bitmap rendering operations from the internal display updating routines of Flash Player and moreover by manipulating a BitmapData object directly, you can create complex images without incurring the per-frame overhead of constantly redrawing the content from vector data.
Each 32-bit integer is a combination of four 8-bit channel values (from 0 to 255) that describe the alpha transparency and the red, green, and blue (ARGB) values of the pixel.
There is a complete list of all the method of the class in the ActionScript documemntation, I would like to point your attention on the histogram method added to the player 10 that computes a 256-value binary number histogram of a BitmapData object

histogram(hRect:Rectangle = null):Vector.>

This is one of the key to play with the luminance effect in Flex.
Trough the combination of different pixel manipulation methods you can get complex effects like luminance
Relative luminance follows the photometric definition of luminance, but with the values normalized to 1 or 100 for a reference white.
Like the photometric definition, it is related to the luminous flux density in a particular direction, which is radiant flux density weighted by the luminosity function of the CIE Standard Observer.
For RGB color spaces that use the ITU-R BT.709 primaries relative luminance can be calculated from linear RGB components:

Y = 0.2126 R + 0.7152 G + 0.0722 B

Let see the demos to see a lot of pixel manipulation in place, in order to get the source of the effects you see here please refer to the nabiro images packaging you can get here http://agile.gnstudio.com/nabiro.

Gray scale and tint component for flex http://www.mxml.it/samples/imagemanipulation/grayscale/NabiroGrayScale.html
Luminance effect and color channel manipulation in flex http://www.mxml.it/samples/imagemanipulation/luminance/NabiroLuminance.html
Red eyes correction in flex http://www.mxml.it/samples/imagemanipulation/redeye/RedEyeDemo.html

Code tuning techniques

Giorgio Natili — Sun, 04 Oct 2009 13:51:12 +0000

Code tuning techniquesCode tuning differs a lot from refactoring because it doesn’t always improve code readability, and changes that you make are not meant to improve the internal structure of a software.
If the changes performed in the code don’t degrade the code’s readability, we believe that you are refactoring rather than fine-tuning.

One of the practices most of the fine tuning papers recommend is to stop testing a condition when an answer is known; this means that it could be better to split a short circuit evaluation into two separate evaluations, but this is not true in the Flash Player, if you make a simple test like this


private function testShortCircuit():void{
var start:int;
start = getTimer();

for(var i:int = 0; i < 100000000; i++){

    if(i > 3000000 && i < 4000000){

        break;

    }

}

trace("Short circuit", (getTimer() - start))

start = getTimer();

for(var j:int = 0; j < 100000000; j++){

    if(j > 3000000){

        if(j < 4000000){

            break;

        }

    }

}

trace("Not short circuit", (getTimer() - start));

you’ll get a result that clearly shows that short circuit in the Flash Player is faster

Short circuit 307
Not short circuit 331

Arrange tests in the conditional statements by frequency, putting the most common case as the first condition to evaluate is a good strategy for increasing performance.

We strongly recommend grouping together loops that operate on the same set of elements, so that you can remove a loop and acquire a lot of speed processing.

When dealing with nested loops we recommend always putting the busiest loop in the inside and moving the one with fewest iterations to the outside.

There are many common mathematical operations that can be done faster than usual

Operation Faster solution

Math.floor(1.5);         int(1.5);
Math.ceil(1.5);          int(1.5) + 1;
Math.abs(value);         var test:Number = value < 0 ? value * -1 : value;
value / 2;               value >> 1
value * 2;               value << 1

If you need some values multiple times in a component / class and these values need to be calculated we suggest that you calculate them only once and put the in constants for faster access

private const SOME_VALUE:Number = Math.sqrt(Math.pow(Math.PI, 10));

If the calculation varies during the execution of the class we suggest putting it in a method and avoiding having multiple pieces of code for the same calculation duplicated in the code.

Other resources

http://www.adobe.com/devnet/flex/articles/client_perf.html

Using the Abstract Factory pattern with Flex

Giorgio Natili — Fri, 13 Feb 2009 06:21:33 +0000

Accordingly to the Gang of four the Abstract Factory pattern intent is to provide an interface for creating families of related or dependent objects without specifying their concrete classes.
This design pattern actually ensures that the patterns automatically get and use the correct object accordingly to the context in which the client is working.
There are many different situations in which this pattern can work, imagine for instance a system in which the drawing and printing method varies accordingly to the resolution supported by the system; the system has to use different drivers in different cases.
At a first glance you may be tempted to use two different switch case for the drawing and printing procedure in which your system reacts in a different way accordingly to the resolution but remember that switches may indicate the need of abstraction in your system and that it can bring your system to a combinatorial explosion (imagine to add new drivers for each different resolution and create and even more complex switch case).
A good way to solve this issue us to create a Factory that creates the appropriate object accordingly to the resolution supported by the system, in this way you avoid the combinatorial explosion I mentioned and you can keep the switches in a single place or even better accordingly to the language you are working on and to your code style you can avoid switches also in the factory.
We have talked since now about two possible families of objects to use, monitor and printer drivers. Give me a chance to introduce you to a more complex system, an e-commerce with a group of families related to the system payments

•    Credit Card
•    OnLine payment
•    Other payment

For each of these families you may have the need to define multiple objects when you system starts

•    Credit Card
o    Visa
o    American Express
o    Master Card
•    OnLine payment
o    Paypal
o    E-check
•    Other payment
o    Wire transfer
o    Check

and add even more objects when the system grows or when new payment methods will be released over the net.
In an e-commerce system you may also have the need to show to the user the appropriate payment system accordingly to his preferences, in order to increase the abstraction of your system you can define multiple Abstract classes and keep the system ignorant on which particular implementation is in use because the factories are the responsible to instantiate them.
Imagine the scenario I described an put it in an UML diagram

The application is composed by a form that contains a submit button and the form fields vary accordingly to the user preferences retrieved by the system.
The CheckOutFactory class is an abstract class that have two concrete implementations able to return to the client the UI needed for each payment (actually the MXML representation of the class). The PaymentContainer is a VBox with a property used to store a reference to the payment form created from the factory that implements an interface that defines two common methods of the payment forms

•    validateFields()
•    submit()

As you know ActionScript 3.0 doesn’t support abstract classes, so the CheckOutFactory simulates the abstraction of the class trough the use of an internal class in its constructor.
Another good way to implement the abstraction is the use of interfaces, this is the reason why I defined a common interface ICheckOut and two other interfaces (IOnlinePayment and ICreditCard) that extend the base interface and that will be implemented in the view of each payment form of the system.
Take a look to the class hierarchy in order to understand where we are and where we are going

The abstraction of the on-line and credit card payments is reached through the interfaces put on the top of the onLinePayment and creditCardPayment packaging, the view and it’s logic has been keep separated through the Model View Presenter pattern used from each payment form.
Each presenter implements a public submit() method, in this way you can call in a centralized fashioned way the submit of each form trough the PaymentContainer property named element, each presenter will have the responsibility to recover the data from the view and each view, due to the fact that implements the ICheckOut interface, validate it’s fields (a good idea is to validate each credit card with a different Validator, this is the reason why you find an instance of the CreditCardValidator class in the credit card payment forms.
In order to run this sample (view source enabled) I created an XML file that stores the name of some users and the payment preferences, each node has the following structure

In the main application a combo box is populated with this data and each time you change the selection a concrete factory is created and through the factory a new view is added to the PaymentContainer

private function onUserSelection(e:Event):void{
checkOutFactory = CheckOutFactory.getPaymentFacotry(e.target.selectedItem.@mode);
var s:String = e.target.selectedItem.@type;
checkOutModule = checkOutFactory.getUI(s.substr(0, 1).toLocaleLowerCase() + s.substring(1, s.length) + ".view." + s + "View");
paymentContainer.element = checkOutModule;
}

The checkOutFactory and the checkOutMopdule properties data type represents the layer of abstraction I’m searching for
private var checkOutFactory:CheckOutFactory;
private var checkOutModule:ICheckOut;
The method defined as a listener for the click event inside the PaymentContainer uses the methods defined in the ICheckOut interface to complete his task

private function doSubmit():void{
if(_element.validateData()){
_element.submit();
}else{
Alert.show("Invalid data in the form...", "Attention!");
}
}

At the end of the day we have a quite flexible sample, but which are the benefits of this pattern? It would be simpler to have a switch instead of all this code?
The main benefit is that if you have to add the support for another credit card you have to deal only with the logic stored in the MVP triad you need to add a payment form and the system automatically will be able to handle the new form.
The switch could be hard to maintain in a situation with more than 4 payment methods, moreover the abstraction layer that the system has reached give to you the flexibility to put each developer you want on the new payment forms the system needs without having to explain to the developer anything about the system itself.

There are other possible contexts in which the Abstract Factory pattern can be used

•    Handle different operating systems API in a cross platform application
•    Different traits for users of an application
•    Different version of an application
•    Different performance guidelines

At the end of the day we can recap with the following points the Abstract Factory pattern

•    You want to have families or sets of objects for particular clients
•    Families of related objects have to be instantiated
•    You want to coordinate the creation of families of objects
•    You need to isolates the rules of which objects are to be made

Obviously this is only a small sample and more complex implementation are out of the scope of this blog entry, so feel free to open a discussion on this topic.

Using the Strategy pattern with ActionScript 3.0

Giorgio Natili — Wed, 11 Feb 2009 12:27:25 +0000

Accordingly to the Gang of four the Strategy pattern intent is to define a family of algorithms an make them interchangeable; the pattern let the algorithm vary independently from the client that use it.
It seems to me a very nice idea because I believe that a good developer have to write his code in an “open way”. What I mean is that if your code it’s full of if statements, conditionals, etc. each change became very difficult to introduce and maintain.
The Strategy pattern can be roughly summarized like in the following UML diagram

The context is your application or a component in your application, the strategy may be a class or a method that define which algorithm your system can use, the concrete strategies are the classes that implements the algorithm that suits the needs of your system.
One of the most sample and concrete samples of the application of the Strategy pattern is the calculation of taxes inside an e-commerce application.
Imagine the situation in which your application has to deliver products all around the world and to apply different taxes factor accordingly to the country your customer lives, this means to use a different algorithm (a strategy) for each country.
We need to define a strategy and apply a different tax factor for each country, so model your system with the following classes and interfaces
1.    Calculator: an abstract class that implements the main algorithm
2.    ENTaxCalculator: the class that changes the algorithm in order to apply the right amount of taxes for the English customers
3.    ITTaxCaclulator: the class that changes the algorithm in order to apply the right amount of taxes for the English customers
4.    ITaxCaclulator: the interface that defines the common operations of the strategy and that you can use in your system as the algorithm data type and that it’s implemented by all the strategies

Let’s take a look to the implementation…
First of all in order to avoid the instantiation of your abstract Calculator defines an internal class in the same Calculator.as file and use it in the constructor

package it.mxml.utilities.taxes{
public class Calculator implements ITaxCalculator{
protected var _amount:Number;
protected var _taxesFactor:Number;
public function Calculator(enforcer:AbstractEnforcer){
if (enforcer == null){
throw new Error("AbstractException");
}
}
protected static function getAccess():AbstractEnforcer{
return new AbstractEnforcer();
}
}
internal class AbstractEnforcer{
// Do nothing
}

Now you are ready to define your algorithms extending this class Calculator and changing in the constructor the _taxesFactor value (for brevity I removed from here the methods used for calculation but you can get them in the source code of the sample you find here).
Imagine to have in your application a small basket and a method that calculate the taxes to apply, you can create the instance of the appropriate tax calculator through reflection and show the result

private function doCalculate():void{
var lang:String = Capabilities.language.toUpperCase();
var amount:Number = 0;
for each (var item:Object in selectedItems){
amount += item.price;
}
var calculator:ITaxCalculator;
var ClassDefinition:Class;
try{
ClassDefinition = getDefinitionByName("it.mxml.utilities.taxes." + lang + "TaxCalculator") as Class;
}catch(e:Error){
ClassDefinition = getDefinitionByName("it.mxml.utilities.taxes.DefaulTaxCalculator") as Class;
}
}

In the complete sample application you find here you can get also the output of this method.
At the end of the day we can recap with the following points the Strategy pattern
1.    Define a family of algorithms (with an abstract class) in order to solve a particular issue of your system
2.    Define the single algorithms making them interchangeable (use an interface)
3.    Define a procedure that is able to detect automatically the con text and which strategy to use (the appropriate algorithm)
4.    Keep separate the algorithm definition / implementation and the selection of an algorithm

Obviously this is only a Mickey Mouse sample, but following this building blocks you can define great strategies for your system.

Building blocks of agile modeling

Giorgio Natili — Thu, 15 Jan 2009 19:06:11 +0000

I have heard tons of time the term agile modeling from other developers both in my team and in other teams, with this small article I don’t want to create a reference for the agile modeling process (there are already a lot of resources on-line) but I want to point your attention to some terms and to the procedure I’m used to use during the development of Flex projects.
One of the main issues during the live cycle of a project is the communication between the customer and the development team, what you need is an easy and agile way to define the functionalities of the software that enables the two teams to understand the goals of the project and eventually to change the scope of the features planned for each release.
In order to avoid a situation in which the customer and his team make one all-encompassing set of decision at the beginning of the project you can start to use stories and spread the decision making across the duration of the project.
An user story describe in a very short way a functionality that will be valuable for the customer using a jargon that is not too much technical, moreover a story can be used to track the activity of the development team and to keep track about the conversation between the two main actors of a software development project: the customer team and the development team.
Traditionally the stories are hand written and pointed on a dashboard, so the use of stories is not a way to document a project but a way to represent customer requirements in a very informal way.
In order to write a story that can be useful for the project you have to avoid to put technical statement inside the story, the reason why is that the technology stuffs are related to developers only.
Imagine the simple scenario in which you have to describe the login form of an application, you can put in place these stories

    User can login in the system

    User can recover his password

    User can cancel the login process

    Login form will connect the data base

The first three stories represent a good example, the last one not because this is something that the application need to do but not something that can be clear for the two actors of the development process, move this in the technical specification that will be based on the stories or remove it completely because is quite obvious that some server side interactions are needed in order to run an application.
The key point here is that stories have to be written in a way that customer can evaluate them, project managers can understand them and developers can easily provide information about the time they need to implement the feature.
Sometimes stories are not so simple, imagine if you have to write down stories for a research form in which the user can select multiple and sometimes complex criterion, the functionalities the user can use may be represented with more than a story (remember that stories have to be short), in this scenario you can group them under an epic; an epic can be split into two or more stories (actually I suggest to keep 10 as the maximum number of stories under each epic).
Don’t incur in the mistake to split stories in too much epic and stories until you are able get a story that define all the details, details are a task for the technical specifications that usually (but not always) come after the customer and the development team have complete the stories / epics exercise.
When one of the team need to discuss some details add a note to the story inside the story itself

    User can search for a piece of inventory

        A piece of inventory can be searched accordingly to the price

        A piece of inventory can be searched accordingly to the location
            note: show the location selection

but keep the note as a part of the story itself and if you discuss the story with one of the two teams add relevant information as part of the note.
When you have a story completed you can also add some information about how to test the story, in the real world you can do it writing the tests on the back of the card, otherwise if you use some web application 99% you this option. If you are using another tool you can put the test in a box connected to the story and use the green as the color background.
In order to plan a release with the customer you can put a set of story in a pile (also an Excel file is good enough) in which the stories priority is based on the pile order and use the estimation for the delivery that each developer put on a story in order to understand when the release can be deployed.
If the pile time is not satisfactory for the customer you can split the stories in more than one pile, each pile now represent an iteration of the live cycle of the software.
The time the development team needs to complete a iteration represent the speed of the team and this factor will be the one that a project manager can use to plan new release with the customer without asking a continuous opinion to the development team.
In order to write a good story you can rely to the Bill Wake definition, a good story is
•    Independent
•    Negotiable
•    Valuable to user, customer and developer
•    Estimable
•    Small
•    Testable
Each story has to be as much as possible without any dependency on other stories but if you can’t remove the dependencies you can combine the dependent stories into one larger but independent story or you can find a different way to split the stories.
Stories are negotiable, they are not written contracts or requirements that the software house must implement, stories are short descriptions of functionalities the details of which are negotiated in a conversation between the customer and the development team.
With this approach you can avoid the situation in which a customer is afraid that during the development process everything he said can be used against him.
Actually the stories are a reminder for the developer and the customer to have a conversation then they have to be no more than one sentence or two with some possible notes.
A story has to be valuable for different purposes and so have to be written with a jargon that is understandable for the customer team, the development team and the test users, the best approach is that the customer write the stories but that is not possible the development team have to handle this task carefully.
It is important that the developers are able to estimate the effort to design and develop each story, if the developers or the customers don’t understand the story this is a good starting point for the project manager to write down the agenda of the next meeting.
If the estimation is not possible because there is a lack of knowledge the team can move one or two members on spike, a spike is a brief experiment to learn about an area of the application that is not clear.

Remember always to keep stories small, epics are sometimes difficult to handle but they can be used as well (not too much!).

Stories must be written in a way that make them testable, I mean that a story can be used as a blue print for the unit testing and for the user test, a story is not testable when it comes from a non functional requirement.
Following this building blocks you’ll be able to write good stories and to start to define estimates for each one, the web is full of resources about that so feel free to investigate and learn more on this topic.

Flex item renderers, an expandable list with transitions

Giorgio Natili — Sun, 11 Jan 2009 08:54:12 +0000

I think that each flex developer at a certain point have had the necessity to work with custom item renderers in order to display data in a fancy way.
There is a lot of knowledge around the web regarding this topic but I want to show the process that has driven me to a list that contains custom item renderers with different states and with transitions between each state.
In order to perform this task I’ll show to you how you can create a simple item render, an item renderer with two different states, an item render with some transitions with a visual bug (it’s the default rendering of the list) and one without any bug.
I know that an expandable list can be done also with a VBox and Repeater and that it perform nicely but the list has a caching procedure of the item renderers that is very useful when you have to render on the screen a great number of complex renderers.

A simple item render
Imagine the simple scenario in which your layout require something more than a label in a list and you need to add for instance a “buy now” button, you can create an MXML component





and set it as the item renderer in the List control

The dataprovider is an ArrayCollection that contain several Article value objects, the class that define an article can be summarized with the following UML diagram

A multi state item render
Imagine now the scenario in which an item renderer needs to show some data and expand itself in order to display on the screen more information about this item, first of all create an MXML component that extends the VBox and that contain three different states, in the first one the component have to show the article name and a button to expand the content

in the second state the component needs to render the price of the article, a “buy now” button and a control in order to expand the third state

In the third state the component has to render the details of the article

In order to complete this task you can define the UI of the component with the following MXML using the tag to define states, label and event handler

If you come back to the list and set this component as an item renderer you will see that the nested states are not rendered, you have to define the List as a variable row list

Now the list is able to render the nested states but if you scroll up and down the list you will see that the states and the data of each item renderer are not consistent with your model, this is due to the List behavior that recycle components in order to render data, when items scroll out of view, its itemRenderer will be moved to the bottom of the list.
In order to keep state and data consistent you have to perform some changes in your code, first of all my suggestion is to create a class that can hold state information and data of each item (in this way also if you work with remote value object you don’t need to make any change on the server side), the class can be summarized with the following UML diagram

the state property contains a string that represent the currentState of the component, the renderData property represents the data you need to display in the components.
Inside your component override the public data method in order to be sure that each time the data changes (each time the list is scrolled) the UI elements are updated

override public function set data(value:Object):void{
super.data = value;
if(!data)return
var dt:Article = data.renderData;
if(_article)_article.text = dt.name;
if(_price)_price.text = String(dt.price);
if(_detailsData)_detailsData.text = dt.description;
invalidateProperties();
dispatchEvent(new FlexEvent(FlexEvent.DATA_CHANGE));
}

Please not that in the method the article value object has been extracted from the object used to define the data of each item.
In order to keep track of the state of each item render override the currentState method and store the value of the new state in the model

override public function set currentState(value:String):void{
super.currentState = value;
if(data)data.state = value;
}

Now is the time to handle the state value in the commitProperties protected method

override protected function commitProperties():void{
super.commitProperties();
if(!data)return;
currentState = data.state;
}

The List component needs to know the dimension of the item render in order to gracefully adapt each item to its state, this is the reason why in the measure() method you have to explicitly set the values of the properties measuredHeight and measuredMinHeight for each state

override protected function measure():void{
super.measure();
if(!data)return;
switch(true){
case currentState == "":
measuredHeight = 30;
measuredMinHeight = 30;
break;
case currentState == "opened":
measuredHeight = 70;
measuredMinHeight = 70;
break;
case currentState == "details":
measuredHeight = 110;
measuredMinHeight = 110;
break;
}
}

If you compile your application now the item renders display the data and the states in a consistent way.

A multi state item render with transitions
In order to add a transition between each state of the your item renderer add the following MXML tags to the previous component and save it with a different name

If you try now the list with this item renderer you’ll be surprised, the transitions don’t perform very well because the item renderer doesn’t know anything about the state in the data method so use an event handler for the StateChangeEvent.CURRENT_STATE_CHANGE event

protected function onStateChange(e:StateChangeEvent):void{
if(!data)return
var dt:Article = data.renderData;
if(e.newState == ""){
dt.opened = 0;
}
if(e.newState == "opened"){
dt.opened = 1;
}
if(e.newState == "details"){
dt.opened = 2;
}
}

and store a specific int value in the opened property of each value object.
In the overridden data method add a switch case to handle this value

switch(true){
case dt.opened == 0:
currentState = "";
break;
case dt.opened == 1:
currentState = "opened";
break;
case dt.opened == 2:
currentState = "details";
break;
}

Now your item renderer is able to handle state and transitions but you’ll see that scrolling the List when it has to render again an item each transition is rendered with a delay, this is due to the live cycle of the List that calls a last udpateDisplayList after a while, in order to solve this stuff you have to put your hands inside the List source code and create an easy reusable class for the item render.

A smart multi state item render with transitions
Surfing the web I found a nice article on item renderers but when I read this sentence “I think a resizing itemRenderer is too complex and not really worth the effort. I believe there is a better way to do this using VBox and Repeater. However, the catch with Repeater is that every child will be created. If you have 1000 records and use a Repeater, you will get 1000 instances of your itemRenderer.” my mind started to think to a solution because with a great number of instances of a complex item renderer the performance of each Flex application can be seriously impacted.
I started to read the source code of the List and I found the two methods that recycle or create the item renderers in the list

getReservedOrFreeItemRenderer(data:Object):IListItemRenderer
createItemRenderer(data:Object):IListItemRenderer

In order to avoid the delay I need to change the state of each item renderer in these two methods, the first issues I found are that the transitions defined in the item renderer stop to work and that the height is not rendered.
The other issue I found is that without a base class each time I would like to use smart item renderers in my List I have to start over.
The solution I found is create a VariableRowList class that extends the List, define a base class for item renderers (I started with a class for VBox based item renderers), define an interface that define a method to use in order to update the state and the height and define the effects I need outside the tag.
The VariableRowList class makes an override of the methods used in order to create and recycle the item renderers and attempt to call the method defined in the interface ISmartRenderer the renderer needs in order to handle its state and its height at the end of each method

try{
ISmartRenderer(item).updateState(dt.state);
}catch(e:Error){
trace("It's not an ISmartRenderer implementors")
}

The ExpandableVBoxRenderer class first of all implements two interfaces, IDropInListItemRenderer and ISmartRenderer, and define a constant that hold an array of objects used to define the heights for each state

protected const STATES_HEIGHT:Array = [{state: "", height: 30}, {state: "opened", height: 60}, {state: "details", height: 110}];

In the constructor of this class you find the definition of a listener for the StateChangeEvent.CURRENT_STATE_CHANGE and for the FlexEvent.CREATION_COMPLETE events and the policy for the scroll bars

this.addEventListener(StateChangeEvent.CURRENT_STATE_CHANGE, onStateChange);
this.addEventListener(FlexEvent.CREATION_COMPLETE, onCreationComplete);
this.verticalScrollPolicy = ScrollPolicy.OFF;
this.horizontalScrollPolicy = ScrollPolicy.OFF;

The override of the data method use a protected method populateControl() that use the data stored in the renderData property of the SmartRenderData class in order to populate the UI elements (this method is empty and need to be overridden from the classes that extend the ExpandableVBoxRenderer)

override public function set data(value:Object):void{
super.data = value;
if(!data)return;
data.state = currentState;
populateControl(data.renderData);
invalidateProperties();
dispatchEvent(new FlexEvent(FlexEvent.DATA_CHANGE));
}

In the override of the measure method the class calculates the needed height trough a private method that get the data from the STATES_HEIGHT constant

override protected function measure():void{
super.measure();
if(!data)return;
var currentHeight:Number = recoverHeight(currentState || "");
measuredHeight = currentHeight;
measuredMinHeight = currentHeight;
}

The updateState method defined in the ISmartRenderer interface update the state and the height of the component and call the measure method

public function updateState(state:String):void{
currentState = state;
height = recoverHeight(state);
measure();
}

If you want now start to use this stuffs define the namespace you need to use the VariableRowList class in your application and place these tags in place of the List you have used before

Define now a new class that extends the ExpandableVBoxRenderer and use it as the base class for a new MXML component that will have the same tags of the one you defined in order to handle the transitions except for the transitions that will be removed and that will be substituted from the following effects

Came back in the class and define the public members that point to the controls defined via MXML

[Bindable]public var _article:Label;
[Bindable]public var _price:Label;
[Bindable]public var _detailsData:Text;
[Bindable]public var _details:Button;
[Bindable]public var _expand:Button;

Override the populateControls() method in order to render the data inside the item renderer

override protected function populateControl(data:Object):void{
if(_article)_article.text = data.name;
if(_price)_price.text = data.price;
if(_detailsData)_detailsData.text = data.description;
}

and define the handlers for the click event on the buttons in order to play the effect defined trough MXML (see in the source of the sample application to check the other handlers)

private function onDetails(e:MouseEvent):void{
if(e.target.label == "Show Details"){
currentState = "details";
this["openDetails"].play()
}else{
currentState = "opened";
this["openDetails"].play(null, true)
}
}

In this way your List will be able to render the data and the transition like a charm, check the sample application and the source code (right click, view source) in order to read the complete implementation.

Resources
http://www.returnundefined.com/2006/10/item-renderers-in-datagrids-a-primer-for-predictable-behavior

http://blogs.adobe.com/aharui/item_renderers/

http://flexdiary.blogspot.com/2007/11/order-of-events-for-itemrenderers.html

http://www.adobe.com/devnet/flex/articles/itemrenderers_pt4_print.html

Flex and SVN

Giorgio Natili — Tue, 14 Oct 2008 16:06:52 +0000

I’m sure that tons of flex developers has already used SVN during the development of their projects but I have seen sometimes great difficulties when during the development of a project different coders need to modify the same file or add a file to a project. In the first situation the way to handle merge is not really intuitive, in the second one most of the times the file is not committed.

For this reason I decided to write some notes on SVN and TortoiseSVN 1.5.4 that has been recently released.

First of all please be sure to use a sane repository layout. There are many ways to lay out your repository. Because branches and tags are ordinary directories, you’ll need to account for them in your repository structure. The Subversion project officially recommends the idea of a “project root”, which represents an anchoring point for a project that contains exactly three subdirectories: /trunk, /branches, and /tags.

“trunk” is supposed to signify the main development line for the project. You could call this “main” or “mainline” or “production” or whatever you like.

“branches” is obviously supposed to be a place to create branches. People use branches for a lot of purposes. You might want to separate your release or maintenance branches from your feature branches or your customer modification branches etc.

“tags” are not treated as special by Subversion either. They are a convention, perhaps enforced by hook script or authoring rules, that indicate you are creating a point in time snapshot. Typically the difference between tags and branches is that the former are not modified once they are created. You might call your tag folders “releases” or “snapshots” or “baselines” or whatever term you prefer.

Be sure to Commit logical change set. When you commit a change to the repository, make sure your change reflects a single purpose: the fixing of a specific bug, the addition of a new feature, or some particular task. Your commit will create a new revision number which can forever be used as a “name” for the change. You can mention this revision number in bug databases, or use it as an argument to SVN merge should you want to undo the change or port it to another branch.

Merging changes sounds simple enough, but in practice it can become a headache. The problem is that if you repeatedly merge changes from one branch to another, you might accidentally merge the same change twice. When this happens, sometimes things will work fine. When patching a file, Subversion typically notices if the file already has the change, and does nothing. But if the already-existing change has been modified in any way, you’ll get a conflict.
Ideally, your version control system should prevent the double-application of changes to a branch. It should automatically remember which changes a branch has already received, and be able to list them for you. It should use this information to help automate merges as much as possible. Unfortunately, Subversion is not such a system. Like CVS, Subversion 1.0 does not yet records any information about merge operations. When you commit local modifications, the repository has no idea whether those changes came from running SVN merge, or from just hand-editing the files.
What does this mean to you, the user? It means that until the day Subversion grows this feature, you’ll have to track merge information yourself. The best place to do this is in the commit log-message.

Let’s take a look to a practical Flex development situation, first of all you have to install Tortoise SVN on your machine and create an empty folder for your project (I’m supposing that you have already started to work on some stuff and that is the time to go under source control and that you are the one that will create the repository).
Right click on the folder and select the import option

In the dialog that appears insert the data for the remote repository

Right click again and perform the check out, now your folder is synchronized with the remote repository.
Copy the files you need in the folder and perform a commit, you’ll be prompted to select the files you want to commit

It’s a good habit to remove properties, project, bin-debug, bin-release, etc. in order to perform this task you can deselect the files from this dialog or you can select a specific file, right click and remove it or all the files with the same extension from the synchronization of the repository

Now you are able to work quite easily with SVN but remember that

· in order to rename a file or a folder you must first checkout the file or folder to your machine. Once it’s on your machine, right-click on the file or folder, and select the menu option SVN Rename,

· in order to delete a file or folder, simply right-click on it, and select the Delete… option from the Tortoise SVN menu

· to add a file or folder, check out the repo (if you haven’t already done so). move the new file(s) and folder(s) to the location you want them in the repository (for e.g. to add the file newfile.mxml to the mxml/trhunk/newclient/ folder, move newfile.mxml to that folder). Now, with everything in its place, right-click on the file(s) and folder(s) you want to add to the repository, and select the SVN Add… menu option

Basically all the usual operations of an operating system needs to be performed trough the Tortoise SVN contextual menu.

SVN is not a back-up system, is a way to handle versioning and conflict, what happens if you make some changes to a file and another developer make the changes to the same file and both of you make a commit at the end of your working day?
SVN will try to make a merge but sometimes it’s not possible so be careful when you do the commit and use the Check for modifications function from the Tortoise SVN menu option

If something goes wrong during the merge you’ll keep your work safe because in the file you are committing SVN will add the change log in the code

<<<<<<< .mine
                var beautiful:int = 5;
=======
                var ugly:int = 5;
>>>>>>> .r10

and in your folder you get a copy of the file with the release name.
I wasn’t a fun of SVN the first time I used but now I am happy to say “It works!”.

Resources
http://electricjellyfish.net/garrett/talks/oscon2004/svn-best-practices/
http://blog.evanweaver.com/articles/2007/08/15/svn-branching-best-practices-in-practice/
http://www.iovene.com/5-svn-best-practices/
http://svnbook.red-bean.com/en/1.4/svn.tour.cycle.html
http://www.changelogic.com/SvnProjectSetup
http://svnbook.red-bean.com/en/1.0/ch05s04.html#svn-ch-5-sect-6.1

Flex code annotations

Giorgio Natili — Tue, 14 Oct 2008 12:38:06 +0000

Today I was talking with a friend of mine that said to me that the only way to find something related to code annotations in Flex is a book he has… that’s definitely not true, the Flex documentation contain a lot of info on this topic and the web is full of resources.

In this short post I want to summarize the building blocks of code annotation in Flex.

In computing, the programmer often adds annotations to source code in the form of comments. These do not affect the working of the program but give explanations (for other programmers, or potential readers of the code principally, but also as a reminder for the author), hints or plans for improvement, etc.
Further Annotations can also be added by a compiler or programmer in the form of metadata, which is then made available in later stages of building or executing a program. For example, a compiler may use metadata to make decisions about what warnings to issue, or a linker can use metadata to connect multiple object files into a single executable.

In computer programming, a Java annotation is a way of adding metadata to Java source code that can also be available to the programmer at run-time.
Java annotations can be added to program elements such as classes, methods, fields, parameters, local variables, and packages.
Unlike tags added to Java documentation and processed with tools such as XDoclet, Java annotations are completely accessible to the programmer while the software is running using reflection.

Class annotations, also known as metadata in Flex, are extremely valuable as they allow developers to provide additional information about classes, properties and methods which may not be appropriate to convey through implementation details such as Marker interfaces or some other means.

You can create your own custom metadata following the same format. The example which follows defines a custom metadata attribute utilized for annotating a class with version information. The name of the annotation is “Version”, which contains three properties; major, minor and revision.

package{

[Version(major="1", minor="2", revision="123")]
public class Model {

}
}

Accessing custom annotations in Flex is accomplished via the flash.utils reflection APIs; describeType, getQualifiedClassName and getDefinitionByName.

ArrayElementType metadata tag can be easily associated to code annotations in fact when you define an Array variable in ActionScript, you specify Array as the data type of the variable but you cannot specify the data type of the elements of the Array.
To allow the Flex MXML compiler to perform type checking on Array elements, you can use the [ArrayElementType] metadata tag to specify the allowed data type of the Array elements, as the following example shows:

public class myComponent extends VBox {
[ArrayElementType("String")]
public var users:Array;

[ArrayElementType("Number")]
public var orders:Array;

}

In a more complex environment you can use java beans in Flex as the datatype of the ArrayElementType tag specifyng the fully qualified name of the class or get inspiration from this article http://www.flexpasta.com/index.php/2008/05/19/blazeds-with-annotations-for-remote-objects/ that is strictly related to Flex and Blaze DS (i.e. java based enterprise applications).

This tag only works for Arrays – there is no way to set the type of elements in ArrayCollection, to have typed array collection, you can take existing ArrayCollection.as rename it to YourArrayCollection.as and modify source property and add ArrayElementType tag with your prefered type, (I have not tried it but it should work) or even better extend the ArrayCollection in order to create your custom collection with the support for the ArrayElementType metatag.

In order to check the generated code add the -keep parameters to the flex builder compiler.