1. Basic Features

1.1. UML Compliance, Analysis Elements, ActionScript Elements

UML4AS - UML for ActionScript and Flex is a graphical modeling tool that’s focused on code synchronization. The modeling language of UML4AS - UML for ActionScript and Flex is based on UML (Unified Modeling Language), with 2 particularities:

• It supports a subset of the full UML specification, more precisely diagrams and elements that are directly related to code,
• It extends existing UML elements that are rather generic, by adding programming language specific elements. This way they are less generic and closer to the programming language.

There are 2 types of elements (by elements we understand packages, classes, interfaces, attributes, operations, etc.):

• Analysis Elements. They are generic and cannot be synchronized with code. They are useful for high level design, discussions, expressing ideas, etc.;

• ActionScript specific elements. They support AS specific constructs (i.e. annotations, constants, override flag, etc.).

ActionScript elements have a slightly different icons and an "A" letter in the upper right corner. ActionScript elements can be synchronized with code. For this, they need to be placed (directly or indirectly) inside a SrcDir. In this case they receive additional graphical elements: the synchronization markers in the upper left corner of the element icon.

1.2. Code Synchronization and CodeSync Technology

ActionScript model and code synchronization is THE feature of UML4AS - UML for ActionScript and Flex. To achieve this, a technology that’s called CodeSync is used. Compared to traditional tools, the CodeSync technology has a new and innovative way of working. It’s "more" focused on code, more flexible and friendlier to the developer.

The synchronization can work in 2 ways:

• Automatically. It is fired when elements from the workspace are saved (i.e. source code files or model files);
• Manually. The user invokes the synchronization manually using the context menu action available on the SrcDir.

The “Enable automatic synchronization” option from the “Flower Modeling Platform” preferences page controls this behavior.

1.3. SrcDirs

The CodeSync story begins with a SrcDir. The SrcDir (or longer, Source Directory Package) is a special package that maps to a source directory on the file system. Everything that’s contained within a SrcDir has a one to one mapping with what’s on the file system. An ActionScript SrcDir can contain only ActionScript elements (analysis elements are not welcome here).

On the other hand, an ActionScript element can be contained or not (directly or not) in a SrcDir. If it is the case, then it is synchronized with the code (it is called a synchronizable element). If not, it’s ignored during code synchronization.

A model file can have several SrcDirs, from the same or other projects from the Eclipse workspace.

1.4. Synchronization Markers

All ActionScript elements from (and including) a SrcDir (i.e. synchronizable elements) have graphical synchronization markers, in the upper left corner of the element icons, with the following meaning:

• Green () - the element & its children are in sync with the code,
• Red () - the element is not in sync with the code; it has modifications that are not yet written,
• Yellow () - the element is in sync, but one of its children is not, or it is marked deleted,
• Marked Deleted () - the element is marked deleted; synchronizable elements cannot be directly deleted. They are marked for deletion and they are deleted when synchronizing (or not, because a delete can cause a conflict as well),
• Conflict () - during the last synchronization, overlapping changes were detected; the user needs to decide what to do in this case,
• Conflicts on children () - the element has one/several children with conflicts.

1.5. CodeSync Differences

The CodeSync Differences view is available from the tree context menu ("CodeSync Differences" entry), for each synchronizable element. It displays (for itself and its children) the state on the model, the state on the file system and the changes that were made.

Using this view, changes made on the model can be reverted. This view is used as well when conflicts are detected. The user can keep the changes from the model, the changes from the code or a mix between them.

2. Advanced Features

2.1. Timestamps and Version Management Systems

The CodeSync engine processes files only if their timestamp has been modified since the last synchronization (or if there are changes on the model side). It adopts this strategy in order to optimize the synchronization speed. In the manual synchronization mode, a full synchronization (with disregard of timestamps) can be done by selecting "Synchronize Full (Ignore Time Stamps)" (on a SrcDir, although it is used rarely or never). The CodeSync Log view (see below) displays the action taken by the CodeSync engine for each file.

When working in teams and using version management systems, the same file has different timestamps for different users, even if the contents are the same. However the model file memorizes the timestamps only for the last user who modified the model. This means that the above mechanism doesn't work well (meaning there is no speed gain every time).

There is a solution for this setup. Version management systems often have a setting to enforce the same timestamp for every working copy of the same repository. This setting should be enabled. For example on Subversion this setting is called "use-commit-times". It should be enabled for every user (e.g. on Windows, the file c:\Documents and Settings\User\Application Data\Subversion\config should contain use-commit-times = yes).

2.2. UID Annotations and Refactor Support

Synchronizable model elements (e.g. a class Customer) can be referenced:

• by other synchronizable elements (e.g. an attribute customer of type Customer),
• by elements that are non synchonizable (i.e. don't have an equivalent on the file system; e.g. some relations: associations, dependencies or graphical elements diagrams and their contents: documentation notes, etc.)

The second type of references (from non-synchronizable elements) are delicate some times. During most of the code synchronization operations, everything works fine.
However, if a refactor is done on the file system (rename or move for classes, attributes, etc), these references are lost (i.e. diagram data, documentation notes, associations, etc.).
Why is that? Because the CodeSync engine interprets the refactor operation as a delete + add, instead of a rename or move operation.

The solution for this problem is the use of Unique IDs (UIDs) attached to the model elements' documentation (e.g. @flowerModelElementId _t9B7oGUQEd-1u9VEndCgSA). They appear only for elements that are referenced by non-synchronizable items (they don't appear on all the elements to reduce unnecessary UID pollution of the source files).

For example, if the class Customer is on the Main diagram, and it is renamed to ImportantCustomer and moved to another package:

• without UID annotations, the diagram information is lost; the Main diagram won't contain the renamed class
• with UID annotation, the diagram Main will show the newly renamed and moved class, ImportantCustomer

This setting can be modified for each SrcDir (from the context menu entry, "Use UID Annotations"). When this setting is toggled (enabled/disabled), the elements from the SrcDir that are referenced by non-synchronizable items are updated (i.e. their documentation is updated: a "@flowerModelElementId" is added/removed).

2.3. Lock Synchronization (i.e. Ignore Elements)

It can be useful sometimes to temporarily ignore some elements during synchronization.

For example, we are working on the model side at the BasicCustomer class. We need to suspend the current work for something more urgent. In this case we don't want to synchronize our draft modifications, as they are not finished, but we would like to continue to use the tool normally for the rest of the model.

In this case we "lock" the BasicCustomer class.

• a red lock appears in the bottom right corner of the element icon, meaning that the element is locked;
• all of its children have a blue lock; that means that a parent (direct on indirect) is locked;
• all of its "parents" (direct or indirect) have a yellow lock; that means that on of their children (direct or indirect) is locked.

This feature is useful as well when working in teams. It can be enabled or disabled from the context menu, for synchronizable elements. It is recommended to lock only "higher" level elements: SrcDirs, packages or types (classes/interfaces).

2.4. CodeSync Log

UML4AS - UML for ActionScript and Flex keeps a detailed log of each synchronization operation. Using the CodeSync Log view (available in the tree’s context menu, for each element contained in a SrcDir, under "CodeSync Log" entry) you can view the log entries or erase them. The log should be erased from time to time to avoid having big model files.