3.4. ArgoUML Basics

The aim of this section is to get you started with ArgoUML. It takes you through obtaining the code and getting it running.

3.4.1. Getting Started System Requirements

Since ArgoUML is written in 100% pure Java, it should run on any machine with Java installed. Java, version 1.4 or later is needed. You may have this in place, but if not it can be downloaded free from www.java.com. Note that you only need the Java Runtime Environment (JRE), there is no need to download the whole Java Development Kit (JDK).

ArgoUML needs a reasonable amount of computing resource. A PC with 200MHz processor, 64Mb RAM and 10Mb of space available on a harddisk should be adequate. Download the code from Download section of the project website argouml.tigris.org. Choose the version that suits your needs as described in the section below. Downloading Options

You have three options for obtaining ArgoUML.

  1. Run ArgoUML directly from the Web Site using Java Web Start. This is the easiest option.

  2. Download the binary executable code. This is the right option if you intend using ArgoUML regularly and is not that difficult.

  3. Download the source code using CVS and build your own version. Choose this option if you want to look at the internal workings of ArgoUML, or want to join in as a developer. This option does require the whole JDK (see Section, “System Requirements”).

All three options are freely available through the project web site, argouml.tigris.org. ArgoUML Using Java Web Start

There are two steps to this.

  1. Install Java Web Start on your machine. This is available from java.sun.com/products/javawebstart, or via the Java Web Start link on the ArgoUML home page.

  2. Click on the Launch latest stable release link on the ArgoUML home page.

Java Web Start will download ArgoUML, cache it and start it the first time, then on subsequent starts, check if ArgoUML is updated and only download any updated parts and then start it. The ArgoUML home page also provides details on starting ArgoUML from the Java Web Start console. Downloading the Binary Executable

If you choose to download the binary executable, you will have a choice of downloading the latest stable version of the code (which will be more reliable, but not have all the latest features), or the current version (which will be less reliable, but have more features). Choose according to your own situation.

ArgoUML comes in .zip or tar.gz flavors. Choose the former if you are a Microsoft Windows user, and the latter if you are running some flavor of Unix. Unpacking is as follows.

  • On Windows. Unzip the .zip file with WinZip, or on later versions of Windows (ME, XP) copy the files out of the compressed folder and put them into a directory of your choosing.

  • On Unix. Use GNU tar to unzip and break out the files to a directory of your choice tar??zxvf??<file>.tar.gz. If you have an older version of tar, the z option may not be available, so use gunzip??<??file.tar.gz??|??tar??xvf??-.

You should have a directory containing a number of .jar files and a README.txt. Problems Downloading

If you get completely stuck and you have no local assistance, try the web site, particularly the FAQ. If this still doesn't solve the problem, try the ArgoUML users' mailing list.

You can subscribe through the mailing lists section of the project web site argouml.tigris.org, or send an empty message to users@argouml.org with the subject line subscribe.

You can then send your problem to users@argouml.org and see how other users are able to help.

The users' mailing list is an excellent introduction to the live activity of the project. If you want to get further involved there are additional mailing lists that cover the development of the product and issues in the current and future releases. Running ArgoUML

To run ArgoUML depends on whether you use Microsoft Windows or some flavor of Unix.

  • On Windows. Start an MSDOS shell window by e.g. using Start/Run with “command” in the text window. In the window change to the directory holding your ArgoUML files and type java??-jar??argouml.jar. This method has the advantage that progress and debugging information is visible in the DOS window. Alternatively create a batch file (.bat) containing the above command, with a shortcut to it on the desktop. The batch file should end with a "pause" statement in case any debugging information is created during a run. On some systems, simply (double) clicking on the argouml.jar file works. On others doing so initiates a zip utility. Refer to you operating system instructions or help facility to determine how to configure this.

  • On Unix. Start a shell window and type java??-jar??argouml.jar Problems Running ArgoUML

It's unusual to encounter problems if you have made a successful download. If you can't solve the problem. Try the users' mailing list (see Section, “Problems Downloading”).

  • Wrong JRE. The most common issue is not having a new enough Java Runtime Environment (it must be 1.4 or later).

  • Wrong language. If the product came up in a language you can't read or just don't want, go to the second leftmost menu item in the menu bar at the top of the screen. Select the bottom most menu entry in the drop down. Figure 3.5, “Setting Language in the Appearance Pane” show this in Russian. Then click on the second tab from the bottom in the column of tabs on the left. Drop down the list as shown in Figure 3.5, “Setting Language in the Appearance Pane”. and select a language. Note that the languages are listed in themselves. The language shown as being selected is German in which the word for “German” is “Deutsch”. You will have to exit ArgoUML and restart it for the change to take effect. Use the X button at the upper right.

Figure 3.4. Finding the Settings Wizard

Finding the Settings Wizard

Figure 3.5. Setting Language in the Appearance Pane

Setting Language in the Appearance Pane

3.4.2. The ArgoUML User Interface

Before beginning the Case Study, you need to become familiar with the user interface. Start by reading the introduction to the User Interface Reference. See Chapter 8, Introduction.

As you go through this tutorial you will be told what to do, and when to do it but how to do it will often be left to the User Interface Reference. It is not necessary at this point to read all of the Reference, but you should leaf through enough of it to become familiar with how to find things in it. Every attempt will be made to direct you to the appropriate part of the Reference at those points in the tutorial where they apply.

Figure 3.6, “Initial ArgoUML window”, shows the main ArgoUML window as it appears when ArgoUML is first entered.

Figure 3.6. Initial ArgoUML window

Initial ArgoUML window

Grab the vertical divider bars and move them back and forth. Grab the horizontal divider bar and move it up and down. Play around a little with the little arrows at the left or top of the divider bars. See Section 8.3, “General Information About Panes”;. The Explorer Pane

At this time you should take the time to read Chapter 11, The Explorer. There is not a lot that you can do at this point with the Explorer Pane as there is nothing in it but the root of the tree (currently "untitledModel") and two empty diagrams. However, the Explorer Pane is fundamental to almost everything that you do and we will be coming back to it again and again in what follows.

There is an expand or contract control in front of the package symbol for “untitledModel” in the Explorer Pand and the package symbol for “Medium” in the To-Do Pane. Click on these controls and observe that these panes are tree widgets that behave pretty much as you would expect them to. The expand or contract control is either plus (+)/minus (-) sign or knob with a right or bottom pointer depending upon the look and feel that you have chosen for an appearance.

At this point you should try the various choices available for a look and feel. You used the editor that establishes the look and feel when you were selecting a language, however, you only saw it in Russian. It you look at an English rendition Section, “Appearance Tab” you will see that the topmost combobox is for selecting the look and feel. When the panel is first opened the box contains the current value. Select another one, exit from ArgoUML and restart it.

Select alternately Class Diagram 1 and Use Case Diagram 1 observing that the detail pane changes to track to the selected item in the Explorer. The detail pane is described in Chapter 12. It is not necessary to read Chapter 12 at this point, but it couldn't hurt. The Editing Pane

  • Reading assignment.
  • Walk through a couple of changes.
  • Add some stuff.
  • Delete some stuff.
  • Resize things.
  • Select stuff with click and drag.
  • Select stuff with click and ctrl click.
  • Edit names inline.
  • Remove "images/tutorial/editoverview.gif" from file system. The Details Pane

  • Reading assignment.
  • To-Do Item. Discuss differences with other tabs about locations of items selected. Hold particulars for discussion of To-Do Pane.
  • Properties,
  • Documentation,
  • Presentation,
  • Source,
  • Constraints,
  • Stereotype,
  • Tagged Values,
  • Checklist.
  • Remove "images/tutorial/detailsoverview.gif" from file system. The To-Do Pane

  • Reading assignment.
  • Describe priorities.
  • Resolving items.
  • Relation to ToDo Item tab in details pane.
  • Remove "images/tutorial/todooverview.gif" from file system. The Menu Bar and Toolbars

The menu bar and toolbars gives access to all the main features of ArgoUML. As is conventional, menu options and toolbar options that are not available are grayed out and menu items that invoke a dialog box are followed by an ellipsis (...).

  • File menu. This allows you to create a new project, save and open projects, import sources from elsewhere, load and save the model to and from a database, print the model, save the graphics of the model, save the configuration of the model and exit ArgoUML

  • Edit menu. This allows you to select one or more UML items on a diagram, undo and redo edits, remove items from diagrams or the whole model, empty the trash and change settings.

  • View menu. This allows you to switch between diagrams, find artifacts in the model, zoom in a diagram, select a particular diagram representation (although at present there is only one), select a particular tab in the details menu, adjust the grid, view buttons on a selection, and switch between UML and Java notation.

  • Create Diagram menu. This allows you to create any one of the seven UML diagram types (class, use case, state, activity, collaboration, deployment and sequence) supported by ArgoUML.

    State and activity diagrams can only be created when a class or actor is selected, even though the relevant menu entries are not grayed out if this has not been done (nothing will happen under this circumstance).

  • Arrange menu. This allows you to align, distribute, reorder and nudge artifacts on a diagram and set the layout strategy for the diagram.

  • Generation menu. This allows you to generate Java code for selected classes or all classes.

  • Critique menu. This allows you to toggle the auto-critique on and off, set the level of importance of design issues and design goals and browse the critics available.

  • Tools menu. This menu is permanently grayed out unless there is some tool available in your version of ArgoUML.

  • Help menu. This menu gives access to details of those who authored the system, and where additional help may be found.

  • File Toolbar. This toolbar contains some of the tools from the File menu.

  • Edit Toolbar. This toolbar contains some of the tools from the Edit menu.

  • View Toolbar. This toolbar contains some of the tools from the View menu.

  • Create Diagram Toolbar. This toolbar contains some of the tools from the Create Diagram menu. The Mouse

The mouse and mouse buttons (or their equivalent with alternative tracking devices) are used in a wide variety of ways. In this section we look at the common modes of use.

ArgoUML assumes a two button mouse. We will refer to the buttons as “button??1” and “button 2”. Button??1 is the leftmost button on a right-handed mouse, and sometimes referred to as the “select” button. Button??2 is sometimes referred to as the “adjust” button.

  1. Button??1 click. This action is generally used to select an item for subsequent operations. If the item is an artifact in the explorer or the editing pane it will be highlighted.

    In the case of the Edit Pane Toolbar, that artifact is selected as the next to be added to the diagram (but only once???see double clicking for adding multiple artifacts). The adding to the diagram is achieved by moving the mouse to the editing area and clicking again.

  2. Button??1 double click. This action is identical to a single click except, when it is used with the edit pane toolbar. Under these circumstances the selected artifact will be added multiple times to the drawing area, once for each further button click, until the tool is again selected or another tool chosen.

  3. Button??2 click. When used over text items in the the explorer or details panes, or graphical artifacts in the editing pane, this will display a context dependent drop-down menu.

    If the item has not yet been selected it will also be selected.

  4. Button??1 motion. Where button??1 click has been used to pull down a menu from the menu bar, button??1 motion is used to select items on that menu.

    Button??1 motion also has an effect in the editing pane. Over graphical artifacts it will move the artifact to a new position. Graphical artifacts that are selected show handles, and these can be used for re-sizing.

    Where the artifact is some form of connector between other items, button??1 motion other than at a handle will cause a new handle to be created, allowing the connector to be articulated at that point. Such new handles can be removed by moving them to the end of the connector.

  5. Button??2 motion. This is used to select items in a context sensitive menu popped up by use of button??2 click.

There are other more specific behaviors that will be encountered under the specific cases where they are used. Drawing Diagrams

In general diagrams are drawn by using the edit pane toolbar to select the artifact desired and clicking in the diagram at the position required as described in Section, “The Mouse”. That section also explains the use of the mouse for re-sizing artifacts.

Artifacts that are already in the model, but not on a diagram, may be added to a diagram by selecting the artifact in the explorer, using Add??to??Diagram from the drop down menu (button??2) over that artifact, and then clicking button??1 at the desired location on the diagram.

As well as UML artifacts, the Edit pane toolbar provides for general drawing artifacts (rectangles, circles, lines, polygons, curves, text) to provide supplementary information on diagrams. Moving Diagram Elements

There are several ways to move diagram elements. Using the Mouse Keys

Select the elements you want to move. By holding down the Ctrl key while selecting you can select several elements to move at the same time.

Now hit your arrow keys. Your elements move a little with every key stroke.

If you also hold down the Shift key, they move a bit faster. Using the Edit Pane Toolbar

Click on the broom button on the toolbar. Move your mouse to the diagram pane, right click and hold. Now moving your mouse will align elements. Arranging Elements

The menu item Arrange allows you to align, group, or nudge elements. Working with Projects The Start-Up Window

Figure 3.6, “Initial ArgoUML window” shows the ArgoUML main window as it appears as right after start-up

The main window's client area, below the menu and toolbar, is subdivided into four panes. Starting at the leftmost top pane, and working around the clock, you can see the Explorer, showing a tree view of your UML model, the Editing Pane with its toolbar, two scroll bars and gray drawing area, the Details Pane with the ToDoItem tab selected, and the To-Do Pane with a tree view of the to do items, ranked in various ways selected via the drop down list at the top of the pane.

Each time ArgoUML is started up without a project file as an argument, a new blank project is created. This project contains a model called untitledModel. This model contains a blank Class Diagram, called class??diagram??1, and a blank Use Case Diagram called use??case??diagram??1.

The model and both empty diagrams can be seen in the explorer, which is the main tool for you to navigate through your model.

Let's assume for a moment that this is the point where you want to start modeling a new purchasing system. You want to give the name “purchasingmodel” to your model, and you want to store it in a file called FirstProject. Saving a Project - The File Menu

For now ArgoUML; saves diagrams using an earlier proposed standard, Precision Graphics Markup Language (PGML). However it has the option to export graphical data as SVG for those who can make use of it. When ArgoUML; supports UML 2.0, it will store diagrams using the UML 2.0 Diagram Interchange format.

First, let's save the model in it's current (empty and unnamed) state. On the menu bar, click on File, then on Save??Project??As... as shown in Figure 3.7, “Invoking Save??Project??As....

Figure 3.7. Invoking Save??Project??As...

Invoking Save??Project??As...

Please notice that the File menu contains the usual options for creating a new project, for opening an existing project, for saving a project under a new name, for printing the currently displayed diagram, for saving the currently displayed diagram as a file, and for program Exit.

Some of these menu commands can be invoked by pressing key combinations, as indicated on the drop-down menu. For instance, holding down the “Ctrl” key, and pressing “N”, will create a new project.

In the current version, ArgoUML can only contain one active project at a time. In addition, a project can only contain one UML model. Since an UML model can contain an unlimited number of elements and diagrams, this should not present any serious limitations, even for modeling quite large and complex systems. The File Chooser Dialog

But let's go back to saving our project. After clicking on the Save??Project??As... menu command, we get the file chooser dialog to enter the file name we wish to use as shown in Figure 3.8, “File Chooser Dialog”.

Figure 3.8. File Chooser Dialog

File Chooser Dialog

This is a standard Java FileChooser. Let's go over it in some detail.

The main, outstanding feature, is the scrollable folders list in the center of the dialog. By using the scroll bar on the right, you can move up and down in the list of folders contained inside the currently selected folder. If it is scrollable or not depends on the amount of files and folders shown and also how they are shown. If everything fits the window is not scrollable as seen in the picture.

Double-clicking on one of the displayed folders navigates you into that folder, allowing you to quickly navigate down into the folders hierarchy on your hard disk.

Notice that only folder names, and no file names are displayed in the scrollable area. Indeed, the dialog is currently set up in order to show only ArgoUML project files with an extension of .zargo, as can be seen on the lower drop-down control labeled Files??of??Type:.

Also notice that the currently selected folder's name is displayed in the upper drop-down control labeled Look??in:. A single click on a folder inside the scrollable area does select that folder on screen but does not select the folder for saving.

At the top of the dialog, above the scrollable folder chooser area, there are a few more folder navigation tools.

  • The Folder drop-down control. Clicking on the down-arrow displays a tree view of the folder hierarchy, allowing you to navigate quickly up the hierarchy, and at the same time to quickly determine where in the hierarchy we are currently positioned.

  • The Folder-Up icon. Clicking on this icon will bring us to the parent folder of the current folder.

  • The Home Folder icon. Clicking on this icon will bring us to our home directory.

  • The New Folder icon. Clicking on this icon will create a new folder called "New Folder" under the current folder. After the folder is created selecting it an clicking in the name allows us to select the name of our choice.

  • The Folders Presentation Icon.

OK, now we navigate to the directory where we want to save our ArgoUML project, fill in the File??name: with an appropriate name, such as “FirstProject” and click on the Save button.

You have now an active project called FirstProject, connected to the file FirstProject.zargo.

3.4.3. Output Loading and Saving Saving XMI files in ArgoUML

ArgoUML saves the diagram information in a PGML file (with extension .pgml, the model information in an XMI file (with extension .xmi and information about the project in a file with extension .argo. See Section, “Precision Graphics Markup Language (PGML)” and Section, “XMI” for more about PGML and XMI respectively.

All of these are then zipped to a file with extension .zargo. You can easily extract the .xmi file from the .zargo file using any old generic ZIP application. Give it a try and look into the magic of Argo.


Be aware that double clicking will launch a ZIP utility, if one is installed, and NOT Argo. Graphics and Printing The Graph Editing Framework (GEF)

GEF is the software package that is the foundation of the diagrams that appear in the Editing Pane. GEF was an integral part of ArgoUML but has been separated. Like ArgoUML it is an open source project available via Tigris. Precision Graphics Markup Language (PGML)

PGML is the current storage format for diagram information used in ArgoUML. In the future, PGML will be replaced by the UML 2.0 Diagram Interchange format. Applications Which Open PGML

PGML is a predecessor of SVG (see Section, “Scalable Vector Graphics (SVG)”. It was dropped by the W3C Consortium.

Currently there are no other tools that we know of working on PGML. Printing Diagrams

Select a diagram, then go to File???Export??Diagrams. You can generate GIF, PostScript, Encapsulated PostScript or SVG format. Scalable Vector Graphics (SVG)

A World Wide Web Consortium (W3C) standard vector graphics format ( http://www.w3.org/TR/SVG/).

Support is built in to modern browsers, but you can also get a plugin for older browsers from adobe.com. Saving Diagrams as SVG
  1. Select .svg as the file type.

  2. Type the name of the file as you like with the .svg tag at the end. Example myumldiagram.svg

Et viola! SVG! Give it a try and zoom around a little... They are not pretty though, so if you know anything about rendering beautiful SVG let us know.

Most modern browsers support SVG. If yours doesn't try Firefox or get a plugin for your current browser from adobe.com


You will not have scroll bars for your SVG unless it is embedded in HTML. Good luck and let us know what you find! XMI

ArgoUML supports XMI 1.0, 1.1, and 1.2 files which contain UML 1.3 and UML 1.4 models. For best compatibility with ArgoUML, export your models using UML 1.4 and XMI 1.1 or 1.2. Be sure to turn off any proprietary extensions (such as Poseidon's diagram data).

With UML versions earlier than UML 2.0, it isn't possible to save diagram information, so no diagrams will be transferred.

There is also a tool that converts XMI to HTML. For more information, see http://www.objectsbydesign.com/projects/xmi_to_html_2.html. Using XMI from Rational Rose

... Using Models Created by Poseidon

In the Export project to XMI dialog, but sure to clear the selection of Save with diagram dataliteral>. Using Models Created by MagicDraw

... XMI Compatibility with other versions of ArgoUML

Versions of ArgoUML prior to 0.19.7 supported UML 1.3/XMI 1.0. After this time, the save format is UML 1.4/XMI 1.2 which is not backward compatible. Newer versions of ArgoUML will read projects written by older versions, but not vice versa. If you might need to return to an older version of ArgoUML you should be careful to save a backup of your old projects.

Additionally, if you write XMI files which need to be read by other tools, you should take into account the different versions. Most modern UML modelling tools should read UML 1.4, but you may have in-house code generators or other tools which are tied to UML 1.3. Importing Other XMI Formats into ArgoUML

XMI compatibility between UML modeling tools has improved over the years, but you may still occasionally run into problems.

ArgoUML will not read XMI files which contain UML 1.5 or UML 2.0 models, but it should be able to open most UML 1.4 and UML 1.3 files. If you find one that it can't open, please file a bug report so that a developer can investigate. Generating XMI Format

Select the command File??? Export??as??XMI and choose a filename. Code Generation Code Generated by ArgoUML

It is possible to compile your generated code with ArgoUML, you still need to implement method bodies, though, to get usable results. Generating Code for Methods

At the moment you cannot write code for methods (operations) within ArgoUML. The source pane is editable, but the changes are ignored. ArgoUML is a pure design tool for now, no IDE functionality but the desire is there. You might consider using Forte and ArgoUML together???it's a good work around!

You can help us out there if you'd like!

3.4.4. Working With Design Critics The To-Do Pane???Messages From the Design Critics

Where do we stand now? A new project has been created, and is connected to the file FirstProject.argo. Figure 3.9, “ ArgoUML Window Having Saved FirstProject.zargo shows how your ArgoUML window should look at this stage.

Figure 3.9.  ArgoUML Window Having Saved FirstProject.zargo

ArgoUML Window Having Saved FirstProject.zargo

The project contains a top-level package, called untitledModel, which contains a class diagram and a use case diagram.

If we look carefully at the screen, we can see that the "Medium" folder in the To Do pane (the lower left pane) must contain some items, since its activation icon is displayed.

Clicking on this icon will open the "Medium" folder. An open folder is indicated by the icon.

But what is this “To-Do” Pane anyway. You haven't recorded anything yet that has to be done, so where do these to do items originate.

The answer is simple, and is at the same time one of the strong points of ArgoUML. While you are working on your UML model, your work is monitored continuously and invisibly by a piece of code called a design critic. This is like a personal mentor that watches over your shoulder and notifies you each time he sees something questionable in your design.

Critics are quite unobtrusive. They give you a friendly warning, but they do not force you into design principles that you don't want or like to follow. Let us take a look at what the critics are telling us. Click on the icon next to the Medium folder, and click on the Revise??Package??Name??UntitledModel item.

Figure 3.10, “ArgoUML Window Showing the Critic Item Revise??Package??Name??UntitledModel shows how your screen should now look.

Figure 3.10. ArgoUML Window Showing the Critic Item Revise??Package??Name??UntitledModel

ArgoUML Window Showing the Critic Item Revise??Package??Name??UntitledModel

Notice that your selection is highlighted in red in the To-Do Pane, and that a full explanation appears now in the Details Pane (the lower right pane). You may have to re-size your Details Pane or to scroll down in order to see the full message as displayed in our example.

What ArgoUML is trying to tell you is that usually, package names are written in lower cases. The default top level package created by ArgoUML is called untitledModel and therefore violates a sound design principle. (Actually, this could be considered as a bug within ArgoUML, but it comes in handy to demonstrate the working of critics).

At this point, you can choose to change the package name manually, to impose silence on the design critic for some time or permanently, or to request a more comprehensive explanation by Email from an expert.

We will do nothing of this (we'll come back to it when we talk about the design critics in more detail) but we'll use another handy feature of ArgoUML???an auto-correct feature.

In order to do that, just click on the Next button on the Details Pane. This will cause a renaming wizard to be displayed inside the properties panel, proposing to use the name untitledmodel (all in lower case). Design Critics at Work: The Rename Package Wizard

Replace the name untitledmodel with purchasingmodel, and click on the Finish button. Figure 3.11, “ArgoUML Window Showing the Critic Wizard to Rename the Package” shows how the ArgoUML window will now look.

Figure 3.11. ArgoUML Window Showing the Critic Wizard to Rename the Package

ArgoUML Window Showing the Critic Wizard to Rename the Package

Watch now how the design critic note in the To Do panel disappears, leaving only the Add??Elements??to??Package??purchasingmodel note in the To-Do list.

If this doesn't happen at once, wait for a few seconds. ArgoUML makes heavy use of several threads of execution that execute in parallel. This can cause delays of a few seconds before the information gets updated on the screen.

The package name change should also be reflected in the explorer, in the top left corner of your ArgoUML window.

We are now ready to create our first UML diagram, a Use Case diagram, but first let's save what we've done so far.

Click on the File menu item, and select Save??Project. You can now safely exit ArgoUML without losing your work so far, or go on creating your first diagram.