Programming with UMLAF

JAC provides an IDE that supports UML-like editors so that it greatly simplifies the programmer's task. This IDE is called UMLAF for UML Aspectual Factory

UMLAF is entirely programmed with JAC itself. It is a good example of what can be done using JAC. Sources of UMLAF are located in src/org/objectweb/jac/ide of the sources tarball.

Using UMLAF to program with JAC is not mandatory. Since JAC is a framework, JAC programs are written in pure Java (excepting the *.acc files). Thus, your favorite IDE can be used instead of UMLAF.

Warnings

UMLAF is still in a beta version. The core model is quite stable and you should be able to read your projects with upcomming JAC releases, however, class diagrams could be lost.

The supported modeling language is a subset of UML (it only supports class diagram), plus a set of new concepts to model aspects (aspect classes, pointcut relations, and groups). These concepts should not be used for actual softwares since they are experimental (for the moment).

We claim that when using aspect-oriented technology, the whole UML language is not actually needed since the program is expressed with its simpliest core-business form. All the complexity related to implementation and design is handled in the provided aspects. As a consequence, you might be disapointed if you try to use this IDE whithin a regular development process on regular OO or CB technologies. In the future, other useful UML concepts (such as collaboration diagrams) will be implemented.

Getting started

Refer to the installation guide to launch UMLAF.

When launched for the first time, the IDE appears as a window separated in 4 sub-panels. In the upper-left pannel, one can see a treeview that contains one single node called "projects". This sub-panel is the most important since it allows you to navigate in your projects and all the projects entities such as packages, diagrams, classes, or applications. The following list shows the hierachy of all the different entities manipulated by the IDE:

Using the treeview is simple. You can double-click on a given node to open it. You can use the right-click to show the available treatements on the entity. For instance, to create a new project, just right-click on the "projects" node and choose the "Add project" item.

The upper-right panel is used to edit diagrams. Once you have created a package in your project (using right-click on the treeview), create a diagram in this package. The upper-right panel will show a diagram editor that allows you to create and edit the entities of the owning package.

The two lower panels are used to provide a Widget-based representation of the currently selected entity in a diagram. The left one shows classes, aspects, instances, or groups. The right one shows relation and pointcut links, attributes, or methods. These two panels can be used to edit the model elements without using a graphical diagram editor (which is sometimes useful to avoid using the mouse to much).

Creating an application

Modeling the core business

First create a new project using the right click on the "projects" node of the treeview. Call it "myProject" and choose the generation path (the directory where the Java code will be generated).

You then need to create a new package in your project to define the business classes. Right-click on "myProject" node and add a package that you can call "invoices".

Since it is nicer to model graphically, right-click on "invoices" and add a new diagram. Call it "business" since it will represent the core-busines model of the application. A diagram editor component should then open in the upper-right sub-panel.

The JAC IDE

Click on the "New class" button (New class icon) of the diagram editor toolbar and then click on the desktop where you want to locate the new class. A popup should appear to enter the class' name. Note that you can modify names later on by using the "Text tool" (Text tool icon) button or by using the other sub-panels. Just call the new class "Invoices". This class represents a container for a set of invoices.

Now create in the same way an "Invoice" class. You can add an attribute by using the "Add attribute" button (Add attribute icon) of the toolbar or by right-clicking on the class in the tree view or in the diagram. Set the name of the field to "amount" and its type to "double".

Adding a new field to a class

Attributes can be read-only, which means that no method to set its value will be generated, or calculated which means to no real java field will be generated to store it value. A calulated field should usually be read-only.

With the same process, create an attribute named "date" of type "Date".

You can now create another class "Client" with an attribute named "name" of type "String".

Classes are created

We can now relate the three classes together. Use the "New relation" button (New
      relation icon). Press the left button down on the "Invoices" class and, without releasing, move to the "Invoice" class and let the button up. A new relation link should be created with its default roles, names, and cardinalities. You can edit them on the diagram using the text tool, or in the lower-right sub-panel after you have selected one in the diagram. Set the end cardinality to "0-*" and the start cardinality to "1". Do the same to create a relation between "Invoice" and "Client" set the start cardinality to "0-*" and the cardinality to "1".

Set the role names as shown in the following screenshot.

The invoices.business
	class diagram

We also set the orientation of the relation between Invoices and Invoice to "start->end" so that it is only navigable from Invoices to Invoice. No collection field will be generated in the Invoice class for this relation.

Creating the application

Global configuration

Once the core business is modeled, you should create a new application to make a running JAC program.

Right-click on the "myProject" node and choose "Add application". Call it "myFirstApplication" for instance. You can also program the launching code of the program (this code corresponds to the static void main(String[] args) method that is used as an entry point for the Java program).

In JAC, the idea of a lauching code is to create the root objects of the application that can be used to reach or create other objects via collections (relation links with "0-*" end cardinality) or references (relation links with "0-1" end cardinality).

In this case, we only need to create an "Invoices" instance since all the other objects are reachable from it (regarding the model). Thus, in the launching code editor, type the line:

new invoices.Invoices();
My first application
	global configuration

Note that the full name of the class is as expected the parent package path concated with the class name (this follows the Java conventions).

At this step, the application is ready to run. Validate and use the "Generate code" and the "Compile" commands by right-clicking on the "myProject" node. If something goes wrong, some error message(s) should appear in an errors dialog. If you do not figure out how to solve the problem, do not hesitate to contact us.

Since the application does not perform any treatment, it is not very interesting to launch it as is. Thus, we should add at least a GUI aspect so that the user of the application can create and manipulate the business objets.

Configuring the RTTI/GUI aspect

The GUI aspect is one of the most useful aspect provided by JAC since it allows the programmer to configure how the business objects should be rendered and how the final user can interact with the application.

As any aspect in JAC, the GUI aspect provides a configuration interface GUIConf (extends ClassAppearenceGuiConf, FieldAppearenceGuiConf, MethodAppearenceGuiConf, and BehaviorGuiConf) that defines all the configuration methods that can be used during the configuration process. The programmer can refer these interfaces to know the available commands that can be used.

To add an aspect configuration to an application, right-click on the application node of the treeview and add a new aspect configuration.

An RTTI aspect configuration is automatically added when you create a new application. No configuration is required for the moment since the RTTI aspect automatically import a default configuration that is sufficent for this application. To know more about RTTI and what can be configured in it, see RttiConf.

Do not forget to check the woven checkbox. Otherwise, the aspect will be disabled when running the application.

Then, create and configure the GUI aspect as shown in the following screenshots.

For more details on aspect configurations and syntaxes.

The GUI aspect configuration
The GUI aspect configuration
setEmbeddedEditors;
setAutoCreateAll;
The GUI aspect configuration
setTableView invoices.Invoices invoices;

window myGUI {
    registerCustomized;
    setTitle "Invoices";
    setSubPanesGeometry 2 HORIZONTAL {false,false};
    setPaneContent 0 Object {"invoices0"};
    addReferenceToPane invoices.Invoices invoices 1;
    setPosition 0 0 60 60;
    setSplitterLocation 0 0.6;
}

Starting the application

Before starting, ensure that the code generation is ok by right-click on the project's node and "Generate code" then "Compile".

The application code and classes is then available in the generation directory (GEN_DIR) that you have choosen when you have created the project (you can change it by asking a view on the project).

We are now almost ready to start the application. We just need to configure a few options before we can do so. Right-click on the application and "View", then in the "Run options" tab, configure as below:

Run options tab of an application

You can now right-click on the application and "start"!

Alternatively, you can start your application by hand with the application's desciptor that was automatically generated:

Under Unix
cd <jac_dir>

java -jar org.objectweb.jac.jar -R . 
     -C GEN_DIR:GEN_DIR/classes 
     -G myGUI
     GEN_DIR/myFirstApplication/myFirstApplication.jac
Under windows
Create a shortcut for the following command:
java -jar org.objectweb.jac.jar -R .
     -C "GEN_DIR;GEN_DIR\classes" 
     -G myGUI
     "GEN_DIR\myFirstApplication\myFirstApplication.jac"
And set its start directory to <jac_dir>.

To stop the application, use the "stop" action in the application popup menu. Closing the window will not kill the process by default.

Finalizing the application

On the following model (please, update your current one):

The final diagram

Note that the navigability of the relation between Invoices and Client is only navigable from Invoices to Client.

Do not forget do generate the code of the project and compile it after you modified the classes.

We are now showing all the aspect configurations that are needed for the full application (exept the RTTI that is also needed at first place).

Final GUI aspect (configuration tab)

For details on configuration commands, see the entire configuration interface at GUIConf (extends ClassAppearenceGuiConf, FieldAppearenceGuiConf, MethodAppearenceGuiConf, and BehaviorGuiConf).

class invoices.Invoices {
  setCategories {"invoices","clients"};
  attribute invoices {
    setTableView;
    setCategory "invoices";
    setDisplayLabel false;
  }
  attribute clients {
    // setTableView;
    setCategory "clients";
    setDisplayLabel false;
  }
}

class invoices.Invoice {
  setTableMembersOrder {amount,date};
  setAttributesOrder {amount,date,client};
}

class invoices.Client {
  setToString "%name%";
  setAttributesOrder {name,invoices};
  setTableView invoices;
}

window myGUI {
   registerCustomized;
   setTitle "DEMO";
   setSubPanesGeometry 2 HORIZONTAL {false,false};
   setPaneContent 0 Object {invoices0};
   addReferenceToPane invoices.Invoices invoices 1;
   addReferenceToPane invoices.Invoices clients 1;
   setPosition 0 0 60 60;
   setSplitterLocation 0 0.6;
}

Integrity aspect configuration

With this configuration, you can declare some data dependencies and some conditions on their values.

For details on configuration commands, see the entire configuration interface at IntegrityConf.

Associations need to be declared. This is done automatically when the code is generated for each relation, depending on its direction.

Add an aspect configuration named "integrity" to your application, and write the following code in the "Configuration" tab:

// clients are automatically added to the repository collection
declareRepository invoices0 invoices.Invoices.clients 
   invoices.Invoice.client;

// add a condition
addPostCondition invoices.Invoice amount 
   org.objectweb.jac.aspects.integrity.GenericConditions.isGreaterThan {0} 
   "The amount must be positive";

Persistence aspect configuration

With this aspect, your datas are automatically made persistent.

For details on configuration commands, see the entire configuration interface at PersistenceConf.

Add a "persistence" aspect configuration to your application with the following configuration code:

// we use a file-system storage (path is from the root JAC dir)
configureStorage org.objectweb.jac.aspects.persistence.FSStorage {"data/invoices"};
makePersistent invoices.* ALL;
registerStatics invoices.Invoices invoices0;

Result

Regenerate the code for the application by right-clicking on the application in the tree view. You need not regenerate the java code for the classes nor recompile it: this is the power of aspect oriented programming.

Launch the application.

The resulting application should look as following.

The invoices demo application

It works also on the WEB: you just need to use the "start web GUI" and "Web GUIs" options in the "Run options" tab or replace the -G option with -W in the command line or windows shortcut.

You can then access your application at http://localhost:8088/org/objectweb/jac/myGUI

The invoices demo application

Important notes

UMLAF helps the programmer to design JAC applications and allows him to easily configure existing aspects (the ones that are provided by the JAC distribution). However, for the moment, the knowlege of the aspect configuration interfaces is still needed. In a short future, the IDE will provide some graphical customization means that will make the programmer task easier.

With UMLAF, the programmer can also create entirely new aspects despite it is not documented yet.