Cookbook for Developers of ArgoUML

Information on how to compile ArgoUML. (Chapter 2, Building from source)

Information on how different features of ArgoUML are implemented and how they are to be used. (Chapter 4, ArgoUML Design, The Big Picture and Chapter 5, Inside the subsystems)

Information on how you should write extensions to ArgoUML. (Chapter 6, Extending ArgoUML)

Information that you, as a developer of ArgoUML, need to know about how to contribute. (Chapter 7, Standards for coding in ArgoUML, Chapter 8, Writing Documentation in the ArgoUML Project and Chapter 9, Processes for the ArgoUML project)

You will not find information on how to install and use ArgoUML.

You will not find information on what UML is and if or how you should use it in your project.

You will not find information on how to convince your project to use ArgoUML as a modeling tool.

These are the tools not included in the repository that you need to work with ArgoUML.

For building the documentation from DocBook format, you also need the following tools:

To reduce problems with line endings and to get the headers working, we use the properties on files in the Subversion repository according to the table below.

The properties described here are project conventions and should be applied to the files in the repository. This is normally only needed when creating new files because the existing files should have their properties set correctly.

Alas, Subversion and the Tigris set-up does not allow us in the project to enforce this from the Subversion server end. Instead we rely on each developer and the subversion client installation on each developer's machine to perform this correctly.

To get your subversion client to help you in this, make sure the configuration in your subversion client config file contains settings for this. Your subversion client config file is

Suggested settings:

[miscellany]
enable-auto-props = yes

[auto-props]
### The format of the entries is:
###   file-name-pattern = propname[=value][;propname[=value]...]
### The file-name-pattern can contain wildcards (such as '*' and
### '?').  All entries which match will be applied to the file.
### Note that auto-props functionality must be enabled, which
### is typically done by setting the 'enable-auto-props' option.
*.java = svn:eol-style=native; svn:keywords=Id Author Date Revision
*.properties = svn:eol-style=native
*.sh = svn:eol-style=LF;svn:executable; svn:keywords=Id Author Date Revision
*.bat = svn:eol-style=CRLF; svn:keywords=Id Author Date Revision
*.txt = svn:eol-style=native; svn:keywords=Id Author Date Revision
*.xml = svn:eol-style=native
*.zargo = svn:needs-lock=*

# Picture formats
*.eps = svn:needs-lock=*
*.jpg = svn:mime-type=image/jpeg; svn:needs-lock=*
*.png = svn:mime-type=image/png; svn:needs-lock=*
*.gif = svn:mime-type=image/gif; svn:needs-lock=*

*.pdf = svn:mime-type=application/octet-stream; svn:needs-lock=*
*.PDF = svn:mime-type=application/octet-stream; svn:needs-lock=*

These tools are provided by the development environment that you get when you do a command line check-out, or when you import the argouml-command-line-build.psf Eclipse Team Project Set file, see http://argouml.tigris.org/psf/.

For building the documentation from DocBook format, the following tools are also provided with the command-line check-out development environment or when you import the argouml-doc-projectset.psf Eclipse Team Project Set file, see http://argouml.tigris.org/psf/.

These libraries are provided in the development environment that you get when you check out from the repository. They are checked by the Java compiler when compiling, needed for running ArgoUML and therefore distributed with ArgoUML.

For your convenience the ant tool is present in the source repository of ArgoUML in the file argouml/tools/apache-ant-X.X.X directory.

It is possible to start ant with the command tools/apache-ant-X.X.X/bin/ant arg, ../../tools/apache-ant-X.X.X/bin/ant arg, ../argouml/tools/apache-ant-X.X.X/bin/ant arg, or ../tools/apache-ant-X.X.X/bin/ant arg, depending on if you work from the argouml directory, the argouml/src/argouml-build directory, a module in the argouml-cpp directory, or the argouml/documenation directory respectively.

On windows the script to run is the ant.bat.

To keep you from having to write this and keeping track if you are working with a module or not there are two scripts (one for Unix and one for Windows) that are called build.sh and build.bat respectively present in most of the directories that contain a build.xml file. These two scripts run the equivalence of the above paths.

	Note
	Some of the build.<sh|bat> files have been removed in the repository restructuring, (issue #4625).

By setting JAVA_HOME to different values you can at different times build with different versions of JDK and Java.

To use another version of Ant than the one provided in the repository you must execute /where/ever/you/placed/your/new/ant target rather than build target.

This describes how to do development in one of the ArgoUML sub-projects.

If you are in a hurry:

C:\Work>mkdir argouml
C:\Work>mkdir argouml\build

Download and unpack the latest release of ArgoUML into this directory.

C:\Work>svn checkout http://argouml-XX.tigris.org/svn/argouml-XX/trunk argouml-XX
C:\Work>set JAVA_HOME=C:\Programs\jdkwhatever
C:\Work>cd argouml-XX
C:\Work\argouml-XX>ant run

An ArgoUML starts with the module from the subproject argouml-XX enabled.

That was the short version provided that, you are using Windows + JDK, you have ant installed, and the subproject in question does not require any of the ArgoUML tools to build.

If you don't understand this or it doesn't work, read the rest of the chapter that describes why and how in more detail.

Now this will make all you Java enthusiasts go nuts! We have both class names and method names with a special syntax.

The name of the test case class starts with "Test" (i.e. Capital T, then small e, s and t) or "GUITest" (i.e. Capital G, U, I, T then small e, s, t). The reason for this is that the special targets in trunk/src/argouml-build/build.xml search for test case classes with these names. If you write a test case class that does not comply to this rule, you still can run the test cases in this class manually but they wont be run by other developers and nightly build. If you write support classes for the tests on the other hand, don't name them as a test case to avoid confusion.

Test case classes that don't require GUI components in place have filenames like Test*.java. They must be able to run on a headless system. To make sure that this works, always run your newly developed test cases with build tests. ^[1]

Test case classes that do require GUI components in place have filenames like GUITest*.java.

Every test case class imports the JUnit framework:

and it inherits TestCase (i.e. junit.framework.TestCase).

An ArgoUML class org.argouml.x.y.z stored in the file trunk/src/argouml-app/src/org/argouml/x/y/z.java has its JUnit test case class called org.argouml.x.y.Testz stored in the file trunk/src/argouml-app/tests/org/argouml/x/y/Testz.java containing all the Unit Test Cases for that class that don't need the GUI components to run. Tests that do need GUI components to run should be part of a class named org.argouml.x.y.GUITestz stored in the file trunk/src/argouml-app/tests/org/argouml/x/y/GUITestz.java

If, for convenience reasons, you would like to split the tests of a single class into several test classes, just name them with some extra suffix. Either 1, 2, 3, or something describing what part that test case tests.

If you only want to run your newly written test cases and not all the test cases, you could start with the command build run-with-test-panel and give the class name of your test case like org.argouml.x.y.Testz or org.argouml.x.y.GUITestz. You will then get the output in the window. You could run all tests in this way by specifying the special test suite org.argouml.util.DoAllTests in the same way.

Methods that are tests must have names that start with "test" (i.e. all small t, e, s, t). This is a requirement of the JUnit framework.

Try to keep the test cases as short as possible. There is no need in cluttering them up just to beautify the output. Prefer

// Example from JUnit FAQ
public void testIndexOutOfBoundsExceptionNotRaised()
        throws IndexOutOfBoundsException {
    ArrayList emptyList = new ArrayList();
    Object o = emptyList.get(0);
}

over

public void testIndexOutOfBoundsExceptionNotRaised() {
    try {
        ArrayList emptyList = new ArrayList();
        Object o = emptyList.get(0);
    } catch (IndexOutOfBoundsException iobe) {
        fail("Index out of bounds exception was thrown.");
    }
}

because the code is shorter, easier to maintain and you get a better error message from the JUnit framework.

A lot of times it is useful just to run the compiler to verify that the signatures are correct on the interfaces. Therefore Linus has thought it is a good idea to add methods called compileTestStatics, compileTestConstructors, and compileTestMethods that was thought to include correct calls to all static methods, all public constructors, and all other public methods that are not otherwise tested. These methods are never called. They serve as a guarantee that the public interface of a class will never lose any of the functionality provided by its signature in an uncontrolled way in just the same way as the test-methods serve as a guarantee that no features will ever be lost.

package org.argouml.uml.ui;
import junit.framework.*;

public class GUITestUMLAction extends TestCase {
    public GUITestUMLAction(String name) {
	super(name);
    }

    public void setUp() throws Exception {
	super.setUp();
        InitializeModel.initializeDefault();
    }

    // Testing all three constructors.
    public void testCreate1() {
	UMLAction to = new UMLAction(new String("hexagon"));
	assert("Disabled", to.shouldBeEnabled());
    }
    public void testCreate2() {
	UMLAction to = new UMLAction(new String("hexagon"), true);
	assert("Disabled", to.shouldBeEnabled());
    }
    public void testCreate3() {
	UMLAction to = new UMLAction(new String("hexagon"), true, UMLAction.NO_ICON);
	assert("Disabled", to.shouldBeEnabled());
    }
}

package org.argouml.uml.ui;
import junit.framework.*;

public class TestUMLAction extends TestCase {
    public TestUMLAction(String name) {
	super(name);
    }

    // Functions never actually called. Provided in order to make
    // sure that the static interface has not changed.
    private void compileTestStatics() {
	boolean t1 = UMLAction.HAS_ICON;
	boolean t2 = UMLAction.NO_ICON;
	UMLAction.getShortcut(new String());
	UMLAction.getMnemonic(new String());
    }

    private void compileTestConstructors() {
	new UMLAction(new String());
	new UMLAction(new String(), true);
	new UMLAction(new String(), true, true);
    }

    private void compileTestMethods() {
	UMLAction to = new UMLAction(new String());
	to.markNeedsSave();
	to.updateEnabled(new Object());
	to.updateEnabled();
	to.shouldBeEnabled();
    }

    public void testDummy() { }
}

Test cases are better if they are simpler. Strive to involve as little part of the ArgoUML code as possible. Ideally you are just testing a single class at a time.

The involvement of the Model subsystem is in most cases inevitable since a majority of the classes within ArgoUML use the Model subsystem. Nevertheless, we should, to allow for better and quicker tests, strive to not involve the Model subsystem if possible.

If the Model subsystem is to be involved, it must be initialized. Either with the default implementation (the MDR) or with some other implementation. For testing purposes there exists a Mock implementation that can be used if no functionality is required from the Model subsystem or when testing the Model subsystem itself.

If the Mock model subsystem implementation cannot be used, then the tests have to have the MDR subproject on the class path when running. This is not a problem when running the tests from the ant setup since MDR is always included when running the tests. When running tests from within Eclipse this is a small problem. ^[2]

This means that you should have the following priorities:

We should try to get as many tests from a GUITest* class to the corresponding Test* class because The Test*-classes don't involve the GUI components and are run by automatic builds regularly.

To build the documentation, you will need to check out the trunk of the argouml-documentation project. This contains most of the tools you will need as well as the source code of the manuals. None of the other ArgoUML source directories are needed if you are just building the documentation.

The subdirectories trunk/src/manual, and trunk/src/quickguide contain the source code for each book. The subdirectory trunk/src/docbook-setup contains two things. It contains the configuration files that control how the generation is done. It contains the XSL rules for all the generation. The subdirectory trunk/documentation/xxx/images contains the required pictures for each book.

There are separate build targets available for each output format, as well as a target ('docs') that builds all possible output formats. Use the command build -p to get a complete list of targets.

For testing purposes while editing a manual, you can use a specific target for the document, format, and translation that you are working with.

The manual and quickguide contain multiple translations into different spoken languages. All of the text for all translations is in the same source code file, and a DocBook process called 'profiling' separates the text into the different languages when the documentation is generated.

The build.xml file makes use of the Ant 'macrodef' task. This is used to create parameterised targets for building different documents in different translations. It is very helpful when there are many similar targets. If you are working with the the build file, it suggested that you make yourself familiar with the macrodef task before going further.

The build process for a given target does the following:

The files manual/manual-generated.xml and manual/manual-generated-yy.xml are temporary files that only exists while processing the XML. If you are editing the XML be sure to edit the file manual/manual.xml and not the temporary files. If in doubt, run

 
C:\Work\argouml-documentation>build tidy

to explicitly delete the intermediate files before starting.

The 'clean' target deletes all generated files, including the output files.

These instructions are tested on Eclipse 3.3.1.1, downloading Eclipse IDE for Java developers. Note that if you download Eclipse Classic, you will not need to install the PDE plugin (PDE is included in Eclipse Classic).

If any of these instructions don't work or could be improved in some way, please help in making them better by contacting the editor of the Cookbook.

Here are the ideas governing the layout of the recommended Eclipse set up.

This instruction is for downloading the ArgoUML source through Eclipse.

Eclipse uses Team Project Set (.psf) files to automatically control the check-out from the SVN repository.

Do the following.

	Note
	With the change to project specific settings this need not be done by every developer.

This instruction is to set up Eclipse to work according to the ArgoUML Coding standards. If this is not done correctly you will most likely find that you will have to do a lot of manual edits every time Eclipse has touched the code. You have your tool working against you instead of for you.

The instructions here are for these settings to affect your Eclipse Workspace. If you have other projects in the same Eclipse Workspace you would probably want this for only the ArgoUML projects and that is possible although not explained here. We suggest you to consider having ArgoUML work in an Eclipse Workspace separate from your other projects.

	Note
	With the change to project specific settings this need not be done by every developer.

This instruction is to set up Eclipse to automatically find what, in the ArgoUML project, could be considered problems in the code.

You can apply these individually depending on what level of help you need in your coding. I (Linus Tolke) recommend that you set them all on the Warning level. This makes them visible for you. You can then decide to fix them or not depending on how you feel about the code you are working with.

The instructions on where to find the different settings are for Eclipse 3.2. If you use Eclipse 3.1 you might need to search through the tabs to find where the setting is since they were reorganized for Eclipse 3.2.

	Note
	This description needs to be updated!

Checkclipse is a plug in for Eclipse which needs to be installed separately. It enables style checking according the rules set for the ArgoUML project.

Get the latest Checkclipse kit from SourceForge at http://sourceforge.net/projects/checkclipse and install it by unzipping into your Eclipse plug-ins directory and restarting Eclipse. (Checkstyle is bundled with Checkclipse so it's not necessary to install it separately, but the web site is http://checkstyle.sourceforge.net/ for reference.)

Most ArgoUML projects in Eclipse have their Checkclipse settings predefined which should be found as soon as you install Checkclipse, but if you need to set them up by hand, use the following instructions. These instructions are for Checkclipse 2.1.

In the Java perspective, in the Package Explorer select the project argouml-app. Then, in the menu, select Project => Properties, select Checkclipse (appears only if Checkclipse is correctly installed) and then fill the fields like this:

Leave the rest of the fields at their default (empty). The File Filters are defined on an additional preferences tab rather than in a separate file as in earlier versions of Checkclipse. If this isn't populated with the saved values from SVN you can add individual files to the exclude list as you encounter them, but generally any machine generated source file (JavaLexer, JavaRecognizer, etc) should be excluded from the checks.

Most of the JUnit test cases belong to the argouml-core-tests Eclipse project. The argouml-core-tests Eclipse project has its compile time dependencies set up to include the things needed to compile the test cases. This means that it is possible to compile the test cases and nobody will create tests that use the insides of some subsystem that is supposed to be hidden.

The Model subsystem is separated in two parts:

There is also for test purposes a partly implemented Mock implementation of the model subsystem in the org.argouml.model.MockModelImplementation-class for the purpose of testing the interfaces and the bootstrap code but it requires the test cases to be written especially for that.

The tests are never to be compiled against the MDR-implementation but against the interfaces. This means that the MDR-implementation is not included in the project dependencies.

When it comes to running the tests, most of the tests require the Model subsystem working to succeed. To run the application with a working Model subsystem, a working implementation is needed so the tests require the MDR-implementation.

The simplest way to solve this is to:

The Eclipse set up is prepared to handle work with some ArgoUML subprojects too in the same way. To work on these, or having them enabled in the workspace to spot incompatible changes you do the following:

	Warning
	This description is not yet updated to fit the subversion set up for ArgoUML.

This shouldn't happen! This really shouldn't happen!

The reason that this has happened is that one of the developers has made a mistake. You now must decide a way forward.

REQ1 REVa

Rationale: There is no way of telling where the user is looking while working with ArgoUML. For this reason he might be terribly confused if some other view that happens to show the same element is not showing the same thing.

Stakeholder: User of ArgoUML

REQ2 REVb

Rationale: If a user makes an update of a part of the model, an immediate feedback in all other parts that are currently showing might help him to get it right.

Stakeholder: User of ArgoUML

REQ11 REVa

Rationale: If a user makes an update of a part of the model, an immediate feedback in all other parts that are currently showing might help him to get it right.

Stakeholder: User of ArgoUML

REQ12 REVa

Rationale: If a text field requires validation there exists, by definition, a possibility that the text field is in an invalid state at any time during editing. Therefore the model cannot be updated until the field is completed in a valid state or rejected.

Stakeholder: User of ArgoUML. TODO: Is this the correct stakeholder?

REQ13 REVa

Rationale: It is a common feature of GUIs that a dialog displays a snapshot of its model at the time of creation and only updates that model on the user acceptance of the entire dialog. This is a familiar look and feel for users.

Stakeholder: User of ArgoUML.

REQ14 REVa

Rationale: Writing anything in the correct syntax is complicated. Good compilers are helpful in pinpointing where the problem is (what line and what token is in error). The text fields in ArgoUML are not developed in the same way as source code and we have no compiler step to verify it all. Instead this validation needs to be done while editing meaning that the user needs all the help he can get, as quickly as possible, to get the syntax right. TODO: Is this the correct motivation for this?

Stakeholder: User of ArgoUML.

REQ3 REVa

Rationale: An exception in the log or on the screen is always the sign of a serious error in the application that should be reported as a DEFECT. If a mistyping generates such a problem the user might lose interest in ArgoUML as a tool because he percieves it as not working correctly.

Stakeholder: User of ArgoUML

As follows:

REQ4 REVa

Rationale: Throughout a complex application like ArgoUML there are lots of text fields. Unless there is a possibility to always get this kind of help the user might not be able to make out what he is actually supposed to do in that field.

Stakeholder: User of ArgoUML

REQ5 REVa

Rationale: The vision of ArgoUML is to provide a tool that helps people work with an UML model. The UML model might later on be used in some other tool. If the implementation is not correct then ArgoUML will not be compatible with that other tool or the user will be confused. There might be a lot of tough decisions when it comes to if it is ArgoUML or some other tool that deviates from the UML 1.4 but there shall never be any doubt that the intention of ArgoUML is to implement UML correctly.

Stakeholder: User of ArgoUML

REQ6 REVa

Rationale: The ambition is to implement all of UML. This means that no matter how you use UML ArgoUML will always be a working tool.

Stakeholder: User of ArgoUML

REQ15 REVa

WFR = Well-Formedness Rule. This matter was discussed in the dev list, in the thread following "http://argouml.tigris.org/servlets/ReadMsg?list=dev&msgNo=20622".

1. Critics shall warn for any WFR violations (a critic for every WFR would be ideal).

2. Generally, ArgoUML shall not enforce WFRs, except in certain cases.

3. In such cases (where we enforce a WFR) we shall

a. document this case, and

b. be consistent about it.

4. Even if a WFR is enforced, ArgoUML shall still be able to deal with a model that breaks it. Rationale: since we can load a XMI that breaks the WFR.

Stakeholder: User of ArgoUML

REQ7 REVb

Rationale: The JREs and the adjoining libraries (especially swing) are always improving to include new features and new ideas. The developers of ArgoUML would like to use these new features.

Note: J2SE 1.3.1 begun its Sun End of Life (EOL) process on October 25, 2004.

Stakeholder: Developers of ArgoUML

It shall be possible to install ArgoUML locally on the machine and use without Internet connection.

REQ8 REVa

Rationale: ArgoUML is an application that edits an UML model. There is no need to have any network defined while doing this.

Stakeholder: User of ArgoUML

REQ9 REVa

Rationale: ArgoUML is an application that edits an UML model. Any information written to anywhere but the files that the user specifies the user won't know what to do with and it will be perceived as garbage generated by the ArgoUML application.

Stakeholder: User of ArgoUML

REQ10 REVa

Rationale: When the developers are searching for some problem or when they ask any of the users to help them pinpoint some problem such logging messages are very helpful.

Stakeholder: Developers of ArgoUML

Currently there is a full implementation using NetBeans MDR to store the OMG UML 1.4 metamodel. The previous implementation used the NSUML library to implement a UML 1.3 metamodel.

The decision of which implementation to use is controlled by the Model class which contols the implementations as alternative strategies (as in the Strategy Pattern - GOF p315)

Both helpers and factories (and the Facade and ModelEventPump) are interfaces that are fetched through static methods in the Model object.

Because the same interface is used internally each implementation must provide objects for each of these interfaces.

The helpers contain all utility methods for manipulating model elements. For example, they contain methods to get all model elements of a certain class out of the model (see getAllModelelementsOfKind in ModelManagementHelper).

To find a utility method you need to know where it is. As a rule of thumb, a utility method for some model element is defined in the helper that corresponds with the section in the UML specification. For example, all utility methods for manipulating classes are defined in CoreHelper.

There are a few exceptions to this rule, mainly if the utility method deals with two model elements that correspond to different sections in the UML specification. Then you have to look in both corresponding helpers and you will probably find what you are searching for.

Question: Am I allowed to call the helpers from any thread? Answer: The current checks are not written to allow for multiple threads so don't!

Up to version 0.18.1, ArgoUML used the NSUML model repository internally to implement the UML model. Since version 0.19.1, the NSUML implementation was replaced with the NetBeans Model Data Repository (MDR) which implements the JSR-040 Java Metadata Interface.

All changes to the MDR repository are effectively serialized in the form of change events. The ArgoUML Model-MDR subsystem gets notified before each change with the contents of the change that is about to be made and then again after the change is made. The latter is what we propogate back to the ArgoUML application as model subsystem events.

UUIDs aren't used internally by MDR. We only maintain UUIDs because PGML requires them. MDR has two types of IDs: 1) MOF ID - managed by the repository and guaranteed unique within it for the life of the repository, and 2) xmi.id - used within a single XMI file to link various items together (type references, etc). What gets called a "UUID" is actually the MOF ID of the creating repository. We maintain an internal mapping that gets created every time a new XMI file gets read to map from this "UUID" to the current internal MOF ID.

The Model subsystem is a set of classes that lay between the model implementation (e.g. MDR) and the rest of ArgoUML that hides the APIs of the implementation. It was originally implemented to provide the ability to switch between NSUML and MDR. This is the API classes of the Model subsystem i.e. Factories, Helpers, Event Pump (where to register for changes).

Here follows a list of how different things were done to make the transition easy. Everything within ArgoUML should access the Model subsystem through the interfaces in the org.argouml.model package. The NSUML or MDR and whatever other implementation we eventually come up with would provide the implementation of those interfaces.

Here is an illustration of the main classes implementing critics

Critics are currently located in:

The Base class for Wizards is org.argouml.kernel.Wizard.

Checklists are located in the package org.argouml.cognitive.checklist.

Helper classes for To Do Items, To Do Pane, Wizards and the Knowledge Types are located in the package org.argouml.cognitive.ui.

The multi editor pane is the pane with the diagram editor in it. Normally it is placed in the upper right corner of the application. One of the feature requests is to make the pane dockable so maybe it won't be there in the future.

The multi editor pane consists of tabs that hold editors as you can see in the class diagram.

At the moment there is only one editor tab in place. This is the TabDiagram that shows an UMLDiagram, the target.

The TabDiagram is spawn-able. This means that the user can double click the tab and the diagram will spawn as a separate window.

The target of the MultiEditorPane is set via the setTarget method of the pane. This method is called by the setTarget method of the ProjectBrowser. The pane's setTarget method will call each setTarget method of each tab that is an instance of TabModelTarget. Besides setting the target of the tabs, the setTarget method also calls MultiEditorPane.select(Object o). This selects the new target on a tab. This probably belongs in the setTarget method of the individual tabs and diagrams but that's how it's implemented at the moment.

To add a new element to a diagram, two main things have to be done.

Throughout we shall use the example of adding the UML Extend relationship to a use case diagram. This allows two Use Cases to be joined by a dotted arrow labeled «extend» to show that one extends the behavior of the other.

The classes involved in this particular example have all been well commented and have full Javadoc descriptions, to help when examining the code. You will need to read the description here in conjunction with looking at the code.

The new item must be added to the tool-bar. Both the graph model and diagram renderer for the diagram will need modifying for any new fig object.

private static Action actionUseCase; 

    protected Action getActionUseCase() {
        if (actionUseCase == null) {
            actionUseCase = new RadioAction(new CmdCreateNode(
                    Model.getMetaTypes().getUseCase(), "button.new-usecase"));
        }
        return actionUseCase;
    }

Property Panels for UML model elements are found as class PropPanelXXX.java, where XXX is the UML meta-class. They are in sub-packages of org.argouml.uml.ui corresponding to the UML package which contains the XXX metaclass in the UML specification.

So for our example we create a new class PropPanelExtend in package org.argouml.uml.ui.behavior.use_cases.

Any associated classes that do not fall into the UML classification are provided in org.argouml.uml.ui.

Typically the constructor for the new proppanel class invokes the parent constructor, and then builds the fields required on the property tab. The parent constructor may need an icon. If you need a new icon, a call to lookupIcon() should be made (note that this is a utility method of the parent PropPanel class). For our example we had to add Extend.gif.

You will need to make an icon, in .gif format, 16 X 16 pixels, with the transparent background color set to white. Place this file in the org.argouml.Images directory (it must be named like Name.gif). This icon will automatically be used in the toolbar and in the Navigation pane.

Finally the property panel must be added to the list of property panels in the run() method of the TabProps class, with a new call of panels.put(). If you don't do this, navigation listeners won't know about it!

The content of the property panel is created as a grid with columns (1 column if there are only a few fields, 2 or 3 if there are more). Each row of each column contains a caption (i.e. label) and its corresponding field.

A caption and its field may be added with one of a small number of utility methods which shield you from the layout stuff: addField() and addSeperator().

A button may be added to the toolbar with the utility method addButton().

Every field is built from Java Swing components. However these are extended by ArgoUML to help in the provision of action methods for fields in the property tab. Several fields involve lists, and these require in addition list models to compute the members of the list.

The fields that you might add to a property panel include:

Examples of these fields in more detail follow below.

5.4.1.1. Adding a simple list field

For example we need to add a field to the use case property panel for the extends relationships that derive from this use case.

This field consists of a label and a scrollable pane (JScrollPane) containing the list (JList), which may be empty, or contain extend relationships from this use case.

Rather than a straight JList, we use its child, UMLLinkedList, which adds several features to the standard JList specifically for ArgoUML's properties panels.

The constructor for UMLLinkedList requires two arguments, a list model and a flag to indicate whether to show an icon.

The list model should be a subclass of UMLModelElementListModel2, a subclass of the Swing DefaultListModel which implements AbstractListModel. The UMLModelElementListModel2 implements two interfaces: one that listens to target changes, and one that listens to UML model changes.

5.4.1.1.1. The list model

In our example we create UMLUseCaseExtendListModel. Its constructor takes no arguments. However, we need to provide the parent class with a Model subsystem event name by invoking the constructor of the parent class, with the event name as parameter.

A string naming a Model subsystem event that should force a refresh of the list model. A null value will cause all events to trigger a refresh. The name of the event is the same as the name of the associated attribute or association end from the UML 1.4 metamodel.

This list model should then be provided with a number of methods. The following are mandatory, since they are declared abstract in the parent.

protected void buildModelList()

(Re)Builds the list of elements. Called from targetChanged every time the target of the proppanel is changed.

protected boolean isValidElement(Object/*MBase*/ o)

Returns true if the given element is valid, i.e. it may be added to the list of elements. This function is called for many UML elements, to determine if it fits in the list. Remark: The indication /*MBase*/ is a remainder from the time that ArgoUML included direct references to the NSUML model all over the code. Now it is a practical reminder of what we are dealing with.

	Warning
	The following description is old and the property panels have undergone some fundamental changes since it was written. It would be good if someone that knows how it works now could write a description on how it works now.

The following are sometimes provided as an override of the parent, although for many uses the default is fine.

public void open(int index)

Perform the action associated with the “open” pop-up menu on the element at the given index. The default provided in the parent just navigates to that element.

public boolean buildPopup(JPopupMenu popup, int index)

Build a pop-up menu for the list and return whether it should be displayed. Any actions will be associated with the item at the given index in the list. This is built using UMLListMenuItem, which can record the index, rather than plain JListItem. The default provides open, add, delete, move up and move down, with add disabled if there are already as many elements as the upper bound (if any) for the list, open and delete disabled if there are no elements and move up and move down disabled if they cannot be invoked on the given element. The default implementation always returns true.

The following should be declared as needed to support particular pop-up functions.

public void add(int index)

Perform the actions associated with the “add” pop-up menu on the element at the given index. There is no default provided, so this must be given if the “add” operation is supported. The addAtUtil() method (see below) may prove helpful.

In this routine you may create a new Model subsytem entity. The best way to do this is using a buildXXX method from the appropriate factory so that the appropriate initialization gets done, but you can also use a createXXX method and set it up (don't forget e.g namespace etc) yourself. Remember also to change anything that references the newly created entity.

Warning

NOTE: The following was written regarding NSUML. It may be generally true for the Model subsystem, but this hasn't been verified. NSUML routines generally set up the “other” end of a relationship automatically if you set up one end. If you try to do both (on a NxM relationship) you will probably end up doing it twice. If you do encounter this, the rule of thumb is to explicitly set the ordered end (if you do it the other way round, NSUML will assume you mean the "other" end to be at the end of its ordered list).

public void delete(int index)

Perform the actions associated with the “delete” pop-up menu on the element at the given index. There is no default provided, so this must be given if the “delete” operation is supported.

public void moveUp(int index)

Perform the actions associated with the “move up” pop-up menu on the element at the given index. There is no default provided, so this must be given if the “move up” operation is supported.

public void moveDown(int index)

Perform the actions associated with the “move down” pop-up menu on the element at the given index. There is no default provided, so this must be given if the “move down” operation is supported.

The following normally use the default method, but may be declared to override methods in the parent

public void resetSize()

Called when an external event may have changed the size of the list. The default just sets a flag, which will ensure recalcModelElementSize (see above) is invoked as needed.

public Object formatElement(MModelElement element)

Return an object (invariably a String) that represents an element. The default provided in the parent defers this to the container, which in turn defers it to the current profile. This is usually perfectly satisfactory.

public void targetChanged()

Called when the number of elements in the displayed list (including “none”) may have changed. Default invokes the necessary Swing operations to advise of a change in list size.

public void targetReasserted()

Called when the navigation history has been changed (and navigation buttons may need changing). Not clear why anything is needed, but default recomputes the list size, and invokes the necessary Swing operations.

public void roleAdded(final MElementEvent event)

	Warning
	This describes the old event interface. It needs to be updated.

part of the NSUML EventListener interface. Called when an add event happens, i.e. some Model subsystem object has been added. The default provided looks to see if the event is the role name we declared, or we are listening to all events, and if so looks to see if it relates to an element in our list. If so Swing is notified that the element has been added.

public void roleRemoved(final MElementEvent event)

	Warning
	This describes the old event interface. It needs to be updated.

part of the NSUML EventListener interface. Called when a remove event happens, i.e. some Model subsystem object has been removed. The default provided looks to see if the event is the role name we declared, or we are listening to all events, and if so looks to see if it relates to an element in our list. If so Swing is notified that the element has been removed.

public void recovered(final MElementEvent p1) , public void listRoleItemSet(final MElementEvent p1) , public void removed(final MElementEvent p1) , public void propertySet(final MElementEvent p1)

	Warning
	This describes the old event interface. It needs to be updated.

these are all required as part of the NSUML EventListener interface, which is not well documented. In each case the default implementation recomputes the size, and advises Swing that the entire list has changed. Needs more investigation.

public void navigateTo(MModelElement modelElement)

a request to navigate to the specified object as part of the NavigationListener interface. The default in the parent just invokes navigateTo() on the container (ultimately PropPanel).

The following utility routines are also provided in the parent. They are not normally overridden.

public int getUpperBound()

get any upper bound (-1 is used if there is none).

public void setUpperBound(int newBound)

set the upper bound (-1 is used if there is none).

public final String getProperty()

returns the Model subsystem event name being monitored (null if all are being monitored).

protected final int getModelElementSize()

returns the number of elements in the list. Invokes recalcModelElementSize() (see above) if necessary.

final Object getTarget()

returns the Model subsystem object associated with the container (some child of PropPanel usually) that holds this list model.

final UMLUserInterfaceContainer getContainer()

returns the the container (some child of PropPanel usually) that holds this list model.

public int getSize()

returns the size of the list. Including if there are no elements in the model, but the list has a default text when empty.

public Object getElementAt(int index)

returns the element at the given index in the list.

static protected Collection addAtUtil(Collection oldCollection, MModelElement newItem, int index)

helps in writing the “add” function. newItem is added at the specified index in the given oldCollection.

static protected java.util.List moveUpUtil(Collection oldCollection, int index)

helps in writing the “move up” function. Swaps the elements at offsets index and index-1. Not clear why it doesn't return a Collection.

static protected java.util.List moveDownUtil(Collection oldCollection, int index)

helps in writing the “move down” function. Swaps the elements at offsets index and index-1. Not clear why it doesn't return a Collection.

static protected MModelElement elementAtUtil(Collection collection, int index, Class requiredClass)

helps in writing the getElementAt(). Finds the element at a specific index. The last argument is ignored!

To initialize the profile subsystem you do:

new org.argouml.profile.init.InitProfileSubsystem().init();

This will create a new instance of the class that implements the ProfileManager interface and set ProfileFacade to use this instance of ProfileManager... Which, by the way is currently ProfileManagerImpl, from the org.argouml.profile.internal package. Check Figure 5.6, “Sequence diagram of the profile subsystem initialization.” for more details.

Figure 5.6. Sequence diagram of the profile subsystem initialization.

To complete the description we explain how to re-initialize the subsystem:

new org.argouml.profile.init.InitProfileSubsystem().init();

Simple enough?! But, what does it mean from an internal point of view? Well, the prior internal objects that were used by the subsystem are left alone and hopefully the garbage collector will clean the memory they occupy. So, it simply creates new fresh objects and these are attached to ProfileFacade. This is of use in the automated tests, where there is the need to guarantee that the status of the subsystem isn't changed by previously executed test fixtures.

For a profile to be known by the profile subsystem it must be registered. This is done by external entities, like for instance, a language module to register its UML profile would do:

ProfileFacade.register(profile);

Which is a synonym for:

ProfileFacade.getManager().registerProfile(profile);

Another possibility is for the profile manager to register its own profiles. That happens for the UML profile, being created by the profile manager and then registered by it. That also happens for user defined profiles, which consist of XMI files that the user places in some directories and afterwards, using the GUI, marks the directories as containing user defined profiles.

All of these registered profiles have the common base class Profile, which establishes the interface that must be implemented by a profile so that it is registrable. The Figure 5.7, “Class diagram of the Profile class and some derived classes” shows the Profile class and its specialized classes ProfileUML and UserDefinedProfile. ProfileUML is the class that specializes Profile with behavior specific for the UML profile; UserDefinedProfile is a specialization that contains functionality for loading and representing a user defined profile.

Figure 5.7. Class diagram of the Profile class and some derived classes

As it is possible to register a Profile in the ProfileManager, it is possible to unregister it also. A common case is that of a ArgoUML language module, which registers its specific Profile when enabled and unregisters it when it is disabled. Figure 5.8, “Sequence diagram of the registering and unregistering of a profile” illustrates this, standing the module ClassifierRole as a language module which is activated by moduleManager by a call to its operation enable. As part of the activation, module creates the moduleProfile and registers it in the profile subsystem by a call to the register(moduleProfile) operation of the ProfileFacade. The deactivation of the module causes the call to the remove(moduleProfile), which will unregister the moduleProfile in the profile subsystem.

	Note
	The above described scheme for registering a module defined profile is probably deemed for being reviewed if work in progress by Marcos Aurélio is integrated into ArgoUML trunk. For more information see issue #5029: Improve Plugability of Profile Subsystem.

Figure 5.8. Sequence diagram of the registering and unregistering of a profile

After a profile is registered, it may be chosen as a default profile by the user. A default profile is a profile which is added to new projects by default. For this there is the class org.argouml.ui.SettingsTabProfile that is part of the ArgoUML application settings dialog and shows all the registered profiles, being the profiles set as default profiles shown in a specific list.

The ProfileManager is responsible for keeping track of the profiles chosen as default. For this, it has the operations:

Besides the class org.argouml.ui.SettingsTabProfile for handling application wide settings of the profile subsystem, there is the class org.argouml.ui.ProjectSettingsTabProfile to enable the users to modify the profile subsystem project settings, which take the form of an instance of the class org.argouml.kernel.ProfileConfiguration. The class org.argouml.ui.ProjectSettingsTabProfile also shows all the registered profiles, as org.argouml.ui.SettingsTabProfile does, but, this time it is to enable the user to add or remove profiles to an open project. In its operation handleSettingsTabSave() the changes the user did are made in the instance of org.argouml.kernel.ProfileConfiguration.

The ProfileConfiguration is a ProjectMember and is part of a Project. It is persisted and loaded to/from a project file by means of an instance of the class org.argouml.persistence.ProfileConfigurationFilePersister. These two classes aren't part of the profile subsystem, but, are closely related. Specifically, the ProfileConfiguration is part of the kernel subsystem and the ProfileConfigurationFilePersister is part of the persistence subsystem.

It all starts with a XMI file containing a model... User defined profiles are simply this, at least from the point of view of the author of the profile. So, to define a profile you start by modeling the profile in an ArgoUML project and then export it as XMI.

The profile subsystem provides means to add additional features to the profiles, but, for this you must get your hands dirty with a bit of java coding. Recall the Profile class in Figure 5.7, “Class diagram of the Profile class and some derived classes”. The additional things that may be added to an ArgoUML profile, but, which require coding are:

Unfortunately these extras are only possible for profiles contained in extension modules, such as the UML profile for C++, or profiles contained within ArgoUML, such as the UML profile of UML. This limitation is caused by the need to load the Java classes that would implement the extended behavior.

	Note
	If the work in progress by Marcos Aurélio is successful and is integrated into ArgoUML it is possible that the above customizations are performed without any Java coding. This could make user defined profiles and module contained profiles virtually equivalent in what concerns the functionality provided. For more information see issue #5029: Improve Plugability of Profile Subsystem.

There is a detail that must be taken into account when defining profiles which is the ProfileReference that must be associated to each profile. See Figure 5.9, “Class diagram of the ProfileReference class and associated classes” for a diagram that shows how these classes are associated with Profile and ProfileModelLoader derived classes.

Figure 5.9. Class diagram of the ProfileReference class and associated classes

When a profile model is loaded, it must be associated with a ProfileReference instance which defines for the profile a path and a public reference (a URL). The path part of a profile reference is something that enables ArgoUML to locate and load the actual XMI file. The public reference is something that will identify the profile uni-vocally, enabling references to model elements of profiles from other models. Specifically it is very important to guarantee that the persisted models that refer to profiles are correctly loaded in other ArgoUML installations than the ones that originally created the models.

The profile subsystem was the result of the Google Summer of Code project of Marcos Aurélio in 2007. Much of the design of Marcos' original purposal is still present in the subsystem. His GSoC mentor was Linus Tolke and the work was integrated into ArgoUML trunk by Tom Morris during September of 2007. Previously Tom Morris was involved in adding support for cross XMI file references, which are required for the profiles to work.

After the bulk of the work in creating and integrating the subsystem, we list some issues that might be of interest to persons that want to go after the reasoning behind some of the decisions that took the subsystem to where it is now or which should be solved to raise the subsystem to a quality level above average:

Follow some of the issues that might affect the future of the subsystem:

In late 2006, the source importers were restructured to make them GUI independent and move as much functionality as possible to common code. Things such as source file selection and class diagram creation which previously had been provided by the specific language importers are now provided as common services, simplifying creation of new language importers. These services also include a GUI independent method for requesting, saving, and restoring any language-specific settings (not fully implemented).

The classes in org.argouml.uml.diagram.static_structure.layout.* hold the Class diagram 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) super-classes. 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 super-classes 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 diagram, a link goes to an 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 objects are sorted within their row then to minimize crossing links between them. Compute the average value of the vertical positions of all linked objects in the row above. Example: we have 2 ranks, 0 and 1, with 3 classes each:

We give the super-classes 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 super-classes here):

Compute the average value of the indexes:

Then sort the subclasses by that value:

So the placement is:

...

The package org.argouml.uml.reveng is supposed to hold those classes that are common to all reverse engineering (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 the moment, but there might be other languages like C++ in the future. With this concept you could mix several languages within a project.

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...

It is an Antlr ( http://www.antlr.org) grammar, based on the Antlr Java parser example. The main difference is that the AST (Abstract Syntax Tree) generation and tree-parser have been removed. The ArgoUML code parses the source file and generates Model subsystem 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. The disadvantage of this approach is that it requires multiple parser passes rather than being able to work from the pre-parsed AST.

The *context classes hold the current context for a package, class etc. When the required information for an object is available, the corresponding Model subsystem object is created. The collection of newly created model elements is returned to the common Import code where it can be used to add the elements to a diagram or diagrams if the user has so requested.

Located in org.argouml.ui.targetmanager.

The purpose of the targetmanager is to have a central spot to manage the list of current targets.

The target of ArgoUML is the element currently selected by the user. This can either be a UML element (an Interface or a Class for example) but it can also be a diagram or anything that is shown on a diagram.

There can be multiple targets in case someone selected multiple items in the explorer or on the diagram. This can be done by shift-clicking or Ctrl-clicking items, or by drawing a box on the diagram around the items to select.

In case multiple targets are selected, the target manager will add each target to the beginning of the list of targets. This way, the first item of the list is the last selected item. Most functions in ArgoUML work on all selected items. However, a few (intentionally) only work on one target, such as the properties panels.

Thanks to the architecture of ArgoUML of Modelelements and Figs, one rule has been decided upon: The list of targets shall not contain any Fig that has an owner. Instead, the owner is enlisted.

The TargetManager is also the manager of the history of targets. Every time the user (or the program) selects a new target, this is recorded in the history. Via navigateBack and navigateForward, the user can browse through the history just like in an ordinary internet browser.

Via an event mechanism this manager makes sure that all objects interested in knowing whether the selection changed are notified.

The TargetManager does not depend on the org.argouml.ui package, nor any of its sub-packages. Hence, it can be used by all of these to modify the target, or get it.

In a discussion on the dev list, it has been decided that the TargetManager is GUI state, and hence shall be a part of the GUI subsystem, and should not be used anywhere outside the GUI subsystem. However, currently the TargetManager is used in other subsystems, e.g. the Project. Hence, this needs refactoring.

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, tool-bar, 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 project file or a create newly generated project.

The Details pane contains several tabs: Property Panels (See Section 5.4, “Property panels”, Critics explanations and wizards (belonging to the Critics subsystem) (See Section 5.2, “Critics and other cognitive tools”), Documentation, Style, Source, Constraints (OCL constraints on the current object. See Section 5.22, “OCL”), and Tagged values.

	Warning
	It is not clear in what subsystem Documentation, Style, Source, and Tagged values belong.

The problems with internationalization are not so much the technical problems as to how it works but more so the problems are with getting, keeping and coordinating the correct competences to do the job. This comes from the fact that, as would be expected, the different persons working with internationalization often have different native languages which complicates the communication.

To handle this problem for GNU applications there is a community set up around “gettext” with one language team per language working with all “gettext” applications. There are also tools to help the translator do his job delivered with “gettext” that are the same for all the applications. In each of these language teams discussions are held that ensure a consistent use of words over all these applications.

It is for me (Linus Tolke, May 2002) unclear if and how such a community exists for Open Source Java tools and ArgoUML cannot simply benefit from the “gettext” communities since we don't use “gettext” and cannot use the same tools.

To get things done, we organize our own Language Teams for ArgoUML. Each language team is actually just one or several persons that know that language and are eager to work with translating ArgoUML.

The language team has the following responsibilities:

An ArgoUML subproject is created for each Language Team.

The subproject has the following that is used in building a community:

Logging entries in log4j belong to exactly one level.

This list is ordered according to the priority of these logging entries i.e. if logging on level WARN is enabled for a particular class/package, all logging entries that belong to the above levels ERROR and FATAL are logged as well.

In the ArgoUML project have decided to have all loggers private static final with a static initializer.

You should not use System.out.println in ArgoUML Java Code. The only exception of this rule is for output in non-GUI mode like to print the usage message in Main.java.

import org.apache.log4j.Logger;
...
public class theClass {
...
    private static final Logger LOG = 
        Logger.getLogger(theClass.class);

...

    public void anExample() {
        LOG.debug("This is a debug message.");
        LOG.info("This is a info message.");
        LOG.warn("This is a warning.");
        LOG.error("This is an error.");
        LOG.fatal("This is fatal. The program stops now working...");
    }
            

log4j uses the command line parameter -Dlog4j.configuration = URL to configure itself where URL points to the location of your log4j configuration file.

Example 5.3. Various URLs

org/argouml/resource/filename.lcf              

http://localhost/shared/argouml/filename.lcf   

file://home/username/filename.lcf              
            

	Reference to a configuration file filename.lcf within argouml.jar.
	Reference to a configuration file filename.lcf on a remote server/localhost.
	Reference to a configuration file filename.lcf on your localmachine.

[localhost:~] billy% java -Dlog4j.configuration=URL -jar argouml.jar                        
                

<!-- =================================================================== -->
<!-- Run ArgoUML from compiled sources                                   -->
<!-- =================================================================== -->
<target 
    name="run"
 depends="compile">
    <echo message="--- Executing ${Name} ---"/>
    <!-- Uncomment the sysproperty and change the value if you want -->
    <java class
    name="org.argouml.application.Main"

          fork="yes"
          classpath="${build.dest};${classpath}">
          < sysproperty key="log4j.configuration"
                       value="org/argouml/resource/filename.lcf"></sysproperty>
    </java>
</target>
                

Most of the log statements passed in ArgoUML are passed with logging turned off. This means that the only thing log4j should do is to determine that logging is off and return. Log4j has a really quick algorithm to determine if logging is on for a certain level so that is not a problem.

The problem is how to avoid the overhead of all the concatenations, data conversions and temporary objects that would be created otherwise. Even if logging is turned off for DEBUG and/or INFO level.

It is best explained by noticing the following log statement:

        int i;
...
        LOG.debug("Entry number: " + i + " is " + entry[i]);
      

It is quite innocent looking isn't it? That is because the java compiler is very helpful when it comes to handling strings and will convert it to the equivalent of:

        StringBuffer sb = new StringBuffer();
        sb.append("Entry number: ");
        sb.append(i);
        sb.append(" is ");
        sb.append(entry[i].toString());
        LOG.debug(sb.toString());
      

If entry[i] is some object with a lot of calculations this could cause a performance problem. If the toString() methods are simple you are still stuck with the overhead of creating a StringBuffer (and a String from the sb.toString()-statement.

The Explorer must react to user and application events.

User events include

Application events include

The Explorer Subsystem provides/will provide the following APIs:

The Explorer Subsystem provides/will provide the following SPIs:

The APIs collectively represent the Explorer subsystem facade and the SPIs represent plug-ins.

The Explorer is currently shown in the Explorer Pane (org.argouml.ui.NavigatorPane) - the upper left hand pane of ArgoUML.

Except for the Explorer Pane, The Explorer is located in org.argouml.ui.explorer.*. The explorer has been refactored since version 0.15.2 so that it has a slightly more standard Java Swing implementation.

The explorer perspectives provide the different views of the project. They are implemented by sets of PerspectiveRules that get the child nodes for any parent node in the tree.

The Explorer has 3 main subcomponents: a customized JTree, a customized TreeModel and an interface for generating child nodes in the tree which forms the tree Perspective.

Each node is displayed with a name and an Icon, representing the type of node it is in the UML model. This is done using the org.argouml.uml.ui.UMLTreeRenderer (for the Icon), and the text is produced in the convertValueToText(...) method in org.argouml.ui.explorer.ExplorerTree.

The ModuleLoader looks for module jars. It scans through all jars available in the ext directory. See Edit Settings Environment tab. If you turn on logging on the debug level while running ArgoUML you should be able to see what jar files it finds and what it does with them.

A module jar contains the classes, resources and a manifest file. The manifest file points out the class to be loaded. Also notice that the Specification-Title and Vendor must be specified correctly for this to work. [What does "correctly" mean in this context?]

Design:

This is essentially and implementation of the Dynamic Linkage pattern as described in Patterns in Java Volume 1 by Mark Grand ISBN 0-471-25839-3. The whole of ArgoUML Core is the Environment, the classes inheriting Pluggable are the AbstractLoadableClass.

	Note
	This description is for the old moduleloader.

Florent wrote a small tutorial for creating modules. It can be found on the ArgoPNO website.

An external module requires:

New modules that are added to ArgoUML shall reside in whole new packages. Either you put your module classes in your.own.domain .your.package.name or if you want to emphasize the connection to ArgoUML you can use org.argouml.your.package.name where your.package.name is the name of your addition.

Target audiences are the following:

In the longer term it would be desirable to also target the following.

The goals are (in priority order):

I (probably Jeremy Bennet in 2002?) think the existing User Manual is a good start particularly towards the second of these goals.

Here are my (Jeremy Bennet, 2002?) thoughts. I think the user manual is really a set of two books, the tutorial manual (corresponding to Part I of the current manual), and the reference manual (Part II of the current manual)

I (Jeremy Bennet, 2002?) suggest that the tutorial book be based around an OOA&D process (any preferences), and that each UML concept is introduced with each step of the process, followed by an explanation of how to do it under ArgoUML. A simple case study will be needed throughout.

This section has two serious problems. Firstly, I (Linus Tolke, 2004) think Jeremy Bennet wrote this and then started and has completed a lot of the items so they could be checked off. Secondly, keeping this list in a docbook document is not a good idea. It is better to make issues in Issuezilla of it that can be individually closed. I (Linus Tolke 2004) will make issues of the things I think are left to be done and remove this section (unless someone beats me to it). I (Linus Tolke 2006) am still hoping that someone will beat me to it.

The priorities are used in the following manner in ArgoUML: