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=native;svn:executable; 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 of the correct version is present in the source repository of ArgoUML in the file argouml/tools/apache-ant-X.X.X/lib/ant.jar.

It is possible to start ant with the command ../tools/apache-ant-X.X.X/bin/ant arg and in the modules ../../tools/apache-ant-X.X.X/bin/ant arg . On windows the command ..\tools\apache-ant-X.X.X\bin\ant arg runs the program 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 different versions of Ant, you are responsible for installing your own version. Also, 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