Developping a contact manager application (CManager) – Part 1

Introduction

We are going to create a contact manager application step-by-step in order to expose AS Foundry benefits and mechanisms. CManager is composed of a Flex client and Java/BlazeDS service running on a Tomcat server. Thanks to its simple structure, CManager allow for modification (create, update, delete) of contacts data drawn from a Java service. In this first tutorial step, we will expose the basis of MVC and AS Foundry patterns. In the following tutorials, we will improve CManager and see some of advanced AS Foundry Toolbox functionalities.

The demo of CManager is available just right here : http://cmanager.servebox.org

Requirements

IDE :

Runtime environment :

  • JDK 1.5
  • Tomcat 6.x : we have set up Tomcat preconfigured versions for Windows and Linux.

Installation

JDK 1.5 installation

  • Download and install JDK 5.0 Update x
  • Create the ‘system’ environment variable :
    ${JAVA_HOME} = C:\Program Files\Java\jdk1.5.0_17
  • Add the environment variable to your path :
    Path= ... ;%JAVA_HOME%\bin

Tomcat installation

  • Download apache-tomcat-6.0.16.rar just right here :
  • Unzip the archive in a folder, for example D:\Softs\apache-tomcat-6.0.16
  • Create the ‘system’ environment variable :
    ${CATALINA_HOME} = D:\Softs\apache-tomcat-6.0.16
  • Add the environment variable to your path :
    Path= ... ;%CATALINA_HOME%\bin
  • Your Apache TomCat application server is now ready to go, launch it using startup.bat (C:\Foundry\apache-tomcat-6.0.16\bin).

Flex Builder or Eclipse configuration :

Download the CManager projet layout and complete sources by following the tutorial step-by-step.

  • In the .actionScriptProperties of flex-gui, replace the attribute outputFolderLocation in the compiler tag :
    outputFolderLocation="/C:/Foundry/apache-tomcat-6.0.16/webapps/contactApplication/flex-gui-debug"
  • Same replacement for the attribute serverRoot of flexProperties tag in .flexProperties file :
    serverRoot="C:\Foundry\apache-tomcat-6.0.16\webapps\contactApplication"
  • In .project file, replace the location tag in order to target the Apache tomcat deployment folder :
    /C:/Foundry/apache-tomcat-6.0.16/webapps/contactApplication/flex-gui-debug

Right now, you can import the flex-gui project to your workspace.

The project

CManager application is composed of three sub-projects :

  • « flex-gui » for the Flex graphic user interface
  • « java-service » for the Java service
  • « web-app » which allow for the assembly of TomCat deployed web application.
  • If you plan to use this Tomcat provided version, you’re done with this step.

Project layout

The « Java-service » project contains Java classes used at runtime for data retrieval. It also contains a HSQLDB database which is auto-installed in a Tomcat temporary folder. We won’t dwell on the Java service part and instead focus on the « flex-gui » project. src/main/resources folder contains additional resources used by the compiler : assets and css style sheets. Download the CManager project layout (zip)

Project pattern : Model, view and controller

AS Foundry uses several design patterns to bring a way to speed up development of RIA applications with the use of tools like data synchronizing between models and views, browsing navigations, ACL, localization and labels internationalization, and much more! In the MVC design pattern, the model encapsulates the data handled by the application, the view renders the data and handles user interactions. Finally, the controller translates the actions performed by the user into actions to be performed by the model or calls to the remote data services. For more information about MVC, see the « The MVC Framework » article. The main AS Foundry packages that we will use are the following ones :

  • view : graphical layout
  • helper : view logical handling
  • control : controller
  • business : remote services
  • model : data model

Initialization

Download the MVC design pattern setup archive (zip)

Creating the Model

The Model part of the MVC is represented in the AS Foundry framework by a single class : AbstractModel. This class is an implementation of the IObservable (also known as Subject) part of the Observer pattern. The role of an Observable instance is to relay changes to the Observer instances (here, the views) using a notification mechanism. In order to create our model, we have to extend the AbstractModel class provided by the framework.

Model-View-Controller elements

Model-View-Controller elements

//model/ContactModel.as
...
public class ContactModel extends AbstractModel
{
	public function ContactModel()
	{
		super();
	}
}
...

Please verify your imports.

ContactModel handles the contacts’ list. The getter & setter methods respectively allow to retrieve and to modify this contacts’ list. The use of the notifyObservers method allow observers to be informed of any modification that would happen on the contacts’ list. Observers (which is to say, our views) can register to the model and be notified of any data updates.

//model/ContactModel.as
...
private var _contacts : ArrayCollection;
...
public function getContacts(): ArrayCollection
{
	_contacts.source.sortOn("lastName");
	return _contacts;
}
 
public function setContacts( ar : ArrayCollection ): void
{
	_contacts = ar;
	// Notification des observateurs éventuels
	notifyObservers( new ContactListNotification( null ) );
}
...

Please verify your imports.

Creating the Controller

The Controller handles every user interactions from the views by calling the model or the remote data services. In order to create the application controller, we simply have to extend the AbstractController class. Being the main application entry point :

  • it must implement the Singleton design pattern to insure that we will always call the same instance ;
  • it must initialize models and businessdelegates (see 6.3 Creating the BusinessDelegate) : that’s why we have to override initializeModels and initializeDelegates methods.

The following code sample initializes these methods to create the MainController instance. Notice that our model is registered to the ModelLocator. ModelLocator implements the Singleton design pattern : this class registers references to the application models.

//control/MainController.as
...
public class MainController extends AbstractController
{
...
	/**
 	* MainController Singleton
 	* */
	public static function getInstance() : MainController
	{
		if(_mainControllerInstance == null)
		{
			_mainControllerInstance = new MainController();
		}
		return _mainControllerInstance;
	}
...
	/**
	 * Initialize Models
	 * */
	override public function initializeModels():void
	{
ModelLocator.getInstance().registerModel( getQualifiedClassName(ContactModel), new ContactModel() );
	}
...
	/**
	 * initialize business delegate
	 * */
	override public function initializeDelegates():void
	{
		//we will acces to the remote services
	}
 
...

Please verify your imports.

Now that we have created both our Model and Controller, we can initialize the application and start creating our views.

Application initialization

In a basic Flex application, the root file is a mx.core.Application instance. For AS Foundry, the application must perform our controller’s initialization. We have to extend the AbstractApplication class by overriding the getControllerClass method.

//control/MainApplication.as
...
package org.servebox.sample.contactapplication.control
{
	import org.servebox.foundry.control.AbstractApplication;
 
	public class MainApplication extends AbstractApplication
	{
		public function MainApplication()
		{
			super();
		}
 
		override protected function getControllerClass():Class
		{
			return MainController;
		}
	}
}
...

Please verify your imports.

Since our application is now ready to go, we have to declare it as the top-level component in the main.mxml file.

<!-- src/main/flex/main.mxml –--->
<?xml version="1.0" encoding="utf-8"?>
<!-- src/main/flex/main.mxml –->
<control:MainApplication
	xmlns:mx="http://www.adobe.com/2006/mxml"
	xmlns:control="org.servebox.sample.contactapplication.control.*"
	xmlns:view="org.servebox.sample.contactapplication.view.*"
	>
</control:MainApplication>

Please verify your imports.

Page 1 Page 2 Page 3

Friday, April 24th, 2009 No Comments by Jeff Mathiot