1 Developer FAQ
ArgoUML is an open source project, so it depends on
people that volunteer to work on it. Especially in the
area of development there is still so much to do!
Everyone who wants to contribute needs to know the
what, where and how to write good quality code, but
getting into it is a big challenge since there are
hundreds of Java files. This developer FAQ is dedicated
to all interested programmers and should help to transfer
the knowledge from the old experts to them. Please
feel free to send more questions and/or answers to the
dev mailing list!
1.1 Prerequisite stuff
1.1.1 Which tools do I need to build ArgoUML?
- CVS for obtaining the latest files via internet
- ANT, the Java make tool to manage compiling and packaging
- JDK, at least version 1.3 (includes the java compiler)
- libs: nsuml.jar, ocl-argo.jar, gef.jar, antlrall.jar
The four libs can be found on this site. If not directly,
then in the latest (unstable) distribution. In the future, they
might be available through CVS, too, which would make your life
much easier. For compiling/building, a simple 'build package'
should be sufficient.
1.1.2 Compiling failed. Any suggestions?
Most compiling problems arise from wrong versions: maybe ANT
or JDK, but most often one of the four libs. A look on the error
messages can help. Get the appropriate version (or, e.g. in the
case of gef.jar, get the sources through CVS and build it on
your own). Another reason for problems is an unclean local
source tree: if yours is in doubt, remove it completely and
get it all again through CVS. If nothing helps, ask the
experts!
1.2 Argo Initialization
1.2.1 Which sources are involved?
Relative to the directory org/argouml, they are mainly:
- application/Main.java,
- kernel/Project.java + xml/argo/ArgoParser.java,
- ui/{ProjectBrowser.java,*Pane.java},
- cognitive/{Designer.java,ui/ToDoPane.java}.
1.2.2 What is loaded/initialized?
It all begins in org.argouml.application.Main: set up
main application frame (org.argouml.ui.ProjectBrowser), the
project (org.argouml.kernel.Project), numerous classes, and
finally as a background thread: cognitive support
(org.argouml.cognitive.Designer) and some more classes.
The ProjectBrowser initializes the menu, toolbar, status bar
and the four main areas:
navigation pane (org.argouml.ui.NavigatorPane),
editor pane (org.argouml.ui.MultiEditorPane),
to do pane (org.argouml.cognitive.ui.ToDoPane), and
details pane (org.argouml.ui.DetailsPane). Then, the actual
project is set to either a read from file project
(see ArgoParser.SINGLETON.readProject(URL) and
ArgoParser.SINGLETON.getProject() in org.argouml.xml.argo.ArgoParser)
or a newly generated project (see Project.makeEmptyProject()).
1.3 Runtime Issues
1.3.1 Which Objects live during a typical session?
(Project, Designer, Globals, NavPane, ToDoPane, ...)
1.3.2 What is their task?
(visual component, model, controller, ...)
1.3.3 How about memory organization, e.g. cleanup?
1.4 Working with Projects
1.4.1 How is a project represented/stored/loaded?
1.4.2 Which sources are involved?
1.4.3 What happens when something is added/removed/modified?
(in the model and/or the diagram)
1.5 Cognitive Support
1.5.1 Which sources are involved?
1.5.2 How do Critics/Checklists work?
1.5.3 How are changes recognized?
1.5.4 How is the connection to the model/diagrams?
1.6 Code Generation
1.6.1 Which sources are involved?
1.6.2 How does it work?
1.6.3 What in the model is (not) considered?
1.6.4 How is Java/C++ specific stuff handled?
1.7 Reverse Engineering
1.7.1 Which sources are involved?
The package org.argouml.uml.reveng is supposed to hold those classes
that are common to all RE packages. At the moment this is the Import
class which is mainly responsible to recognize directories, get their
content and parse every known source file in them. These are only java
files at them moment, but there might be other languages like C++ in
the future. With this concept you could mix several languages within
a project. The DiagramInterface is used to visualize generated NSUML
metamodel objects then.
The package org.argouml.uml.reveng.java holds the Java specific parts
of the current RE code. C++ RE might go to org.argouml.uml.reveng.cc,
or so...
1.7.2 How is the grammar of the target language implemented?
It's a Antlr (
http://www.antlr.org) grammar, based on the Antlr Java parser
example. The main difference is the missing AST (Abstract Syntax Tree)
generation and treeparser. So the original example generates a AST
(a treelike data structure) and then traverses this tree, while the
ArgoUML code parses the source file and generates NSUML objects
directly from the sources. This was done to avoid the memory usage
of an AST and the frequent GC while parsing many source files.
1.7.3 Which model/diagramm elements are generated?
The *context classes hold the current context for a package, class
etc. When the required information for a object is available, the
corresponding NSUML object is created and passed to the DiagramInterface
to visualize it.
1.7.4 Which layout algorithm is used?
The classes in org.argouml.uml.diagram.static_structure.layout.* hold
the Classdiagram layout code. No layout for other diagram types yet.
It's based on a ranking scheme for classes and interfaces. The rank of
a class/interface depends on the total number of (direct or indirect)
superclasses. So if class B extends A (with rank(A)=0), then rank(B)=1.
If C extends B, then rank(C)=2 since it has 2 superclasses A,B. An
implemented interface is treated similar to a extended class. The
objects are placed in rows then, that depend on their rank.
rank(0)=1st row. rank(1) =2nd row (below the 1st one) etc. Example:
In the next diagramm, a link goes to a object that is not in the row
above:
In this case, insert virtual objects which are linked to the actual
target and link to them:
The object are sorted within their row then to minimize crossing links
then. Compute the average value of the vertical positions of all linked
object in the row above. Example: we have 2 ranks 0 and 1 with 3
classes each:
A B C : rank 0
D E F : rank 1
We give the superclasses an index in their rank (assuming that they are
already sorted):
D, E, F have the following links (A, B, C could be interfaces, so I allow
links to multiple superclasses here):
D -> C
E -> A and C
F -> A and B
Compute the average value of the indexes:
D = 2 (C has index 2 / 1 link)
E = 0 + 2 / 2 = 1 (A=0, C=2 divide by 2 links)
F = 0 + 1 / 2 = 0.5 (A=0, B=1, 2 links)
Then sort the subclasses by that value:
F(is 0.5), E(is 1), D(is 2)
So the placement is:
A B C
(here are the links, but I can't hardly paint them as ASCIIs)
F E D
1.8 Graphics Environment (GEF)
1.8.1 What are the basics of GEF (short intro)?
The basic element in GEF is a figure. There are five different kinds
of figures: lines, rectangles, edges, texts and nodes (with groups as
a special case of nodes). Edges and nodes are used as base classes
for UML specific elements like associations, states, classes etc.
There is old documentation, where you can find a
class diagram about GEF.
1.8.2 How and where is the GEF API used for UML?
At the moment there only exists old documentation: about
UML figures and their associated
property panels. Though package names changed a lot, you will
find the mentioned classes in org.argouml.uml.diagram.*(.*)
and org.argouml.uml.ui.foundation.core.* instead.
1.9 UML Meta Model (NSUML)
1.9.1 What are the basics of the used meta model (short intro)?
1.9.2 How and where is the Novosoft API used?
1.9.3 How is the model and its representation (e.g. in diagrams) synchronized?
All changes immediately modify the model that the prop panels, diagrams
and other panels share. (Since one might change one thing in PropPanel,
then tweak something else in the diagram and then possible remove
something from the tree view, keeping the prop panel changes uncommitted
until an apply button is pressed would be undesireable and complicated
to implement.)
|