Login | Register
My pages Projects Community openCollabNet

Cookbook for Developers of ArgoUML

An introduction to Developing ArgoUML

Edited by

Linus Tolke

Markus Klink

Michiel van der Wulp

Copyright (c) 1996-2007 The Regents of the University of California. All Rights Reserved. Permission to use, copy, modify, and distribute this software and its documentation without fee, and without a written agreement is hereby granted, provided that the above copyright notice and this paragraph appear in all copies. This software program and documentation are copyrighted by The Regents of the University of California. The software program and documentation are supplied "AS IS", without any accompanying services from The Regents. The Regents does not warrant that the operation of the program will be uninterrupted or error-free. The end-user understands that the program was developed for research purposes and is advised not to rely exclusively on the program for any reason. IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

Abstract

The purpose of this Cookbook is to help in coordinating and documenting the development of ArgoUML.

This version of the cookbook is loosely connected to the version PRE-0.25.5 of ArgoUML.


Table of Contents

1. Change Log
1. Introduction
1.1. Thanks
1.2. About the project
1.3. How to contribute
1.4. About this Cookbook
1.4.1. In this Cookbook, you will find...
1.4.2. In this Cookbook, you will not find...
1.5. Mailing Lists
2. Building from source
2.1. Quick Start
2.2. Source layout
2.3. Preparations
2.3.1. What do I need to build ArgoUML?
2.3.2. Configuring Subversion
2.4. The ArgoUML development environment
2.4.1. Which tools are part of the ArgoUML development environment?
2.4.2. What libraries are needed and used by ArgoUML?
2.5. Downloading from the Subversion repository
2.6. Build Process
2.6.1. How Ant is run from the ArgoUML development environment
2.6.2. Developing in a subproject
2.6.3. Troubleshooting the development build
2.7. The JUnit test cases
2.7.1. About the Test case Class
2.7.2. Naming JUnit tests classes
2.7.3. About the Test case Methods
2.7.4. Improving a test case
2.8. Generating documentation
2.8.1. Building documentation
2.9. Setting up Eclipse 3
2.9.1. Eclipse installation instructions
2.9.2. Basic ideas of the set up
2.9.3. Checking out through Eclipse
2.9.4. Eclipse to help with the ArgoUML coding style
2.9.5. Eclipse to automatically find problems in the code
2.9.6. Settings for Checkclipse
2.9.7. Running JUnit test cases from within Eclipse
2.9.8. How to work with the modules
2.10. Settings for NetBeans
2.11. Settings for Emacs
2.12. Making a release
2.12.1. The release did not work
3. ArgoUML requirements
3.1. Requirements for Look and feel
3.1.1. When multiple visual components are showing the same model element they shall be updated in a consistent manner throughout the application.
3.1.2. All views of a model element shall be updated as soon as the model element is updated.
3.1.3. Editable views of the model should update the model on each keystroke and mouse click.
3.1.4. Any text fields that require validation should not be editable directly from a view.
3.1.5. With dialogs, the model is not updated until the dialog is accepted by the user with valid fields.
3.1.6. The user shall receive some visual feedback during the edit process of textual UML to indicate whether the text represents valid UML syntax.
3.1.7. There shall be no indication of an exception on the screen or in the log if it has occured merely because of a user mistyping or not being aware of UML syntax.
3.1.8. All text fields shall have context sensitive help.
3.2. Requirements for UML
3.2.1. ArgoUML shall be a correct implementation of the UML 1.4 model.
3.2.2. ArgoUML shall implement everything in the UML 1.4 model.
3.2.3. About enforcement of well-formedness rules from the UML standard.
3.3. Requirements on java and jvm
3.3.1. Choice of JRE: ArgoUML will support any JRE compatible with a Sun specification of any JRE from Sun that has not begun the Sun End of Life (EOL) process.
3.3.2. Download and start
3.3.3. Console output: Logging or tracing information shall not be written to the console or to any file unless explicitly turned on by the user.
3.4. Requirements set up for the benefit of the development of ArgoUML
3.4.1. Logging: The code shall contain entries logging important information for the purpose of helping Developers of ArgoUML in finding problems in ArgoUML itself.
4. ArgoUML Design, The Big Picture
4.1. Definition of subsystem
4.2. Relationship of the subsystems
4.3. External subsystems
4.4. Low-level subsystems
4.5. View and Control subsystems
4.6. Top Level subsystem
4.7. Loadable subsystems
5. Inside the subsystems
5.1. Model
5.1.1. Design of the subsystem
5.1.2. Factories
5.1.3. Helpers
5.1.4. The model event pump
5.1.5. NSUML specifics
5.1.6. The use of IDs in MDR
5.1.7. How to work against the model
5.1.8. How do I...?
5.2. Critics and other cognitive tools
5.2.1. Main classes
5.2.2. How do I ...?
5.2.3. org.argouml.cognitive.critics.* class diagram
5.3. Diagrams
5.3.1. Multi editor pane
5.3.2. How do I add a new element to a diagram?
5.3.3. How to add a new Fig
5.4. Property panels
5.4.1. Adding the property panel
5.5. Persistence
5.6. Notation
5.7. Reverse Engineering Subsystem
5.7.1. Common import code
5.7.2. Diagram layout algorithms
5.8. Code Generation Subsystem
5.9. Java - Code Generation and Reverse Engineering
5.9.1. How do I ...?
5.9.2. Which sources are involved?
5.9.3. How is the grammar of the target language implemented?
5.9.4. Which model/diagram elements are generated?
5.10. Other source languages (C++, Python, etc)
5.11. The GUI
5.11.1. The TargetManager
5.12. Application
5.12.1. What is loaded/initialized?
5.12.2. Details pane
5.13. Help System
5.14. Internationalization
5.14.1. Organizing translators
5.14.2. Ambitions for localization
5.14.3. How do I ...?
5.15. Logging
5.15.1. What to Log in ArgoUML
5.15.2. How to Create Log Entries...
5.15.3. How to Enable Logging...
5.15.4. How to Customize Logging...
5.15.5. References
5.16. TaskManagement
5.17. Configuration
5.18. To Do items
5.19. Explorer
5.19.1. Requirements
5.19.2. Public APIs and SPIs
5.19.3. Details of the Explorer Implementation
5.19.4. How do I ...?
5.20. Module loader
5.20.1. What the ModuleLoader does
5.20.2. Design of the Module Loader
5.21. OCL
6. Extending ArgoUML
6.1. How do I ...?
6.2. Modules
6.2.1. Modules
6.2.2. Modules
6.2.3. Tip for creating new modules (from Florent de Lamotte)
6.3. How are modules organized in the Java code?
6.3.1. Requirements on modules
6.3.2. How do I ...?
7. Standards for coding in ArgoUML
7.1. When Writing Java Code
7.2. When Committing to the Repository
7.3. When Using Branches
7.4. When Working with the Build Process
7.5. When Considering Dependencies
8. Writing Documentation in the ArgoUML Project
8.1. Introduction
8.2. Style
8.3. Document Conventions
8.4. DocBook Conventions
8.5. For Eclipse Users
8.6. For Emacs Users
8.7. User Manual Plans
8.7.1. Target Audiences for the User Manual
8.7.2. Goals for the User Manual
8.7.3. Suggested Manual Structure
8.7.4. Actions, Priorities and Questions
9. Processes for the ArgoUML project
9.1. The big picture for Issues
9.2. Attributes of an issue
9.2.1. Priorities
9.2.2. Resolutions
9.3. Roles Of The Workers
9.3.1. The Reporter
9.3.2. The Resolver
9.3.3. The Verifier
9.4. How to resolve an Issue
9.5. How to verify an Issue that is FIXED
9.6. How to verify an Issue that is rejected
9.7. How to Close an Issue
9.8. How to relate issues to problems in dependencies
9.9. How to Create a Stable Release
9.10. Moderation of a mailing list
Glossary
Index
A. Further Reading
A.1. Jason Robbins Dissertation
A.1.1. Abstract
A.1.2. Where to find it
A.2. Martin Skinners Dissertation
A.2.1. Abstract
A.2.2. Where to find it
B. Repository Contents
C. Organization of ArgoUML documentation

Change Log

This will also be a log of major design decisions. A major design decision is a decision that changes responsibilities or functions of the subsystems.

Table 1. Changes done

WhenWhatWho
2008-01-20 Added a quick Eclipse instruction. (See Section 2.1, “Quick Start”). Linus Tolke
2008-01-07 Added requirement about enforcement of well-formedness rules. (See Section 3.2.3, “ About enforcement of well-formedness rules from the UML standard. ”). Michiel van der Wulp
2007-01-16 Change to the definition of the subsystem. Added the responsibility for wellformedness rules. (See Section 5.1, “Model”).
[Note]Design decision - Bob Tarling 2007-02-16

The Model subsystem implements wellformedness rules.

Linus Tolke
2007-01-18 Added instructions on how to configure Subversion. (See Section 2.3, “Preparations”). Linus Tolke
2007-01-07 Change to the process of verifying issues to allow the reporter to more freedom. (See Section 9.3, “Roles Of The Workers”, Section 9.5, “How to verify an Issue that is FIXED”, Section 9.6, “How to verify an Issue that is rejected”, and Section 9.7, “How to Close an Issue”). Linus Tolke
2006-12-30 Change how we handle problems in the JRE and other SW not delivered with ArgoUML. (See Section 9.8, “How to relate issues to problems in dependencies”). Linus Tolke
2006-10-07 Removed mentions of CVS. Linus Tolke
2006-10-01 Change the description on how to check out and build with Eclipse to fit the Subversion set up (and Eclipse 3.2). (See Section 2.9, “Setting up Eclipse 3”). Linus Tolke
2006-09-30 Change to describe the new release build mechanism based on subversion (See Section 2.12, “Making a release”). Linus Tolke
2006-09-12 Removed the manual tests. Removed the description on how to publish the documentation. Updated the download and build section for Subversion. (See Chapter 2, Building from source). Linus Tolke
2006-07-14 Added a section on how to run all JUnit test cases from within Eclipse. (See Section 2.9.7.1, “Running all JUnit test cases from within Eclipse”). Linus Tolke
2006-06-24 Added explanation on different kinds of releases and how we work with them. (See Section 9.9, “How to Create a Stable Release”). Linus Tolke
2006-06-19 Added a description on how to run JUnit tests from within Eclipse. (See Section 2.9.7, “Running JUnit test cases from within Eclipse”). Linus Tolke
2006-05-28 Renamed subprojects to dependencies. Linus Tolke
2006-05-14 Split and moved the CVS chapter. One part goes into the Standards for coding chapter and one part goes into a newly created appendix. (See Section 7.2, “When Committing to the Repository”, and Appendix B, Repository Contents). Linus Tolke
2006-05-14 Moved the Terminology into the Cookbook. (See Terminology in the ArgoUML project). Linus Tolke
2006-05-13 Change to the introduction to the ArgoUML project to reflect that there are several Tigris projects involved. (See Chapter 1, Introduction). Linus Tolke
2006-05-13 Moved the User Manual section from chapter 7 to chapter 10. (See Section 8.7, “User Manual Plans”). Moved the rest of chapter 7 to appendix. Linus Tolke
2005-05-01 Removed old description on how to make releases. Added instructions on how to run the installers. Linus Tolke
2006-04-30 Change to the explanation on how to use Eclipse. (See Section 2.9, “Setting up Eclipse 3”). Linus Tolke
2005-10-29 Change to the instructions on how to build ArgoUML to describe how it works with the argouml-mdr project. (See Chapter 2, Building from source and Section 2.9.3, “Checking out through Eclipse”). Linus Tolke
2005-07-22 Removed the /modules/junit. (See Section 2.12, “Making a release”). Linus Tolke
2005-07-19 Change to the descriptions of the Model, Diagrams, and Persistence subsystems (See Section 5.1, “Model”, Section 5.3, “Diagrams”, and Section 5.5, “Persistence”).
[Note]Design decision - Bob Tarling 2005-07-14

The Diagrams subsystem does not store any data. All data it works on is stored in the Model subsystem.

Linus Tolke
2005-07-18 Change to the short list of subsystems and responsibilities. (See Chapter 5, Inside the subsystems). Linus Tolke
2005-06-18 Restructured: all main chapters are now in seperate files. No content changes. Michiel van der Wulp
2005-06-15 Change to how internationalization is done. Subprojects. (See Section 5.14, “Internationalization”). Linus Tolke
2005-06-12 Change to the description on how to set up an Eclipse environment. (See Section 2.9.3, “Checking out through Eclipse”). Linus Tolke
2005-06-11 Change to how to make an announcement. (See Section 2.12, “Making a release”). Linus Tolke
2005-05-23 Change to release building description. (See Section 2.12, “Making a release”). Linus Tolke
2005-05-06 Added instructions on how we work with sub-projects. (See Section 2.6.2.2, “Working in a subproject”). Linus Tolke
2005-05-01 Change to the tools for releases. (See Section 2.12, “Making a release”). Linus Tolke
2005-04-29 Added a diagram explaining Explorer. (See Section 5.19.3, “Details of the Explorer Implementation”). Michiel van der Wulp
2005-03-10 Change to process for verifying issues. Any release after the one where the issue is fixed can be used for verifications. (See Section 9.5, “How to verify an Issue that is FIXED”). Linus Tolke
2005-03-06 Change to description of how to build. src directory is now involved. (See Chapter 2, Building from source). Linus Tolke
2005-03-01 Removed the modules component. (See 6). Linus Tolke
2005-02-01 Change to Model subsystem. (See Section 5.1, “Model”, Section 5.3, “Diagrams”). Added the Persistence subsystem. More work is needed. (See Section 5.5, “Persistence”). Linus Tolke
2005-01-30 Change to the description on how to use the Model subsystem, the ModelFacade does not exist anymore. (See Section 5.1.7, “How to work against the model”). Linus Tolke
2005-01-29 Change to Model subsystem chapter. Removed references to UmlEventPump and clearified how to remove elements using the UmlFactory. (See Section 5.1.4.2.1, “ How do I register a listener for a certain type event ” and Section 5.1.7, “How to work against the model”). Linus Tolke
2005-01-26 Change to requirement of JDK version support. (See Section 3.3.1, “Choice of JRE: ArgoUML will support any JRE compatible with a Sun specification of any JRE from Sun that has not begun the Sun End of Life (EOL) process. ”). Linus Tolke
2005-01-07 Added copyright notices to the files. Linus Tolke
2004-12-30 Change the default year in the copyright notices. Yes, I am a little early. (See Chapter 7, Standards for coding in ArgoUML and Section 2.9, “Setting up Eclipse 3”). Linus Tolke
2004-11-01 Change to the way we generate documentation. The FILENAME.id files are no longer used. (See Section 2.8, “Generating documentation”). Linus Tolke
2004-10-29 Change to the description on how to generate documentation. Better explanation of how it works. (See Section 2.8, “Generating documentation”). Linus Tolke
2004-10-19 Change to How to Contribute. Changed some spelling errors in cookbook.in while at it. (See Section 1.3, “How to contribute”). Linus Tolke
2004-10-11 Changes to description of module loader making the new module loader a fact. (See Section 5.20, “Module loader” and Section 6.2, “Modules ”).
[Note]Design decision - Linus Tolke 2004-10-11

New imperative Module loader.

Linus Tolke
2004-09-17 Change to the description on how to extend ArgoUML. Now module loader described. (See Chapter 6, Extending ArgoUML). Linus Tolke
2004-09-16 Changed the meaning of RESOLVED/LATER. (See 6 f and g in Section 2.12, “Making a release”, and Section 9.2.2, “Resolutions”). Linus Tolke
2004-09-15 Change to design of new module loader. (See Section 5.20.2, “Design of the Module Loader”). Linus Tolke
2004-08-17 Deemphasized the layers and instead describe the subsystems in groups according to the MVC-pattern. (See Chapter 4, ArgoUML Design, The Big Picture and Chapter 5, Inside the subsystems). Linus Tolke
2004-08-17 Change to the definition of the priorities. Now they are defined in terms of how much release blocker they are. (See Section 9.2.1, “Priorities”). Linus Tolke
2004-08-02 Added rationale for not using RESOLVED/REMIND or RESOLVED/LATER (See Section 9.2.2, “Resolutions”). Linus Tolke
2004-07-28 Reorganized the description on how to use Eclipse 3. Added instructions on how to use the Eclipse JUnit test runner. (See Section 2.9, “Setting up Eclipse 3”). Linus Tolke
2004-07-25 Added this Change Log. (See Change Log). Linus Tolke

Chapter 1. Introduction

1.1. Thanks

We, the authors, would like to take the opportunity to thank everyone involved in the creation of this documentation, and especially the people behind setting up the DocBook environment. In particular thanks go out to Alejandro Ramirez, Phillipe Vanpeperstraete and Andreas Rueckert. Thank you!

1.2. About the project

ArgoUML is an open source project, so it depends on people that volunteer to work on it. Especially in the area of development there is still so much to do!

This Cookbook is dedicated to everyone interested in taking part in the ArgoUML project as such and should help to transfer the knowledge from the old experts to them. Please feel free to discuss the ArgoUML project and this Cookbook on dev mailing list!

The ArgoUML project is hosted at Tigris. For best use of the Tigris platform, the ArgoUML project is spread over several Tigris projects with the argouml project as the top project. Each Tigris project has its own list of developers, source repository, issuezilla, web site, set of mailing lists, ... but they are released together.

1.3. How to contribute

You can help, there are big tasks and small tasks waiting for you.

Here is a suggestion on how you could become part of the ArgoUML Project. This could be perceived as a ladder to climb but remember that if so it is firstly a ladder of levels of commitment and time spent by you. You get no prize for climbing higher, you just get more responsibility in the project.

  1. Use ArgoUML.

  2. Report bugs & suggest enhancements.

    There are bugs in ArgoUML. When you use ArgoUML you might encounter them where you least expect it. To help, make sure they are known about i.e. that there exists an issue in Issuezilla describing the problem. You need to be a registered user at Tigris to report bugs but notice that to add further comments to the issue you also need to have gotten a Role in the ArgoUML project.

    Like all good open-source projects, ArgoUML is evolving to meet the needs of its users. We can only do this if we know what users need, so please file enhancement requests.

    To help the developers prioritise work on bugs and enhancements, vote for the ones that you really care about.

    You need to be a registered user at Tigris to report bugs and enhancements (and to vote for them) but notice that to add further comments to the issue you also need to have gotten a Role in the ArgoUML project.

  3. Subscribe to some of the users' mailing lists.

    Discuss how you use ArgoUML in your project and how you promote ArgoUML in your organization. You can also help other users with their ArgoUML-related problems.

    There is one users' mailing list for each language project (Spanish, Swedish, Chinese, ...) for the users that prefer to discuss ArgoUML using that language. These are not currently (May 2006) very active but the main list, the English-speaking list at users@argouml.tigris.org-list, is.

    In some cases there are also users' mailing lists for the specific subproject, for discussing these specific features or uses of them (cpp, andromda, ...). Prefer those if your discussion is for that area.

  4. Apply for an Observer role.

    This shows that you are committed to the project and also allows you to comment on issues.

  5. Familiarize yourself with the project and how we work.

    Suggestion on how to go about this:

    1. Read through most of the User manual and install and run the latest version of ArgoUML.

    2. Subscribe to the issues list.

      You will get updates on all issues so you can monitor what we are doing in the project. (It could be a lot of mails. If it turns out you don't like watching issues in this way, you unsubscribe!)

    3. Subscribe to the commits mailing list of the project that you are interested in.

      You will get updates on all changes that are done to code, documentation, and the web site. (It could be a lot of large mails. If it turns out you don't like watching what is going on in the project in this way you unsubscribe.)

    4. Read the process part of the Developers Cookbook at Chapter 9, Processes for the ArgoUML project.

      This will give you the idea of how the ArgoUML project attempts to release with good quality and especially how we use Issuezilla.

    5. Get the Observer role granted.

      You can apply for the Observer role in any or all of the argouml projects if you like. Choose the ones you are interested in.

      From this point on you can comment on bugs yourself directly in Issuezilla.

      You can also verify issues according to the verification process (see Section 9.5, “How to verify an Issue that is FIXED”).

      This will help you understand the terminology used in the project and also gives you an idea of the current quality of ArgoUML and what needs to be done in the future.

      This is also a very low-commitment level task that could be completed in a couple of minutes (depending on your choice of issue).

    6. Read the rest of the Developers Cookbook.

      There is a lot of stuff discussed in here that is interesting for your understanding of the project and the code.

    7. Check out the source from subversion and build.

  6. Subscribe to some of the dev mailing lists.

    There is one dev mailing list for each project with the purpose of discussing the specifics for that project. Subscribe to as many of them as you'd like and take part.

    The purpose of this is to see what the developers are discussing in the project.

    Monitor the discussions and as soon as you see something discussed where you have an opinion, jump right in!

  7. Familiarize yourself with the code.

    For this a good knowledge of Java is more or less a prerequisite.

    Suggestion on how to go about this:

    1. Take active part in the discussions on the dev-list.

    2. Solve issues registered in Issuezilla or fix other things that you want to pursue.

    3. Convince someone to commit your changes.

      Establish a relationship with one developer of the project you want to work with. That developer will check that your code reaches the quality level that we strive for in the project and obeys the design.

    4. Repeat.

      This can go on until the developer helping you knows that you have good knowledge of the project quality and design and the main problem for you two is that sending, waiting, committing, updating et.c. is extra work.

  8. Apply for a Developer role in the project where you want to contribute.

    This allows you to do commits on your own and you can now increase the pace in which you are working while also increasing your responsibilities in the project.

    This role is granted by the Project leader after he is convinced that you have learned enough about the project with regard to:

    • Understanding and accepting the goals.

    • Understanding where we are in the development process.

    • Understanding the terminology used in the project.

    • Understanding how we use subversion in the project.

    • Understanding the set of tools (ant, JUnit) and how to use them.

  9. Focus your work in a specific area.

    Everybody has different interests and the best contribution is made when someone is allowed to pursue his own interests. Hopefully ArgoUML provides you with interesting challenges to your taste.

  10. Accept responsibility for a specific area.

1.4. About this Cookbook

This document, the Cookbook for Developers of ArgoUML, is provided with the hope of being helpful for the developers of ArgoUML when it comes to learning and understanding how ArgoUML works in order to improve on its functions and features. It may also be of interest for persons that wish to analyze the ArgoUML project for whatever purpose that may be.

1.4.1. In this Cookbook, you will find...

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)

1.4.2. In this Cookbook, you will not find...

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.

1.5. Mailing Lists

All developers MUST subscribe to the mailing list for developers. Please find the details at: http://argouml.tigris.org/servlets/ProjectMailingListList

It is also recommended to join the commits and issues mailing lists. Both give you a good idea of what is going on. Developers should also work with Issuezilla registering or fixing problems found by themselves and others.

Chapter 2. Building from source

Building ArgoUML from source requires a SVN client, a current JDK (Java5 or later), and 350MB of free disk space. All other tools, including the Ant build tool upon which the build is based, are included in the project source tree. If you have these tools and are familiar with them, the next section contains quick instructions to build ArgoUML from source. For more detailed directions, see the following sections.

2.1. Quick Start

We use Eclipse as the suggested development environment when developing ArgoUML. Here is the recommended, step by step instruction to set up your Eclipse development environment:

  1. Download and install Eclipse. This is if you don't already have it installed. See http://www.eclipse.org/downloads/.

    You need the Eclipse IDE for Java EE Developers, Eclipse for RCP/Plug-in Developers, or Eclipse Classic 3.3.2.

  2. Download and install Subclipse. This is if you don't already have it installed in your Eclipse. See http://subclipse.tigris.org/install.html.

  3. Download the Project Set File for the argouml project and save it on your file system.

    The main file is called argouml-core-projectset.psf and is available at http://argouml.tigris.org/nonav/psf/argouml-core-projectset.psf

  4. In a new workspace, Import the Project Set File. The project will download several Eclipse projects and automatically build them.

    If some fails to build, try to do refresh or clean. It should work but there has been reports of problems at first download.

  5. Start argouml using ArgoUML configuration.

Details of this can be found at Section 2.9, “Setting up Eclipse 3”.

If you want to work without Eclipse in Windows, the following commands will build ArgoUML from source and run it. If you are using Unix/Linux, the equivalent commands for your particular shell should work.

C:\Work>svn checkout http://argouml.tigris.org/svn/argouml/trunk/src http://argouml.tigris.org/svn/argouml/trunk/tools argouml --username guest
Password:  (give empty password if prompted)
C:\Work>set JAVA_HOME=C:\Programs\jdkwhatever
C:\Work>cd argouml\src
C:\Work\argouml\src>build run

A newly compiled ArgoUML will open in a new window.

[Note]Note

JDK Java5 or later is required

If you don't understand these instructions or they don't work, please read the rest of the chapter for more detailed instructions on how to build ArgoUML.

2.2. Source layout

The development environment (source layout) of ArgoUML exists in two flavors:

  • The repository layout.

  • The Eclipse layout.

The repository layout is used by the nightly build, when building releases, and when doing development that is not done within Eclipse. This is the traditional layout and the checkout procedure is described in Section 2.5, “Downloading from the Subversion repository”.

The Eclipse layout is used when doing development within Eclipse. This was created to fit with Eclipse way of organizing projects. The checkout procedure is described in Section 2.9.3, “Checking out through Eclipse” and controlled by Eclipse psf files.

The table below show how the code is organized in the different layouts.

Table 2.1. Layout differences

CodeRepository locationThe repository layoutThe Eclipse layout
Subsystems

http://argouml.tigris.org/svn/argouml/
trunk/src/SUBSYSTEM-NAME

WORK/argouml/src/SUBSYSTEM-NAMEWORKSPACE/SUBSYSTEM-NAME
Integration scripts for the core application

http://argouml.tigris.org/svn/argouml/
trunk/src/argouml-build/*

WORK/argouml/src/argouml-build/*WORKSPACE/argouml-build/* (optional)
Subsystems that are separate projects

http://PROJECT-NAME.tigris.org/svn/PROJECT-NAME/
trunk

WORK/PROJECT-NAMEWORKSPACE/PROJECT-NAME
Integration resultN/AWORK/argouml/build or WORK/argouml/src/build?N/A
Tools used for building and testing. This is the tools common to several subsystems.

http://argouml.tigris.org/svn/argouml/
trunk/tools

WORK/argouml/toolsWORKSPACE/argouml-tools
Tools used for release generation

http://argoumlinstaller.tigris.org/
svn/argoumlinstaller/
trunk/*

WORK/argoumlinstaller/N/A
Tools used for static checks

http://argouml-gen.tigris.org/svn/argouml-gen/
trunk/tools

WORK/argouml-gen/toolsN/A ???
Documentation source

http://argouml.tigris.org/svn/argouml/
trunk/documentation

WORK/argouml/documentationWORKSPACE/argouml-documentation
Eclipse psf files

http://argouml.tigris.org/svn/argouml/
trunk/www/psf

WORK/argouml/www/psf (not used)WORKSPACE/psf
Eclipse templates (to use in the workspace or import into each project)

http://argouml.tigris.org/svn/argouml/
trunk/tools/eclipse

WORK/argouml/tools/eclipse (not used)WORKSPACE/argouml-core-tools/eclipse
Tools used for static checks

http://argouml-gen.tigris.org/svn/argouml-gen/
trunk/tools

WORK/argouml-gen/toolsN/A ???
Src of released subsystem from core project

http://argouml.tigris.org/svn/argouml/
releases/RELEASE-TAG/src/SUBSYSTEM-NAME

WORK/argoumlinstaller/build/RELEASE-TAG/argouml/src/SUBSYSTEM-NAMEN/A or WORKSPACE/SUBSYSTEM-NAME (if switched to)
Src of released subsystem from other project

http://PROJECT-NAME.tigris.org/svn/PROJECT-NAME/
releases/RELEASE-TAG

WORK/argoumlinstaller/build/RELEASE-TAG/PROJECT-NAME/N/A or WORKSPACE/PROJECT-NAME (if switched to)

To handle the two layouts the following guidelines for writing ant scripts apply:

  • The same build.xml file is used, both for building from ant in the repository layout and in the Eclipse layout.

  • In argouml/src/subsystem/build.xml use ../subsystem/build/name to refer to files needed to compile and run tests.

    Only references to subsystems depended on are allowed.

    Table 2.2. Allowed subsystem dependencies

    ProjectDepends on (only)
    argouml-core-model-mdrargouml-core-infra, argouml-core-model
    argouml-core-model-eumlargouml-core-infra, argouml-core-model
    argouml-appargouml-core-infra, argouml-core-model (+ argouml-core-model-mdr but only for integration-level tests)
    argouml-core-diagrams-sequence2argouml-core-infra, argouml-core-model, argouml-app
    all other diagram subsystemsargouml-core-infra, argouml-core-model, argouml-app

  • The "jar" target in argouml/src/subsystem/build.xml compiles the code, creates the directory build within subsystem, and copies all exported jars there.

    Since this build depends on jars in depended on subsystems, the target should first run the "jar" target in those subsystems.

    Also jars that are not generated but provided by the subsystem are copied.

  • In the repository layout, the "package" target in argouml/src/argouml-build/build.xml compiles all subsystems, creates the directory build in argouml/src/argouml-build and copies all exported jars from all subsystems there.

    The copying only copies files and not directories. For that reason make sure everything that is exported is in files and everything that is not exported in directories.

    Specially generated java files, the class files as results of the compilation of source and tests, test results, javadoc report, and other generated reports shall be generated in directories to avoid being included in the release.

  • In the Eclipse layout, the "package" target in argouml-build/build.xml (same as above) compiles all subsystems, creates the directory ../argouml/build and copies all exported jars from all subsystems there.

    For this reason no Eclipse project shall be named "argouml".

  • For Modules that are developed in separate Tigris projects in the argouml-name/build.xml file use ../argouml/build/name to refer to files needed to compile and run tests.

    Only references to subsystems depended on are allowed.

    Modules should probably depend on argouml-core-infra, argouml-core-model, and argouml-app and not anything else.

  • The "jar" target in argouml-name/build.xml compiles the code, creates the directory argouml-name/build, and copies all exported jars there.

  • The "install" target in argouml-name/build.xml performs the "jar" target and copies all jars needed by the deployed application to ../argouml/build/ext.

    The release script includes the files from there.

  • For the listed purposes, use the paths listed in the table, in all subsystems and modules.

    Table 2.3. Created things

    WhatWhere (under ./build)
    Result of the compilation of src/tree and build/java/tree classes/tree
    Result of the compilation of tests/tree tests/classes/tree
    Generated java codejava/tree
    XML result from tests tests/reports/junit/output/XML-files
    HTML result from tests tests/reports/junit/output/html/HTML-files
    Complete javadoc reportjavadocs
    Javadoc report exported functions onlyapi
    Instrumented classes from build/classes/tree instrumented/tree

  • Tools that reside in the tools directory are referenced using the property argo.tools.dir. Like this: ${argo.tools.dir}/path to the file

    The tools in question are the tools used for build and testing that are common to several subsystems.

  • Every build.xml file that uses tools from the tools directory shall set the argo.tools.dir property.

    This is done by testing for the existance of the candidate-dir/checkstyle/java.header file and the result should be set to:

    • ../../tools for subsystems in the repository layout.

    • ../argouml-core-tools for subsystems in the Eclipse layout.

    • ../../tools for argouml-build in the repository layout.

    • ../argouml-core-tools for argouml-build in the Eclipse layout.

    • ../tools for documentation in the repository layout.

    • ../argouml-core-tools for documentation in the Eclipse layout.

    • ../argouml/tools for other Tigris projects in the repository layout.

    • ../argouml-core-tools for other Tigris projects in the Eclipse layout.

2.3. Preparations

In order to develop the ArgoUML source it is absolutely mandatory that you work with ArgoUML from the source repository. How you checkout this is described in Section 2.5, “Downloading from the Subversion repository”.

Notice that the source repository contains not only a set of source files but a complete development environment with required tools for working with ArgoUML.

2.3.1. What do I need to build ArgoUML?

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

  • A computer with an Internet connection and free disk space for your work.

    Around 150MB to download everything from the repository. (Currently September 2006 it is 147MB.) Around 200MB to download all and build the tool and the documentation. (Currently September 2006 it is 192MB.) 350MB should be enough to build it all (Javadocs, documentation, classes, ...). (Currently September 2006 it is 299MB.)

  • Subversion for getting the files and committing source code updates. You can also use an IDE with a built-in subversion client.

  • JDK (including the Java compiler)

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

  • DocBook XSL style sheets.

    Rules exist in the file argouml/argouml-documentation/documentation/build.xml for downloading this correctly.

  • Jimi

    Used by FOP for including PNG pictures.

    Detailed instructions:

    1. Download the file jimi1_0.zip from java.sun.com.

    2. Extract the file JimiProClasses.zip. Most unzip applications allow you to specify the output location. If you are using one of these, this step can be combined with the next.

    3. If the previous step put the extracted file elsewhere, copy or move this file into the argouml\tools\lib directory.

2.3.2. Configuring Subversion

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.

Table 2.4. Changes done

PropertyValueComment
svn:keywordsAuthor Date Id Revision All text files, Java files, XML files. This is for the Id-tag at the top of all source files and the Date-tag on some web pages.
svn:eol-stylenative All text files, Java files, XML files, i.e. almost all non-binary files.
svn:executable* This is for the tools of the development environment to work properly.

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

  • On Windows: %APPDATA%\Subversion\config where %APPDATA% is C:\Documents and Settings\your username\Application Data.

  • On Unix/Linux: $HOME/.subversion/config.

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=*

2.4. The ArgoUML development environment

2.4.1.  Which tools are part of the ArgoUML development environment?

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

  • Ant, the tool to manage compiling and packaging.

  • mdrant, the integration allowing to run mdr from ant.

  • ANTLR, for regenerating the built-in parser.

  • JUnit, for running the JUnit test cases.

  • JDepend, for examining the code.

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

  • Saxon for building documentation from DocBook format.

  • fop for generating PDF versions of the DocBook format.

    To build a PDF file with the pictures included you need Jimi which is downloaded separately. See Jimi.

2.4.2. What libraries are needed and used by ArgoUML?

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.

  • MDR, the Netbeans Model Data Repository.

    This library provides services to manipulate both the UML metamodel and the users model. It includes services to serial/deserialize to/from XMI.

    This is included in the files jmi.jar, jmiutils.jar, mdrapi.jar, mof.jar, nbmdr.jar, openide-util.jar.

  • GEF graph editing framework, available from gef.tigris.org.

    If you would like the GEF sources for reference, please consult their web site for directions on checking them out.

  • The OCL package to parse and run the Object Constraint Language things.

    Details about the package are available from SourceForge OCL Compiler.

  • log4j, a library with infrastructure for logs.

  • antlrall, the run-time part of the ANTLR tool.

  • swidgets, a library providing the buttons used by ArgoUML.

    See the project at Swidgets project.

  • toolbar, a library providing the toolbar functions used by ArgoUML.

    See the project at Toolbar project.

2.5. Downloading from the Subversion repository

[Note]Note

If you are using Eclipse, please use the Team Project Set files to check-out ArgoUML, see Section 2.9.3, “Checking out through Eclipse”

The easiest thing to do is to check out the whole argouml project from http://argouml.tigris.org/svn/argouml/trunk. This includes the source code, tools, documentation and web-site, i.e. :

svn checkout http://argouml.tigris.org/svn/argouml/trunk argouml --username guest

If you only want to build argouml, and don't want anything else, you can just download the source code and the tools:

svn checkout http://argouml.tigris.org/svn/argouml/trunk/src http://argouml.tigris.org/svn/argouml/trunk/tools argouml --username guest

If you just want to build the documentation you can just check out the documentation xml files and the tools:

svn checkout http://argouml.tigris.org/svn/argouml/trunk/documentation http://argouml.tigris.org/svn/argouml/trunk/tools argouml --username guest

For the documentation you will also need the file default.properties from http://argouml.tigris.org/svn/argouml/trunk/src/argouml-app/default.properties.

If you only want to work with the web site, just check out the www directory:

svn checkout http://argouml.tigris.org/svn/argouml/trunk/www argouml/www --username guest

When using the "guest" account, use an empty password.

2.6. Build Process

[Note]Note

This needs to be updated with the Eclipse-orientation.

When building from the command line, the build process is driven by Apache Ant using the ant distribution provided in the tools directory.

Ant is a tool written in Java developed for Apache that reads an XML-file with rules telling what to compile to what result and what files to include in what jar-file.

The rule file is named build.xml, and there is one in each mini-project directory: (argouml/src/argouml-app, argouml/src/argouml-core-infra, argouml/src/argouml-core-model, argouml/src/argouml-core-model-euml, argouml/src/argouml-core-model-mdr, and argouml/documentation).

2.6.1. How Ant is run from the ArgoUML development environment

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

2.6.1.1. Compiling for Unix

Here is what you need to do in order to compile and run your checked out copy of ArgoUML under Unix.

  1. JAVA_HOME=/where/you/have/installed/jdk

    export JAVA_HOME

    This is for sh-style shells like sh, ksh, zsh and bash. If you use csh-style shells like csh and tcsh you will instead have to write setenv JAVA_HOME /where/you/have/installed/jdk.

  2. Change the current directory to the directory you are building

    cd /your/checked/out/copy/of/argouml/src

  3. Start Ant with no parameters to get a list of build targets with descriptions

    ./build.sh

  4. Run ArgoUML using ./build.sh run

If you change something, running the run target again will build and run.

In certain cases when something is changed in the argouml project you need to use the clean target to re-compile everything, since we have not set up dependencies correctly.

2.6.1.2. Compiling for Windows

If you do this from Cygwin you work just like for Unix.

  1. set JAVA_HOME=\where\you\have\installed\jdk

  2. Change the current directory to the directory you are building

    cd \your\checked\out\copy\of\argouml\src_new

  3. Start Ant with "-p" parameter to get a list of build targets with descriptions

    build -p

  4. Run ArgoUML using build run

2.6.1.3. Customizing and configuring your build

It is possible to customize your compilation of ArgoUML.

If you issue the command build list-property-files you can see what files are searched for properties.

Don't change the trunk/src/argouml-app/default.properties file (unless you are working with updating the development environment itself). Instead create one of the other files locally on you machine. The properties in these files have precedence over the properties in trunk/src/argouml-app/default.properties.

Remember that if you do this, you have modified your development environment. To be sure that you will not break anything for anyone else when checking in things developed using this modified environment, remove these files temporarily for the compiling and testing you do just before you commit.

2.6.1.4. Building Javadoc

By running Ant again using build prepare-docs the Javadoc documentation is generated and put into trunk/src/build/javadocs.

2.6.1.5. Building one of the modules

If you want to run ArgoUML with modules enabled the build.xmls are set up to do this in two ways:

  1. Test just one module

    1. Build ArgoUML, the package

      This is done with ant package in the trunk/src/argouml-build directory.

    2. Run the module

      This is done with ant run-command in the trunk/modules/whatever directory.

  2. Test several modules together

    1. Build ArgoUML, the package

      This is done with ant package in the trunk/src/argouml-build directory.

    2. Compile and install the modules

      This is done with ant install-command in each of the trunk/modules/whatever directories.

    3. Start ArgoUML

      This is done with ant run in the trunk/src/argouml-build directory.

    This will start ArgoUML with all modules available.

2.6.2. Developing in a subproject

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.

2.6.2.1. The sub-project's relation to ArgoUML

The purpose of a subproject to ArgoUML is to develop things that are run within ArgoUML. In ArgoUML we call them modules, in other tools they are called add-ins or plug-ins.

If you want to start working with a module of your own you could do it by letting the ArgoUML project leader set up a subproject to ArgoUML for you. The benefits are:

  • You will inherit all the infrastructure from the ArgoUML project.

    This includes a site for your Subversion repository, mailing lists, web server..., a common way to set up the project, releases, bug fixes, static checks, and coding guidelines and license.

  • You get a community of ArgoUML developers that might monitor your work and fix problems, especially problems caused by changes that the developer makes to the ArgoUML API.

The draw-backs are:

  • You are forced to use the ArgoUML infrastructure

    Subversion, BSD license, coding guidelines.

  • You are forced to make your module Open Source.

    This is actually a Tigris policy.

If you decide not to make your module a argouml subproject, you can still benefit from using a similar set up as described here but since you have your module repository elsewhere, some adaptations are necessary.

The sub-projects are developed close to the ArgoUML project and reside in a similarly-looking subversion repository. We try to provide a working set of tools and instructions to fit the whole set of projects. These tools are sometimes located in the argouml project and sometimes in the subproject. Also, to compile the module, you need the argouml interfaces, and to run it you need argouml in place. In most cases the argouml interfaces is argouml itself so this distinction is mostly formal.

There are two ways to get the argouml in place w.r.t. your module. The ArgoUML source way and the quicker ArgoUML distribution way.

Using the ArgoUML source way you check out the argouml project alongside the subproject you are going to work with and build it. If you are doing development in the argouml project too, if the subproject in question requires a tool from the argouml project, or if your modules is on the bleeding edge of argouml development and you can't wait for distributions, this is the preferred way. You will need to update and rebuild the argouml project regularly.

Using the ArgoUML distribution way, you check out only your module and then download the ArgoUML distribution and work against that. This is the approach described in the beginning of this section. You will need to download and replace the ArgoUML distribution whenever you need a newer version to work against. You could also, at any point, upgrade to the ArgoUML source way to get to the bleeding edge.

The build.xml ant configuration file in the subproject and the argouml main project are set up to allow for both of these ways.

2.6.2.2. Working in a subproject

Each subproject has its own web site with documentation and plans of the subproject.

The subproject has its own commits mailing list that you need to join to monitor the commits. It also has its own dev mailing list where the people working within that subproject discusses the subproject. Join both of these mailing list to see what is going on in the subproject!

The sub-projects could use their own Issuezilla database but could also be subcomponents in the ArgoUML Issuezilla. If it is a subcomponent you need to acquire an Observer role in the argouml project to work in a subproject.

2.6.2.3. Targets in build.xml in a subproject

The following targets have the same documented meaning in all sub-projects:

  • clean - optional

    Removes files that are generated by running any of the other targets.

  • compile - optional

    Compiles the code. The result is in build/classes.

  • generate - optional

    This is a step that, if it exists, can be run before compile. The result of this is some files that are prerequisites for compile so the compile target runs this automatically.

  • install

    This builds the whole module and copies it into the ext directory in the argouml installation.

    The purpose of the ext directory is so that argouml can be started with several different modules started at once.

  • jar - optional

    This builds the whole module and puts the resulting jar file(s) in build.

  • run

    This starts argouml with this module active.

    This is the way to start this module with the newly compiled source.

  • tests - optional

    This runs all the JUnit test cases available in the module. This probably requires the junit.jar tool from the argouml project.

2.6.3. Troubleshooting the development build

2.6.3.1. Compiling failed. Any suggestions?

It might be that some other developer has made a mistake in checking in things that contain errors, or forgotten to check in some files in a change. Look at the last couple of hours on the developers mailing list! It is probably on fire.

Another reason for problems is an unclean local source tree. This means that if you have updated different parts of your source tree at different times it might contain inconsistencies. If you suspect this, first try to fix it by doing build clean and svn update before trying to build again. If that doesn't work remove your checked out copy completely and get it all again.

Another reason might be that you have an build.properties or argouml.build.properties file that you have been working with earlier and that is doing something. If in doubt, remove those files.

If nothing helps, ask the developers mailing list!

2.6.3.2. Can't commit my changes?

You need to have a developer role in the ArgoUML project or in the subproject you are working with. If you don't, then you cannot do commits yourself. Discuss what you have done and how best to test it on the ArgoUML project developers mailing list or the developers' mailing list for your subproject. Get in contact with the active developers and urge them to commit it for you.

Furthermore the checkout of your copy needs to be done with your Tigris id that has the Developer role. If you for some reason have earlier checked out a copy as guest and then made modifications you may have problems. It is unknown if this is a problem in Subversion. Let the editor know if you find out.

2.7. The JUnit test cases

ArgoUML has a set of automatic test cases using JUnit-framework for testing the insides of the code. The purpose of these are to help in pin-pointing problems with code changes before even starting ArgoUML.

The JUnit test cases reside in a separate directory and run from ant targets in trunk/src/argouml-build/build.xml. They are never distributed with ArgoUML; they are merely a tool for developers.

By running the command build tests guitests or build alltests in trunk/src/argouml-build these test cases are run, each in its own JVM.

Each test case writes its result on the Ant log.

The result is also generated into a browsable report that can be found at build/test/reports/junit/output/html/index.html. This is the same report that is presented as a result from the nightly build.

The test cases' Java source code is located under argouml/tests/org/argouml.

2.7.1. About the Test case Class

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:

import junit.framework.TestCase;

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

2.7.2. Naming JUnit tests classes

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.

2.7.3. About the Test case Methods

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