Overview

This post will contain the process for producing UML diagrams from your Actionscript classes. This is a work in progress until I actually succeed in getting the UML diagrams.

Update: This project is on hold because of deadlines. I will get back to it soon. There are still some useful tips in this post, though.


Introduction

I was inspired to write this post by the worst c*ck-tease ever: Creating the ActionScript 3.0 UML Diagrams. In this, the author says, “Next I wrote some XSL that converted the ASDocs XML into XML Model Interchange (XMI) format.” Wow! I was so excited that I skimmed the article to look for them. Then I read the article carefully. Then I read the list of comments all asking for the XSL file. Turns out, he’s mum on it. The XSL is, of course, the only piece which we need to know about – the rest is public info (with a bit of research). So, I decided to not take his suggestion to buy a UML program that can do this. Probably is a good program. But that is lame, to charge for what is actually very easy to create, ultimately.

Now, before I get a bunch of comments claiming that I am as bad as this guy, let me restate that this is a work in progress until I actually succeed in getting the UML diagrams. This should be within a few days. Once I get the XSL file developed, I will post it here, and then fill in more information about how to use it after that point.

This is focused on Windows development. Linux and Apple environs will have different processes for some of the steps.


Programs used

  • ASDoc.exe, part of Adobe Flex 3 files (I believe it will work for ASDoc from Abobe Flex 4, too.)
  • Indirectly using XALAN. ASDoc is a glorified XALAN XML translator front-end. It even requires the xalan.jar. So you can do read the docs and maybe advance the ASDoc cause.
  • BOUML for the developing the UML diagrams. This is a free program that works fairly well. It has some rather unique user-interface issues, but everything works once you know what to do.
  • FlashDevelop, of course!

Using ASDoc on Actionscript classes

Summary of ASDoc setup:

Possible fixes to get ASDoc to process your class files:

Possible Java errors you will meet:

  • Using the wrong version of Java. ASDoc requires Java 5.
  • Not referencing Java correctly. Create this system variable called JAVA_HOME, like this (use quotes and backslashes): JAVA_HOME=”C:\Program Files (x86)\Java\jre1.5″

This is the first pain in the ass step. It requires quite a bit of manual work, which really sucks. Also, and this is important if you are going to follow my directions: you will probably have to do more or less than these instructions. Every ASDoc project may be different. A lot of this could have solved if Adobe would provide a complete internal class SWC file (Note: use the FlashBuilder SWCs if you can). Anyway, here is what I did:

One of the main problems is that FlashDevelop has a different set of intrinsic class references than Flex does. So you can reference things in FD that won’t be available in ASDoc.

Note: you cannot use FD’s “intrinsic Flash classes” source paths, since the FlashDevelop classes are only shells. ASDoc will throw errors.

Created an SWC called flashShim.swc, and put it some place accessible.

Added this ASDoc command:

-library-path+=flashShim.swc

This is needed in order to have the classes listed be accessible. Don’t know why it’s not auto-found.
Note that you MUST use ‘+=’ and not just ‘=’. using ‘=’ will result in all previous libraries being removed and replaced.

Within flashShim.swc:

  • Added a tween of a MovieClip in order to reference fl.transitions.Tween for the AS3_0.classes.Structures.Events.ShowHideEffect class.
  • In flashShim.swc in Actionscript, I tried to import flash.ui.Mouse, but it didn’t take. I think I switched to the flex import, and it worked (using playerglobal.swc, below).
  • In flashShim.swc in Actionscript, tried to import flash.ui.MouseCursor, but it never appeared in the SWC. Since this is only an enumeration (struct) class, I changed all references to hard-coded text.

Revise code (AS# to Flex, making data accessible to ASDoc, etc.):
Cannot access “Mouse.cursor” – maybe this is outdated, dunno. But it doesn’t work, so I removed it.
Moved Tweener to the root Actionscript directory. ASDoc could not find the code base otherwise, not even with “library-path”. However, I did this very early on, and it may actually be a ‘+=’ issue.
playerglobal.swc is found in Flex’s “frameworks\libs\player\” directory. I copied it to someplace accessible, but that is not necessary. Just make sure you reference it correctly. ASDoc will NOT tell you that it cannot find the file.

  • -library-path+=playerglobal.swc

ByteArray.clear() is not accessible, so I did data clearing in a ByteArray a different way.
Loader.unloadAndStop() does not exist to ASDoc. Not sure why. But this is important for keeping clean code, so may need a workaround. All the same – forgoing the inherent garbage collection – I did a Loader.unload() and MovieClip(Loader).stop(). Hopefully that works well enough to keep the memory load low.

{update is pending}

Java issues:
If you get an error like “Could not find a JVM” or “Unable to load java.dll”:

You MUST use Java 5 (aka JRE1.5, Java SE 5, etc.) to run ASDoc.exe. If (on running ASDoc.exe) you receive an error reading, “Error: could not find a JVM” or “Unable to load java.dll”, make sure that you are using Java 5. Java 5 is a legacy version of Java, and no longer being developed. However, you can download it from the Java website. (I spent a day trying to get Java to work correctly, until I found this post’s comment: http://forums.adobe.com/thread/93057?tstart=1.)

The other cause for this error is not correctly referencing the Java 5 directory. It is best to use the system variable JAVA_HOME (create it if it doesn’t exist). According to one post’s comment, you have to put the file location in quotes and use backslashes instead of the Windows forward slashes. E.g., JAVA_HOME=”C:\Program Files (x86)\Java\jre1.5″


Using ASDoc to output XMI (UML)

ASDoc is an XALAN front-end, so it’s only real job is to convert XML from one format to another (this is what XALAN does). This makes sense, since it is taking the class files, converting them to XML, and then following a set of XSL instructions to convert that XML to HTML (another XML format):  AS3 classes to XML to HTML.  The goal of this post is to show how to go from classes to XML and convert that into XMI (UML): :  AS3 classes to XML to XMI.

There is a set of XML/XSLTs that create the HTML; these can be re-purposed to output XMI (UML). The XSLTs are found in:

{Flex folder}\asdoc\templates

Copy this set of files to an accessible directory.

(Here is a tutorial on how to develop an XML transformation (all the tools mentioned are free): http://www.vogella.de/articles/XSLT/article.html ).

{This post is incomplete – no XSLTs yet, sorry!  An update is pending.}

– 30 –

– 30 –

Advertisements