UML, Stub Code and ASDocs
I have recently started using Enterprise Architect (EA) for creating UML diagrams for Actionscript and Flex projects. This is an outstanding product that is reducing my development time and helping me to create self documenting code following AsDoc formatting rules. If you have never created a UML diagram or used UML software, the concept can seem a little overwhelming but let me assure you, your time spent learning how to do so will be time very well spent.
In it's simplest form UML software allows a person to visually layout and architect a project before ever doing any actual coding. You can create your classes, document the properties and functions you intend to use, organize them and relate them (for either implementing or extending). At this point you are probably wondering why you would want to do that when you could just fire up your IDE of choice and start coding. Before I started using Enterprise Architect I only had one really good reason, it makes you think through the solution and plan before you start coding, so you can attack the project with a well defined plan. Now I have another reason, that I think is just as important as the first, EA can generate all your UML'd classes in either AS2 or AS3 in ASDoc friendly format. All your stub code is generated in seconds, perfectly formatted and compilable. This is an absolutely huge time and effort saver. By using UML you can create a well structured plan for your project and using the code generation in EA allows you to export all that planning effort into perfectly formatted Actionscript. I have created a sample project to demonstrate just how nicely this solution works and hopefully show why you may want to consider this approach for your projects. I will walk you through how to create a simple UML diagram in EA, how to export the diagram into AS3 files, and how to run the AS3 code through ASDoc to create project documentation.
You can download all my source files for this sample here.
Step 1 - Configure EA for Actionscript projects
Download the trial version of Enterprise Architect. Once you have it installed a few adustments need to be made. First, select the 'Tools/Options' menu and click the 'Source Code Engineering' node, set the 'Default Language for Code Generation' to 'Actionscript'. Click on the 'Actionscript' node and set the 'Default Version' to whichever AS version you are working in. Second, the templates that generate the AS code need some tweaks (just a few minor things that EA appears to have missed). You have two options, import the template updates I created or do it manually. To import my adjustements, download this file, unzip it, in EA, open the 'Tools' menu and select the 'Import Reference Data' item. Browse to the 'actionscript_code_templates.xml' file, select and open it, select the 'Actionscript_Code_Template' and click 'Import'. To do it manualy open the 'Settings' menu and select the 'Code Generation Templates' item and then make these two changes.
- Select the 'Class' template, change the entire section to
%ImportSection%
This puts the import statements after the package declaration but before the class declaration in the as files.
%ClassNotes%
%ClassDeclaration%
%ClassBody% - Select the 'Operation Declaration' template, find this block of code (near the top)
%PI=" "%
and change it to this
%opStatic == "T" ? "static"%
%if genOptActionscriptVersion=="3.0" and opTag:"namespace"!=""%
%opTag:"namespace"%
%else%
%CONVERT_SCOPE(opScope)%
%endIf%%PI=" "%
This ensures that functions in Interfaces can not be declared Public, Private etc, which will throw a compiler error.
%opStatic == "T" ? "static"%
%if genOptActionscriptVersion=="3.0" and opTag:"namespace"!=""%
%opTag:"namespace"%
%elseIf elemType=="Interface"%
%else%
%CONVERT_SCOPE(opScope)%
%endIf%
Step 2 - Create a UML diagram
Open EA and create a new project. In the project browser you can setup your package structure. For this sample I will keep it really simple and add a few packages 'com.dgrigg.vo', 'com.dgrigg.view'. The next step is creating the diagram. You can drag Class and Interface (to name a few) elements onto the diagram to begin creating your class structure. As you add new elements, you are prompted to enter the class properties. Enter information in the 'Notes' field to explain what the class is for. A few things to note when you are creating elements.
- As you create Classes, Interfaces etc. and add Operations and Attributes (functions and properties) to each, be sure to enter a description in the 'Notes' field, this will get exported in your code and also be used by ASDocs.
- When you create a new class you must create a constructor for it in the Operators list, for some reason EA does not do this for Actionscript projects.
- If you add an Operator that has return value, be sure to enter a return line in the 'Initial Code' field on the 'Behavior' tab. This will set a 'default' return value in the code and allow ASDoc to properly execute and also not throw any compiler errors.
- If the element you are working with needs to import '.as' files, right click on the element in the 'Project Browser', select 'Generate Code' and enter your import statements in the second 'Import(s)/Header(s)' field, click the 'Save' button.
When you are all done your diagram it will look something like this.
Step 3 - Generate the AS file
In the Project Browser right click on the 'com' folder, or whatever you root package folder is, and select 'Code Engineering/Generate Source Code'. Set the path you want to export to, check the 'Include all Child Packages' options, and click the 'Generate' button. Below is a sample of a generated AS file, straight from EA with no editing.
///////////////////////////////////////////////////////////
// ProductList.as
// Macromedia ActionScript Implementation of the Class ProductList
// Generated by Enterprise Architect
// Created on: 14-Sep-2006 5:08:46 PM
// Original author: Derrick Grigg
///////////////////////////////////////////////////////////
package com.dgrigg.view
{
import com.dgrigg.vo.ProductVO;
import flash.text.TextField;
import mx.controls.DataGrid;
import flash.events.Event;
import com.dgrigg.vo.ProductVO;
import com.dgrigg.view.IView;
/**
* Displays a DataGrid of products, lets the user select and view a product.
*
* @see com.dgrigg.vo.ProductVO
* @author Derrick Grigg
* @version 1.0
* @updated 14-Sep-2006 7:38:22 PM
*/
public class ProductList implements IView
{
/**
* displays the list of products
*/
private var products_dg: DataGrid;
/**
* display the selected product's name
*/
private var name_txt: TextField;
/**
* display the selected products' description
*/
private var description_txt: TextField;
/**
* display the selected product's sku
*/
private var sku_txt: TextField;
/**
* Constructor
*/
public function ProductList()
{
}
/**
* add a product to the displayed product list
*
* @param product product to add to the product list
*/
public function addProduct(product:ProductVO): Boolean
{
return true;
}
public function getSelectedProduct(): ProductVO
{
return new ProductVO();
}
/**
* handle the event that is triggered when a user selected a row in the data grid
*
* @param event event dispatched from DataGrid
*/
public function handleSelectedProduct(event:Event): void
{
}
}//end ProductList
}
Step 4 - Generate the ASDoc files
Download and install the ASDoc tool from Adobe. I have created a little bat file I use with ASDoc just to make is easier to recreate the files whenever I need to without having to remember my settings, you can download it here. Run ASDoc to create your files. Click here to see the final ASDocs files.
Conclusion
If you develop Actionscript projects of any size and/or complexity, and you need some documentation done along the way, the steps I have outlined above are any excellent way to quickly generate both the stub code you need to begin your development and some project documentation, which as we all know is a hassle to create but invaluable to have. Enjoy
Sep 18, 2006 at 12:59 PM
Hello
Thanks for sharing :)
Oct 01, 2006 at 1:23 PM
I couldnt pass step 2 /
can you give an example project.
I will add classes but which classes and ,,,
I couldnt understand this part.
/*
For this sample I will keep it really simple and add a few packages 'com.dgrigg.vo', 'com.dgrigg.view'. The next step is creating the diagram. You can drag Class and Interface (to name a few) elements onto the diagram to begin creating your class structure. As you add new elements, you are prompted to enter the class properties. Enter information in the 'Notes' field to explain what the class is for. A few things to note when you are creating elements.
* As you create Classes, Interfaces etc. and add Operations and Attributes (functions and properties) to each,
*/
Oct 02, 2006 at 7:14 AM
Hey Anonim, you can download the sample project here. Setting up a package is like setting up a folder. In the 'project browser' in EA you can click on an existing project or folder and 'add a package', you keep doing that to setup the folder structure (packages) that contain your class files. To create the diagram, if you are having difficultly, I would recommend using the EA help to walk through some of their samples on how to create a UML diagram.
Feb 16, 2007 at 8:17 AM
Man, I wish I found this entry 3 months ago when I learned the hard way how to implement my own AS3 template with an older copy of EA.
Yes, EA is great!
-mL
Mar 08, 2007 at 6:25 AM
Derrick, thanks for nice tutorial. I was trying to dig into EA and all is working like a charm, but the only question left is extending one class from other. How can I specify that MySuperClass extends mx.core.UIComponent for example?
Peace,
Oleg
Apr 21, 2007 at 8:59 AM
hi! great article :)
i'm pretty new to this stuff, but was wondering: when I perform as2 code generation, none of my classes have constructors.. Do you know how to edit the templates to include a default constructor? or am I just being silly? thanks!
Apr 23, 2007 at 3:30 AM
i downloaded the trial version of Enterprise Architect, i went to Tools/Options, then I clicked 'Source Code Engineering' node, the problem is that 'Default Language for Code Generation' is disabled !
also, when I try to create a new project with Enterprise Architect, i got this error:
An Error has Occurred Incorrect version of the DLL file 'MSJET35.DLL' was found
please help, as i am really interested to apply this article : )
Jun 01, 2007 at 9:26 AM
Hello everyone,
This is a great post Derrick! Thanks! I've been actively developing a cross platform UML tool primarily for actionscript but with support for other languages as well. I'll be having a private alpha soon and would be honored if you would join. More information can be found here...
http://www.levelofindustry.com/journal/2007/4/30/apollo-uml-modeling-tool-saffron.html
Thanks in advance! Cheers,
Samuel Agesilas
Aug 16, 2007 at 12:08 PM
You need to create a project first. If the default language for code is disabled, it is probably because EA was fresh installed and no projects have been created.
Also, there is two ways to add stuff to a diagram, dragging existing packages or dragging new ones (one from "class elements" the other from the "Project Browser".
I am totally new to EA and do not know yet where to start. I would guess we first build the architecture in the project browser usinf right-click + add, and then drag the resulting elements from the project browser and drop them into the newly created diagram.
That what I am presently trying and what I believe to make sense but we need some confirmation from Derrick :-)
Aug 23, 2007 at 6:26 PM
Great.
I am trying to start using EA to create my VOs in AS3 and in Java at the same time. The idea is to create Platform Independent Model and then transform it using MDA (http://sparxsystems.com/resources/mda/) into an AS3 and Java class models. I have some peculiarities, like that i declare properties as public in as3 directly while in java I make use of getters and setters, so this transformations are great for dealing with this.
Right now I am trying to figure out how can I declare a property as a Collection with a certain type. In EA you can declare a property as a Collection and declare the container type, but the source code still does not represent this :( Any help with this would be greatly appreciated.
Nov 19, 2007 at 11:18 AM
Thanks for the post on ASDocs with your example. We couldn't get ASDocs to traverse a tree of classes without typing all their names in specifically until I read your .bat file. Thanks again
Nov 29, 2007 at 1:10 PM
Hi
Just wondering if you have had the opportunity to create Test models with EA or generating test cases. I have a complete project but the tutorials does not clearly assist with testing (in my opinion.)
Nov 29, 2007 at 7:07 PM
Hey Zak, I've never tried to create Test cases using EA.
Dec 26, 2007 at 5:35 AM
Solution to Sameers Problem:
My problem:
When I try to open any *.eap file (e.g. \\pluto\Universal Banking\Tech Design\UBDesignTemplate.eap) , I get the following error:
"An error has occured: incorrect version of the dll file 'msjet35.dll' was found"
Solution
I had the version: 3.50.3907.5
replaced it with the current version is: 3.51.2723.0
Jan 11, 2008 at 4:51 PM
Thanks for this post. I'm getting up to speed on EA for Flex. I think I'm pretty clear on how it all works now, except for one thing. In your sample project, how are you defining a property as type "DataGrid", and having the code generator properly import "mx.controls.DataGrid"?
Related, how would you specify that a class extends some Flex class, such as mx.controls.Canvas?
Feb 14, 2008 at 2:06 AM
Cool! EA sounds like just what i was searching for..
Hmm.. Asdoc gets stuck when I try to link some of my classes that uses fl.transistion. Do you know any solution to that? Ignore classes doesnt seem to work. Neither does ignore warnings..
When I try include the swc file, i just get an error.
(but the code compiles allright)
Feb 18, 2008 at 10:10 AM
I get the following problem:
""An error has occured: incorrect version of the dll file 'msjet35.dll' was found"
Tryied to use this solution
"I had the version: 3.50.3907.5
replaced it with the current version is: 3.51.2723.0"
But there is the same error. Please help me.
Feb 20, 2008 at 9:54 PM
Nice post Derrick. I'm curious, how does EA handle imported classes? Say I create a package that needs displayObject, how do I associate it with the class? I see that you write your initial code when exporting, however I would like to keep things in sync. What if I edit my class outside of AE, is it possible to update the AE diagram without ruining everything?
-James
Feb 28, 2008 at 2:14 PM
For those of you experiencing the "An error has occured: incorrect version of the dll file 'msjet35.dll' was found" problem, go to
http://support.microsoft.com/kb/172733,
download the Jet35sp3.exe file, run it, and your error should go away.
At least it worked for me!
mary
Apr 08, 2008 at 9:48 AM
I've also noticed that the "override" statment is mispositioned.
you need to move this statement....
%opTag:"override" == "true" ? "override"%
...AFTER the first occurance of this statement...
%PI=" "%
...in the Operation Declaration Template portion.
Dec 09, 2008 at 10:42 AM
Mary, thanks, but it dont works for me.. Any other idea to repair it?
Dec 09, 2008 at 10:42 AM
Mary, thanks, but it dont works for me.. Any other idea to repair it?