svn commit: r14048 - branches/work_docbook5_zearin/branch1/documentation/cookbook
[email protected] 16 Jan 2008 03:22:21 -0000
Newsgroups
gmane.comp.lang.uml.argouml.cvs
Message-ID
<[email protected] >
Author: zearin
Date: 2008-01-15 19:22:21-0800
New Revision: 14048
Modified:
branches/work_docbook5_zearin/branch1/documentation/cookbook/building.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/changelog.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/cookbook.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/cookbook_modules.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/documentation_organization.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/documentationstandards.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/extending.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/further_reading.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/glossary.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/inside_subsystems.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/introduction.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/process.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/repository.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/require.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/standard.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemcritics.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemdiagrams.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/subsysteminternationalization.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemlogging.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemmodel.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemnotation.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystempersistence.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystempropertypanels.xml
branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystems.xml
Log:
Cookbook updated to DocBook v5.
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/building.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/building.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/building.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/building.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/building.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/building.xml 2008-01-15 19:22:21-0800
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
// Copyright (c) 1996-2007 The Regents of the University of California. All
@@ -24,2572 +24,1271 @@
// CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT,
// UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
-->
+<chapter
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xml:id="buildingandtools"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink">
+
+ <title>Building from source</title>
+
+ <para>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.</para>
+ <para>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. </para>
+
+ <section xml:id="quickbuild">
+ <title>Quick Start</title>
+
+ <para>If you are using Eclipse 3.1 or later, see <xref xlink:href="eclipse3"
+ /> for quick setup instructions. </para>
+ <para>If you are using Windows, the follow commands will build ArgoUML from source and run it. If you using Unix/Linux, the comparable commands, modified slightly for your particular shell, should work. <programlisting> C:\Work>svn checkout http://argouml.tigris.org/svn/argouml/trunk/src http://argouml.tigris.org/svn/argouml/trunk/src_new http://argouml.tigris.org/svn/argouml/trunk/tools http://argouml.tigris.org/svn/argouml/trunk/lib http://argouml.tigris.org/svn/argouml/trunk/tests argouml --username guest Password: (give empty password if prompted) C:\Work>set JAVA_HOME=<replaceable>C:\Programs\jdkwhatever</replaceable> C:\Work>cd argouml\src_new C:\Work\argouml\src_new>build run </programlisting> A newly compiled ArgoUML will open in a new window. </para>
+ <note>
+ <para>JDK Java5 or later is required</para>
+ </note>
+ <para>That was the compact version for Windows + JDK. Modifying these steps slightly as appropriate for your shell should work on Unix/Linux systems as well. </para>
+ <para>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. </para>
+ </section>
+
+ <section xml:id="starting">
+ <title>Preparations</title>
+ <para>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 <xref
+ endterm="checkout_term" linkend="checkout" />. </para>
+ <para>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. </para>
+ <section>
+ <title>What do I need to build ArgoUML?</title>
+ <indexterm>
+ <primary>Building</primary>
+ <secondary>tools</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Tools</primary>
+ <secondary>needed for building</secondary>
+ </indexterm>
+ <para>These are the tools not included in the repository that you need to work with ArgoUML. </para>
+ <itemizedlist>
+ <listitem>
+ <para>A computer with an Internet connection and free disk space for your work. </para>
+ <para>Around 150MB to download everything from the repository. (Currently September 2006 it is 147MB.) <!-- In March 2003 it was 68MB but CVS was used then. --> Around 200MB to download all and build the tool and the documentation. (Currently September 2006 it is 192MB.) <!-- In March 2003 it is 114MB. --> 350MB should be enough to build it all (Javadocs, documentation, classes, â¦). (Currently September 2006 it is 299MB.) </para>
+ </listitem>
+ <listitem>
+ <para>Subversion for getting the files and committing source code updates. You can also use an IDE with a built-in subversion client. </para>
+ </listitem>
+ <listitem>
+ <para>JDK (including the Java compiler) </para>
+ </listitem>
+ </itemizedlist>
+ <para>For building the documentation from DocBook format, you also need the following tools: </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>DocBook</primary>
+ </indexterm>
+ <indexterm>
+ <primary>XSL style sheets</primary>
+ </indexterm> DocBook XSL style sheets. </para>
+ <para>There exists rules in the <filename>argouml/documentation/build.xml</filename> for downloading this correctly. </para>
+ </listitem>
+ <listitem xml:id="download-jimi">
+ <para>
+ <indexterm>
+ <primary xml:id="download-jimi-name">Jimi</primary>
+ </indexterm> Jimi </para>
+ <para>Used by FOP for including PNG pictures. </para>
+ <para>Detailed instructions: <orderedlist>
+ <listitem>
+ <para>Download the file <filename>jimi1_0.zip</filename> from <link
+ xlink:href="http://java.sun.com/products/jimi/"
+ >java.sun.com</link>. </para>
+ </listitem>
+ <listitem>
+ <para>Extract the file <code>JimiProClasses.zip</code>. 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. </para>
+ </listitem>
+ <listitem>
+ <para>If the previous step put the extracted file elsewhere, copy or move this file into the <filename>argouml\tools\lib</filename> directory. </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Configuring Subversion</title>
+ <para>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. </para>
+ <table>
+ <title>Changes done</title>
+ <tgroup cols="3">
+ <colspec colnum="1" colname="property" colwidth="2*" />
+ <colspec colnum="2" colname="value" colwidth="1*" />
+ <colspec colnum="3" colname="comment" colwidth="5*" />
+ <thead>
+ <row>
+ <entry>Property</entry>
+ <entry>Value</entry>
+ <entry>Comment</entry>
+ </row>
+ </thead>
+ <tbody valign="top">
+ <row>
+ <entry>svn:keywords</entry>
+ <entry>Author Date Id Revision</entry>
+ <entry> 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. </entry>
+ </row>
+ <row>
+ <entry>svn:eol-style</entry>
+ <entry>native</entry>
+ <entry> All text files, Java files, XML files, i.e. almost all non-binary files. </entry>
+ </row>
+ <row>
+ <entry>svn:executable</entry>
+ <entry>*</entry>
+ <entry> This is for the tools of the development environment to work properly. </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>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.. </para>
+ <para>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. </para>
+ <para>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 <itemizedlist>
+ <listitem>
+ <para>On Windows: <filename>%APPDATA%\Subversion\config</filename> where %APPDATA% is <filename>C:\Documents and Settings\<replaceable>your username</replaceable>\Application Data</filename>. </para>
+ </listitem>
+ <listitem>
+ <para>On Unix/Linux: <filename>$HOME/.subversion/config</filename>. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>Suggested settings: <programlisting> [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=* </programlisting>
+ </para>
+ </section>
+ </section>
+
+ <section>
+ <title>The ArgoUML development environment</title>
+
+ <section>
+ <title> Which tools are part of the ArgoUML development environment? </title>
+
+ <indexterm>
+ <primary>Tools</primary>
+ <secondary>used</secondary>
+ </indexterm>
+ <para>These tools are provided by the development environment that you get when you check out from the repository. </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>Ant</primary>
+ </indexterm> Ant, the tool to manage compiling and packaging. </para>
+ </listitem>
+ <listitem>
+ <para>mdrant, the integration allowing to run mdr from ant. </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>ANTLR</primary>
+ </indexterm> ANTLR, for regenerating the built-in parser. </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>JUnit</primary>
+ </indexterm> JUnit, for running the JUnit test cases. </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>JDepend</primary>
+ </indexterm> JDepend, for examining the code. </para>
+ </listitem>
+ </itemizedlist>
+ <para>For building the documentation from DocBook format, these tools are also provided with the development environment that you get when you check out from the repository. </para>
+ <itemizedlist>
+ <listitem>
+ <para>Saxon for building documentation from DocBook format. </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>fop</primary>
+ </indexterm> fop for generating PDF versions of the DocBook format. </para>
+ <para>To build a PDF file with the pictures included you need Jimi that is downloaded separately. See <xref
+ xlink:href="download-jimi" endterm="download-jimi-name" />. </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>What libraries are needed and used by ArgoUML?</title>
+ <para>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. </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>MDR</primary>
+ </indexterm> MDR, the Netbeans Model Data Repository. </para>
+ <para>This library provides services to manipulate both the UML metamodel and the users model. It includes services to serial/deserialize to/from XMI. </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>GEF</primary>
+ </indexterm> GEF graph editing framework, available from <link
+ xlink:href="http://gef.tigris.org">gef.tigris.org</link>. </para>
+ <para>If you would like the GEF sources for reference, please consult their web site for directions on checking them out. </para>
+ </listitem>
+ <listitem>
+ <para>The OCL package to parse and run the Object Constraint Language things. </para>
+ <para>Details about the package are available from SourceForge <link
+ xlink:href="http://dresden-ocl.sourceforge.net/"
+ >OCL Compiler</link>. </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>log4j</primary>
+ </indexterm> log4j, a library with infrastructure for logs. </para>
+ </listitem>
+ <listitem>
+ <para>antlrall, the run-time part of the ANTLR tool. </para>
+ </listitem>
+ <listitem>
+ <para>MDR, the Netbeans Meta Data Repository. </para>
+ <para>This is included in the files jmi.jar, jmiutils.jar, mdrapi.jar, mof.jar, nbmdr.jar, openide-util.jar. </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+
+ <section xml:id="checkout">
+ <title xml:id="checkout_term">Download from the Subversion repository</title>
+
+ <indexterm>
+ <primary>CVS</primary>
+ <secondary>checking out from</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Checking out from CVS</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Subversion</primary>
+ <secondary>checking out from</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Checking out from Subversion</primary>
+ </indexterm>
+
+ <para>The easiest thing to do now, is just check out the whole <parameter>argouml</parameter> project. For this use the Subversion URL http://argouml.tigris.org/svn/argouml/trunk. </para>
+ <para>If you want to limit the download size, by not checking out the images in the <filename
+ class="directory">argouml/documentation</filename> and <filename class="directory"
+ >argouml/www</filename> the repository directories you need to check out to work with ArgoUML are <filename
+ class="directory">argouml/lib</filename>, <filename class="directory"
+ >argouml/tools</filename>, <filename class="directory"
+ >argouml/src_new</filename>, <filename class="directory"
+ >argouml/src</filename>, and <filename class="directory"
+ >argouml/tests</filename>. These are located at the subversion URLs <filename>http://argouml.tigris.org/svn/argouml/trunk/lib</filename>, <filename>http://argouml.tigris.org/svn/argouml/trunk/tools</filename>, <filename>http://argouml.tigris.org/svn/argouml/trunk/src_new</filename>, <filename>http://argouml.tigris.org/svn/argouml/trunk/src</filename>, and <filename>http://argouml.tigris.org/svn/argouml/trunk/tests</filename> respectively. </para>
+ <para>If you just want to build the documentation you check out the directories <filename
+ class="directory">argouml/tools</filename> and <filename class="directory"
+ >argouml/documentation</filename>. These are located at the subversion URLs <filename>http://argouml.tigris.org/svn/argouml/trunk/tools</filename> and <filename>http://argouml.tigris.org/svn/argouml/trunk/documentation</filename> respectively. For the documentation you will also need the file <filename>default.properties</filename> from <filename>http://argouml.tigris.org/svn/argouml/trunk/src_new/default.properties</filename>. </para>
+ <para>If you want to work with the web site you check out the directory <parameter>argouml/www</parameter>. This is located at the subversion URLs <filename>http://argouml.tigris.org/svn/argouml/trunk/www</filename>. </para>
+ <para>If you don't want to acquire a Tigris login to do this you can use the "guest" account with an empty password. </para>
+ </section>
+
+ <section xml:id="Build">
+ <title xml:id="Build_term">Build Process</title>
+
+ <indexterm>
+ <primary>Building</primary>
+ <secondary>ArgoUML</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Ant</primary>
+ </indexterm>
+ <para>The standard ArgoUML build process is driven by Apache Ant, and it is highly recommend that you stick to that. Some developers use the integrated build tools of Eclipse and NetBeans, but always make sure that your work compiles with the standard Ant build process. There are also some Java files generated by magic scripts in Ant that you need to create before opening with the IDE. </para>
+ <para>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. </para>
+ <indexterm>
+ <primary>
+ <filename>build.xml</filename>
+ </primary>
+ </indexterm>
+
+ <para>The rule file is named <filename>build.xml</filename>. There is one of those in every separate build directory (<filename class="directory">argouml/src_new</filename>, <filename class="directory" >argouml/src/<replaceable>whatever</replaceable></filename>, <filename class="directory">argouml/documentation</filename>, and <filename class="directory" >argouml/modules/<replaceable>whatever</replaceable></filename>). </para>
+
+ <section>
+ <title>How Ant is run from the ArgoUML development environment</title>
+
+ <indexterm>
+ <primary>Ant</primary>
+ <secondary>how it is used</secondary>
+ </indexterm>
+
+ <para>For your convenience the ant tool of the correct version is present in the source repository of ArgoUML in the file <filename class="libraryfile">argouml/tools/ant-1.6.2/lib/ant.jar</filename>. </para>
+ <para>It is possible to start ant with the command <command>../tools/ant-1.6.2/bin/ant <replaceable>arg</replaceable></command> and in the modules <command> ../../tools/ant-1.6.2/bin/ant <replaceable>arg</replaceable> </command>. On windows the command <command>..\tools\ant-1.6.2\bin\ant <replaceable>arg</replaceable></command> runs the program <filename>ant.bat</filename>. </para>
+ <para>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 <filename>build.sh</filename> and <filename>build.bat</filename> respectively present in most of the directories that contain a <filename>build.xml</filename> file. These two scripts run the equivalence of the above paths. </para>
+ <para>By setting JAVA_HOME to different values you can at different times build with different versions of JDK and Java. </para>
+ <para>To use different versions of Ant, you are responsible for installing your own version. Also, you must execute <command>/where/ever/you/placed/your/new/ant <replaceable>target</replaceable></command> rather than <command>build <replaceable>target</replaceable></command>. </para>
+
+ <section>
+ <title>Compiling for Unix</title>
+
+ <indexterm>
+ <primary>Compiling</primary>
+ <secondary>Unix</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Unix</primary>
+ <secondary>compilation</secondary>
+ </indexterm>
+
+ <para>Here is what you need to do in order to compile and run your checked out copy of ArgoUML under Unix. </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ <command>JAVA_HOME=<replaceable>/where/you/have/installed/jdk</replaceable></command>
+ </para>
+ <para>
+ <command>export JAVA_HOME</command>
+ </para>
+ <para>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 <command>setenv JAVA_HOME <replaceable>/where/you/have/installed/jdk</replaceable></command>. </para>
+ </listitem>
+ <listitem>
+ <para>Change the current directory to the directory you are building </para>
+ <para>
+ <command>cd <replaceable>/your/checked/out/copy/of/argouml/src_new</replaceable></command>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Start Ant with no parameters to get a list of build targets with descriptions </para>
+ <para>
+ <command>./build.sh</command>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>Ant target</primary>
+ <secondary>run</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>run ant target</primary>
+ </indexterm> Run ArgoUML using <command>./build.sh run</command>
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>If you change something, running the run target again will build and run. </para>
+ <para>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. </para>
+ </section>
+ <section>
+ <title>Compiling for Windows</title>
+ <indexterm>
+ <primary>Compiling</primary>
+ <secondary>Windows</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Windows</primary>
+ <secondary>Compilation</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Compiling</primary>
+ <secondary>Cygwin</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Cygwin Compilation</primary>
+ </indexterm>
+ <para>If you do this from Cygwin you work just like for Unix. </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ <command>set JAVA_HOME=<replaceable>\where\you\have\installed\jdk</replaceable></command>
+ <!-- TODO: MVW: My setting includes a "\" at the end, and works. Does it matter? -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>Change the current directory to the directory you are building </para>
+ <para>
+ <command>cd <replaceable>\your\checked\out\copy\of\argouml\src_new</replaceable></command>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Start Ant with "-p" parameter to get a list of build targets with descriptions </para>
+ <para>
+ <command>build -p</command>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Run ArgoUML using <command>build run</command>
+ </para>
+ </listitem>
+ </orderedlist>
+ </section>
+ <section>
+ <title>Customizing and configuring your build</title>
+ <indexterm>
+ <primary>Compiling</primary>
+ <secondary>customized</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>build.properties</primary>
+ </indexterm>
+ <indexterm>
+ <primary>default.properties</primary>
+ </indexterm>
+ <indexterm>
+ <primary>argouml.build.properties</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Ant target</primary>
+ <secondary>list-property-files</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>list-property-files ant target</primary>
+ </indexterm>
+ <para>It is possible to customize your compilation of ArgoUML. </para>
+ <para>If you issue the command <command>build list-property-files</command> you can see what files are searched for properties. </para>
+ <para>Don't change the <filename class="libraryfile"
+ >argouml/src_new/default.properties</filename> 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 <filename
+ class="libraryfile">argouml/src_new/default.properties</filename>. </para>
+ <para>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. </para>
+ </section>
+ <section>
+ <title>Building Javadoc</title>
+ <indexterm>
+ <primary>Javadoc building</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Building</primary>
+ <secondary>Javadoc</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Ant target</primary>
+ <secondary>prepare-docs</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>prepare-docs ant target</primary>
+ </indexterm>
+ <para>By running Ant again using <command>build prepare-docs</command> the Javadoc documentation is generated and put into <filename
+ class="directory">argouml/build/javadocs</filename>. </para>
+ </section>
+ <section>
+ <title>Building one of the modules</title>
+ <para>If you want to run ArgoUML with modules enabled the <filename>build.xml</filename>s are set up to do this in two ways: <orderedlist>
+ <listitem>
+ <para>Test just one module</para>
+ <orderedlist>
+ <listitem>
+ <para>Build ArgoUML, the package</para>
+ <para>This is done with <command>ant package</command> in the <filename
+ class="directory"
+ >argouml/src_new</filename>-directory. </para>
+ </listitem>
+ <listitem>
+ <para>Run the module</para>
+ <para>This is done with <command>ant run</command>-command in the <filename
+ class="directory"
+ > argouml/modules/<replaceable>whatever</replaceable>
+ </filename>-directory. </para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ <listitem>
+ <para>Test several modules together</para>
+ <orderedlist>
+ <listitem>
+ <para>Build ArgoUML, the package</para>
+ <para>This is done with <command>ant package</command> in the <filename
+ class="directory"
+ >argouml/src_new</filename>-directory. </para>
+ </listitem>
+ <listitem>
+ <para>Compile and install the modules</para>
+ <para>This is done with <command>ant install</command>-command in each of the <filename
+ class="directory"
+ > argouml/modules/<replaceable>whatever</replaceable>
+ </filename>-directories. </para>
+ </listitem>
+ <listitem>
+ <para>Start ArgoUML</para>
+ <para>This is done with <command>ant run</command> in the <filename
+ class="directory"
+ >argouml/src_new</filename>-directory. </para>
+ </listitem>
+ </orderedlist>
+ <para>This will start ArgoUML with all modules available. </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </section>
+ </section>
+ <section>
+ <title>Developing in a subproject</title>
+ <para>This describes how to do development in one of the ArgoUML sub-projects. </para>
+ <para>If you are in a hurry: <programlisting> C:\Work>mkdir argouml C:\Work>mkdir argouml\build </programlisting> Download and unpack the latest release of ArgoUML into this directory. <programlisting> C:\Work>svn checkout http://argouml-<replaceable>XX</replaceable>.tigris.org/svn/argouml-<replaceable>XX</replaceable>/trunk argouml-<replaceable>XX</replaceable> C:\Work>set JAVA_HOME=<replaceable>C:\Programs\jdkwhatever</replaceable> C:\Work>cd argouml-<replaceable>XX</replaceable> C:\Work\argouml-<replaceable>XX</replaceable>>ant run </programlisting> An ArgoUML starts with the module from the subproject argouml-<replaceable>XX</replaceable> enabled. </para>
+ <para>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. </para>
+ <para>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. </para>
+ <section>
+ <title>The sub-project's relation to ArgoUML</title>
+ <para>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. </para>
+ <para>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: <itemizedlist>
+ <listitem>
+ <para>You will inherit all the infrastructure from the ArgoUML project. </para>
+ <para>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. </para>
+ </listitem>
+ <listitem>
+ <para>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. </para>
+ </listitem>
+ </itemizedlist> The draw-backs are: <itemizedlist>
+ <listitem>
+ <para>You are forced to use the ArgoUML infrastructure</para>
+ <para>Subversion, BSD license, coding guidelines. </para>
+ </listitem>
+ <listitem>
+ <para>You are forced to make your module Open Source.</para>
+ <para>This is actually a Tigris policy. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>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. </para>
+ <para>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. </para>
+ <para>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. </para>
+ <para>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. </para>
+ <para>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. </para>
+ <para>The build.xml ant configuration file in the subproject and the argouml main project are set up to allow for both of these ways. </para>
+ </section>
+ <section xml:id="working-with-subproject">
+ <title>Working in a subproject</title>
+ <para>Each subproject has its own web site with documentation and plans of the subproject. </para>
+ <para>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! </para>
+ <para>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. </para>
+ </section>
+ <section>
+ <title>Targets in build.xml in a subproject</title>
+ <para>The following targets have the same documented meaning in all sub-projects: <itemizedlist>
+ <listitem>
+ <para>clean - optional</para>
+ <para>Removes files that are generated by running any of the other targets. </para>
+ </listitem>
+ <listitem>
+ <para>compile - optional</para>
+ <para>Compiles the code. The result is in <filename>build/classes</filename>. </para>
+ </listitem>
+ <listitem>
+ <para>generate - optional</para>
+ <para>This is a step that, if it exists, can be run before compile. The result of this is some files that is a prerequisite for compile so the compile target runs this automatically. </para>
+ </listitem>
+ <listitem>
+ <para>install</para>
+ <para>This builds the whole module and copies it into the <filename>ext</filename> directory in the argouml installation. </para>
+ <para>The purpose of the ext directory is so that argouml can be started with several different modules started at once. </para>
+ </listitem>
+ <listitem>
+ <para>jar - optional</para>
+ <para>This builds the whole module and puts the resulting jar file(s) in <filename>build</filename>. </para>
+ </listitem>
+ <listitem>
+ <para>run</para>
+ <para>This starts argouml with this module active. </para>
+ <para>This is the way to start this module with the newly compiled source. </para>
+ </listitem>
+ <listitem>
+ <para>tests - optional</para>
+ <para>This runs all the JUnit test cases available in the module. This probably requires the <filename>junit.jar</filename> tool from the argouml project. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ </section>
+ <section>
+ <title>Troubleshooting the development build</title>
+ <indexterm>
+ <primary>Troubleshooting</primary>
+ <secondary>development build</secondary>
+ </indexterm>
+ <section>
+ <title>Compiling failed. Any suggestions?</title>
+ <para>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 <link
+ xlink:href="http://argouml.tigris.org/servlets/BrowseList?listName=dev"
+ > developers mailing list</link>! It is probably on fire. </para>
+ <indexterm>
+ <primary>Ant target</primary>
+ <secondary>clean</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>clean ant target</primary>
+ </indexterm>
+ <para>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 <command>build clean</command> and <command>svn update</command> before trying to build again. If that doesn't work remove your checked out copy completely and get it all again. </para>
+ <para>Another reason might be that you have an <filename>build.properties</filename> or <filename>argouml.build.properties</filename> file that you have been working with earlier and that is doing something. If in doubt, remove those files. </para>
+ <para>If nothing helps, ask the <link xlink:href="mailto:[email protected] "
+ >developers mailing list</link>! </para>
+ </section>
+ <section>
+ <title>Can't commit my changes?</title>
+ <indexterm>
+ <primary>Troubleshooting</primary>
+ <secondary>committing changes</secondary>
+ </indexterm>
+ <para>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. </para>
+ <para>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. </para>
+ </section>
+ </section>
+ </section>
+
+ <section xml:id="junittests">
+ <title>The JUnit test cases</title>
+
+ <indexterm>
+ <primary>JUnit testing</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Unit testing of ArgoUML</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Testing ArgoUML</primary>
+ </indexterm>
+
+ <para>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. </para>
+ <para>The JUnit test cases are residing in a separate directory and run from ant targets in the <filename>src_new/build.xml</filename>. They are never distributed with ArgoUML but merely a tool for developers. </para>
+
+ <indexterm>
+ <primary>Ant target</primary>
+ <secondary>tests</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>tests ant target</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Ant target</primary>
+ <secondary>guitests</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>guitests ant target</primary>
+ </indexterm>
+
+ <para>By running the command <command>build tests guitests</command> or <command>build alltests</command> in <filename>src_new</filename> these test cases are run, each in its own JVM. </para>
+ <para>Each test case writes its result on the Ant log. </para>
+ <para>The result is also generated into a browsable report that can be found at <filename>build/test/reports/junit/output/html/index.html</filename>. This is the same report that is presented as a result from the nightly build. </para>
+ <para>The test cases' Java source code is located under <filename>argouml/tests/org/argouml</filename>. </para>
+
+ <section>
+ <title>About the Test case Class</title>
+ <indexterm>
+ <primary>Unit testing of ArgoUML</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Testing ArgoUML</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Test cases</primary>
+ <secondary>writing</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Writing test cases</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Ant target</primary>
+ <secondary>run-with-test-panel</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>run-with-test-panel ant target</primary>
+ </indexterm>
+
+ <para>Now this will make all you Java enthusiasts go nuts! We have both class names and method names with a special syntax. </para>
+ <para>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 <filename>src_new/build.xml</filename> 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. </para>
+ <para>Test case classes that don't require GUI components in place have filenames like <filename>Test<replaceable>*</replaceable>.java</filename>. They must be able to run on a headless system. To make sure that this works, always run your newly developed test cases with <command>build tests</command>.
+ <footnote>
+ <para>When running the tests using <command>build tests</command> the <constant>java.awt.headless</constant> is set to true. This means that awt is started in a mode that disallows actual presentation so no windows will be opened. On any attempt to realize a window a JavaHeadlessException is thrown making the test case fail. </para>
+ </footnote>
+ </para>
+ <para>Test case classes that do require GUI components in place have filenames like <filename>GUITest<replaceable>*</replaceable>.java</filename>. </para>
+ <para>Every test case class imports the JUnit framework: <blockquote> <para> import junit.framework.TestCase; </para> </blockquote> and it inherits <classname>TestCase</classname> (i.e. <classname>junit.framework.TestCase</classname>). </para>
+ </section>
+
+ <section>
+ <title>Naming JUnit tests classes</title>
+
+ <para>An ArgoUML class <classname>org.argouml.<replaceable>x.y</replaceable>.<replaceable>z</replaceable></classname> stored in the file <filename class="directory" >src_new/org/argouml/<replaceable>x/y</replaceable>/<replaceable>z</replaceable>.java</filename> have its JUnit test case class called <classname>org.argouml.<replaceable>x.y</replaceable>.Test<replaceable>z</replaceable></classname> stored in the file <filename class="directory" >tests/org/argouml/<replaceable>x/y</replaceable>/Test<replaceable>z</replaceable>.java</filename> 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 <classname>org.argouml.<replaceable>x.y</replaceable>.GUITest<replaceable>z</replacea
ble></classname> stored in the file <filename class="directory" >tests/org/argouml/<replaceable>x/y</replaceable>/GUITest<replaceable>z</replaceable>.java</filename> </para>
+ <para>If, for convenience reason, you would like to split the tests of a single class in several test classes, just name them with some extra suffix. Either 1, 2, 3, or something describing what part that test case tests. </para>
+ <para>If you only want to run your newly written test cases and not all the test cases, you could start with the command <command>build run-with-test-panel</command> and give the class name of your test case like <classname>org.argouml.<replaceable>x.y</replaceable>.Test<replaceable>z</replaceable></classname> or <classname>org.argouml.<replaceable>x.y</replaceable>.GUITest<replaceable>z</replaceable></classname>. You will then get the output in the window. You could run all tests in this way by specifying the special test suite <classname>org.argouml.util.DoAllTests</classname> in the same way. </para>
+ </section>
+
+ <section>
+ <title>About the Test case Methods</title>
+
+ <para>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. </para>
+ <para>Try to keep the test cases as short as possible. There is no need in cluttering them up just to beautify the output. Prefer <programlisting> // Example from JUnit FAQ public void testIndexOutOfBoundsExceptionNotRaised() throws IndexOutOfBoundsException { ArrayList emptyList = new ArrayList(); Object o = emptyList.get(0); } </programlisting> over <programlisting> public void testIndexOutOfBoundsExceptionNotRaised() { try { ArrayList emptyList = new ArrayList(); Object o = emptyList.get(0); } catch (IndexOutOfBoundsException iobe) { fail("Index out of bounds exception was thrown."); } } </programlisting> because the code is shorter, easier to maintain and you get a better error message from the JUnit framework. </para>
+ <para>A lot of times it is useful just to run the compiler to verify that the signatures are correct on the interfaces. Therefor Linus has thought it is a good idea to add methods called <methodname>compileTestStatics</methodname>, <methodname>compileTestConstructors</methodname>, and <methodname>compileTestMethods</methodname> 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. </para>
+
+ <example>
+ <title>An example without Javadoc comments</title>
+
+ <indexterm>
+ <primary>Test cases</primary>
+ <secondary>an example</secondary>
+ </indexterm>
+
+ <programlisting language="java">
+ 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()); }
+ }
+ </programlisting>
+
+ <para>And the corresponding no-GUI-class:</para>
+
+ <programlisting language="java">
+ 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() {}
+ }
+ </programlisting>
+
+ </example>
+ </section>
+
+ <section>
+ <title>Improving a test case</title>
+
+ <para>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 the time. </para>
+ <para>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. </para>
+ <para>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. </para>
+ <para>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.
+
+ <footnote>
+ <para>This is because the run-time dependency defaults used in Eclipse when creating a JUnit test configuration are based on the compile-time dependency settings and we don't have MDR in the compile-time dependencies because we want to enforce that there is no such dependency. Hopefully an upcoming code reorganization will address this problem. </para>
+ <para>The simplest way is to create/run the JUnit test configuration and if it fails with a ExceptionInInitializer error open it with the Configuration editor, add the argouml-core-model-mdr project to the class path and then run again. </para>
+ </footnote>
+ </para>
+
+ <para>This means that you should have the following priorities:
+
+ <orderedlist>
+ <listitem>
+ <para>Don't use the Model subsystem. </para>
+ <para>Only possible in a few simple cases. </para>
+ </listitem>
+ <listitem>
+ <para>Use the Mock model subsystem implementation. </para>
+ <para>Call the function <function>org.argouml.model.InitializeModel#initializeMock()</function> from setUp() in your test case. </para>
+ <para>Only possible in a few simple cases. </para>
+ </listitem>
+ <listitem>
+ <para>Use the real Model subsystem implementation from the <function>setUp()</function> function. </para>
+ <para>Call the function <function>org.argouml.model.InitializeModel#initializeDefault()</function> from setUp() in your test case. </para>
+ </listitem>
+ <listitem>
+ <para>Use the real Model subsystem implementation from the constructor. </para>
+ <para>Call the function <function>org.argouml.model.InitializeModel#initializeDefault()</function> in the constructor of your test case. </para>
+ <para>This is needed if your tests rely on the value in some member variables referencing some object retrieved from the model. </para>
+ </listitem>
+ <listitem>
+ <para>Use the real Model subsystem implementation from the static initialization section of your test class. </para>
+ <para>Call the function <function>org.argouml.model.InitializeModel#initializeDefault()</function> in the static initialization. </para>
+ <para>This is needed if your tests rely on the value of some static member variables referencing some object retrieved from the model. </para>
+ </listitem>
+ </orderedlist>
+ </para>
+
+ <para>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. </para>
+ </section>
+
+ </section>
+
+ <section xml:id="generating_documentation">
+ <title>Generating documentation</title>
+
+ <para>This describes how to generate the documentation for ArgoUML.</para>
+ <para>If you are in a hurry, here's the quick version:</para>
+
+ <programlisting os="windows">
+ C:\Work>svn checkout -N http://argouml.tigris.org/svn/argouml/trunk/src_new argouml/src_new
+ C:\Work>svn checkout http://argouml.tigris.org/svn/argouml/trunk/documentation http://argouml.tigris.org/svn/argouml/trunk/tools
+ C:\Work>set JAVA_HOME=<replaceable>C:\Programs\jdkwhatever</replaceable>
+ C:\Work>cd argouml\documentation
+ C:\Work\argouml\documentation>build docbook-xsl-get (first time only)
+ C:\Work\argouml\documentation>build defaulthtml
+ </programlisting>
+
+ <para>The chunked HTML versions of the Cookbook, Quick Guide, and User Manual are built and the results are placed in:
+ <filename class="directory">C:\Work\argouml\build\documentation\defaulthtml\cookbook</filename>,
+ <filename class="directory">C:\Work\argouml\build\documentation\defaulthtml\quick-guide</filename>, and
+ <filename class="directory">C:\Work\argouml\build\documentation\defaulthtml\manual</filename> respectively.
+ </para>
+
+ <section>
+ <title>Building documentation</title>
+
+ <indexterm>
+ <primary>Documentation</primary>
+ <secondary>work with</secondary>
+ </indexterm>
+
+ <para>To build the documentation, you will need to check out the whole <filename class="directory" >argouml/documentation</filename> directory. as well as the <filename class="directory" >argouml/tools</filename> directory which contains the tools needed (Ant, FOP, Saxon, etc) and the file <filename>argouml/src_new/default.properties</filename> which contains the current version and other project-wide settings. None of the other ArgoUML source directories are needed if you are just building the documentation. </para>
+ <para>The subdirectories of <filename class="directory" >argouml/documentation</filename>, <filename class="directory" >cookbook</filename>, <filename class="directory" >manual</filename>, and <filename class="directory" >quick-guide</filename> each contain one of the three books. The subdirectory <filename class="directory" >docbook-setup</filename> 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 <filename class="directory" >images</filename> contains all the required pictures for all the books. </para>
+ <para>There are separate build targets available for each output format, as well as a target that builds all possible output formats. Use the command <command>build -p</command> to get a complete list of targets. </para>
+ <para>For testing purposes while editing a manual, you probably want to build just a single output format for the one manual that you are working with. To suppress the building of the other manuals, you can define the following properties in your <filename>build.properties</filename> file: <programlisting> skip-cookbook=true skip-quickguide=true skip-argomanual=true </programlisting> </para>
+ <para>When, in the <filename class="directory" >documentation</filename> directory, you run <command>./build.sh defaulthtml</command> or one of the other targets that builds the documentation, all books are built. </para>
+ <para>What happens is (the target internal-dispatcher): </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The <filename><replaceable>manual</replaceable>/<replaceable>argomanual.xml</replaceable></filename> is copied by ant to <filename><replaceable>manual</replaceable>/<replaceable>argomanual-generated.xml</replaceable></filename> while doing substitution of tokens: (@VERSION@ to become the version as specified in <filename>default.properties</filename>) </para>
+ </listitem>
+ <listitem>
+ <para>The file <filename><replaceable>manual</replaceable>/<replaceable>argomanual-generated.xml</replaceable></filename> is processed by the special <filename>docbook-setup/create-imglist.xsl</filename> XSL script that generates a list of included images. </para>
+ </listitem>
+ <listitem>
+ <para>All included images are copied. </para>
+ <para>The purpose of this is to avoid copying images not actually used in the document. </para>
+ </listitem>
+ <listitem>
+ <para>The HTML is generated by processing the file <filename><replaceable>manual</replaceable>/<replaceable>argomanual-generated.xml</replaceable></filename>. </para>
+ </listitem>
+ </itemizedlist>
+ <para>The file <filename><replaceable>manual</replaceable>/<replaceable>argomanual-generated.xml</replaceable></filename> is a temporary file that only exists while processing the XML. If you are editing the XML be sure to edit the file <filename><replaceable>manual</replaceable>/<replaceable>argomanual.xml</replaceable></filename> and not the temporary file. </para>
+ </section>
+ </section>
+
+ <section xml:id="eclipse3">
+ <title>Setting up Eclipse 3</title>
+
+ <info>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ </info>
+
+ <indexterm>
+ <primary>Setting up Eclipse</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Eclipse</primary>
+ <secondary>Setting up the development environment</secondary>
+ </indexterm>
+
+ <para>If you are running Eclipse 3.1 or 3.2 we have a prepared and recommended setup committed into our repository. This setup is slightly different than the ant setup with regard to the directory tree structure of the checked out copy and some special magic is used in the ant scripts that is controlled from the special Eclipse configurations. </para>
+ <para>The prepared setup includes settings for Checkstyle within Eclipse that will be enabled if you have the Checkclipse Eclipse plugin installed. </para>
+ <para>You need to have Subclipse installed in your Eclipse to retrieve the files from the repository. See <link xlink:href="http://subclipse.tigris.org/install.html" />. </para>
+ <para>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. </para>
+
+ <section xml:id="eclipse-setup-summary">
+ <title>Basic ideas of the set up</title>
+
+ <para>This is a terse list of some ideas on the Eclipse set up. </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Argouml in its own workspace</para>
+ </listitem>
+
+ <listitem>
+ <para>No project-specific settings (compiler, JRE, style), instead workspace-specific settings. </para>
+ </listitem>
+
+ <listitem>
+ <para>Compile time dependencies are set up on the Java Build Path.</para>
+ </listitem>
+
+ <listitem>
+ <para>Run time dependencies are set up in the Configurations.</para>
+ </listitem>
+
+ <listitem>
+ <para>Configurations saved in the project where they "belong".</para>
+ </listitem>
+
+ </itemizedlist>
+ </section>
+
+ <section xml:id="eclipse-checkout">
+ <title>Checking out through Eclipse</title>
+
+ <para>This instruction is if you want to use Eclipse to download the source and it takes you up to where you can start ArgoUML from the source.</para>
+ <para>We have Eclipse Team Project Set files prepared to make the set up automatic.</para>
+ <para>Do the following.</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Change to the SVN Repository Explorer perspective and select Add SVN Repository. Then enter the following url <command>http://argouml.tigris.org/svn/argouml</command>. </para>
+ </listitem>
+ <listitem>
+ <para>Download the initial Team Project Set file and save it somewhere. </para>
+ <para>Suggested by browsing to <filename>trunk/tools/eclipse</filename> and checking it out as a project. </para>
+ <para>This is only needed the first time and if you don't already happen to have an updated checked out copy of argouml laying around. </para>
+ </listitem>
+ <listitem>
+ <para>Do File => Import and select Team Project Set and press Next. </para>
+ </listitem>
+ <listitem>
+ <para>Browse to the file <filename>argouml-core-projectset.psf</filename> and press Finish. </para>
+ <para>Now everything is automatic even though it takes a while. What happens is: </para>
+ <orderedlist>
+ <listitem>
+ <para>Files are downloaded from the Tigris SVN server and put into Eclipse projects. </para>
+ <para>It is around 30Meg that is downloaded so beware if you are on a slow connection. </para>
+ </listitem>
+ <listitem>
+ <para>The projects are built. First things that are special for ArgoUML, generated Java code, are created by Eclipse calling ant, then Eclipse kicks in and compiles the Java code. </para>
+ </listitem>
+ <listitem>
+ <para>Eclipse finds the Configurations that are also checked out. </para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ <listitem>
+ <para>Select Project => Clean... => Clean all projects and wait for everything to build again. </para>
+ </listitem>
+ <listitem>
+ <para>Verify that you can start ArgoUML from the debugger within Eclipse. You can do this by clicking on the little down-arrow close to the Debug icon in the tool bar, selecting Debugâ¦, and finding ArgoUML in the list (under Java Application). </para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section>
+ <title>Eclipse to help with the ArgoUML coding style</title>
+
+ <para>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. </para>
+ <para>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. </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Code conventions. </para>
+
+ <orderedlist>
+ <listitem>
+ <para>Select in the menu Window => Preferences. </para>
+ </listitem>
+ <listitem>
+ <para>Then select Java => Code Style => Formatter. </para>
+ </listitem>
+ <listitem>
+ <para>For Eclipse 3.2 you do: Select Java Conventions [built-in]. </para>
+ </listitem>
+ <listitem>
+ <para>For Eclipse 3.1 you do: Select Import and give the file <filename>eclipse/eclipse-argo-formatter.xml</filename> located in the argouml-core-tools project that you just checked out. </para>
+ <para>This takes care of the Eclipse-built-in bug (<link
+ xlink:href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=104765"
+ />). </para>
+ </listitem>
+ <listitem>
+ <para>Press OK. </para>
+ </listitem>
+ </orderedlist>
+ <para>This will give you Code Conventions exactly like the Sun Coding Style that we use in the ArgoUML project. </para>
+ </listitem>
+ <listitem>
+ <para>New file templates. </para>
+ <orderedlist>
+ <listitem>
+ <para>Select in the menu Window => Preferences. </para>
+ </listitem>
+ <listitem>
+ <para>Then select Java => Code Style => Code Templates. </para>
+ </listitem>
+ <listitem>
+ <para>Select Import and give the file <filename>eclipse/eclipse-argo-codetemplates.xml</filename> located in the argouml-core-tools project that you just checked out. </para>
+ </listitem>
+ <listitem>
+ <para>Press OK. </para>
+ </listitem>
+ </orderedlist>
+ <para>This will set up templates to be used when using the Eclipse functions for creating files, functions, types and Javadoc⦠</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Eclipse to automatically find problems in the code</title>
+
+ <para>This instruction is to set up Eclipse to automatically find what, in the ArgoUML project, could be considered problems in the code. </para>
+ <para>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. </para>
+ <para>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. </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Compiler compliance level. </para>
+ <para>See in the menu Window => Preferences. Then select Java => Compiler. At the right hand side set Compiler compliance level: 5.0. </para>
+ <para>Check Use default compliance settings. </para>
+ <para>In the ArgoUML project we have decided to keep source compliance to Java5 (See <xref xlink:href="#REQ7" />). This setting enables Eclipse to tell you where some Java6 features have crept in. </para>
+ </listitem>
+ <listitem>
+ <para>Find forgotten and incorrect Javadoc comments. </para>
+ <para>In the menu select Window => Preferences. Then select Java => Compiler => Javadoc. Suggested settings for these tabs (Only things diverting from the Eclipse defaults are listed): </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Javadoc => Malformed Javadoc comments: Warning, Private, Check all reports. </para>
+ </listitem>
+ <listitem>
+ <para>Javadoc => Missing Javadoc tags: Warning, Private, check Check overriding and implementing methods. </para>
+ </listitem>
+ <listitem>
+ <para>Javadoc => Missing Javadoc comments: Warning, Protected, uncheck Check overriding and implementing methods. </para>
+ </listitem>
+ </itemizedlist>
+ <para>These problems (except missing Javadoc comments) are also found by Checkstyle so if you are running Checkclipse (See <xref
+ xlink:href="checkclipse" />) put this in Ignore instead. </para>
+ </listitem>
+ <listitem>
+ <para>Code that hides other code. </para>
+ <para>In the menu select Window => Preferences. Then select Java => Compiler => Error/Warnings. Suggested settings for these tabs (Only things diverting from the Eclipse defaults are listed): </para>
+ <itemizedlist>
+ <listitem>
+ <para>Potential programming problems => Serializable class without serialVersionUID: Ignore </para>
+ <para>We don't use serialization in the ArgoUML project anyway. </para>
+ </listitem>
+ <listitem>
+ <para>Potential programming problems => Possible accidental boolean assignment: Warning. </para>
+ </listitem>
+ <listitem>
+ <para>Name shadowing and conflicts => Local variable declaration hides another field or variable: Warning, check Include constructor or setter method parameters. </para>
+ </listitem>
+ <listitem>
+ <para>Name shadowing and conflicts => Field declaration hides another field or variable: Warning. </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>Find Code that shall be removed. </para>
+ <para>In the menu select Window => Preferences. Then select Java => Compiler => Error/Warnings. Suggested settings for these tabs (Only things diverting from the Eclipse defaults are listed): </para>
+ <itemizedlist>
+ <listitem>
+ <para>Unnecessary code => Local variable is never read: Warning. </para>
+ </listitem>
+ <listitem>
+ <para>Unnecessary code => Parameter is never read: Warning. </para>
+ </listitem>
+ <listitem>
+ <para>Unnecessary code => Unused or unread private members: Warning. </para>
+ </listitem>
+ <listitem>
+ <para>Unnecessary code => Unnecessary semicolon: Warning. </para>
+ </listitem>
+ <listitem>
+ <para>Unnecessary code => Unnecessary cast or 'instanceof' operation: Warning. </para>
+ </listitem>
+ <listitem>
+ <para>Unnecessary code => Unnecessary declaration of thrown checked exception: Warning. </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section xml:id="checkclipse">
+ <title>Settings for Checkclipse</title>
+
+ <para>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. </para>
+ <para>Get the latest Checkclipse kit from SourceForge at <link xlink:href="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 <link xlink:href="http://checkstyle.sourceforge.net/" /> for reference.) </para>
+ <para>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. </para>
+ <para>In the Java perspective, select the project argouml, i.e. the icon at the top of the Package Explorer. Then, in the menu, select Project => Properties, select Checkclipse (appears only if Checkclipse is correctly installed) and then fill the fields like this: </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Enable Checkstyle - Checked. </para>
+ </listitem>
+ <listitem>
+ <para>Set Project Classloader - Checked.</para>
+ </listitem>
+ <listitem>
+ <para>Checkstyle Configuration File: <filename>/argouml-core-tools/checkstyle/checkstyle_argouml.xml</filename> in the argouml-core-tools project. </para>
+ </listitem>
+ <listitem>
+ <para>Checkstyle Properties File: <filename>/argouml-core-tools/checkstyle/checkstyle.properties</filename> in the argouml-core-tools project. </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Leave the rest of the fields at their default (empty). The File Filters are defined on an additional preferences tab rather than in separate file as in earlier versions of Checkclipse. If this isn't populate 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. </para>
+ </section>
+
+ <section xml:id="eclipse-running-junit">
+ <title>Running JUnit test cases from within Eclipse</title>
+
+ <para>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 uses the insides of some subsystem that is supposed to be hidden. </para>
+ <para>The Model subsystem is separated in two parts:
+ <itemizedlist>
+ <listitem>
+ <para>The interfaces and some bootstrap code in the argouml-core-model Eclipse project. </para>
+ </listitem>
+ <listitem>
+ <para>The MDR implementation in the argouml-core-model-mdr Eclipse project. </para>
+ </listitem>
+ </itemizedlist> There is also for test purposes a partly implemented Mock implementation of the model subsystem in the <classname>org.argouml.model.MockModelImplementation</classname>-class for the purpose of testing the interfaces and the bootstrap code but it requires the test cases to be written especially for that. </para>
+ <para>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. </para>
+ <para>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. </para>
+ <para>The simplest way to solve this is to:
+ <orderedlist>
+ <listitem>
+ <para>Create the test (by right-clicking on any of the test classes and select Run as JUnit Test or Debug as JUnit Test). </para>
+ <para>The test fails with a <exceptionname>java.lang.ExceptionInInitializerError</exceptionname> on the first reference to Model. If it doesn't then the perhaps the test case doesn't use the Model. </para>
+ </listitem>
+ <listitem>
+ <para>Select Debug⦠or Run⦠to get the configuration editing box. It has remembered the test case and it is selected. </para>
+ </listitem>
+ <listitem>
+ <para>Add the argouml-core-model-mdr to the class path. </para>
+ <para>Classpath tab, Select User Entries, Add Projects, Check argouml-core-model-mdr, make sure Add exported entries of selected projects and Add required projects of selected projects are checked, Press OK, Press Debug or Run. Eclipse will remember these changes to that configuration but you will have to do it all over again once for each new test case. </para>
+ </listitem>
+ </orderedlist>
+ </para>
+
+ <section xml:id="running-all-junit-from-within-eclipse">
+ <title>Running all JUnit test cases from within Eclipse</title>
+
+ <para>The description so far describes how to do this for a single test case at the time. If you want to run all test cases in one go from within Eclipse it is also possible. We have not prepared that for three reasons:
+ <itemizedlist>
+ <listitem>
+ <para>Some of the tests fail when run in this way. </para>
+ <para>The guess (Linus July 2006) is that this depends on the fact that Eclipse doesn't start each test in its own JVM and some of the tests relies on a fresh environment (empty modelsâ¦). Let's hope that an upcoming version of Eclipse includes a function to allow us to specify that the tests are to be run each in its own JVM. </para>
+ <para>Another cause might be that the tests relies on certain other files being in specified places and that the Eclipse set up doesn't provide that. </para>
+ </listitem>
+ <listitem>
+ <para>Maintaining the Configuration. </para>
+ <para>Since we have an Eclipse setup with a mismatch between the compile time dependencies and the run time dependencies this Configuration contains references to specific jar-files. This means a maintenance problem whenever changing version of a dependency. </para>
+ </listitem>
+ <listitem>
+ <para>Selection of tests. </para>
+ <para>In the project we keep all tests in the same tree, whether they are working or not. We distinguish between test classes with names starting with "Test", "GUITest", and neither of them. The ones starting with "Test" or "GUITest" are official tests that should be working. All others are tests that are never run automatically. They are perhaps used for other purposes. In Eclipse, there is no way to specify this so the description below will run all tests. </para>
+ <para>Such a test is the DoAllTests-test suite that runs all tests so tests risk to be run twice. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>If you want to test this, this is what you do: </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Right-click on the project argouml-core-tests. </para>
+ </listitem>
+ <listitem>
+ <para>On the multilevel pop-up that opens, select Run As⦠JUnit Test or Debug As⦠JUnit Test. </para>
+ </listitem>
+ <listitem>
+ <para>A Configuration is created on that project with the Run all tests in the selected project, package or source folder: checked and the configuration is started/launched. </para>
+ </listitem>
+ <listitem>
+ <para>Stop the running Configuration. </para>
+ <para>The newly Configuration has the same problem as every single test above with the model subsystem so it won't work. </para>
+ </listitem>
+ <listitem>
+ <para>Press Debug⦠or Run⦠to open the Configuration editor. </para>
+ <para>The newly created Configuration argouml-core-test is selected. </para>
+ </listitem>
+ <listitem>
+ <para>Add the argouml-core-model-mdr project to the class path. </para>
+ <para>This is done by: <itemizedlist>
+ <listitem>
+ <para>selecting the Classpath tab,</para>
+ </listitem>
+ <listitem>
+ <para>selecting argouml-core-tests under User Entries,</para>
+ </listitem>
+ <listitem>
+ <para>clicking Add projects, and</para>
+ </listitem>
+ <listitem>
+ <para>selecting the argouml-core-model-mdr project and press OK. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Run all the tests by pressing Debug or Run. </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title>Settings for NetBeans</title>
+
+ <info>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ </info>
+
+ <warning>
+ <para>It is unclear what version of NetBeans these settings work in. If you test it, let us know so that we can update the Cookbook. </para>
+ </warning>
+
+ <para>The argouml style guides correspond to the following settings in NetBeans: </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>In (Tools =>) Options => Editing => Editor Settings => Java Editor </para>
+ <para>Tab Size = 8 </para>
+ </listitem>
+ <listitem>
+ <para>In (Tools =>) Options => Editing => Indentation Engines => Java Indentation Engine </para>
+ <para>Add Newline Before Brace: False, Add Space Before Parenthesis: False, Expand Tabs to Spaces: False, Number of Spaces per Tab: 4 (Should probably be read as Number of Spaces per indentation level). </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Settings for Emacs</title>
+
+ <info>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ </info>
-<chapter id="buildingandtools">
- <title>Building from source</title>
- <para>
-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.
-</para>
-
- <sect1 id="quickbuild">
- <title>Quick Start</title>
-
- <para>
-If you are using Eclipse 3.1 or later, see <xref linkend="eclipse3"></xref>
-for quick setup instructions.
-</para>
-
- <para>
-If you are using Windows, the follow commands will build ArgoUML from source and
-run it. If you using Unix/Linux, the comparable commands, modified slightly for
-your particular shell, should work.
-<programlisting>
-C:\Work>svn checkout http://argouml.tigris.org/svn/argouml/trunk/src http://argouml.tigris.org/svn/argouml/trunk/src_new http://argouml.tigris.org/svn/argouml/trunk/tools http://argouml.tigris.org/svn/argouml/trunk/lib http://argouml.tigris.org/svn/argouml/trunk/tests argouml --username guest
-Password: (give empty password if prompted)
-C:\Work>set JAVA_HOME=<replaceable>C:\Programs\jdkwhatever</replaceable>
-C:\Work>cd argouml\src_new
-C:\Work\argouml\src_new>build run
-</programlisting>
-A newly compiled ArgoUML will open in a new window.
-</para>
- <note>
- <para>JDK Java5 or later is required</para>
- </note>
- <para>
-That was the compact version for Windows + JDK.
-Modifying these steps slightly as appropriate for your shell should
-work on Unix/Linux systems as well.
-</para>
- <para>
-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.
-</para>
- </sect1>
-
- <sect1 id="starting">
- <title>Preparations</title>
- <para>
-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
-<xref linkend="checkout"></xref>.
-</para>
- <para>
-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.
-</para>
-
- <sect2>
- <title>What do I need to build ArgoUML?</title>
- <indexterm>
- <primary>Building</primary>
- <secondary>tools</secondary>
- </indexterm>
- <indexterm>
- <primary>Tools</primary>
- <secondary>needed for building</secondary>
- </indexterm>
- <para>
-These are the tools not included in the repository that
-you need to work with ArgoUML.
-</para>
- <itemizedlist>
- <listitem>
- <para>
-A computer with an Internet connection and free disk space for your work.
-</para>
- <para>
-Around 150MB to download everything from the repository.
-(Currently September 2006 it is 147MB.)
-<!--
- In March 2003 it was 68MB but CVS was used then.
- -->
-Around 200MB to download all and build the tool and the documentation.
-(Currently September 2006 it is 192MB.)
-<!--
- In March 2003 it is 114MB.
--->
-350MB should be enough to build it all
-(Javadocs, documentation, classes, ...).
-(Currently September 2006 it is 299MB.)
-</para>
- </listitem>
- <listitem>
- <para>
-Subversion for getting the files
-and committing source code updates.
-You can also use an IDE with a built-in subversion client.
-</para>
- </listitem>
- <listitem>
- <para>
-JDK (including the Java compiler)
-</para>
- </listitem>
- </itemizedlist>
-
- <para>
-For building the documentation from DocBook format,
-you also need the following tools:
-</para>
- <itemizedlist>
- <listitem>
- <para>
- <indexterm>
- <primary>DocBook</primary>
- </indexterm>
- <indexterm>
- <primary>XSL style sheets</primary>
- </indexterm>
-DocBook XSL style sheets.
-</para>
-
- <para>
-There exists rules in the
-<filename>argouml/documentation/build.xml</filename>
-for downloading this correctly.
-</para>
- </listitem>
-
- <listitem id="download-jimi">
- <para>
- <indexterm>
- <primary id="download-jimi-name">Jimi</primary>
- </indexterm>
-Jimi
-</para>
- <para>
-Used by FOP for including PNG pictures.
-</para>
- <para>
-Detailed instructions:
- <orderedlist>
- <listitem>
- <para>
-Download the file
-<filename>jimi1_0.zip</filename> from
-<ulink url="http://java.sun.com/products/jimi/">java.sun.com</ulink>.
-</para>
- </listitem>
- <listitem>
- <para>
-Extract the file <code>JimiProClasses.zip</code>.
-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.
-</para>
- </listitem>
- <listitem>
- <para>
-If the previous step put the extracted file elsewhere, copy or move this file into the
-<filename>argouml\tools\lib</filename> directory.
-</para>
- </listitem>
- </orderedlist>
-</para>
- </listitem>
- </itemizedlist>
- </sect2>
-
- <sect2>
- <title>Configuring Subversion</title>
- <para>
-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.
-</para>
- <table>
- <title>Changes done</title>
- <tgroup cols="3">
- <colspec colnum="1" colname="property" colwidth="2*"/>
- <colspec colnum="2" colname="value" colwidth="1*"/>
- <colspec colnum="3" colname="comment" colwidth="5*"/>
- <thead>
- <row>
- <entry>Property</entry>
- <entry>Value</entry>
- <entry>Comment</entry>
- </row>
- </thead>
-
- <tbody valign="top">
- <row>
- <entry>svn:keywords</entry>
- <entry>Author Date Id Revision</entry>
- <entry>
-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.
-</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>svn:eol-style</entry>
- <entry>native</entry>
- <entry>
-All text files, Java files, XML files,
-i.e. almost all non-binary files.
-</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>svn:executable</entry>
- <entry>*</entry>
- <entry>
-This is for the tools of the development environment to work properly.
-</entry>
- </row>
- </tbody>
-
- </tgroup>
- </table>
-
- <para>
-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.
-</para>
- <para>
-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.
-</para>
- <para>
-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
-<itemizedlist>
- <listitem>
- <para>
-On Windows:
-<filename>%APPDATA%\Subversion\config</filename>
-where %APPDATA% is
-<filename>C:\Documents and Settings\<replaceable>your username</replaceable>\Application Data</filename>.
-</para>
- </listitem>
-
- <listitem>
- <para>
-On Unix/Linux:
-<filename>$HOME/.subversion/config</filename>.
-</para>
- </listitem>
- </itemizedlist>
-</para>
-
- <para>
-Suggested settings:
-<programlisting>
-[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=*
-</programlisting>
-</para>
- </sect2>
- </sect1>
-
- <sect1>
- <title>The ArgoUML development environment</title>
- <sect2>
- <title>
-Which tools are part of the ArgoUML development environment?
-</title>
- <indexterm>
- <primary>Tools</primary>
- <secondary>used</secondary>
- </indexterm>
- <para>
-These tools are provided by the development environment that you
-get when you check out from the repository.
-</para>
- <itemizedlist>
- <listitem>
- <para>
- <indexterm>
- <primary>Ant</primary>
- </indexterm>
-Ant, the tool to manage compiling and packaging.
-</para>
- </listitem>
- <listitem>
- <para>
-mdrant, the integration allowing to run mdr from ant.
-</para>
- </listitem>
-
- <listitem>
- <para>
- <indexterm>
- <primary>ANTLR</primary>
- </indexterm>
-ANTLR, for regenerating the built-in parser.
-</para>
- </listitem>
- <listitem>
- <para>
- <indexterm>
- <primary>JUnit</primary>
- </indexterm>
-JUnit, for running the JUnit test cases.
-</para>
- </listitem>
- <listitem>
- <para>
- <indexterm>
- <primary>JDepend</primary>
- </indexterm>
-JDepend, for examining the code.
-</para>
- </listitem>
- </itemizedlist>
- <para>
-For building the documentation from DocBook format,
-these tools are also provided with the development environment that
-you get when you check out from the repository.
-</para>
- <itemizedlist>
- <listitem>
- <para>
-Saxon for building documentation from DocBook format.
-</para>
- </listitem>
- <listitem>
- <para>
- <indexterm>
- <primary>fop</primary>
- </indexterm>
-fop for generating PDF versions of the DocBook format.
-</para>
- <para>
-To build a PDF file with the pictures included you need Jimi
-that is downloaded separately.
-See
-<xref linkend="download-jimi" endterm="download-jimi-name"/>.
-</para>
- </listitem>
- </itemizedlist>
- </sect2>
- <sect2>
- <title>What libraries are needed and used by ArgoUML?</title>
- <para>
-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.
-</para>
- <itemizedlist>
- <listitem>
- <para>
- <indexterm>
- <primary>MDR</primary>
- </indexterm>
-MDR, the Netbeans Model Data Repository.
-</para>
- <para>
-This library provides services to manipulate both the UML
-metamodel and the users model. It includes services to
-serial/deserialize to/from XMI.
-</para>
-
- </listitem>
-
- <listitem>
- <para>
- <indexterm>
- <primary>GEF</primary>
- </indexterm>
-
-GEF graph editing framework, available from
-<ulink url="http://gef.tigris.org">gef.tigris.org</ulink>.
-</para>
- <para>
-If you would like the GEF sources for reference, please
-consult their web site for directions on checking them out.
-</para>
-
- </listitem>
-
- <listitem>
- <para>
-The OCL package to parse and run the Object Constraint Language things.
-</para>
- <para>
-Details about the package are available from SourceForge
-<ulink url="http://dresden-ocl.sourceforge.net/">OCL Compiler</ulink>.
-</para>
- </listitem>
-
- <listitem>
- <para>
- <indexterm>
- <primary>log4j</primary>
- </indexterm>
-log4j, a library with infrastructure for logs.
-</para>
- </listitem>
-
- <listitem>
- <para>
-antlrall, the run-time part of the ANTLR tool.
-</para>
- </listitem>
-
-
-
- <listitem>
- <para>
-MDR,
-the Netbeans Meta Data Repository.
-</para>
- <para>
-This is included in the files
-jmi.jar, jmiutils.jar, mdrapi.jar, mof.jar, nbmdr.jar, openide-util.jar.
-</para>
- </listitem>
- </itemizedlist>
- </sect2>
-
- </sect1>
-
- <sect1 id="checkout">
- <title id="checkout_term">Download from the Subversion repository</title>
- <indexterm>
- <primary>CVS</primary>
- <secondary>checking out from</secondary>
- </indexterm>
- <indexterm>
- <primary>Checking out from CVS</primary>
- </indexterm>
- <indexterm>
- <primary>Subversion</primary>
- <secondary>checking out from</secondary>
- </indexterm>
- <indexterm>
- <primary>Checking out from Subversion</primary>
- </indexterm>
-
- <para>
-The easiest thing to do now, is
-just check out the whole
-<parameter>argouml</parameter> project.
-For this use the Subversion URL
-<filename>http://argouml.tigris.org/svn/argouml/trunk</filename>.
-</para>
- <para>
-If you want to limit the download size,
-by not checking out the images in the
-<filename class="directory">argouml/documentation</filename>
-and
-<filename class="directory">argouml/www</filename>
-the repository directories you need to check out to work with ArgoUML are
-<filename class="directory">argouml/lib</filename>,
-<filename class="directory">argouml/tools</filename>,
-<filename class="directory">argouml/src_new</filename>,
-<filename class="directory">argouml/src</filename>,
-and
-<filename class="directory">argouml/tests</filename>.
-These are located at the subversion URLs
-<filename>http://argouml.tigris.org/svn/argouml/trunk/lib</filename>,
-<filename>http://argouml.tigris.org/svn/argouml/trunk/tools</filename>,
-<filename>http://argouml.tigris.org/svn/argouml/trunk/src_new</filename>,
-<filename>http://argouml.tigris.org/svn/argouml/trunk/src</filename>,
-and
-<filename>http://argouml.tigris.org/svn/argouml/trunk/tests</filename>
-respectively.
-</para>
- <para>
-If you just want to build the documentation you check out the directories
-<filename class="directory">argouml/tools</filename>
-and
-<filename class="directory">argouml/documentation</filename>.
-These are located at the subversion URLs
-<filename>http://argouml.tigris.org/svn/argouml/trunk/tools</filename>
-and
-<filename>http://argouml.tigris.org/svn/argouml/trunk/documentation</filename>
-respectively.
-For the documentation you will also need the file
-<filename>default.properties</filename>
-from
-<filename>http://argouml.tigris.org/svn/argouml/trunk/src_new/default.properties</filename>.
-</para>
- <para>
-If you want to work with the web site you check out
-the directory
-<parameter>argouml/www</parameter>.
-This is located at the subversion URLs
-<filename>http://argouml.tigris.org/svn/argouml/trunk/www</filename>.
-</para>
-
- <para>
-If you don't want to acquire a Tigris login to do this you can use the
-"guest" account with an empty password.
-</para>
- </sect1>
-
-
- <sect1 id="Build">
- <title id="Build_term">Build Process</title>
- <indexterm>
- <primary>Building</primary>
- <secondary>ArgoUML</secondary>
- </indexterm>
- <indexterm>
- <primary>Ant</primary>
- </indexterm>
- <para>
-The standard ArgoUML build process is driven by Apache Ant, and it is highly recommend
-that you stick to that.
-Some developers use the integrated build tools of Eclipse and NetBeans, but always
-make sure that your work compiles with the standard Ant build process.
-There are also some Java files generated by magic scripts in Ant that
-you need to create before opening with the IDE.
-</para>
- <para>
-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.
-</para>
- <indexterm>
- <primary><filename>build.xml</filename></primary>
- </indexterm>
- <para>
-The rule file is named <filename>build.xml</filename>.
-There is one of those in every separate build directory
-(<filename class="directory">argouml/src_new</filename>,
-<filename class="directory">argouml/src/<replaceable>whatever</replaceable></filename>,
-<filename class="directory">argouml/documentation</filename>, and
-<filename class="directory">argouml/modules/<replaceable>whatever</replaceable></filename>).
-</para>
-
- <sect2>
- <title>How Ant is run from the ArgoUML development environment</title>
- <indexterm>
- <primary>Ant</primary>
- <secondary>how it is used</secondary>
- </indexterm>
- <para>
-For your convenience the ant tool of the correct version is present in the
-source repository of ArgoUML in the file
-<filename class="libraryfile">argouml/tools/ant-1.6.2/lib/ant.jar</filename>.
-</para>
- <para>
-It is possible to start ant with the command
-<command>../tools/ant-1.6.2/bin/ant <replaceable>arg</replaceable></command>
-and in the modules
-<command>
-../../tools/ant-1.6.2/bin/ant <replaceable>arg</replaceable>
-</command>.
-On windows the command
-<command>..\tools\ant-1.6.2\bin\ant <replaceable>arg</replaceable></command>
-runs the program <filename>ant.bat</filename>.
-</para>
- <para>
-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 <filename>build.sh</filename> and
-<filename>build.bat</filename> respectively present in most
-of the directories that contain a <filename>build.xml</filename> file.
-These two scripts run the equivalence of the above paths.
-</para>
- <para>
-By setting JAVA_HOME to different values you can at different times
-build with different versions of JDK and Java.
-</para>
- <para>
-To use different versions of Ant,
-you are responsible for installing your own version.
-Also, you must execute
-<command>/where/ever/you/placed/your/new/ant <replaceable>target</replaceable></command>
-rather than
-<command>build <replaceable>target</replaceable></command>.
-</para>
-
- <sect3>
- <title>Compiling for Unix</title>
- <indexterm>
- <primary>Compiling</primary>
- <secondary>Unix</secondary>
- </indexterm>
- <indexterm>
- <primary>Unix</primary>
- <secondary>compilation</secondary>
- </indexterm>
- <para>
-Here is what you need to do in order to compile and run
-your checked out copy of ArgoUML under Unix.
-</para>
- <orderedlist>
- <listitem>
- <para><command>JAVA_HOME=<replaceable>/where/you/have/installed/jdk</replaceable></command></para>
- <para><command>export JAVA_HOME</command></para>
- <para>
-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
-<command>setenv JAVA_HOME <replaceable>/where/you/have/installed/jdk</replaceable></command>.
-</para>
- </listitem>
- <listitem>
- <para>
-Change the current directory to the directory you are building
-</para>
- <para>
-<command>cd <replaceable>/your/checked/out/copy/of/argouml/src_new</replaceable></command>
-</para>
- </listitem>
- <listitem>
- <para>
-Start Ant with no parameters to get a list of build targets
-with descriptions
-</para>
- <para> <command>./build.sh</command></para>
- </listitem>
- <listitem>
-
- <para>
- <indexterm>
- <primary>Ant target</primary>
- <secondary>run</secondary>
- </indexterm>
- <indexterm>
- <primary>run ant target</primary>
- </indexterm>
-Run ArgoUML using <command>./build.sh run</command>
-</para>
- </listitem>
- </orderedlist>
- <para>
-If you change something, running the run target again will
-build
-and run.
-</para>
-
- <para>
-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.
-</para>
- </sect3>
- <sect3>
- <title>Compiling for Windows</title>
- <indexterm>
- <primary>Compiling</primary>
- <secondary>Windows</secondary>
- </indexterm>
- <indexterm>
- <primary>Windows</primary>
- <secondary>Compilation</secondary>
- </indexterm>
-
- <indexterm>
- <primary>Compiling</primary>
- <secondary>Cygwin</secondary>
- </indexterm>
- <indexterm>
- <primary>Cygwin Compilation</primary>
- </indexterm>
- <para>
-If you do this from Cygwin you work just like for Unix.
-</para>
-
- <orderedlist>
- <listitem>
- <para>
-<command>set JAVA_HOME=<replaceable>\where\you\have\installed\jdk</replaceable></command>
-<!-- TODO: MVW: My setting includes a "\" at the end, and works.
-Does it matter? -->
-</para>
- </listitem>
- <listitem>
- <para>
-Change the current directory to the directory you are building
-</para>
- <para>
-<command>cd <replaceable>\your\checked\out\copy\of\argouml\src_new</replaceable></command>
-</para>
- </listitem>
- <listitem>
- <para>
-Start Ant with "-p" parameter to get a list of build targets
-with descriptions
-</para>
- <para><command>build -p</command></para>
- </listitem>
- <listitem>
-
- <para>
-Run ArgoUML using <command>build run</command>
-</para>
- </listitem>
- </orderedlist>
-
-
-
- </sect3>
- <sect3>
- <title>Customizing and configuring your build</title>
- <indexterm>
- <primary>Compiling</primary>
- <secondary>customized</secondary>
- </indexterm>
- <indexterm>
- <primary>build.properties</primary>
- </indexterm>
- <indexterm>
- <primary>default.properties</primary>
- </indexterm>
- <indexterm>
- <primary>argouml.build.properties</primary>
- </indexterm>
- <indexterm>
- <primary>Ant target</primary>
- <secondary>list-property-files</secondary>
- </indexterm>
- <indexterm>
- <primary>list-property-files ant target</primary>
- </indexterm>
- <para>
-It is possible to customize your compilation of ArgoUML.
-</para>
- <para>
-If you issue the command
-<command>build list-property-files</command>
-you can see what files are searched for properties.
-</para>
- <para>
-Don't change the
-<filename class="libraryfile">argouml/src_new/default.properties</filename>
-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
-<filename class="libraryfile">argouml/src_new/default.properties</filename>.
-</para>
- <para>
-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.
- </para>
- </sect3>
- <sect3>
- <title>Building Javadoc</title>
- <indexterm>
- <primary>Javadoc building</primary>
- </indexterm>
- <indexterm>
- <primary>Building</primary>
- <secondary>Javadoc</secondary>
- </indexterm>
- <indexterm>
- <primary>Ant target</primary>
- <secondary>prepare-docs</secondary>
- </indexterm>
- <indexterm>
- <primary>prepare-docs ant target</primary>
- </indexterm>
- <para>
-By running Ant again using <command>build prepare-docs</command>
-the Javadoc documentation is generated and put into
-<filename class="directory">argouml/build/javadocs</filename>.
-</para>
- </sect3>
- <sect3>
- <title>Building one of the modules</title>
- <para>
-If you want to run ArgoUML with modules enabled the
-<filename>build.xml</filename>s are set up to do this in two ways:
- <orderedlist>
- <listitem>
- <para>Test just one module</para>
- <orderedlist>
- <listitem>
- <para>Build ArgoUML, the package</para>
- <para>
-This is done with <command>ant package</command>
-in the <filename class="directory">argouml/src_new</filename>-directory.
-</para>
- </listitem>
- <listitem>
- <para>Run the module</para>
- <para>
-This is done with <command>ant run</command>-command
-in the
-<filename class="directory">
-argouml/modules/<replaceable>whatever</replaceable>
-</filename>-directory.
-</para>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem>
- <para>Test several modules together</para>
- <orderedlist>
- <listitem>
- <para>Build ArgoUML, the package</para>
- <para>
-This is done with <command>ant package</command>
-in the <filename class="directory">argouml/src_new</filename>-directory.
-</para>
- </listitem>
- <listitem>
- <para>Compile and install the modules</para>
- <para>
-This is done with <command>ant install</command>-command
-in each of the
-<filename class="directory">
-argouml/modules/<replaceable>whatever</replaceable>
-</filename>-directories.
-</para>
- </listitem>
- <listitem>
- <para>Start ArgoUML</para>
- <para>
-This is done with <command>ant run</command>
-in the <filename class="directory">argouml/src_new</filename>-directory.
-</para>
- </listitem>
- </orderedlist>
- <para>
-This will start ArgoUML with all modules available.
-</para>
- </listitem>
- </orderedlist>
-</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Developing in a subproject</title>
-
- <para>
-This describes how to do development in one of the ArgoUML sub-projects.
-</para>
-
- <para>
-If you are in a hurry:
-<programlisting>
-C:\Work>mkdir argouml
-C:\Work>mkdir argouml\build
-</programlisting>
-Download and unpack the latest release of ArgoUML into this directory.
-<programlisting>
-C:\Work>svn checkout http://argouml-<replaceable>XX</replaceable>.tigris.org/svn/argouml-<replaceable>XX</replaceable>/trunk argouml-<replaceable>XX</replaceable>
-C:\Work>set JAVA_HOME=<replaceable>C:\Programs\jdkwhatever</replaceable>
-C:\Work>cd argouml-<replaceable>XX</replaceable>
-C:\Work\argouml-<replaceable>XX</replaceable>>ant run
-</programlisting>
-An ArgoUML starts with the module from the subproject
-argouml-<replaceable>XX</replaceable> enabled.
-</para>
- <para>
-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.
-</para>
- <para>
-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.
-</para>
-
- <sect3>
- <title>The sub-project's relation to ArgoUML</title>
-
- <para>
-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.
-</para>
-
- <para>
-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:
-<itemizedlist>
- <listitem>
- <para>You will inherit all the infrastructure
-from the ArgoUML project.
-</para>
- <para>
-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.
-</para>
- </listitem>
-
- <listitem>
- <para>
-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.
-</para>
- </listitem>
- </itemizedlist>
-The draw-backs are:
-<itemizedlist>
- <listitem>
- <para>You are forced to use the ArgoUML infrastructure</para>
- <para>
-Subversion, BSD license, coding guidelines.
-</para>
- </listitem>
- <listitem>
- <para>You are forced to make your module Open Source.</para>
- <para>
-This is actually a Tigris policy.
-</para>
- </listitem>
- </itemizedlist>
-</para>
-
- <para>
-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.
-</para>
-
- <para>
-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.
-</para>
-
- <para>
-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.
-</para>
- <para>
-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.
-</para>
-
- <para>
-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.
-</para>
-
- <para>
-The build.xml ant configuration file in the subproject
-and the argouml main project
-are set up to allow for both of these ways.
-</para>
- </sect3>
-
- <sect3 id="working-with-subproject">
- <title>Working in a subproject</title>
- <para>
-Each subproject has its own web site with
-documentation and plans of the subproject.
-</para>
- <para>
-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!
-</para>
- <para>
-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.
-</para>
- </sect3>
-
- <sect3>
- <title>Targets in build.xml in a subproject</title>
- <para>
-The following targets have the same documented meaning in all sub-projects:
-
-<itemizedlist>
- <listitem>
- <para>clean - optional</para>
- <para>
-Removes files that are generated by running any of the other targets.
-</para>
- </listitem>
- <listitem>
- <para>compile - optional</para>
- <para>
-Compiles the code.
-The result is in <filename>build/classes</filename>.
-</para>
- </listitem>
- <listitem>
- <para>generate - optional</para>
- <para>
-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.
-</para>
- </listitem>
- <listitem>
- <para>install</para>
- <para>
-This builds the whole module and copies it into the
-<filename>ext</filename> directory in the argouml installation.
-</para>
- <para>
-The purpose of the ext directory is so that argouml can be started
-with several different modules started at once.
-</para>
- </listitem>
- <listitem>
- <para>jar - optional</para>
- <para>
-This builds the whole module and puts the resulting jar file(s)
-in <filename>build</filename>.
-</para>
- </listitem>
- <listitem>
- <para>run</para>
- <para>
-This starts argouml with this module active.
-</para>
- <para>
-This is the way to start this module with the newly compiled source.
-</para>
- </listitem>
- <listitem>
- <para>tests - optional</para>
- <para>
-This runs all the JUnit test cases available in the module.
-This probably requires the <filename>junit.jar</filename> tool
-from the argouml project.
-</para>
- </listitem>
- </itemizedlist>
-</para>
- </sect3>
- </sect2>
-
-
-
- <sect2>
- <title>Troubleshooting the development build</title>
- <indexterm>
- <primary>Troubleshooting</primary>
- <secondary>development build</secondary>
- </indexterm>
- <sect3>
- <title>Compiling failed. Any suggestions?</title>
- <para>
-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
-<ulink url="http://argouml.tigris.org/servlets/BrowseList?listName=dev">
-developers mailing list</ulink>!
-It is probably on fire.
-</para>
- <indexterm>
- <primary>Ant target</primary>
- <secondary>clean</secondary>
- </indexterm>
- <indexterm>
- <primary>clean ant target</primary>
- </indexterm>
- <para>
-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
-<command>build clean</command> and <command>svn update</command>
-before trying to build again.
-If that doesn't work remove your checked out copy completely and
-get it all again.
-</para>
- <para>
-Another reason might be that you have an
-<filename>build.properties</filename> or
-<filename>argouml.build.properties</filename>
-file that you have been working with earlier
-and that is doing something. If in doubt, remove those files.
-</para>
- <para>
-If nothing helps, ask the
-<ulink url="mailto:[email protected] ">developers mailing list</ulink>!
-</para>
- </sect3>
- <sect3>
- <title>Can't commit my changes?</title>
- <indexterm>
- <primary>Troubleshooting</primary>
- <secondary>committing changes</secondary>
- </indexterm>
- <para>
-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.
-</para>
- <para>
-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.
-</para>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1 id="junittests">
- <title>The JUnit test cases</title>
- <indexterm>
- <primary>JUnit testing</primary>
- </indexterm>
- <indexterm>
- <primary>Unit testing of ArgoUML</primary>
- </indexterm>
- <indexterm>
- <primary>Testing ArgoUML</primary>
- </indexterm>
- <para>
-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.
-</para>
- <para>
-The JUnit test cases reside in a separate directory and
-run from ant targets in
-<filename>src_new/build.xml</filename>.
-They are never distributed with ArgoUML; they are merely a tool for
-developers.
-</para>
-
- <indexterm>
- <primary>Ant target</primary>
- <secondary>tests</secondary>
- </indexterm>
- <indexterm>
- <primary>tests ant target</primary>
- </indexterm>
- <indexterm>
- <primary>Ant target</primary>
- <secondary>guitests</secondary>
- </indexterm>
- <indexterm>
- <primary>guitests ant target</primary>
- </indexterm>
- <para>
-By running the command
-<command>build tests guitests</command>
-or
-<command>build alltests</command>
-in <filename>src_new</filename>
-these test cases are run, each in its own JVM.
-</para>
- <para>
-Each test case writes its result on the Ant log.
-</para>
- <para>
-The result is also generated into a browsable report that can be found at
-<filename>build/test/reports/junit/output/html/index.html</filename>.
-This is the same report that is presented as a result from
-the nightly build.
-</para>
-
- <para>
-The test cases' Java source code is located under
-<filename>argouml/tests/org/argouml</filename>.
-</para>
-
- <sect2>
- <title>About the Test case Class</title>
- <indexterm>
- <primary>Unit testing of ArgoUML</primary>
- </indexterm>
- <indexterm>
- <primary>Testing ArgoUML</primary>
- </indexterm>
- <indexterm>
- <primary>Test cases</primary>
- <secondary>writing</secondary>
- </indexterm>
- <indexterm>
- <primary>Writing test cases</primary>
- </indexterm>
- <indexterm>
- <primary>Ant target</primary>
- <secondary>run-with-test-panel</secondary>
- </indexterm>
- <indexterm>
- <primary>run-with-test-panel ant target</primary>
- </indexterm>
- <para>
-Now this will make all you Java enthusiasts go nuts!
-We have both class names and method names with a special syntax.
-</para>
- <para>
-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
-<filename>src_new/build.xml</filename>
-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.
-</para>
-
- <para>
-Test case classes that don't require GUI components in place
-have filenames like
-<filename>Test<replaceable>*</replaceable>.java</filename>.
-They must be able to run on a headless system.
-To make sure that this works, always run your newly developed
-test cases with <command>build tests</command>.
-<footnote>
- <para>
-When running the tests using
-<command>build tests</command>
-the
-<constant>java.awt.headless</constant> is set to true.
-This means that awt is started in a mode that disallows actual presentation
-so no windows will be opened.
-On any attempt to realize a window a JavaHeadlessException is thrown making
-the test case fail.
-</para>
- </footnote>
-</para>
- <para>
-Test case classes that do require GUI components in place
-have filenames like
-<filename>GUITest<replaceable>*</replaceable>.java</filename>.
-</para>
- <para>
-Every test case class imports the JUnit framework:
-<blockquote>
- <para>
-import junit.framework.TestCase;
-</para>
- </blockquote>
-and it inherits <classname>TestCase</classname>
-(i.e. <classname>junit.framework.TestCase</classname>).
-</para>
- </sect2>
-
- <sect2>
- <title>Naming JUnit tests classes</title>
- <para>
-An ArgoUML class
-<classname>org.argouml.<replaceable>x.y</replaceable>.<replaceable>z</replaceable></classname>
-stored in the file
-<filename class="directory">src_new/org/argouml/<replaceable>x/y</replaceable>/<replaceable>z</replaceable>.java</filename>
-has its JUnit test case class called
-<classname>org.argouml.<replaceable>x.y</replaceable>.Test<replaceable>z</replaceable></classname>
-stored in the file
-<filename class="directory">tests/org/argouml/<replaceable>x/y</replaceable>/Test<replaceable>z</replaceable>.java</filename>
-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
-<classname>org.argouml.<replaceable>x.y</replaceable>.GUITest<replaceable>z</replaceable></classname>
-stored in the file
-<filename class="directory">tests/org/argouml/<replaceable>x/y</replaceable>/GUITest<replaceable>z</replaceable>.java</filename>
-</para>
- <para>
-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.
-</para>
- <para>
-If you only want to run your newly written test cases and not
-all the test cases, you could start with the command
-<command>build run-with-test-panel</command>
-and give the class name of your test case like
-<classname>org.argouml.<replaceable>x.y</replaceable>.Test<replaceable>z</replaceable></classname>
-or
-<classname>org.argouml.<replaceable>x.y</replaceable>.GUITest<replaceable>z</replaceable></classname>.
-You will then get the output in the window.
-You could run all tests in this way by specifying the special test suite
-<classname>org.argouml.util.DoAllTests</classname>
-in the same way.
-</para>
- </sect2>
-
-
- <sect2>
- <title>About the Test case Methods</title>
- <para>
-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.
-</para>
- <para>
-Try to keep the test cases as short as possible.
-There is no need in cluttering them up just to beautify the output.
-Prefer
-<programlisting>
-// Example from JUnit FAQ
-public void testIndexOutOfBoundsExceptionNotRaised()
- throws IndexOutOfBoundsException {
- ArrayList emptyList = new ArrayList();
- Object o = emptyList.get(0);
-}
-</programlisting>
-over
-<programlisting>
-public void testIndexOutOfBoundsExceptionNotRaised() {
- try {
- ArrayList emptyList = new ArrayList();
- Object o = emptyList.get(0);
- } catch (IndexOutOfBoundsException iobe) {
- fail("Index out of bounds exception was thrown.");
- }
-}
-</programlisting>
-because the code is shorter, easier to maintain and you get a better
-error message from the JUnit framework.
-</para>
- <para>
-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
-<methodname>compileTestStatics</methodname>,
-<methodname>compileTestConstructors</methodname>, and
-<methodname>compileTestMethods</methodname>
-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.
-</para>
- <example>
- <title>An example without Javadoc comments</title>
- <indexterm>
- <primary>Test cases</primary>
- <secondary>an example</secondary>
- </indexterm>
- <para>
-<programlisting>
-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());
- }
-}
-</programlisting>
-and the corresponding no-GUI-class:
-<programlisting>
-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() { }
-}
-</programlisting>
-</para>
- </example>
- </sect2>
-
- <sect2>
- <title>Improving a test case</title>
- <para>
-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.
-</para>
- <para>
-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.
-</para>
- <para>
-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.
-</para>
- <para>
-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.
-<footnote>
- <para>
-This is because the run-time dependency defaults used in Eclipse
-when creating a JUnit test configuration are based on the
-compile-time dependency settings and we don't have MDR in the
-compile-time dependencies because we want to enforce that there
-is no such dependency.
-Hopefully an upcoming code reorganization will address this problem.
-</para>
- <para>
-The simplest way is to create/run the JUnit test configuration
-and if it fails with a ExceptionInInitializer error open it with
-the Configuration editor, add the argouml-core-model-mdr project
-to the class path and then run again.
-</para>
- </footnote>
-</para>
- <para>
-This means that you should have the following priorities:
-
- <orderedlist>
- <listitem>
- <para>
-Don't use the Model subsystem.
-</para>
- <para>
-Only possible in a few simple cases.
-</para>
- </listitem>
- <listitem>
- <para>
-Use the Mock model subsystem implementation.
-</para>
- <para>
-Call the function
-<function>org.argouml.model.InitializeModel#initializeMock()</function>
-from setUp() in your test case.
-</para>
- <para>
-Only possible in a few simple cases.
-</para>
- </listitem>
- <listitem>
- <para>
-Use the real Model subsystem implementation from the
-<function>setUp()</function> function.
-</para>
- <para>
-Call the function
-<function>org.argouml.model.InitializeModel#initializeDefault()</function>
-from setUp() in your test case.
-</para>
- </listitem>
- <listitem>
- <para>
-Use the real Model subsystem implementation from the constructor.
-</para>
- <para>
-Call the function
-<function>org.argouml.model.InitializeModel#initializeDefault()</function>
-in the constructor of your test case.
-</para>
- <para>
-This is needed if your tests rely on the value in some member variables
-referencing some object retrieved from the model.
-</para>
- </listitem>
- <listitem>
- <para>
-Use the real Model subsystem implementation from the static initialization
-section of your test class.
-</para>
- <para>
-Call the function
-<function>org.argouml.model.InitializeModel#initializeDefault()</function>
-in the static initialization.
-</para>
- <para>
-This is needed if your tests rely on the value
-of some static member variables referencing
-some object retrieved from the model.
-</para>
- </listitem>
- </orderedlist>
-</para>
-
- <para>
-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.
-</para>
- </sect2>
-
- </sect1>
-
- <sect1 id="generating_documentation">
- <title>Generating documentation</title>
- <para>
-This describes how to generate the documentation for ArgoUML.
-</para>
- <para>
-If you are in a hurry, here's the quick version:
-<programlisting>
-C:\Work>svn checkout -N http://argouml.tigris.org/svn/argouml/trunk/src_new argouml/src_new
-C:\Work>svn checkout http://argouml.tigris.org/svn/argouml/trunk/documentation http://argouml.tigris.org/svn/argouml/trunk/tools
-C:\Work>set JAVA_HOME=<replaceable>C:\Programs\jdkwhatever</replaceable>
-C:\Work>cd argouml\documentation
-C:\Work\argouml\documentation>build docbook-xsl-get (first time only)
-C:\Work\argouml\documentation>build defaulthtml
-</programlisting>
-The chunked HTML versions of the Cookbook, Quick Guide, and User Manual are
-built and the results are placed in:
-<filename class="directory">C:\Work\argouml\build\documentation\defaulthtml\cookbook</filename>,
-<filename class="directory">C:\Work\argouml\build\documentation\defaulthtml\quick-guide</filename>,
-and
-<filename class="directory">C:\Work\argouml\build\documentation\defaulthtml\manual</filename>
-respectively.
-</para>
-
-
- <sect2>
- <title>Building documentation</title>
- <indexterm>
- <primary>Documentation</primary>
- <secondary>work with</secondary>
- </indexterm>
- <para>
-To build the documentation, you will need to check out the whole
-<filename class="directory">argouml/documentation</filename> directory.
-as well as the
-<filename class="directory">argouml/tools</filename> directory
-which contains the tools needed (Ant, FOP, Saxon, etc) and the file
-<filename>argouml/src_new/default.properties</filename>
-which contains the current version and other project-wide settings.
-None of the other ArgoUML source directories are needed if you are just
-building the documentation.
-</para>
-
- <para>
-The subdirectories of
-<filename class="directory">argouml/documentation</filename>,
-<filename class="directory">cookbook</filename>,
-<filename class="directory">manual</filename>, and
-<filename class="directory">quick-guide</filename>
-each contain one of the three books.
-The subdirectory
-<filename class="directory">docbook-setup</filename>
-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
-<filename class="directory">images</filename>
-contains all the required pictures for all the books.
-</para>
- <para>
-There are separate build targets available for each output format,
-as well as a target that builds all possible output formats.
-Use the command <command>build -p</command> to get a complete list
-of targets.
-</para>
- <para>
-For testing purposes while editing a manual, you probably want to
-build just a single output format for the one manual that you are
-working with. To suppress the building of the other manuals,
-you can define the following properties in your
-<filename>build.properties</filename> file:
-<programlisting>
-skip-cookbook=true
-skip-quickguide=true
-skip-argomanual=true
-</programlisting>
-
-</para>
- <para>
-When, in the <filename class="directory">documentation</filename> directory,
-you run <command>./build.sh defaulthtml</command> or one of the other targets
-that builds the documentation,
-all books are built.
-</para>
- <para>
-What happens is (the target internal-dispatcher):
-</para>
- <itemizedlist>
- <listitem>
- <para>
-The
-<filename><replaceable>manual</replaceable>/<replaceable>argomanual.xml</replaceable></filename>
-is copied by ant to
-<filename><replaceable>manual</replaceable>/<replaceable>argomanual-generated.xml</replaceable></filename>
-while doing substitution of tokens:
-(@VERSION@ to become the version as specified in
-<filename>default.properties</filename>)
-</para>
- </listitem>
-
- <listitem>
- <para>
-The file
-<filename><replaceable>manual</replaceable>/<replaceable>argomanual-generated.xml</replaceable></filename>
-is processed by the special
-<filename>docbook-setup/create-imglist.xsl</filename>
-XSL script that generates a list of included images.
-</para>
- </listitem>
-
- <listitem>
- <para>
-All included images are copied.
-</para>
- <para>
-The purpose of this is to avoid copying images not actually
-used in the document.
-</para>
- </listitem>
-
- <listitem>
- <para>
-The HTML is generated by processing the file
-<filename><replaceable>manual</replaceable>/<replaceable>argomanual-generated.xml</replaceable></filename>.
-</para>
- </listitem>
- </itemizedlist>
- <para>
-The file
-<filename><replaceable>manual</replaceable>/<replaceable>argomanual-generated.xml</replaceable></filename> is
-a temporary file that only exists while processing the XML.
-If you are editing the XML be sure to edit
-the file
-<filename><replaceable>manual</replaceable>/<replaceable>argomanual.xml</replaceable></filename>
-and not the temporary file.
-</para>
-
- </sect2>
- </sect1>
-
- <sect1 id="eclipse3">
- <sect1info>
- <author>
- <firstname>Linus</firstname>
- <surname>Tolke</surname>
- </author>
- </sect1info>
- <title>Setting up Eclipse 3</title>
- <indexterm>
- <primary>Setting up Eclipse</primary>
- </indexterm>
- <indexterm>
- <primary>Eclipse</primary>
- <secondary>Setting up the development environment</secondary>
- </indexterm>
-
- <para>
-If you are running Eclipse 3.1 or 3.2
-we have a prepared a recommended setup
-committed into our repository.
-This setup is slightly different than the ant setup
-with regard to the directory tree structure of the checked out copy
-and some special magic is used in the ant scripts
-that is controlled from the special Eclipse configurations.
-</para>
- <para>
-The prepared setup includes settings for Checkstyle within Eclipse that
-will be enabled if you have the Checkclipse Eclipse plugin installed.
-</para>
- <para>
-You need to have Subclipse installed in your Eclipse to retrieve
-the files from the repository.
-See <ulink url="http://subclipse.tigris.org/install.html"/>.
-</para>
- <para>
-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.
-</para>
-
- <sect2 id="eclipse-setup-summary">
- <title>Basic ideas of the set up</title>
- <para>
-This is a terse list of some ideas on the Eclipse set up.
-</para>
-
- <itemizedlist>
- <listitem>
- <para>Argouml in its own workspace</para>
- </listitem>
-
- <listitem>
- <para>
-No project-specific settings (compiler, JRE, style),
-instead workspace-specific settings.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Compile time dependencies are set up on the Java Build Path.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Run time dependencies are set up in the Configurations.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Configurations saved in the project where they "belong".
-</para>
- </listitem>
-
- </itemizedlist>
- </sect2>
-
- <sect2 id="eclipse-checkout">
- <title>Checking out through Eclipse</title>
- <para>
-This instruction is if you want to use Eclipse to download the source
-and it takes you up to where you can start ArgoUML from the source.
-</para>
-
- <para>
-We have Eclipse Team Project Set files prepared to make the set up automatic.
-</para>
-
- <para>
-Do the following.
-</para>
-
- <orderedlist>
- <listitem>
- <para>
-Change to the SVN Repository Explorer perspective and select
-Add SVN Repository.
-Then enter the following url
-<command>http://argouml.tigris.org/svn/argouml</command>.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Download the initial Team Project Set file and save it somewhere.
-</para>
- <para>
-Suggested by browsing to
-<filename>trunk/tools/eclipse</filename>
-and checking it out as a project.
-</para>
- <para>
-This is only needed the first time and if you don't already
-happen to have an updated checked out copy of argouml laying around.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Do File => Import and select Team Project Set and press Next.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Browse to the file
-<filename>argouml-core-projectset.psf</filename>
-and press Finish.
-</para>
-
- <para>
-Now everything is automatic even though it takes a while. What happens is:
-</para>
- <orderedlist>
- <listitem>
- <para>
-Files are downloaded from the Tigris SVN server and put into Eclipse
-projects.
-</para>
- <para>
-It is around 30Meg that is downloaded so beware if you are on a slow
-connection.
-</para>
- </listitem>
- <listitem>
- <para>
-The projects are built.
-First things that are special for ArgoUML, generated Java code,
-are created by Eclipse calling ant,
-then Eclipse kicks in and compiles the Java code.
-</para>
- </listitem>
- <listitem>
- <para>
-Eclipse finds the Configurations that are also checked out.
-</para>
- </listitem>
- </orderedlist>
- </listitem>
-
- <listitem>
- <para>
-Select Project => Clean... => Clean all projects
-and wait for everything to build again.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Verify that you can start ArgoUML from the debugger within Eclipse.
-You can do this by clicking on the little down-arrow close to the
-Debug icon in the tool bar,
-selecting Debug...,
-and finding ArgoUML in the list (under Java Application).
-</para>
- </listitem>
-
- </orderedlist>
- </sect2>
-
- <sect2>
- <title>Eclipse to help with the ArgoUML coding style</title>
- <para>
-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.
-</para>
- <para>
-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.
-</para>
-
- <itemizedlist>
- <listitem>
- <para>
-Code conventions.
-</para>
- <orderedlist>
- <listitem>
- <para>
-Select in the menu Window => Preferences.
-</para>
- </listitem>
- <listitem>
- <para>
-Then select Java => Code Style => Formatter.
-</para>
- </listitem>
- <listitem>
- <para>
-For Eclipse 3.2 you do:
-Select Java Conventions [built-in].
-</para>
- </listitem>
- <listitem>
- <para>
-For Eclipse 3.1 you do:
-Select Import and give the file
-<filename>eclipse/eclipse-argo-formatter.xml</filename>
-located in the argouml-core-tools project that you just checked out.
-</para>
- <para>
-This takes care of the Eclipse-built-in bug
-(<ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=104765"/>).
-</para>
- </listitem>
- <listitem>
- <para>
-Press OK.
-</para>
- </listitem>
- </orderedlist>
-
- <para>
-This will give you Code Conventions exactly like the Sun Coding Style
-that we use in the ArgoUML project.
-</para>
- </listitem>
-
- <listitem>
- <para>
-New file templates.
-</para>
-
- <orderedlist>
- <listitem>
- <para>
-Select in the menu Window => Preferences.
-</para>
- </listitem>
- <listitem>
- <para>
-Then select Java => Code Style => Code Templates.
-</para>
- </listitem>
- <listitem>
- <para>
-Select Import and give the file
-<filename>eclipse/eclipse-argo-codetemplates.xml</filename>
-located in the argouml-core-tools project that you just checked out.
-</para>
- </listitem>
- <listitem>
- <para>
-Press OK.
-</para>
- </listitem>
- </orderedlist>
-
- <para>
-This will set up templates to be used when using the Eclipse functions
-for creating files, functions, types and Javadoc...
-</para>
-
- </listitem>
- </itemizedlist>
- </sect2>
-
- <sect2>
- <title>Eclipse to automatically find problems in the code</title>
- <para>
-This instruction is to set up Eclipse to automatically find
-what, in the ArgoUML project, could be considered problems in the code.
-</para>
- <para>
-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.
-</para>
- <para>
-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.
-</para>
- <itemizedlist>
- <listitem>
- <para>
-Compiler compliance level.
-</para>
- <para>
- See in the menu Window => Preferences.
- Then select
- Java => Compiler.
-At the right hand side set
-Compiler compliance level: 5.0.
-</para>
- <para>
-Check Use default compliance settings.
-</para>
- <para>
-In the ArgoUML project we have decided to keep source compliance to Java5
-(See <xref linkend="REQ7"/>).
-This setting enables Eclipse to tell you where some
-Java6
-features have crept in.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Find forgotten and incorrect Javadoc comments.
-</para>
- <para>
-In the menu select Window => Preferences.
-Then select
-Java => Compiler => Javadoc.
-Suggested settings for these tabs
-(Only things diverting from the Eclipse defaults are listed):
-</para>
- <itemizedlist>
- <listitem>
- <para>
-Javadoc => Malformed Javadoc comments:
-Warning,
-Private,
-Check all reports.
-</para>
- </listitem>
- <listitem>
- <para>
-Javadoc => Missing Javadoc tags: Warning, Private,
-check Check overriding and implementing methods.
-</para>
- </listitem>
- <listitem>
- <para>
-Javadoc => Missing Javadoc comments: Warning, Protected,
-uncheck Check overriding and implementing methods.
-</para>
- </listitem>
- </itemizedlist>
- <para>
-These problems
-(except missing Javadoc comments)
-are also found by Checkstyle so if you are
-running Checkclipse (See <xref linkend="checkclipse"/>)
-put this in Ignore instead.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Code that hides other code.
-</para>
- <para>
-In the menu select Window => Preferences.
-Then select
-Java => Compiler => Error/Warnings.
-Suggested settings for these tabs
-(Only things diverting from the Eclipse defaults are listed):
-</para>
- <itemizedlist>
- <listitem>
- <para>
-Potential programming problems => Serializable class without serialVersionUID:
-Ignore
-</para>
- <para>
-We don't use serialization in the ArgoUML project anyway.
-</para>
- </listitem>
- <listitem>
- <para>
-Potential programming problems =>
-Possible accidental boolean assignment: Warning.
-</para>
- </listitem>
- <listitem>
- <para>
-Name shadowing and conflicts =>
-Local variable declaration hides another field or variable: Warning,
-check Include constructor or setter method parameters.
-</para>
- </listitem>
- <listitem>
- <para>
-Name shadowing and conflicts =>
-Field declaration hides another field or variable: Warning.
-</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>
-Find Code that shall be removed.
-</para>
- <para>
-In the menu select Window => Preferences.
-Then select
-Java => Compiler => Error/Warnings.
-Suggested settings for these tabs
-(Only things diverting from the Eclipse defaults are listed):
-</para>
- <itemizedlist>
- <listitem>
- <para>
-Unnecessary code => Local variable is never read: Warning.
-</para>
- </listitem>
- <listitem>
- <para>
-Unnecessary code => Parameter is never read: Warning.
-</para>
- </listitem>
- <listitem>
- <para>
-Unnecessary code => Unused or unread private members: Warning.
-</para>
- </listitem>
- <listitem>
- <para>
-Unnecessary code => Unnecessary semicolon: Warning.
-</para>
- </listitem>
- <listitem>
- <para>
-Unnecessary code => Unnecessary cast or 'instanceof' operation: Warning.
-</para>
- </listitem>
- <listitem>
- <para>
-Unnecessary code =>
-Unnecessary declaration of thrown checked exception: Warning.
-</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- </itemizedlist>
- </sect2>
-
- <sect2 id="checkclipse">
- <title>Settings for Checkclipse</title>
- <para>
-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.
-</para>
- <para>Get the latest Checkclipse kit from SourceForge at
- <ulink url="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
- <ulink url="http://checkstyle.sourceforge.net/"/>
- for reference.)
- </para>
- <para>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.
- </para>
- <para>
- In the Java perspective, select the project argouml,
- i.e. the icon at the top of the Package Explorer.
- Then, in the menu, select Project => Properties,
-select Checkclipse (appears only if Checkclipse is correctly installed)
-and then fill the fields like this:
-</para>
- <itemizedlist>
- <listitem>
- <para>Enable Checkstyle -
-Checked.
-</para>
- </listitem>
- <listitem>
- <para>Set Project Classloader - Checked.</para>
- </listitem>
- <listitem>
- <para>Checkstyle Configuration File:
-<filename>/argouml-core-tools/checkstyle/checkstyle_argouml.xml</filename>
-in the argouml-core-tools project.
-</para>
- </listitem>
- <listitem>
- <para>Checkstyle Properties File:
-<filename>/argouml-core-tools/checkstyle/checkstyle.properties</filename>
-in the argouml-core-tools project.
-</para>
- </listitem>
- </itemizedlist>
- <para>
-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.
-</para>
- </sect2>
-
- <sect2 id="eclipse-running-junit">
- <title>Running JUnit test cases from within Eclipse</title>
- <para>
-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.
-</para>
- <para>
-The Model subsystem is separated in two parts:
- <itemizedlist>
- <listitem>
- <para>
-The interfaces and some bootstrap code
-in the argouml-core-model Eclipse project.
-</para>
- </listitem>
- <listitem>
- <para>
-The MDR implementation in the argouml-core-model-mdr Eclipse project.
-</para>
- </listitem>
- </itemizedlist>
-There is also for test purposes a partly implemented
-Mock implementation of the model subsystem in the
-<classname>org.argouml.model.MockModelImplementation</classname>-class
-for the purpose of testing the interfaces and the bootstrap code
-but it requires the test cases to be written especially for that.
-</para>
- <para>
-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.
-</para>
- <para>
-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.
-</para>
- <para>
-The simplest way to solve this is to:
- <orderedlist>
- <listitem>
- <para>
-Create the test (by right-clicking on any of the test classes
-and select Run as JUnit Test or Debug as JUnit Test).
-</para>
- <para>
-The test fails with a
-<exceptionname>java.lang.ExceptionInInitializerError</exceptionname>
-on the first reference to Model.
-If it doesn't then the perhaps the test case doesn't use the Model.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Select Debug... or Run... to get the configuration editing box.
-It has remembered the test case and it is selected.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Add the argouml-core-model-mdr to the class path.
-</para>
-
- <para>
-Classpath tab,
-Select User Entries,
-Add Projects,
-Check argouml-core-model-mdr,
-make sure
-Add exported entries of selected projects
-and
-Add required projects of selected projects are checked,
-Press OK,
-Press Debug or Run.
-Eclipse will remember these changes to that configuration
-but you will have to do it all over again once for each new test case.
-</para>
- </listitem>
- </orderedlist>
-</para>
-
- <sect3 id="running-all-junit-from-within-eclipse">
- <title>Running all JUnit test cases from within Eclipse</title>
- <para>
-The description so far describes how to do this for a single test case
-at the time.
-If you want to run all test cases in one go from within Eclipse
-it is also possible.
-We have not prepared that for three reasons:
- <itemizedlist>
- <listitem>
- <para>
-Some of the tests fail when run in this way.
-</para>
- <para>
-The guess (Linus July 2006) is that this depends on the fact that
-Eclipse doesn't start each test in its own JVM and some of the tests
-relies on a fresh environment (empty models...).
-Let's hope that an upcoming version of Eclipse includes a function
-to allow us to specify that the tests are to be run each in its own JVM.
-</para>
-
- <para>
-Another cause might be that the tests rely on certain other files being
-in specified places that the Eclipse set up doesn't provide.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Maintaining the Configuration.
-</para>
- <para>
-Since we have an Eclipse setup with a mismatch between the
-compile time dependencies and the run time dependencies
-this Configuration contains references to specific jar-files.
-This means a maintenance problem whenever changing version of
-a dependency.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Selection of tests.
-</para>
- <para>
-In the project we keep all tests in the same tree,
-whether they are working or not.
-We distinguish between test classes with names starting with "Test", "GUITest",
-and neither of them.
-The ones starting with "Test" or "GUITest" are official tests
-that should be working.
-All others are tests that are never run automatically.
-They are perhaps used for other purposes.
-In Eclipse, there is no way to specify this so the description below
-will run all tests.
-</para>
- <para>
-Such a test is the DoAllTests-test suite that runs all tests so
-tests risk to be run twice.
-</para>
- </listitem>
- </itemizedlist>
-</para>
- <para>
-If you want to test this, this is what you do:
-</para>
-
- <itemizedlist>
- <listitem>
- <para>
-Right-click on the project argouml-core-tests.
-</para>
- </listitem>
-
- <listitem>
- <para>
-On the multilevel pop-up that opens, select
-Run As... JUnit Test or
-Debug As... JUnit Test.
-</para>
- </listitem>
- <listitem>
- <para>
-A Configuration is created on that project with the
-Run all tests in the selected project, package or source folder:
-checked
-and the configuration is started/launched.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Stop the running Configuration.
-</para>
- <para>
-The newly Configuration has the same problem as every single
-test above with the model subsystem so it won't work.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Press Debug... or Run... to open the Configuration editor.
-</para>
- <para>
-The newly created Configuration argouml-core-test is selected.
-</para>
- </listitem>
- <listitem>
- <para>
-Add the argouml-core-model-mdr project to the class path.
-</para>
- <para>
-This is done by:
- <itemizedlist>
- <listitem>
- <para>selecting the Classpath tab,</para>
- </listitem>
-
- <listitem>
- <para>selecting argouml-core-tests under User Entries,</para>
- </listitem>
-
- <listitem>
- <para>clicking Add projects, and</para>
- </listitem>
-
- <listitem>
- <para>
-selecting the argouml-core-model-mdr project and press OK.
-</para>
- </listitem>
- </itemizedlist>
-</para>
- </listitem>
-
- <listitem>
- <para>
-Run all the tests by pressing Debug or Run.
-</para>
- </listitem>
- </itemizedlist>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1>
- <sect1info>
- <author>
- <firstname>Linus</firstname>
- <surname>Tolke</surname>
- </author>
- </sect1info>
- <title>Settings for NetBeans</title>
-
- <warning>
- <para>
-It is unclear what version of NetBeans these settings work in.
-If you test it, let us know so that we can update the Cookbook.
-</para>
- </warning>
-
- <para>
-The argouml style guides correspond to the following settings in NetBeans:
-</para>
- <itemizedlist>
- <listitem>
- <para>
-In (Tools =>) Options => Editing => Editor Settings => Java Editor
- </para>
- <para>
-Tab Size = 8
- </para>
- </listitem>
- <listitem>
- <para>
-In (Tools =>) Options => Editing =>
-Indentation Engines => Java Indentation Engine
- </para>
- <para>
-Add Newline Before Brace: False,
-Add Space Before Parenthesis: False,
-Expand Tabs to Spaces: False,
-Number of Spaces per Tab: 4 (Should probably be read as
-Number of Spaces per indentation level).
- </para>
- </listitem>
- </itemizedlist>
- </sect1>
-
- <sect1>
- <sect1info>
- <author>
- <firstname>Linus</firstname>
- <surname>Tolke</surname>
- </author>
- </sect1info>
- <title>Settings for Emacs</title>
- <para>
-These style guides correspond to the default Java settings in Emacs:
-<programlisting>
+ <para>These style guides correspond to the default Java settings in Emacs:</para>
+
+ <programlisting>
("java"
(c-basic-offset . 4)
(c-comment-only-line-offset 0 . 0)
@@ -2607,453 +1306,192 @@
(access-label . 0)
(inher-cont . c-lineup-java-inher)
(func-decl-cont . c-lineup-java-throws)))
-</programlisting>
- </para>
- </sect1>
-
-
-
- <sect1 id="release_process">
- <title>Making a release</title>
- <indexterm>
- <primary>Making a release</primary>
- </indexterm>
- <para>
-The purpose of this chapter is
-to simplify the procedure for the person actually doing the release work, and
-to make sure that everything is done in the exact same way
-every time without anything being forgotten.
-</para>
- <para>
-The scripts involved have been developed and are mostly run
-on a Cygwin system.
-They will hopefully work on any UNIX system but most likely they
-will need some adjustments.
-</para>
-
- <para>
-The scripts and tools used specifically for the build are maintained
-in the argoumlinstaller project.
-From the argouml project the files
-<filename>argouml/src_new/build.xml</filename> and
-other <filename>build.xml</filename> files
-are reused.
-</para>
-
- <para>
-Prerequisites (what you need to be able to do this):
-<itemizedlist>
- <listitem>
- <para>
-Subversion access to the argouml projects (to create the releases branch/tag).
-The projects involved are specified by
-<filename>argoumlinstaller/build-release.sh</filename>.
-</para>
- </listitem>
- <listitem>
- <para>
-Subversion access to the argouml-downloads project (to upload the result).
-</para>
- </listitem>
- <listitem>
- <para>
-A machine with 3GB of disk to use for this purpose
-(September 2006).
-</para>
- <para>
-This is probably the machine you use for your development if you are
-an argouml developer.
-</para>
- <para>
-The machine needs
-Internet access (it is not a small download and upload so at least
-128KB Internet connection to keep the time reasonable < 2 hours),
-the correct version of Java installed (should be a JDK for Java5),
-SVN installed,
-Unix or Cygwin to be able to run the scripts.
-</para>
- </listitem>
-
- <listitem>
- <para>
-The argoumlinstaller and argouml-downloads projects checked out
-alongside each other.
-</para>
-
- <para>
-If this is not in place from a previous release this is done using
-the commands
-<programlisting>
-cd wherever
-svn co http://argoumlinstaller.tigris.org/svn/argoumlinstaller/trunk argoumlinstaller
-svn co http://argouml-downloads.tigris.org/svn/argouml-downloads/trunk argouml-downloads
-</programlisting>
-Note that the argouml-downloads checkout is large (almost 1.5 GB) and
-will take a considerable time to check out so you'd better do this in
-advance.
-</para>
- </listitem>
-
- <listitem>
- <para>
-You have generated a key to sign the jar files (for Java Web Start).
-</para>
- <para>
-Run the command
-<command>keytool -list -v</command>
-and give the keystore password
-<parameter>secret</parameter>.
-You should have a key named argouml that is valid several months
-in the future.
-</para>
- <para>
-This is to make sure that you have a valid key
-for the purpose of signing the jar files.
-</para>
- <sidebar>
- <para>
-Since the ArgoUML project and the Tigris organization are loose
-organizations we cannot buy a "real" key.
-The keys we use are the unsigned keys
-that can be generated by anyone using the keytool provided with Java.
-</para>
- </sidebar>
- <para>
-A key is generated with the command
-<command>keytool -genkey -alias argouml -storepass secret</command>.
-</para>
- <para>
-By default these keys have a validity of just three (3) months
-but by giving the
-<parameter>-validity <replaceable>days</replaceable></parameter>
-the validity can be extended.
-</para>
-
- <para>
-Don't forget to upload your new key to the Downloads area.
-This is for those who want to see the key on the site
-separately.
-</para>
-
- </listitem>
-
- </itemizedlist>
-</para>
-
- <para>
-Here are the steps to be done when one actually does a release:
-</para>
-
- <orderedlist>
- <listitem>
- <para>
-Check for new projects.
-</para>
- <para>
-If there are any new projects to be included in the release,
-add them to the list of projects in
-<filename>argoumlinstaller/build-release.sh</filename>.
-You also need to create the
-<filename>releases</filename>-directory at the top of the
-SVN repository.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Create the release branch/tag and checkout that copy.
-</para>
-
- <para>
-This is done using the command
-<command>./build-release.sh -tc</command>
-in the argoumlinstaller project
-and giving the release name.
-</para>
-
- <para>
-You must have set JAVA_HOME for this to work.
-</para>
-
- <para>
-The script will check that the releases top directory is present in
-all the involved projects and that the given release name is not
-already present in any of the involved projects.
-</para>
- </listitem>
-
- <listitem>
- <para>Set the <methodname>argo.core.version</methodname>
-to not include the "PRE-" part.
-</para>
- <para>
-This is done in the <filename>default.properties</filename>-file
-in
-<filename>build/VERSION_<replaceable>GIVEN_VERSION</replaceable>/argouml/src_new</filename>
-and then, commit the file.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Build ArgoUML and the sub-projects,
-and sign the jar files.
-</para>
- <para>
-This is done using the command
-<command>./build-release.sh -bs</command>
-</para>
- </listitem>
-
- <listitem>
- <para>
-Build the pdf version of the documentation.
-</para>
-
- <para>
-This is done using the command
-<command>./build-release.sh -d</command>
-</para>
- </listitem>
-
- <listitem id="issuezilla_release_maintenance">
- <para>
-Go through Issuezilla and check things.
-</para>
- <para>
-Things to check are:
-</para>
- <orderedlist>
- <listitem>
- <para>
-That there is a Version created in Issuezilla for the newly created release.
-</para>
- <para>
-The purpose of this is to make it possible for everyone
-to report bugs on the new release.
-</para>
- </listitem>
- <listitem>
- <para>
-Make sure that the upcoming releases have
-target milestones created for them.
-This needs to be done for all components that has the same
-release scheme.
-Also see that the numbering is the same in all components and
-that it is in the correct chronological order
-except for the not yet done releases that come before the already completed.
-</para>
- </listitem>
- <listitem>
- <para>
-Change the target milestones of all the not yet resolved issues
-for this release to ---.
-</para>
- </listitem>
- <listitem>
- <para>
-Change the target milestones of
-any fixed issue
-in component argouml
-with target milestone ---
-to that of the current release.
-</para>
- <para>
-This is probably some developer that has fixed an issue but forgotten to
-set the target milestone correctly.
-</para>
- </listitem>
- <listitem>
- <para>
-Move all issues reported on 'current' to this release
-(for the component argouml).
-</para>
- <para>
-These items were reported between the previous version and this version.
-Since 'current' will be reused for the next release, they need to be
-locked to the closest release to where they were found.
-</para>
- </listitem>
- <listitem id="reopen_remind_and_later">
- <para>Reopen RESOLVED/REMIND</para>
- <para>
-This can also be a good time to change all
-RESOLVED/REMIND.
-Search for them and Reopen them.
-</para>
- </listitem>
- <listitem id="check_for_later">
- <para>Check RESOLVED/LATER</para>
- <para>
-It could also be good to check that all
-RESOLVED/LATER has a valid target milestone (must be an upcoming milestone).
-Search for them and Reopen the ones that haven't.
-Also, if the milestone denotes or is going to be resolved in
-the upcoming release, Reopen them with a comment that they are now
-active.
-</para>
- </listitem>
- </orderedlist>
- </listitem>
-
- </orderedlist>
-
- <para>
-After this, the work continues with the installers.
-</para>
- <para>
-This is what you do:
-</para>
-
- <orderedlist>
- <listitem>
- <para>
-Create the zip files and the tgz files,
-copy the documentation,
-copy changed Java web start files and create new Java web start jnlp files.
-</para>
- <para>
-This is done by the command
-<command>./official.sh</command>.
-</para>
- </listitem>
-
- <listitem>
- <para>
-For Java Web Start,
-update the "Latest development" or perhaps the
-"Latest stable" files
-essentially with the contents of the newly created JNLP file.
-</para>
-
- <para>
-These files are located in the
-<filename class="directory">svn/argouml-downloads/www/jws</filename>-directory.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Update the index file for the downloads project to point out the new release.
-</para>
-
- <para>
-It should point out the release at
-<filename>/argouml-<replaceable>RELEASENAME</replaceable>/</filename>,
-the Java web start file at
-<filename>/jws/argouml-<replaceable>RELEASENAME</replaceable>.jnlp</filename>.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Commit the release in the argouml-downloads project
-</para>
- <para>
-The following commands will do it for you:
-<programlisting>
-cd ../argouml-downloads/www
-svn commit -m'The release <replaceable>RELEASENAME</replaceable>.'
-</programlisting>
-</para>
- </listitem>
- </orderedlist>
-
- <sect2 id="release_process_test_failed">
- <title>The release did not work</title>
- <indexterm>
- <primary>Troubleshooting</primary>
- <secondary>during the release work</secondary>
- </indexterm>
-
- <warning>
- <para>
-This description is not yet updated to fit the subversion set up
-for ArgoUML.
-</para>
- </warning>
-
- <para>
-This shouldn't happen! This really shouldn't happen!
-</para>
- <para>
-The reason that this has happened is that one of the developers
-has made a mistake.
-You now must decide a way forward.
-</para>
- <sect3 id="release_work_fix_problem_yourself">
- <title>Fix the problem yourself.</title>
- <para>
-If the problem is obvious to you and you can fix it quickly, do so.
-This is done by doing the following:
-<itemizedlist>
- <listitem>
- <para>Make the release tag into a branch</para>
- </listitem>
- <listitem>
- <para>Check out that branch</para>
- </listitem>
- <listitem>
- <para>Fix the problem in your checked out copy</para>
- </listitem>
- <listitem>
- <para>Commit the problem to the branch</para>
- </listitem>
- <listitem>
- <para>Continue the build process</para>
- <para>
-This is done by restarting the <command>build dist-release</command>-command
-and from that point on working in the branch instead of at the tag.
-</para>
- </listitem>
- <listitem>
- <para>
-Explain to the culprit what mistakes he has made and how to fix it.
-</para>
- <para>
-It is now his responsibility to make sure that the problem will not
-appear in the next version.
-He can do this either by merging in your fix or by fixing the problem
-in some other way.
-</para>
- <para>
-At this point an in-detail description of how poor programming skills
-the culprit has and how ugly his mother is, is probably in place but
-please keep it constructive!
-Remember, you might be mistaken when you guess who the responsible is.
-</para>
- </listitem>
- </itemizedlist>
-</para>
- </sect3>
-
- <sect3>
- <title>
-Delay the release waiting for someone to fix the problem.
-</title>
- <para>
-Create the branch as described in
-<xref linkend="release_work_fix_problem_yourself"/>.
-Then tell the culprit and everyone on the developer list
-what the problem is and that it is to be fixed in the
-release branch a.s.a.p.
-</para>
- <para>
-Monitor the changes made to the branch to verify that
-no one commits anything else but the solutions to the
-problems.
-</para>
- <para>
-When you get notified that it is completed,
-update your checked out copy and continue the release work.
-</para>
- </sect3>
- </sect2>
+ </programlisting>
- </sect1>
+ </section>
-</chapter>
+ <section xml:id="release_process">
+ <title>Making a release</title>
+
+ <indexterm>
+ <primary>Making a release</primary>
+ </indexterm>
+
+ <para>The purpose of this chapter is to simplify for the person that is actually doing the release work and to make sure that everything is done in the exact same way every time and nothing is forgotten. </para>
+ <para>The scripts involved have been developed and are mostly run on a Cygwin system. They will hopefully work on any UNIX system but most likely they will need some adjustments. </para>
+ <para>The scripts and tools used specifically for the build are maintained in the argoumlinstaller project. From the argouml project the files <filename>argouml/src_new/build.xml</filename> and other <filename>build.xml</filename> files are reused. </para>
+ <para>Prerequisites (what you need to be able to do this):
+ <itemizedlist>
+ <listitem>
+ <para>Subversion access to the argouml projects (to create the releases branch/tag). The projects involved are specified by <filename>argoumlinstaller/build-release.sh</filename>. </para>
+ </listitem>
+ <listitem>
+ <para>Subversion access to the argouml-downloads project (to upload the result). </para>
+ </listitem>
+ <listitem>
+ <para>A machine with 3GB of disk to use for this purpose (September 2006). </para>
+ <para>This is probably the machine you use for your development if you are an argouml developer. </para>
+ <para>The machine needs Internet access (it is not a small download and upload so at least 128KB Internet connection to keep the time reasonable < 2 hours), the correct version of Java installed (should be a JDK for Java5), SVN installed, Unix or Cygwin to be able to run the scripts. </para>
+ </listitem>
+ <listitem>
+ <para>The argoumlinstaller and argouml-downloads projects checked out alongside each other. </para>
+ <para>If this is not in place from a previous release this is done using the commands <programlisting> cd wherever svn co http://argoumlinstaller.tigris.org/svn/argoumlinstaller/trunk argoumlinstaller svn co http://argouml-downloads.tigris.org/svn/argouml-downloads/trunk argouml-downloads </programlisting> Note that the argouml-downloads checkout is large (almost 1.5 GB) and will take a considerable time to check out so you'd better do this in advance. </para>
+ </listitem>
+ <listitem>
+ <para>You have generated a key to sign the jar files (for Java Web Start). </para>
+ <para>Run the command <command>keytool -list -v</command> and give the keystore password <parameter>secret</parameter>. You should have a key named argouml that is valid several months in the future. </para>
+ <para>This is to make sure that you have a valid key for the purpose of signing the jar files. </para>
+ <sidebar>
+ <para>Since the ArgoUML project and the Tigris organization are loose organizations we cannot buy a "real" key. The keys we use are the unsigned keys that can be generated by anyone using the keytool provided with Java. </para>
+ </sidebar>
+ <para>A key is generated with the command <command>keytool -genkey -alias argouml -storepass secret</command>. </para>
+ <para>By default these keys have a validity of just three (3) months but by giving the <parameter>-validity <replaceable>days</replaceable></parameter> the validity can be extended. </para>
+ <para>Don't forget to upload your new key to the Downloads area. This is for those who want to see the key on the site separately. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>Here are the steps to be done when one actually does a release: </para>
+
+ <orderedlist>
+ <listitem>
+ <para>Check for new projects. </para>
+ <para>If there are any new projects to be included in the release, add them to the list of projects in <filename>argoumlinstaller/build-release.sh</filename>. You also need to create the <filename>releases</filename>-directory at the top of the SVN repository. </para>
+ </listitem>
+ <listitem>
+ <para>Create the release branch/tag and checkout that copy. </para>
+ <para>This is done using the command <command>./build-release.sh -tc</command> in the argoumlinstaller project and giving the release name. </para>
+ <para>You must have set JAVA_HOME for this to work. </para>
+ <para>The script will check that the releases top directory is present in all the involved projects and that the given release name is not already present in any of the involved projects. </para>
+ </listitem>
+ <listitem>
+ <para>Set the <methodname>argo.core.version</methodname> to not include the "PRE-" part. </para>
+ <para>This is done in the <filename>default.properties</filename>-file in <filename>build/VERSION_<replaceable>GIVEN_VERSION</replaceable>/argouml/src_new</filename> and then, commit the file. </para>
+ </listitem>
+ <listitem>
+ <para>Build ArgoUML and the sub-projects, and sign the jar files. </para>
+ <para>This is done using the command <command>./build-release.sh -bs</command>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Build the pdf version of the documentation. </para>
+ <para>This is done using the command <command>./build-release.sh -d</command>
+ </para>
+ </listitem>
+
+ <listitem xml:id="issuezilla_release_maintenance">
+ <para>Go through Issuezilla and check things. </para>
+ <para>Things to check are: </para>
+ <orderedlist>
+ <listitem>
+ <para>That there is a Version created in Issuezilla for the newly created release. </para>
+ <para>The purpose of this is to make it possible for everyone to report bugs on the new release. </para>
+ </listitem>
+ <listitem>
+ <para>Make sure that the upcoming releases have target milestones created for them. This needs to be done for all components that has the same release scheme. Also see that the numbering is the same in all components and that it is in the correct chronological order except for the not yet done releases that come before the already completed. </para>
+ </listitem>
+ <listitem>
+ <para>Change the target milestones of all the not yet resolved issues for this release to ---. </para>
+ </listitem>
+ <listitem>
+ <para>Change the target milestones of any fixed issue in component argouml with target milestone --- to that of the current release. </para>
+ <para>This is probably some developer that has fixed an issue but forgotten to set the target milestone correctly. </para>
+ </listitem>
+ <listitem>
+ <para>Move all issues reported on 'current' to this release (for the component argouml). </para>
+ <para>These items were reported between the previous version and this version. Since 'current' will be reused for the next release, they need to be locked to the closest release to where they were found. </para>
+ </listitem>
+ <listitem xml:id="reopen_remind_and_later">
+ <para>Reopen RESOLVED/REMIND</para>
+ <para>This can also be a good time to change all RESOLVED/REMIND. Search for them and Reopen them. </para>
+ </listitem>
+ <listitem xml:id="check_for_later">
+ <para>Check RESOLVED/LATER</para>
+ <para>It could also be good to check that all RESOLVED/LATER has a valid target milestone (must be an upcoming milestone). Search for them and Reopen the ones that haven't. Also, if the milestone denotes or is going to be resolved in the upcoming release, Reopen them with a comment that they are now active. </para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ </orderedlist>
+
+ <para>After this, the work continues with the installers. </para>
+ <para>This is what you do: </para>
+
+ <orderedlist>
+ <listitem>
+ <para>Create the zip files and the tgz files, copy the documentation, copy changed Java web start files and create new Java web start jnlp files. </para>
+ <para>This is done by the command <command>./official.sh</command>. </para>
+ </listitem>
+ <listitem>
+ <para>For Java Web Start, update the "Latest development" or perhaps the "Latest stable" files essentially with the contents of the newly create JNLP file. </para>
+ <para>These files are located in the <filename class="directory"
+ >svn/argouml-downloads/www/jws</filename>-directory. </para>
+ </listitem>
+ <listitem>
+ <para>Update the index file for the downloads project to point out the new release. </para>
+ <para>It should point out the release at <filename>/argouml-<replaceable>RELEASENAME</replaceable>/</filename>, the Java web start file at <filename>/jws/argouml-<replaceable>RELEASENAME</replaceable>.jnlp</filename>. </para>
+ </listitem>
+ <listitem>
+ <para>Commit the release in the argouml-downloads project </para>
+ <para>The following commands will do it for you: <programlisting> cd ../argouml-downloads/www svn commit -m'The release <replaceable>RELEASENAME</replaceable>.' </programlisting>
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <section xml:id="release_process_test_failed">
+ <title>The release did not work</title>
+
+ <indexterm>
+ <primary>Troubleshooting</primary>
+ <secondary>during the release work</secondary>
+ </indexterm>
+ <warning>
+ <para>This description is not yet updated to fit the subversion set up for ArgoUML. </para>
+ </warning>
+
+ <para>This shouldn't happen! This really shouldn't happen! </para>
+ <para>The reason that this has happened is that one of the developers has made a mistake. You now must decide a way forward. </para>
+
+ <section xml:id="release_work_fix_problem_yourself">
+ <title>Fix the problem yourself.</title>
+
+ <para>If the problem is obvious to you and you can fix it quickly, do so. This is done by doing the following:
+ <itemizedlist>
+ <listitem>
+ <para>Make the release tag into a branch</para>
+ </listitem>
+ <listitem>
+ <para>Checked out that branch</para>
+ </listitem>
+ <listitem>
+ <para>Fix the problem in your checked out copy</para>
+ </listitem>
+ <listitem>
+ <para>Commit the problem in the branch</para>
+ </listitem>
+ <listitem>
+ <para>Continue the build process</para>
+ <para>This is done by restarting the <command>build dist-release</command>-command and from that point on working in the branch instead of at the tag. </para>
+ </listitem>
+ <listitem>
+ <para>Explain to the culprit what mistakes he has made and how to fix it. </para>
+ <para>It is now his responsibility to make sure that the problem will not appear in the next version. He can do this either by merging in your fix or by fixing the problem in some other way. </para>
+ <para>At this point an in-detail description of how poor programming skills the culprit has and how ugly his mother is, is probably in place but please keep it constructive! Remember, you might be mistaken when you guess who the responsible is. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section>
+ <title> Delay the release waiting for someone to fix the problem. </title>
+
+ <para>Create the branch as described in <xref xlink:href="release_work_fix_problem_yourself" />. Then tell the culprit and everyone on the developer list what the problem is and that it is to be fixed in the release branch a.s.a.p. </para>
+ <para>Monitor the changes made to the branch to verify that no one commits anything else but the solutions to the problems. </para>
+ <para>When you get notified that it is completed, update your checked out copy and continue the release work. </para>
+ </section>
+ </section>
+ </section>
+</chapter>
<!-- Local stuff for Emacs - please do not delete
Local Variables:
@@ -3065,4 +1503,4 @@
indent-tabs-mode: nil
End:
--->
+-->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/changelog.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/changelog.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/changelog.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/changelog.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/changelog.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/changelog.xml 2008-01-15 19:22:21-0800
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
// Copyright (c) 1996-2007 The Regents of the University of California. All
@@ -25,698 +25,710 @@
// UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
-->
-<preface id="changelog">
- <title>Change Log</title>
-
- <para>
-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.
-</para>
-
- <table>
- <title>Changes done</title>
- <tgroup cols="3">
- <colspec colnum="1" colname="When" colwidth="1*"/>
- <colspec colnum="2" colname="What" colwidth="5*"/>
- <colspec colnum="3" colname="Who" colwidth="1.5*"/>
- <thead>
- <row>
- <entry>When</entry>
- <entry>What</entry>
- <entry>Who</entry>
- </row>
- </thead>
- <!--
- Fill with lines like this. Newest entry first.
-
- Also add a link to the new text (if any).
-
-
- <tbody valign="top">
- <row>
- <entry>2007-01-</entry>
- <entry>
-Change to XXX.
-(See <xref linkend="xxx"/>).
- </entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
- -->
-
- <tbody valign="top">
- <row>
- <entry>2007-01-16</entry>
- <entry>
-Change to the definition of the subsystem.
-Added the responsibility for wellformedness rules.
-(See <xref linkend="comp-model-purpose"/>).
- <note>
- <title>Design decision - Bob Tarling 2007-02-16</title>
- <para>
-The Model subsystem implements wellformedness rules.
-</para>
- </note>
- </entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2007-01-18</entry>
- <entry>
-Added instructions on how to configure Subversion.
-(See <xref linkend="starting"/>).
- </entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2007-01-07</entry>
- <entry>
-Change to the process of verifying issues to allow the reporter to
-more freedom.
-(See <xref linkend="rolesofworkers"/>,
-<xref linkend="verify_resolved_fixed"/>,
-<xref linkend="verify_resolved_invalid"/>, and
-<xref linkend="close_verified_issue"/>).
- </entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
-
- <tbody valign="top">
- <row>
- <entry>2006-12-30</entry>
- <entry>
-Change how we handle problems in
-the JRE and
-other SW not delivered with ArgoUML.
-(See <xref linkend="issues_dependencies"/>).
- </entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2006-10-07</entry>
- <entry>
-Removed mentions of CVS.
- </entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2006-10-01</entry>
- <entry>
-Change the description on how to check out and build with Eclipse
-to fit the Subversion set up (and Eclipse 3.2).
-(See <xref linkend="eclipse3"/>).
- </entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2006-09-30</entry>
- <entry>
-Change to describe the new release build mechanism based on subversion
-(See <xref linkend="release_process"/>).
- </entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2006-09-12</entry>
- <entry>
-Removed the manual tests.
-Removed the description on how to publish the documentation.
-Updated the download and build section for Subversion.
-(See <xref linkend="buildingandtools"/>).
- </entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2006-07-14</entry>
- <entry>
-Added a section on how to run all JUnit test cases from within Eclipse.
-(See <xref linkend="running-all-junit-from-within-eclipse"/>).
- </entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2006-06-24</entry>
- <entry>
-Added explanation on different kinds of releases and how we work with them.
-(See <xref linkend="proc-create-stable-releases"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2006-06-19</entry>
- <entry>
-Added a description on how to run JUnit tests from within Eclipse.
-(See <xref linkend="eclipse-running-junit"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
-
- <tbody valign="top">
- <row>
- <entry>2006-05-28</entry>
- <entry>
-Renamed subprojects to dependencies.
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2006-05-14</entry>
- <entry>
-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 <xref linkend="groundrules"/>,
-and
-<xref linkend="repository-contents"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2006-05-14</entry>
- <entry>
-Moved the Terminology into the Cookbook.
-(See <xref linkend="terminology"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2006-05-13</entry>
- <entry>
-Change to the introduction to the ArgoUML project to reflect that
-there are several Tigris projects involved.
-(See <xref linkend="introduction"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2006-05-13</entry>
- <entry>
-Moved the User Manual section from chapter 7 to chapter 10.
-(See <xref linkend="user-manual-plans"/>).
-Moved the rest of chapter 7 to appendix.
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2005-05-01</entry>
- <entry>
-Removed old description on how to make releases.
-Added instructions on how to run the installers.
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2006-04-30</entry>
- <entry>
-Change to the explanation on how to use Eclipse.
-(See <xref linkend="eclipse3"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
-
- <tbody valign="top">
- <row>
- <entry>2005-10-29</entry>
- <entry>
-Change to the instructions on how to build ArgoUML to describe
-how it works with the argouml-mdr project.
-(See <xref linkend="buildingandtools"/> and
-<xref linkend="eclipse-checkout"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2005-07-22</entry>
- <entry>
-Removed the /modules/junit.
-(See <xref linkend="release_process"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2005-07-19</entry>
- <entry>
-Change to the descriptions of the Model, Diagrams, and Persistence subsystems
-(See <xref linkend="model"/>,
-<xref linkend="diagrams"/>, and
-<xref linkend="subsystem-persistence"/>).
-
-<note>
- <title>Design decision - Bob Tarling 2005-07-14</title>
- <para>
-The Diagrams subsystem does not store any data.
-All data it works on is stored in the Model subsystem.
-</para>
- </note>
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2005-07-18</entry>
- <entry>
-Change to the short list of subsystems and responsibilities.
-(See <xref linkend="inside_subsystems"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2005-06-18</entry>
- <entry> Restructured: all main chapters are now in seperate files. No
- content changes.
- </entry>
- <entry>Michiel van der Wulp</entry>
- </row>
- </tbody>
-
-
- <tbody valign="top">
- <row>
- <entry>2005-06-15</entry>
- <entry>
-Change to how internationalization is done. Subprojects.
-(See <xref linkend="internationalization"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2005-06-12</entry>
- <entry>
-Change to the description on how to set up an Eclipse environment.
-(See <xref linkend="eclipse-checkout"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
-
- <tbody valign="top">
- <row>
- <entry>2005-06-11</entry>
- <entry>
-Change to how to make an announcement.
-(See <xref linkend="release_process"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2005-05-23</entry>
- <entry>
-Change to release building description.
-(See <xref linkend="release_process"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
-
- <tbody valign="top">
- <row>
- <entry>2005-05-06</entry>
- <entry>
-Added instructions on how we work with sub-projects.
-(See <xref linkend="working-with-subproject"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
-
- <tbody valign="top">
- <row>
- <entry>2005-05-01</entry>
- <entry>
-Change to the tools for releases.
-(See <xref linkend="release_process"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2005-04-29</entry>
- <entry>
-Added a diagram explaining Explorer.
-(See <xref linkend="explorer-implementation-details"/>).
-</entry>
- <entry>Michiel van der Wulp</entry>
- </row>
- </tbody>
-
-
- <tbody valign="top">
- <row>
- <entry>2005-03-10</entry>
- <entry>
-Change to process for verifying issues.
-Any release after the one where the issue is fixed
-can be used for verifications.
-(See <xref linkend="verify_resolved_fixed"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
-
- <tbody valign="top">
- <row>
- <entry>2005-03-06</entry>
- <entry>
-Change to description of how to build.
-<filename>src</filename> directory is now involved.
-(See <xref linkend="buildingandtools"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
-
- <tbody valign="top">
- <row>
- <entry>2005-03-01</entry>
- <entry>
-Removed the modules component.
-(See <xref linkend="issuezilla_release_maintenance"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2005-02-01</entry>
- <entry>
-Change to Model subsystem.
-(See <xref linkend="comp-model-purpose"/>,
-<xref linkend="diagrams"/>).
-Added the Persistence subsystem. More work is needed.
-(See <xref linkend="subsystem-persistence"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2005-01-30</entry>
- <entry>
-Change to the description on how to use the Model subsystem,
-the ModelFacade does not exist anymore.
-(See <xref linkend="working-with-the-model"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2005-01-29</entry>
- <entry>
-Change to Model subsystem chapter.
-Removed references to UmlEventPump and clearified how to remove
-elements using the UmlFactory.
-(See <xref linkend="pump-register-listener-for-type"/>
-and <xref linkend="working-with-the-model"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
-
- <tbody valign="top">
- <row>
- <entry>2005-01-26</entry>
- <entry>
-Change to requirement of JDK version support.
-(See <xref linkend="REQ7"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2005-01-07</entry>
- <entry>
-Added copyright notices to the files.
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
-
- <tbody valign="top">
- <row>
- <entry>2004-12-30</entry>
- <entry>
-Change the default year in the copyright notices.
-Yes, I am a little early.
-(See <xref linkend="standards"/> and <xref linkend="eclipse3"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2004-11-01</entry>
- <entry>
-Change to the way we generate documentation.
-The FILENAME.id files are no longer used.
-(See <xref linkend="generating_documentation"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
-
- <tbody valign="top">
- <row>
- <entry>2004-10-29</entry>
- <entry>
-Change to the description on how to generate documentation.
-Better explanation of how it works.
-(See <xref linkend="generating_documentation"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
-
- <tbody valign="top">
- <row>
- <entry>2004-10-19</entry>
- <entry>
-Change to How to Contribute.
-Changed some spelling errors in cookbook.in while at it.
-(See <xref linkend="contributing"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
-
- <tbody valign="top">
- <row>
- <entry>2004-10-11</entry>
- <entry>
-Changes to description of module loader making the new module loader a fact.
-(See <xref linkend="moduleloader"/> and <xref linkend="modules_and_plugins"/>).
-
-<note>
- <title>Design decision - Linus Tolke 2004-10-11</title>
- <para>
-New imperative Module loader.
-</para>
- </note>
-
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
-
- <tbody valign="top">
- <row>
- <entry>2004-09-17</entry>
- <entry>
-Change to the description on how to extend ArgoUML.
-Now module loader described.
-(See <xref linkend="extending"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
-
- <tbody valign="top">
- <row>
- <entry>2004-09-16</entry>
- <entry>
-Changed the meaning of RESOLVED/LATER.
-(See
-<xref linkend="issuezilla_release_maintenance"/>
-<xref linkend="reopen_remind_and_later"/> and
-<xref linkend="check_for_later"/> in
-<xref linkend="release_process"/>, and
-<xref linkend="issuezilla_resolutions"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2004-09-15</entry>
- <entry>
-Change to design of new module loader.
-(See <xref linkend="design-module-loader"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2004-08-17</entry>
- <entry>
-Deemphasized the layers and instead describe the subsystems in
-groups according to the MVC-pattern.
-(See <xref linkend="subsystems"/> and <xref linkend="inside_subsystems"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2004-08-17</entry>
- <entry>
-Change to the definition of the priorities.
-Now they are defined in terms of how much release blocker they are.
-(See <xref linkend="issue_priorities"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2004-08-02</entry>
- <entry>
-Added rationale for not using RESOLVED/REMIND or RESOLVED/LATER
-(See <xref linkend="issuezilla_resolutions"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- <tbody valign="top">
- <row>
- <entry>2004-07-28</entry>
- <entry>
-Reorganized the description on how to use Eclipse 3.
-Added instructions on how to use the Eclipse JUnit test runner.
-(See <xref linkend="eclipse3"/>).
-</entry>
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
-
- <tbody valign="top">
- <row>
- <!-- When -->
- <entry>2004-07-25</entry>
-
- <!-- What -->
- <entry>
-Added this Change Log.
-(See <xref linkend="changelog"/>).
-<!-- This is a rather stupid reference but it is there more to set the
- level than anything else.
- -->
-</entry>
-
- <!-- Who -->
- <entry>Linus Tolke</entry>
- </row>
- </tbody>
-
- </tgroup>
- </table>
+<preface
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xml:id="changelog"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink">
+
+ <title>Change Log</title>
+
+ <para>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. </para>
+
+ <revhistory>
+ <title>Changes done</title>
+
+ <revision>
+ <date>2007-01-16</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to the definition of the subsystem. Added the responsibility for wellformedness rules. (See <xref xlink:href="#comp-model-purpose" />). (Design decision - Bob Tarling 2007-02-16 - The Model subsystem implements wellformedness rules) </revremark>
+ </revision>
+
+
+ <revision>
+ <date>2007-01-18</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Added instructions on how to configure Subversion. (See <xref xlink:href="#starting" />). </revremark>
+ </revision>
+
+
+ <revision>
+ <date>2007-01-07</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to the process of verifying issues to allow the reporter to more freedom. (See <xref xlink:href="#rolesofworkers" />, <xref xlink:href="#verify_resolved_fixed" />, <xref xlink:href="#verify_resolved_invalid" />, and <xref xlink:href="#close_verified_issue" />). </revremark>
+ </revision>
+
+
+ <revision>
+ <date>2006-12-30</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change how we handle problems in the JRE and other SW not delivered with ArgoUML. (See <xref xlink:href="#issues_dependencies" />). </revremark>
+ </revision>
+
+
+ <revision>
+ <date>2006-10-07</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Removed mentions of CVS. </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2006-10-01</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change the description on how to check out and build with Eclipse to fit the Subversion set up (and Eclipse 3.2). (See <xref xlink:href="#eclipse3" />). </revremark>
+ </revision>
+
+
+ <revision>
+ <date>2006-09-30</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to describe the new release build mechanism based on subversion (See <xref
+ xlink:href="#release_process" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2006-09-12</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Removed the manual tests. Removed the description on how to publish the documentation. Updated the download and build section for Subversion. (See <xref
+ xlink:href="#buildingandtools" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2006-07-14</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Added a section on how to run all JUnit test cases from within Eclipse. (See <xref
+xlink:href="#running-all-junit-from-within-eclipse" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2006-06-24</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Added explanation on different kinds of releases and how we work with them. (See <xref
+ xlink:href="#proc-create-stable-releases" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2006-06-19</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Added a description on how to run JUnit tests from within Eclipse. (See <xref
+ xlink:href="#eclipse-running-junit" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2006-05-28</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Renamed subprojects to dependencies. </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2006-05-14</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> 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 <xref xlink:href="#groundrules" />, and <xref xlink:href="#repository-contents" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2006-05-14</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Moved the Terminology into the Cookbook. (See <xref xlink:href="#terminology"
+ />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2006-05-13</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to the introduction to the ArgoUML project to reflect that there are several Tigris projects involved. (See <xref
+ xlink:href="#introduction" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2006-05-13</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Moved the User Manual section from chapter 7 to chapter 10. (See <xref
+ xlink:href="#user-manual-plans" />). Moved the rest of chapter 7 to appendix. </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2005-05-01</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Removed old description on how to make releases. Added instructions on how to run the installers. </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2006-04-30</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to the explanation on how to use Eclipse. (See <xref xlink:href="#eclipse3" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2005-10-29</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to the instructions on how to build ArgoUML to describe how it works with the argouml-mdr project. (See <xref
+ xlink:href="#buildingandtools" /> and <xref xlink:href="#eclipse-checkout" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2005-07-22</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Removed the /modules/junit. (See <xref xlink:href="#release_process" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2005-07-19</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark>
+ Change to the descriptions of the Model, Diagrams, and Persistence subsystems (See <xref xlink:href="#model" />, <xref xlink:href="#diagrams" />, and <xref xlink:href="#subsystem-persistence" />).
+ <remark>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.</remark>
+ </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2005-07-18</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to the short list of subsystems and responsibilities. (See <xref xlink:href="#inside_subsystems" />). </revremark>
+ </revision>
+
+
+ <revision>
+ <date>2005-06-18</date>
+ <author>
+ <personname>
+ <firstname>Michiel</firstname>
+ <surname>van der Wulp</surname>
+ </personname>
+ </author>
+ <revremark> Restructured: all main chapters are now in seperate files. No content changes. </revremark>
+ </revision>
+
+
+ <revision>
+ <date>2005-06-15</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to how internationalization is done. Subprojects. (See <xref
+ xlink:href="#internationalization" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2005-06-12</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to the description on how to set up an Eclipse environment. (See <xref
+ xlink:href="#eclipse-checkout" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2005-06-11</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to how to make an announcement. (See <xref xlink:href="#release_process"
+ />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2005-05-23</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to release building description. (See <xref xlink:href="#release_process"
+ />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2005-05-06</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Added instructions on how we work with sub-projects. (See <xref
+ xlink:href="#working-with-subproject" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2005-05-01</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to the tools for releases. (See <xref xlink:href="#release_process" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2005-04-29</date>
+ <author>
+ <personname>
+ <firstname>Michiel</firstname>
+ <surname>van der Wulp</surname>
+ </personname>
+ </author>
+ <revremark> Added a diagram explaining Explorer. (See <xref
+ xlink:href="#explorer-implementation-details" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2005-03-10</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to process for verifying issues. Any release after the one where the issue is fixed can be used for verifications. (See <xref
+ xlink:href="#verify_resolved_fixed" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2005-03-06</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark>Change to description of how to build. /src directory is now involved. (See <xref xlink:href="#buildingandtools" />). </revremark>
+ </revision>
+
+
+ <revision>
+ <date>2005-03-01</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Removed the modules component. (See <xref xlink:href="#issuezilla_release_maintenance" />). </revremark>
+ </revision>
+
+
+ <revision>
+ <date>2005-02-01</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to Model subsystem. (See <xref xlink:href="#comp-model-purpose" />, <xref xlink:href="#diagrams" />). Added the Persistence subsystem. More work is needed. (See <xref xlink:href="#subsystem-persistence" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2005-01-30</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to the description on how to use the Model subsystem, the ModelFacade does not exist anymore. (See <xref
+ xlink:href="#working-with-the-model" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2005-01-29</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to Model subsystem chapter. Removed references to UmlEventPump and clearified how to remove elements using the UmlFactory. (See <xref
+ xlink:href="#pump-register-listener-for-type" /> and <xref
+ xlink:href="#working-with-the-model" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2005-01-26</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to requirement of JDK version support. (See <xref xlink:href="#REQ7"
+ />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2005-01-07</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Added copyright notices to the files. </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2004-12-30</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change the default year in the copyright notices. Yes, I am a little early. (See <xref
+ xlink:href="#standards" /> and <xref xlink:href="#eclipse3" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2004-11-01</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to the way we generate documentation. The FILENAME.id files are no longer used. (See <xref
+ xlink:href="#generating_documentation" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2004-10-29</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to the description on how to generate documentation. Better explanation of how it works. (See <xref
+ xlink:href="#generating_documentation" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2004-10-19</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to How to Contribute. Changed some spelling errors in cookbook.in while at it. (See <xref
+ xlink:href="#contributing" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2004-10-11</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark>
+ Changes to description of module loader making the new module loader a fact. (See <xref xlink:href="#moduleloader" /> and <xref xlink:href="#modules_and_plugins" />).
+ <remark>
+ Design decision - Linus Tolke 2004-10-11 - New imperative Module loader.
+ </remark>
+ </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2004-09-17</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to the description on how to extend ArgoUML. Now module loader described. (See <xref xlink:href="#extending" />). </revremark>
+ </revision>
+
+
+ <revision>
+ <date>2004-09-16</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark>Changed the meaning of RESOLVED/LATER. (See <xref xlink:href="#issuezilla_release_maintenance" /> <xref xlink:href="#reopen_remind_and_later" /> and <xref xlink:href="#check_for_later" /> in <xref xlink:href="#release_process" />, and <xref xlink:href="#issuezilla_resolutions" />). </revremark>
+ </revision>
+
+
+ <revision>
+ <date>2004-09-15</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to design of new module loader. (See <xref
+ xlink:href="#design-module-loader" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2004-08-17</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Deemphasized the layers and instead describe the subsystems in groups according to the MVC-pattern. (See <xref
+ xlink:href="#subsystems" /> and <xref xlink:href="#inside_subsystems" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2004-08-17</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Change to the definition of the priorities. Now they are defined in terms of how much release blocker they are. (See <xref
+ xlink:href="#issue_priorities" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2004-08-02</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Added rationale for not using RESOLVED/REMIND or RESOLVED/LATER (See <xref
+ xlink:href="#issuezilla_resolutions" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2004-07-28</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <revremark> Reorganized the description on how to use Eclipse 3. Added instructions on how to use the Eclipse JUnit test runner. (See <xref
+ xlink:href="#eclipse3" />). </revremark>
+
+ </revision>
+
+
+ <revision>
+ <date>2004-07-25</date>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ <!-- This is a rather stupid reference but it is there more to set the level than anything else. -->
+ <revremark> Added this Change Log. (See <xref xlink:href="#changelog" />).</revremark>
+ </revision>
+ </revhistory>
</preface>
-
<!-- Local stuff for Emacs - please do not delete
Local Variables:
@@ -728,4 +740,4 @@
indent-tabs-mode: nil
End:
--->
+-->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/cookbook.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/cookbook.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/cookbook.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/cookbook.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/cookbook.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/cookbook.xml 2008-01-15 19:22:21-0800
@@ -1,164 +1,151 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id$ -->
<!--
-// 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.
+ 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.
-->
-<!DOCTYPE book SYSTEM "../docbook-setup/docbookx/docbookx.dtd" [
-
-<!ENTITY changelog SYSTEM "changelog.xml">
-<!ENTITY introduction SYSTEM "introduction.xml">
-<!ENTITY building SYSTEM "building.xml">
-<!ENTITY requirements SYSTEM "require.xml">
-<!ENTITY subsystems SYSTEM "subsystems.xml">
-<!ENTITY inside_subsystems SYSTEM "inside_subsystems.xml">
-<!ENTITY extending SYSTEM "extending.xml">
-<!ENTITY documentationorganization SYSTEM "documentation_organization.xml">
-<!ENTITY repository SYSTEM "repository.xml">
-<!ENTITY standards SYSTEM "standard.xml">
-<!ENTITY documentationstandards SYSTEM "documentationstandards.xml">
-<!ENTITY further_reading SYSTEM "further_reading.xml">
-<!ENTITY processes SYSTEM "process.xml">
-
-<!ENTITY subsystemmodel SYSTEM "subsystemmodel.xml">
-<!ENTITY subsystemcritics SYSTEM "subsystemcritics.xml">
-<!ENTITY subsystemdiagrams SYSTEM "subsystemdiagrams.xml">
-<!ENTITY subsystempersistence SYSTEM "subsystempersistence.xml">
-<!ENTITY subsystemnotation SYSTEM "subsystemnotation.xml">
-<!ENTITY subsystempropertypanels SYSTEM "subsystempropertypanels.xml">
-<!ENTITY subsysteminternationalization SYSTEM "subsysteminternationalization.xml">
-<!ENTITY subsystemlogging SYSTEM "subsystemlogging.xml">
-
-<!ENTITY cookbookmodules SYSTEM "cookbook_modules.xml">
-<!ENTITY glossary SYSTEM "glossary.xml">
-
-
-
-<!ENTITY ooad "OOA&D">
-<!ENTITY argoversion "@VERSION@">
-<!ENTITY argouml "ArgoUML">
-
-]>
-
-<!-- This is the ArgoUML Developer Cookbook.
- - Please feel free to add to the content and insert your
- name in the Author Group.
- - Images should be located in the general images section of the
- documentation module under the directory cookbook
- - Please verify that your changes compile correctly before committing them
+<!--
+ This is the ArgoUML Developer Cookbook.
+
+ - Please feel free to add to the content and insert your name in the Author Group.
+ - Images should be located in the general images section of the documentation
+ module under the directory cookbook
+ - Please verify that your changes compile correctly before committing them
-->
-
-<book>
- <bookinfo>
- <date>2001-11-10
- </date>
+<book
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink">
+
+ <info>
<title>Cookbook for Developers of ArgoUML</title>
<subtitle>An introduction to Developing ArgoUML</subtitle>
+
+ <date>2001-11-10</date>
+
<abstract>
- <para>
-The purpose of this Cookbook is to help in coordinating and
-documenting the development of ArgoUML.
-</para>
- <para>
-This version of the cookbook is loosely connected to the version
-&argoversion; of ArgoUML.
-</para>
+ <para>The purpose of this Cookbook is to help in coordinating and documenting the development of ArgoUML.</para>
+ <para>This version of the cookbook is loosely connected to the version @VERSION@ of ArgoUML.</para>
</abstract>
+
<authorgroup>
<editor>
- <firstname>Linus</firstname>
- <surname>Tolke</surname>
+ <personname>
+ <firstname>Anthony</firstname>
+ <othername>Tony</othername>
+ <surname>Rogers</surname>
+ </personname>
+ </editor>
+ <editor>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
</editor>
<author>
- <firstname>Markus</firstname>
- <surname>Klink</surname>
+ <personname>
+ <firstname>Markus</firstname>
+ <surname>Klink</surname>
+ </personname>
</author>
<author>
- <firstname>Michiel</firstname>
- <surname>van der Wulp</surname>
+ <personname>
+ <firstname>Michiel</firstname>
+ <surname>van der Wulp</surname>
+ </personname>
</author>
</authorgroup>
+
<legalnotice>
- <para>
-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.
-</para>
+ <para>Copyright © 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. I
N 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.</para>
</legalnotice>
- </bookinfo>
- <toc/>
+ </info>
+
+ <toc />
- &changelog;
+ <!--
+ <!ENTITY changelog SYSTEM "changelog.xml">
+ <!ENTITY introduction SYSTEM "introduction.xml">
+ <!ENTITY building SYSTEM "building.xml">
+ <!ENTITY requirements SYSTEM "require.xml">
+ <!ENTITY subsystems SYSTEM "subsystems.xml">
+ <!ENTITY inside_subsystems SYSTEM "inside_subsystems.xml">
+ <!ENTITY extending SYSTEM "extending.xml">
+ <!ENTITY documentationorganization SYSTEM "documentation_organization.xml">
+ <!ENTITY repository SYSTEM "repository.xml">
+ <!ENTITY standards SYSTEM "standard.xml">
+ <!ENTITY documentationstandards SYSTEM "documentationstandards.xml">
+ <!ENTITY further_reading SYSTEM "further_reading.xml">
+ <!ENTITY processes SYSTEM "process.xml">
+
+ <!ENTITY subsystemmodel SYSTEM "subsystemmodel.xml">
+ <!ENTITY subsystemcritics SYSTEM "subsystemcritics.xml">
+ <!ENTITY subsystemdiagrams SYSTEM "subsystemdiagrams.xml">
+ <!ENTITY subsystempersistence SYSTEM "subsystempersistence.xml">
+ <!ENTITY subsystemnotation SYSTEM "subsystemnotation.xml">
+ <!ENTITY subsystempropertypanels SYSTEM "subsystempropertypanels.xml">
+ <!ENTITY subsysteminternationalization SYSTEM "subsysteminternationalization.xml">
+ <!ENTITY subsystemlogging SYSTEM "subsystemlogging.xml">
+
+ <!ENTITY cookbookmodules SYSTEM "cookbook_modules.xml">
+ <!ENTITY glossary SYSTEM "glossary.xml">
+
+ <!ENTITY ooad "OOA&D">
+ <!ENTITY argoversion "@VERSION@">
+ <!ENTITY argouml "ArgoUML">
+ ]>
+ -->
- &introduction;
- &building;
- &requirements;
- &subsystems;
- &inside_subsystems;
- &extending;
- &standards;
- &documentationstandards;
- &processes;
-
- &glossary;
-
- <index/>
-
- &further_reading;
- &repository;
- &documentationorganization;
+ <xi:include href="changelog.xml" />
+
+ <xi:include href="introduction.xml" />
+ <xi:include href="building.xml" />
+ <xi:include href="requirements.xml" />
+ <xi:include href="subsystems.xml" />
+ <xi:include href="inside_subsystems.xml" />
+ <xi:include href="extending.xml" />
+ <xi:include href="standards.xml" />
+ <xi:include href="documentation_standards.xml" />
+ <xi:include href="process.xml" />
+
+ <xi:include href="glossary.xml" />
+
+ <index />
+
+ <xi:include href="further_reading.xml" />
+ <xi:include href="repository.xml" />
+ <xi:include href="documentation_organization.xml" />
</book>
-
<!-- Local stuff for Emacs - please do not delete
-
-Local Variables:
-mode: xml
-sgml-validate-command: "nsgmls -wxml -sv ../docbook-setup/xml.dcl \
+
+ Local Variables:
+ mode: xml
+ sgml-validate-command: "nsgmls -wxml -sv ../docbook-setup/xml.dcl \
cookbook.xml"
-indent-tabs-mode: nil
-End:
-
+ indent-tabs-mode: nil
+ End:
-->
-
-<!-- LocalWords: ModuleLoader
- -->
+<!-- LocalWords: ModuleLoader -->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/cookbook_modules.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/cookbook_modules.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/cookbook_modules.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/cookbook_modules.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/cookbook_modules.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/cookbook_modules.xml 2008-01-15 19:22:21-0800
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
// Copyright (c) 1996-2007 The Regents of the University of California. All
@@ -25,7 +25,14 @@
// UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
-->
-<sect1 id="modules_and_plugins">
+<section
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xml:id="modules_and_plugins"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ >
<!--
<sect1info>
<authorgroup>
@@ -69,176 +76,71 @@
</sect1info>
-->
<title>Modules </title>
- <para>
-The ArgoUML tool provides a basis
-for UML design and potentially an executable architecture
-environment for more specialized applications.
-This is solved by a clear interfaces between the ArgoUML core
-and the extensions.
-Extensions are called modules.
-</para>
-
- <sect2 id="modules_vs_plugins">
- <title>Modules</title>
-
- <para>
-<itemizedlist>
- <listitem>
- <para>Modules</para>
- <para>
-A module is a collection of classes and resource files that can
-be enabled and disabled in ArgoUML.
-Currently this is decided by the module's availability when ArgoUML starts
-but in the future it could be made possible to enable modules from within
-a running ArgoUML.
-</para>
- <para>
-This module system is the extension capability to the ArgoUML tool.
-It gives developers of ArgoUML and
-developers of applications running within the ArgoUML architecture
-the ability to add
-functionality to the ArgoUML environment
-without modifying the basic ArgoUML tool.
-This flexibility is designed to encourage
-additional open source and/or commercial involvement
-with the open source UML tool.
-</para>
-
- <para>
-The module extensions load when ArgoUML starts.
-When the modules are loaded
-they have the capability of attaching
-to internal ArgoUML architectural elements.
-Once the plugins are attached,
-the plugins will receive calls at the right moment and
-can perform the correct action at that point.
-</para>
-
- <para>
-Modules can be internal and external.
-The only difference is that the internal modules are part of
-the <filename>argouml.jar</filename> and the external are
-delivered as separate jar-files.
-</para>
- </listitem>
-
- </itemizedlist>
-</para>
- <para>
-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 <classname>Pluggable</classname> are the
-AbstractLoadableClass.
-</para>
-
- </sect2>
-
-
- <sect2 id="modules">
- <title>Modules</title>
-
- <sect3>
- <title>Module Architecture</title>
- <para>
-The controlling class for the implementation is
-<classname>org.argouml.moduleloader.ModuleLoader2</classname>.
-It is a singleton created when first used.
-It is first used in the main initialization routine.
-</para>
-
- <para>
-When created it searches through all available modules and creates
-a list of their main objects
-(implementing <classname>ModuleInterface</classname>).
-Currently (September 2004) this also means that the found modules are
-by default selected i.e. they are marked to be enabled.
-</para>
-
- <para>
-At the end of the main initialization routine
-the selected modules are enabled.
-(The original idea was to do this several times during the main routine
-to allow for modules to
-add command line arguments,
-add languages, and
-make functions available for batch command,
-but the example used for testing loaded the ProjectBrowser "too early"
-<!-- See issue ??? -->
-and the result wasn't so good.
-I (Linus) hope this can be eventually fixed.)
-</para>
- </sect3>
-
- <sect3>
- <title>The ModuleInterface interface</title>
- <para>
-Each class used by the <classname>ModuleLoader2</classname>
-must implement the <classname>ModuleInterface</classname> interface.
-</para>
- <para>
-This interface has methods for
-enabling,
-disabling and
-identifying
-the module.
-</para>
- <para>
-When a module is enabled it is expected to register some class
-wherever it affects ArgoUML using the interfaces provided there.
-Since the same interfaces and registration mechanism is used internally
-within ArgoUML there is a small likelyhood that there already is
-an interface and a possibility to register.
-If there isn't, ArgoUML cannot currently be extended
-at that point.
-If you still need ArgoUML to be extended at that point you will have to
-work in getting this interface or registration mechanism implemented within
-ArgoUML.
-(This could also be another module that has to be amended.)
-</para>
-
- <para>
-Classes administered by the module that registers to whatever
-place of ArgoUML they are interested in, does not need to have any
-connection to the module loader.
-They are written exactly as if they would have been if they were
-part of the core ArgoUML.
-</para>
- </sect3>
-
- <sect3 id="using_modules">
- <title>Using Modules</title>
- <para>
-When modules are used they can't be distinguished from the
-rest of the ArgoUML environment.
-</para>
- </sect3>
-
- <sect3 id="howdoi_modules">
- <title>How do I ...?</title>
- <para>
-<itemizedlist>
-
- <listitem>
- <para>...tell when a module is enabled?</para>
- <para>
-The method <methodname>isEnabled</methodname>
-in <classname>ModuleLoader2</classname>
-returns true if the module with that name is enabled and false otherwise.
-</para>
-
- </listitem>
-
- </itemizedlist>
-</para>
+
+ <para>The ArgoUML tool provides a basis for UML design and potentially an executable architecture environment for more specialized applications. This is solved by a clear interfaces between the ArgoUML core and the extensions. Extensions are called modules. </para>
- </sect3>
- </sect2>
+ <section xml:id="modules_vs_plugins">
+ <title>Modules</title>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>Modules</para>
+ <para>A module is a collection of classes and resource files that can be enabled and disabled in ArgoUML. Currently this is decided by the module's availability when ArgoUML starts but in the future it could be made possible to enable modules from within a running ArgoUML. </para>
+ <para>This module system is the extension capability to the ArgoUML tool. It gives developers of ArgoUML and developers of applications running within the ArgoUML architecture the ability to add functionality to the ArgoUML environment without modifying the basic ArgoUML tool. This flexibility is designed to encourage additional open source and/or commercial involvement with the open source UML tool. </para>
+ <para>The module extensions load when ArgoUML starts. When the modules are loaded they have the capability of attaching to internal ArgoUML architectural elements. Once the plugins are attached, the plugins will receive calls at the right moment and can perform the correct action at that point. </para>
+ <para>Modules can be internal and external. The only difference is that the internal modules are part of the <filename>argouml.jar</filename> and the external are delivered as separate jar-files. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>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 <classname>Pluggable</classname> are the AbstractLoadableClass. </para>
+ </section>
+
+
+ <section xml:id="modules">
+ <title>Modules</title>
+
+ <section>
+ <title>Module Architecture</title>
+
+ <para>The controlling class for the implementation is <classname>org.argouml.moduleloader.ModuleLoader2</classname>. It is a singleton created when first used. It is first used in the main initialization routine. </para>
+ <para>When created it searches through all available modules and creates a list of their main objects (implementing <classname>ModuleInterface</classname>). Currently (September 2004) this also means that the found modules are by default selected i.e. they are marked to be enabled. </para>
+ <para>At the end of the main initialization routine the selected modules are enabled. (The original idea was to do this several times during the main routine to allow for modules to add command line arguments, add languages, and make functions available for batch command, but the example used for testing loaded the ProjectBrowser "too early" <!-- See issue ??? --> and the result wasn't so good. I (Linus) hopes this can be eventually fixed.) </para>
+ </section>
+
+ <section>
+ <title>The ModuleInterface interface</title>
+
+ <para>Each class used by the <classname>ModuleLoader2</classname> must implement the <classname>ModuleInterface</classname> interface. </para>
+ <para>This interface has methods for enabling, disabling and identifying the module. </para>
+ <para>When a module is enabled it is expected to register some class wherever it affects ArgoUML using the interfaces provided there. Since the same interfaces and registration mechanism is used internally within ArgoUML there is a small likelyhood that there already is an interface and a possibility to register. If there isn't, ArgoUML cannot currently be extended at that point. If you still need ArgoUML to be extended at that point you will have to work in getting this interface or registration mechanism implemented within ArgoUML. (This could also be another module that has to be amended.) </para>
+ <para>Classes administered by the module that registers to whatever place of ArgoUML they are interested in, does not need to have any connection to the module loader. They are written exactly as if they would have been if they were part of the core ArgoUML. </para>
+ </section>
+
+ <section xml:id="using_modules">
+ <title>Using Modules</title>
+
+ <para>When modules are used they can't be distinguished from the rest of the ArgoUML environment. </para>
+ </section>
+
+ <section xml:id="howdoi_modules">
+ <title>How do I �</title>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>â¦tell when a module is enabled?</para>
+ <para>The method <methodname>isEnabled</methodname> in <classname>ModuleLoader2</classname> returns true if the module with that name is enabled and false otherwise. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ </section>
<!-- This example is obsolete. It needs to be updated to the new architecture
or replaced
- <sect2 id="plugins">
+ <sect2 xml:id="plugins">
<title>Plugins</title>
<note>
<para>
@@ -246,13 +148,13 @@
</para>
</note>
- <sect3 id="architecture_plugins">
+ <sect3 xml:id="architecture_plugins">
<title>Plugin Architecture</title>
<para>
Each class must derive from the <classname>Pluggable</classname> interface.
In addition to the methods declared in <classname>ArgoModule</classname>,
which <classname>Pluggable</classname> extends
-(see <xref linkend="argomodule_interface"/>),
+(see <xref xlink:href="argomodule_interface"/>),
the interface provides the following method:
<itemizedlist>
@@ -283,18 +185,18 @@
</para>
</sect3>
- <sect3 id="howdoi_plugins">
- <title>How do I ...?</title>
+ <sect3 xml:id="howdoi_plugins">
+ <title>How do I �</title>
<para>
<itemizedlist>
- <listitem><para>...create a pluggable settings tab?</para>
- <para>...</para>
+ <listitem><para>â¦create a pluggable settings tab?</para>
+ <para>â¦</para>
</listitem>
- <listitem><para>...create a pluggable menu item?</para>
+ <listitem><para>â¦create a pluggable menu item?</para>
<para>
Look at the modules junit and menutest for examples of how to add to
menus using the PluggableMenu interface.
@@ -325,11 +227,11 @@
</para>
</listitem>
- <listitem><para>...create a pluggable notation?</para>
- <para>...</para>
+ <listitem><para>â¦create a pluggable notation?</para>
+ <para>â¦</para>
</listitem>
- <listitem><para>...create a pluggable diagram?</para>
+ <listitem><para>â¦create a pluggable diagram?</para>
<para>
Let's say we want to enable a Java diagram type as a plug-in.
We use the interface PluggableDiagram that uses a
@@ -400,16 +302,16 @@
</listitem>
<listitem>
<para>
-...do the localization stuff (not plug-in specific, but important)?
+â¦do the localization stuff (not plug-in specific, but important)?
</para>
- <para>...</para>
+ <para>â¦</para>
</listitem>
- <listitem><para>...create a pluggable resource bundle?</para>
- <para>...</para>
+ <listitem><para>â¦create a pluggable resource bundle?</para>
+ <para>â¦</para>
</listitem>
- <listitem><para>...create a new pluggable type?</para>
+ <listitem><para>â¦create a new pluggable type?</para>
<para>
<orderedlist>
<listitem>
@@ -529,23 +431,21 @@
********** end of obsolete example ************************* -->
- <sect2>
- <title>Tip for creating new modules (from Florent de Lamotte)</title>
- <indexterm>
- <primary>Modules</primary>
- <secondary>understanding</secondary>
- </indexterm>
- <note>
- <para>
-This description is for the old moduleloader.
-</para>
- </note>
-
- <para>Florent wrote a small tutorial for creating modules. It can be found on the <ulink url="http://argopno.tigris.org/documentation/argouml.html">ArgoPNO website</ulink>.
-</para>
- </sect2>
-
-</sect1>
+ <section>
+ <title>Tip for creating new modules (from Florent de Lamotte)</title>
+
+ <indexterm>
+ <primary>Modules</primary>
+ <secondary>understanding</secondary>
+ </indexterm>
+
+ <note>
+ <para>This description is for the old moduleloader. </para>
+ </note>
+
+ <para>Florent wrote a small tutorial for creating modules. It can be found on the <uri xlink:href="http://argopno.tigris.org/documentation/argouml.html" >ArgoPNO website</uri>. </para>
+ </section>
+</section>
<!-- Local stuff for Emacs - please do not delete
@@ -556,4 +456,4 @@
indent-tabs-mode: nil
End:
--->
+-->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/documentation_organization.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/documentation_organization.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/documentation_organization.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/documentation_organization.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/documentation_organization.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/documentation_organization.xml 2008-01-15 19:22:21-0800
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
// Copyright (c) 1996-2007 The Regents of the University of California. All
@@ -25,400 +25,270 @@
// UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
-->
-<appendix id="documentation_what_goes_where">
- <appendixinfo>
- <abstract>
- <para>
-This chapter describes what goes into which
-part of the documentation. These ideas are formulated by Linus Tolke.
-</para>
- </abstract>
- <authorgroup>
- <author>
- <firstname>Linus</firstname>
- <surname>Tolke</surname>
- </author>
- </authorgroup>
- </appendixinfo>
- <title>Organization of ArgoUML documentation</title>
- <para>
-There are eight (8) significantly different bits of documentation in the
-ArgoUML project.
-By documentation I mean some information of the product that is
-developed alongside the product and that has a persistent value.
-</para>
- <orderedlist>
- <listitem>
- <para>The web sites</para>
- </listitem>
- <listitem>
- <para>The manual and quick-guide</para>
- </listitem>
- <listitem>
- <para>Help texts within the running ArgoUML</para>
- </listitem>
- <listitem>
- <para>The FAQ</para>
- </listitem>
- <listitem>
- <para>The cookbook</para>
- </listitem>
- <listitem>
- <para>The javadoc of API and SPI of a subsystem</para>
- </listitem>
- <listitem>
- <para>The code, variable names, class names</para>
- </listitem>
- <listitem>
- <para>The javadoc</para>
- </listitem>
- </orderedlist>
- <para>
-These different bits have all different purpose and audience and
-the purpose of this chapter is to try to define that.
-</para>
- <table>
- <title>Bits of documentation</title>
- <tgroup cols="3">
- <colspec colnum="1" colname="Bit" colwidth="1*"/>
- <colspec colnum="2" colname="Main Purpose" colwidth="3*"/>
- <colspec colnum="3" colname="Contains" colwidth="3*"/>
- <thead>
- <row>
- <entry>Bit</entry>
- <entry>Main purpose</entry>
- <entry>Contains</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <!-- Bit -->
- <entry>Web site(s)</entry>
-
- <!-- Purpose -->
- <entry>
-Is
-<itemizedlist>
- <listitem>
- <para>
-an entry point for the other parts of the documentation.
-</para>
- </listitem>
- <listitem>
- <para>
-the main download area for the ArgoUML product.
-</para>
- </listitem>
- <listitem>
- <para>
-the central point of the ArgoUML user community.
-</para>
- </listitem>
- <listitem>
- <para>
-the central point of the ArgoUML development project.
-</para>
- </listitem>
- </itemizedlist>
-
-This is for everyone, i.e.
-<itemizedlist>
- <listitem>
- <para>
-developers in the project,
-</para>
- </listitem>
- <listitem>
- <para>
-users of the product, and
-</para>
- </listitem>
- <listitem>
- <para>
-people searching for UML tools for the purpose of trying, testing,
-evaluating, and using the tools.
-</para>
- </listitem>
- </itemizedlist>
-
-</entry>
-
- <!-- Contains -->
- <entry>
-References to all the other parts of the documentation.
-Current project information like the contents of the upcoming releases
-and the plan for the nearest future.
-Easy access illustration for new users.
-Some illustrations that do not fit in other parts.
-This is done as a complement to the other parts.
-Examples, tours.
-</entry>
- </row>
-
- <row>
- <!-- Bit -->
- <entry>Manual and quick-guide</entry>
-
- <!-- Purpose -->
- <entry>
-<para>
-Describe how ArgoUML is installed and used.
-Describe how UML is used with ArgoUML.
-</para>
-
-<para>
-This is for
-<itemizedlist>
- <listitem>
- <para>
-Users of ArgoUML.
-</para>
- </listitem>
- <listitem>
- <para>
-Persons that want to evaluate ArgoUML for the purpose of starting to use it.
-</para>
- </listitem>
- <listitem>
- <para>
-Persons that are training to use UML and ArgoUML.
-</para>
- </listitem>
- </itemizedlist>
-</para>
-</entry>
-
- <!-- Contains -->
- <entry>
-<itemizedlist>
- <listitem>
- <para>
-Complete installation instructions for all supported installation schemes.
-</para>
- </listitem>
- <listitem>
- <para>
-Complete description on how to use ArgoUML in your project.
-</para>
- </listitem>
- <listitem>
- <para>
-Complete reference on how to use ArgoUML.
-</para>
- </listitem>
- </itemizedlist>
-</entry>
- </row>
-
- <row>
- <!-- Bit -->
- <entry>Help text in ArgoUML</entry>
-
- <!-- Purpose -->
- <entry>
-<para>Give a quick help with a specific feature or button.
-Give short explanations of all commands and actions.
-</para>
-
-<para>
-This is for the Users of ArgoUML.
-</para>
-</entry>
-
- <!-- Contains -->
- <entry>
-A complete set of quick help and explanations.
-</entry>
- </row>
-
- <row>
- <!-- Bit -->
- <entry>FAQ</entry>
-
- <!-- Purpose -->
- <entry>
-<para>
-Cope for shortcomings in ArgoUML, the help text,
-the Manual and quick-guide and the web site.
-</para>
-
-<para>
-This is for
-the Users of ArgoUML and
-the Members of the users mailing list.
-</para>
-</entry>
-
- <!-- Contains -->
- <entry>
-A list of issues that are not addressed in the other part of the documentation.
-It is written in questions-answers-format and the contents is governed by
-the issues discussed recently in the user community.
-</entry>
- </row>
-
- <row>
- <!-- Bit -->
- <entry>Cookbook</entry>
-
- <!-- Purpose -->
- <entry>
-<itemizedlist>
- <listitem>
- <para>
-Make it possible to learn how ArgoUML works and how to extend it.
-</para>
- </listitem>
- <listitem>
- <para>
-Lower the threshold for new developers.
-</para>
- </listitem>
- <listitem>
- <para>
-Reduce the amount of knowledge of
-complex design and
-reasons for certain design decisions,
-that are documented only in the heads of the developers.
-</para>
- </listitem>
- <listitem>
- <para>
-Reduce the amount of simple questions on the developers' mailing list.
-</para>
- </listitem>
- </itemizedlist>
-
-This is for
-developers writing code, maintaining the documentation or the web site.
-</entry>
-
- <!-- Contains -->
- <entry>
-<itemizedlist>
- <listitem>
- <para>
-Instructions on how to add new functions and behavior.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Instructions on how to build and publish a release.
-The purpose of this is to control the generation of each release.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Project policies like what level of quality is aimed for and
-description of processes that achieves that level.
-</para>
- </listitem>
-
- <listitem>
- <para>
-The documentation of the development environment and how to set it up.
-</para>
- </listitem>
-
- <listitem>
- <para>
-The design, where it is so complex or involves so many classes and methods
-that it is meaningless to store it in the javadoc of the involved classes
-and methods.
-</para>
- <para>
-The Cookbook contains one section for each subsystem
-where the internal design of that subsystem is kept.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Design decisions as a
-collection of knowledge around how and why the project makes
-certain decisions.
-</para>
- </listitem>
- </itemizedlist>
-</entry>
- </row>
-
- <row>
- <!-- Bit -->
- <entry>Javadoc of API and SPI of a subsystem</entry>
-
- <!-- Purpose -->
- <entry>
-<para>
-Explain how to use the subsystem.
-</para>
-
-<para>
-This is for developers that work with other parts of ArgoUML
-that interacts with the subsystem in question.
-</para>
-</entry>
-
- <!-- Contains -->
- <entry>
-Description of the function of all public classes,
-all public and protected methods, variables, and constants.
-</entry>
- </row>
-
- <row>
- <!-- Bit -->
- <entry>Javadoc of non API- and SPI-parts</entry>
-
- <!-- Purpose -->
- <entry>
-<para>
-Document the code to understand it later.
-</para>
-
-<para>
-Developers writing code in the same subsystem.
-</para>
-</entry>
-
- <!-- Contains -->
- <entry>
-Together with other comments and variable names,
-this is the description of the functions of all
-classes,
-operations,
-methods,
-variables, and
-constants.
-</entry>
- </row>
-
- <row>
- <!-- Bit -->
- <entry>Source Code</entry>
-
- <!-- Purpose -->
- <entry>
-Implement ArgoUML in a maintainable and understandable way.
-</entry>
-
- <!-- Contains -->
- <entry>
-See <xref linkend="standards"/> for details on how to write the code.
-</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
- <para>
-The Cookbook, the User Manual, and the Quick Guide,
-are all written in docbook and generated into HTML and PDF
-during deployment.
-See <xref linkend="app.docstand"/> for details on how to write these.
-</para>
+<appendix
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xml:id="documentation_what_goes_where">
+
+ <title>Organization of ArgoUML documentation</title>
+
+ <info>
+ <abstract>
+ <para>This chapter describes what goes into which part of the documentation. These ideas are formulated by Linus Tolke. </para>
+ </abstract>
+ <authorgroup>
+ <author>
+ <personname><firstname>Linus</firstname>
+ <surname>Tolke</surname></personname>
+ </author>
+ </authorgroup>
+ </info>
+
+ <para>There are eight (8) significantly different bits of documentation in the ArgoUML project. By documentation I mean some information of the product that is developed alongside the product and that has a persistent value. </para>
+
+ <orderedlist>
+ <listitem>
+ <para>The web sites</para>
+ </listitem>
+ <listitem>
+ <para>The manual and quick-guide</para>
+ </listitem>
+ <listitem>
+ <para>Help texts within the running ArgoUML</para>
+ </listitem>
+ <listitem>
+ <para>The FAQ</para>
+ </listitem>
+ <listitem>
+ <para>The cookbook</para>
+ </listitem>
+ <listitem>
+ <para>The javadoc of API and SPI of a subsystem</para>
+ </listitem>
+ <listitem>
+ <para>The code, variable names, class names</para>
+ </listitem>
+ <listitem>
+ <para>The javadoc</para>
+ </listitem>
+ </orderedlist>
+
+ <para>These different bits have all different purpose and audience and the purpose of this chapter is to try to define that. </para>
+
+ <table>
+ <title>Bits of documentation</title>
+
+ <tgroup cols="3">
+ <colspec colnum="1" colname="Bit" colwidth="1*" />
+ <colspec colnum="2" colname="Main Purpose" colwidth="3*" />
+ <colspec colnum="3" colname="Contains" colwidth="3*" />
+
+ <thead>
+ <row>
+ <entry>Bit</entry>
+ <entry>Main purpose</entry>
+ <entry>Contains</entry>
+ </row>
+ </thead>
+
+ <tbody valign="top">
+ <row>
+ <!-- Bit -->
+ <entry>Web site(s)</entry>
+
+ <!-- Purpose -->
+ <entry>
+ <para>Is</para>
+ <itemizedlist>
+ <listitem>
+ <para>an entry point for the other parts of the documentation. </para>
+ </listitem>
+ <listitem>
+ <para>the main download area for the ArgoUML product. </para>
+ </listitem>
+ <listitem>
+ <para>the central point of the ArgoUML user community. </para>
+ </listitem>
+ <listitem>
+ <para>the central point of the ArgoUML development project. </para>
+ </listitem>
+ <listitem>
+
+ <para>This is for everyone, i.e.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>developers in the project, </para>
+ </listitem>
+ <listitem>
+ <para>users of the product, and </para>
+ </listitem>
+ <listitem>
+ <para>people searching for UML tools for the purpose of trying, testing, evaluating, and using the tools. </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </entry>
+
+ <!-- Contains -->
+ <entry> References to all the other parts of the documentation. Current project information like the contents of the upcoming releases and the plan for the nearest future. Easy access illustration for new users. Some illustrations that do not fit in other parts. This is done as a complement to the other parts. Examples, tours. </entry>
+ </row>
+
+ <row>
+ <!-- Bit -->
+ <entry>Manual and quick-guide</entry>
+
+ <!-- Purpose -->
+ <entry>
+ <para>Describe how ArgoUML is installed and used. Describe how UML is used with ArgoUML. </para>
+ <para>This is for
+ <itemizedlist>
+ <listitem>
+ <para>Users of ArgoUML. </para>
+ </listitem>
+ <listitem>
+ <para>Persons that want to evaluate ArgoUML for the purpose of starting to use it. </para>
+ </listitem>
+ <listitem>
+ <para>Persons that are training to use UML and ArgoUML. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </entry>
+
+ <!-- Contains -->
+ <entry>
+ <itemizedlist>
+ <listitem>
+ <para>Complete installation instructions for all supported installation schemes. </para>
+ </listitem>
+ <listitem>
+ <para>Complete description on how to use ArgoUML in your project. </para>
+ </listitem>
+ <listitem>
+ <para>Complete reference on how to use ArgoUML. </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+
+ <row>
+ <!-- Bit -->
+ <entry>Help text in ArgoUML</entry>
+ <!-- Purpose -->
+ <entry>
+ <para>Give a quick help with a specific feature or button. Give short explanations of all commands and actions. </para>
+ <para>This is for the Users of ArgoUML. </para>
+ </entry>
+ <!-- Contains -->
+ <entry> A complete set of quick help and explanations. </entry>
+ </row>
+
+ <row>
+ <!-- Bit -->
+ <entry>FAQ</entry>
+ <!-- Purpose -->
+ <entry>
+ <para>Cope for shortcomings in ArgoUML, the help text, the Manual and quick-guide and the web site. </para>
+ <para>This is for the Users of ArgoUML and the Members of the users mailing list. </para>
+ </entry>
+ <!-- Contains -->
+ <entry> A list of issues that are not addressed in the other part of the documentation. It is written in questions-answers-format and the contents is governed by the issues discussed recently in the user community. </entry>
+ </row>
+
+ <row>
+ <!-- Bit -->
+ <entry>Cookbook</entry>
+ <!-- Purpose -->
+ <entry>
+
+ <itemizedlist>
+ <listitem>
+ <para>Make it possible to learn how ArgoUML works and how to extend it. </para>
+ </listitem>
+ <listitem>
+ <para>Lower the threshold for new developers. </para>
+ </listitem>
+ <listitem>
+ <para>Reduce the amount of knowledge of complex design and reasons for certain design decisions, that are documented only in the heads of the developers. </para>
+ </listitem>
+ <listitem>
+ <para>Reduce the amount of simple questions on the developers' mailing list. </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>This is for developers writing code, maintaining the documentation or the web site.</para>
+ </entry>
+
+ <!-- Contains -->
+ <entry>
+ <itemizedlist>
+ <listitem>
+ <para>Instructions on how to add new functions and behavior. </para>
+ </listitem>
+ <listitem>
+ <para>Instructions on how to build and publish a release. The purpose of this is to control the generation of each release. </para>
+ </listitem>
+ <listitem>
+ <para>Project policies like what level of quality is aimed for and description of processes that achieves that level. </para>
+ </listitem>
+ <listitem>
+ <para>The documentation of the development environment and how to set it up. </para>
+ </listitem>
+ <listitem>
+ <para>The design, where it is so complex or involves so many classes and methods that it is meaningless to store it in the javadoc of the involved classes and methods. </para>
+ <para>The Cookbook contains one section for each subsystem where the internal design of that subsystem is kept. </para>
+ </listitem>
+ <listitem>
+ <para>Design decisions as a collection of knowledge around how and why the project makes certain decisions. </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+
+ <row>
+ <!-- Bit -->
+ <entry>Javadoc of API and SPI of a subsystem</entry>
+ <!-- Purpose -->
+ <entry>
+ <para>Explain how to use the subsystem. </para>
+ <para>This is for developers that work with other parts of ArgoUML that interacts with the subsystem in question. </para>
+ </entry>
+ <!-- Contains -->
+ <entry> Description of the function of all public classes, all public and protected methods, variables, and constants. </entry>
+ </row>
+
+ <row>
+ <!-- Bit -->
+ <entry>Javadoc of non API- and SPI-parts</entry>
+ <!-- Purpose -->
+ <entry>
+ <para>Document the code to understand it later. </para>
+ <para>Developers writing code in the same subsystem. </para>
+ </entry>
+ <!-- Contains -->
+ <entry> Together with other comments and variable names, this is the description of the functions of all classes, operations, methods, variables, and constants. </entry>
+ </row>
+
+ <row>
+ <!-- Bit -->
+ <entry>Source Code</entry>
+ <!-- Purpose -->
+ <entry> Implement ArgoUML in a maintainable and understandable way. </entry>
+ <!-- Contains -->
+ <entry> See <xref xlink:href="standards"
+ /> for details on how to write the code. </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>The Cookbook, the User Manual, and the Quick Guide, are all written in docbook and generated into HTML and PDF during deployment. See <xref xlink:href="app.docstand" /> for details on how to write these. </para>
</appendix>
<!-- Local stuff for Emacs - please do not delete
@@ -432,4 +302,4 @@
indent-tabs-mode: nil
End:
--->
+-->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/documentationstandards.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/documentationstandards.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/documentationstandards.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/documentationstandards.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/documentationstandards.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/documentationstandards.xml 2008-01-15 19:22:21-0800
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
// Copyright (c) 1996-2006 The Regents of the University of California. All
@@ -24,926 +24,558 @@
// CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT,
// UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
-->
+<!DOCTYPE chapter [<!ENTITY dbcentx SYSTEM "../docbook-setup/docbookx/dbcentx.mod">]>
+<chapter
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xml:id="app.docstand"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink">
+
+ <title>Writing Documentation in the ArgoUML Project</title>
+
+ <section>
+ <title>Introduction</title>
+
+ <para>The documentation (currently manual, cookbook, and quickguide) is written using <uri xlink:href="http://www.oasis-open.org/docbook">DocBook XML v5.0</uri>. This section covers some conventions for use of DocBook and for the documentation in general. It also includes some information for tooling configuration, e.g. for Emacs with the psgml package. </para>
+ </section>
+
+ <!-- Conventions for the document in general -->
+ <section>
+ <title>Style</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>"We" in the documents means the persons reading the document. For the Quick-guide and User Manual this means the user using ArgoUML. For the Cookbook this means the developer working with improving ArgoUML.</para>
+ </listitem>
+ <listitem>
+ <para>"I" in the document refers to the author and is only used to denote the authors personal opinion. Avoid using it! </para>
+ </listitem>
+ <listitem>
+ <para>Use the active voice.</para>
+ </listitem>
+ <listitem>
+ <para>Use plain rather than elegant language.</para>
+ </listitem>
+ <listitem>
+ <para>Use specific and concrete terms rather than vague generalities. </para>
+ </listitem>
+ <listitem>
+ <para>Break up your writing in short sections. Each section dealing with one topic. </para>
+ </listitem>
+ <listitem>
+ <para>Use the present tense.</para>
+ </listitem>
+ <listitem>
+ <para>Opt for an informal rather than a formal style.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+
+ <section>
+ <title>Document Conventions</title>
+
+ <itemizedlist>
+ <listitem>
+ <!--
+ I question the following convention.
+
+ Capitalization is better left for CSS and XSL to impose.
+ It is trivial to do so, as well.
+
+ Also, it's really easy using CSS or XSL to set text to
+ UPPERCASE, lowercase, or Capitalized Case, but not so easy
+ to do something like
+
+ Capitalization of Important Words but not Unimportant Words.
+
+ So personally I think it's preferable to use the above
+ capitazliation scheme; e.g. of most (but not all) words
+ in the DocBook source, and then let stylesheets transform
+ the source automagically as needed.
+
+ ~ Tony / "Zearin"
+ 2007-11-28
+ -->
+ <para>All titles of chapters, sections etc. are capitalized throughout. </para>
+ </listitem>
+
+ <listitem>
+ <para>All titles of figures, tables etc. have the first word only capitalized. </para>
+ </listitem>
+
+ <listitem>
+ <para>Spelling is US English. (According to The Webster's Second Unabridged.) </para>
+ </listitem>
+
+ <listitem>
+ <para>Use full URLs throughout all documents! Rationale: These documents may also be published in other formats than html on the ArgoUML web site. </para>
+ </listitem>
+
+ <listitem>
+ <para>Do not include lists of what changes have been done to the files. This information is kept by the version control tool. This is changed since Jeremy Bennet did the work for the 0.9/0.10 User Manual and there might still exist such lists. Remove them while changing the files! </para>
+ <para>The Cookbook has a Change Log (See <xref xlink:href="changelog.xml" />) that is updated for every significant change but that is for the purpose of making it easier for the readers. </para>
+ </listitem>
+
+ <listitem>
+ <para>When problems in the current implementation of ArgoUML are mentioned or perhaps even emphasized using the <tag>warning</tag> tag, include the issue number in a sgml-comment in the source so that it is easy to know if this problem has been fixed when revising the document. The issue should be mentioned in the format <quote>issue xxx</quote>, i.e. there should only be a space between the word <quote>issue</quote> and the issue number. This allows the tigris web site to generate links when viewing the manual source. </para>
+ </listitem>
+
+ <listitem>
+ <para>Do not write "currently". Better write either "in version 0.14" if you mean in the stable version 0.14 of ArgoUML or "in version &argoversion;" if you mean in the current version of the document as defined in <filename>default.properties</filename> when the document is deployed. There are some old references to "current" or "currently" also. If you encounter them, try to remove them! </para>
+ </listitem>
+
+ <listitem>
+ <para>For documents that contain an <quote>index</quote>, Add indexterms while doing changes. Creating the index is a good idea and we eventually should have indexterms all over. Initially, the manual was written without useing indexterms at all. They have been added generously on certain parts but that makes the index strangely biased. </para>
+ <para>Capitalize the part of the indexterms that are terms. </para>
+ <para>Don't use the tertiary level of the index terms but use only two alternatives: Only primary, and primary/secondary. If you are unsure when to use primary or primary/secondary use the small word approach. I.e. if the indexterm contains a small word (typically to, of, for, in) and normally not capitalized, let the secondary start with that small word. </para>
+ <para>When using primary/secondary, see that you get the same kind of word as used before in the index (especially when it comes to differences in singular/plural-form). Also create other indexterm by turning the phrase to as many permutations that you can think of. </para>
+ </listitem>
+
+ </itemizedlist>
+ </section>
+
+ <!-- Conventions relating to DocBook -->
+
+ <section>
+ <title>DocBook Conventions</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>The top level document of the document is in <filename>documentname.xml</filename>. Each chapter (or preface, glossary, appendix etc) of the cookbook and the quickguide is a separate file, defined as a system entity and included from this top level file. The manual is one big file: <filename>manual.xml</filename> </para>
+ </listitem>
+
+ <listitem>
+ <para>There may be some useful entities defined for common terms in the beginning of this top level document. </para>
+ <para>E.g. for the cookbook: The use of <tag>&argouml;</tag> will ensure consistent naming of the product (ArgoUML) and allow us to change it later (to Argo/UML, Argouml or whatever). </para>
+ <para>In the build script there is some magic that translates @tagname@ to a real value. E.g. @VERSION@ in the <filename>documentname.xml</filename> file into <replaceable>0.16</replaceable>. </para>
+ </listitem>
+
+ <listitem>
+ <para>XML comments are used throughout to explain what various sections are trying to achieve. </para>
+ </listitem>
+
+ <listitem>
+ <para>Cross-referencing requires use of <literal>id.</literal> attributes. Many of these used in the manual are of the following format, but the use of this format is not obligatory any more. </para>
+ <para>To avoid confusion, use a prefix of <literal>ch.</literal> for <tag>chapter</tag>, <literal>app.</literal> for <tag>appendix</tag>, <literal>s.</literal> for <tag>sect1</tag> through <tag>sect5</tag>, <literal>fig.</literal> for <tag>figure</tag>, <literal>tab.</literal> for <tag>table</tag> and <literal>gl</literal> for <tag>glossentry</tag>. </para>
+ <para>A second prefix of <literal>tut.</literal> or <literal>ref.</literal> is allowed to distinguish tutorial and reference material. The remainder of the tag should be descriptive, but concise with words separate by underscore. Where a graphic is involved this remainder should correspond to the file name. For example <literal>fig.ref.navigation_pane</literal> for a figure showing the explorer, with the diagram in <literal>navigation_pane.gif</literal></para>
+ <para>There is one exception to this and that is the description of the critics in the manual. Each paragraph about a critic is instead marked with <literal>critics.</literal> followed by the classname implementing that critic. The reason for this is that the intention is to have the manual accessable when pressing the Help button on that critic. Generating a link to the correct place in the manual is easier if the classname need not undergo some kind of textual transformation and the implementation doesn't care if a a specific critic is described in a <tag>sect1</tag>, <tag>sect2</tag>, <tag>sect3</tag>, or <tag>sect4</tag>. Reorganizing the manual would otherwise affect also the java code. The conversion to the correct tagname or really the correct URL is currently implemented in th
e <literal>defaultMoreInfoURL()</literal> method in the <literal>org.argouml.cognitive.critics.Critic</literal> class. </para>
+ </listitem>
+
+ <listitem>
+ <para>Only use <tag>glossterm</tag> (for the term <emphasis>or</emphasis> its abbreviation/acronym), <tag>glossdef</tag> and <tag>glossseealso</tag> within <tag>glossentry</tag>. Other entries are not implemented in the style sheets and so do not appear in the glossary! </para>
+ </listitem>
+
+ <listitem>
+ <para>Use spaces rather than tabs. Tabs are generally set so large the text moves over to the right of the page, and are not set the same everywhere (emacs uses 8 spaces, some MS editors use 6 spaces), making documents unreadable between users. </para>
+ </listitem>
+
+ <!--
+ listitem>
+ <para>This does not apply to the manual any more (it now uses standard formatting as supported by most xml editors): Indent only the tags, not the text. The Docbook source is kept in subversion that is a line-oriented tool. This means that reindentation will be a major thing in subversion making it hard to see if there were other things done to the code. Especially if reindentation caused the paragraphs to be broken in a different way. Not indenting the text means that the text will be unchanged even if the heading level was changed. The contributions that Jeremy Bennet did for the 0.10 User Manual are not indented like this. Change it while changing the paragraphs. </para>
+ </listitem
+ -->
+
+ <listitem>
+ <para>The indentation size is 2. </para>
+ </listitem>
+
+ <listitem>
+ <para>Make a new line after each sentence or before expressions. The Docbook source is source that is handled by subversion. When structuring the text the parts are paragraphs, sentences and words. By having each sentence on a line of its own it is easier to see which sentences have been changed and which have not in the <literal>diff</literal> reports from subversion. The contributions that Jeremy Bennet did for the 0.10 User Manual are not written like this. Change it while changing the paragraphs. </para>
+ </listitem>
+
+ <listitem>
+ <para>All block graphics should be encapsulated within <tag>figure</tag>, allowing reference from around the text. Set attribute <tag>float</tag> to 1 to allow the figure to float (makes life easier for printed version). </para>
+ </listitem>
+
+ <listitem>
+ <para>All block graphics should be provided through <tag>mediaobject</tag> and provided with both an <tag>imageobject</tag> and comprehensive description in a <tag>textobject</tag>. This gives the potential of meaningful content where a diagram cannot be displayed for any reason. Where appropriate the <tag>mediaobject</tag> should be wrapped by <tag>screenshot</tag>. </para>
+ </listitem>
+
+ <listitem>
+ <para>Inline graphics can be done through <tag>inlinegraphic</tag>, rather <tag>inlinemediaobject</tag>. A textual alternative is of little value in these circumstances. Where appropriate the <tag>mediaobject</tag> should be wrapped by <tag>guiicon</tag>
+ </para>
+ </listitem>
-<!--
+ <!--listitem><para>In general use <sgmltag>literal</sgmltag> for computer
+ related text (input and output). There are a huge number of possible
+ specialist tags, but I suggest restriction to the following list:
+ <sgmltag>filename</sgmltag> and <sgmltag>application</sgmltag>.
+ </para></listitem-->
+ </itemizedlist>
+ </section>
-Standards for writing documentation (manual, cookbook, quickguide).
+ <!-- Conventions relating to use of eclipse -->
--->
+ <section>
+ <title>For Eclipse Users</title>
-<chapter id="app.docstand">
- <title>Writing Documentation in the ArgoUML Project</title>
+ <para>If you use the Eclipse, then the XML editor that comes with the Eclipse <emphasis>Tools Platform (WTP)</emphasis> project allows comfortable editing. </para>
+ <para>Regretfully, the docbook-validation of this editor (as any other suitable editor that has been evaluated) currently does not support the way the cookbook and quickguide are divided in seperate XML files. The manual consists of one single XML file, so it does not have this problem. </para>
+ </section>
- <sect1>
- <title>Introduction</title>
+ <!-- Conventions relating to use of emacs -->
- <para>
-The documentation
- (currently manual, cookbook, and quickguide)
- is written using
- <ulink url="http://www.oasis-open.org/docbook"><application>DocBook
- XML V4.1.2</application></ulink>. This section covers some
- conventions for use of DocBook and for the documentation in general. It
-also includes some information
-for tooling configuration, e.g.
-for Emacs with the psgml package.
-</para>
- </sect1>
-
- <!-- Conventions for the document in general -->
-
- <sect1>
- <title>Style</title>
-
- <itemizedlist>
- <listitem>
- <para>
-"We" in the documents means the persons reading the document.
-For the Quick-guide and User Manual this means the user using &argouml;.
-For the Cookbook this means the developer working with improving &argouml;.
-</para>
- </listitem>
-
- <listitem>
- <para>
-"I" in the document refers to the author and is only used to denote
-the authors personal opinion.
-Avoid using it!
-</para>
- </listitem>
-
- <listitem>
- <para>Use the active voice.</para>
- </listitem>
-
- <listitem>
- <para>Use plain rather than elegant language.</para>
- </listitem>
-
- <listitem>
- <para>
-Use specific and concrete terms rather than vague generalities.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Break up your writing into short sections,
-each section dealing with a single topic.
-</para>
- </listitem>
-
- <listitem>
- <para>Use the present tense.</para>
- </listitem>
-
- <listitem>
- <para>Opt for an informal rather than a formal style.</para>
- </listitem>
-
-
- </itemizedlist>
- </sect1>
-
-
- <sect1>
- <title>Document Conventions</title>
-
- <itemizedlist>
- <listitem>
- <para>
-All titles of chapters, sections etc. are capitalized throughout.
-</para>
- </listitem>
-
- <listitem>
- <para>
-All titles of figures, tables etc. have the first word only capitalized.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Spelling is US English.
-(According to The Webster's Second Unabridged.)
-</para>
- </listitem>
-
- <listitem>
- <para>
-Use full URLs throughout all documents!
-Rationale:
-These documents may also be published in other formats than
-html on the &argouml; web site.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Do not include lists of what changes have been done to the files.
-This information is kept by the version control tool.
-This is changed since Jeremy Bennet did the work for
-the 0.9/0.10 User Manual and there might still exist such lists.
-Remove them while changing the files!
-</para>
- <para>
-The Cookbook has a Change Log
-(See <xref linkend="changelog"/>)
-that is updated for every significant
-change but that is for the purpose of making it easier for the readers.
-</para>
- </listitem>
-
- <listitem>
- <para>
-When problems in the current implementation of &argouml; are mentioned
-or perhaps even emphasized using the
-<sgmltag>warning</sgmltag> tag,
-include the issue number in a sgml-comment in the source
-so that it is easy to know if this problem has been fixed
-when revising the document.
-The issue should be mentioned in the format <quote>issue xxx</quote>, i.e.
-there should only be a space between
-the word <quote>issue</quote>
-and the issue number.
-This allows the tigris web site to
-generate links when viewing
-the manual source.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Do not write "currently". Better write either
-"in version 0.14" if you mean in the stable version 0.14 of ArgoUML or "in
-version &argoversion;" if you mean in the current version of the document
-as defined in <filename>default.properties</filename> when
-the document is deployed.
-There
-are some old references to "current" or "currently" also. If you encounter
-them, try to remove them!
-</para>
- </listitem>
-
- <listitem>
- <para>
-For documents that contain an <quote>index</quote>,
-Add indexterms while doing changes.
-Creating the index is a good idea
-and we eventually should have indexterms all over.
-Initially, the manual was written without
-useing indexterms at all.
-They have been added
-generously on certain parts but that makes the index
-strangely biased.
-</para>
-
- <para>
-Capitalize the part of the indexterms that are terms.
-</para>
-
- <para>
-Don't use the tertiary level of the index terms but
-use only two alternatives:
-Only primary, and primary/secondary.
-If you are unsure when to use primary or primary/secondary use
-the small word approach.
-I.e. if the indexterm contains a small word (typically to, of, for, in)
-and normally not capitalized, let the secondary start with that
-small word.
-</para>
-
- <para>
-When using primary/secondary, see that you get the same kind of
-word as used before in the index (especially when it comes to
-differences in singular/plural-form).
-Also create other indexterm by turning the phrase to as many
-permutations that you can think of.
-</para>
- </listitem>
-
- </itemizedlist>
- </sect1>
-
- <!-- Conventions relating to DocBook -->
-
- <sect1>
- <title>DocBook Conventions</title>
-
- <itemizedlist>
- <listitem>
- <para>
-The top level document
-of the document
-is in <filename>documentname.xml</filename>.
-Each chapter (or
- preface, glossary, appendix etc)
- of the cookbook and the quickguide
- is a separate file, defined as a
- system entity and included from this top level
- file.
- The manual is one big file: <filename>manual.xml</filename>
-</para>
- </listitem>
-
- <listitem><para>There may be some useful entities defined
- for common terms
- in the beginning of
-this top level document.
-</para>
- <para>
- E.g. for the cookbook:
- The use of
- <sgmltag>&argouml;</sgmltag> will ensure consistent naming of the
-product (ArgoUML) and allow us to change it later (to Argo/UML,
- Argouml or whatever).
-</para>
- <para>
-In the build script there is some magic that
-translates @tagname@ to a real value.
-E.g. @VERSION@ in the <filename>documentname.xml</filename> file
-into <replaceable>0.16</replaceable>.
-</para>
- </listitem>
-
- <listitem>
- <para>
-XML comments are used throughout to explain what various
-sections are trying to achieve.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Cross-referencing requires use of <literal>id.</literal>
- attributes.
- Many of these used in the manual are of the following format, but the
- use of this format is not obligatory any more.
-</para>
-
- <para>
- To avoid confusion, use
- a prefix of <literal>ch.</literal>
- for <sgmltag>chapter</sgmltag>, <literal>app.</literal> for
- <sgmltag>appendix</sgmltag>, <literal>s.</literal>
- for <sgmltag>sect1</sgmltag> through
- <sgmltag>sect5</sgmltag>, <literal>fig.</literal> for
- <sgmltag>figure</sgmltag>, <literal>tab.</literal> for
- <sgmltag>table</sgmltag> and <literal>gl</literal> for
- <sgmltag>glossentry</sgmltag>.
-</para>
-
- <para>A second prefix of <literal>tut.</literal> or
- <literal>ref.</literal> is allowed
- to distinguish tutorial and reference
- material. The remainder of the tag should be descriptive, but concise
- with words separated by underscores. Where a graphic is involved this
- remainder should correspond to the file name. For example
- <literal>fig.ref.navigation_pane</literal> for a figure showing the
- explorer, with the diagram in
- <literal>navigation_pane.gif</literal>
-</para>
-
- <para>
-There is one exception to this and that is the
-description of the critics in the manual.
-Each paragraph about a critic is instead marked with
-<literal>critics.</literal> followed by the classname
-implementing that critic.
-The reason for this is that the intention is to have the manual
-accessable when pressing the Help button on that critic.
-Generating a link to the correct place in the manual is easier
-if the classname need not undergo some kind of textual
-transformation and the implementation doesn't
-care if a a specific critic is described in a
-<sgmltag>sect1</sgmltag>,
-<sgmltag>sect2</sgmltag>,
-<sgmltag>sect3</sgmltag>, or
-<sgmltag>sect4</sgmltag>.
-Reorganizing the manual would otherwise affect also the
-java code.
-The conversion to the correct tagname or really the correct URL
-is currently implemented in the
-<literal>defaultMoreInfoURL()</literal>
-method in the
-<literal>org.argouml.cognitive.critics.Critic</literal>
-class.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Only use <sgmltag>glossterm</sgmltag> (for the term
- <emphasis>or</emphasis> its abbreviation/acronym),
- <sgmltag>glossdef</sgmltag> and <sgmltag>glossseealso</sgmltag>
- within <sgmltag>glossentry</sgmltag>. Other entries are not
- implemented in the style sheets and so do not appear in the
- glossary!
-</para>
- </listitem>
-
- <listitem>
- <para>
-Use spaces rather than tabs.
-Tabs are generally set so large the text moves over to the right of the page,
-and are not set the same everywhere (emacs uses 8 spaces, some MS
-editors use 6 spaces), making documents unreadable between users.
-</para>
- </listitem>
-
- <!--listitem>
- <para>
- This does not apply to the manual any more
- (it now uses standard formatting as supported by most xml editors):
-Indent only the tags, not the text.
-The Docbook source is kept in subversion that is a line-oriented tool.
-This means that reindentation will be a major thing in subversion making
-it hard to see if there were other things done to the code.
-Especially if reindentation caused the paragraphs to be broken
-in a different way.
-Not indenting the text means that the text will be unchanged even
-if the heading level was changed.
-The contributions that Jeremy Bennet did for the 0.10 User Manual
-are not indented like this.
-Change it while changing the paragraphs.
-</para>
- </listitem-->
-
- <listitem>
- <para>
-The indentation size is 2.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Make a new line after each sentence or before expressions.
-The Docbook source is source that is handled by subversion.
-When structuring the text the parts are paragraphs, sentences and words.
-By having each sentence on a line of its own it is easier to see
-which sentences have been changed and which have not in the <literal>diff</literal>
-reports from subversion.
-The contributions that Jeremy Bennet did for the 0.10 User Manual
-are not written like this.
-Change it while changing the paragraphs.
-</para>
- </listitem>
-
- <listitem>
- <para>
-All block graphics should be encapsulated within
- <sgmltag>figure</sgmltag>, allowing reference from around the
- text. Set attribute <sgmltag>float</sgmltag> to 1 to allow the figure
- to float (makes life easier for printed version).
-</para>
- </listitem>
-
- <listitem>
- <para>
-All block graphics should be provided through
- <sgmltag>mediaobject</sgmltag> and provided with both an
- <sgmltag>imageobject</sgmltag> and comprehensive description in a
- <sgmltag>textobject</sgmltag>. This gives the potential of meaningful
- content where a diagram cannot be displayed for any
- reason. Where appropriate the <sgmltag>mediaobject</sgmltag> should be
- wrapped by <sgmltag>screenshot</sgmltag>.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Inline graphics can be done through
- <sgmltag>inlinegraphic</sgmltag>, rather
- <sgmltag>inlinemediaobject</sgmltag>. A textual alternative is of
- little value in these circumstances. Where appropriate the
- <sgmltag>mediaobject</sgmltag> should be wrapped by
- <sgmltag>guiicon</sgmltag>
-</para>
- </listitem>
+ <section>
+ <title>For Emacs Users</title>
- <!--listitem><para>In general use <sgmltag>literal</sgmltag> for computer
- related text (input and output). There are a huge number of possible
- specialist tags, but I suggest restriction to the following list:
- <sgmltag>filename</sgmltag> and <sgmltag>application</sgmltag>.
- </para></listitem-->
- </itemizedlist>
- </sect1>
+ <para>If you use the psgml library within emacs, then editing and verifying XML gets easier. Information on using this facility is inluded with psgml. </para>
- <!-- Conventions relating to use of eclipse -->
+ <itemizedlist>
+ <listitem>
+ <para>Emacs' local variables appear in a few lines of comment at the bottom of each XML file. Please don't delete these! </para>
+ </listitem>
- <sect1>
- <title>For Eclipse Users</title>
+ <listitem>
+ <para>Adding <literal>(setq sgml-set-face t)</literal> to your <filename>.emacs</filename> file will cause all tags and entities to appear in boldface. </para>
+ </listitem>
- <para>If you use Eclipse, then the XML editor that comes
- with the Eclipse <emphasis>Tools Platform (WTP)</emphasis>
- project allows comfortable editing.
- </para>
-
- <para>Regretfully, the docbook-validation of this editor
- (as any other suitable editor that has been evaluated)
- currently does not support the way the cookbook
- and quickguide are divided into
- seperate XML files.
- The manual
- consists of one single XML file,
- so it does not have this problem.
- </para>
-
- </sect1>
-
- <!-- Conventions relating to use of emacs -->
-
- <sect1>
- <title>For Emacs Users</title>
-
- <para>If you use the psgml library within emacs, then editing and
- verifying XML gets easier. Information on using this facility is
- inluded with psgml.
-</para>
-
- <itemizedlist>
- <listitem>
- <para>
-Emacs' local variables appear in a few lines of
-comment at the bottom of each XML file.
-Please don't delete these!
-</para>
- </listitem>
-
- <listitem>
- <para>
-Adding
- <literal>(setq sgml-set-face t)</literal> to your
- <filename>.emacs</filename> file will cause all tags and entities to
- appear in boldface.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Adding
- <literal>(setq sgml-auto-activate-dtd t)</literal> to your
- <filename>.emacs</filename> file will ensure the DocBook DTD is
- parsed as soon as the file is loaded.
-</para>
- </listitem>
- </itemizedlist>
- </sect1>
-
- <!-- An overview of how the manual should be written -->
- <sect1 id="user-manual-plans">
- <title>User Manual Plans</title>
- <!-- Target audiences -->
-
- <para>
-The User Manual is a very separate part of the ArgoUML project.
-It is independent of the rest of the project w.r.t. updates,
-deliveries, ambition and plans.
-The development of the User Manual is more or less a project of its own.
-Since autumn 2003 we also have an appointed sub project leader for this.
-This Responsibility is called Editor for the User Manual and Quick Guide
-and is held by Michiel van der Wulp.
-</para>
- <para>
-This section describes the ambition and plans for the User Manual.
-</para>
-
- <sect2>
- <title>Target Audiences for the User Manual</title>
-
- <para>Target audiences are the following:</para>
-
- <itemizedlist>
- <listitem>
- <para>Experienced users of UML in &ooad;
-(perhaps with other tools) who wish to transfer to &argouml;.
-</para>
- </listitem>
-
- <listitem>
- <para>Designers who know &ooad;, and wish to adopt a UML
-based process.
-</para>
- </listitem>
- </itemizedlist>
-
- <para>
-In the longer term it would be desirable to also target the following.
-</para>
-
- <itemizedlist>
- <listitem>
- <para>Those who are learning design and
-wish to start with a UML based &ooad; process.
-</para>
- </listitem>
-
- <listitem>
- <para>
-People interested in modularized code design with a GUI.
-</para>
- </listitem>
- </itemizedlist>
- </sect2>
-
- <!-- Goals -->
-
- <sect2>
- <title>Goals for the User Manual</title>
-
- <para>The goals are (in priority order):</para>
-
- <orderedlist>
- <listitem>
- <para>
-A tutorial style explanation of &argouml;
-in the context of an &ooad; process.
-</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Descriptive</emphasis> reference material
-on all components of ArgoUML
-</para>
- </listitem>
-
- <listitem>
- <para>
-Keep boundaries clearly defined, to avoid
-duplication with the Cookbook, FAQ, Quick Guide, on-line help etc.
-</para>
- </listitem>
-
- </orderedlist>
-
- <para>
-I (probably Jeremy Bennet in 2002?) think the existing User Manual
-is a good start particularly towards
-the second of these goals.
-</para>
-
- <!-- Non-Goals -->
-
- <sect3>
- <title>What the User Manual is not (currently)</title>
-
- <para>
-To keep the effort feasible the user manual should avoid the
-following (at least initially).
-</para>
-
- <itemizedlist>
- <listitem>
- <para>
-Providing a quick overview—the Quick Guide
-already does this.
-</para>
- </listitem>
-
- <listitem>
- <para>Listing all the errors and what they mean.
-The help system does this—one day the manual will link to
-that.
-</para>
- </listitem>
-
- <listitem>
- <para>Explaining the internal workings of ArgoUML.
-The cookbook, combined with Jason Robbins dissertation is already a good
-start for this.
-</para>
- </listitem>
- </itemizedlist>
- </sect3>
- </sect2>
-
- <!-- Structure -->
-
- <sect2>
- <title>Suggested Manual Structure</title>
-
- <para>
-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)
-</para>
-
- <para>
-I (Jeremy Bennet, 2002?) suggest that the tutorial book be based
-around an &ooad; 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 <emphasis>simple</emphasis> case study will be needed
-throughout.
-</para>
-
- <sect3>
- <title>Tutorial Manual Structure</title>
-
- <orderedlist>
-
- <!-- Introduction puts everything into context -->
-
- <listitem>
- <para>Introduction</para>
- <orderedlist>
-
- <listitem>
- <para>Origins and overview of &argouml;</para>
- </listitem>
-
- <listitem>
- <para>Scope of the User Manual.
-Include cross-reference to other documentation
-(Cookbook,
-FAQ,
-Quick Guide,
-on-line help,
-&argouml; website
-etc).
-</para>
- </listitem>
-
- <listitem>
- <para>Overview of the User Manual.
-Explains that &argouml;
-will be explained in the context of an &ooad; process, and
-with an example running through.
-</para>
- </listitem>
-
- <listitem>
- <para>Assumptions.
-At this stage assume the user knows &ooad;, but not UML.
-</para>
- </listitem>
-
- </orderedlist>
- </listitem>
-
- <!-- Need to explain how we're going to go about learning &argouml; -->
-
- <listitem>
- <para>UML Based &ooad;</para>
- <orderedlist>
-
- <listitem>
- <para>Background to UML —
-what it is,
-history etc.
-</para>
- </listitem>
-
- <listitem>
- <para>UML based processes for &ooad;</para>
- </listitem>
-
- <listitem>
- <para>ArgoUML Basics —
-projects,
-drawing,
-exploring,
-details
-</para>
- </listitem>
-
- <listitem>
- <para>What &argouml; has that other tools are missing
-(critics,
-to-do list,
-based on cognitive psychology theory).
-</para>
- </listitem>
-
- <listitem>
- <para>The Case Study</para>
- </listitem>
-
- </orderedlist>
- </listitem>
-
- <!-- Diagrams associated with requirements capture.
- This will include a lot of &argouml; stuff,
- since you hit this at the first diagram.-->
-
- <listitem>
- <para>Requirements Capture</para>
- <orderedlist>
-
- <listitem>
- <para>Use Case Diagrams
-(this section will be relatively large,
-because its the first time we use ArgoUML to create something).
-</para>
- </listitem>
-
- </orderedlist>
- </listitem>
-
- <!-- Diagrams for analysis. What goes where is a bit dependent on the
- specific process. -->
-
- <listitem>
- <para>Analysis</para>
- <orderedlist>
-
- <listitem>
- <para>Concept Class Diagrams</para>
- </listitem>
-
- <listitem>
- <para>System Sequence Charts and Collaboration Diagrams</para>
- </listitem>
-
- <listitem>
- <para>System State-chart Diagrams</para>
- </listitem>
-
- </orderedlist>
- </listitem>
-
- <!-- Design -->
-
- <listitem>
- <para>Design</para>
- <orderedlist>
-
- <listitem>
- <para>Class Diagrams for Realization</para>
- </listitem>
-
- <listitem>
- <para>Sequence Charts and
-Collaboration Diagrams for Realization
-</para>
- </listitem>
-
- <listitem>
- <para>State-chart Diagrams for realization</para>
- </listitem>
-
- <listitem>
- <para>Package Diagrams</para>
- </listitem>
-
- </orderedlist>
- </listitem>
-
- <!-- Build -->
-
- <listitem>
- <para>Build</para>
-
- <orderedlist>
-
- <listitem>
- <para>Deployment Diagrams</para>
- </listitem>
-
- <listitem>
- <para>Code Generation in &argouml;</para>
- </listitem>
-
- </orderedlist>
- </listitem>
- </orderedlist>
- </sect3>
-
- <!-- What needs to be in the Reference Manual -->
-
- <sect3>
- <title>Reference Manual Structure</title>
-
- <orderedlist>
- <listitem>
- <para>
-Material on each of the
-diagram types, each of the artifacts that can appear on the diagrams
-and details of the features of each artifact type.
-</para>
- </listitem>
-
- <listitem>
- <para>An Index</para>
- </listitem>
- </orderedlist>
- </sect3>
- </sect2>
-
- <!-- What we need to do to get to a final manual -->
-
- <sect2>
- <title>Actions, Priorities and Questions</title>
-
- <para>
-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.
-</para>
-
- <sect3>
- <title>Actions and priorities</title>
-
- <para>
-Here's my first call for what needs to be done in priority order.
-From the comments made over the last few days I think the first
-5 items won't take very long, meaning effort can concentrate on the
-main stuff.
-</para>
-
- <orderedlist>
- <listitem>
- <para>Get buy-in for the approach. (Completed)</para>
- </listitem>
-
- <listitem>
- <para>Agree document structure (broadly). (Completed)</para>
- </listitem>
-
- <listitem>
- <para>Choose a suitable example to run throughout.</para>
- </listitem>
-
- <listitem>
- <para>Break into several files (XML entities) to make the
-manual more manageable. (Completed and then joined again.)
-</para>
- </listitem>
-
- <listitem>
- <para>Identify all existing sources of material to be reused</para>
- </listitem>
-
- <listitem>
- <para>Get writing!
-I (Jeremy Bennet 2002?) suggest the priorities here are:
-</para>
-
- <orderedlist>
- <listitem>
- <para>
-User Manual sections relating to &argouml; diagrams
-and artifacts (assume the reader knows UML already, and allows a
-quick advance by pulling together a lot of existing
-material).
-</para>
- </listitem>
-
- <listitem>
- <para>User Manual examples</para>
- </listitem>
-
- <listitem>
- <para>User Manual sections
-relating to additional &argouml; cognitive design features.
-</para>
- </listitem>
-
- <listitem>
- <para>User Manual sections relating to UML
-(for readers who don't know UML).
-</para>
- </listitem>
-
- <listitem>
- <para>Completion of Reference Manual material.</para>
- </listitem>
- </orderedlist>
- </listitem>
-
- <listitem>
- <para>Create an index. (Completed)</para>
- </listitem>
- </orderedlist>
- </sect3>
-
- <!-- What questions still need answering -->
-
- <sect3>
- <title>Remaining Questions</title>
-
- <orderedlist>
- <listitem>
- <para>
-The current manual shows copyright held by Phillipe, and no legal notice.
-What is the position of this material? (Solved)
-</para>
- </listitem>
- </orderedlist>
- </sect3>
- </sect2>
- </sect1>
-</chapter>
+ <listitem>
+ <para>Adding <literal>(setq sgml-auto-activate-dtd t)</literal> to your <filename>.emacs</filename> file will ensure the DocBook DTD is parsed as soon as the file is loaded. </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <!--
+ An overview of how the manual should be written
+ -->
+ <section xml:id="user-manual-plans">
+ <title>User Manual Plans</title>
+ <!-- Target audiences -->
+
+ <para>The User Manual is a very separate part of the ArgoUML project. It is independent of the rest of the project w.r.t. updates, deliveries, ambition and plans. The development of the User Manual is more or less a project of its own. Since autumn 2003 we also have an appointed sub project leader for this. This Responsibility is called Editor for the User Manual and Quick Guide and is held by Michiel van der Wulp. </para>
+ <para>This section describes the ambition and plans for the User Manual. </para>
+
+ <section>
+ <title>Target Audiences for the User Manual</title>
+
+ <para>Target audiences are the following:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Experienced users of UML in Object-Oriented Analysis and Design (perhaps with other tools) who wish to transfer to ArgoUML. </para>
+ </listitem>
+
+ <listitem>
+ <para>Designers who know Object-Oriented Analysis and Design, and wish to adopt a UML based process. </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In the longer term it would be desirable to also target the following. </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Those who are learning design and wish to start with a UML based Object-Oriented Analysis and Design process. </para>
+ </listitem>
+
+ <listitem>
+ <para>People interested in modularized code design with a GUI. </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <!--
+ Goals
+ -->
+ <section>
+ <title>Goals for the User Manual</title>
+
+ <para>The goals are (in priority order):</para>
+
+ <orderedlist>
+ <listitem>
+ <para>A tutorial style explanation of ArgoUML in the context of an Object-Oriented Analysis and Design process. </para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Descriptive</emphasis> reference material on all components of ArgoUML </para>
+ </listitem>
+
+ <listitem>
+ <para>Keep boundaries clearly defined, to avoid duplication with the Cookbook, FAQ, Quick Guide, on-line help etc. </para>
+ </listitem>
+
+ </orderedlist>
+
+ <para>I (probably Jeremy Bennet in 2002?) think the existing User Manual is a good start particularly towards the second of these goals. </para>
+
+ <!-- Non-Goals -->
+
+ <section>
+ <title>What the User Manual is not (currently)</title>
+
+ <para>To keep the effort feasible the user manual should avoid the following (at least initially). </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Providing a quick overview—the Quick Guide already does this. </para>
+ </listitem>
+
+ <listitem>
+ <para>Listing all the errors and what they mean. The help system does this—one day the manual will link to that. </para>
+ </listitem>
+
+ <listitem>
+ <para>Explaining the internal workings of ArgoUML. The cookbook, combined with Jason Robbins dissertation is already a good start for this. </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+
+ <!-- Structure -->
+
+ <section>
+ <title>Suggested Manual Structure</title>
+
+ <para>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) </para>
+
+ <para>I (Jeremy Bennet, 2002?) suggest that the tutorial book be based around an Object-Oriented Analysis and Design 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 <emphasis>simple</emphasis>case study will be needed throughout. </para>
+
+ <section>
+ <title>Tutorial Manual Structure</title>
+
+ <orderedlist>
+
+ <!-- Introduction puts everything into context -->
+
+ <listitem>
+ <para>Introduction</para>
+ <orderedlist>
+
+ <listitem>
+ <para>Origins and overview of ArgoUML</para>
+ </listitem>
+
+ <listitem>
+ <para>Scope of the User Manual. Include cross-reference to other documentation (Cookbook, FAQ, Quick Guide, on-line help, ArgoUML website etc). </para>
+ </listitem>
+
+ <listitem>
+ <para>Overview of the User Manual. Explains that ArgoUML will be explained in the context of an Object-Oriented Analysis and Design process, and with an example running through. </para>
+ </listitem>
+
+ <listitem>
+ <para>Assumptions. At this stage assume the user knows Object-Oriented Analysis and Design, but not UML. </para>
+ </listitem>
+
+ </orderedlist>
+ </listitem>
+
+ <!--
+ Need to explain how we're going to go about learning &argouml;
+ -->
+
+ <listitem>
+ <para>UML Based Object-Oriented Analysis and Design</para>
+ <orderedlist>
+
+ <listitem>
+ <para>Background to UML — what it is, history etc. </para>
+ </listitem>
+
+ <listitem>
+ <para>UML based processes for Object-Oriented Analysis and Design</para>
+ </listitem>
+
+ <listitem>
+ <para>ArgoUML Basics — projects, drawing, exploring, details </para>
+ </listitem>
+
+ <listitem>
+ <para>What ArgoUML has that other tools are missing (critics, to-do list, based in cognitive psychology theory). </para>
+ </listitem>
+
+ <listitem>
+ <para>The Case Study</para>
+ </listitem>
+
+ </orderedlist>
+ </listitem>
+
+ <!--
+ Diagrams associated with requirements capture.
+ This will include a lot of &argouml; stuff,
+ since you hit this at the first diagram.
+ -->
+
+ <listitem>
+ <para>Requirements Capture</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Use Case Diagrams (this section will be relatively large, because its the first time we use ArgoUML to create something). </para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+
+ <!--
+ Diagrams for analysis. What goes where is a bit
+ dependent on the specific process.
+ -->
+
+ <listitem>
+ <para>Analysis</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Concept Class Diagrams</para>
+ </listitem>
+
+ <listitem>
+ <para>System Sequence Charts and Collaboration Diagrams</para>
+ </listitem>
+
+ <listitem>
+ <para>System State-chart Diagrams</para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+
+ <!--
+ Design
+ -->
+
+ <listitem>
+ <para>Design</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Class Diagrams for Realization</para>
+ </listitem>
+
+ <listitem>
+ <para>Sequence Charts and Collaboration Diagrams for Realization </para>
+ </listitem>
+
+ <listitem>
+ <para>State-chart Diagrams for realization</para>
+ </listitem>
+
+ <listitem>
+ <para>Package Diagrams</para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+
+ <!-- Build -->
+
+ <listitem>
+ <para>Build</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Deployment Diagrams</para>
+ </listitem>
+
+ <listitem>
+ <para>Code Generation in ArgoUML</para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <!--
+ What needs to be in the Reference Manual
+ -->
+
+ <section>
+ <title>Reference Manual Structure</title>
+
+ <orderedlist>
+ <listitem>
+ <para>Material on each of the diagram types, each of the artifacts that can appear on the diagrams and details of the features of each artifact type. </para>
+ </listitem>
+
+ <listitem>
+ <para>An Index</para>
+ </listitem>
+ </orderedlist>
+ </section>
+ </section>
+
+ <!-- What we need to do to get to a final manual -->
+
+ <section>
+ <title>Actions, Priorities and Questions</title>
+
+ <para>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. </para>
+
+ <section>
+ <title>Actions and priorities</title>
+
+ <para>Here's my first call for what needs to be done in priority order. From the comments made over the last few days I think the first 5 items won't take very long, meaning effort can concentrate on the main stuff. </para>
+
+ <orderedlist>
+ <listitem>
+ <para>Get buy-in for the approach. (Completed)</para>
+ </listitem>
+
+ <listitem>
+ <para>Agree document structure (broadly). (Completed)</para>
+ </listitem>
+
+ <listitem>
+ <para>Choose a suitable example to run throughout.</para>
+ </listitem>
+
+ <listitem>
+ <para>Break into several files (XML entities) to make the manual more manageable. (Completed and then joined again.) </para>
+ </listitem>
+
+ <listitem>
+ <para>Identify all existing sources of material to be reused</para>
+ </listitem>
+
+ <listitem>
+ <para>Get writing! I (Jeremy Bennet 2002?) suggest the priorities here are: </para>
+
+ <orderedlist>
+ <listitem>
+ <para>User Manual sections relating to ArgoUML diagrams and artifacts (assume the reader knows UML already, and allows a quick advance by pulling together a lot of existing material). </para>
+ </listitem>
+
+ <listitem>
+ <para>User Manual examples</para>
+ </listitem>
+
+ <listitem>
+ <para>User Manual sections relating to additional ArgoUML cognitive design features. </para>
+ </listitem>
+
+ <listitem>
+ <para>User Manual sections relating to UML (for readers who don't know UML). </para>
+ </listitem>
+
+ <listitem>
+ <para>Completion of Reference Manual material.</para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+
+ <listitem>
+ <para>Create an index. (Completed)</para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <!-- What questions still need answering -->
+
+ <section>
+ <title>Remaining Questions</title>
+
+ <orderedlist>
+ <listitem>
+ <para>The current manual shows copyright held by Phillipe, and no legal notice. What is the position of this material? (Solved) </para>
+ </listitem>
+ </orderedlist>
+ </section>
+ </section>
+ </section>
+</chapter>
<!-- Local stuff for Emacs - please do not delete
Local Variables:
@@ -955,4 +587,4 @@
indent-tabs-mode: nil
End:
--->
+-->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/extending.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/extending.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/extending.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/extending.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/extending.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/extending.xml 2008-01-15 19:22:21-0800
@@ -1,208 +1,150 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
-// Copyright (c) 1996-2006 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.
+ // Copyright (c) 1996-2006 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.
-->
-<chapter id="extending">
+<chapter
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xml:id="extending"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+
<title>Extending ArgoUML</title>
- <para> This section explains some general concepts which come in handy, when
- developing additions to ArgoUML. </para>
+ <para>This section explains some general concepts which come in handy, when developing additions to ArgoUML. </para>
- <sect1 id="howdoi_general">
- <title>How do I ...?</title>
+ <section xml:id="howdoi_general">
+ <title>How do I �</title>
+
<para>
<itemizedlist>
<listitem>
- <para> ...get the corresponding UML element for a given
- <classname>Fig<replaceable>XXX</replaceable></classname>
- object? </para>
- <para> Each <classname>Fig<replaceable>XXX</replaceable>
- </classname> implements the method
- <methodname>getOwner()</methodname> which returns the
- appropriate owner element which is responsible for this Fig
- element. </para>
+ <para>â¦get the corresponding UML element for a given <classname>Fig<replaceable>XXX</replaceable></classname> object? </para>
+ <para>Each <classname>Fig<replaceable>XXX</replaceable>
+ </classname> implements the method <methodname>getOwner()</methodname> which returns the appropriate owner element which is responsible for this Fig element. </para>
</listitem>
<listitem>
- <para> ...get the corresponding Fig element for a given
- <classname>ModelElement</classname>? </para>
- <para> for this one needs to iterate through all Fig objects and invoke
- <methodname>getOwner</methodname>. Compare the result with the
- given <classname>ModelElement</classname>. Be aware that there
- might be more than one Fig object for a given
- <classname>ModelElement</classname> if it appears in multiple
- diagrams or there may be none if it has no diagrams. </para>
+ <para>â¦get the corresponding Fig element for a given <classname>ModelElement</classname>? </para>
+ <para>for this one needs to iterate through all Fig objects and invoke <methodname>getOwner</methodname>. Compare the result with the given <classname>ModelElement</classname>. Be aware that there might be more than one Fig object for a given <classname>ModelElement</classname> if it appears in multiple diagrams or there may be none if it has no diagrams. </para>
</listitem>
- </itemizedlist> </para>
- </sect1>
+ </itemizedlist>
+ </para>
+ </section>
- &cookbookmodules;
+ <xi:include href="cookbook_modules.xml" />
- <sect1>
- <title>How are modules organized in the Java code?</title>
- <para>
- The previous section describes how modules and plug-ins are
- organized at the Java level independent of how they are actually
- packaged.
- </para>
- <para> Within the ArgoUML project some parts of the code are developed
- and packaged separately from the main ArgoUML source code.
- This section describes how they are
- organized and how you create such source-code modules. </para>
+ <section>
+ <title>How are modules organized in the Java code</title>
+
+ <para>The previous section describes how modules and plug-ins are organized at the Java level independent of how they are actually packaged. </para>
+ <para>Within the ArgoUML project some parts of the code are developed and packaged separately from the main ArgoUML source code. This section describes how they are organized and how you create such source-code modules. </para>
- <sect2>
+ <section>
<title>Requirements on modules</title>
-
- <para>
-An external module requires:
-<orderedlist>
+
+ <para>An external module requires:
+ <orderedlist>
<listitem>
- <para>
-The module main class implements org.argouml.moduleloader.ModuleInterface
-</para>
+ <para>The module main class implements <interfacename>org.argouml.moduleloader.ModuleInterface</interfacename></para>
</listitem>
-
+
<listitem>
- <para>
-Archive the main class into a jar, with an entry "Name" in MANIFEST.MF
-specifying the name of the main class. For example, Name:
-<programlisting>
-Name: your/own/domain/your/package/your.class
-</programlisting>
-The class in question must implement
-<classname>org.argouml.moduleloader.ModuleInterface</classname>.
-</para>
+ <para>Archive the main class into a jar, with an entry "Name" in MANIFEST.MF specifying the name of the main class. For example, Name: <programlisting> Name: your/own/domain/your/package/your.class </programlisting> The class in question must implement <classname>org.argouml.moduleloader.ModuleInterface</classname>. </para>
</listitem>
-
+
<listitem>
- <para>
-Put the jar file into a directory called "ext" under the home directory of
-ArgoUML
-</para>
+ <para>Put the jar file into a directory called <filename class="directory">ext</filename> under the home directory of ArgoUML</para>
</listitem>
-
+
<listitem>
- <para>
-Run ArgoUML and check if the module appears in Edit -> Settings -> Modules
-</para>
+ <para>Run ArgoUML and check if the module appears in EditâSettingsâModules</para>
</listitem>
</orderedlist>
-</para>
-
+ </para>
-
- <para> New modules that are added to ArgoUML shall reside in whole new
- packages. Either you put your module classes in
- <classname><replaceable>your.own.domain</replaceable>
- .<replaceable>your.package.name</replaceable></classname> or if
- you want to emphasize the connection to ArgoUML you can use
- <classname>org.argouml.<replaceable>your.package.name</replaceable>
- </classname> where <replaceable>your.package.name</replaceable>
- is the name of your addition. </para>
- </sect2>
+
+
+ <para>New modules that are added to ArgoUML shall reside in whole new packages. Either you put your module classes in <replaceable>your.own.domain</replaceable>.<package><replaceable>your.package.name</replaceable></package> or if you want to emphasize the connection to ArgoUML you can use org.argouml.<package><replaceable>your.package.name</replaceable></package> where <package><replaceable>your.package.name</replaceable></package> is the name of your addition.</para>
+ </section>
- <sect2 id="howdoi_source_code_modules">
- <title>How do I ...?</title>
+ <section xml:id="howdoi_source_code_modules">
+ <title>How do I �</title>
+
<para>
<itemizedlist>
<listitem>
- <para> ...create a new source-code module. </para>
- <para> Suggestion, copy from the <filename class="directory">
- menutest</filename> module as described here. </para>
- <para> Make a copy of <filename class="directory">
- argouml/modules/menutest</filename> into <filename
- class="directory">argouml/modules/<replaceable>your
- name</replaceable></filename>. </para>
- <para> Add any jar you need to <filename class="directory">
- argouml/modules/<replaceable>your name</replaceable>
- /lib</filename> and add references to each of the jars in
- <filename>argouml/modules/<replaceable>your
- name</replaceable>/build.xml</filename>. </para>
- <para> Edit <filename class="directory">
- argouml/modules/<replaceable>your name</replaceable>
- /module.properties</filename>
- </para>
- <para> Edit <filename>argouml/modules/<replaceable>your
- name</replaceable>/src/org/manifest.mf</filename>.
- </para>
- <para> Reorganize the source files as necessary. Remove the
- directory <filename class="directory">
- argouml/modules/<replaceable>your name</replaceable>
- /src/org/argouml/ui</filename> and create your own classes
- like org.argouml.<replaceable>your package
- name</replaceable> in <filename class="directory">
- argouml/modules/<replaceable>your name</replaceable>
- /src/org/argouml/<replaceable>your package
- name</replaceable></filename>. </para>
- </listitem>
- <listitem>
- <para> ...get Argo to use a plug-in? </para> <note>
- <para> This description is for the old module loader. </para>
+ <para>â¦create a new source-code module? </para>
+ <para>Suggestion, copy from the <filename class="directory" > menutest</filename> module as described here. </para>
+ <para>Make a copy of <filename class="directory" >argouml/modules/menutest</filename> into <filename class="directory" >argouml/modules/<replaceable>your name</replaceable></filename>. </para>
+ <para>Add any jar you need to <filename class="directory" > argouml/modules/<replaceable>your name</replaceable> /lib</filename> and add references to each of the jars in <filename>argouml/modules/<replaceable>your name</replaceable>/build.xml</filename>. </para>
+ <para>Edit <filename class="directory" > argouml/modules/<replaceable>your name</replaceable> /module.properties</filename> </para>
+ <para>Edit <filename>argouml/modules/<replaceable>your name</replaceable>/src/org/manifest.mf</filename>. </para>
+ <para>Reorganize the source files as necessary. Remove the directory <filename class="directory" > argouml/modules/<replaceable>your name</replaceable> /src/org/argouml/ui</filename> and create your own classes like org.argouml.<replaceable>your package name</replaceable> in <filename class="directory" > argouml/modules/<replaceable>your name</replaceable> /src/org/argouml/<replaceable>your package name</replaceable></filename>. </para>
+ </listitem>
+
+ <listitem>
+ <para>â¦get Argo to use a plug-in? </para>
+
+ <note>
+ <para>This description is for the old module loader. </para>
</note>
- <para> Once you've created a jar file with a plug-in in it, you need to
- make sure that Argo can find the jar to be able to execute it. </para>
- <para> If you are using a "standard" ArgoUML source structure, then
- you should be able to execute <command>build install</command>
- or <command>ant install</command> in the source directory of the
- plug-in. This will copy the jar file to the proper directory in the
- main ArgoUML build target. You can test your plug-in by running
- <command>build run</command> in the <filename
- class="directory">src_new</filename> directory. </para>
- <para> If you need to install the jar "the hard way", try the following
- steps.
- <itemizedlist>
- <listitem><para> Start up ArgoUML. </para></listitem>
- <listitem><para> Go to the menu
- <command>Edit->Settings</command> and look at the
- <command>Environment</command> tab. Find the entry
- labeled <literal>${argo.ext.dir}</literal>. Create that
- directory if it does not already exist. </para></listitem>
- <listitem><para> Copy the plug-in jar and any other jars
- required by it into that directory. </para></listitem>
- <listitem><para> Start up ArgoUML again, and you should see the
- plug-in's startup banner (if it has one, of course). </para>
- </listitem>
-
- </itemizedlist>
+
+ <para>Once you've created a jar file with a plug-in in it, you need to make sure that Argo can find the jar to be able to execute it. </para>
+ <para>If you are using a "standard" ArgoUML source structure, then you should be able to execute <command>build install</command> or <command>ant install</command> in the source directory of the plug-in. This will copy the jar file to the proper directory in the main ArgoUML build target. You can test your plug-in by running <command>build run</command> in the <filename class="directory">src_new</filename> directory. </para>
+ <para>If you need to install the jar "the hard way", try the following steps. <itemizedlist>
+ <listitem>
+ <para>Start up ArgoUML. </para>
+ </listitem>
+ <listitem>
+ <para>Go to the menu <command>EditâSettings</command> and look at the <command>Environment</command> tab. Find the entry labeled <literal>${argo.ext.dir}</literal>. Create that directory if it does not already exist. </para>
+ </listitem>
+ <listitem>
+ <para>Copy the plug-in jar and any other jars required by it into that directory. </para>
+ </listitem>
+ <listitem>
+ <para>Start up ArgoUML again, and you should see the plug-in's startup banner (if it has one, of course). </para>
+ </listitem>
+ </itemizedlist>
</para>
</listitem>
- </itemizedlist> </para>
- </sect2>
- </sect1>
+ </itemizedlist>
+ </para>
+ </section>
+ </section>
</chapter>
-
<!-- Local stuff for Emacs - please do not delete
-
-Local Variables:
-mode: xml
-sgml-doctype: "cookbook.xml"
-sgml-parent-document: ("cookbook.xml" "chapter" nil)
-sgml-validate-command: "nsgmls -wxml -sv ../docbook-setup/xml.dcl \
-cookbook.xml"
-indent-tabs-mode: nil
-End:
-
+
+ Local Variables:
+ mode: xml
+ sgml-doctype: "cookbook.xml"
+ sgml-parent-document: ("cookbook.xml" "chapter" nil)
+ sgml-validate-command: "nsgmls -wxml -sv ../docbook-setup/xml.dcl \
+ cookbook.xml"
+ indent-tabs-mode: nil
+ End:
+
-->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/further_reading.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/further_reading.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/further_reading.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/further_reading.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/further_reading.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/further_reading.xml 2008-01-15 19:22:21-0800
@@ -1,120 +1,95 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
-// Copyright (c) 1996-2006 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.
+ // Copyright (c) 1996-2006 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.
-->
-<appendix id="further_reading">
+<appendix
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xml:id="further_reading"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ >
+
<title>Further Reading</title>
- <sect1 id="robbins">
- <title>Jason Robbins Dissertation</title> <indexterm>
+
+ <section xml:id="robbins">
+
+ <title>Jason Robbins Dissertation</title>
+ <indexterm>
<primary>Jason Robbins</primary>
- <secondary>Dissertation</secondary> </indexterm>
- <para> Cognitive Support Features for Software Development Tools </para>
- <para> The dissertation of Jason Robbins is a <emphasis>MUST
- READ</emphasis> for everyone concerned about ArgoUML. Be careful though,
- since it is based on an old version of ArgoUML, but many of the concepts remain
- intact. </para>
- <sect2>
+ <secondary>Dissertation</secondary>
+ </indexterm>
+ <para>Cognitive Support Features for Software Development Tools </para>
+ <para>The dissertation of Jason Robbins is a <emphasis>MUST READ</emphasis> for everyone concerned about ArgoUML. Be careful though, since it is based on an old version of ArgoUML, but many of the concepts remain intact. </para>
+
+ <section>
<title>Abstract</title>
- <para> Software design is a cognitively challenging task. Most software
- design tools provide support for editing, viewing, storing, sharing,
- and transforming designs, but lack support for the essential and
- difficult cognitive tasks facing designers. These cognitive tasks
- include decision making, decision ordering, and task-specific design
- understanding. To date, software design tools have not included
- features that specifically address key cognitive needs of designers, in
- part, because there has been no practical method for developing and
- evaluating these features. </para>
- <para> This dissertation contributes a practical description of several
- cognitive theories relevant to software design, a method for devising
- cognitive support features based on these theories, a basket of
- cognitive support features that are demonstrated in the context of a
- usable software design tool called ArgoUML, and a reusable
- infrastructure for building similar features into other design tools.
- ArgoUML is an object-oriented design tool that includes several novel
- features that address the identified cognitive needs of software
- designers. Each feature is explained with respect to the cognitive
- theories that inspired it and the set of features is evaluated with a
- combination of heuristic and empirical techniques. </para>
- </sect2>
- <sect2>
+ <para>Software design is a cognitively challenging task. Most software design tools provide support for editing, viewing, storing, sharing, and transforming designs, but lack support for the essential and difficult cognitive tasks facing designers. These cognitive tasks include decision making, decision ordering, and task-specific design understanding. To date, software design tools have not included features that specifically address key cognitive needs of designers, in part, because there has been no practical method for developing and evaluating these features. </para>
+ <para>This dissertation contributes a practical description of several cognitive theories relevant to software design, a method for devising cognitive support features based on these theories, a basket of cognitive support features that are demonstrated in the context of a usable software design tool called ArgoUML, and a reusable infrastructure for building similar features into other design tools. ArgoUML is an object-oriented design tool that includes several novel features that address the identified cognitive needs of software designers. Each feature is explained with respect to the cognitive theories that inspired it and the set of features is evaluated with a combination of heuristic and empirical techniques. </para>
+ </section>
+
+ <section>
<title>Where to find it</title>
- <para>LINK: <ulink
- url="http://argouml.tigris.org/docs/robbins_dissertation/">
- Robbins Dissertation</ulink> </para>
- </sect2>
- </sect1>
- <sect1 id="skinner">
- <title>Martin Skinners Dissertation</title> <indexterm>
+ <para>LINK: <link xlink:href="http://argouml.tigris.org/docs/robbins_dissertation/" > Robbins Dissertation</link> </para>
+ </section>
+ </section>
+
+ <section xml:id="skinner">
+ <title>Martin Skinners Dissertation</title>
+
+ <indexterm>
<primary>Martin Skinner</primary>
- <secondary>Dissertation</secondary> </indexterm>
- <para> Enhancing an UML Modeling Tool with Context-Based Constraints for
- Components </para>
- <sect2>
+ <secondary>Dissertation</secondary>
+ </indexterm>
+
+ <para>Enhancing an UML Modeling Tool with Context-Based Constraints for Components </para>
+
+ <section>
<title>Abstract</title>
- <para lang="de"> Noch vor der Erstellung eines detaillierten Entwurfs
- hilft ein Spezifikationsmodell eines komponenten-basierten Systems
- dabei, Probleme so früh im Entwicklungsprozess wie möglich zu
- entdecken. Die Sprache CCL ('Component Constraint Language') wurde bei
- CIS entwickelt und erlaubt den Entwickler 'Contextbased Constraints'
- dem Spezifikationsmodell hinzuzufügen. Dadurch entsteht ein Modell,
- das über die Beschreibung der statische Struktur des Systems
- hinausgeht. Zur Zeit existiert allerdings kein Werkzeug, dass das
- Komponentenspezifikationsmodell in den Entwicklungsprozess
- integriert. Ziel dieser Diplomarbeit war der Entwurf eines solchen
- Werkzeugs, um die Philosophie des Continuous Software Engineering
- (CSE) zu unterstützten. </para>
- <para> Before starting a detailed design, a specification model of the
- component-based system assists the software developer in early problem
- detection as soon as possible in the development process. The Component
- Constraint Language (CCL) developed at CIS enables the developer to add
- context-based constraints (CoCons) to a component specification
- model. This produces a model which goes beyond the simple description of
- the system's static structure. At this time, there is no tool to integrate
- the component specification model into the development process. The
- goal of this master's thesis was to design such a tool, thereby supporting
- the Continuous Software Engineering (CSE) philosophy. </para>
- </sect2>
- <sect2>
+ <para xml:lang="de" > Noch vor der Erstellung eines detaillierten Entwurfs hilft ein Spezifikationsmodell eines komponenten-basierten Systems dabei, Probleme so fr�h im Entwicklungsprozess wie m�glich zu entdecken. Die Sprache CCL ('Component Constraint Language') wurde bei CIS entwickelt und erlaubt den Entwickler 'Contextbased Constraints' dem Spezifikationsmodell hinzuzuf�gen. Dadurch entsteht ein Modell, das �ber die Beschreibung der statische Struktur des Systems hinausgeht. Zur Zeit existiert allerdings kein Werkzeug, dass das Komponentenspezifikationsmodell in den Entwicklungsprozess integriert. Ziel dieser Diplomarbeit war der Entwurf eines solchen Werkzeugs, um die Philosophie des Continuous Software Engineering (CSE) zu unterst�tzten. </para>
+ <para>Before starting a detailed design, a specification model of the component-based system assists the software developer in early problem detection as soon as possible in the development process. The Component Constraint Language (CCL) developed at CIS enables the developer to add context-based constraints (CoCons) to a component specification model. This produces a model which goes beyond the simple description of the system's static structure. At this time, there is no tool to integrate the component specification model into the development process. The goal of this master's thesis was to design such a tool, thereby supporting the Continuous Software Engineering (CSE) philosophy. </para>
+ </section>
+
+ <section>
<title>Where to find it</title>
- <para> LINK: <ulink
- url="http://www.cocons.org/publications/CCL_plugin_for_ArgoUML.pdf">
- Martin Skinners dissertation</ulink> </para>
- </sect2>
- </sect1>
+ <para>LINK: <link xlink:href="http://www.cocons.org/publications/CCL_plugin_for_ArgoUML.pdf" > Martin Skinners dissertation</link> </para>
+ </section>
+ </section>
</appendix>
<!-- Local stuff for Emacs - please do not delete
-
-Local Variables:
-mode: xml
-sgml-doctype: "cookbook.xml"
-sgml-parent-document: ("cookbook.xml" "chapter" nil)
-sgml-validate-command: "nsgmls -wxml -sv ../docbook-setup/xml.dcl \
-cookbook.xml"
-indent-tabs-mode: nil
-End:
-
+
+ Local Variables:
+ mode: xml
+ sgml-doctype: "cookbook.xml"
+ sgml-parent-document: ("cookbook.xml" "chapter" nil)
+ sgml-validate-command: "nsgmls -wxml -sv ../docbook-setup/xml.dcl \
+ cookbook.xml"
+ indent-tabs-mode: nil
+ End:
+
-->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/glossary.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/glossary.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/glossary.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/glossary.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/glossary.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/glossary.xml 2008-01-15 19:22:21-0800
@@ -1,46 +1,53 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
-// Copyright (c) 1996-2006 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.
+ // Copyright (c) 1996-2006 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.
-->
-<glossary>
+<glossary
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ >
+
<title>Glossary</title>
-
- <glossdiv id="terminology">
+
+ <glossdiv xml:id="terminology">
<title>Terminology in the ArgoUML project</title>
-
+
<para>
-This is the Terminology for the ArgoUML project and also for the ArgoUML
-product.
-The purpose is to establish a common use of some words to make it easier
-to understand what we are talking about.
-</para>
-
+ This is the Terminology for the ArgoUML project and also for the ArgoUML
+ product.
+ The purpose is to establish a common use of some words to make it easier
+ to understand what we are talking about.
+ </para>
+
<para>
-The terminology here is used for:
-</para>
+ The terminology here is used for:
+ </para>
<itemizedlist>
<listitem>
<para>All code (class names, variable names, method names)</para>
@@ -50,206 +57,206 @@
</listitem>
<listitem>
<para>
-All strings in the user interface (in the default language en_US)
-</para>
+ All strings in the user interface (in the default language en_US)
+ </para>
</listitem>
<listitem>
<para>All documents (in the default language en_US)</para>
</listitem>
<listitem>
<para>
-All postings to the mailing lists and all other discussions within
-the ArgoUML project.
-</para>
+ All postings to the mailing lists and all other discussions within
+ the ArgoUML project.
+ </para>
</listitem>
</itemizedlist>
-
+
<glossentry>
<glossterm>Add</glossterm>
<glossdef>
<para>
-Add existing object to something.
-</para>
+ Add existing object to something.
+ </para>
</glossdef>
</glossentry>
-
+
<glossentry>
<glossterm>Code Generation / Reverse Engineering</glossterm>
<glossdef>
<para>
-Code Generation and Reverse Engineering are the processes of converting
-between the ArgoUML UML model and program code
-in a certain programming language.
-ArgoUML supports different languages
-such as Java, C++ and PHP for Code Generation and Reverse Engineering,
-but both are not supported for all languages equally.
-</para>
+ Code Generation and Reverse Engineering are the processes of converting
+ between the ArgoUML UML model and program code
+ in a certain programming language.
+ ArgoUML supports different languages
+ such as Java, C++ and PHP for Code Generation and Reverse Engineering,
+ but both are not supported for all languages equally.
+ </para>
</glossdef>
</glossentry>
-
+
<glossentry>
<glossterm>Delete</glossterm>
<glossdef>
<para>
-Usually used as "Delete from Model".
-The object will be destructed, and will
-not be present any more on any diagram, nor in the model.
-Additionally, all objects that can not exist without the deleted object
-are deleted from the model, too.
-E.g. deleting a class also deletes all its associations.
-</para>
+ Usually used as "Delete from Model".
+ The object will be destructed, and will
+ not be present any more on any diagram, nor in the model.
+ Additionally, all objects that can not exist without the deleted object
+ are deleted from the model, too.
+ E.g. deleting a class also deletes all its associations.
+ </para>
</glossdef>
</glossentry>
-
+
<glossentry>
<glossterm>Dependency</glossterm>
<glossdef>
-
+
<para>
-A piece of software that is developed by someone outside of the
-ArgoUML project and that the ArgoUML project is not responsible for.
-</para>
- <para>
-The ArgoUML product, like almost any other software project,
-use dependencies so that we don't have to do everything ourselves.
-Examples: JDK, NSUML, GEF, log4j, ...
-</para>
-
+ A piece of software that is developed by someone outside of the
+ ArgoUML project and that the ArgoUML project is not responsible for.
+ </para>
+ <para>
+ The ArgoUML product, like almost any other software project,
+ use dependencies so that we don't have to do everything ourselves.
+ Examples: JDK, NSUML, GEF, log4j, â¦
+ </para>
+
<para>
-Dependencies were previously called subproducts.
-</para>
+ Dependencies were previously called subproducts.
+ </para>
<indexterm>
<primary>subproducts</primary>
</indexterm>
</glossdef>
</glossentry>
-
+
<glossentry>
<glossterm>Export</glossterm>
<glossdef>
<para>
-Export everything or some part from an existing structure to some format.
-This implies some kind of conversion involved.
-</para>
+ Export everything or some part from an existing structure to some format.
+ This implies some kind of conversion involved.
+ </para>
</glossdef>
</glossentry>
-
+
<glossentry>
<glossterm>Import</glossterm>
<glossdef>
<para>
-Import some other format into an existing structure.
-This implies that there is some kind of conversion involved and that
-the already existing things are not removed.
-They are either changed or left unchanged by the import.
-An Export, New, Import cycle can lead to information loss because
-of the two conversions involved.
-</para>
+ Import some other format into an existing structure.
+ This implies that there is some kind of conversion involved and that
+ the already existing things are not removed.
+ They are either changed or left unchanged by the import.
+ An Export, New, Import cycle can lead to information loss because
+ of the two conversions involved.
+ </para>
</glossdef>
</glossentry>
-
+
<glossentry>
<glossterm>Library</glossterm>
<glossdef>
<para>
-A part of a <emphasis>dependency</emphasis> that is installed and handled as
-a unit in the ArgoUML building and installation set-up.
-</para>
+ A part of a <emphasis>dependency</emphasis> that is installed and handled as
+ a unit in the ArgoUML building and installation set-up.
+ </para>
</glossdef>
</glossentry>
-
+
<glossentry>
<glossterm>Module</glossterm>
<glossdef>
<para>
-A piece of software that is to be loaded into ArgoUML by the Module Loader.
-</para>
+ A piece of software that is to be loaded into ArgoUML by the Module Loader.
+ </para>
<para>
-Modules traditionally use the Plug-in interfaces and are for that
-reason also known as Plug-ins.
-</para>
+ Modules traditionally use the Plug-in interfaces and are for that
+ reason also known as Plug-ins.
+ </para>
</glossdef>
</glossentry>
-
+
<glossentry>
<glossterm>New</glossterm>
<glossdef>
<para>
-Create a new project or object.
-How does this relate to the Java GUI standards?
-(Don't use Create or Add)
-</para>
+ Create a new project or object.
+ How does this relate to the Java GUI standards?
+ (Don't use Create or Add)
+ </para>
</glossdef>
</glossentry>
-
+
<glossentry>
<glossterm>Notation</glossterm>
<glossdef>
<para>
-Notation is the textual representation of model fragments
-on a diagram. ArgoUML supports Notation
-in different languages such as UML and Java.
-Notation may be not only pure text: e.g. UML attributes/operations
-have graphical text properties (underlining, italics)
-with a semantic relevance. To be shown on a diagram, the text has to be
-created by a generator,
-and when the user edits
-the text on the diagram, a parser processes the text,
-and adapts the model accordingly.
-</para>
+ Notation is the textual representation of model fragments
+ on a diagram. ArgoUML supports Notation
+ in different languages such as UML and Java.
+ Notation may be not only pure text: e.g. UML attributes/operations
+ have graphical text properties (underlining, italics)
+ with a semantic relevance. To be shown on a diagram, the text has to be
+ created by a generator,
+ and when the user edits
+ the text on the diagram, a parser processes the text,
+ and adapts the model accordingly.
+ </para>
</glossdef>
</glossentry>
-
+
<glossentry>
<glossterm>Open</glossterm>
<glossdef>
<para>
-Open an existing project or saved file.
-How does this relate to the Java GUI standards?
-(Don't use Load, Read, or Import for this).
-</para>
+ Open an existing project or saved file.
+ How does this relate to the Java GUI standards?
+ (Don't use Load, Read, or Import for this).
+ </para>
</glossdef>
</glossentry>
-
+
<glossentry>
<glossterm>Remove</glossterm>
<glossdef>
<para>
-Usually used as "Remove from Diagram". The object that will be removed is
-not deleted from the model, i.e. it still exists, but is simply not present
-any more on the current diagram. It might still be present on other diagrams,
-or not, but it is surely present in the explorer.
-Additionally, all objects that cannot be drawn without the removed object,
-are removed from the diagram, too. E.g. removing a class also removes all
-its associations.
-Once removed, an object can be "added" to a diagram (again).
-</para>
+ Usually used as "Remove from Diagram". The object that will be removed is
+ not deleted from the model, i.e. it still exists, but is simply not present
+ anymore on the current diagram. It might still be present on other diagrams,
+ or not, but it is surely present in the explorer.
+ Additionally, all objects that can not be drawn without the removed object,
+ are removed from the diagram, too. E.g. removing a class also removes all
+ its associations.
+ Once removed, an object can be "added" to a diagram (again).
+ </para>
</glossdef>
</glossentry>
-
+
<glossentry>
<glossterm>Save</glossterm>
<glossdef>
<para>
-Save the existing project to a file.
-The Save operation saves everything (it is a no-loss operation).
-A Save, Open cycle does not loose any information.
-(Don't use Export, or Write for this).
-</para>
+ Save the existing project to a file.
+ The Save operation save everything (it is a no-loss operation).
+ A Save, Open cycle does not loose any information.
+ (Don't use Export, or Write for this).
+ </para>
</glossdef>
</glossentry>
-
+
</glossdiv>
</glossary>
<!-- Local stuff for Emacs - please do not delete
-
-Local Variables:
-mode: xml
-sgml-doctype: "cookbook.xml"
-sgml-parent-document: ("cookbook.xml" "book" nil)
-indent-tabs-mode: nil
-End:
-
--->
+
+ Local Variables:
+ mode: xml
+ sgml-doctype: "cookbook.xml"
+ sgml-parent-document: ("cookbook.xml" "book" nil)
+ indent-tabs-mode: nil
+ End:
+
+-->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/inside_subsystems.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/inside_subsystems.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/inside_subsystems.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/inside_subsystems.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/inside_subsystems.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/inside_subsystems.xml 2008-01-15 19:22:21-0800
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
// Copyright (c) 1996-2007 The Regents of the University of California. All
@@ -25,1094 +25,685 @@
// UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
-->
-<chapter id="inside_subsystems">
- <title>Inside the subsystems</title> <warning>
- <para> This chapter is currently under rework with new subsystem organization.
- </para>
- <para> Things that are not actually in place are: TargetManager </para>
- </warning>
- <para>...</para>
-
- <!--
+<chapter
+ xml:id="inside_subsystems"
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink">
+
+ <title>Inside the Subsystems</title>
+
+ <warning>
+ <para>This chapter is currently under rework with new subsystem organization.</para>
+ <para>Things that are not actually in place are: TargetManager </para>
+ </warning>
+
+ <para>â¦</para>
+
+ <!--
Each section in this chapter describes a subsystem.
It starts with:
Purpose - one or two sentences/lines.
Where that subsystem is located.
What layer it belongs to.
-->
-
- &subsystemmodel;
+
+ <!--
+ &subsystemmodel;
&subsystemcritics;
&subsystemdiagrams;
&subsystempropertypanels;
&subsystempersistence;
- &subsystemnotation;
-
- <sect1 id="reverseengineering">
- <title>Reverse Engineering Subsystem</title> <indexterm>
- <primary>Reverse Engineering</primary> </indexterm>
- <para> Purpose: Provide a central registration point for language reverse
- engineering modules as well as common reverse engineering methods for
- all languages. </para>
- <para> The Reverse Engineering subsystem is located in
- <classname>org.argouml.uml.reveng</classname>. </para>
- <para> The Reverse Engineering Subsystem is a Control subsystem. See <xref
- linkend="view_control_subsystems"></xref>. </para>
-
- <itemizedlist>
-
- <listitem>
- <para> All language reverse engineering modules must implement the
- <classname>org.argouml.uml.reveng.ImportInterface</classname>
- interface. </para>
- </listitem>
- <listitem>
- <para> All modules must implement the
- <classname>org.argouml.moduleloader.ModuleInterface</classname>
- interface. </para>
- </listitem>
- <listitem>
- <para> At initialization time, each language registers themselves using
- <classname>org.argouml.uml.reveng.ImportManager</classname>.
- </para>
- </listitem>
-
-
- </itemizedlist>
-
- <sect2>
- <title>Common import code</title>
- <para>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).</para>
- </sect2>
-
- <sect2>
- <title>Diagram layout algorithms</title>
- <para> 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: </para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/examples/example1.gif"
- format="GIF"/>
- </imageobject>
- </mediaobject>
- <para> In the next diagram, a link goes to an object that is not in the row
- above: </para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/examples/example2.gif"
- format="GIF"/>
- </imageobject>
- </mediaobject>
- <para> In this case, insert virtual objects which are linked to the actual
- target and link to them: </para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/examples/example3.gif"
- format="GIF"/>
- </imageobject>
- </mediaobject>
- <para> 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: </para>
- <blockquote>
- <para> A B C : rank 0 </para>
- <para> D E F : rank 1 </para>
- </blockquote>
- <para> We give the super-classes an index in their rank (assuming that they
- are already sorted): </para>
- <blockquote>
- <para> A:0, B:1, C:2 </para>
- </blockquote>
- <para> D, E, F have the following links (A, B, C could be interfaces, so I allow
- links to multiple super-classes here): </para>
- <blockquote>
- <para> D -> C </para>
- <para> E -> A and C </para>
- <para> F -> A and B </para>
- </blockquote>
- <para> Compute the average value of the indexes: </para>
- <blockquote>
- <para> D = 2 (C has index 2 / 1 link) </para>
- <para> E = 0 + 2 / 2 = 1 (A=0, C=2 divide by 2 links) </para>
- <para> F = 0 + 1 / 2 = 0.5 (A=0, B=1, 2 links) </para>
- </blockquote>
- <para> Then sort the subclasses by that value: </para>
- <blockquote>
- <para> F(is 0.5), E(is 1), D(is 2) </para>
- </blockquote>
- <para> So the placement is: </para>
- <blockquote>
- <para> A B C </para>
- <para> (here are the links, but I can hardly paint them as ASCIIs) </para>
- <para> F E D </para>
- </blockquote>
- </sect2>
-
- </sect1>
-
- <sect1 id="codegeneration">
- <title>Code Generation Subsystem</title>
- <indexterm>
- <primary>Code Generation</primary>
- </indexterm>
- <para> Purpose: Point where the different languages register that they know
- how to do code generation and common functions for all languages. </para>
- <para> The Code Generation is located in
- <classname>org.argouml.language</classname>. </para>
- <para> The Code Generation subsystem is a Control subsystem. See <xref
- linkend="view_control_subsystems"></xref>. </para>
-
- <para> The code to generate various languages
- that is supplied with ArgoUML
- is found in sub-packages of
- <classname>org.argouml.language</classname>.
- In the case of languages
- other than Java, these classes will come from independent projects and
- be packaged separately even though they share this package name space.
- <warning>NOTE: There is a potential conflict here if two separate
- language implementations use this name space in an uncoordinated fashion
- (e.g. two Ruby implementations using org.argouml.language.ruby).
- </warning>
- </para>
-
-
- <itemizedlist>
-
- <listitem>
- <para> All source language code generators must implement the
- <classname>org.argouml.uml.generator.CodeGenerator</classname>
- interface. </para>
- </listitem>
- <listitem>
- <para> All modules must implement the
- <classname>org.argouml.moduleloader.ModuleInterface</classname>
- interface. </para>
- </listitem>
- <listitem>
- <para>At initialization time, each language registers themselves using
- <classname>org.argouml.uml.generator.GeneratorManager</classname>.
- </para>
- </listitem>
-
-
- </itemizedlist>
-
- </sect1>
-
- <sect1 id="java">
- <title>Java - Code Generation and Reverse Engineering</title>
- <indexterm>
- <primary>Reverse Engineering</primary>
- <secondary>Java</secondary>
- </indexterm>
- <indexterm>
- <primary>Code generation</primary>
- <secondary>Java</secondary>
- </indexterm>
- <indexterm>
- <primary>Round-trip Engineering</primary>
- <secondary>Java</secondary> </indexterm>
- <indexterm>
- <primary>Java</primary>
- </indexterm>
-
- <para> Purpose - two purposes: to allow the model to be converted into java code
- and updated either in java or in the model; to allow some java code to be
- converted into a model. </para>
- <para> The java things are located in
- <classname>org.argouml.language.java</classname>. </para>
- <para> The Java subsystem is a Loadable subsystem. See <xref
- linkend="loadable_subsystems"></xref>. </para>
-
- <sect2 id="howdoi_reverse">
- <title>How do I ...?</title>
- <para>...</para></sect2>
-
- <sect2>
- <title>Which sources are involved?</title>
- <para> 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. </para>
- <para> 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... </para>
- </sect2>
- <sect2>
- <title>How is the grammar of the target language implemented?</title>
- <para> It is an Antlr (<ulink url="http://www.antlr.org">
- http://www.antlr.org</ulink>) 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.</para>
- </sect2>
- <sect2>
- <title>Which model/diagram elements are generated?</title>
- <para> 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.
- </para>
- </sect2>
- </sect1>
-
- <sect1 id="otherlanguages">
- <title>Other source languages (C++, Python, etc)</title>
- <para> Each source language supported by ArgoUML has its own subsystem. They
- are each different in level of support and implementation language. All
- languages except for Java are in their own dedicated Tigris project with
- separate web site, mailing lists, source repository, etc. For example,
- the C++ plugin is located <ulink url="http://argouml-cpp.tigris.org/">
- here</ulink>.
- </para>
- <para>Currently C++ has no reverse engineering but only code generation (and
- a very simple one at that). The Java classfile module has only reverse
- engineering.
- </para>
- <para>There are stubs/shells for many different languages, but the following
- are mature enough to be distributed with ArgoUML: C++ (Cpp), C# (Csharp),
- classfile, IDL, and PHP. Others at various stages of development include:
- Python, Ruby, and SQL.</para>
- <para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/cookbook/Languages.gif"
- format="GIF"/>
- </imageobject>
- </mediaobject> </para>
-
- </sect1>
-
- <sect1 id="guiframework">
- <title>The GUI</title>
- <indexterm>
- <primary>GUI Framework</primary>
- </indexterm>
- <indexterm>
- <primary>Details Panel</primary>
- </indexterm>
-
- <para> Purpose - Provide an infrastructure with menus, tabs and panes
- available for the other subsystems to fill with actions and contents.
- </para>
- <para> This subsystem has no knowledge of UML, Critics, Diagrams, or Model.
- </para>
- <para> The GUI Framework is located in
- <classname>org.argouml.ui</classname>.
- </para>
- <para> This is implemented directly on top of Swing and Java. </para>
- <para> The GUI framework provides the following options
- <itemizedlist>
- <listitem>
- <para>The menu with actions</para>
- </listitem>
- <listitem>
- <para>The tool-bar with actions</para>
- </listitem>
- <listitem>
- <para>The Explorer (formerly called Navigator)</para>
- <para>Located in
- <classname>org.argouml.ui.explorer</classname>. Contains the
- tree structure with configurable perspectives. </para>
- </listitem>
- <listitem>
- <para>Tabbed pane</para>
- <para> Could contain several different panes. </para>
- </listitem>
- <listitem>
- <para>The TargetManager</para>
- <para>See <xref linkend="targetmanager"></xref>.</para>
- </listitem>
- <listitem>
- <para>The Settings Tab</para>
- </listitem>
-
- </itemizedlist>
- </para>
-
- <para>
- The GUI subsystem does not contain any knowledge of what is going
- to be put into the different panes but it has knowledge of
- parts of the semantics of those components.
- </para>
-
- <para>
- The components that want to be placed into any of these
- register with the GUI subsystem using the appropriate method in
- <classname>org.argouml.ui.GUI</classname>.
- </para>
-
- <para>Other subsystems that supply their own user interface,
- may be split into 2 packages, e.g.
- <classname>org.argouml.some-subsystem</classname> and
- <classname>org.argouml.some-subsystem.ui</classname>.
- In such case the following figure indicates
- the allowed dependencies:
- </para>
-
- <para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/cookbook/subsystem-ui.png"
- format="PNG"/>
- </imageobject>
- </mediaobject>
- </para>
-
- <sect2 id="targetmanager">
- <title>The TargetManager</title>
- <para> Located in
- <classname>org.argouml.ui.targetmanager</classname>.
- </para>
- <para>The purpose of the targetmanager is
- to have a central spot to manage
- the list of current targets.
- </para>
- <para>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.</para>
- <para>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.
- </para>
- <para>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.
- </para>
- <para> Thanks to the architecture of ArgoUML of Modelelements and
- Figs, one rule has been decided upon<!-- (by [email protected] ) -->:
- <emphasis>The list of targets shall not contain any Fig that has an
- owner</emphasis>. Instead, the owner is enlisted.
- </para>
- <para>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.
- </para>
- <para>Via an event mechanism this manager makes sure
- that all objects interested
- in knowing whether the selection changed are notified.
- </para>
- <para>The TargetManager does not depend on the
- <classname>org.argouml.ui</classname> package,
- nor any of its sub-packages.
- Hence, it can be used by all of these
- to modify the target,
- or get it.
- </para>
- <para>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.
- </para>
-
- </sect2>
-
- </sect1>
-
- <sect1 id="application">
- <title>Application</title>
- <para> Purpose - to provide the entry point when starting ArgoUML.
- Responsibility to start the ball rolling. </para>
- <para> The Application is located in
- <classname>org.argouml.application</classname>. </para>
- <para> The entry point is called
- <classname>org.argouml.application.Main</classname>. </para>
-
- <sect2>
- <title>What is loaded/initialized?</title>
- <para> 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. </para>
- <para> 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.
- </para>
- </sect2>
-
- <sect2>
- <title>Details pane</title>
- <para> The Details pane contains several tabs:
- Property Panels (See <xref linkend="propertypanels"></xref>,
- Critics explanations and wizards (belonging to the Critics subsystem)
- (See <xref linkend="critics"></xref>), Documentation, Style,
- Source, Constraints (OCL constraints on the current object. See
- <xref linkend="ocl"></xref>), and Tagged values. <warning>
- <para> It is not clear in what subsystem Documentation, Style, Source,
- and Tagged values belong. </para> </warning> </para>
-
- <sect3 id="howdoi_detailspanel">
- <title>How do I ...?</title>
- <para>
- <itemizedlist>
- <listitem>
- <para>...add a tab in the Details Panel?</para>
- <para> Create your <classname>TabXXX</classname> class in
- <classname>org.argouml.uml.ui</classname> by copying from
- another <filename>TabYYY.java</filename> (e.g.
- <classname>TabSrc</classname>,
- <classname>TabStyle</classname>). Then register your
- <classname>TabXXX</classname> in
- <filename>org/argouml/argo.ini</filename> by adding a line
- giving the compass point to place the tab. Like -
- <programlisting>
-south: TabXXX
-</programlisting>
- </para>
- </listitem>
- <listitem>
- <para>...remove a tab from the Details Panel?</para>
- <para> Remove the line for the tab from
- <filename>org/argouml/argo.ini</filename>. </para>
- </listitem>
- </itemizedlist> </para>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1 id="help">
- <title>Help System</title> <indexterm>
- <primary>Help system</primary> </indexterm>
- <para> Purpose - to provide the menu actions that start the help and other
- documentation. To provide infrastructure that makes context sensitive
- help possible. </para>
- <para> The Help System is not yet implemented. </para>
- <para> The Help System will be located in
- <classname>org.argouml.help</classname>. </para>
- <para> The Help System is a ??Infrastructure?? subsystem.
- <!--
- TODO: It however violates the layer concept by providing menu items that fit
- into the GUI Framework.
- -->
-</para>
- <para> Javahelp or some other help function will probably be used. </para>
-
- </sect1>
-
- &subsysteminternationalization;
- &subsystemlogging;
-
- <sect1 id="taskmgmt">
- <title>TaskManagement</title>
- <para> Purpose - Everything related to the concept of Task, Job
- or Request. </para>
- <para> The TaskManagement is an infrastructure
- or low-level subsystem. See <xref
- linkend="infrastructure_subsystems"></xref>.
- Currently, this subsystem contains the ProgressMonitor.
- </para>
- <para>The ProgressMonitor is explained by the following:
- SomethingA needs a long running service from SomethingB.
- So, SomethingA decides to ask
- for it in a different Thread of execution
- and to monitor the progress of
- the task in its main thread.
- The reason why it monitors the progress
- could be because it wants to show feedback
- to the user via the GUI,
- but, it could also be in order
- to decide that if there is no progress,
- it should give up by interrupting its other Thread.
- </para>
- </sect1>
-
- <sect1 id="configuration">
- <title>Configuration</title>
- <para> Purpose - Store and retrieve
- all configurable aspects
- of the ArgoUML application. </para>
- <para> The Configuration subsystem is an infrastructure
- or low-level subsystem. See <xref
- linkend="infrastructure_subsystems"></xref>.
- It handles all configuration that is stored
- in the user's home directory
- in the file named "argo.user.properties".
- </para>
- <para>Not inside the scope of this package
- are all the configuration settings
- that are stored in the project,
- i.e. in the .zargo file.
- </para>
- </sect1>
-
- <sect1 id="todoitems">
- <title>To Do items</title>
- <indexterm>
- <primary>To Do Items</primary>
- </indexterm>
-
- <para> Purpose - To keep track of the To do items. Items are generated and
- removed automatically by the critics. They could also be created by other
- means. </para>
- <para> The To Do items are located in
- <classname>org.argouml.cognitive.ToDoItem</classname>
- </para>
- <warning>This is a set of classes in the Cognitive subsystem, not a
- subsystem of its own.</warning>
-
- </sect1>
-
- <sect1 id="explorer">
- <title>Explorer</title>
- <indexterm>
- <primary>Explorer</primary>
- </indexterm>
- <indexterm>
- <primary>Object Explorer</primary>
- </indexterm>
- <indexterm>
- <primary>Navigator Tree</primary>
- </indexterm>
-
- <para> Purpose - to provide tree views of the model elements, diagrams and
- other objects. Note: the Explorer used to be called the Navigator. </para>
- <para> The Explorer is located in
- <classname>org.argouml.ui.explorer</classname> and sub-packages.
- </para>
- <para> The Explorer is a Layer 2 subsystem. See <xref
- linkend="view_control_subsystems"></xref>. </para>
-
- <sect2>
- <title>Requirements</title>
- <para> The Explorer must react to user and application events. </para>
- <para> User events include
- <itemizedlist spacing="compact" continuation="restarts">
- <listitem>
- <para> R1: selection of a node, which must notify the other views to
- make the same selection. </para>
- </listitem>
- <listitem>
- <para> R2: right click on a node, which brings up a pop-up menu.
- </para>
- </listitem>
- <listitem>
- <para> R3: selection of another perspective in the Combo box, which
- must change the explorer to that perspective. A perspective
- provides a different view of the model that will focus on one or
- other part of the model. </para>
- </listitem>
- <listitem>
- <para> R4: node expansion and collapse. </para>
- </listitem>
-
- <listitem>
- <para> R5: It is possible to drag name-space nodes on to other
- name-space nodes. Dropping a name-space node onto another, will,
- if the destination name-space is a valid one, update the explorer
- and model. </para>
- </listitem>
-
- <listitem>
- <para> R6: sorting of nodes with a particular Ordering. [an ordering
- is a comparator that orders child nodes in the explorer, e.g. by
- name and/or type]. </para>
- </listitem>
-
- <listitem>
- <para> R7: copy diagram to clipboard functionality for
- windows/java5 users. </para>
- </listitem>
-
- <listitem>
- <para> R8: tool-tip showing node name and type. </para>
- </listitem>
-
- <listitem>
- <para> R9: standard multiple discontinuous selection with mouse
- and keyboard. </para>
- </listitem>
-
- <listitem>
- <para> R10: the user can configure the perspectives using a dialog.
- Perspectives can be added, deleted, renamed, reordered and
- duplicated. Perspective rules can be added and removed from a
- perspective. The changes are saved to the user properties. If
- there are user perspectives when ArgoUML starts, it loads these,
- otherwise it loads a default set of perspectives. </para>
- </listitem>
-
- </itemizedlist> </para>
- <para> Application events include
- <itemizedlist continuation="restarts" spacing="compact">
-
- <listitem>
- <para> R11: change in selection in another view, any relevant rows to
- be highlighted. </para>
- </listitem>
- <listitem>
- <para> R12: the UML model changes, the tree must update to reflect
- additions/deletions and name changes in the model. </para>
- </listitem>
- <listitem>
- <para> R13: change of project, the tree must update. the root node
- should be expanded with the default diagram selected. </para>
- </listitem>
- </itemizedlist> </para>
- </sect2>
-
- <sect2>
- <title>Public APIs and SPIs</title>
- <para> The Explorer Subsystem provides/will provide the following APIs:
- <itemizedlist continuation="restarts" spacing="compact">
-
- <listitem>
- <para> API1: Addition / Removal of a Perspective from the
- PerspectiveManager. Status: implemented </para>
- </listitem>
- <listitem>
- <para> API2: Addition / Removal of a Perspective Rule from a
- Perspective. Status: implemented </para>
- </listitem>
- <listitem>
- <para> API3: Selection of the Perspective to be displayed by the
- Explorer. Status: not implemented </para>
- </listitem>
- <listitem>
- <para> API4: Selection of Ordering for Explorer nodes. [an Ordering
- is a comparator that orders child nodes in the Explorer] Status:
- not implemented </para>
- </listitem>
- </itemizedlist> </para>
-
- <para> The Explorer Subsystem provides/will provide the following SPIs:
- <itemizedlist continuation="restarts" spacing="compact">
-
- <listitem>
- <para> SPI1: Configurable Node pop-up menu. Status: not
- implemented </para>
- </listitem>
- <listitem>
- <para> SPI2: New PerspectiveRules can be defined and registered
- with the 'library' of available rules. Status: not implemented
- </para>
- </listitem>
- <listitem>
- <para> SPI3: New Orderings can be defined and registered with the
- available orderings. [an ordering is a comparator that orders
- child nodes in the explorer] Status: not implemented </para>
- </listitem>
- </itemizedlist> </para>
-
- <para> The APIs collectively represent the Explorer subsystem facade and
- the SPIs represent plug-ins. </para>
- </sect2>
-
- <sect2 id="explorer-implementation-details">
- <title>Details of the Explorer Implementation</title>
-
- <para> The Explorer is currently shown in the Explorer Pane
- (<classname>org.argouml.ui.NavigatorPane</classname>) - the upper
- left hand pane of ArgoUML. </para>
-
- <para> 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. </para>
-
- <para> 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. </para>
-
- <para>
- <mediaobject>
- <imageobject>
- <imagedata
- fileref="images/cookbook/explorer-architecture.gif"
- format="GIF"/>
- </imageobject>
- </mediaobject> </para>
-
- <para> 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.
- <orderedlist continuation="restarts" spacing="compact">
-
- <listitem>
- <para> The JTree (org.argouml.ui.explorer.ExplorerTree) has
- been customized to maintain consistent selection state with the
- other model views. It provides a pop up menu (ExplorerPopup) for
- performing actions on specific model elements. There is specific
- functionality in DnDExplorerTree for Drag and drop, and in
- ExportExplorer for copy diagram to clipboard. </para>
- </listitem>
- <listitem>
- <para> The TreeModel is a customized DefaultTreeModel that listens
- to changes in the UML model. The JTree builds the tree model as the
- user expands nodes, this minimizes the size of the model to those
- part that the user is interested in. The TreeModel contains custom
- DefaultMutableTreeNodes, ExplorerTreeNodes, that maintain
- their own order on child nodes; this will typically be an
- alphabetical order on the model element names. However, it could
- be enhanced to include more powerful orders like total subtree
- size. </para>
- </listitem>
- <listitem>
- <para> The model uses the third part of the Explorer design,
- PerspectiveRules, to add child nodes to the leaves of the tree. The
- structure of the tree is wholly dependent on the collection of
- PerspectiveRules that together provide a specialized view of the
- UML model. This is very flexible and extensible. The
- org.argouml.ui.explorer.rules package contains a default set
- of PerspectiveRules. </para>
- </listitem>
- </orderedlist> </para>
- <para> 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
- <classname>org.argouml.uml.ui.UMLTreeRenderer</classname> (for
- the Icon), and the text is produced in the
- <methodname>convertValueToText(...)</methodname> method in
- <classname>org.argouml.ui.explorer.ExplorerTree</classname>.
- </para>
- </sect2>
-
- <sect2>
- <title>How do I ...?</title>
- <para>
- <itemizedlist>
- <listitem>
- <para>...add another perspective?</para>
- <para>
- <itemizedlist>
- <listitem>
- <para> The perspectives can be configured using the
- <classname>org.argouml.ui.explorer.PerspectiveConfigurator</classname>
- by the User. The changes to the pre-defined built-in
- defaults are stored in the
- <filename>argo.user.properties</filename>
- file.
-</para>
- </listitem>
- <listitem>
- <para> If you want to do this as part of an extension to ArgoUML
- then you should use (see above) APIs 1,2 and 3, and SPI 2. The
- functions needed are present in the
- <classname>PerspectiveManager</classname>. </para>
- </listitem>
- </itemizedlist> </para>
- </listitem>
- <listitem>
- <para>...improve the PopUp menu?</para>
- <para> There is no way of doing this currently without modifying the
- core of ArgoUML. You could use SPI1 when it gets implemented.
- </para>
- </listitem>
- <listitem>
- <para>...extend the Explorer in other ways?</para>
- <para> The best way is to use the above APIs/SPIs; if they are not
- implemented then it would be best to implement them and feedback
- your improvements to the ArgoUML project so that your code works on
- a recognized public API that will be maintained in the future.
- </para>
- </listitem>
-
- <listitem>
- <para>...add new rules for new model elements?</para>
- <para> You should create a GoRule/PerspectiveRule in
- <address>org/argouml/ui/explorer/rules</address>. There
- are plenty of examples to look at. The important things to get right
- is of course that:
- </para>
- <para>
- <itemizedlist>
- <listitem><para> you return the right children</para>
- </listitem>
- <listitem>
- <para> return the objects that the TreeModel must
- listen to to know when to update the node (and the list of
- immediate children) After that you must register your GoRule
- in org/argouml/ui/explorer/PerspectiveManager
- </para>
- </listitem>
- <listitem><para> add it to the list in loadRules()</para>
- </listitem>
- <listitem>
- <para>
-perhaps add it to some of the default
- perspectives in oldLoadDefaultPerspectives(), I guess And
- then I think it should just be a matter of recompiling and
- possibly switching to the perspective you added your rule
-to.
-</para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
-
- <listitem>
- <para>...tell the explorer to refresh?</para>
- <para> You are not supposed to. The TreeModel is supposed to listen to
- events and refresh affected parts. And this is where the lack of
- events for adding diagrams creates a problem. </para>
- <para> Obviously it would be possible to add an operation somewhere
- to revalidate the expanded parts of the Explorer, but I'm not aware
- of the existence of such an operation today. </para>
- </listitem>
-
- <listitem>
- <para>...navigate programmatically to a certain explorer element
- so that its path is exploded?
- </para>
- <para>In general you can't. The Explorer tree is lazy in that it only
- explores the parts of the tree that the user has opened. And since
- the GoRules are general navigating to them would require a
- complete tree search. Which is also complicated by the fact that
- the answer is not unique and there can be branches with infinite
- depth. </para>
- <para> In reality it would be possible to create an algorithm to
- search out one occurrence of an element (since the model only
- contains finitely many elements and I assume that no-one will add
- go rules that add branches of infinite length that does not
- infinitely often contain elements from the model), but I don't
- think anyone has done it. Obviously finding all occurrences
- cannot be done. </para>
- </listitem>
- </itemizedlist> </para>
- </sect2>
- </sect1>
-
- <sect1 id="moduleloader">
- <title>Module loader</title>
- <indexterm>
- <primary>Module loader</primary>
- </indexterm>
- <indexterm>
- <primary>Pluggable interface</primary>
- </indexterm>
-
- <para> Purpose - to provide the mechanisms to load (and unload) the auxiliary
- modules. </para>
- <para> The Module loader is located in
- <classname>org.argouml.moduleloader</classname>. </para>
-
- <para> It is the modules' responsibility to connect and register to the
- subsystem or subsystems it is going to work with using that subsystem's API,
- Facade, or Plug-in interface. </para>
- <para> A previous implemention of the module loader was located in
- <classname>org.argouml.application.modules.ModuleLoader</classname>
- with interfaces (Pluggable) in
- <classname>org.argouml.application.api</classname>, but it has been
- replaced by the interface described here. </para>
- <para> For details on how to build a module see <xref
- linkend="modules_and_plugins"></xref>. </para>
- <sect2>
- <title>What the ModuleLoader does</title>
- <para> 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. </para>
- <para> 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?]</para>
- </sect2>
-
- <sect2 id="design-module-loader">
- <title>Design of the Module Loader</title>
- <para> Design:
- <itemizedlist>
- <listitem>
- <para> We use a Loadable Proxy Pattern(?) for the modules. </para>
- </listitem>
-
- <listitem>
- <para> Each module can be enabled and disabled individually.
- Dependencies between modules are allowed although not yet handled
- gracefully. </para>
- </listitem>
-
- <listitem>
- <para> Each module is required to have one (1) class that implements
- <classname>ModuleInterface</classname>. That class (and all
- other classes that constitute the module) needs to be made
- available for some class loader, either by including it in the
- classpath or by letting the module loader hunt for it. </para>
- </listitem>
- <listitem>
- <para> The modules are allowed to use all the APIs available from all
- the subsystems within ArgoUML and from other modules. </para>
- <para> This is a big improvement over the old module loader in that:
- <itemizedlist>
- <listitem>
- <para> We use the same APIs for the modules that we use within
- ArgoUML meaning that we implement and document it only once.
- This replaces the Pluggable class at every point where
- ArgoUML can be augmented. </para>
- </listitem>
- <listitem>
- <para> We can have the module have different classes to
- register at different parts of ArgoUML. </para>
- </listitem>
- <listitem>
- <para> We can have dynamic registrations that the module add
- and remove over time depending on some criteria that the
- module decides. </para>
- </listitem>
- <listitem>
- <para> We don't need to search through all modules at every
- possible point where ArgoUML can be augmented. </para>
- </listitem>
- </itemizedlist> Just as in the old solution, whenever a module
- needs to do something to ArgoUML, there needs to be implemented an
- API, possibly with registration/deregistration and callbacks.
- </para>
- </listitem>
-
- <listitem>
- <para> All modules that can be found are examined at startup. They can
- be enabled and disabled individually from a special available
- modules window but have a default state that applies if the user
- hasn't taken action. Currently the default state is "enabled".
- </para>
- </listitem>
-
- <listitem>
- <para> Dependency between modules! </para>
- <para> If a module cannot be enabled because some other module needs
- to be enabled first or because some part of ArgoUML needs to be
- initialized first this is a problem. This is because the initial
- implementation is such that we have no register of dependencies.
- </para>
- <para> The solution suggested is that the module loader persists in
- its attempts to enable a module so that the order among the modules
- is not important. For this to work the modules needs to signal when
- they fail. This is done by returning false or throwing an Exception
- from the module enabling method. </para>
- <para> The module loader also provides an API that the well-behaving
- modules can use to test if the modules they depend on are enabled.
- The less well-behaving modules can just throw an exception when
- they fail to enable themselves properly. </para>
- <para> If a module cannot be disabled, because some other module
- depends on it then this is signaled by returning false from the
- disabling method. </para>
- </listitem>
-
- <listitem>
- <para> Where modules are loaded from? </para>
- <para> The modules are loaded from the same places as in the old module
- loader. They can be internally i.e. available in the core jar file
- of ArgoUML, from the <filename class="directory">
- ext</filename> directory, or if running from JavaWebStart, they
- can be downloaded from the site. </para>
- <para> To reduce the complexity of the downloads, let's use it in the
- simplest possible way: organize each module in a package and a jar
- file, have the jnlp-file list that jar file as a part and a package
- entry listing the classes, have a file listing optional classes
- and a GUI that allows the user to download them. Once a class is
- selected in the GUI it is loaded and, the JavaWebStart class loader
- will guarantee that it is available. </para>
- </listitem>
-
- <listitem>
- <para> The scope of the modules. </para>
- <para> Modules are always enabled and disabled on a per-application
- (per jvm) basis and not on a per-project or per-frame basis.
- </para>
- </listitem>
- </itemizedlist> </para>
- </sect2>
- </sect1>
-
- <sect1 id="ocl">
- <title>OCL</title>
- <indexterm>
- <primary>OCL</primary>
- </indexterm>
- <indexterm>
- <primary>Constraints</primary>
- </indexterm>
-
- <para> Purpose - To allow for editing of strings in the OCL language. </para>
- <para> The OCL is located in <classname>org.argouml.ocl</classname>.
- </para>
- <para> The OCL is a Layer 3 subsystem. See <xref
- linkend="loadable_subsystems"></xref>. </para>
- <para> The OCL editor GUI interface is
- <classname>org.argouml.uml.ui.TabConstraints</classname> (shown in
- the bottom right hand panel - details panel). </para>
- <para> <classname>org.argouml.ocl.ArgoFacade</classname> adapts the
- <classname>tudresden.ocl.gui.OCLEditor</classname> for ArgoUML.
- There are some other helper classes in
- <classname>org.argouml.ocl</classname>, with names beginning with OCL
- but they are used for other purposes. Historically GEF uses OCL as a kind of
- template language to convert the UML diagrams to pgml(and back again), it
- doesn't have anything to do with OCL constraints in your UML model. </para>
- <para> <classname>ArgoFacade</classname> is reused by
- <classname>GeneratorJava</classname> and
- <classname>TabConstraints</classname>.
-</para>
- <para>
- <indexterm>
- <primary>Dresden OCL Toolkit</primary>
- </indexterm>
-Currently this
-subsystem is more or less only Dresden OCL Toolkit and adaptation.
-</para>
- <para> Because of a problem with the interpretation of the UML specification
- and the OCL specification, the implementation of constraints in ArgoUML is
- only possible for Classes, Interfaces and Features (Attributes and
- Operations). See <ulink
- url="http://argouml.tigris.org/issues/show_bug.cgi?id=1805">
- Issue 1805 </ulink>. </para>
- </sect1>
-
-</chapter>
-
-<!-- Local stuff for Emacs - please do not delete
-
-Local Variables:
-mode: xml
-sgml-doctype: "cookbook.xml"
-sgml-parent-document: ("cookbook.xml" "chapter" nil)
-sgml-validate-command: "nsgmls -wxml -sv ../docbook-setup/xml.dcl \
-cookbook.xml"
-indent-tabs-mode: nil
-End:
+ &subsystemnotation;-->
+
+ <section xml:id="reverseengineering">
+ <title>Reverse Engineering Subsystem</title>
+
+ <indexterm>
+ <primary>Reverse Engineering</primary>
+ </indexterm>
+
+ <para>Purpose - Provide a central registration point for language reverse engineering modules as well as common reverse engineering methods for all languages. </para>
+ <para>The Reverse Engineering subsystem is located in <classname>org.argouml.uml.reveng</classname>. </para>
+ <para>The Reverse Engineering Subsystem is a Control subsystem. See <xref xlink:href="view_control_subsystems" />. </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>All language reverse engineering modules must implement the <classname>org.argouml.uml.reveng.ImportInterface</classname> interface. </para>
+ </listitem>
+ <listitem>
+ <para>All modules must implement the <interfacename>org.argouml.moduleloader.ModuleInterface</interfacename> interface. </para>
+ </listitem>
+ <listitem>
+ <para>At initialization time, each language registers themselves using <classname>org.argouml.uml.reveng.ImportManager</classname>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <section>
+ <title>Common import code</title>
+
+ <para>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).</para>
+ </section>
+
+ <section>
+ <title>Diagram layout algorithms</title>
+
+ <para>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: </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/examples/example1.gif" format="GIF"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>In the next diagram, a link goes to an object that is not in the row above: </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/examples/example2.gif" format="GIF"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>In this case, insert virtual objects which are linked to the actual target and link to them: </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/examples/example3.gif" format="GIF"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>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: </para>
+ <blockquote>
+ <para>A B C : rank 0 </para>
+ <para>D E F : rank 1 </para>
+ </blockquote>
+
+ <para>We give the super-classes an index in their rank (assuming that theyare already sorted): </para>
+ <blockquote>
+ <para>A:0, B:1, C:2 </para>
+ </blockquote>
+
+ <para>D, E, F have the following links (A, B, C could be interfaces, so I allow links to multiple super-classes here): </para>
+ <blockquote>
+ <para>D -> C </para>
+ <para>E -> A and C </para>
+ <para>F -> A and B </para>
+ </blockquote>
+
+ <para>Compute the average value of the indexes: </para>
+ <blockquote>
+ <para>D = 2 (C has index 2 / 1 link) </para>
+ <para>E = 0 + 2 / 2 = 1 (A=0, C=2 divide by 2 links) </para>
+ <para>F = 0 + 1 / 2 = 0.5 (A=0, B=1, 2 links) </para>
+ </blockquote>
+
+ <para>Then sort the subclasses by that value: </para>
+ <blockquote>
+ <para>F(is 0.5), E(is 1), D(is 2) </para>
+ </blockquote>
+
+ <para>So the placement is: </para>
+ <blockquote>
+ <para>A B C </para>
+ <para>(here are the links, but I can hardly paint them as ASCIIs) </para>
+ <para>F E D </para>
+ </blockquote>
+ </section>
+ </section>
+
+ <section xml:id="codegeneration">
+ <title>Code Generation Subsystem</title>
+
+ <indexterm>
+ <primary>Code Generation</primary>
+ </indexterm>
+
+ <para>Purpose: Point where the different languages register that they know how to do code generation and common functions for all languages. </para>
+ <para>The Code Generation is located in <package>org.argouml.language</package>. </para>
+ <para>The Code Generation subsystem is a Control subsystem. See <xref xlink:href="view_control_subsystems"/>. </para>
+ <para>The code to generate various languages that is supplied with ArgoUML is found in sub-packages of <classname>org.argouml.language</classname>. In the case of languages other than Java, these classes will come from independent projects and be package separately even though they share this package name space.
+ <warning><para>There is a potential conflict here if two separately language implementations use this name space in an uncoordinated fashion (e.g. two Ruby implementations using org.argouml.language.ruby).</para> </warning>
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>All source language code generators must implement the <interfacename>org.argouml.uml.generator.CodeGenerator</interfacename> interface. </para>
+ </listitem>
+ <listitem>
+ <para>All modules must implement the <interfacename>org.argouml.moduleloader.ModuleInterface</interfacename> interface. </para>
+ </listitem>
+ <listitem>
+ <para>At initialization time, each language registers themselves using <classname>org.argouml.uml.generator.GeneratorManager</classname>. </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section xml:id="java">
+ <title>Java - Code Generation and Reverse Engineering</title>
+
+ <indexterm>
+ <primary>Reverse Engineering</primary>
+ <secondary>Java</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Code generation</primary>
+ <secondary>Java</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Round-trip Engineering</primary>
+ <secondary>Java</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Java</primary>
+ </indexterm>
+
+ <para>Purpose - two purposes: to allow the model to be converted into java code and updated either in java or in the model; to allow some java code to be converted into a model. </para>
+ <para>The java things are located in <classname>org.argouml.language.java</classname>. </para>
+ <para>The Java subsystem is a Loadable subsystem. See <xref xlink:href="loadable_subsystems" />. </para>
+
+ <section xml:id="howdoi_reverse">
+ <title>How do I�</title>
+
+ <para>â¦</para>
+ </section>
+
+ <section>
+ <title>Which sources are involved?</title>
+
+ <para>The package <package>org.argouml.uml.reveng</package> 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. </para>
+ <para>The package <package>org.argouml.uml.reveng.java</package> holds the Java specific parts of the current RE code. C++ RE might go to <package>org.argouml.uml.reveng.cc</package>, or so⦠</para>
+ </section>
+
+ <section>
+ <title>How is the grammar of the target language implemented?</title>
+
+ <para>It is an <productname>Antlr</productname> (<link xlink:href="http://www.antlr.org"> http://www.antlr.org</link>) 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.</para>
+ </section>
+
+ <section>
+ <title>Which model/diagram elements are generated?</title>
+
+ <para>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. </para>
+ </section>
+ </section>
+
+ <section xml:id="otherlanguages">
+ <title>Other source languages (C++, Python, etc)</title>
+
+ <para>Each source language supported by ArgoUML has its own subsystem. They are each different in level of support and implementation language. All languages except for Java are in their own dedicated Tigris project with separate web site, mailing lists, source repository, etc. For example, the C++ plugin is located <link xlink:href="http://argouml-cpp.tigris.org/"> here</link>. </para>
+ <para>Currently C++ has no reverse engineering but only code generation (and a very simple one at that). The Java classfile module has only reverse engineering. </para>
+ <para>There are stubs/shells for many different languages, but the following are mature enough to be distributed with ArgoUML: C++ (Cpp), C# (Csharp), classfile, IDL, and PHP. Others at various stages of development include: Python, Ruby, and SQL.</para>
+
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/cookbook/Languages.gif" format="GIF"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ </section>
+
+ <section xml:id="guiframework">
+ <title>The GUI</title>
+
+ <indexterm>
+ <primary>GUI Framework</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Details Panel</primary>
+ </indexterm>
+
+ <para>Purpose - Provide an infrastructure with menus, tabs and panes available for the other subsystems to fill with actions and contents. </para>
+ <para>This subsystem has no knowledge of UML, Critics, Diagrams, or Model. </para>
+ <para>The GUI Framework is located in <classname>org.argouml.ui</classname>. </para>
+ <para>This is implemented directly on top of Swing and Java. </para>
+ <para>The GUI framework provides the following options
+ <itemizedlist>
+ <listitem>
+ <para>The menu with actions</para>
+ </listitem>
+ <listitem>
+ <para>The tool-bar with actions</para>
+ </listitem>
+ <listitem>
+ <para>The Explorer (formerly called Navigator)</para>
+ <para>Located in <classname>org.argouml.ui.explorer</classname>. Contains the tree structure with configurable perspectives. </para>
+ </listitem>
+ <listitem>
+ <para>Tabbed pane</para>
+ <para>Could contain several different panes. </para>
+ </listitem>
+ <listitem>
+ <para>The TargetManager</para>
+ <para>See <xref xlink:href="targetmanager" />.</para>
+ </listitem>
+ <listitem>
+ <para>The Settings Tab</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>The GUI subsystem does not contain any knowledge of what is going to be put into the different panes but it has knowledge of parts of the semantics of those components. </para>
+ <para>The components that wants to be placed into any of these register with the GUI subsystem using the appropriate method in <classname>org.argouml.ui.GUI</classname>. </para>
+ <para>Other subsystems that supply their own user interface, may be split into 2 packages, e.g. <classname>org.argouml.some-subsystem</classname> and <classname>org.argouml.some-subsystem.ui</classname>. In such case the following figure indicates the allowed dependencies: </para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/cookbook/subsystem-ui.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+
+ <section xml:id="targetmanager">
+ <title>The TargetManager</title>
+
+ <para>Located in <classname>org.argouml.ui.targetmanager</classname>. </para>
+ <para>The purpose of the targetmanager is to have a central spot to manage the list of current targets. </para>
+ <para>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.</para>
+ <para>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. </para>
+ <para>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. </para>
+ <para>Thanks to the architecture of ArgoUML of Modelelements and Figs, one rule has been decided upon<!-- (by [email protected] ) -->: <emphasis>The list of targets shall not contain any Fig that has an owner</emphasis>. Instead, the owner is enlisted. </para>
+ <para>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. </para>
+ <para>Via an event mechanism this manager makes sure that all objects interested in knowing whether the selection changed are acknowledged. </para>
+ <para>The TargetManager does not depend on the <classname>org.argouml.ui</classname> package, nor any of its sub-packages. Hence, it can be used by all of these to modify the target, or get it. </para>
+ <para>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. </para>
+ </section>
+ </section>
+
+ <section xml:id="application">
+ <title>Application</title>
+
+ <para>Purpose : to provide the entry point when starting ArgoUML. Responsibility to start the ball rolling. </para>
+ <para>The Application is located in <classname>org.argouml.application</classname>. </para>
+ <para>The entry point is called <classname>org.argouml.application.Main</classname>. </para>
+
+ <section>
+ <title>What is loaded/initialized?</title>
+
+ <para>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. </para>
+ <para>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. </para>
+ </section>
+
+ <section>
+ <title>Details pane</title>
+
+ <para>The Details pane contains several tabs: Property Panels (See <xref xlink:href="propertypanels" />, Critics explanations and wizards (belonging to the Critics subsystem) (See <xref xlink:href="critics"/>), Documentation, Style, Source, Constraints (OCL constraints on the current object. See <xref xlink:href="ocl" />), and Tagged values.</para>
+ <warning>
+ <para>It is not clear in what subsystem Documentation, Style, Source, and Tagged values belong. </para>
+ </warning>
+
+ <section xml:id="howdoi_detailspanel">
+ <title>How do I�</title>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>â¦add a tab in the Details Panel?</para>
+ <para>Create your <classname>TabXXX</classname> class in <classname>org.argouml.uml.ui</classname> by copying from another <filename>TabYYY.java</filename> (e.g. <classname>TabSrc</classname>, <classname>TabStyle</classname>). Then register your <classname>TabXXX</classname> in <filename>org/argouml/argo.ini</filename> by adding a line giving the compass point to place the tab. Like - <programlisting> south: TabXXX </programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>â¦remove a tab from the Details Panel?</para>
+ <para>Remove the line for the tab from <filename>org/argouml/argo.ini</filename>. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ </section>
+ </section>
+
+ <section xml:id="help">
+ <title>Help System</title>
+
+ <indexterm>
+ <primary>Help system</primary>
+ </indexterm>
+
+ <para>Purpose - to provide the menu actions that start the help and other documentation. To provide infrastructure that makes context sensitive help possible. </para>
+ <para>The Help System is not yet implemented. </para>
+ <para>The Help System will be located in <classname>org.argouml.help</classname>. </para>
+ <para>The Help System is a Model subsystem. See <xref xlink:href="model_subsystems"/>. <!-- TODO: It however violates the layer concept by providing menu items that fit into the GUI Framework. --></para>
+ <para>Javahelp or some other help function will probably be used. </para>
+ </section>
+
+ <!--
+ &subsysteminternationalization;
+ &subsystemlogging;
+ -->
+
+ <section xml:id="taskmgmt">
+ <title>TaskManagement</title>
--->
\ No newline at end of file
+ <para>Purpose - Everything related to the concept of Task, Job or Request. </para>
+ <para>The TaskManagement is an infrastructure or low-level subsystem. See <xref xlink:href="infrastructure_subsystems"/>. Currently, this subsystem contains the ProgressMonitor. </para>
+ <para>The ProgressMonitor is explained by the following: SomethingA needs a long running service from SomethingB. So, SomethingA decides to ask for it in a different Thread of execution and to monitor the progress of the task in its main thread. The reason why it monitors the progress could be because it wants to show feedback to the user via the GUI, but, it could also be in order to decide that if there is no progress, it should give up by interrupting its other Thread. </para>
+ </section>
+
+ <section xml:id="configuration">
+ <title>Configuration</title>
+
+ <para>Purpose - Store and retrieve all configurable aspects of the ArgoUML application. </para>
+ <para>The Configuration subsystem is an infrastructure or low-level subsystem. See <xref xlink:href="infrastructure_subsystems"/>. It handles all configuration that is stored in the user's home directory in the file named "argo.user.properties". </para>
+ <para>Not inside the scope of this package are all the configuration settings that are stored in the project, i.e. in the .zargo file. </para>
+ </section>
+
+ <section xml:id="todoitems">
+ <title>To Do items</title>
+
+ <indexterm>
+ <primary>To Do Items</primary>
+ </indexterm>
+
+ <para>Purpose - To keep track of the To do items. Items are generated and removed automatically by the critics. They could also be created by other means. </para>
+ <para>The To Do items are located in <classname>org.argouml.cognitive.ToDoItem</classname></para>
+ <warning><para>This is a set of classes in the Cognitive subsystem, not a subsystem of its own.</para></warning>
+ <para>The To do items is a Model subsystem. See <xref xlink:href="model_subsystems"/>. </para>
+ </section>
+
+ <section xml:id="explorer">
+ <title>Explorer</title>
+
+ <indexterm>
+ <primary>Explorer</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Object Explorer</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Navigator Tree</primary>
+ </indexterm>
+
+ <para>Purpose - to provide tree views of the model elements, diagrams and other objects. Note: the Explorer used to be called the Navigator. </para>
+ <para>The Explorer is located in <classname>org.argouml.ui.explorer</classname> and sub-packages. </para>
+ <para>The Explorer is a Layer 2 subsystem. See <xref xlink:href="view_control_subsystems"/>. </para>
+
+ <section>
+ <title>Requirements</title>
+
+ <para>The Explorer must react to user and application events. </para>
+ <para>User events include
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>R1: selection of a node, which must notify the other views to make the same selection. </para>
+ </listitem>
+ <listitem>
+ <para>R2: right click on a node, which brings up a pop-up menu. </para>
+ </listitem>
+ <listitem>
+ <para>R3: selection of another perspective in the Combo box, which must change the explorer to that perspective. A perspective provides a different view of the model that will focus on one or other part of the model. </para>
+ </listitem>
+ <listitem>
+ <para>R4: node expansion and collapse. </para>
+ </listitem>
+ <listitem>
+ <para>R5: It is possible to drag name-space nodes on to other name-space nodes. Dropping a name-space node onto another, will, if the destination name-space is a valid one, update the explorer and model. </para>
+ </listitem>
+ <listitem>
+ <para>R6: sorting of nodes with a particular Ordering. [an ordering is a comparator that orders child nodes in the explorer, e.g. by name and/or type]. </para>
+ </listitem>
+ <listitem>
+ <para>R7: copy diagram to clipboard functionality for windows/java5 users. </para>
+ </listitem>
+ <listitem>
+ <para>R8: tool-tip showing node name and type. </para>
+ </listitem>
+ <listitem>
+ <para>R9: standard multiple discontinuous selection with mouse and keyboard. </para>
+ </listitem>
+ <listitem>
+ <para>R10: the user can configure the perspectives using a dialog. Perspectives can be added, deleted, renamed, reordered and duplicated. Perspective rules can be added and removed from a perspective. The changes are saved to the user properties. If there are user perspectives when ArgoUML starts, it loads these, otherwise it loads a default set of perspectives. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>Application events include
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>R11: change in selection in another view, any relevant rows to be highlighted. </para>
+ </listitem>
+ <listitem>
+ <para>R12: the UML model changes, the tree must update to reflect additions/deletions and name changes in the model. </para>
+ </listitem>
+ <listitem>
+ <para>R13: change of project, the tree must update. the root node should be expanded with the default diagram selected. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section>
+ <title>Public APIs and SPIs</title>
+
+ <para>The Explorer Subsystem provides/will provide the following APIs:
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>API1: Addition / Removal of a Perspective from the PerspectiveManager. Status: implemented </para>
+ </listitem>
+ <listitem>
+ <para>API2: Addition / Removal of a Perspective Rule from a Perspective. Status: implemented </para>
+ </listitem>
+ <listitem>
+ <para>API3: Selection of the Perspective to be displayed by the Explorer. Status: not implemented </para>
+ </listitem>
+ <listitem>
+ <para>API4: Selection of Ordering for Explorer nodes. [an Ordering is a comparator that orders child nodes in the Explorer] Status: not implemented </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>The Explorer Subsystem provides/will provide the following SPIs:
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>SPI1: Configurable Node pop-up menu. Status: not implemented </para>
+ </listitem>
+ <listitem>
+ <para>SPI2: New PerspectiveRules can be defined and registered with the 'library' of available rules. Status: not implemented </para>
+ </listitem>
+ <listitem>
+ <para>SPI3: New Orderings can be defined and registered with the available orderings. [an ordering is a comparator that orders child nodes in the explorer] Status: not implemented </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>The APIs collectively represent the Explorer subsystem facade and the SPIs represent plug-ins. </para>
+ </section>
+
+ <section xml:id="explorer-implementation-details">
+ <title>Details of the Explorer Implementation</title>
+
+ <para>The Explorer is currently shown in the Explorer Pane (<classname>org.argouml.ui.NavigatorPane</classname>) - the upper left hand pane of ArgoUML. </para>
+ <para>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. </para>
+ <para>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. </para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/cookbook/explorer-architecture.gif" format="GIF"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+
+ <para>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.
+ <orderedlist spacing="compact">
+ <listitem>
+ <para>The JTree (org.argouml.ui.explorer.ExplorerTree) has been customized to maintain consistent selection state with the other model views. It provides a pop up menu (ExplorerPopup) for performing actions on specific model elements. There is specific functionality in DnDExplorerTree for Drag and drop, and in ExportExplorer for copy diagram to clipboard. </para>
+ </listitem>
+ <listitem>
+ <para>The TreeModel is a customized DefaultTreeModel that listens to changes in the UML model. The JTree builds the tree model as the user expands nodes, this minimizes the size of the model to those part that the user is interested in. The TreeModel contains custom DefaultMutableTreeNodes, ExplorerTreeNodes, that maintain their own order on child nodes; this will typically be an alphabetical order on the model element names. However, it could be enhanced to include more powerful orders like total subtree size. </para>
+ </listitem>
+ <listitem>
+ <para>The model uses the third part of the Explorer design, PerspectiveRules, to add child nodes to the leaves of the tree. The structure of the tree is wholly dependent on the collection of PerspectiveRules that together provide a specialized view of the UML model. This is very flexible and extensible. The org.argouml.ui.explorer.rules package contains a default set of PerspectiveRules. </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ <para>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 <classname>org.argouml.uml.ui.UMLTreeRenderer</classname> (for the Icon), and the text is produced in the <methodname>convertValueToText(â¦)</methodname> method in <classname>org.argouml.ui.explorer.ExplorerTree</classname>. </para>
+ </section>
+
+ <section>
+ <title>How do I�</title>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>â¦add another perspective?</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The perspectives can be configured using the <classname>org.argouml.ui.explorer.PerspectiveConfigurator</classname> by the User. The changes to the pre-defined built-in defaults are stored in the <filename>argo.user.properties</filename> file. </para>
+ </listitem>
+ <listitem>
+ <para>If you want to do this as part of an extension to ArgoUML then you should use (see above) APIs 1,2 and 3, and SPI 2. The functions needed are present in the <classname>PerspectiveManager</classname>. </para>
+ </listitem>
+ </itemizedlist>
+
+ </listitem>
+
+ <listitem>
+ <para>â¦improve the PopUp menu?</para>
+ <para>There is no way of doing this currently without modifying the core of ArgoUML. You could use SPI1 when it gets implemented. </para>
+ </listitem>
+
+ <listitem>
+ <para>â¦extend the Explorer in other ways?</para>
+ <para>The best way is to use the above APIs/SPIs; if they are not implemented then it would be best to implement them and feedback your improvements to the ArgoUML project so that your code works on a recognized public API that will be maintained in the future. </para>
+ </listitem>
+
+ <listitem>
+ <para>â¦add new rules for new model elements?</para>
+ <para>You should create a GoRule/PerspectiveRule in <address>org/argouml/ui/explorer/rules</address>. There are plenty of examples to look at. The important things to get right is of course that: </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>you return the right children</para>
+ </listitem>
+ <listitem>
+ <para>return the objects that the TreeModel must listen to to know when to update the node (and the list of immediate children) After that you must register your GoRule in org/argouml/ui/explorer/PerspectiveManager </para>
+ </listitem>
+ <listitem>
+ <para>add it to the list in loadRules()</para>
+ </listitem>
+ <listitem>
+ <para>perhaps add it to some of the default perspectives in oldLoadDefaultPerspectives(), I guess And then I think it should just be a matter of recompiling and possibly switching to the perspective you added your rule to. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>â¦tell the explorer to refresh?</para>
+ <para>You are not supposed to. The TreeModel is supposed to listen to events and refresh affected parts. And this is where the lack of events for adding diagrams creates a problem. </para>
+ <para>Obviously it would be possible to add an operation somewhere to revalidate the expanded parts of the Explorer, but I'm not aware of the existence of such an operation today. </para>
+ </listitem>
+
+ <listitem>
+ <para>â¦navigate programmatically to a certain explorer element so that its path is exploded? </para>
+ <para>In general you can't. The Explorer tree is lazy in that it only explores the parts of the tree that the user has opened. And since the GoRules are general navigating to them would require a complete tree search. Which is also complicated by the fact that the answer is not unique and there can be branches with infinite depth. </para>
+ <para>In reality it would be possible to create an algorithm to search out one occurrence of an element (since the model only contains finitely many elements and I assume that no-one will add go rules that add branches of infinite length that does not infinitely often contain elements from the model), but I don't think anyone has don't it. Obviously finding all occurrences cannot be done. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ </section>
+
+ <section xml:id="moduleloader">
+ <title>Module loader</title>
+
+ <indexterm>
+ <primary>Module loader</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Pluggable interface</primary>
+ </indexterm>
+
+ <para>Purpose - to provide the mechanisms to load (and unload) the auxiliary modules. </para>
+ <para>The Module loader is located in <classname>org.argouml.moduleloader</classname>. </para>
+ <para>It is the modules' responsibility to connect and register to the subsystem or subsystems it is going to work with using that subsystem's API, Facade, or Plug-in interface. </para>
+ <para>A previous implemention of the module loader was located in <classname>org.argouml.application.modules.ModuleLoader</classname> with interfaces (Pluggable) in <classname>org.argouml.application.api</classname>, but it has been replaced by the interface described here. </para>
+ <para>For details on how to build a module see <xref xlink:href="modules_and_plugins"/>. </para>
+
+ <section>
+ <title>What the ModuleLoader does</title>
+
+ <para>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. </para>
+ <para>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?]</para>
+ </section>
+
+ <section xml:id="design-module-loader">
+ <title>Design of the Module Loader</title>
+
+ <para>Design:
+ <itemizedlist>
+ <listitem>
+ <para>We use a Loadable Proxy Pattern(?) for the modules. </para>
+ </listitem>
+ <listitem>
+ <para>Each module can be enabled and disabled individually. Dependencies between modules are allowed although not yet handled gracefully. </para>
+ </listitem>
+ <listitem>
+ <para>Each module is required to have one (1) class that implements <classname>ModuleInterface</classname>. That class (and all other classes that constitute the module) needs to be made available for some class loader, either by including it in the classpath or by letting the module loader hunt for it. </para>
+ </listitem>
+ <listitem>
+ <para>The modules are allowed to use all the APIs available from all the subsystems within ArgoUML and from other modules. </para>
+ <para>This is a big improvement over the old module loader in that: <itemizedlist>
+ <listitem>
+ <para>We use the same APIs for the modules that we use within ArgoUML meaning that we implement at document it only once. This replaces the Pluggable class at every point where ArgoUML can be augmented. </para>
+ </listitem>
+ <listitem>
+ <para>We can have the module have different classes to register at different parts of ArgoUML. </para>
+ </listitem>
+ <listitem>
+ <para>We can have dynamic registrations that the module add and remove over time depending on some criteria that the module decides. </para>
+ </listitem>
+ <listitem>
+ <para>We don't need to search through all modules at every possible point where ArgoUML can be augmented. </para>
+ </listitem>
+ </itemizedlist> Just as in the old solution, whenever a module needs to do something to ArgoUML, there needs to be implemented an API, possibly with registration/deregistration and callbacks. </para>
+ </listitem>
+ <listitem>
+ <para>All modules that can be found are examined at startup. They can be enabled and disabled individually from a special available modules window but have a default state that applies if the user hasn't taken action. Currently the default state is "enabled". </para>
+ </listitem>
+ <listitem>
+ <para>Dependency between modules! </para>
+ <para>If a module cannot be enabled because some other module needs to be enabled first or because some part of ArgoUML needs to be initialized first this is a problem. This is because the initial implementation is such that we have no register of dependencies. </para>
+ <para>The solution suggested is that the module loader persists in its attempts to enable a module so that the order among the modules is not important. For this to work the modules needs to signal when they fail. This is done by returning false or throwing a Exception from the module enabling method. </para>
+ <para>The module loader also provides an API that the well-behaving modules can use to test if the modules they depend on are enabled. The less well-behaving module can just throw an exception when they fail to enable themselves properly. </para>
+ <para>If a module cannot be disabled, because some other module depends on it then this is signaled by returning false from the disabling method. </para>
+ </listitem>
+ <listitem>
+ <para>Where modules are loaded from? </para>
+ <para>The modules are loaded from the same places as in the old module loader. They can be internally i.e. available in the core jar file of ArgoUML, from the <filename class="directory"> ext</filename> directory, or if running from JavaWebStart, they can be downloaded from the site. </para>
+ <para>To reduce the complexity of the downloads, let's use it in the simplest possible way: organize each module in a package and a jar file, have the jnlp-file list that jar file as a part and a package entry listing the classes, have a file listing optional classes and a GUI that allows the user to download them. Once a class is selected in the GUI it is loaded and, the JavaWebStart class loader will guarantee that it is available. </para>
+ </listitem>
+ <listitem>
+ <para>The scope of the modules.</para>
+ <para>Modules are always enabled and disabled on a per-application (per jvm) basis and not on a per-project or per-frame basis. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ </section>
+
+ <section xml:id="ocl">
+ <title>OCL</title>
+
+ <indexterm>
+ <primary>OCL</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Constraints</primary>
+ </indexterm>
+
+ <para>Purpose - To allow for editing of strings in the OCL language. </para>
+ <para>The OCL is located in <classname>org.argouml.ocl</classname>. </para>
+ <para>The OCL is a Layer 3 subsystem. See <xref xlink:href="loadable_subsystems"/>. </para>
+ <para>The OCL editor GUI interface is <interfacename>org.argouml.uml.ui.TabConstraints</interfacename> (shown in the bottom right hand panel - details panel). </para>
+ <para><classname>org.argouml.ocl.ArgoFacade</classname> adapts the <classname>tudresden.ocl.gui.OCLEditor</classname> for ArgoUML. There are some other helper classes in <classname>org.argouml.ocl</classname>, with names beginning with OCL but they are used for other purposes. Historically, GEF uses OCL as a kind of template language to convert the UML diagrams to pgml(and back again), it doesn't have anything to do with OCL constraints in your UML model. </para>
+ <para><classname>ArgoFacade</classname> is reused by <classname>GeneratorJava</classname> and <classname>TabConstraints</classname>. </para>
+ <para>
+ <indexterm>
+ <primary>Dresden OCL Toolkit</primary>
+ </indexterm>
+
+ Currently this subsystem is more or less only Dresden OCL Toolkit and adaptation.
+ </para>
+
+ <para>Because of a problem with the interpretation of the UML specification and the OCL specification, the implementation of constraints in ArgoUML is only possible for Classes, Interfaces and Features (Attributes and Operations). See <link xlink:href="/issues/show_bug.cgi?id=1805">Issue 1805</link>. </para>
+ </section>
+</chapter> <!-- Local stuff for Emacs - please do not delete Local Variables: mode: xml sgml-doctype: "cookbook.xml" sgml-parent-document: ("cookbook.xml" "chapter" nil) sgml-validate-command: "nsgmls -wxml -sv ../docbook-setup/xml.dcl \ cookbook.xml" indent-tabs-mode: nil End: -->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/introduction.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/introduction.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/introduction.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/introduction.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/introduction.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/introduction.xml 2008-01-15 19:22:21-0800
@@ -1,391 +1,199 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
-// Copyright (c) 1996-2006 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.
+ // Copyright (c) 1996-2006 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.
-->
-<chapter id="introduction">
+<chapter
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xml:id="introduction">
+
<title>Introduction</title>
- <sect1 id="thanks">
+
+ <section xml:id="thanks">
<title>Thanks</title>
- <para> 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! </para>
- </sect1>
+ <para>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! </para>
+ </section>
- <sect1 id="project">
+ <section xml:id="project">
<title>About the project</title>
- <para>
-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!
-</para>
- <para>
-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
-<ulink url="mailto:[email protected] ">dev mailing list</ulink>!
-</para>
- <para>
-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.
-</para>
- </sect1>
+ <para>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! </para>
+ <para>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 <link
+ xlink:href="mailto:[email protected] ">dev mailing list</link>! </para>
+ <para>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. </para>
+ </section>
- <sect1 id="contributing">
+ <section xml:id="contributing">
<title>How to contribute</title>
- <para> You can help, there are big tasks and small tasks waiting for you.
- </para>
- <para> 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.
+ <para>You can help, there are big tasks and small tasks waiting for you. </para>
+ <para>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.
<orderedlist numeration="arabic">
<listitem>
<para>Use ArgoUML.</para>
</listitem>
<listitem>
- <para>
-Report bugs & suggest enhancements.
-</para>
- <para>
-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.
-</para>
-
- <para>
-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.
-</para>
-
- <para>
-To help the developers prioritise work on bugs and enhancements,
-vote for the ones that you really care about.
-</para>
-
- <para>
-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.
-</para>
+ <para>Report bugs & suggest enhancements. </para>
+ <para>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. </para>
+ <para>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. </para>
+ <para>To help the developers prioritise work on bugs and enhancements, vote for the ones that you really care about. </para>
+ <para>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. </para>
</listitem>
-
<listitem>
- <para>
-Subscribe to some of the users' mailing lists.
-</para>
- <para>
-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.
-</para>
-
- <para>
-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 [email protected] , is.
-</para>
-
- <para>
-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.
-</para>
+ <para>Subscribe to some of the users' mailing lists. </para>
+ <para>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. </para>
+ <para>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 [email protected] , is. </para>
+ <para>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. </para>
</listitem>
-
<listitem>
<para>Apply for an Observer role.</para>
- <para>
-This shows that you are committed to the project and also allows
-you to comment on issues.
-</para>
+ <para>This shows that you are committed to the project and also allows you to comment on issues. </para>
</listitem>
<listitem>
- <para> Familiarize yourself with the project and how we work. </para>
- <para> Suggestion on how to go about this:
- <orderedlist numeration="loweralpha">
- <listitem>
- <para> Read through most of the User manual and install and run
- the latest version of ArgoUML. </para>
- </listitem>
- <listitem>
- <para>Subscribe to the issues list.</para>
- <para> 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!) </para>
- </listitem>
- <listitem>
- <para>
-Subscribe to the commits mailing list
-of the project that you are interested in.
-</para>
- <para>
-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.)
-</para>
- </listitem>
- <listitem>
- <para>
-Read the process part of the Developers Cookbook
-at <xref linkend="processes"/>.
-</para>
- <para> This will give you the idea of how the ArgoUML project
- attempts to release with good quality and especially how we
- use Issuezilla. </para>
- </listitem>
- <listitem>
- <para>Get the Observer role granted.</para>
-
- <para>
-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.
-</para>
-
- <para>
-From this point on you can comment on bugs yourself directly in Issuezilla.
-</para>
-
- <para> You can also verify issues according to the verification
- process (see <xref linkend="verify_resolved_fixed"/>).
-</para>
- <para> 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. </para>
- <para> This is also a very low-commitment level task that could
- be completed in a couple of minutes (depending on your choice
- of issue). </para>
- </listitem>
- <listitem>
- <para>Read the rest of the Developers Cookbook.</para>
- <para> There is a lot of stuff discussed in here that is
- interesting for your understanding of the project and the
- code. </para>
- </listitem>
- <listitem>
- <para>Check out the source from subversion and build.</para>
- </listitem>
- </orderedlist> </para>
-
+ <para>Familiarize yourself with the project and how we work. </para>
+ <para>Suggestion on how to go about this: <orderedlist numeration="loweralpha">
+ <listitem>
+ <para>Read through most of the User manual and install and run the latest version of ArgoUML. </para>
+ </listitem>
+ <listitem>
+ <para>Subscribe to the issues list.</para>
+ <para>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!) </para>
+ </listitem>
+ <listitem>
+ <para>Subscribe to the commits mailing list of the project that you are interested in. </para>
+ <para>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.) </para>
+ </listitem>
+ <listitem>
+ <para>Read the process part of the Developers Cookbook at <xref
+ xlink:href="processes" />. </para>
+ <para>This will give you the idea of how the ArgoUML project attempts to release with good quality and especially how we use Issuezilla. </para>
+ </listitem>
+ <listitem>
+ <para>Get the Observer role granted.</para>
+ <para>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. </para>
+ <para>From this on you can comment on bugs yourself directly in Issuezilla. </para>
+ <para>You can also verify issues according to the verification process (see <xref
+ xlink:href="verify_resolved_fixed" />). </para>
+ <para>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. </para>
+ <para>This is also a very low-commitment level task that could be completed in a couple of minutes (depending on your choice of issue). </para>
+ </listitem>
+ <listitem>
+ <para>Read the rest of the Developers Cookbook.</para>
+ <para>There is a lot of stuff discussed in here that is interesting for your understanding of the project and the code. </para>
+ </listitem>
+ <listitem>
+ <para>Check out the source from subversion and build.</para>
+ </listitem>
+ </orderedlist>
+ </para>
</listitem>
-
<listitem>
- <para>
-Subscribe to some of the dev mailing lists.
-</para>
- <para>
-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.
-</para>
-
- <para>
-The purpose of this is to see what the developers are discussing
-in the project.
-</para>
-
- <para>
-Monitor the discussions and as soon as you see something
-discussed where you have an opinion, jump right in!
-</para>
+ <para>Subscribe to some of the dev mailing lists. </para>
+ <para>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. </para>
+ <para>The purpose of this is to see what the developers are discussing in the project. </para>
+ <para>Monitor the discussions and as soon as you see something discussed where you have an opinion, jump right in! </para>
</listitem>
-
<listitem>
<para>Familiarize yourself with the code.</para>
- <para>For this a good knowledge of Java is more or less a prerequisite.
+ <para>For this a good knowledge of Java is more or less a prerequisite. </para>
+ <para>Suggestion on how to go about this: <orderedlist numeration="loweralpha">
+ <listitem>
+ <para>Take active part in the discussions on the dev-list. </para>
+ </listitem>
+ <listitem>
+ <para>Solve issues registered in Issuezilla or fix other things that you want to pursue. </para>
+ </listitem>
+ <listitem>
+ <para>Convince someone to commit your changes. </para>
+ <para>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. </para>
+ </listitem>
+ <listitem>
+ <para>Repeat. </para>
+ <para>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. </para>
+ </listitem>
+ </orderedlist>
</para>
- <para> Suggestion on how to go about this:
- <orderedlist numeration="loweralpha">
- <listitem>
- <para>
-Take active part in the discussions on the dev-list.
-</para>
- </listitem>
- <listitem>
- <para>
-Solve issues registered in Issuezilla or fix other things that you
-want to pursue.
-</para>
- </listitem>
- <listitem>
- <para>
-Convince someone to commit your changes.
-</para>
- <para>
-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.
-</para>
- </listitem>
- <listitem>
- <para> Repeat. </para>
- <para>
-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.
-</para>
- </listitem>
- </orderedlist>
-</para>
</listitem>
<listitem>
- <para>
-Apply for a Developer role in the project where you want to contribute.
-</para>
- <para>
-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.
-</para>
- <para>
-This role is granted by the Project leader after he is convinced
-that you have learned enough about the project with regard to:
-</para>
+ <para>Apply for a Developer role in the project where you want to contribute. </para>
+ <para>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. </para>
+ <para>This role is granted by the Project leader after he is convinced that you have learned the enough about the project w.r.t.: </para>
<itemizedlist>
<listitem>
- <para>
-Understanding and accepting the goals.
-</para>
+ <para>Understanding and accepting the goals. </para>
</listitem>
<listitem>
- <para>
-Understanding where we are in the development process.
-</para>
+ <para>Understanding where we are in the development process. </para>
</listitem>
<listitem>
- <para>
-Understanding the terminology used in the project.
-</para>
+ <para>Understanding the terminology used in the project. </para>
</listitem>
<listitem>
- <para>
-Understanding how we use subversion in the project.
-</para>
+ <para>Understanding how we use subversion in the project. </para>
</listitem>
<listitem>
- <para>
-Understanding the set of tools (ant, JUnit) and how to use them.
-</para>
+ <para>Understanding the set of tools (ant, JUnit) and how to use them. </para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Focus your work in a specific area.</para>
- <para>
-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.
-</para>
+ <para>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. </para>
</listitem>
<listitem>
<para>Accept responsibility for a specific area.</para>
</listitem>
</orderedlist>
-</para>
- </sect1>
+ </para>
+ </section>
- <sect1>
+ <section>
<title>About this Cookbook</title>
- <para> 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. </para>
- <sect2>
- <title>In this Cookbook, you will find...</title>
- <para>
-Information on how to compile ArgoUML.
-(<xref linkend="buildingandtools"/>)
-</para>
-
- <para>
-Information on how different features of ArgoUML are implemented and
-how they are to be used.
-(<xref linkend="subsystems"/> and
-<xref linkend="inside_subsystems"/>)
-</para>
-
- <para>
-Information on how you should write extensions to ArgoUML.
-(<xref linkend="extending"/>)
-</para>
-
- <para>
-Information that you, as a developer of ArgoUML,
-need to know about how to contribute.
-(<xref linkend="standards"/>,
-<xref linkend="app.docstand"/> and
-<xref linkend="processes"/>)
-</para>
-
- </sect2>
- <sect2>
- <title>In this Cookbook, you will not find...</title>
- <para> You will not find information on how to install and use ArgoUML.
- </para>
- <para> You will not find information on what UML is and if or how you should use
- it in your project. </para>
- <para> You will not find information on how to convince your project to use
- ArgoUML as a modeling tool. </para>
- </sect2>
- </sect1>
+ <para>This document, the Cookbook for Developers of ArgoUML, is provided with the hopes of being helpful for the developers of ArgoUML when it comes to learning and understanding how ArgoUML work in order to improve on its functions and features. It can also be of interest for persons that wish to analyze the ArgoUML project for whatever purpose that may be. </para>
+ <section>
+ <title>In this Cookbook, you will findâ¦</title>
+ <para>Information on how to compile ArgoUML. (<xref xlink:href="buildingandtools" />) </para>
+ <para>Information on how different features of ArgoUML are implemented and how they are to be used. (<xref
+ xlink:href="subsystems" /> and <xref xlink:href="inside_subsystems" />) </para>
+ <para>Information on how you should write extensions to ArgoUML. (<xref
+ xlink:href="extending" />) </para>
+ <para>Information that you, as a developer of ArgoUML, need to know about how to contribute. (<xref
+ xlink:href="standards" />, <xref xlink:href="app.docstand" /> and <xref
+ xlink:href="processes" />) </para>
+ </section>
+ <section>
+ <title>In this Cookbook, you will not findâ¦</title>
+ <para>You will not find information on how to install and use ArgoUML. </para>
+ <para>You will not find information on what UML is and if or how you should use it in your project. </para>
+ <para>You will not find information on how to convince your project to use ArgoUML as a modeling tool. </para>
+ </section>
+ </section>
- <sect1 id="mailing_lists">
+ <section xml:id="mailing_lists">
<title>Mailing Lists</title>
<indexterm>
<primary>Mailing lists</primary>
@@ -393,11 +201,10 @@
<indexterm>
<primary>Developers' Mailing List</primary>
</indexterm>
- <para> All developers <emphasis>MUST</emphasis> subscribe to the mailing
- list for developers. Please find the details at: <ulink
- url="http://argouml.tigris.org/servlets/ProjectMailingListList">
- http://argouml.tigris.org/servlets/ProjectMailingListList</ulink>
-</para>
+ <para>All developers <emphasis>MUST</emphasis> subscribe to the mailing list for developers. Please find the details at: <link
+ xlink:href="http://argouml.tigris.org/servlets/ProjectMailingListList"
+ > http://argouml.tigris.org/servlets/ProjectMailingListList</link>
+ </para>
<indexterm>
<primary>Subversion</primary>
<secondary>Mailing list</secondary>
@@ -410,25 +217,18 @@
<primary>Issues</primary>
<secondary>Mailing list</secondary>
</indexterm>
- <para>
-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.
-</para>
- </sect1>
-
+ <para>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. </para>
+ </section>
</chapter>
-
<!-- Local stuff for Emacs - please do not delete
-
-Local Variables:
-mode: xml
-sgml-doctype: "cookbook.xml"
-sgml-parent-document: ("cookbook.xml" "chapter" nil)
-sgml-validate-command: "nsgmls -wxml -sv ../docbook-setup/xml.dcl \
-cookbook.xml"
-indent-tabs-mode: nil
-End:
-
+
+ Local Variables:
+ mode: xml
+ sgml-doctype: "cookbook.xml"
+ sgml-parent-document: ("cookbook.xml" "chapter" nil)
+ sgml-validate-command: "nsgmls -wxml -sv ../docbook-setup/xml.dcl \
+ cookbook.xml"
+ indent-tabs-mode: nil
+ End:
+
-->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/process.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/process.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/process.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/process.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/process.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/process.xml 2008-01-15 19:22:21-0800
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
// Copyright (c) 1996-2007 The Regents of the University of California. All
@@ -25,32 +25,34 @@
// UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
-->
- <chapter id="processes">
- <title>Processes for the ArgoUML project</title>
- <indexterm>
- <primary>Processes</primary>
- </indexterm>
- <para>
-This chapter contains processes used when working with the
-ArgoUML project.
-</para>
- <para>
-These processes are provided with the hope of being helpful for
-the members of the project and if they feel too complicated,
-ambitious or overworked, please raise the issue of simplifying
-them on the
-<ulink url="mailto:[email protected] ">developers' mailing list</ulink>.
-</para>
- <sect1>
- <title>The big picture for Issues</title>
- <indexterm>
- <primary>Issues</primary>
- </indexterm>
- <para>
-Here is the big picture of the life of an Issue.
-</para>
+<chapter
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xml:id="processes"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ >
+
+ <title>Processes for the ArgoUML project</title>
+
+ <indexterm>
+ <primary>Processes</primary>
+ </indexterm>
+
+ <para>This chapter contains processes used when working with the ArgoUML project. </para>
+ <para>These processes are provided with the hope of being helpful for the members of the project and if they feel too complicated, ambitious or overworked, please raise the issue of simplifying them on the <link xlink:href="mailto:[email protected] ">developers' mailing list</link>. </para>
+
+ <section>
+ <title>The big picture for Issues</title>
+
+ <indexterm>
+ <primary>Issues</primary>
+ </indexterm>
- <!--
+ <para>Here is the big picture of the life of an Issue. </para>
+
+ <!--
<note>
<para>
A decision was made in October 2005 to have new issues be created
@@ -61,1426 +63,664 @@
</note>
-->
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/cookbook/IssueBigPicture.gif" format="GIF"/>
- </imageobject>
- </mediaobject>
- </sect1>
-
- <sect1 id="issue_attributes">
- <title>Attributes of an issue</title>
- <para>
-This is what the different attributes mean and how they are used
-in the ArgoUML project.
-This is to be read as an addendum to the
-<ulink url="http://argouml.tigris.org/nonav/scdocs/issue_lifecycle.html">
-Tigris definition of the resolutions
-</ulink>
-and for that reason it is not a complete list.
-</para>
- <sect2 id="issue_priorities">
- <title>Priorities</title>
- <indexterm>
- <primary>Priorities</primary>
- <secondary>on Issues</secondary>
- </indexterm>
- <indexterm>
- <primary>Issue</primary>
- <secondary>Priority</secondary>
- </indexterm>
-
- <para>
-The priorities are used in the following manner in ArgoUML:
-<itemizedlist>
- <listitem>
- <para>P1 - Fatal error</para>
-
- <para>
-These issues are blockers for all releases.
-</para>
-
- <para>
-Examples:
-ArgoUML cannot start;
-Crashes program, JVM or computer; and
-Significant loss of user data.
-</para>
- </listitem>
- <listitem>
- <para>P2 - Serious error</para>
-
- <para>
-These issues are blockers for stable releases.
-</para>
-
- <para>
-Examples:
-Information lost.
-</para>
- </listitem>
- <listitem>
- <para>P3 - Not so serious error</para>
- <para>
-Examples:
-Functions not working;
-Strange behavior; and
-Exceptions logged.
-</para>
- </listitem>
- <listitem>
- <para>P4 - Confusing behavior</para>
- <para>
-Examples:
-Incorrect help texts and documentation;
-Inconsistent behavior;
-UI not updated; and
-Incorrect javadoc.
-</para>
- </listitem>
- <listitem>
- <para>P5 - Small problems</para>
- <para>
-Examples:
-Spelling errors.
-Ugly icons.
-Excessive logging.
-Missing javadoc.
-</para>
- </listitem>
- </itemizedlist>
-</para>
- </sect2>
-
- <sect2 id="issuezilla_resolutions">
- <title>Resolutions</title>
- <indexterm>
- <primary>Resolution</primary>
- <secondary>of Issues</secondary>
- </indexterm>
- <indexterm>
- <primary>Issue</primary>
- <secondary>Resolution</secondary>
- </indexterm>
- <para>
-<itemizedlist>
- <listitem>
- <para>LATER</para>
- <para>
-Used to denote that a certain issue cannot be resolved until
-some special upcoming and planned-for event has happened.
-The event in question is noted in the target milestone.
-</para>
- <para>
-Events can be things like, dropping support for a JDK version,
-changing the version of UML that we support, or
-replacing some central mechanism within ArgoUML.
-Once they have a target milestone registered,
-they are considered events.
-</para>
- </listitem>
-
- <listitem>
- <para>REMIND</para>
- <para>
-Not used.
-</para>
- <sidebar>
- <para>
-Rationale: Each issue have basically four states:
-<orderedlist>
- <listitem>
- <para>NEW/STARTED/REOPENED - To be resolved</para>
- </listitem>
- <listitem>
- <para>RESOLVED - To be verified</para>
- </listitem>
- <listitem>
- <para>VERIFIED - To be closed</para>
- </listitem>
- <listitem>
- <para>CLOSED - Finished.</para>
- </listitem>
- </orderedlist>
-The statistics is based on this and persons looking for
-issues to resolve look among the "To be resolved"-group
-(the web pages to help in this are set up in this way).
-This is also in sync with our release process.
-</para>
- <para>
-Looking at it from a single persons perspective an issue is either a
-"I could work with this issue but I currently don't",
-"I work with this one", or
-"I am now done with my work on this issue".
-For a resolver this is corresponds to NEW/REOPEN for the first group,
-STARTED for the second and
-RESOLVED for the third.
-For a verifier this corresponds to
-RESOLVED for the first group and
-VERIFIED for the third group.
-</para>
- <para>
-The RESOLVED/REMIND does not fit this.
-They risk to be verified because the rest of our process urges
-people to resolve issues that are RESOLVED
-in which case they are probably lost.
-
-They risk to be hanging in the RESOLVED state because nobody understands
-where they should go from there.
-
-It is not clear who is responsible to move them forward.
-The person that "resolved" them or someone else.
-Someone risk to think that there is nothing left to do since it is resolved
-and if so his options of doing work are reduced which could lead to that
-he actually does less with ArgoUML than he else would.
-</para>
- <para>
-To amend this we have made two things:
-<orderedlist>
- <listitem>
- <para>Decided that we don't use the
-RESOLVED/REMIND
-states.
-</para>
- </listitem>
- <listitem>
- <para>At every release,
-as part of the release process,
-clean up issues that for some mysterious reason ended up
-in these states
-(See <xref linkend="release_process"/>,
-<xref linkend="issuezilla_release_maintenance"/>,
-<xref linkend="reopen_remind_and_later"/>)
-</para>
- </listitem>
- </orderedlist>
-</para>
- <para>
-If you plan to solve an issue now,
-assign it to you,
-start it, and
-set the target milestone to the release you plan to have it solved.
-This will signal to everyone that you have the responsibility,
-will pursue it, and your time plan.
-</para>
- <para>
-If you don't plan to solve this now,
-leave it in the "up for grabs"-pile (as not resolved).
-Somebody else might want to work with it.
-</para>
- <para>
-If you know that an issue cannot be resolved now because it requires
-that another issue is solved before,
-register the other issue as "depends on" and leave the issue in the
-"up for grabs"-pile (as not resolved).
-</para>
- <para>
-If you know that an issue cannot be resolved now because it requires
-some big event to take place,
-put the milestone for that event in the target milestone and
-resolve the issue as RESOLVED/LATER.
-</para>
- </sidebar>
- </listitem>
- <listitem>
- <para>WORKSFORME</para>
- <para>
-This means that it works in a released version of ArgoUML.
-State the version in the comment.
-</para>
- <para>
-If the version stated by the reporter in the issue is not
-the same as the version in the comment then this probably
-means that problem was fixed in some release without anyone
-noticing that this problem was fixed.
-</para>
- </listitem>
- </itemizedlist>
-</para>
- </sect2>
- </sect1>
-
- <sect1 id="rolesofworkers">
- <title>Roles Of The Workers</title>
- <indexterm>
- <primary>Roles</primary>
- </indexterm>
- <indexterm>
- <primary>Workers</primary>
- </indexterm>
- <para>
-The roles described below are per issue, i.e. for every issue, there
-is at least a reporter and a resolver.
-
-Hence, each person involved in issues for the ArgoUML project can -
-at the same time - have different roles, and consequently, has
-issues to report,
-issues to close,
-issues to resolve, and
-issues to verify.
-</para>
-
- <sect2 id="rolereporter">
- <title>The Reporter</title>
- <para>
-The Reporter is the person who enters the issue in Issuezilla.
-</para>
- <para>
-Skills:
-The reporter is an ArgoUML user, should not need any knowledge of what the
-ArgoUML project is actually doing.
-</para>
- <para>
-Responsibilities:
- <itemizedlist>
- <listitem>
- <para>
-Report an issue
-</para>
- <para>
-The address to enter new issues is:
-<ulink url="http://argouml.tigris.org/issues/enter_bug.cgi">
-http://argouml.tigris.org/issues/enter_bug.cgi
-</ulink>.
-To enter new issues, you will need to sign up for a Tigris
-account. For some operations in the issue database you
-may also need to apply for Observer status to the ArgoUML project.
-</para>
- </listitem>
- <listitem>
- <para>
-Answer clarification requests
-</para>
- <para>
-Occasionally, the developers of ArgoUML need to request
-the Reporter more information, to be able to solve the issue correctly.
-Another way of putting it is to say that
-if the issue was reported without some vital information
-the Reporter has some more work to do.
-</para>
- </listitem>
- <listitem>
- <para>
-Close the issue
-</para>
- <para>
-This applies to an issue that is in the resolved or verified state.
-At the end of processing the issue,
-the reporter has the final word:
-he can check the result,
-and if he agrees with the solution,
-close the issue himself.
-Closing an issue requires at least "observer" role
-in the ArgoUML project.
-</para>
- </listitem>
- <listitem>
- <para>
-Reopen the issue
-</para>
- <para>
-This applies to an issue that is in
-the resolved,
-verified, or
-closed state.
-The reporter has the final word:
-he can check the result,
-and when he does not agree that the solution is correct,
-he can reopen the issue himself.
-Reopening an issue requires at least "observer" role
-in the ArgoUML project.
-</para>
- </listitem>
- </itemizedlist>
- </para>
- </sect2>
- <sect2 id="roleresolver">
- <title>The Resolver</title>
- <para>
-The Resolver is the software developer who attempts to resolve the issue.
-Doing so requires at least "observer" role.
-The "developer" role is only needed to commit things into the repository
-(e.g. submit changed Java code, scripts or documentation).
-</para>
- <para>
-Remark: Someone who does not have the developer role,
-but solves the issue and convinces someone else to commit the solution,
-is still the Resolver even though he cannot commit things into the repository.
-</para>
- <para>
-The goal of the Resolver is to progress the issue to the status of
-"Resolved".
-The resolver may be the same person as the reporter.
-</para>
- <para>
-Responsibilities:
- <itemizedlist>
- <listitem>
- <para>
-Decide usefulness
-(if this issue is really a bug or enhancement and if it is worth solving)
-</para>
- <para>
-The Resolver has to decide if solving the issue is
-really a useful improvement for ArgoUML.
-The Reporter of the issue may very well be mistaken
-in entering a bug-issue for what is in fact a feature,
-or entering an enhancement-issue which is not really an enhancement.
-Another thing that could be is a bug that appears in
-very exceptional circumstances and that
-may have large impact on ArgoUML architecture.
-If the Resolver decides after the investigation that this bug
-is really not that important or that he is not the right person
-to solve it he enters his findings as a comment and
-assigns the issue back to anyone (issues@argouml) and
-moves along to work on another issue instead.
-</para>
- </listitem>
- <listitem>
- <para>
-If applicable, program and test a solution
-</para>
- <para>
-As this might take considerable time it might be a good idea
-of the Resolver to assign the issue to himself to reserve the issue.
-He can also signal progress by setting the issue to the state Started.
-</para>
- </listitem>
- <listitem>
- <para>
-If applicable, write test cases
-</para>
- </listitem>
- <listitem>
- <para>
-Set the issue in the end to "RESOLVED".
-</para>
- <para>
-When the resolver is finished with the issue,
-he puts it in "RESOLVED" status, and indicates the
-"resolution" is FIXED, WORKSFORME, INVALID, WONTFIX, or DUPLICATE.
-</para>
- </listitem>
- </itemizedlist>
-</para>
- <para>
-Skills:
-The resolver needs to know a lot of the insides of the ArgoUML code, Java,
-coding standards, and also the current status of the project with goals,
-requirements and release plans.
-</para>
- </sect2>
- <sect2 id="roleverifier">
- <title>The Verifier</title>
- <para>
-The Verifier may be neither the Reporter, nor the Resolver of the issue.
-The task of the Verifier is to check the quality of the solution by
-confirming that the solution is complete, to the point, bug-free, etc.
-This is an important part of the quality assurance work we do
-in the ArgoUML project and the objective is to make sure that a resolved
-issue is in fact resolved.
-</para>
- <para>
-The test must be done on the "Target Milestone" version of the issue,
-or any later version released to the public.
-</para>
- <para>
-Responsibilities:
- <itemizedlist>
- <listitem>
- <para>
-Check that the issue is solved in the stated version of ArgoUML
-</para>
- </listitem>
- <listitem>
- <para>
-Verify the issue.
-</para>
- <para>
-If the Verifier can conclude that the problem does not exist or
-the feature/enhancement is now present.
-</para>
- </listitem>
- <listitem>
- <para>
-Close the issue.
-</para>
- <para>
-If someone else has already verified the issue then
-the issue can be closed.
-</para>
- </listitem>
- <listitem>
- <para>
-Reopen the issue if the solution is not fully correct
-</para>
- <para>
-If the solution is not correct or the feature/enhancement does not work,
-it is the duty of the Verifier to reopen the issue.
-</para>
- </listitem>
- </itemizedlist>
-</para>
- <para>
-Skills:
-The verifier needs only to focus on that issue, how the problem in it
-is formulated.
-He doesn't need to know how it is actually solved.
-</para>
- </sect2>
- </sect1>
-
- <sect1 id="resolve_issue">
- <title>How to resolve an Issue</title>
- <indexterm>
- <primary>Issues</primary>
- <secondary>Resolving</secondary>
- </indexterm>
- <para>
-This can be performed by any member of the project (any role).
-Persons without the Developer role need a person
-with the Developer role to actually commit the work if the resolution
-involves changing some artifact.
-There might be special skills involved but it differs widely depending
-on the nature of the Issue.
-</para>
- <para>
-Do the following:
-</para>
- <orderedlist>
- <listitem id="resolve_issue_start">
- <para>
-Pick any Issue that is NEW or REOPENED
-that you from the description think that you are able to solve.
-Best results are often obtained if you find an Issue that you really feel
-needs to be solved.
-<ulink url="http://argouml.tigris.org/issues/buglist.cgi?component=argouml&issue_status=NEW&issue_status=REOPENED">The list of all of them</ulink>.
-</para>
- </listitem>
- <listitem>
- <para>
-Look at your personal schedule and how much time you have during the
-next couple of weeks and compare that to the amount of time you think
-you will need to spend for solving the issue.
-Compare this to the release plan to see what release your contribution
-will fit in.
-</para>
- </listitem>
- <listitem>
- <para>
-Accept the Issue and reserve it by assigning it to yourself.
-Set the Target Milestone to the release you have chosen.
-</para>
- </listitem>
- <listitem>
- <para>
-Make sure you have a checked out copy of ArgoUML or else check out
-a new one.
-</para>
- <para>
-How this is done is described in
-<xref linkend="buildingandtools"/>.
-</para>
- </listitem>
- <listitem>
- <para>
-Mark the issue as Started (this could be done while assigning also).
-</para>
- </listitem>
- <listitem>
- <para>
-Change the code to solve the problem.
-</para>
- </listitem>
- <listitem>
- <para>
-Compile and test your new code.
-</para>
- <para>
-This should include developing a JUnit test case to
-verify that the problem is solved.
-You could also develop the JUnit test case before actually solving
-the problem.
-</para>
- <para>
-If your solution did not work as intended, continue changing it
-until it does.
-</para>
- <para>
-If you feel that your estimation of the complexity of the problem
-and your own abilities and time available was incorrect,
-then change the Target Milestone of the Issue to another one
-that fits your new estimation.
-This is just a change of plan.
-</para>
- <para>
-If you, at this point, feel that your personal plans have changed
-so that you won't have time to pursue the work,
-change the Issue back to "NEW" with your experiences so far
-stated in the comment.
-This means that you are giving up and giving the Issue back to
-anyone.
-You should also assign it back to issues@argouml or if you know
-someone else in the ArgoUML team that will continue the work,
-assign it to him.
-Remember not to commit your changes in the main branch but please
-commit your changes (if any) into a work branch and state the name
-of the branch in the issue.
-That will make it possible for someone to make use of your work so far.
-</para>
- </listitem>
- <listitem>
- <para>
-Commit your changes and the JUnit test cases stating
-the number of the Issue in the comment.
-</para>
- <para>
-If you don't have a developer role in the project,
-this involves sending your changes to someone who has
-and then convincing him to commit them for you.
-</para>
- </listitem>
- <listitem>
- <para>
-"Resolve" the Issue with the resolution "FIXED".
-</para>
- <para>
-Also set the target milestone of the upcoming release
-that will include the fix.
-</para>
- </listitem>
- <listitem>
- <para>
-Sit back and feel the personal satisfaction of having completed
-something that will be part of the ArgoUML product.
-</para>
- </listitem>
- <listitem>
- <para>
-If you during this, have discovered other problems,
-create new Issues stating those new problems
-according to the rule for creating Issues.
-</para>
- </listitem>
- </orderedlist>
- </sect1>
-
- <sect1 id="verify_resolved_fixed">
- <title>How to verify an Issue that is FIXED</title>
- <indexterm>
- <primary>Issues</primary>
- <secondary>Verifying Fixed</secondary>
- </indexterm>
- <indexterm>
- <primary>Issues</primary>
- <secondary>Verifying WORKSFORME</secondary>
- </indexterm>
- <indexterm>
- <primary>Verifying</primary>
- <secondary>Works for me Issues</secondary>
- </indexterm>
- <para>
-This can be performed by any member of the project (any role).
-There might be special skills involved but it differs widely depending
-on the nature of the Issue.
-</para>
- <para>
-If you are the Reporter of the issue, you Close the issue instead.
-</para>
- <para>
-Do the following:
-</para>
- <orderedlist>
- <listitem id="verify_resolved_fixed_start">
- <para>
-Pick any Issue that is RESOLVED/FIXED or WORKSFORME and that you have
-not raised, nor solved and that is included in a release
-(Target milestone set to a release available on the site).
-<ulink url="http://argouml.tigris.org/issues/buglist.cgi?component=argouml&issue_status=RESOLVED&resolution=FIXED&resolution=WORKSFORME">The list of all RESOLVED/FIXED and RESOLVED/WORKSFORME issues</ulink>.
-</para>
- </listitem>
- <listitem>
- <para>
-Run the specified release of ArgoUML.
-You can also use any later release.
-Use ArgoUML provided for downloads or
-through Java Web Start.
-</para>
- </listitem>
- <listitem>
- <para>
-Test the problem in the issue and verify that the problem is no longer
-there or the feature is provided.
-</para>
- </listitem>
- <listitem>
- <para>
-Do one of the following:
-</para>
- <itemizedlist>
- <listitem>
- <para>
-If the problem is gone or the feature is present, set the Issue
-Status to VERIFIED and
-add the version of the ArgoUML used for the test in in the comment.
- </para>
- <para> Remark: As an additional activity, the
- verifier may check if the manual needs to be adapted, and if
- so, may REOPEN the issue with an explanation text, and setting
- the correct subcomponent (Documentation & Help). </para>
- </listitem>
- <listitem>
- <para>
-If the problem is still there, the feature does not work, put the
-Issue in Status REOPENED with a description of what is still there, is
-still missing.
-Also state what version of ArgoUML was used for the test in the comment.
-</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>
-If you during this, have discovered other problems than the one
-stated in the Issue, create new Issues for those new problems
-according to the rule for creating Issues.
-</para>
- </listitem>
- <listitem>
- <para>
-Do this as many times as you like until there are no Issues left.
-</para>
- </listitem>
- </orderedlist>
- </sect1>
-
- <sect1 id="verify_resolved_invalid">
- <title>How to verify an Issue that is rejected</title>
- <indexterm>
- <primary>Issues</primary>
- <secondary>Resolving Rejected</secondary>
- </indexterm>
- <indexterm>
- <primary>Issues</primary>
- <secondary>Resolving INVALID</secondary>
- </indexterm>
- <indexterm>
- <primary>Issues</primary>
- <secondary>Resolving WONTFIX</secondary>
- </indexterm>
- <indexterm>
- <primary>Issues</primary>
- <secondary>Resolving DUPLICATE</secondary>
- </indexterm>
- <indexterm>
- <primary>Resolving</primary>
- <secondary>Rejected Issues</secondary>
- </indexterm>
- <indexterm>
- <primary>Resolving</primary>
- <secondary>Invalid Issues</secondary>
- </indexterm>
- <indexterm>
- <primary>Resolving</primary>
- <secondary>WONTFIX Issues</secondary>
- </indexterm>
- <indexterm>
- <primary>Resolving</primary>
- <secondary>DUPLICATE Issues</secondary>
- </indexterm>
- <para>
-This can be performed by any member of the project (any role).
-There might be special skills involved but it differs widely depending
-on the nature of the Issue.
-</para>
- <para>
-If you are the Reporter of the issue, you Close the issue instead.
-</para>
- <para>
-Do the following:
-</para>
- <orderedlist>
- <listitem id="verify_resolved_invalid_start">
- <para>
-Pick any issue that is RESOLVED/(INVALID, WONTFIX, or DUPLICATE) that
-you have not raised nor solved.
-The chosen issue need not be connected to an available release.
-<ulink url="http://argouml.tigris.org/issues/buglist.cgi?component=argouml&issue_status=RESOLVED&resolution=INVALID&resolution=WONTFIX&resolution=DUPLICATE">The list of all RESOLVED/INVALID, RESOLVED/WONTFIX and RESOLVED/DUPLICATED issues</ulink>.
-</para>
- </listitem>
- <listitem>
- <para>
-Read through the description provided.
-</para>
- </listitem>
- <listitem>
- <para>
-Do one of the following:
-</para>
- <itemizedlist>
- <listitem>
- <para>
-If you agree with the statement and feel that the rejection
-is done for correct reasons,
-put the Issue in Status VERIFIED.
-</para>
- </listitem>
- <listitem>
- <para>
-If you don't agree, put the Issue in status REOPENED and give a
-description as to why you don't agree.
-</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>
-Do this as many times as you like until there are no Issues left.
-</para>
- </listitem>
- </orderedlist>
- </sect1>
-
- <sect1 id="close_verified_issue">
- <title>How to Close an Issue</title>
- <indexterm>
- <primary>Issues</primary>
- <secondary>Closing</secondary>
- </indexterm>
- <para>
-This is performed by the person that originally raised the Issue,
-by the QA responsible for that area,
-or by anyone for issues that are verified.
-You need to be a member of the project (any role).
-This can also be done by someone who would have raised the issue but
-did not because it was already present in Issuezilla.
-</para>
- <orderedlist>
- <listitem>
- <para>
-Pick any Issue that is Verified
-(<ulink url="http://argouml.tigris.org/issues/buglist.cgi?component=argouml&issue_status=VERIFIED">
-all VERIFIED issues
-</ulink>)
-or that you have raised or refrained from raising because
-somebody else already had written it.
-</para>
- </listitem>
- <listitem>
- <para>
-See that you are satisfied with the solution.
-This could involve reading through the resolution and
-starting the tool to verify it.
-</para>
- </listitem>
- <listitem>
- <para>
-Do one of the following:
-</para>
- <itemizedlist>
- <listitem>
- <para>
-If you are satisfied, Close the issue.
-</para>
- </listitem>
- <listitem>
- <para>
-If you are not satisfied but the problem is solved as it is written in
-the Issue, Close the issue and open a new Issue with
-the rest of the problem.
-</para>
- </listitem>
- <listitem>
- <para>
-If you are not satisfied and the problem is not solved, put the Issue
-in status REOPENED with a description on what you are not satisfied
-with.
-</para>
- </listitem>
- </itemizedlist>
- </listitem>
- </orderedlist>
- </sect1>
-
- <sect1 id="issues_dependencies">
- <title>How to relate issues to problems in dependencies</title>
- <indexterm>
- <primary>dependencies</primary>
- </indexterm>
- <para>
-ArgoUML uses products internally and is very
-dependent on these products functioning well.
-This are products like GEF, MDR, OCL, log4j, ...
-</para>
- <para>
-Occasionally a problem found in ArgoUML is found to be a problem in one
-of the dependencies and cannot be or is extremely complicated to fix
-within ArgoUML.
-</para>
- <para>
-If this happens, this is the way to handle this problem.
-</para>
- <para>
-This can be performed by any member of the project (any role).
-There might be special skills involved depending on the nature of the problem.
-In this description "issue" means a issue in Issuezilla,
-"bug report" means a bug report in some other project,
-and "problem" denotes the conceptual problem.
-</para>
- <para>
-Do the following:
-</para>
- <orderedlist>
- <listitem>
- <para>
-During your examination of an issue you find that the problem
-is in one of the ArgoUML dependencies (GEF, MDR, OCL, ...).
-</para>
- </listitem>
- <listitem>
- <para>
-Make sure that the issue is assigned to you.
-</para>
- </listitem>
- <listitem>
- <para>
-Write a comment in the issue stating which one of the dependency
-that has the problem (and what the problem is within that dependency).
-</para>
- </listitem>
- <listitem>
- <para>
-Post a bug report in that dependency bug reporting tool
-(or find that a bug report already registered).
-</para>
- <para>
-I am assuming that there is such a tool for the dependency in question.
-If there isn't,
-then make the bug report to the person responsible for this product
-so that we are sure that the problem is communicated.
-</para>
- </listitem>
- <listitem>
- <para>
-Accept the issue (set it to STARTED) and
-enter the reference from the dependency bug reporting tool and
-if possible the URL to the bug reporting tool or to the bug report in question.
-</para>
- <para>
-I am assuming that there is a bug reporting tool for the dependency.
-If there isn't for the product in question,
-then include all communications (both ways) in the issue.
-</para>
- </listitem>
- </orderedlist>
- <para>
-You are now responsible to follow up on
-the upcoming releases of the dependency.
-If you don't think that you are the best person for this
-(you should be since it was you that found that this problem
-is in the dependency),
-assign the issue to "the right person".
-To follow up you should do the following.
-</para>
- <orderedlist>
- <listitem>
- <para>
-Look at each new release of that dependency to see if the bug report
-is in fact stated as fixed in that release.
-</para>
- </listitem>
- <listitem>
- <para>
-If the bug report is fixed, then you weight together
-the importance of the problem,
-other bug reports that are also problems in ArgoUML
-that are solved in that release,
-the amount of work needed to fit the new version of the dependency
-instead of the old one,
-the planned releases of the dependency with promises to
-solve other bug reports,
-and
-the current release plan of ArgoUML.
-From this you decide whether it is time to do the update of
-the dependency within ArgoUML or to wait.
-</para>
- </listitem>
- <listitem>
- <para>
-If you decide that it is time to update,
-you assign all issues against that dependency to you (if not already),
-then you do the work.
-The work is to add the new version of the dependency to ArgoUML,
-do all the needed work within ArgoUML to fit the new version,
-test and commit everything,
-put the issues indeed fixed in RESOLVED/FIXED,
-and close the bugs registered in the dependency bug reporting tool.
-</para>
- </listitem>
- </orderedlist>
-
- <para>
-For dependencies that are not delivered with ArgoUML
-(JRE, Xerces, OS, drivers, HW, ...),
-the same process is taken except that
-the issue is solved when it is entered into the ArgoUML FAQ or documentation
-or in some cases as tests in the code testing that we are not using that
-version.
-At that point is resolved (as RESOLVED/FIXED).
-</para>
- <para>
-The rationale for this is that we, the development team, help the user
-to the right version of these by the FAQ and documentation and by code
-testing the versions.
-</para>
- </sect1>
-
- <sect1 id="proc-create-stable-releases">
- <title>How to Create a Stable Release</title>
-
- <para>
-We have two kinds of releases of ArgoUML:
-</para>
-
- <itemizedlist>
- <listitem>
- <para>
-Development releases.
-</para>
- </listitem>
- <listitem>
- <para>
-Stable releases.
-</para>
- </listitem>
- </itemizedlist>
-
- <para>
-Stable releases are supposed to be better quality-wise and are
-always advertised to the users community
-on the main ArgoUML home page and
-as a news announcement.
-</para>
-
- <para>
-Development releases are not supposed to be used by users and
-are only advertised to users for the purpose of recruiting developers
-or soliciting help with implementation and test of new features.
-</para>
-
- <para>
-To increase the quality of a stable release, a stable release is preceded
-by a period during which there are a sequence of releases with increased
-quality standards.
-</para>
-
- <para>
-The whole release schedule leading up to a stable release and
-patched stable release looks like this:
-</para>
-
- <itemizedlist>
- <listitem>
- <para>
-Development Period.
-</para>
- <para>
-A period of one to several months where no special restrictions apply.
-</para>
- <para>
-During this period we attempt to make one development release per month.
-The releases are named x.y.z where
-y is an odd number and
-z is counting upwards from 1.
-</para>
- <para>
-The releases are checkpoints where:
-</para>
- <itemizedlist>
- <listitem>
- <para>Everything compiles (including the sub-projects).</para>
- </listitem>
- <listitem>
- <para>The release script works.</para>
- </listitem>
- <listitem>
- <para>No JUnit tests are failing.</para>
- </listitem>
- <listitem>
- <para>There are no P1 issues.</para>
- </listitem>
- </itemizedlist>
-
- <para>
-The releases are used:
-</para>
-
- <itemizedlist>
- <listitem>
- <para>As reference points when reporting bugs.</para>
- </listitem>
-
- <listitem>
- <para>As reference points when verifying issues.</para>
- </listitem>
-
- <listitem>
- <para>
-As reference points and convenient downloads for persons working with modules.
-</para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
-First Alpha.
-</para>
- <para>
-This is the enhancement freeze point.
-All enhancements that are not completed and committed in the main trunk
-before this point will not be
-included in the stable release.
-</para>
- <para>
-The First Alpha release is named x.y.alpha1 or x.y.ALPHA_1 depending on
-the context.
-It marks the end of the Development Period and
-the start of the Alpha Period.
-</para>
- <para>
-Otherwise it works just like a development release.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Alpha Period.
-</para>
- <para>
-A period of a couple of weeks where special restrictions apply
-when committing into the main trunk:
-</para>
-
- <itemizedlist>
- <listitem>
- <para>Only bug fixes are allowed in the code.</para>
- <para>
-Put the number of the DEFECT you are addressing by the commit in the message.
-</para>
- <para>
-Test case code can be added.
-Documentation, web site and other things can be added.
-</para>
- </listitem>
- </itemizedlist>
- <para>
-Exceptions to this are requested to and approved
-by the Release Responsible
-before commit.
-</para>
-
- <para>
-During this period we attempt to make at least one Alpha Release
-each week.
-The releases are named
-<replaceable>x</replaceable>.<replaceable>y</replaceable>.alpha<replaceable>z</replaceable>
-where
-<replaceable>y</replaceable> is an even number and
-<replaceable>z</replaceable> is
-counting upwards from 1 that is the first alpha.
-</para>
-
- <para>
-The purpose of the releases and their use are the same as during
-the development period.
-</para>
- </listitem>
-
- <listitem>
- <para>
-First Beta.
-</para>
- <para>
-This is the bug fixes freeze point.
-All enhancements and bug fixes that are not
-completed and committed in the main trunk before this point
-will not be included in the stable release.
-A known problems list could be compiled at this point.
-</para>
- <para>
-The first beta release is named
-<replaceable>x</replaceable>.<replaceable>y</replaceable>.beta1 or
-<replaceable>x</replaceable>.<replaceable>y</replaceable>.BETA_1
-depending on the context.
-It marks the end of the Alpha Period and
-the start of the Beta Period.
-</para>
- <para>
-It is the first release candidate for the stable release.
-Because of this it is required that:
-</para>
- <itemizedlist>
- <listitem>
- <para>Everything compiles (including the sub-projects).</para>
- </listitem>
- <listitem>
- <para>The release script works.</para>
- </listitem>
- <listitem>
- <para>No JUnit tests are failing.</para>
- </listitem>
- <listitem>
- <para>There are no P1 or P2 issues.</para>
- </listitem>
- </itemizedlist>
-
- <para>
-Otherwise it works just like a development release.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Beta Period.
-</para>
- <para>
-A period of a couple of weeks where the focus is quality assurance.
-Every developer should strive to:
-</para>
- <itemizedlist>
- <listitem>
- <para>
-Test ArgoUML as thoroughly as possible.
-Especially the areas that are new or changed since the last release.
-</para>
- </listitem>
- <listitem>
- <para>
-Verify issues that are resolved.
-</para>
- </listitem>
- <listitem>
- <para>
-Scrutinize the commits in the main trunk to see that no new bugs
-are introduced.
-</para>
- </listitem>
- </itemizedlist>
-
- <para>
-Extreme caution applies when committing into the main trunk.
-Only under the following conditions are commits allowed:
-</para>
- <itemizedlist>
- <listitem>
- <para>
-It is a fix to some DEFECT that was previously fixed
-but it was found during the verification that the solution was not
-correct or complete.
-</para>
- <para>
-Reopen the DEFECT when the problem is found with a statement of what is
-still the problem.
-Put the number of the DEFECT you are addressing by the commit in the message
-together with the statement of the part of the problem.
-Resolve the DEFECT as FIXED and update the target milestone with
-the release name of the next beta.
-</para>
- <para>
-Test case code can still be added.
-Final documentation and web site updates for the release are done.
-</para>
- </listitem>
-
- <listitem>
- <para>
-All JUnit test cases are run from a cleaned checked out copy
-at the commit and no problems are found.
-</para>
- </listitem>
- </itemizedlist>
- <para>
-Exceptions to this are requested and approved
-by the Release Responsible
-before commit.
-</para>
-
- <para>
-If a new problem is found the following needs to be done before
-committing the solution:
-</para>
- <itemizedlist>
- <listitem>
- <para>
-The problem is registered as a DEFECT.
-</para>
- </listitem>
- <listitem>
- <para>
-The solution is implemented.
-</para>
- <para>
-Here the requirement is a high on the quality and low impact of the solution.
-</para>
- </listitem>
- <listitem>
- <para>
-A request is made to the Release Responsible to allow this change.
-</para>
- </listitem>
- <listitem>
- <para>
-This is granted by the Release Responsible.
-</para>
- </listitem>
- </itemizedlist>
-
- <para>
-During the period we attempt to release at least one beta release
-each week.
-The releases are named
-<replaceable>x</replaceable>.<replaceable>y</replaceable>.beta<replaceable>z</replaceable>
-where
-<replaceable>y</replaceable> is an even number and
-<replaceable>z</replaceable> is counting upwards from 1 that is the first beta.
-</para>
-
- <para>
-Each release is a release candidate.
-When we have reached the point where no more issues are verified
-and we are confident that there are no more problems in this release
-we make the stable release without code changes compared to the last beta.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Stable Release.
-</para>
-
- <para>
-This marks the end of the Alpha and Beta Period and
-the start of the next Development Period.
-</para>
-
- <para>
-The release is named
-<replaceable>x</replaceable>.<replaceable>y</replaceable>
-where
-<replaceable>y</replaceable> is an even number.
-</para>
-
- <para>
-The release is used:
-</para>
- <itemizedlist>
- <listitem>
- <para>By all users.</para>
- </listitem>
- </itemizedlist>
-
- <para>
-It can also be used as a development release.
-</para>
- </listitem>
-
- <listitem>
- <para>
-A Stable Patch Release.
-</para>
-
- <para>
-If we find a serious problem in the stable release
-we can decide to make a Stable Patch Release.
-</para>
-
- <para>
-The following needs to be done before committing the solution:
-</para>
- <itemizedlist>
- <listitem>
- <para>
-The problem is registered as a DEFECT stating that it is a problem in the
-Stable Release or a previous Stable Patch Release.
-</para>
- </listitem>
- <listitem>
- <para>
-A working branch is created against the release tag of the
-Stable Release or Stable Patch Release
-and the solution is implemented in that branch.
-</para>
- <para>
-Here the requirement is a high on the quality and low impact of the solution.
-</para>
- </listitem>
- <listitem>
- <para>
-We decide that it is a serious problem and that we are going to do a
-Stable Patch Release.
-</para>
- </listitem>
- <listitem>
- <para>
-Several developers scrutinize the solution, testing and verifying
-in the branch of the issue.
-</para>
- </listitem>
- <listitem>
- <para>
-The Release Responsible creates a branch.
-If this is not the first Stable Patch Release the branch is reused.
-</para>
- </listitem>
- <listitem>
- <para>
-The Release Responsible merges the solution into the branch.
-</para>
-
- <para>
-A Stable Patch Release could contain several issues resolved.
-In that case they are all merged.
-</para>
- </listitem>
- <listitem>
- <para>
-Several developers scrutinize the merge, testing and verifying
-in the release branch.
-</para>
- </listitem>
- </itemizedlist>
-
- <para>
-The release is named
-<replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>
-where
-<replaceable>y</replaceable> is an even number, and
-<replaceable>z</replaceable> is counting upwards from 1.
-</para>
-
- <para>
-The release is used:
-</para>
- <itemizedlist>
- <listitem>
- <para>By all users.</para>
- </listitem>
- </itemizedlist>
-
- <para>
-After the release is completed the person working with the solution
-commits his solution also in the main trunk if still applicable there.
-</para>
- </listitem>
- </itemizedlist>
- </sect1>
-
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/cookbook/IssueBigPicture.gif" format="GIF" />
+ </imageobject>
+ </mediaobject>
+ </section>
+
+ <section xml:id="issue_attributes">
+ <title>Attributes of an issue</title>
+
+ <para>This is what the different attributes mean and how they are used in the ArgoUML project. This is to be read as an addendum to the <link xlink:href="http://argouml.tigris.org/nonav/scdocs/issue_lifecycle.html" > Tigris definition of the resolutions </link> and for that reason it is not a complete list. </para>
+
+ <section xml:id="issue_priorities">
+ <title>Priorities</title>
+ <indexterm>
+ <primary>Priorities</primary>
+ <secondary>on Issues</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Issue</primary>
+ <secondary>Priority</secondary>
+ </indexterm>
+
+ <para>The priorities are used in the following manner in ArgoUML:
+ <itemizedlist>
+ <listitem>
+ <para>P1 - Fatal error</para>
+ <para>These issues are blockers for all releases. </para>
+ <para>Examples: ArgoUML cannot start; Crashes program, JVM or computer; and Significant loss of user data. </para>
+ </listitem>
+ <listitem>
+ <para>P2 - Serious error</para>
+ <para>These issues are blockers for stable releases. </para>
+ <para>Examples: Information lost. </para>
+ </listitem>
+ <listitem>
+ <para>P3 - Not so serious error</para>
+ <para>Examples: Functions not working; Strange behavior; and Exceptions logged. </para>
+ </listitem>
+ <listitem>
+ <para>P4 - Confusing behavior</para>
+ <para>Examples: Incorrect help texts and documentation; Inconsistent behavior; UI not updated; and Incorrect javadoc. </para>
+ </listitem>
+ <listitem>
+ <para>P5 - Small problems</para>
+ <para>Examples: Spelling errors. Ugly icons. Excessive logging. Missing javadoc. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section xml:id="issuezilla_resolutions">
+ <title>Resolutions</title>
+
+ <indexterm>
+ <primary>Resolution</primary>
+ <secondary>of Issues</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Issue</primary>
+ <secondary>Resolution</secondary>
+ </indexterm>
+
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>LATER</para>
+ <para>Used to denote that a certain issue cannot be resolved until some special upcoming and planned-for event has happened. The event in question is noted in the target milestone. </para>
+ <para>Events can be things like, dropping support for a JDK version, changing the version of UML that we support, or replacing some central mechanism within ArgoUML. Once they have a target milestone registered, they are considered events. </para>
+ </listitem>
+ <listitem>
+ <para>REMIND</para>
+ <para>Not used. </para>
+ <sidebar>
+ <para>Rationale: Each issue have basically four states: <orderedlist>
+ <listitem>
+ <para>NEW/STARTED/REOPENED - To be resolved</para>
+ </listitem>
+ <listitem>
+ <para>RESOLVED - To be verified</para>
+ </listitem>
+ <listitem>
+ <para>VERIFIED - To be closed</para>
+ </listitem>
+ <listitem>
+ <para>CLOSED - Finished.</para>
+ </listitem>
+ </orderedlist> The statistics is based on this and persons looking for issues to resolve look among the "To be resolved"-group (the web pages to help in this are set up in this way). This is also in sync with our release process. </para>
+ <para>Looking at it from a single persons perspective an issue is either a "I could work with this issue but I currently don't", "I work with this one", or "I am now done with my work on this issue". For a resolver this is corresponds to NEW/REOPEN for the first group, STARTED for the second and RESOLVED for the third. For a verifier this corresponds to RESOLVED for the first group and VERIFIED for the third group. </para>
+ <para>The RESOLVED/REMIND does not fit this. They risk to be verified because the rest of our process urges people to resolve issues that are RESOLVED in which case they are probably lost. They risk to be hanging in the RESOLVED state because nobody understands where they should go from there. It is not clear who is responsible to move them forward. The person that "resolved" them or someone else. Someone risk to think that there is nothing left to do since it is resolved and if so his options of doing work are reduced which could lead to that he actually does less with ArgoUML than he else would. </para>
+ <para>To amend this we have made two things: <orderedlist>
+ <listitem>
+ <para>Decided that we don't use the RESOLVED/REMIND states. </para>
+ </listitem>
+ <listitem>
+ <para>At every release, as part of the release process, clean up issues that for some mysterious reason ended up in these states (See <xref xlink:href="building.xml#release_process" />, <xref xlink:href="#issuezilla_release_maintenance" />, <xref xlink:href="building.xml.svn-base.xml#reopen_remind_and_later" />) </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ <para>If you plan to solve an issue now, assign it to you, start it, and set the target milestone to the release you plan to have it solved. This will signal to everyone that you have the responsibility, will pursue it, and your time plan. </para>
+ <para>If you don't plan to solve this now, leave it in the "up for grabs"-pile (as not resolved). Somebody else might want to work with it. </para>
+ <para>If you know that an issue cannot be resolved now because it requires that another issue is solved before, register the other issue as "depends on" and leave the issue in the "up for grabs"-pile (as not resolved). </para>
+ <para>If you know that an issue cannot be resolved now because it requires some big event to take place, put the milestone for that event in the target milestone and resolve the issue as RESOLVED/LATER. </para>
+ </sidebar>
+ </listitem>
+ <listitem>
+ <para>WORKSFORME</para>
+ <para>This means that it works in a released version of ArgoUML. State the version in the comment. </para>
+ <para>If the version stated by the reporter in the issue is not the same as the version in the comment then this probably means that problem was fixed in some release without anyone noticing that this problem was fixed. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ </section>
+
+ <section xml:id="rolesofworkers">
+ <title>Roles Of The Workers</title>
+
+ <indexterm>
+ <primary>Roles</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Workers</primary>
+ </indexterm>
+
+ <para>The roles described below are per issue, i.e. for every issue, there is at least a reporter and a resolver. Hence, each person involved in issues for the ArgoUML project can - at the same time - have different roles, and consequently, has issues to report, issues to close, issues to resolve, and issues to verify. </para>
+
+ <section xml:id="rolereporter">
+ <title>The Reporter</title>
+
+ <para>The Reporter is the person who enters the issue in Issuezilla. </para>
+ <para>Skills: The reporter is an ArgoUML user, should not need any knowledge of what the ArgoUML project is actually doing. </para>
+ <para>Responsibilities:
+
+ <itemizedlist>
+ <listitem>
+ <para>Report an issue </para>
+ <para>The address to enter new issues is: <link xlink:href="http://argouml.tigris.org/issues/enter_bug.cgi" >http://argouml.tigris.org/issues/enter_bug.cgi</link>. To enter new issues, you will need to sign up for a Tigris account. For some operations in the issue database you may also need to apply for Observer status to the ArgoUML project. </para>
+ </listitem>
+ <listitem>
+ <para>Answer clarification requests </para>
+ <para>Occasionally, the developers of ArgoUML need to request the Reporter more information, to be able to solve the issue correctly. Another way of putting it is to say that if the issue was reported without some vital information the Reporter has some more work to do. </para>
+ </listitem>
+ <listitem>
+ <para>Close the issue </para>
+ <para>This applies to an issue that is in the resolved or verified state. At the end of processing the issue, the reporter has the final word: he can check the result, and if he agrees with the solution, close the issue himself. Closing an issue requires at least "observer" role in the ArgoUML project. </para>
+ </listitem>
+ <listitem>
+ <para>Reopen the issue </para>
+ <para>This applies to an issue that is in the resolved, verified, or closed state. The reporter has the final word: he can check the result, and when he does not agree that the solution is correct, he can reopen the issue himself. Reopening an issue requires at least "observer" role in the ArgoUML project. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section xml:id="roleresolver">
+ <title>The Resolver</title>
+
+ <para>The Resolver is the software developer who attempts to resolve the issue. Doing so requires at least "observer" role. The "developer" role is only needed to commit things into the repository (e.g. submit changed Java code, scripts or documentation). </para>
+ <para>Remark: Someone who does not have the developer role, but solves the issue and convinces someone else to commit the solution, is still the Resolver even though he cannot commit things into the repository. </para>
+ <para>The goal of the Resolver is to progress the issue to the status of "Resolved". The resolver may be the same person as the reporter. </para>
+ <para>Responsibilities:
+ <itemizedlist>
+ <listitem>
+ <para>Decide usefulness (if this issue is really a bug or enhancement and if it is worth solving) </para>
+ <para>The Resolver has to decide if solving the issue is really a useful improvement for ArgoUML. The Reporter of the issue may very well be mistaken in entering a bug-issue for what is in fact a feature, or entering an enhancement-issue which is not really an enhancement. Another thing that could be is a bug that appears in very exceptional circumstances and that may have large impact on ArgoUML architecture. If the Resolver decides after the investigation that this bug is really not that important or that he is not the right person to solve it he enters his findings as a comment and assigns the issue back to anyone (issues@argouml) and moves along to work on another issue instead. </para>
+ </listitem>
+ <listitem>
+ <para>If applicable, program and test a solution </para>
+ <para>As this might take considerable time it might be a good idea of the Resolver to assign the issue to himself to reserve the issue. He can also signal progress by setting the issue to the state Started. </para>
+ </listitem>
+ <listitem>
+ <para>If applicable, write test cases </para>
+ </listitem>
+ <listitem>
+ <para>Set the issue in the end on "RESOLVED". </para>
+ <para>When the resolver is finished with the issue, he puts it in "RESOLVED" status, and indicates the "resolution" is FIXED, WORKSFORME, INVALID, WONTFIX, or DUPLICATE. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>Skills: The resolver needs to know a lot of the insides of the ArgoUML code, Java, coding standards, and also the current status of the project with goals, requirements and release plans. </para>
+ </section>
+
+ <section xml:id="roleverifier">
+ <title>The Verifier</title>
+
+ <para>The Verifier may be neither the Reporter, nor the Resolver of the issue. The task of the Verifier is to check the quality of the solution by confirming that the solution is complete, to the point, bug-free, etc. This is an important part of the quality assurance work we do in the ArgoUML project and the object is to make sure that a resolved issue is in fact resolved. </para>
+ <para>The test must be done on the "Target Milestone" version of the issue, or any later version released to the public. </para>
+ <para>Responsibilities:
+ <itemizedlist>
+ <listitem>
+ <para>Check that the issue is solved in the stated version of ArgoUML </para>
+ </listitem>
+ <listitem>
+ <para>Verify the issue. </para>
+ <para>If the Verifier can conclude that the problem does not exist or the feature/enhancement is now present. </para>
+ </listitem>
+ <listitem>
+ <para>Close the issue. </para>
+ <para>If someone else has already verified the issue then the issue can be closed. </para>
+ </listitem>
+ <listitem>
+ <para>Reopen the issue if the solution is not fully correct </para>
+ <para>If the solution is not correct or the feature/enhancement does not work, it is the duty of the Verifier to reopen the issue. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>Skills: The verifier needs only to focus on that issue, how the problem in it is formulated. He doesn't need to know how it is actually solved. </para>
+ </section>
+ </section>
+
+ <section xml:id="resolve_issue">
+ <title>How to resolve an Issue</title>
+
+ <indexterm>
+ <primary>Issues</primary>
+ <secondary>Resolving</secondary>
+ </indexterm>
+
+ <para>This can be performed by any member of the project (any role). Persons without the Developer role need a person with the Developer role to actually commit the work if the resolution involves changing some artifact. There might be special skills involved but it differs widely depending on the nature of the Issue. </para>
+ <para>Do the following: </para>
+ <orderedlist>
+ <listitem xml:id="resolve_issue_start">
+ <para>Pick any Issue that is NEW or REOPENED that you from the description think that you are able to solve. Best result if you also find some Issue that you really feel needs to be solved. <link
+ xlink:href="http://argouml.tigris.org/issues/buglist.cgi?component=argouml&issue_status=NEW&issue_status=REOPENED"
+ >The list of all of them</link>. </para>
+ </listitem>
+ <listitem>
+ <para>Look at your personal schedule and how much time you have during the next couple of weeks and compare that to the amount of time you think you will need to spend for solving the issue. Compare this to the release plan to see what release your contribution will fit in. </para>
+ </listitem>
+ <listitem>
+ <para>Accept the Issue and reserve it by assigning it to yourself. Set the Target Milestone to the release you have chosen. </para>
+ </listitem>
+ <listitem>
+ <para>Make sure you have a checked out copy of ArgoUML or else check out a new one. </para>
+ <para>How this is done is described in <xref xlink:href="#buildingandtools" />. </para>
+ </listitem>
+ <listitem>
+ <para>Mark the issue as Started (this could be done while assigning also). </para>
+ </listitem>
+ <listitem>
+ <para>Change the code to solve the problem. </para>
+ </listitem>
+ <listitem>
+ <para>Compile and test your new code. </para>
+ <para>This should include developing a JUnit test case to verify that the problem is solved. You could also develop the JUnit test case before actually solving the problem. </para>
+ <para>If your solution did not work as intended, continue changing it until it does. </para>
+ <para>If you feel that your estimation of the complexity of the problem and your own abilities and time available was incorrect, then change the Target Milestone of the Issue to another one that fits your new estimation. This is just a change of plan. </para>
+ <para>If you, at this point, feel that your personal plans have changed so that you won't have time to pursue the work, change the Issue back to "NEW" with your experiences so far stated in the comment. This means that you are giving up and giving the Issue back to anyone. You should also assign it back to issues@argouml or if you know someone else in the ArgoUML team that will continue the work, assign it to him. Remember not to commit your changes in the main branch but please commit your changes (if any) into a work branch and state the name of the branch in the issue. That will make it possible for someone to make use of your work so far. </para>
+ </listitem>
+ <listitem>
+ <para>Commit your changes and the JUnit test cases stating the number of the Issue in the comment. </para>
+ <para>If you don't have a developer role in the project, this involves sending your changes to someone who has and then convincing him to commit them for you. </para>
+ </listitem>
+ <listitem>
+ <para>"Resolve" the Issue with the resolution "FIXED". </para>
+ <para>Also set the target milestone of the upcoming release that will include the fix. </para>
+ </listitem>
+ <listitem>
+ <para>Sit back and feel the personal satisfaction of having completed a something that will be part of the ArgoUML product. </para>
+ </listitem>
+ <listitem>
+ <para>If you during this, have discovered other problems, create new Issues stating those new problems according to the rule for creating Issues. </para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section xml:id="verify_resolved_fixed">
+ <title>How to verify an Issue that is FIXED</title>
+
+ <indexterm>
+ <primary>Issues</primary>
+ <secondary>Verifying Fixed</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Issues</primary>
+ <secondary>Verifying WORKSFORME</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Verifying</primary>
+ <secondary>Works for me Issues</secondary>
+ </indexterm>
+
+ <para>This can be performed by any member of the project (any role). There might be special skills involved but it differs widely depending on the nature of the Issue. </para>
+ <para>If you are the Reporter of the issue, you Close the issue instead. </para>
+ <para>Do the following: </para>
+
+ <orderedlist>
+ <listitem xml:id="verify_resolved_fixed_start">
+ <para>Pick any Issue that is RESOLVED/FIXED or WORKSFORME and that you have not raised, nor solved and that is included in a release (Target milestone set to a release available on the site). <link xlink:href="http://argouml.tigris.org/issues/buglist.cgi?component=argouml&issue_status=RESOLVED&resolution=FIXED&resolution=WORKSFORME" >The list of all RESOLVED/FIXED and RESOLVED/WORKSFORME issues</link>. </para>
+ </listitem>
+ <listitem>
+ <para>Run the specified release of ArgoUML. You can also use any later release. Use ArgoUML provided for downloads or through Java Web Start. </para>
+ </listitem>
+ <listitem>
+ <para>Test the problem in the issue and verify that the problem is no longer there or the feature is provided. </para>
+ </listitem>
+ <listitem>
+ <para>Do one of the following: </para>
+ <itemizedlist>
+ <listitem>
+ <para>If the problem is gone, the feature is present put the Issue in Status VERIFIED and add the version of the ArgoUML used for the test in in the comment. </para>
+ <para>Remark: As an additional activity, the verifier may check if the manual needs to be adapted, and if so, may REOPEN the issue with an explanation text, and setting the correct subcomponent (Documentation & Help). </para>
+ </listitem>
+ <listitem>
+ <para>If the problem is still there, the feature does not work, put the Issue in Status REOPENED with a description of what is still there, is still missing. Also state what version of ArgoUML used for the test in the comment. </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>If you during this, have discovered other problems than the one stated in the Issue, create new Issues for those new problems according to the rule for creating Issues. </para>
+ </listitem>
+ <listitem>
+ <para>Do this as many times as you like until there are no Issues left. </para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section xml:id="verify_resolved_invalid">
+ <title>How to verify an Issue that is rejected</title>
+
+ <indexterm>
+ <primary>Issues</primary>
+ <secondary>Resolving Rejected</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Issues</primary>
+ <secondary>Resolving INVALID</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Issues</primary>
+ <secondary>Resolving WONTFIX</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Issues</primary>
+ <secondary>Resolving DUPLICATE</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Resolving</primary>
+ <secondary>Rejected Issues</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Resolving</primary>
+ <secondary>Invalid Issues</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Resolving</primary>
+ <secondary>WONTFIX Issues</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Resolving</primary>
+ <secondary>DUPLICATE Issues</secondary>
+ </indexterm>
+ <para>This can be performed by any member of the project (any role). There might be special skills involved but it differs widely depending on the nature of the Issue. </para>
+ <para>If you are the Reporter of the issue, you Close the issue instead. </para>
+ <para>Do the following: </para>
+ <orderedlist>
+ <listitem xml:id="verify_resolved_invalid_start">
+ <para>Pick any issue that is RESOLVED/(INVALID, WONTFIX, or DUPLICATE) that you have not raised nor solved. The chosen issue need not be connected to an available release. <link xlink:href="http://argouml.tigris.org/issues/buglist.cgi?component=argouml&issue_status=RESOLVED&resolution=INVALID&resolution=WONTFIX&resolution=DUPLICATE" >The list of all RESOLVED/INVALID, RESOLVED/WONTFIX and RESOLVED/DUPLICATED issues</link>. </para>
+ </listitem>
+ <listitem>
+ <para>Read through the description provided. </para>
+ </listitem>
+ <listitem>
+ <para>Do one of the following: </para>
+ <itemizedlist>
+ <listitem>
+ <para>If you agree with the statement and feel that the rejection is done for correct reasons, put the Issue in Status VERIFIED. </para>
+ </listitem>
+ <listitem>
+ <para>If you don't agree, put the Issue in status REOPENED and give a description as to why you don't agree. </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>Do this as many times as you like until there are no Issues left. </para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section xml:id="close_verified_issue">
+ <title>How to Close an Issue</title>
+
+ <indexterm>
+ <primary>Issues</primary>
+ <secondary>Closing</secondary>
+ </indexterm>
+
+ <para>This is performed by the person that originally raised the Issue, by the QA responsible for that area, or by anyone for issues that are verified. You need to be a member of the project (any role). This can also be done by someone who would raise the issue but did not because it was already present in Issuezilla. </para>
+
+ <orderedlist>
+ <listitem>
+ <para>Pick any Issue that is Verified (<link xlink:href="http://argouml.tigris.org/issues/buglist.cgi?component=argouml&issue_status=VERIFIED" > all VERIFIED issues </link>) or that you have raised or refrained from raising because somebody else already had written it. </para>
+ </listitem>
+ <listitem>
+ <para>See that you are satisfied with the solution. This could involve reading through the resolution and starting the tool to verify it. </para>
+ </listitem>
+ <listitem>
+ <para>Do one of the following: </para>
+ <itemizedlist>
+ <listitem>
+ <para>If you are satisfied, Close the issue. </para>
+ </listitem>
+ <listitem>
+ <para>If you are not satisfied but the problem is solved as it is written in the Issue, Close the issue and open a new Issue with the rest of the problem. </para>
+ </listitem>
+ <listitem>
+ <para>If you are not satisfied and the problem is not solved, put the Issue in status REOPENED with a description on what you are not satisfied with. </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section xml:id="issues_dependencies">
+ <title>How to relate issues to problems in dependencies</title>
+
+ <indexterm>
+ <primary>dependencies</primary>
+ </indexterm>
+
+ <para>ArgoUML uses products internally and is very dependent on that these products are functioning well. This are products like GEF, MDR, OCL, log4j, ⦠</para>
+ <para>Occasionally a problem found in ArgoUML is found to be a problem in one of the dependencies and cannot be or is extremely complicated to fix within ArgoUML. </para>
+ <para>If this happens this is the way to handle this problem. </para>
+ <para>This can be performed by any member of the project (any role). There might be special skills involved depending on the nature of the problem. In this description "issue" means a issue in Issuezilla, "bug report" means a bug report in some other project, and "problem" denotes the conceptual problem. </para>
+ <para>Do the following: </para>
+
+ <orderedlist>
+ <listitem>
+ <para>During your examination of an issue you find that the problem is in one of the ArgoUML dependencies (GEF, MDR, OCL, â¦). </para>
+ </listitem>
+ <listitem>
+ <para>Make sure that the issue is assigned to you. </para>
+ </listitem>
+ <listitem>
+ <para>Write a comment in the issue stating which one of the dependency that has the problem (and what the problem is within that dependency). </para>
+ </listitem>
+ <listitem>
+ <para>Post a bug report in that dependency bug reporting tool (or find that a bug report already registered). </para>
+ <para>I am assuming that there is such a tool for the dependency in question. If there isn't, then make the bug report to the person responsible for this product so that we are sure that the problem is communicated. </para>
+ </listitem>
+ <listitem>
+ <para>Accept the issue (set it to STARTED) and enter the reference from the dependency bug reporting tool and if possible the URL to the bug reporting tool or to the bug report in question. </para>
+ <para>I am assuming that there is a bug reporting tool for the dependency. If there isn't for the product in question, then include all communications (both ways) in the issue. </para>
+ </listitem>
+ </orderedlist>
+
+ <para>You are now responsible to follow up on the upcoming releases of the dependency. If you don't think that you are the best person for this (you should be since it was you that found that this problem is in the dependency), assign the issue to "the right person". To follow up you should do the following. </para>
+
+ <orderedlist>
+ <listitem>
+ <para>Look at each new release of that dependency to see if the bug report is in fact stated as fixed in that release. </para>
+ </listitem>
+ <listitem>
+ <para>If the bug report is fixed, then you weight together the importance of the problem, other bug reports that are also problems in ArgoUML that are solved in that release, the amount of work needed to fit the new version of the dependency instead of the old one, the planned releases of the dependency with promises to solve other bug reports, and the current release plan of ArgoUML. From this you decide whether it is time to do the update of the dependency within ArgoUML or to wait. </para>
+ </listitem>
+ <listitem>
+ <para>If you decide that it is time to update, you assign all issues against that dependency to you (if not already), then you do the work. The work is to add the new version of the dependency to ArgoUML, do all the needed work within ArgoUML to fit the new version, test and commit everything, put the issues indeed fixed in RESOLVED/FIXED, and close the bugs registered in the dependency bug reporting tool. </para>
+ </listitem>
+ </orderedlist>
+
+ <para>For dependencies that are not delivered with ArgoUML (JRE, Xerces, OS, drivers, HW, â¦), the same process is taken except that the issue solved when it is entered in the ArgoUML FAQ or documentation or in some cases as tests in the code testing that we are not using that version. At that point is resolved (as RESOLVED/FIXED). </para>
+ <para>The rationale for this is that we, the development team, help the user to the right version of these by the FAQ and documentation and by code testing the versions. </para>
+ </section>
+
+ <section xml:id="proc-create-stable-releases">
+ <title>How to Create Stable Release</title>
+
+ <para>We have two kinds of releases of ArgoUML: </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Development releases. </para>
+ </listitem>
+ <listitem>
+ <para>Stable releases. </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Stable releases are supposed to be better quality-wise and are always advertised to the users community on the main ArgoUML home page and as a news announcement. </para>
+ <para>Development releases are not supposed to be used by users and are only advertised to users for the purpose of recruiting developers or soliciting help with implementation and test of new features. </para>
+ <para>To increase the quality of a stable release, it is preceded by period during which a sequence of releases with increased quality standards. </para>
+ <para>The whole release schedule leading up to a stable release and patched stable release looks like this: </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Development Period. </para>
+ <para>A period of one to several months where no special restrictions apply. </para>
+ <para>During this period we attempt to make one development release per month. The releases are named x.y.z where y is an odd number and z is counting upwards from 1. </para>
+ <para>The releases are checkpoints where: </para>
+ <itemizedlist>
+ <listitem>
+ <para>Everything compiles (including the sub-projects).</para>
+ </listitem>
+ <listitem>
+ <para>The release script works.</para>
+ </listitem>
+ <listitem>
+ <para>No JUnit tests are failing.</para>
+ </listitem>
+ <listitem>
+ <para>There are no P1 issues.</para>
+ </listitem>
+ </itemizedlist>
+ <para>The releases are used: </para>
+ <itemizedlist>
+ <listitem>
+ <para>As reference points when reporting bugs.</para>
+ </listitem>
+ <listitem>
+ <para>As reference points when verifying issues.</para>
+ </listitem>
+ <listitem>
+ <para>As reference points and convenient downloads for persons working with modules. </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>First Alpha. </para>
+ <para>This is the enhancement freeze point. All enhancements that are not completed and committed in the main trunk before this point will not be included in the stable release. </para>
+ <para>The First Alpha release is named x.y.alpha1 or x.y.ALPHA_1 depending on the context. It marks the end of the Development Period and the start of the Alpha Period. </para>
+ <para>Otherwise it works just like a development release. </para>
+ </listitem>
+ <listitem>
+ <para>Alpha Period. </para>
+ <para>A period of a couple of weeks where special restrictions apply when committing into the main trunk: </para>
+ <itemizedlist>
+ <listitem>
+ <para>Only bug fixes are allowed in the code.</para>
+ <para>Put the number of the DEFECT you are addressing by the commit in the message. </para>
+ <para>Test case code can be added. Documentation, web site and other things can be added. </para>
+ </listitem>
+ </itemizedlist>
+ <para>Exceptions to this are requested to and approved by the Release Responsible before commit. </para>
+ <para>During this period we attempt to make at least one Alpha Release each week. The releases are named <replaceable>x</replaceable>.<replaceable>y</replaceable>.alpha<replaceable>z</replaceable> where <replaceable>y</replaceable> is an even number and <replaceable>z</replaceable> is counting upwards from 1 that is the first alpha. </para>
+ <para>The purpose of the releases and their use are the same as during the development period. </para>
+ </listitem>
+ <listitem>
+ <para>First Beta. </para>
+ <para>This is the bug fixes freeze point. All enhancements and bug fixes that are not completed and committed in the main trunk before this point will not be included in the stable release. A known problems list could be compiled at this point. </para>
+ <para>The first beta release is named <replaceable>x</replaceable>.<replaceable>y</replaceable>.beta1 or <replaceable>x</replaceable>.<replaceable>y</replaceable>.BETA_1 depending on the context. It marks the end of the Alpha Period and the start of the Beta Period. </para>
+ <para>It is the first release candidate for the stable release. Because of this it is required that: </para>
+ <itemizedlist>
+ <listitem>
+ <para>Everything compiles (including the sub-projects).</para>
+ </listitem>
+ <listitem>
+ <para>The release script works.</para>
+ </listitem>
+ <listitem>
+ <para>No JUnit tests are failing.</para>
+ </listitem>
+ <listitem>
+ <para>There are no P1 or P2 issues.</para>
+ </listitem>
+ </itemizedlist>
+ <para>Otherwise it works just like a development release. </para>
+ </listitem>
+ <listitem>
+ <para>Beta Period. </para>
+ <para>A period of a couple of weeks where the focus is quality assurance. Every developer should strive to: </para>
+ <itemizedlist>
+ <listitem>
+ <para>Test ArgoUML as thoroughly as possible. Especially the areas that are new or changed since the last release. </para>
+ </listitem>
+ <listitem>
+ <para>Verify issues that are resolved. </para>
+ </listitem>
+ <listitem>
+ <para>Scrutinize the commits in the main trunk to see that no new bugs are introduced. </para>
+ </listitem>
+ </itemizedlist>
+ <para>Extreme caution applies when committing into the main trunk. Only under the following conditions are commits allowed: </para>
+ <itemizedlist>
+ <listitem>
+ <para>It is a fix to some DEFECT that was previously fixed but it was found during the verification that the solution was not correct or complete. </para>
+ <para>Reopen the DEFECT when the problem is found with a statement of what is still the problem. Put the number of the DEFECT you are addressing by the commit in the message together with the statement of the part of the problem. Resolve the DEFECT as FIXED and update the target milestone with the release name of the next beta. </para>
+ <para>Test case code can still be added. Final documentation and web site updates for the release are done. </para>
+ </listitem>
+ <listitem>
+ <para>All JUnit test cases are run from a cleaned checked out copy at the commit and no problems are found. </para>
+ </listitem>
+ </itemizedlist>
+ <para>Exceptions to this are requested and approved by the Release Responsible before commit. </para>
+ <para>If a new problem is found the following needs to be done before committing the solution: </para>
+ <itemizedlist>
+ <listitem>
+ <para>The problem is registered as a DEFECT. </para>
+ </listitem>
+ <listitem>
+ <para>The solution is implemented. </para>
+ <para>Here the requirement is a high on the quality and low impact of the solution. </para>
+ </listitem>
+ <listitem>
+ <para>A request is made to the Release Responsible to allow this change. </para>
+ </listitem>
+ <listitem>
+ <para>This is granted by the Release Responsible. </para>
+ </listitem>
+ </itemizedlist>
+ <para>During the period we attempt to release at least one beta release each week. The releases are named <replaceable>x</replaceable>.<replaceable>y</replaceable>.beta<replaceable>z</replaceable> where <replaceable>y</replaceable> is an even number and <replaceable>z</replaceable> is counting upwards from 1 that is the first beta. </para>
+ <para>Each release is a release candidate. When we have reached the point where no more issues are verified and we are confident that there are no more problems in this release we make the stable release without code changes compared to the last beta. </para>
+ </listitem>
+ <listitem>
+ <para>Stable Release. </para>
+ <para>This marks the end of the Alpha and Beta Period and the start of the next Development Period. </para>
+ <para>The release is named <replaceable>x</replaceable>.<replaceable>y</replaceable> where <replaceable>y</replaceable> is an even number. </para>
+ <para>The release is used: </para>
+ <itemizedlist>
+ <listitem>
+ <para>By all users.</para>
+ </listitem>
+ </itemizedlist>
+ <para>It can also be used as a development release. </para>
+ </listitem>
+ <listitem>
+ <para>A Stable Patch Release. </para>
+ <para>If we find a serious problem in the stable release we can decide to make a Stable Patch Release. </para>
+ <para>The following needs to be done before committing the solution: </para>
+ <itemizedlist>
+ <listitem>
+ <para>The problem is registered as a DEFECT stating that it is a problem in the Stable Release or a previous Stable Patch Release. </para>
+ </listitem>
+ <listitem>
+ <para>A working branch is created against the release tag of the Stable Release or Stable Patch Release and the solution is implemented in that branch. </para>
+ <para>Here the requirement is a high on the quality and low impact of the solution. </para>
+ </listitem>
+ <listitem>
+ <para>We decide that it is a serious problem and that we are going to do a Stable Patch Release. </para>
+ </listitem>
+ <listitem>
+ <para>Several developers scrutinize the solution, testing and verifying in the branch of the issue. </para>
+ </listitem>
+ <listitem>
+ <para>The Release Responsible creates a branch. If this is not the first Stable Patch Release the branch is reused. </para>
+ </listitem>
+ <listitem>
+ <para>The Release Responsible merges the solution into the branch. </para>
+ <para>A Stable Patch Release could contain several issues resolved. In that case they are all merged. </para>
+ </listitem>
+ <listitem>
+ <para>Several developers scrutinize the merge, testing and verifying in the release branch. </para>
+ </listitem>
+ </itemizedlist>
+ <para>The release is named <replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable> where <replaceable>y</replaceable> is an even number, and <replaceable>z</replaceable> is counting upwards from 1. </para>
+ <para>The release is used: </para>
+ <itemizedlist>
+ <listitem>
+ <para>By all users.</para>
+ </listitem>
+ </itemizedlist>
+ <para>After the release is completed the person working with the solution commits his solution also in the main trunk if still applicable there. </para>
+ </listitem>
+ </itemizedlist>
+ </section>
</chapter>
-
-
<!-- Local stuff for Emacs - please do not delete
Local Variables:
@@ -1492,4 +732,4 @@
indent-tabs-mode: nil
End:
--->
+-->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/repository.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/repository.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/repository.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/repository.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/repository.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/repository.xml 2008-01-15 19:22:21-0800
@@ -1,32 +1,40 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
-// 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.
+ // 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.
-->
-<appendix id="repository-contents">
+<appendix
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xml:id="repository-contents">
+
<title>Repository Contents</title>
+
<indexterm>
<primary>SVN Repository Contents</primary>
</indexterm>
@@ -36,148 +44,148 @@
<indexterm>
<primary>Contents of the SVN repository at Tigris</primary>
</indexterm>
-
+
<para>
-This appendix describes what parts of the repository is used for
-what purpose.
-This is a rather terse collection.
-Further details on specific parts can sometimes be found elsewhere in
-this document.
-</para>
-
+ This appendix describes what parts of the repository is used for
+ what purpose.
+ This is a rather terse collection.
+ Further details on specific parts can sometimes be found elsewhere in
+ this document.
+ </para>
+
<note>
<para>
-<!-- TODO: Explain the different projects. -->
-This explanation only describes the single Tigris project layout.
-Lately (since beginning of 2006) we have been working with splitting
-the project over several Tigris projects.
-This is not yet described here.
-</para>
+ <!-- TODO: Explain the different projects. -->
+ This explanation only describes the single Tigris project layout.
+ Lately (since beginning of 2006) we have been working with splitting
+ the project over several Tigris projects.
+ This is not yet described here.
+ </para>
</note>
-
+
<para>
-This chapter is organized as the repository itself and
-everything is in alphabetical order.
-</para>
+ This chapter is organized as the repository itself and
+ everything is in alphabetical order.
+ </para>
<para>
-This is the normal structure for any argouml jar file and project.
-</para>
+ This is the normal structure for any argouml jar file and project.
+ </para>
<itemizedlist>
<listitem>
<para><filename>build.xml</filename></para>
<para>
-The file controlling the build of that subsystem.
-</para>
+ The file controlling the build of that subsystem.
+ </para>
<para>
-When built, the result end up in a newly created build directory.
-</para>
+ When built, the result end up in a newly created build directory.
+ </para>
</listitem>
-
+
<listitem>
<para><filename class="directory">build</filename></para>
<para>
-Directory where the built things end up when building with ant.
-</para>
+ Directory where the built things end up when building with ant.
+ </para>
<para>
-This is not kept in the repository. It is created by the build.
-For historic reasons this actually exists in the CVS repository
-of some of the projects.
-This will be fixed after the move to SVN.
-</para>
+ This is not kept in the repository. It is created by the build.
+ For historic reasons this actually exists in the CVS repository
+ of some of the projects.
+ This will be fixed after the move to SVN.
+ </para>
</listitem>
<listitem>
<para><filename class="directory">build-eclipse</filename></para>
<para>
-Directory where the built things end up when building with Eclipse.
-</para>
+ Directory where the built things end up when building with Eclipse.
+ </para>
<para>
-This is not kept in the repository. It is created by the build.
-</para>
+ This is not kept in the repository. It is created by the build.
+ </para>
</listitem>
<listitem>
<para><filename class="directory">lib</filename></para>
<para>jar files used by the project.</para>
<para>
-This directory contains the jar files of products that are shipped with
-the project i.e. needed to run the project.
-For ArgoUML this is things like log4j, gef, ...
-</para>
- <para>
-These are distributed with ArgoUML and have licenses that allow this.
-For clarity the README files and licenses and other distribution
-details of each used jar will also be stored in this directory.
-(Quick summary: BSD License, Apache License, LGPL are OK, GPL is not.)
-Don't forget to arrange for the modules version and license information
-to appear when starting ArgoUML and in the About box.
-</para>
- <para>
-Take care also to make the versions of these libraries explicit,
-so as to allow people building from sources to figure out
-exact dependencies. Easiest way is to rename the files to
-include version information, the same way as shared
-libraries in Unix world: foo-x.y.z.jar, bar-x.y.z.jar,
-etc...
-</para>
+ This directory contains the jar files of products that are shipped with
+ the project i.e. needed to run the project.
+ For ArgoUML this is things like log4j, gef, â¦
+ </para>
+ <para>
+ These are distributed with ArgoUML and have licenses that allow this.
+ For clarity the README files and licenses and other distribution
+ details of each used jar will also be stored in this directory.
+ (Quick summary: BSD License, Apache License, LGPL are OK, GPL is not.)
+ Don't forget to arrange for the modules version and license information
+ to appear when starting ArgoUML and in the About box.
+ </para>
+ <para>
+ Take care also to make the versions of these libraries explicit,
+ so as to allow people building from sources to figure out
+ exact dependencies. Easiest way is to rename the files to
+ include version informations, the same way as shared
+ libraries in Unix world: foo-x.y.z.jar, bar-x.y.z.jar,
+ etcâ¦
+ </para>
</listitem>
<listitem>
<para><filename class="directory">src</filename></para>
<para>
-Source code.
-</para>
+ Source code.
+ </para>
<para>
-This directory contains exactly one java class tree
-that is build into exactly one jar file.
-</para>
+ This directory contains exactly one java class tree
+ that is build into exactly one jar file.
+ </para>
</listitem>
-
+
<listitem>
<para><filename class="directory">tests</filename></para>
<para>
-Source code for JUnit tests of everything that is in the src directory.
-See <xref linkend="junittests"/>.
-</para>
+ Source code for JUnit tests of everything that is in the src directory.
+ See <xref xlink:href="junittests"/>.
+ </para>
<para>
-This directory contains exactly one java class tree.
-</para>
+ This directory contains exactly one java class tree.
+ </para>
</listitem>
-
+
<listitem>
<para><filename class="directory">tools</filename></para>
<para>
-Tools used during the build process.
-</para>
+ Tools used during the build process.
+ </para>
<para>
-Tools also have the readme files, licenses and other distribution files
-stored in this directory in much the same way as the libraries in
-<filename class="directory">lib</filename>.
-However the requirement on the license is different.
-The tools are never distributed with ArgoUML but merely used in the
-development of ArgoUML so it is enough to have a license that does not
-allow distribution.
-(Quick summary: BSD License, Apache license, LGPL, GPL, Freeware are OK.)
-</para>
+ Tools also have the readme files, licenses and other distribution files
+ stored in this directory in much the same way as the libraries in
+ <filename class="directory">lib</filename>.
+ However the requirement on the license is different.
+ The tools are never distributed with ArgoUML but merely used in the
+ development of ArgoUML so it is enough to have a license that does not
+ allow distribution.
+ (Quick summary: BSD License, Apache license, LGPL, GPL, Freeware are OK.)
+ </para>
</listitem>
</itemizedlist>
-
-
+
+
<para>
-Because of they way the Tigris site works there is also the following:
-</para>
-
+ Because of they way the Tigris site works there is also the following:
+ </para>
+
<itemizedlist>
<listitem>
<para><filename class="directory">www</filename></para>
<para>
-This is all the static contents of the web site.
-</para>
+ This is all the static contents of the web site.
+ </para>
</listitem>
</itemizedlist>
-
+
<para>
-For historic reasons the argouml project i.e. the main project
-looks a little bit different.
-</para>
-
+ For historic reasons the argouml project i.e. the main project
+ looks a little bit different.
+ </para>
+
<itemizedlist>
<listitem>
<para><filename class="directory">documentation</filename></para>
@@ -190,9 +198,9 @@
<listitem>
<para><filename class="directory">docbook-setup</filename></para>
<para>
-XML Tools and configuration files used for the formatting of
-the documentation from the XML-source to HTML and PDF.
-</para>
+ XML Tools and configuration files used for the formatting of
+ the documentation from the XML-source to HTML and PDF.
+ </para>
</listitem>
<listitem>
<para><filename class="directory">images</filename></para>
@@ -211,68 +219,68 @@
<para>XML-source code for the Quick Guide.</para>
</listitem>
</itemizedlist>
-
+
<para>
-It is not yet decided how to handle the User Manual in other languages.
-It is probably best if they reside in the documentation directory in
-the subproject for that language.
-That would make the correct group of developers get access to the files
-without special features.
-</para>
-
- <para>
-Documentation for features and functions provided by other projects
-are, for the time being, best kept in the one big User Manual.
-</para>
+ It is not yet decided how to handle the User Manual in other languages.
+ It is probably best if they reside in the documentation directory in
+ the subproject for that language.
+ That would make the correct group of developers get access to the files
+ without special features.
+ </para>
+
+ <para>
+ Documentation for features and functions provided by other projects
+ are, for the time being, best kept in the one big User Manual.
+ </para>
</listitem>
-
-
+
+
<listitem>
<para><filename class="directory">modules</filename></para>
<para>Old module structure. To be removed.</para>
</listitem>
-
+
<listitem>
<para><filename class="directory">src</filename></para>
<para>
-In conflict with the description above
-this directory contains one directory for each subsystem within ArgoUML.
-Each directory is a complete tree as described above.
-</para>
+ In conflict with the description above
+ this directory contains one directory for each subsystem within ArgoUML.
+ Each directory is a complete tree as described above.
+ </para>
</listitem>
-
+
<listitem>
<para><filename class="directory">src_new</filename></para>
<para>
-All source code for ArgoUML including pictures of icons.
-</para>
+ All source code for ArgoUML including pictures of icons.
+ </para>
<para>
-This is replacing the <filename class="directory">src</filename> directory
-above with the exception that it also contains the build.xml file.
-</para>
+ This is replacing the <filename class="directory">src</filename> directory
+ above with the exception that it also contains the build.xml file.
+ </para>
</listitem>
-
+
</itemizedlist>
-
+
<para>
-The ArgoUML subprojects are projects on Tigris that belong to the
-ArgoUML project.
-To simplify the administration, they are all set up in the same way, i.e.
-as describe above.
-</para>
-
+ The ArgoUML subprojects are projects on Tigris that belong to the
+ ArgoUML project.
+ To simplify the administration, they are all set up in the same way, i.e.
+ as describe above.
+ </para>
+
</appendix>
<!-- Local stuff for Emacs - please do not delete
-
-Local Variables:
-mode: xml
-sgml-doctype: "cookbook.xml"
-sgml-parent-document: ("cookbook.xml" "chapter" nil)
-sgml-validate-command: "nsgmls -wxml -sv ../docbook-setup/xml.dcl \
+
+ Local Variables:
+ mode: xml
+ sgml-doctype: "cookbook.xml"
+ sgml-parent-document: ("cookbook.xml" "chapter" nil)
+ sgml-validate-command: "nsgmls -wxml -sv ../docbook-setup/xml.dcl \
cookbook.xml"
-indent-tabs-mode: nil
-End:
-
--->
+ indent-tabs-mode: nil
+ End:
+
+-->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/require.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/require.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/require.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/require.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/require.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/require.xml 2008-01-15 19:22:21-0800
@@ -1,428 +1,210 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
-// Copyright (c) 1996-2006 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.
+ // Copyright (c) 1996-2006 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.
-->
- <chapter id="requirements">
- <chapterinfo>
- <authorgroup>
- <author>
- <firstname>Linus</firstname>
- <surname>Tolke</surname>
- </author>
- </authorgroup>
- </chapterinfo>
- <title>ArgoUML requirements</title>
-
- <para>
-This chapter contains a description on how ArgoUML should work
-and behave for the users.
-</para>
-
- <para>
-These things might not be implemented yet and the solutions
-might not even be clear but it is a definition of the goal.
-</para>
- <para>
-The fact that it is not implemented or doesn't work as stated here
-should be registered as a bug
-in the bug registering tool.
-</para>
- <para>
-Every requirement has
-a number (REQ1, REQ2, REQ3, ...) that never changes,
-a revision (REVa, REVb, REVc, ...) that changes when the requirement change,
-a text that is the requirement text to implement,
-a rationale that is the description of why the requirement is important,
-and a stakeholder, i.e. a person or group that the requirement is
-important to.
-</para>
-
- <sect1>
- <title>Requirements for Look and feel</title>
- <para>
-This describes how the ArgoUML look and feel shall behave.
-</para>
- <sect2 id="REQ1">
- <title>
-When multiple visual components are showing the same model element
-they shall be updated in a consistent manner throughout the application.
-</title>
- <para>
-REQ1 REVa
-</para>
- <para>
-<emphasis>Rationale:</emphasis>
-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.
-</para>
- <para>
-<emphasis>Stakeholder:</emphasis>
-User of ArgoUML
-</para>
- </sect2>
-
- <sect2 id="REQ2">
- <title>
-All views of a model element shall be updated
-as soon as the model element is updated.
-</title>
- <para>
-REQ2 REVb
-</para>
- <para>
-<emphasis>Rationale:</emphasis>
-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.
-</para>
- <para>
-<emphasis>Stakeholder:</emphasis>
-User of ArgoUML
-</para>
- </sect2>
-
- <sect2 id="REQ11">
- <title>
-Editable views of the model should update the model
-on each keystroke and mouse click.
-</title>
- <para>
-REQ11 REVa
-</para>
- <para>
-<emphasis>Rationale:</emphasis>
-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.
-</para>
- <para>
-<emphasis>Stakeholder:</emphasis>
-User of ArgoUML
-</para>
- </sect2>
-
- <sect2 id="REQ12">
- <title>
-Any text fields that require validation
-should not be editable directly from a view.
-</title>
- <para>
-REQ12 REVa
-</para>
- <para>
-<emphasis>Rationale:</emphasis>
-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.
-</para>
- <para>
-<emphasis>Stakeholder:</emphasis>
-User of ArgoUML.
-TODO: Is this the correct stakeholder?
-</para>
- </sect2>
-
- <sect2 id="REQ13">
- <title>
-With dialogs, the model is not updated until the dialog
-is accepted by the user
-with valid fields.
-</title>
- <para>
-REQ13 REVa
-</para>
- <para>
-<emphasis>Rationale:</emphasis>
-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.
-</para>
- <para>
-<emphasis>Stakeholder:</emphasis>
-User of ArgoUML.
-</para>
- </sect2>
-
- <sect2 id="REQ14">
- <title>
-The user shall receive some visual feedback during
-the edit process of textual UML to indicate whether
-the text represents valid UML syntax.
-</title>
- <para>
-REQ14 REVa
-</para>
- <para>
-<emphasis>Rationale:</emphasis>
-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?
-</para>
- <para>
-<emphasis>Stakeholder:</emphasis>
-User of ArgoUML.
-</para>
- </sect2>
-
- <sect2 id="REQ3">
- <title>
-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.
-</title>
- <para>
-REQ3 REVa
-</para>
- <para>
-<emphasis>Rationale:</emphasis>
-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.
-</para>
- <para>
-<emphasis>Stakeholder:</emphasis>
-User of ArgoUML
-</para>
- </sect2>
-
- <sect2 id="REQ4">
- <title>
-All text fields shall have context sensitive help.
-</title>
- <para>
-As follows:
-<orderedlist>
- <listitem>
- <para>
-A tooltip that explains the data and format expected by the
-particular field.
-</para>
- <para>
-This can be omitted when there is a header stating the data of
-the field and the format is obvious.
-</para>
- </listitem>
- <listitem>
- <para>
-Pressing F1 or choosing help from the menu shall display a popup
-window explaining the data and format required by the current input
-field.
-Input focus shall be left on the field during any user
-interaction with the popup (dragging, scrolling or closing).
-</para>
- </listitem>
- </orderedlist>
-</para>
- <para>
-REQ4 REVa
-</para>
- <para>
-<emphasis>Rationale:</emphasis>
-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.
-</para>
- <para>
-<emphasis>Stakeholder:</emphasis>
-User of ArgoUML
-</para>
-
- </sect2>
- </sect1>
-
- <sect1>
- <title>Requirements for UML</title>
- <sect2 id="REQ5">
- <title>
-ArgoUML shall be a correct implementation of the UML 1.4 model.
-</title>
- <para>
-REQ5 REVa
-</para>
- <para>
-<emphasis>Rationale:</emphasis>
-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.
-</para>
- <para>
-<emphasis>Stakeholder:</emphasis>
-User of ArgoUML
-</para>
- </sect2>
- <sect2 id="REQ6">
- <title>
-ArgoUML shall implement everything in the UML 1.4 model.
-</title>
- <para>
-REQ6 REVa
-</para>
- <para>
-<emphasis>Rationale:</emphasis>
-The ambition is to implement all of UML.
-This means that no matter how you use UML ArgoUML will always be
-a working tool.
-</para>
- <para>
-<emphasis>Stakeholder:</emphasis>
-User of ArgoUML
-</para>
-
- </sect2>
- </sect1>
-
- <sect1>
- <title>Requirements on java and jvm</title>
- <sect2 id="REQ7">
- <title>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.
-</title>
- <para>
-REQ7 REVb
-</para>
- <para>
-<emphasis>Rationale:</emphasis>
-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.
-</para>
- <para>
-Note: J2SE 1.3.1 begun its Sun End of Life (EOL) process
-on October 25, 2004.
-</para>
- <para>
-<emphasis>Stakeholder:</emphasis>
-Developers of ArgoUML
-</para>
- </sect2>
-
- <sect2 id="REQ8">
- <title>Download and start</title>
- <para>
-It shall be possible to install ArgoUML locally on the machine
-and use without Internet connection.
-</para>
- <para>
-REQ8 REVa
-</para>
- <para>
-<emphasis>Rationale:</emphasis>
-ArgoUML is an application that edits an UML model.
-There is no need to have any network defined while doing this.
-</para>
- <para>
-<emphasis>Stakeholder:</emphasis>
-User of ArgoUML
-</para>
- </sect2>
-
- <sect2 id="REQ9">
- <title>
-Console output:
-Logging or tracing information shall not be written to the console
-or to any file unless explicitly turned on by the user.
-</title>
- <para>
-REQ9 REVa
-</para>
- <para>
-<emphasis>Rationale:</emphasis>
-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.
-</para>
- <para>
-<emphasis>Stakeholder:</emphasis>
-User of ArgoUML
-</para>
-
- </sect2>
- </sect1>
-
- <sect1>
- <title>Requirements set up for the benefit of the development of ArgoUML</title>
- <sect2 id="REQ10">
- <title>
-Logging:
-The code shall contain entries logging important information
-for the purpose of helping Developers of ArgoUML in finding problems
-in ArgoUML itself.
-</title>
- <para>
-REQ10 REVa
-</para>
- <para>
-<emphasis>Rationale:</emphasis>
-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.
-</para>
- <para>
-<emphasis>Stakeholder:</emphasis>
-Developers of ArgoUML
-</para>
-
- </sect2>
- </sect1>
-
- </chapter>
-
-
+<chapter
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xml:id="requirements">
+
+ <title>ArgoUML requirements</title>
+
+ <info>
+ <authorgroup>
+ <author>
+ <personname><firstname>Linus</firstname>
+ <surname>Tolke</surname></personname>
+ </author>
+ </authorgroup>
+ </info>
+
+
+
+ <para>This chapter contains a description on how ArgoUML should work and behave for the users. </para>
+ <para>These things might not be implemented yet and the solutions might not even be clear but it is a definition of the goal. </para>
+ <para>The fact that it is not implemented or doesn't work as stated here should be registered as a bug in the bug registering tool. </para>
+ <para>Every requirement has a number (REQ1, REQ2, REQ3, â¦) that never changes, a revision (REVa, REVb, REVc, â¦) that changes when the requirement change, a text that is the requirement text to implement, a rationale that is the description on why this is important, a stakeholder that is one of the stakeholders in the vision for who this is important. </para>
+
+ <section>
+ <title>Requirements for Look and feel</title>
+
+ <para>This describes how the ArgoUML look and feel shall behave. </para>
+
+ <section xml:id="REQ1">
+ <title> When multiple visual components are showing the same model element they shall be updated in a consistent manner throughout the application. </title>
+
+ <para>REQ1 REVa </para>
+ <para><emphasis>Rationale:</emphasis> 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. </para>
+ <para><emphasis>Stakeholder:</emphasis> User of ArgoUML </para>
+ </section>
+
+ <section xml:id="REQ2">
+ <title> All views of a model element shall be update as soon as the model element is updated. </title>
+
+ <para>REQ2 REVb </para>
+ <para><emphasis>Rationale:</emphasis> 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. </para>
+ <para><emphasis>Stakeholder:</emphasis> User of ArgoUML </para>
+ </section>
+
+ <section xml:id="REQ11">
+ <title> Editable views of the model should update the model on each keystroke and mouse click. </title>
+
+ <para>REQ11 REVa </para>
+ <para><emphasis>Rationale:</emphasis> 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. </para>
+ <para><emphasis>Stakeholder:</emphasis> User of ArgoUML </para>
+ </section>
+
+ <section xml:id="REQ12">
+ <title> Any text fields that require validation should not be editable directly from a view. </title>
+
+ <para>REQ12 REVa </para>
+ <para><emphasis>Rationale:</emphasis> 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. </para>
+ <para><emphasis>Stakeholder:</emphasis> User of ArgoUML. TODO: Is this the correct stakeholder? </para>
+ </section>
+
+ <section xml:id="REQ13">
+ <title> With dialogs, the model is not updated until the dialog is accepted by the user with valid fields. </title>
+
+ <para>REQ13 REVa </para>
+ <para><emphasis>Rationale:</emphasis> 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. </para>
+ <para><emphasis>Stakeholder:</emphasis> User of ArgoUML. </para>
+ </section>
+
+ <section xml:id="REQ14">
+ <title> The user shall receive some visual feedback during the edit process of textual UML to indicate whether the text represents valid UML syntax. </title>
+
+ <para>REQ14 REVa </para>
+ <para><emphasis>Rationale:</emphasis> Writing a correct syntax of anything 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 to as quickly as possible, get the syntax right. TODO: Is this the correct motivation for this? </para>
+ <para><emphasis>Stakeholder:</emphasis> User of ArgoUML. </para>
+ </section>
+
+ <section xml:id="REQ3">
+ <title> 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. </title>
+
+ <para>REQ3 REVa </para>
+ <para><emphasis>Rationale:</emphasis> 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 loose interest in ArgoUML as a tool because he percieves it as not working correctly. </para>
+ <para><emphasis>Stakeholder:</emphasis> User of ArgoUML </para>
+ </section>
+
+ <section xml:id="REQ4">
+ <title> All text fields shall have context sensitive help. </title>
+
+ <para>As follows:
+ <orderedlist>
+ <listitem>
+ <para>A tooltip that explains the data and format expected by the particular field. </para>
+ <para>This can be omitted when there is a header stating the data of the field and the format is obvious. </para>
+ </listitem>
+ <listitem>
+ <para>Pressing F1 or choosing help from the menu shall display a popup window explaining for data and format required by the current input field. Input focus shall be left on the field during any user interaction with the popup (dragging, scrolling or closing). </para>
+ </listitem>
+ </orderedlist>
+ </para>
+
+ <para>REQ4 REVa </para>
+ <para><emphasis>Rationale:</emphasis> 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. </para>
+ <para><emphasis>Stakeholder:</emphasis> User of ArgoUML </para>
+ </section>
+ </section>
+
+ <section>
+ <title>Requirements for UML</title>
+
+ <section xml:id="REQ5">
+ <title> ArgoUML shall be a correct implementation of the UML 1.4 model. </title>
+
+ <para>REQ5 REVa </para>
+ <para><emphasis>Rationale:</emphasis> 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. </para>
+ <para><emphasis>Stakeholder:</emphasis> User of ArgoUML </para>
+ </section>
+
+ <section xml:id="REQ6">
+ <title> ArgoUML shall implement everything in the UML 1.4 model. </title>
+
+ <para>REQ6 REVa </para>
+ <para><emphasis>Rationale:</emphasis> The ambition is to implement all of UML. This means that no matter how you use UML ArgoUML will always be a working tool. </para>
+ <para><emphasis>Stakeholder:</emphasis> User of ArgoUML </para>
+ </section>
+ </section>
+
+ <section>
+ <title>Requirements on java and jvm</title>
+
+ <section xml:id="REQ7">
+ <title>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. </title>
+
+ <para>REQ7 REVb </para>
+ <para><emphasis>Rationale:</emphasis> 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. </para>
+ <para>Note: J2SE 1.3.1 begun its Sun End of Life (EOL) process on October 25, 2004. </para>
+ <para><emphasis>Stakeholder:</emphasis> Developers of ArgoUML </para>
+ </section>
+
+ <section xml:id="REQ8">
+ <title>Download and start</title>
+
+ <para>It shall be possible to install ArgoUML locally on the machine and use without Internet connection. </para>
+ <para>REQ8 REVa </para>
+ <para><emphasis>Rationale:</emphasis> ArgoUML is an application that edits an UML model. There is no need to have any network defined while doing this. </para>
+ <para><emphasis>Stakeholder:</emphasis> User of ArgoUML </para>
+ </section>
+
+ <section xml:id="REQ9">
+ <title> Console output: Logging or tracing information shall not be written to the console or to any file unless explicitly turned on by the user. </title>
+
+ <para>REQ9 REVa </para>
+ <para><emphasis>Rationale:</emphasis> 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. </para>
+ <para><emphasis>Stakeholder:</emphasis> User of ArgoUML </para>
+ </section>
+ </section>
+
+ <section>
+ <title>Requirements set up for the benefit of the development of ArgoUML</title>
+
+ <section xml:id="REQ10">
+ <title> Logging: The code shall contain entries logging important information for the purpose of helping Developers of ArgoUML in finding problems in ArgoUML itself. </title>
+
+ <para>REQ10 REVa </para>
+ <para><emphasis>Rationale:</emphasis> 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. </para>
+ <para><emphasis>Stakeholder:</emphasis> Developers of ArgoUML </para>
+ </section>
+ </section>
+
+</chapter>
<!-- Local stuff for Emacs - please do not delete
-
-Local Variables:
-mode: xml
-sgml-doctype: "cookbook.xml"
-sgml-parent-document: ("cookbook.xml" "chapter" nil)
-sgml-validate-command: "nsgmls -wxml -sv ../docbook-setup/xml.dcl \
- cookbook.xml"
-indent-tabs-mode: nil
-End:
-
--->
+
+ Local Variables:
+ mode: xml
+ sgml-doctype: "cookbook.xml"
+ sgml-parent-document: ("cookbook.xml" "chapter" nil)
+ sgml-validate-command: "nsgmls -wxml -sv ../docbook-setup/xml.dcl \
+ cookbook.xml"
+ indent-tabs-mode: nil
+ End:
+
+-->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/standard.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/standard.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/standard.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/standard.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/standard.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/standard.xml 2008-01-15 19:22:21-0800
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
// Copyright (c) 1996-2007 The Regents of the University of California. All
@@ -25,35 +25,35 @@
// UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
-->
-<chapter id="standards">
- <title>Standards for coding in ArgoUML</title>
- <indexterm>
- <primary>Coding Standards</primary>
- </indexterm>
- <indexterm>
- <primary>Standards</primary>
- <secondary>Coding</secondary>
- </indexterm>
- <sect1>
- <title>When Writing Java Code</title>
-
- <para>
-The coding style for ArgoUML is based on the
-<ulink url="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">
-Code Conventions for the Java Programming Language
-</ulink>.
-We have the following exceptions and comments:
-</para>
- <itemizedlist>
- <listitem>
- <para>
-Each file starts with some header info:
-file,
-version info,
-copyright notice.
-Like this:
-<programlisting>
-// $Id$
+<chapter
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xml:id="standards"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink">
+
+ <title>Standards for coding in ArgoUML</title>
+
+ <indexterm>
+ <primary>Coding Standards</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Standards</primary>
+ <secondary>Coding</secondary>
+ </indexterm>
+
+ <section>
+ <title>When Writing Java Code</title>
+
+ <para>The coding style for ArgoUML is based on the <uri xlink:href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">Code Conventions for the Java Programming Language</uri>. We have the following exceptions and comments: </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Each file starts with some header info: file, version info, copyright notice. Like this:
+
+ <programlisting>
+// $Id$
// Copyright (c) 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
@@ -77,778 +77,313 @@
// CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT,
// UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
-package <replaceable>whatever</replaceable>;
+package <package><replaceable>whatever</replaceable></package>;
<replaceable>...</replaceable>
-</programlisting>
-</para>
- <para>
-The file and version is maintained by subversion using keyword substitution.
-Remember to set the property "svn:keywords" to "Id" on all source files.
-The year in the copyright notice is maintained manually.
-</para>
- <para>
-This differs from the Sun Code Conventions that
-requires the initial comment to be a C-style comment.
-</para>
- <para>
-This is checked by Checkstyle.
-</para>
- </listitem>
- <listitem>
- <para>
-All instance variables are private.
-</para>
- <para>
-This is not required by the Sun Code Conventions but
-an additional requirement for ArgoUML.
-</para>
- <para>
-This is checked by Checkstyle.
-</para>
- </listitem>
- <listitem>
- <para>
-Use Javadoc for each class, instance variable, and
-methods that are not overriding or implementing a method
-from an interface or extended class.
-In general do not put comments in the body of a method.
-If you are doing something complex enough to need a comment, consider
-breaking it out into its own private commented method.
-</para>
- <para>
-If you are overriding or implementing a method and
-you want to describe specifics of the implementation,
-use the Javadoc and reference the overridden or implemented method.
-</para>
- <para>
-This is not required by the Sun Code Conventions but
-an additional requirement for ArgoUML.
-</para>
- <para>
-This is partly checked by Checkstyle.
-Checkstyle does currently only warn if a Javadoc comment is omitted for
-public, protected or default visibility variables.
-</para>
- </listitem>
- <listitem>
- <para>
+ </programlisting>
+
+ </para>
+
+ <para>The file and version is maintained by subversion using keyword substitution. Remember to set the property "svn:keywords" to "Id" on all source files. The year in the copyright notice is maintained manually. </para>
+ <para>This differs from the Sun Code Conventions that requires the initial comment to be a C-style comment. </para>
+ <para>This is checked by Checkstyle. </para>
+ </listitem>
+ <listitem>
+ <para>All instance variables are private. </para>
+ <para>This is not required by the Sun Code Conventions but an additional requirement for ArgoUML. </para>
+ <para>This is checked by Checkstyle. </para>
+ </listitem>
+ <listitem>
+ <para>Use Javadoc for each class, instance variable, and methods that are not overriding or implementing a method from an interface or extended class. In general do not put comments in the body of a method. If you are doing something complex enough to need a comment, consider breaking it out into its own private commented method. </para>
+ <para>If you are overriding or implementing a method and you want to describe specifics of the implementation, use the Javadoc and reference the overridden or implemented method. </para>
+ <para>This is not required by the Sun Code Conventions but an additional requirement for ArgoUML. </para>
+ <para>This is partly checked by Checkstyle. Checkstyle does currently only warn if a Javadoc comment is omitted for a public, protected or default visibility variables. </para>
+ </listitem>
+
+ <listitem>
+ <para>
Indicate places of future modifications with
<programlisting>
// TODO: reason and explanation
</programlisting>
+
or if within a Javadoc or c-style comment
-<programlisting>
+
+ <programlisting>
* TODO: reason and explanation
</programlisting>
-</para>
- <para>
-This differs from the Sun Code Conventions that
-uses either XXX or FIXME depending on if it works or not.
-</para>
- </listitem>
- <listitem>
- <para>
-Four spaces should be used as the unit of indentation.
-Tabs must be set exactly every 8 spaces (not 4) and represent 2 indents.
-</para>
- <para>
-This is exactly as it is stated in the Sun Code Conventions.
-It is here just for emphasis.
-</para>
- <para>
-This is checked by Checkstyle.
-</para>
- </listitem>
- <listitem>
- <para>
-If possible use lines shorter than 80 characters wide.
-</para>
- <para>
-This is exactly as it is stated in the Sun Code Conventions.
-It is here just for the emphasis.
-</para>
- <para>
-This is checked by Checkstyle.
-Checkstyle ignores three kinds of lines in this check because of the
-historical use of long class names and package names.
-These are lines that contain
-"@see <replaceable>some method name</replaceable>",
-"// $Id:<replaceable>whatever</replaceable>$", and
-import statements.
-</para>
- </listitem>
- <listitem>
- <para>
-Open brace on same line (at end).
-Both for if/while/for and for class and functions definitions.
-</para>
- <para>
-This is exactly as it is stated in the Sun Code Conventions.
-It is here just for the emphasis.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Use deprecation when removing public and protected
-classes,
-methods and
-attributes.
-</para>
- <para>
-Whenever you have a public or protected method or attribute in a class or
-a public class
-that you want to
-remove, rename, move to a different package,
-change the signature in an incompatible way, or
-reduce the visibility for
-you shall always deprecate it first.
-After the next stable release you (or someone else) can remove it.
-</para>
- <para>
-In the future, when the subsystems are well defined and it is clear
-what public or protected
-methods, attributes or classes
-that are part of a certain subsystem's
-exported interface
-we can allow an exception to this rule for
-methods, attributes and classes
-that are not.
-(See <xref linkend="subsystems_relationships"></xref>.)
-</para>
- <para>
-Write deprecation statements like this:
-<programlisting>
- * @deprecated by <replaceable>your name</replaceable> in <replaceable>the upcoming release</replaceable>. Use {@link <replaceable>whatever</replaceable>}
- * <replaceable>a complete explanation on what to do instead</replaceable>
-</programlisting>
-</para>
- <para>
-This is not checked by Checkstyle.
-</para>
- <para>
-Rationale:
-This is part of the "Do Simple Things"-development approach that we
-use in ArgoUML.
-ArgoUML is a big project with lots of legacy code that we do not know
-exactly how it works.
-Deprecation shows the intent between decision to remove a method and
-the point where it is actually removed
-and this without breaking anything of the old code.
-There are also modules or plug ins that we might know nothing about that
-could be loaded by some user to run within ArgoUML to add functionality.
-It is for the modules and plug ins that we always save
-deprecated methods to the next stable release.
-It makes it possible for the module developers to do work during the
-unstable releases and release at the same time as ArgoUML releases its
-stable release.
-Failing to maintain API stability will discourage developers from
-creating new modules for ArgoUML.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Don't use deprecated methods or classes.
-</para>
- <para>
-Rationale:
-Deprecation is an indication that a class is to be removed.
-We always want to build ArgoUML in a way that allows for future updates
-of everything.
-Using things that are on the way out already when doing the implementation
-is for this reason not allowed.
-</para>
- <para>
-Rationale 2:
-If you feel like you really want to use a method that is deprecated instead
-of the replacement you should first convince the person responsible
-for doing the deprecation that he has made a mistake and upgrade ArgoUML
-to a version of that library without that method or class deprecated.
-If it is within ArgoUML discuss it with the person who actually did
-the deprecation or in the development team.
-</para>
- <para>
-Comment:
-<!-- What does this mean? It makes no sense to me. - tfm -->
-There is an ongoing task (probably perpetually) to change
-the calls to deprecated methods and classes that
-have been deprecated after use in ArgoUML.
-This is a normal part of improving ArgoUML.
-If this work is too slow it makes it impossible to upgrade to new
-versions of different sub-tools.
-This problem is seen by "the person responsible for sourcing of the sub-tool"
-when actually trying to upgrade the sub-tool.
-(See <xref linkend="issues_dependencies"></xref>.)
-</para>
- </listitem>
-
- <listitem>
- <para>
-Don't use very long package and class names.
-</para>
- <para>
-To make the code readable,
-keep class names shorter than 25 chars, and
-have at most four levels of packages.
-</para>
- <para>
-Historically in the ArgoUML design,
-a deep package structure was used.
-There are several places in the code where the package structure is
-mimicking the UML hierarchy of objects resulting in impossibly long
-package names like
-<classname>org.argouml.model.uml.behavioralelements.collaborations.<replaceable>class name</replaceable></classname>, and
-<classname>org.argouml.uml.ui.behavior.common_behavior.<replaceable>class name</replaceable></classname>.
-</para>
- <para>
-While establishing the subsystems we use a two-level approach much
-like the rest of the Java world.
-For the subsystem API we always use:
-<classname>org.argouml.<replaceable>subsystem package name</replaceable></classname>
-i.e. the classes are in the subsystem's directory and all subsystems have
-package names that is a single level below <classname>org.argouml</classname>.
-If a subsystem is really complex or will be complex
-w.r.t. the amount of classes (meaning more than 50 files with classes),
-we create new packages with internal classes on a single level below
-the subsystem package.
-</para>
- <para>
-This is the plan for the subsystems and new classes.
-Don't move old classes just yet!
-That would create more confusion that it would help.
-</para>
- </listitem>
-
- <listitem>
- <para>
-For everything else follow
-<ulink url="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">
-Code Conventions for the Java Programming Language
-</ulink>
-(called Sun Code Conventions)!
-</para>
- </listitem>
-
- </itemizedlist>
-
- <para>
-Some of these rules are marked with a comment that they are
-checked by a Checkstyle.
-Checkstyle is a tool available with the ArgoUML development environment
-preconfigured for these rules.
-The current configuration can be found in
-<filename>argouml/tools/checkstyle/checkstyle_argouml.xml</filename>.
-</para>
- <para>
-To run Checkstyle run the command
-<command>build checkstyle</command> from the
-<filename class="directory">argouml/src_new</filename>
-directory.
-This requires you to have checked out the directories
-<filename class="directory">argouml/tools</filename>,
-<filename class="directory">argouml/tests</filename>, and
-<filename class="directory">argouml/src_new</filename>.
-</para>
- <para>
-The last couple of Checkstyle results are also available in
-the Xenofarm result.
-</para>
- <para>
-Checkstyle will also check some of the rules from the
-Sun Code Conventions that are not stated here.
-Furthermore Checkstyle nags about when the order of modifiers does
-not conform to the suggestions in the
-Java Language Specification, Section 8.1.1, 8.3.1, 8.4.3.
-</para>
- </sect1>
-
- <sect1 id="groundrules">
- <title>When Committing to the Repository</title>
- <indexterm>
- <primary>CVS</primary>
- <secondary>standards</secondary>
- </indexterm>
- <indexterm>
- <primary>SVN</primary>
- <secondary>standards</secondary>
- </indexterm>
- <indexterm>
- <primary>Repository Committing</primary>
- </indexterm>
- <indexterm>
- <primary>Committing to the Repository</primary>
- </indexterm>
- <indexterm>
- <primary>Standards</primary>
- <secondary>CVS</secondary>
- </indexterm>
- <indexterm>
- <primary>Standards</primary>
- <secondary>SVN</secondary>
- </indexterm>
- <para>
-The source code repository is a shared resource in the project.
-This means that once you commit your stuff it has the potential
-of getting in the way of everybody else's work in the project.
-For this reason special considerations are needed.
-This chapter describes what you should do to limit the risk
-of causing someone else problems.
-</para>
-
- <para>
-When you have done all the work, and all the testing and
-are about to commit something please do the following:
- <orderedlist>
- <listitem>
- <para>
-Compile ArgoUML
-(<command>build run</command> or <command>build package</command>).
-</para>
- <para>
-This goes for all changes, even changes in comments.
-</para>
- </listitem>
-
- <listitem>
- <para>
-If your changes include removing files make a clean compile.
-(<command>build clean</command> followed by
-<command>build run</command> or <command>build package</command>).
-</para>
- </listitem>
-
- <listitem>
- <para>
-If your changes include removing public or protected operations and
-attributes, make a clean compile
-(<command>build clean</command> followed by
-<command>build run</command> or <command>build package</command>).
-</para>
- <para>
-The build mechanism does not yet have a reliable
-dependency checker enabled so this is the best way to make sure.
-</para>
- </listitem>
-
- <listitem>
- <para>
-If your changes include adding abstract operations, make a clean compile
-(<command>build clean</command> followed by
-<command>build run</command> or <command>build package</command>).
-</para>
- <para>
-The build mechanism does not yet have a reliable
-dependency checker enabled so this is the best way to make sure.
-</para>
- </listitem>
-
- <listitem>
- <para>
-If you have changed anything that has the potential to affect
-something in a totally different part of the code like internal
-data structure, handling of exceptions,
-run all JUnit test cases
-and start the tool and do some more testing.
-</para>
- <para>
-If in doubt, run all JUnit test cases.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Do a <command>svn status</command> in trunk to make sure that
-you do not forget to commit a file and a
-<command>svn update</command> to make sure that no one
-else has committed anything in the mean time.
-</para>
- <para>
-Remember that if you do not commit all the files from trunk
-that <command>svn status</command> found (marked A, R, and M)
-in the same commit then you would better remove those file
-from the checked out copy, update to get the original version
-from the repository and start over with the compilation.
-</para>
- <para>
-If someone else has updated a file
-(<command>svn update</command> shown U, or R)
-please compile again.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Commit all files that are included in a change at the same time.
-</para>
- <para>
-This reduces the chance of anyone getting an inconsistent set of files
-by updating in the middle of your commit.
-</para>
- </listitem>
-
- <listitem>
- <para>
-Commit often.
-</para>
- <para>
-Remember that the repository is also a backup copy of your work.
-</para>
- <para>
-If your change is so big and involves so many files that you would
-like to commit it for backup reasons but it doesn't compile or
-doesn't work or for some other reason should not confuse
-the trunk in the subversion repository, create a branch to work in.
-Then when your work is complete, you merge the branch into
-trunk.
-</para>
- </listitem>
- </orderedlist>
-</para>
- <para>
-<emphasis>Rationale:</emphasis>
-These ground rules are not intended to stop or hinder
-anyone's work.
-Remember that there might be several developers working with
-different agendas and different efficiency (slower or faster)
-and the commits are the melting point of this.
-</para>
- <para>
-<emphasis>Perspective:</emphasis>
-If this will take you an extra two minutes before every commit
-remember that if you commit something that will not work this
-will take everyone else (guess 10 persons) the extra time of
-looking at the compilation error or see the tool crash (1 minute),
-wonder why (1 minute),
-search for the error in his own changes (3 minutes),
-search for the error somewhere else (1 minute),
-glance at the mailing list to see if someone else has noticed this
-and send a mail (1 minute),
-wait for some response (1 hour wait),
-update (1 minute),
-compile (1 minute).
-This amounts to 10 hours wait and 1.5 hours extra work for
-all developers in the project.
-</para>
- </sect1>
-
- <sect1>
- <title>When Using Branches</title>
- <para>
-We use the following standards in ArgoUML:
- </para>
- <itemizedlist>
- <listitem>
- <para>
-Developers working on code, with an unspecified due date are requested
-to put the code into a branch if it is deemed useful that the code can
-be shared. Developer branches follow the scheme:
-<emphasis>work_<replaceable>explanation</replaceable>_<replaceable>owner</replaceable></emphasis>, where
-</para>
- <itemizedlist>
- <listitem>
- <para>
-<replaceable>explanation</replaceable> is something like
-javahelp,
-propertypanel,
-cppcodegeneration,
-issue12345
-</para>
- </listitem>
- <listitem>
- <para>
-<replaceable>owner</replaceable> is the uid for the
-developer that started the branch,
-e.g. tlach (Thierry Lach) or mkl (Markus Klink).
-</para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
-
- <para>
-Merging branches together is complex.
-Please use branches sparingly and announce your intentions on the mailing list.
-</para>
- </sect1>
-
-
- <sect1>
- <title>When Working with the Build Process</title>
- <para>
-For the <filename>build.xml</filename> files we use the following rules.
- </para>
- <itemizedlist>
- <listitem>
- <para>
-Be careful when downloading stuff.
- </para>
- <para>
-ArgoUML is supposed to be a self-contained development environment.
-Some times it is better to have things downloaded from the ant script
-instead of from the repository.
-In that case separate the download-targets from the target that does
-building so that it is easy for everyone to know when their
-development machine is working against the Internet and when it is not.
- </para>
- </listitem>
-
- <listitem>
- <para>
-Public targets shall have descriptions.
-Non-public targets shall not have descriptions
-(write xml comments or echos instead).
- </para>
- </listitem>
-
- <listitem>
- <para>
-Use ant-built-ins for everything.
- </para>
- <para>
-ArgoUML is supposed to be a self-contains development environment.
-If you feel tempted to use other tools (perl, sed, nsgmls), don't!
-They are probably not present in all environments where we want to
-run a development environment.
- </para>
- </listitem>
- </itemizedlist>
- </sect1>
-
- <sect1>
- <sect1info>
- <author>
- <firstname>Linus</firstname>
- <surname>Tolke</surname>
- </author>
- </sect1info>
- <title>When Considering Dependencies</title>
-
- <para>
-In the ArgoUML project we use several third-party libraries
-to solve parts of the problem for us.
-These libraries (referred to as dependencies below)
-are an important part of the ArgoUML tool and
-must be handled in a good way if ArgoUML is going to be successful.
-</para>
-
- <para>
-Here is the list of things to check in the dependency
-and to discuss with yourself and maybe with the rest of the
-ArgoUML development team
-before considering it's use in the ArgoUML project.
-</para>
- <itemizedlist>
- <listitem>
- <para>
-License
-</para>
- <para>
-We must be allowed to
-develop against,
-release with,
-distribute, and
-use
-the dependency indefinitely
-without monetary or other compensation.
-</para>
- <para>
-Rationale:
-We have no money in the ArgoUML project,
-we don't want to have money in the ArgoUML project.
-We have no organization that can enter agreements and live up to them.
-We don't want to require our users to enter agreements to use ArgoUML.
-</para>
- </listitem>
- <listitem>
- <para>
-Java version
-</para>
- <para>
-The dependency must have a policy that is compatible with the ArgoUML project
-policy on Java version requirements.
-</para>
- <para>
-Rationale:
-The ambition for ArgoUML is to be a working tool for
-as many people as possible.
-Java is still under development and there are nice features available in
-future releases.
-In ArgoUML we have a plan for how to handle this. It is to always support
-two major releases of Java (currently Java5 and Java6).
-We cannot have a dependency that restricts us in this aspect.
-</para>
- </listitem>
- <listitem>
- <para>
-Distribution
-</para>
- <para>
-We require the dependency to make it possible for us to take the distribution,
-enter it in our repository and write rules to automate
-the use of the dependency while developing, releasing and running ArgoUML.
-This automated use must be able to run without relying on access to some
-server and without user intervention.
-</para>
- <para>
-The API documentation of the dependency (assumed to be Javadoc)
-we can use from some web site belonging to that dependency.
-</para>
- <para>
-Rationale:
-In the ArgoUML project we want to make it as easy as possible for our users
-to install ArgoUML.
-We also want to make it as easy as possible for our developers to get their
-development environment working and for the release manager to prepare
-the releases.
-</para>
- </listitem>
- <listitem>
- <para>
-Road map
-</para>
- <para>
-The project developing the dependency must have a plan that fits
-the ArgoUML plan for the future.
-</para>
- <para>
-Rationale:
-If a dependency will soon go somewhere else
-i.e. stop doing what we require or stop supporting what we require,
-then we will soon have troubles with that dependency.
-</para>
- </listitem>
- <listitem>
- <para>
-Working project
-</para>
- <para>
-The project that develops the dependency should be a working project.
-Check that there is some person responsible for it,
-preferably with a team or organization backing him.
-Check that there is a plan for upcoming releases.
-Check that there is a way to report bugs and enhancement requests.
-</para>
- <para>
-Rationale:
-We don't want to rely on a dependency where there is no chance of ever
-getting a bug that we encounter fixed.
-We are also part of an ever-evolving world.
-Soon we want the tool to do more for us.
-We should then be able to wish that and eventually get that included.
-</para>
- </listitem>
- </itemizedlist>
- <para>
-Notice that we should not and don't need to do this in a passive way.
-We should explain to the dependency team what we want and why.
-Especially for dependency that we have already in ArgoUML but also
-for dependencies that we consider taking in.
-This is to increase the likelihood that they will have us in mind when
-planning and evolving.
-</para>
- <para>
-Here are the steps to go through and the recommended order
-once the decision is taken to use the dependency in ArgoUML:
-</para>
- <itemizedlist>
- <listitem>
- <para>
-Documentation
-</para>
- <para>
-Describe in the Cookbook in the appropriate subsystem section
-in <xref linkend="inside_subsystems"/>
-what part of the problem that the dependency solves and
-how it is used in ArgoUML.
-</para>
- </listitem>
- <listitem>
- <para>
-Javadoc
-</para>
- <para>
-Enter the package list file in a special directory under
-<filename class="directory">argouml/lib/javadocs</filename>.
-Update the list of links used when building the Javadoc.
-One place in <filename>default.properties</filename>,
-One or two places in <filename>build.xml</filename>
-(targets javadocs and javadocs-api).
-</para>
- <para>
-Test by referencing some class from the dependency,
-building the Javadoc, and
-check that the link is working.
-</para>
- </listitem>
- <listitem>
- <para>
-Repository
-</para>
- <para>
-Assuming that the dependency is distributed in a set of jar files,
-add the jar files to the <filename class="directory">lib</filename> directory
-in a versioned way together with the license file.
-Use filenames like:
-<filename><replaceable>dependency</replaceable>-<replaceable>version</replaceable>.jar</filename>, and
-<filename><replaceable>dependency</replaceable>.LICENSE.txt</filename>.
-</para>
- <para>
-The plan is to have each subsystem in their own directory.
-If the dependency in question belongs to a subsystem that is moved to a
-separate directory you should put it in
-the <filename class="directory">lib</filename> directory for that subsystem.
-See how the model-mdr dependencies are handled.
-</para>
- </listitem>
- <listitem>
- <para>
-Building
-</para>
- <para>
-Assuming that the dependency is distributed in a set of jar files,
-add the jar files to the list of files that are to be included
-when building ArgoUML.
-The files are to be copied to the argouml/build directory when
-performing the "package"-target.
-One place in <filename>default.properties</filename>,
-Four places in <filename>build.xml</filename>
-(targets init (tree places),
-prerequisites,
-package (two places),
-new target check.<replaceable>dependency</replaceable>), and
-one possible place in <filename>AboutBox.java</filename> (Constructor).
-Notice especially that <filename>build.xml</filename> shall not contain
-any version information.
-Notice also that the text in <filename>AboutBox.java</filename>
-shall not contain anything that needs to be localized but just
-the dependency name, reference and possibly version.
-</para>
- <para>
-This will take care of
-running tests,
-building releases, and
-building for the purpose of developing modules.
-</para>
- <para>
-Check by having some class from the dependency loaded immediately
-when starting ArgoUML and start using
-<command>build run</command>.
-</para>
- </listitem>
- </itemizedlist>
-
- <para>
-See <xref linkend="issues_dependencies"></xref> for a discussion on
-how to handle bugs found in a dependency and
-updates of the version of a dependency.
-</para>
- </sect1>
-
-</chapter>
-
+ </para>
+
+ <para>This differs from the Sun Code Conventions that uses either XXX or FIXME depending on if it works or not. </para>
+ </listitem>
+
+ <listitem>
+ <para>Four spaces should be used as the unit of indentation. Tabs must be set exactly every 8 spaces (not 4) and represent 2 indents. </para>
+ <para>This is exactly as it is stated in the Sun Code Conventions. It is here just for the emphasis. </para>
+ <para>This is checked by Checkstyle. </para>
+ </listitem>
+
+ <listitem>
+ <para>If possible use lines shorter than 80 characters wide. </para>
+ <para>This is exactly as it is stated in the Sun Code Conventions. It is here just for the emphasis. </para>
+ <para>This is checked by Checkstyle. Checkstyle ignores three kinds of lines in this check because of the historical use of long class names and package names. These are lines that contain "@see <methodname><replaceable>some method name</replaceable></methodname>", "// $Id:<replaceable>whatever</replaceable>$", and import statements. </para>
+ </listitem>
+
+ <listitem>
+ <para>Open brace on same line (at end). Both for if/while/for and for class and functions definitions. </para>
+ <para>This is exactly as it is stated in the Sun Code Conventions. It is here just for the emphasis. </para>
+ </listitem>
+
+ <listitem>
+ <para>Use deprecation when removing public and protected classes, methods and attributes. </para>
+ <para>Whenever you have a public or protected method or attribute in a class or a public class that you want to remove, rename, move to a different package, change the signature in an incompatible way, or reduce the visibility for you shall always deprecate it first. After the next stable release you (or someone else) can remove it. </para>
+ <para>In the future, when the subsystems are well defined and it is clear what public or protected methods, attributes or classes that are part of a certain subsystem's exported interface we can allow an exception to this rule for methods, attributes and classes that are not. (See <xref linkend="subsystems_relationships" />.) </para>
+ <para>Write deprecation statements like this:
+
+ <programlisting>
+ * @deprecated by <replaceable>your name</replaceable> in <replaceable>the upcoming release</replaceable>. Use {@link <replaceable>whatever</replaceable>}
+ * <replaceable>a complete explanation on what to do instead</replaceable>
+ </programlisting>
+ </para>
+
+ <para>This is not checked by Checkstyle. </para>
+
+ <note>
+ <title>Rationale</title>
+
+ <para>This is part of the "Do Simple Things"-development approach that we use in ArgoUML.</para>
+ <para>ArgoUML is a big project with lots of legacy code that we do not know exactly how it works. Deprecation shows the intent between decision to remove a method and the point where it is actually removed and this without breaking anything of the old code.</para>
+ <para>There are also modules or plug ins that we might know nothing about that could be loaded by some user to run within ArgoUML to add functionality. It is for the modules and plug ins that we always save deprecated methods to the next stable release.</para>
+ <para>It makes it possible for the module developers to do work during the unstable releases and release at the same time as ArgoUML releases its stable release.</para>
+ <para>Failing to maintain API stability will discourage developers from creating new modules for ArgoUML.</para>
+ </note>
+ </listitem>
+
+ <listitem>
+ <para>Don't use deprecated methods or classes. </para>
+ <para>Rationale: Deprecation is an indication that a class is to be removed. We always want to build ArgoUML in a way that allows for future updates of everything. Using things that are on the way out already when doing the implementation is for this reason not allowed. </para>
+ <para>Rationale 2: If you feel like you really want to use a method that is deprecated instead of the replacement you should first convince the person responsible for doing the deprecation that he has made a mistake and upgrade ArgoUML to a version of that library without that method or class deprecated. If it is within ArgoUML discuss it with the person who actually did the deprecation or in the development team. </para>
+ <para>Comment: <!-- What does this mean? It makes no sense to me. - tfm --> There is an ongoing work (probably perpetually) to change the calls to deprecated methods and classes that has been deprecated after used in ArgoUML. This is a normal part of improving ArgoUML. If this work is too slow it makes it impossible to upgrade to new versions of different sub-tools. This problem is seen by "the person responsible for sourcing of the sub-tool" when actually trying to upgrade the sub-tool. (See <xref linkend="issues_dependencies" />.) </para>
+ </listitem>
+
+ <listitem>
+ <para>Don't use very long package and class names. </para>
+ <para>To make the code readable, keep class names shorter than 25 chars, and have at most four levels of packages. </para>
+ <para>Historically in the ArgoUML design, a deep package structure has been used. There are several places in the code where the package structure is mimicking the UML hierarchy of objects resulting in impossibly long package names like <classname>org.argouml.model.uml.behavioralelements.collaborations.<replaceable>class name</replaceable></classname>, and <classname>org.argouml.uml.ui.behavior.common_behavior.<replaceable>class name</replaceable></classname>. </para>
+ <para>While establishing the subsystems we use a two-level approach much like the rest of the Java world. For the subsystem API we always use: <classname>org.argouml.<replaceable>subsystem package name</replaceable></classname> i.e. the classes are in the subsystem's directory and all subsystems have package names that is a single level below <classname>org.argouml</classname>. If a subsystem is really complex or will be complex w.r.t. the amount of classes (meaning more than 50 files with classes), we create new packages with internal classes on a single level below the subsystem package. </para>
+ <para>This is the plan for the subsystems and new classes. Don't move old classes just yet! That would create more confusion that it would help. </para>
+ </listitem>
+
+ <listitem>
+ <para>For everything else follow <uri xlink:href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html"> Code Conventions for the Java Programming Language </uri> (called Sun Code Conventions)! </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>Some of these rules are marked with a comment that they are checked by a Checkstyle. Checkstyle is a tool available with the ArgoUML development environment preconfigured for these rules. The current configuration can be found in <filename>argouml/tools/checkstyle/checkstyle_argouml.xml</filename>. </para>
+ <para>To run Checkstyle run the command <command>build checkstyle</command> from the <filename class="directory" >argouml/src_new</filename> directory. This requires you to have checked out the directories <filename class="directory">argouml/tools</filename>, <filename class="directory" >argouml/tests</filename>, and <filename class="directory" >argouml/src_new</filename>. </para>
+ <para>The last couple of Checkstyle result are also available in the Xenofarm result. </para>
+ <para>Checkstyle will also check some of the rules from the Sun Code Conventions that are not stated here. Furthermore Checkstyle nags about when the order of modifiers does not conform to the suggestions in the Java Language Specification, Section 8.1.1, 8.3.1, 8.4.3. </para>
+ </section>
+
+ <section xml:id="groundrules">
+
+ <title>When Committing to the Repository</title>
+
+ <indexterm>
+ <primary>CVS</primary>
+ <secondary>standards</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>SVN</primary>
+ <secondary>standards</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Repository Committing</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Committing to the Repository</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Standards</primary>
+ <secondary>CVS</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Standards</primary>
+ <secondary>SVN</secondary>
+ </indexterm>
+
+ <para>The source code repository is a shared resource in the project. This means that once you commit your stuff it has the potential of getting in the way of everybody else's work in the project. For this reason special considerations are needed. This chapter describes the how you should do to limit the risk of causing someone else problems. </para>
+ <para>When you have done all the work, and all the testing and are about to commit something please do:
+
+ <orderedlist>
+ <listitem>
+ <para>Compile ArgoUML (<command>build run</command> or <command>build package</command>). </para>
+ <para>This goes for all changes, even changes in comments. </para>
+ </listitem>
+
+ <listitem>
+ <para>If your changes include removing files make a clean compile. (<command>build clean</command> followed by <command>build run</command> or <command>build package</command>). </para>
+ </listitem>
+
+ <listitem>
+ <para>If your changes include removing public or protected operations and attributes make a clean compile (<command>build clean</command> followed by <command>build run</command> or <command>build package</command>). </para>
+ <para>The build mechanism does not yet have reliable dependency checker enabled so this is the best way to make sure. </para>
+ </listitem>
+
+ <listitem>
+ <para>If your changes include adding abstract operations make a clean compile (<command>build clean</command> followed by <command>build run</command> or <command>build package</command>). </para>
+ <para>The build mechanism does not yet have reliable dependency checker enabled so this is the best way to make sure. </para>
+ </listitem>
+
+ <listitem>
+ <para>If you have changed anything that has the potential of affecting something in a totally different part of the code like internal data structure, handling of exceptions, run all JUnit test cases and start the tool and do some more testing. </para>
+ <para>If in doubt, run all JUnit test cases. </para>
+ </listitem>
+
+ <listitem>
+ <para>Do a <command>svn status</command> in trunk to make sure that you do not forget to commit a file and a <command>svn update</command> to make sure that no one else has committed anything in the mean time. </para>
+ <para>Remember that if you do not commit all the files from trunk that <command>svn status</command> found (marked A, R, and M) in the same commit then you would better remove those file from the checked out copy, update to get the original version from the repository and start over with the compilation. </para>
+ <para>If someone else have updated a file (<command>svn update</command> shown U, or R) please compile again. </para>
+ </listitem>
+
+ <listitem>
+ <para>Commit all files that are included in a change at the same time. </para>
+ <para>This reduces the chance of anyone getting an inconsistent set of files by updating in the middle of your commit. </para>
+ </listitem>
+
+ <listitem>
+ <para>Commit often. </para>
+ <para>Remember that the repository is also a backup copy of your work. </para>
+ <para>If your change is so big and involves so many files that you would like to commit it for backup reasons but it doesn't compile or doesn't work or for some other reason should not confuse the trunk in the subversion repository, create a branch to work in. Then when your work is complete, you merge the branch into trunk. </para>
+ </listitem>
+ </orderedlist>
+ </para>
+
+ <para><emphasis>Rationale:</emphasis> These ground rules is for the purpose of not stopping or hindering the work for anyone. Remember that there might be several developers working with different agendas and different efficiency (slower or faster) and the commits is the melting point of this. </para>
+ <para><emphasis>Perspective:</emphasis> If this will take you an extra two minutes before every commit remember that if you commit something that will not work this will take everyone else (guess 10 persons) the extra time of looking at the compilation error or see the tool crash (1 minute), wonder why (1 minute), search for the error in his own changes (3 minutes), search for the error somewhere else (1 minute), glance at the mailing list to see if someone else has noticed this and send a mail (1 minute), wait for some response (1 hour wait), update (1 minute), compile (1 minute). This amounts to 10 hours wait and 1.5 hours extra work for all developers in the project. </para>
+ </section>
+
+ <section>
+ <title>When Using Branches</title>
+
+ <para>We use the following standards in ArgoUML: </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Developers working on code, with an unspecified due date are requested to put the code into a branch if it is deemed useful that the code can be shared. Developer branches follow the scheme: <emphasis>work_<replaceable>explanation</replaceable>_<replaceable>owner</replaceable></emphasis>, where </para>
+
+ <itemizedlist>
+ <listitem>
+ <para><replaceable>explanation</replaceable> is something like javahelp, propertypanel, cppcodegeneration, issue12345 </para>
+ </listitem>
+
+ <listitem>
+ <para><replaceable>owner</replaceable> is the uid for the developer that started the branch, e.g. tlach (Thierry Lach) or mkl (Markus Klink). </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+
+ <para>Merging branches together is complex. Please use branches sparingly and announce your intentions on the mailing list. </para>
+ </section>
+
+
+ <section>
+ <title>When Working with the Build Process</title>
+
+ <para>For the <filename>build.xml</filename> files we use the following rules. </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Be careful when downloading stuff. </para>
+ <para>ArgoUML is supposed to be a self-contained development environment. Some times it is better to have things downloaded from the ant script instead of from the repository. In that case separate the download-targets from the target that does building so that it is easy for everyone to know when their development machine is working against the Internet and when it is not. </para>
+ </listitem>
+
+ <listitem>
+ <para>Public targets shall have description. Non-public targets shall not have description (write xml comments or echos instead). </para>
+ </listitem>
+
+ <listitem>
+ <para>Use ant-built-ins for everything. </para>
+ <para>ArgoUML is supposed to be a self-contains development environment. If you feel tempted to use other tools (perl, sed, nsgmls), don't! They are probably not present in all environments where we want to run a development environment. </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>When Considering Dependencies</title>
+
+ <info>
+ <author>
+ <personname>
+ <firstname>Linus</firstname>
+ <surname>Tolke</surname>
+ </personname>
+ </author>
+ </info>
+
+ <para>In the ArgoUML project we use several third-party libraries to solve parts of the problem for us. These libraries (referred to as dependencies below) are an important part of the ArgoUML tool and must be handled in a good way if ArgoUML is going to be successful. </para>
+ <para>Here is the list of things to check in the dependency and to discuss with yourself and maybe with the rest of the ArgoUML development team before considering to use it in the ArgoUML project. </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>License </para>
+ <para>We must be allowed to develop against, release with, distribute, and use the dependency indefinitely without monetary or other compensation. </para>
+ <para>Rationale: We have no money in the ArgoUML project, we don't want to have money in the ArgoUML project. We have no organization that can enter agreements and live up to them. We don't want to require our users to enter agreements to use ArgoUML. </para>
+ </listitem>
+ <listitem>
+ <para>Java version </para>
+ <para>The dependency must have a policy that matches the ArgoUML project policy on Java version requirements. </para>
+ <para>Rationale: The ambition for ArgoUML is to be a working tool for as many people as possible. Java is still under development and there are nice features available in future releases. In ArgoUML we have a plan for how to handle this. It is to always support two major releases of Java (currently Java5 and Java6). We cannot have a dependency that restricts us in this aspect. </para>
+ </listitem>
+ <listitem>
+ <para>Distribution </para>
+ <para>We require the dependency to make it possible for us to take the distribution, enter it in our repository and write rules to automate the use of the dependency while developing, releasing and running ArgoUML. This automated use must be able to run without relying on access to some server and without user intervention. </para>
+ <para>The API documentation of the dependency (assumed to be Javadoc) we can use from some web site belonging to that dependency. </para>
+ <para>Rationale: In the ArgoUML project we want to make it as easy as possible for our users to install ArgoUML. We also want to make it as easy as possible for our developers to get their development environment working and for the release manager to prepare the releases. </para>
+ </listitem>
+ <listitem>
+ <para>Road map </para>
+ <para>The project developing the dependency must have a plan that fits the ArgoUML plan for the future. </para>
+ <para>Rationale: If a dependency will soon go somewhere else i.e. stop doing what we require or stop supporting what we require, then we will soon have troubles with that dependency. </para>
+ </listitem>
+ <listitem>
+ <para>Working project </para>
+ <para>The project that develops the dependency should be a working project. Check that there is some person responsible for it, preferably with a team or organization backing him. Check that there is a plan for upcoming releases. Check that there is a way to report bugs and enhancement requests. </para>
+ <para>Rationale: We don't want to rely on a dependency where there is no chance of ever getting a bug that we encounter fixed. We are also part of an ever-evolving world. Soon we want the tool to do more for us. We should then be able to wish that and eventually get that included. </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Notice that we should not and don't need to do this in a passive way. We should explain to the dependency team what we want and why. Especially for dependency that we have already in ArgoUML but also for dependencies that we consider taking in. This is to increase the likelihood that they will have us in mind when planning and evolving. </para>
+ <para>Here are the steps to go through and the recommended order once the decision is taken to use the dependency in ArgoUML: </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Documentation</para>
+ <para>Describe in the Cookbook in the appropriate subsystem section in <xref linkend="inside_subsystems" /> what part of the problem that the dependency solves and how it is used in ArgoUML. </para>
+ </listitem>
+ <listitem>
+ <para>Javadoc </para>
+ <para>Enter the package list file in a special directory under <filename class="directory" >argouml/lib/javadocs</filename>. Update the list of links used when building the Javadoc. One place in <filename>default.properties</filename>, One or two places in <filename>build.xml</filename> (targets javadocs and javadocs-api). </para>
+ <para>Test by referencing some class from the dependency, building the Javadoc, and check that the link is working. </para>
+ </listitem>
+ <listitem>
+ <para>Repository </para>
+ <para>Assuming that the dependency is distributed in a set of jar files, add the jar files to the <filename class="directory" >lib</filename> directory in a versioned way together with the license file. Use filenames like: <filename><replaceable>dependency</replaceable>-<replaceable>version</replaceable>.jar</filename>, and <filename><replaceable>dependency</replaceable>.LICENSE.txt</filename>. </para>
+ <para>The plan is to have each subsystem in their own directory. If the dependency in question belongs to a subsystem that is moved to a separate directory you should put it in the <filename class="directory" >lib</filename> directory for that subsystem. See how the model-mdr dependencies are handled. </para>
+ </listitem>
+ <listitem>
+ <para>Building </para>
+ <para>Assuming that the dependency is distributed in a set of jar files, add the jar files to the list of files that are to be included when building ArgoUML. The files are to be copied to the argouml/build directory when performing the "package"-target. One place in <filename>default.properties</filename>, Four places in <filename>build.xml</filename> (targets init (tree places), prerequisites, package (two places), new target check.<replaceable>dependency</replaceable>), and One possibly place in <filename>AboutBox.java</filename> (Constructor). Notice especially that <filename>build.xml</filename> shall not contain any version information. Notice also that the text in <filename>AboutBox.java</filename> shall not contain anything that needs to be localized but just the dependency na
me, reference and possibly version. </para>
+ <para>This will take care of running tests, building releases, and building for the purpose of developing modules. </para>
+ <para>Check by having some class from the dependency loaded immediately when starting ArgoUML and start using <command>build run</command>. </para>
+ </listitem>
+ </itemizedlist>
+ <para>See <xref linkend="issues_dependencies" /> for a discussion on how to handle bugs found in dependency and updates of the version of a dependency. </para>
+ </section>
+</chapter>
<!-- Local stuff for Emacs - please do not delete
Local Variables:
@@ -860,4 +395,4 @@
indent-tabs-mode: nil
End:
--->
+-->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemcritics.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemcritics.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemcritics.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemcritics.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemcritics.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemcritics.xml 2008-01-15 19:22:21-0800
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
// Copyright (c) 1996-2006 The Regents of the University of California. All
@@ -25,9 +25,17 @@
// UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
-->
-<sect1 id="critics">
- <title>Critics and other cognitive tools</title>
- <indexterm>
+<section
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xml:id="critics">
+
+ <title>Critics and other cognitive tools</title>
+
+ <indexterm>
<primary>Critics</primary>
</indexterm>
<indexterm>
@@ -36,7 +44,7 @@
<indexterm>
<primary>Wizards</primary>
</indexterm>
- <para id="comp-critics-purpose">
+ <para xml:id="comp-critics-purpose">
Purpose - to provide cognitive help for the User.
This help is based on the current model that the User works with.
</para>
@@ -44,7 +52,7 @@
The Critics are located in <classname>org.argouml.cognitive</classname>.
</para>
<para>
-The Critics is a Loadable subsystem. See <xref linkend="loadable_subsystems"></xref>.
+The Critics is a Loadable subsystem. See <xref xlink:href="loadable_subsystems" />.
</para>
<para>
The Critics subsystem depends on the Model that it works against to take
@@ -141,11 +149,11 @@
</para>
</sect2>
- <sect2 id="howdoi_critics">
- <title>How do I ...?</title>
+ <sect2 xml:id="howdoi_critics">
+ <title>How do I �</title>
<para>
<itemizedlist>
- <listitem><para>...create a new critique?</para>
+ <listitem><para>â¦create a new critique?</para>
<para>
Currently the only way to add a new critique is to write a class that
implements it so that is described here.
@@ -182,7 +190,7 @@
<command>addSupportedDecision(UMLDecision.dec<replaceable>AAAA</replaceable>);</command>
where <replaceable>AAAA</replaceable> is the design issue category
this critic falls into
-(examples include STORAGE, PATTERNS, METHODS).
+(examples include STORAGE, PATTERN METHODS).
</para>
</listitem>
<listitem>
@@ -249,13 +257,13 @@
which will be named respectively
<constant>critics.<replaceable>CrXxxxxYyyyZzzz</replaceable>-head</constant>
and
-<constant>critics.<replaceable>CrXxxxxYyyyZzzz</replaceable>-desc</constant>.
+<constant>critics<replaceable>CrXxxxxYyyyZzzz</replaceable>-desc</constant>.
There are plenty of examples to look at there.
Headlines shall be unique, see issue 618.
The other files
for
British English,
-Spanish, ...
+Spanish, â¦
respectively)
are the responsibility of the corresponding language team.
Notify the language teams that there is work to be done.
@@ -266,7 +274,7 @@
add two statements:
<programlisting>
private static Critic <replaceable>crXxxxxYyyyZzzz</replaceable> = new <replaceable>CrXxxxxYyyyZzzz</replaceable>();
-...
+â¦
Agency.register(<replaceable>crXxxxxYyyyZzzz</replaceable>, <replaceable>DesignMaterialCls</replaceable>);
</programlisting>
If you want to add a critic to a design material
@@ -288,7 +296,7 @@
</para>
</listitem>
<listitem>
- <para>...write the test in a critique?</para>
+ <para>â¦write the test in a critique?</para>
<para>
The critiques tests are essentially a combination of conditions
that are to be fulfilled.
@@ -312,7 +320,7 @@
<classname>org.argouml.uml.cognitive.critics.CrConstructorNeeded</classname>.
</para>
</listitem>
- <listitem><para>...fix a critique?</para>
+ <listitem><para>â¦fix a critique?</para>
<para>Locate the critique and insert some logging code. You should make sure
that you understand all the implications of changes, therefore it is a good idea
to see what makes the critic nag in the first place. But rest assured: some of
@@ -321,7 +329,7 @@
some exposure to related UML elements.
</para>
</listitem>
- <listitem><para>...change the text of a critique?</para>
+ <listitem><para>â¦change the text of a critique?</para>
<para>
The texts of the critics should be in the according localization files
and resource bundles. Be careful: in some critics the text is still in
@@ -331,7 +339,7 @@
</listitem>
<listitem>
- <para>...get my critic to trigger?</para>
+ <para>â¦get my critic to trigger?</para>
<para>
This is a suggested way to troubleshoot if the critic doesn't trigger.
</para>
@@ -377,7 +385,7 @@
</imageobject>
</mediaobject>
</sect2>
-</sect1>
+</section>
@@ -392,4 +400,4 @@
indent-tabs-mode: nil
End:
--->
+-->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemdiagrams.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemdiagrams.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemdiagrams.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemdiagrams.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemdiagrams.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemdiagrams.xml 2008-01-15 19:22:21-0800
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
// Copyright (c) 1996-2006 The Regents of the University of California. All
@@ -26,7 +26,14 @@
-->
-<sect1 id="diagrams">
+<sect1
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xml:id="diagrams">
+
<title>Diagrams</title>
<indexterm>
<primary>Diagrams</primary>
@@ -40,13 +47,13 @@
the diagrams through the view.
</para>
<para>
-The Diagrams are located in <classname>org.argouml.uml.diagram</classname>.
+The Diagrams are be located in <classname>org.argouml.uml.diagram</classname>.
</para>
<para>
-The Diagrams are a View subsystem. <xref linkend="view_control_subsystems"></xref>.
+The Diagrams is a View subsystem. <xref xlink:href="view_control_subsystems"></xref>.
</para>
<para>
-The Diagrams depend on the Model subsystem and the GUI.
+The Diagrams are depending on the Model subsystem and the GUI.
</para>
<para>
@@ -114,11 +121,11 @@
that's how it's implemented at the moment.
</para>
<sect3>
- <title>How do I ...?</title>
+ <title>How do I �</title>
<para>
<itemizedlist>
<listitem>
- <para>...add a new tab to the <classname>MultiEditorPane</classname>?</para>
+ <para>â¦add a new tab to the <classname>MultiEditorPane</classname>?</para>
<para>
Create a new class that's a child of <classname>JPanel</classname>
and put the following
@@ -133,7 +140,7 @@
</sect3>
</sect2>
- <sect2 id="howdoi_diagrams">
+ <sect2 xml:id="howdoi_diagrams">
<title>How do I add a new element to a diagram?</title>
<para>
@@ -155,7 +162,7 @@
<para>
Create a new property panel class that will be displayed in
the property tab window on the details pane.
-This is described in <xref linkend="propertypanels"></xref>.
+This is described in <xref xlink:href="propertypanels"></xref>.
</para>
</listitem>
</orderedlist>
@@ -328,7 +335,7 @@
</para>
</sect3>
- <sect3 id="howto_createnewfig_2">
+ <sect3 xml:id="howto_createnewfig_2">
<title>Creating a new Fig (explanation 2)</title>
<para>
@@ -339,10 +346,10 @@
<orderedlist>
<listitem>
<para>
-Nodes that are Figs that are enclosed figures like
+For nodes, that are Figs that are enclosed figures like
<classname>FigClass</classname>,
extend from <classname>FigNodeModelElement</classname>.
-Edges that are lines like <classname>FigAssociation</classname>,
+For edges, that are lines like <classname>FigAssociation</classname>,
extend from <classname>FigEdgeModelElement</classname>.
The name of the Fig has to start with (yes indeed) Fig.
The rest of the name should be equal to the model element name.
@@ -470,4 +477,4 @@
indent-tabs-mode: nil
End:
--->
+-->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/subsysteminternationalization.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/subsysteminternationalization.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/subsysteminternationalization.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/subsysteminternationalization.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/subsysteminternationalization.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/subsysteminternationalization.xml 2008-01-15 19:22:21-0800
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
// Copyright (c) 1996-2006 The Regents of the University of California. All
@@ -25,8 +25,15 @@
// UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
-->
-<sect1 id="internationalization">
- <title>Internationalization</title>
+<sect1
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xml:id="internationalization">
+
+ <title>Internationalization</title>
<indexterm>
<primary>Internationalization</primary>
</indexterm>
@@ -59,7 +66,7 @@
Command line argument
</para>
<para>
-The prepared Java Web Start alternatives also use this to override
+The prepared Java Web Start alternatives also uses this to override
everything else.
</para>
</listitem>
@@ -111,7 +118,7 @@
</para>
<para>
The Internationalization is an Infrastructure subsystem.
-See <xref linkend="infrastructure_subsystems"></xref>.
+See <xref xlink:href="infrastructure_subsystems"></xref>.
</para>
<indexterm>
@@ -140,9 +147,9 @@
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.
+This comes from the fact that by necessity the different
+persons working with internationalization have different native languages
+and that complicates the communications.
</para>
<para>
To handle this problem for GNU applications
@@ -197,8 +204,8 @@
needs to be modified to allow for localization.
</para>
<para>
-As ArgoUML was originally built without localization there may still be
-places in the GUI that are not localizable just by
+As ArgoUML is originally built without localization there may still have
+places in the GUI that is not localizable just by
modifying the resource bundles.
Each such place is a Defect and shall be corrected.
</para>
@@ -259,12 +266,12 @@
</listitem>
</itemizedlist>
</sect2>
- <sect2 id="howdoi_internationalization">
- <title>How do I ...?</title>
+ <sect2 xml:id="howdoi_internationalization">
+ <title>How do I �</title>
<para>
<itemizedlist>
<listitem>
- <para>...fix an incorrect or missing translation?</para>
+ <para>â¦fix an incorrect or missing translation?</para>
<para>
This is the responsibility of the language team.
</para>
@@ -295,7 +302,7 @@
</para>
</listitem>
<listitem>
- <para>...verify that all translations are up to date?</para>
+ <para>â¦verify that all translations are up to date?</para>
<para>
There is a simple tool you can use that is developed in the argouml-gen
project.
@@ -304,7 +311,7 @@
</para>
</listitem>
<listitem>
- <para>...start a new Language Team?</para>
+ <para>â¦start a new Language Team?</para>
<para>
Contact the project leader of the ArgoUML project to discuss this.
He will create the project and make you the first member
@@ -312,15 +319,15 @@
you have understood the responsibilities.
</para>
<para>
-The projects are ArgoUML subprojects so they are listed at the bottom of
-the ArgoUML web page.
+The project are argouml subprojects so they are listed at the bottom of
+the argouml web page.
</para>
</listitem>
<listitem>
<para>
-...find the languages internationalization code for the language
-your instance of ArgoUML is attempting to run with: en, es, en_GB,...
+â¦find the languages internationalization code for the language
+your instance of ArgoUML is attempting to run with: en, es, en_GB,â¦
</para>
<para>
The one you are currently using is shown in the Versions information
@@ -340,12 +347,12 @@
</para>
</listitem>
<listitem>
- <para>...start the translation work?</para>
+ <para>â¦start the translation work?</para>
<para>
This is only applicable for members of the language team.
</para>
<para>
-Make sure you are a Developer in the appropriate language project.
+Make sure you are a Developer in the appropriate project.
</para>
<para>
Look at the files in
@@ -370,7 +377,7 @@
<filename>action_<replaceable>language code</replaceable>.properties</filename>,
<filename>button_<replaceable>language code</replaceable>.properties</filename>,
<filename>checkbox_<replaceable>language code</replaceable>.properties</filename>,
-<filename>combobox_<replaceable>language code</replaceable>.properties</filename>, ...
+<filename>combobox_<replaceable>language code</replaceable>.properties</filename>, â¦
</para>
<para>
When this is done the first iteration of the Tool translation is completed.
@@ -378,7 +385,7 @@
</para>
</listitem>
<listitem>
- <para>...join an existing Language Team</para>
+ <para>â¦join an existing Language Team</para>
<para>
Join the dev mailing list in the correct project and
apply for an Observer role in the project.
@@ -390,7 +397,7 @@
</para>
</listitem>
<listitem>
- <para>...add or modify code with localized things?</para>
+ <para>â¦add or modify code with localized things?</para>
<para>
This is only applicable for developers working with the ArgoUML Java source
or some argouml module.
@@ -427,10 +434,10 @@
to convert them to wherever they are used.
</para>
<para>
-This is how a real example would look:
+This is how a real example would look like:
<programlisting>
import org.argouml.i18n.Translator;
-...
+â¦
String localized = Translator.localize(<replaceable>key</replaceable>);
</programlisting>
</para>
@@ -456,7 +463,7 @@
Contact all language-teams so that they can update their files.
</para>
<para>
-Currently (November 2003) there is great confusion as to where
+Currently (November 2003) there is a great confusion as to where
we stand on the different translations.
For this reason we can't say if any language team is up to date
with the changes and served by such a contact.
@@ -482,7 +489,7 @@
spot the modification.
</para>
<para>
-There allegedly are tools in the java world to spot these kinds of changes.
+There allegedly are tools in the java world to spot this kind of changes.
Until we have the tools and processes in place to handle them
it is better to rely on this simpler mechanism to guarantee correctness.
</para>
@@ -498,7 +505,7 @@
the users of ArgoUML would want to be able to run an ArgoUML localized
differently with
otherwise the exact same settings,
-loading and saving the same files, ...
+loading and saving the same files, â¦
Also a user, changing the language, should not have his files or
configuration corrupted by this change.
</para>
@@ -520,4 +527,4 @@
indent-tabs-mode: nil
End:
--->
+-->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemlogging.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemlogging.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemlogging.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemlogging.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemlogging.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemlogging.xml 2008-01-15 19:22:21-0800
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
// Copyright (c) 1996-2006 The Regents of the University of California. All
@@ -25,13 +25,20 @@
// UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
-->
-<sect1 id="logging">
+<sect1
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xml:id="logging">
+
<title>Logging</title>
<indexterm>
<primary>Logging</primary>
</indexterm>
- <para id="comp-logging-purpose">
+ <para xml:id="comp-logging-purpose">
Purpose - to provide an api for debug log and trace messages.
</para>
<para>
@@ -54,7 +61,7 @@
</para>
<para>
<application>ArgoUML</application> uses the standard
- <ulink url="http://jakarta.apache.org/log4j/">log4j</ulink>
+ <link xlink:href="http://jakarta.apache.org/log4j/">log4j</link>
logging facility. The following sections deal with the current
implementation in <application>ArgoUML</application>. By
default, logging is turned off and only the version
@@ -118,13 +125,13 @@
<para>
For performance reasons, it is advised to do a check before
frequently passed DEBUG
-and INFO log4j messages (see <xref linkend="example.log4j.speed"/>).
+and INFO log4j messages (see <xref xlink:href="example.log4j.speed"/>).
The purpose of this test is to avoid the creation of the argument.
</para>
</sect2>
<sect2>
- <title>How to Create Log Entries...</title>
+ <title>How to Create Log Entriesâ¦</title>
<indexterm>
<primary>LOG</primary>
</indexterm>
@@ -146,27 +153,27 @@
<orderedlist>
<listitem><para>Import the org.apache.log4j.Logger class</para></listitem>
<listitem><para>Get a Logger</para></listitem>
- <listitem><para>Start Logging...</para></listitem>
+ <listitem><para>Start Loggingâ¦</para></listitem>
</orderedlist>
</para>
<example>
<title>For log4j version 1.2.x</title>
<programlisting>
import org.apache.log4j.Logger;
-...
+â¦
public class <replaceable>theClass</replaceable> {
-...
+â¦
private static final Logger LOG =
Logger.getLogger(<replaceable>theClass</replaceable>.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...");
+ LOG.fatal("This is fatal. The program stops now workingâ¦");
}
</programlisting>
</example>
@@ -194,7 +201,7 @@
temporary objects that would be created otherwise. Even if logging
is turned off for DEBUG and/or INFO level.
</para>
- <example id="example.log4j.speed">
+ <example xml:id="example.log4j.speed">
<title>Improving on speed/performance</title>
<programlisting>
if (LOG.isDebugEnabled()) {
@@ -215,7 +222,7 @@
</warning>
<para>
For more information go to the log4j homepage at
- <ulink url="http://jakarta.apache.org/log4j/">http://jakarta.apache.org/log4j</ulink>.
+ <link xlink:href="http://jakarta.apache.org/log4j/">http://jakarta.apache.org/log4j</link>.
</para>
<sect3>
@@ -233,7 +240,7 @@
the following log statement:
<programlisting>
int i;
-...
+â¦
LOG.debug("Entry number: " + i + " is " + entry[i]);
</programlisting>
It is quite innocent looking isn't it?
@@ -259,7 +266,7 @@
</sect2>
<sect2>
- <title>How to Enable Logging...</title>
+ <title>How to Enable Loggingâ¦</title>
<para>
log4j uses the command line parameter
<parameter>-Dlog4j.configuration = URL</parameter>
@@ -269,11 +276,11 @@
<example>
<title>Various URLs</title>
<programlisting>
-org/argouml/resource/<emphasis>filename.lcf</emphasis> <co id="ex.url.package"/>
+org/argouml/resource/<emphasis>filename.lcf</emphasis> <co xml:id="ex.url.package"/>
-http://localhost/shared/argouml/<emphasis>filename.lcf</emphasis> <co id="ex.url.link"/>
+http://localhost/shared/argouml/<emphasis>filename.lcf</emphasis> <co xml:id="ex.url.link"/>
-file://home/username/<emphasis>filename.lcf</emphasis> <co id="ex.url.file"/>
+file://home/username/<emphasis>filename.lcf</emphasis> <co xml:id="ex.url.file"/>
</programlisting>
<calloutlist>
<callout arearefs="ex.url.package"><para>
@@ -294,9 +301,9 @@
</calloutlist>
</example>
<sect3>
- <title>...when running ArgoUML from the command line</title>
+ <title>â¦when running ArgoUML from the command line</title>
<para>
- There are currently two ways of running
+ There are currently two possibilities of running
<application>ArgoUML</application> from the command
line:
<orderedlist>
@@ -349,7 +356,7 @@
</sect3>
<sect3>
- <title>...when running ArgoUML from WebStart</title>
+ <title>â¦when running ArgoUML from WebStart</title>
<para>
To view the console output, the WebStart user has to
set <parameter>Enable Java Console</parameter> in the
@@ -366,7 +373,7 @@
</sect3>
<sect3>
- <title>...when running ArgoUML from NetBeans</title>
+ <title>â¦when running ArgoUML from NetBeans</title>
<para>
At the time of writing this paragraph, it is not possible to
set the logging configuration file on a per project basis in
@@ -386,13 +393,13 @@
</sect2>
<sect2>
- <title>How to Customize Logging...</title>
+ <title>How to Customize Loggingâ¦</title>
<para>
There are some sample configuration files provided in
<parameter>org.argouml.resource</parameter>. Modify these according
to your needs.
- Or alternatively, you can try <ulink url="http://www.japhy.de/configLog4j">
- configLog4j</ulink> to assist yourself in creating a log4j configuration file.
+ Or alternatively, you can try <link xlink:href="http://www.japhy.de/configLog4j">
+ configLog4j</link> to assist yourself in creating a log4j configuration file.
</para>
</sect2>
@@ -401,12 +408,12 @@
<itemizedlist>
<listitem><para>
The log4j project homepage at
- <ulink url="http://jakarta.apache.org/log4j/">http://jakarta.apache.org/log4j</ulink>
+ <link xlink:href="http://jakarta.apache.org/log4j/">http://jakarta.apache.org/log4j</link>
</para>
</listitem>
<listitem><para>
The configlog4j homepage at
- <ulink url="http://www.japhy.de/configLog4j/">http://www.japhy.de/configLog4j</ulink>
+ <link xlink:href="http://www.japhy.de/configLog4j/">http://www.japhy.de/configLog4j</link>
</para>
</listitem>
<!-- TO DO
@@ -425,4 +432,4 @@
indent-tabs-mode: nil
End:
--->
+-->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemmodel.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemmodel.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemmodel.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemmodel.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemmodel.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemmodel.xml 2008-01-15 19:22:21-0800
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
// Copyright (c) 1996-2007 The Regents of the University of California. All
@@ -25,699 +25,278 @@
// UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
-->
-<sect1 id="model">
- <title>Model</title>
- <indexterm>
- <primary>Model</primary>
- </indexterm>
-
- <para id="comp-model-purpose">
-Purpose - To remove knowledge from the rest of ArgoUML of what model repository
-is in use (e.g. MDR, EMF, NSUML) and to give a consistent interface for
-manipulating data within those repositories.
-</para>
- <para>
-The Model is located in <classname>org.argouml.model</classname>.
-</para>
- <para>
- The Model is a Model subsystem
- according the MVC pattern
- (Model-View-Control).
-</para>
- <para>
-The Model class provides the rest of ArgoUML with various interfaces through
-which ArgoUML can manipulate the repository.
-</para>
-
- <para>
-The Model subsystem manages the well-formedness rules for the data in the
-repository for those well-formedness rules that are considered important to
-enforce.
-</para>
-
- <para>
-Currenty there are factory and helper interfaces for controlling the lifetime
-and properties of elements in the repository.
-</para>
- <para>
-An interface is also made available to the Diagram Interchange Model should the
-repository implementation contain such.
-</para>
- <para>
-A ModelEventPump interface is provided through which ArgoUML can listen for
-changes in the repository in a consistent way. Implementations of this pump
-convert from the repository specific events to PropertyChangeEvents.
-</para>
- <!--para>
-There are discussion underway to provide a facade (GOF p185) to this model.
-Once the facade is complete this is likely to take over as a replacement model
-interface. This will allow the complexities of the existing interfaces to be
-rationalized without affecting the facade user.
-</para-->
-
- <para>
-The factories contain all methods that deal with
-creating and building model elements.
-The helpers contain all utility methods needed to manipulate
-the model elements.
-Per section of the semantics chapter of the UML
-specification there is one factory
-and one helper.
-</para>
+<section
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xml:id="model"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ >
+
+ <title>Model</title>
+
+ <indexterm>
+ <primary>Model</primary>
+ </indexterm>
+
+ <para xml:id="comp-model-purpose" > Purpose - To remove knowledge from the rest of ArgoUML of what model repository is in use (e.g. MDR, EMF, NSUML) and to give a consistent interface for manipulating data within those repositories. </para>
+ <para>The Model is located in <classname>org.argouml.model</classname>. </para>
+ <para>The Model is a Model subsystem according the MVC pattern (Model-View-Control). </para>
+ <para>The Model class provides the rest of ArgoUML with various interfaces through which ArgoUML can manipulate the repository. </para>
+ <para>The Model subsystem manages the well-formedness rules for the data in the repository for those well-formedness rules that are considered important to enforce. </para>
+ <para>Currenty there are factory and helper interfaces for controlling the lifetime and properties of elements in the repository. </para>
+ <para>An interface is also made available to the Diagram Interchange Model should the repository implementation contain such. </para>
+ <para>A ModelEventPump interface is provided through which ArgoUML can listen for changes in the repository in a consistent way. Implementations of this pump convert from the repository specific events to PropertyChangeEvents. </para>
+ <!--para> There are discussion underway to provide a facade (GOF p185) to this model. Once the facade is complete this is likely to take over as a replacement model interface. This will allow the complexities of the existing interfaces to be rationalized without affecting the facade user. </para-->
+ <para>The factories contain all methods that deal with creating and building model elements. The helpers contain all utility methods needed to manipulate the model elements. Per section of the semantics chapter of the UML specification there is one factory and one helper. </para>
+
+ <section>
+ <title>Design of the subsystem</title>
+ <para>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. </para>
+ <para>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) </para>
+ <para>Both helpers and factories (and the Facade and ModelEventPump) are interfaces that are fetched through static methods in the Model object. </para>
+ <para>Because the same interface is used internally each implementation must provide objects for each of these interfaces. </para>
+ </section>
+
+ <section xml:id="model_factories">
+ <title>Factories</title>
+
+ <section>
+ <title>Create and Build</title>
+
+ <para>The factories contain in most cases a create method for each model element. Example: <methodname>createClass</methodname> resides in <classname>CoreFactory</classname>-interface. </para>
+ <para>Besides that, there are several build methods to build classes. The build methods have a signature like <methodsynopsis>
+ <modifier>public</modifier>
+ <type>Object</type>
+ <methodname>build<replaceable>MODELELEMENTNAME</replaceable></methodname>
+ <methodparam>
+ <parameter>
+ <replaceable>params</replaceable>
+ </parameter>
+ </methodparam>
+ </methodsynopsis>. </para>
+ <para>Each build method is intended to follow the wellformedness rules as defined in the UML spec. The reason for having extra build methods, is that the model repository does not enforce the wellformedness rules even though, in some cases, non-well-formed UML can lead to non-well-formed XMI which leads to saving/loading issues and all kinds of illegal states of ArgoUML. </para>
+ <para>If you want to create an element you shall use the build or create methods in the factories. You are strongly advised to use a build method or, if there is none that suits your needs, to write a new one reusing the already existing build methods and utility methods in the helpers. The reason for this is that the event listeners for the newly created model element are setup correctly. </para>
+ </section>
+
+ <section>
+ <title>Copy and DoCopy</title>
+
+ <para>The factories also contain methods that deal with copying modelelements. They are not supposed to be called directly from outside the model-subsystem, but only from the <classname>CopyHelper</classname>-implementation. The <classname>CopyHelper</classname> has one method that copies any modelelement into a new "location" (mostly a namespace). This method determines the type of element to copy, and then dispatches the call to the appropriate method of a Factory that is named similar to <methodname>copyClass</methodname>. </para>
+ <para>The responsability of the <methodname>copyModelElement</methodname> method is to create the new element (with <methodname>createModelElement</methodname>) and set the containment. Then, if necessary, sub-elements are to be created. E.g. the <classname>CoreFactoryMDRImpl</classname>. <methodname>copyEnumeration</methodname> method also creates EnumerationLiterals, with the <methodname>createEnumerationLiteral</methodname> method. </para>
+ <para>Then a next method is called to copy all the attributes from the old element to the newly created one: <methodname>doCopyModelElement</methodname>. This type of method shall only set attributes and lay associations, but not create any more elements. </para>
+ <para>The implementation of these copy related methods is far from complete. Only the CoreFactory already has the most important functions.</para>
+ </section>
+
+ <section>
+ <title>Multi-threading</title>
+
+ <para>Question: Am I allowed to call the factories from any thread? Answer: The current checks are not written to allow for multiple threads so don't! </para>
+ </section>
+ </section>
+
+ <section xml:id="model_helpers">
+ <title>Helpers</title>
+
+ <para>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 <methodname>getAllModelelementsOfKind</methodname> in <classname>ModelManagementHelper</classname>). </para>
+ <para>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 <classname>CoreHelper</classname>. </para>
+ <para>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. </para>
+ <para>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! </para>
+ </section>
+
+
+ <section>
+ <title>The model event pump</title>
+
+ <section>
+ <title>Introduction</title>
+
+ <para>Late 2002, the ArgoUML community decided for the introduction of a clean interface between the NSUML model and the rest of ArgoUML. This interface consists of three parts: <orderedlist>
+ <listitem>
+ <para>The model factories, responsible for creation and deletion of model elements </para>
+ </listitem>
+ <listitem>
+ <para>The model helpers, responsible for utility functions to manipulate the model elements and </para>
+ </listitem>
+ <listitem>
+ <para>The model event pump, responsible for sending model events to the rest of ArgoUML. </para>
+ </listitem>
+ </orderedlist>
+ </para>
+
+ <para>The model factories and the model helpers are described in <xref xlink:href="#model_factories" /> and <xref xlink:href="#model_helpers" /> respectively. </para>
+ <para>In the beginning of 2003, in the work to replace NSUML, the need was seen for this interface to not use any NSUML classes. The <classname>ModelFacade</classname> was introduced to wrap model factories, model helpers, and direct calls to NSUML but not the model event pump. In April 2004 a <classname>ModelEventPump</classname>-interface was introduced to wrap the <classname>UmlModelEventPump</classname> using <classname>PropertyChangeEvent</classname>s. </para>
+ <para>The model event pump is the gateway between the model elements and the rest of ArgoUML. Events fired by the model elements are caught by the pump and then 'pumped' to those listeners interested in them. The main advantage of this model is that the registration of listeners is concentrated in one place (see picture *). This makes it easier to change the interface between the model and the rest of ArgoUML. </para>
+ <para>Besides this, there are some improvements to the performance of the pump made in comparison to the situation without the pump. The main improvement is that you can register for just one type of event and not for all events fired by some model element. In this respect the pump works as a filter. </para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/cookbook/eventsbeforepump.gif" format="GIF" />
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/cookbook/eventsafterpump.gif" format="GIF" />
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>The model event pump will replace all other event mechanisms for model events in the future. These mechanisms (like UMLChangeDispatch and ThirdPartyEventlisteners for those who are interested) are DEPRECATED. Do not use them therefore and do not use classes that use them. </para>
+ </section>
+
+ <section>
+ <title>Public API</title>
+
+ <para>You might wonder: how does this all work? Well, very simple in fact. </para>
+ <para>A model event (from now on a Event) has a name that uniquely identifies the type of the event. In most cases the name of the Event is equal to the name of the property that was changed in the model. In fact, there is even a 1-1 relationship between the type of Event and the property changed in the model. Therefore most listeners that need Events are only interested in one type of Event since they are only interested in the status of 1 property. </para>
+ <para>TODO: What thread will I receive my event in? What locks will be held by the Model while I receive my event i.e. is there something I cannot do from the event thread? </para>
+ <para>In the case described above (the most common one) you only have to subscribe with the pump for that type of event. This is explained in section <xref xlink:href="#pump-register-listener-for-type" /> and <xref xlink:href="#pump-remove-listener-for-event" /> </para>
+ <para>Besides the case that you are interested in only one type of event (or a set of types), there are occasions that you are interested in all events fired by a certain model element or even for all events fired by a certain type of model element. For these cases, the pump has functionality too. This is described in section <xref xlink:href="#pump-methods-for-adding-and-removing" />. </para>
+
+ <section xml:id="pump-register-listener-for-type">
+ <title> How do I register a listener for a certain type event </title>
+ <para>This is really very simple. Use the model <programlisting> addModelEventListener(PropertyChangeListener listener, Object modelelement, String eventName) </programlisting> like this: <programlisting> Model.getPump().addModelEventListener(this, modelelementIAmInterestedIn, "IamInterestedInThisEventnameType"); </programlisting> Now your object this gets only the <classname>Events</classname> fired by modelElementIAmInterestedIn that have the name "IamInterestedInThisEventnameType". </para>
+ </section>
+
+ <section xml:id="pump-remove-listener-for-event">
+ <title>How do I remove a listener for a certain event</title>
+ <para>This is the opposite of registering a listener. It all works with the method <programlisting> removeModelEventListener(PropertyChangeListener listener, Object modelElement, String eventName) </programlisting> on the <classname>ModelEventPump</classname> like this: <programlisting> Model.getPump().removeModelEventListener(this, modelelementIAmInterestedIn, "IamInterestedInThisEventnameType"); </programlisting> Now your object is not registered any more for this event type. </para>
+ </section>
+
+ <section xml:id="pump-methods-for-adding-and-removing">
+ <title> Hey, I saw some other methods for adding and removing? </title>
+
+ <para>Yes there are some other method for adding and removing. You can add a listener that is interested in ALL events fired by a certain model elements. This works with the method: <programlisting> addModelEventListener(PropertyChangeListener listener, Object modelelement) </programlisting> As you can see no names of events you can register for here. </para>
+ <para>Furthermore, you can add a listener that is interested in several types of events but coming from 1 model element. This is a convenience method for not having to call the methods explained in section <xref xlink:href="#pump-register-listener-for-type" /> more than once. It works via: <programlisting> addModelEventListener(PropertyChangeListener listener, Object modelelement, String[] eventNames) </programlisting> </para>
+ <para>You can pass the method an array of strings with event names in which your listener is interested. </para>
+ <para>Thirdly there is a very powerful method to register your listener to ALL events fired by a ALL model elements of a certain class. You can understand that using this method can have severe performance impacts. Therefore use it with care. The method is: <programlisting> addClassModelEventListener(PropertyChangeListener listener, Object modelClass) </programlisting> There are also methods that allow you to register only for one type of event fired by all model elements of a certain class and to register for a set of types of events fired by all mod elements of a certain class. </para>
+ <para>Of course you can remove your listeners from the event pump. This works with methods starting with remove instead of add. </para>
+ </section>
+ </section>
+
+ <section>
+ <title>Tips</title>
+
+ <orderedlist>
+ <listitem>
+ <para>Don't forget to remove your listener from the event pump if it's not interested in some event any more. </para>
+ <para>If you do not remove it, that's gonna cost performance and it will give you a hard time to debug all the logical bugs you see in your listener. </para>
+ </listitem>
+ <listitem>
+ <para>When you implement your listener, it is wise to NOT DO the following: <programlisting> propertyChanged(MElementEvent event) { // do my thing for event type 1 // do my thing for event type 2 // etc. } </programlisting>
+ </para>
+ <para>This will cause the things that need to be done for event type 1 to be fired when event type 2 do arrive. </para>
+ <para>This still happens at a lot of places in the code of ArgoUML, most notably in the modelChanged method of the children of FigEdgeModelElement. </para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section>
+ <title>Possible investigation points and improvements</title>
+
+ <para>Should we use our own event types? </para>
+ <para>Should we replace the <classname>MElementListener</classname> with <classname>PropertyChangeListener</classname> and <classname>MElementEvent</classname> with <classname>PropertyChangeEvent</classname>? One reason we have not done so yet is that it involves a lot of work and testing. </para>
+ <para>Should we change the implementation of the Event pump itself? Not the API but the implementation! </para>
+ <para>At the moment the event pump does not use the AWT Event Thread for dispatching events. This can make ArgoUML slow (in the perception of the user). </para>
+ <para>Use the standard data structure that Swing uses for event registration (i.e. <classname>javax.swing.EventListenerList</classname>). Would this be an improvement? </para>
+ </section>
+ </section>
+
+
+ <section>
+ <title>NSUML specifics</title>
+
+ <para>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. </para>
+ </section>
+
+ <section>
+ <title>The use of IDs in MDR</title>
+
+ <para>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. </para>
+ <para>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. </para>
+ </section>
+
+ <section xml:id="working-with-the-model">
+ <title>How to work against the model</title>
+
+ <para>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). </para>
+ <para>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 <classname>org.argouml.model</classname> package. The NSUML or MDR and whatever other implementation we eventually come up with would provide the implementation of those interfaces. </para>
+
+ <table>
+
+ <title>How to work against the model</title>
+
+ <tgroup cols="4">
+ <colspec colnum="1" colname="What" colwidth="1*" />
+ <colspec colnum="2" colname="NSUML" colwidth="2*" />
+ <colspec colnum="3" colname="MDR" colwidth="2*" />
+ <colspec colnum="4" colname="Model" colwidth="3*" />
+ <thead>
+ <row>
+ <entry>What</entry>
+ <entry>NSUML (use only within Model subsystem)</entry>
+ <entry>MDR (use only within Model subsystem)</entry>
+ <entry>Model subsystem</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>Test that an Object o has a certain type</entry>
+ <entry>o instanceof M<replaceable>modelelementtype</replaceable> → boolean </entry>
+ <entry> ???CLASSNAME???​.isInstanceOf(​RefObject toTest, String className) → boolean </entry>
+ <entry> Model.getFacade()​.isA<replaceable>modelelementtype</replaceable>(o) → boolean </entry>
+ </row>
+ <row>
+ <entry>Get a single valued model element from an Object o</entry>
+ <entry> ((M<replaceable>modelelementtype</replaceable>)o)​.get<replaceable>property</replaceable>() → model element </entry>
+ <entry> ((RefFeatured)obj)​.refGetValue(​String propName) → ???Type??? </entry>
+ <entry> Model.getFacade()​.get<replaceable>property</replaceable>(o) → Object </entry>
+ </row>
+ <row>
+ <entry>Get a multi valued property from an Object o</entry>
+ <entry> ((M<replaceable>modelelementtype</replaceable>)o)​.get<replaceable>property</replaceable>() → Collection </entry>
+ <entry> ((RefFeatured)obj)​.refGetValue(String propName) → Collection </entry>
+ <entry> Model.getFacade()​.get<replaceable>property</replaceable>(o) → Iterator or Collection (total confusion!) </entry>
+ </row>
+ <row>
+ <entry>Create a new model element of type Type:</entry>
+ <entry> MFactory​.getDefaultFactory()​.create<replaceable>Type</replaceable>() </entry>
+ <entry> ???CLASSNAME???​.creatInstance(​String "<replaceable>Type</replaceable>", List argument) → RefObject </entry>
+ <entry> Model​.get<replaceable>ModelElementDomain?</replaceable>Factory​.build<replaceable>modelelementtype</replaceable>(args) or Model​.get<replaceable>ModelElementDomain?</replaceable>Factory​.create<replaceable>modelelementtype</replaceable>() to create them completely empty. </entry>
+ </row>
+ <row>
+ <entry>Delete a model element</entry>
+ <entry> </entry>
+ <entry> </entry>
+ <entry> Model​.getUmlFactory()​.delete(​<replaceable>object</replaceable>) ⦠but only call this function from Project.moveToTrash(Object). </entry>
+ </row>
+ <row>
+ <entry> Register for notification that a model element Object o has changed: </entry>
+ <entry> ((MBase) o)​.addMElementListener(​MElementListener el) </entry>
+ <entry> ((MDRChangeSource) obj)​.addChangeListener(???) </entry>
+ <entry> Model.getPump()​.addModelEventListener(​(PropertyChangeListener)li, Object o, String[] eventnames) </entry>
+ </row>
+ <row>
+ <entry> Register for notification on all model elements of a certain type Type: </entry>
+ <entry> Not possible! </entry>
+ <entry> ((MDRChangeSource)obj​.refClass())​.addChangeListener(???) </entry>
+ <entry> Model.getPump()​.addModelEventListener(​(PropertyChangeListener)li, (Object)Model​.getMetaTypes()​.getMODELELEMENTTYPE(), String[] eventnames) </entry>
+ </row>
+ <row>
+ <entry>How do I get the model as XMI on the stream Stream:</entry>
+ <entry> (new XMIWriter(MModel m, Writer Stream)).gen() </entry>
+ <entry> new XMIWriter(???) </entry>
+ <entry> Handled by the Persistence subsystem. </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
- <sect2>
- <title>Design of the subsystem</title>
- <para>
-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.
-</para>
- <para>
-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)
-</para>
-
- <para>
-Both helpers and factories (and the Facade and ModelEventPump)
-are interfaces that are fetched through static methods in the Model object.
-</para>
- <para>
-Because the same interface is used internally
-each implementation must provide objects for each of these interfaces.
-</para>
- </sect2>
-
- <sect2 id="model_factories">
- <title>Factories</title>
- <sect3>
- <title>Create and Build</title>
- <para>
-The factories contain in most cases a create method for each model element.
-Example: <methodname>createClass</methodname>
-resides in <classname>CoreFactory</classname>-interface.
-</para>
- <para>
-Besides that, there are several build methods to build classes.
-The build methods have a signature like
-<methodsynopsis>
- <modifier>public</modifier>
- <type>Object</type>
- <methodname>build<replaceable>MODELELEMENTNAME</replaceable></methodname>
- <methodparam>
- <parameter><replaceable>params</replaceable></parameter>
- </methodparam>
- </methodsynopsis>.
-</para>
- <para>
-Each build method is intended to follow the wellformedness rules
-as defined in the UML spec.
-The reason for having extra build methods,
-is that the model repository does not enforce
-the wellformedness rules even though, in some cases,
-non-well-formed UML can lead to
-non-well-formed XMI which leads to saving/loading issues and
-all kinds of illegal states of ArgoUML.
-</para>
- <para>
-If you want to create an element you shall use the build or create methods
-in the factories.
-You are strongly advised to use a build method or, if there is
-none that suits your needs, to write a new one reusing the already
-existing build methods and utility methods in the helpers.
-The reason for this is that the event listeners for
-the newly created model element are setup correctly.
-</para>
- </sect3>
-
- <sect3>
- <title>Copy and DoCopy</title>
- <para>The factories also contain methods that deal with copying
- modelelements.
- They are not supposed to be called directly
- from outside the model-subsystem, but only from the
- <classname>CopyHelper</classname>-implementation.
- The <classname>CopyHelper</classname> has one method
- that copies any modelelement into a new
- "location" (mostly a namespace).
- This method determines the type of element to copy,
- and then dispatches the call to the appropriate method
- of a Factory that is named
- similar to <methodname>copyClass</methodname>.
- </para>
-
- <para>
- The responsability of the <methodname>copyModelElement</methodname>
- method is to create the new element
- (with <methodname>createModelElement</methodname>)
- and set the containment.
- Then, if necessary, sub-elements are to be created.
- E.g. the <classname>CoreFactoryMDRImpl</classname>.
- <methodname>copyEnumeration</methodname> method
- also creates EnumerationLiterals, with the
- <methodname>createEnumerationLiteral</methodname> method.
- </para>
-
- <para>
- Then a next method is called to copy all the attributes
- from the old element to the newly created one:
- <methodname>doCopyModelElement</methodname>.
- This type of method shall
- only set attributes and lay associations,
- but not create any more elements.
- </para>
-
- <para>The implementation of these copy related methods
- is far from complete.
- Only the CoreFactory already has
- the most important functions.</para>
- </sect3>
- <sect3>
- <title>Multi-threading</title>
- <para>
-Question: Am I allowed to call the factories from any thread?
-Answer: The current checks are not written to allow for multiple threads
-so don't!
-</para>
- </sect3>
- </sect2>
- <sect2 id="model_helpers">
- <title>Helpers</title>
- <para>
-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 <methodname>getAllModelelementsOfKind</methodname> in
-<classname>ModelManagementHelper</classname>).
-</para>
- <para>
-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 <classname>CoreHelper</classname>.
-</para>
- <para>
-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.
-</para>
- <para>
-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!
-</para>
- </sect2>
-
-
- <sect2>
- <title>The model event pump</title>
- <sect3>
- <title>Introduction</title>
- <para>
-Late 2002, the ArgoUML community decided for the introduction of a clean
-interface between the NSUML model and the rest of ArgoUML.
-This interface consists of three parts:
-<orderedlist>
- <listitem>
- <para>
-The model factories, responsible for creation and deletion of model elements
-</para>
- </listitem>
- <listitem>
- <para>
-The model helpers, responsible for utility functions to manipulate the
-model elements and
-</para>
- </listitem>
- <listitem>
- <para>
-The model event pump, responsible for sending model events to the rest
-of ArgoUML.
-</para>
- </listitem>
- </orderedlist>
-</para>
- <para>
-The model factories and the model helpers are described in
-<xref linkend="model_factories"/> and
-<xref linkend="model_helpers"/> respectively.
-</para>
- <para>
-In the beginning of 2003, in the work to replace NSUML, the need
-was seen for this interface to not use any NSUML classes.
-The <classname>ModelFacade</classname> was introduced to wrap
-model factories,
-model helpers, and
-direct calls to NSUML
-but not the model event pump.
-In April 2004 a <classname>ModelEventPump</classname>-interface
-was introduced to wrap
-the <classname>UmlModelEventPump</classname>
-using <classname>PropertyChangeEvent</classname>s.
-</para>
- <para>
-The model event pump is the gateway between the model elements and the
-rest of ArgoUML.
-Events fired by the model elements are caught by the pump and then
-'pumped' to those listeners interested in them.
-The main advantage of this model is that the registration of listeners
-is concentrated in one place (see picture *).
-This makes it easier to change the interface between the model and the
-rest of ArgoUML.
-</para>
- <para>
-Besides this, there are some improvements to the performance of the
-pump made in comparison to the situation without the pump.
-The main improvement is that you can register for just one type of
-event and not for all events fired by some model element.
-In this respect the pump works as a filter.
-</para>
- <para>
-<mediaobject>
- <imageobject>
- <imagedata fileref="images/cookbook/eventsbeforepump.gif" format="GIF"/>
- </imageobject>
- </mediaobject>
-</para>
- <para>
-<mediaobject>
- <imageobject>
- <imagedata fileref="images/cookbook/eventsafterpump.gif" format="GIF"/>
- </imageobject>
- </mediaobject>
-</para>
-
- <para>
-The model event pump will replace all other event mechanisms for model
-events in the future.
-These mechanisms (like UMLChangeDispatch and ThirdPartyEventlisteners
-for those who are interested) are DEPRECATED.
-Do not use them therefore and do not use classes that use them.
-</para>
- </sect3>
- <sect3>
- <title>Public API</title>
- <para>
-You might wonder: how does this all work?
-Well, very simple in fact.
-</para>
- <para>
-A model event (from now on a Event) has a name that uniquely
-identifies the type of the event.
-
-In most cases the name of the Event is equal to the name of the
-property that was changed in the model.
-
-In fact, there is even a 1-1 relationship between the type of Event
-and the property changed in the model.
-
-Therefore most listeners that need Events are only interested in one
-type of Event since they are only interested in the status of 1
-property.
-</para>
- <para>
-TODO: What thread will I receive my event in?
-What locks will be held by the Model while I receive my event i.e.
-is there something I cannot do from the event thread?
-</para>
- <para>
-In the case described above (the most common one) you only have to
-subscribe with the pump for that type of event.
-This is explained in section <xref linkend="pump-register-listener-for-type"/>
-and <xref linkend="pump-remove-listener-for-event"/>
-</para>
- <para>
-Besides the case that you are interested in only one type of event (or
-a set of types), there are occasions that you are interested in all
-events fired by a certain model element or even for all events fired by
-a certain type of model element.
-
-For these cases, the pump has functionality too.
-
-This is described in section
-<xref linkend="pump-methods-for-adding-and-removing"/>.
-</para>
- <sect4 id="pump-register-listener-for-type">
- <title>
-How do I register a listener for a certain type event
-</title>
- <para>
-This is really very simple. Use the model
-<programlisting>
-addModelEventListener(PropertyChangeListener listener, Object modelelement, String eventName)
-</programlisting>
-like this:
-<programlisting>
-Model.getPump().addModelEventListener(this, modelelementIAmInterestedIn, "IamInterestedInThisEventnameType");
-</programlisting>
-Now your object this gets only the <classname>Events</classname>
-fired by modelElementIAmInterestedIn that have the name
-"IamInterestedInThisEventnameType".
-</para>
- </sect4>
- <sect4 id="pump-remove-listener-for-event">
- <title>How do I remove a listener for a certain event</title>
- <para>
-This is the opposite of registering a listener. It all works with the
-method
-<programlisting>
-removeModelEventListener(PropertyChangeListener listener, Object modelElement, String eventName)
-</programlisting>
-on the <classname>ModelEventPump</classname> like this:
-<programlisting>
-Model.getPump().removeModelEventListener(this, modelelementIAmInterestedIn, "IamInterestedInThisEventnameType");
-</programlisting>
-Now your object is not registered any more for this event type.
-</para>
- </sect4>
- <sect4 id="pump-methods-for-adding-and-removing">
- <title>
-Hey, I saw some other methods for adding and removing?
-</title>
- <para>
-Yes there are some other method for adding and removing.
-
-You can add a listener that is interested in ALL events fired by a
-certain model elements.
-
-This works with the method:
-<programlisting>
-addModelEventListener(PropertyChangeListener listener, Object modelelement)
-</programlisting>
-As you can see no names of events you can register for here.
-</para>
- <para>
-Furthermore, you can add a listener that is interested in several
-types of events but coming from 1 model element.
-
-This is a convenience method for not having to call the methods
-explained in section
-<xref linkend="pump-register-listener-for-type"/>
-more than once.
-
-It works via:
-<programlisting>
-addModelEventListener(PropertyChangeListener listener, Object modelelement, String[] eventNames)
-</programlisting>
-</para>
- <para>
-You can pass the method an array of strings with event names in which
-your listener is interested.
-</para>
- <para>
-Thirdly there is a very powerful method to register your listener to
-ALL events fired by a ALL model elements of a certain class.
-
-You can understand that using this method can have severe performance
-impacts.
-Therefore use it with care.
-
-The method is:
-<programlisting>
-addClassModelEventListener(PropertyChangeListener listener, Object modelClass)
-</programlisting>
-There are also methods that allow you to register only for one type of
-event fired by all model elements of a certain class and to register
-for a set of types of events fired by all mod elements of a certain
-class.
-</para>
- <para>
-Of course you can remove your listeners from the event pump.
-This works with methods starting with remove instead of add.
-</para>
- </sect4>
- </sect3>
- <sect3>
- <title>Tips</title>
- <orderedlist>
- <listitem>
- <para>
-Don't forget to remove your listener from the event pump if it's not
-interested in some event any more.
-</para>
- <para>
-If you do not remove it, that's gonna cost performance and it will
-give you a hard time to debug all the logical bugs you see in your
-listener.
-</para>
- </listitem>
- <listitem>
- <para>
-When you implement your listener, it is wise to NOT DO the following:
-<programlisting>
-propertyChanged(MElementEvent event) {
- // do my thing for event type 1
- // do my thing for event type 2
- // etc.
-}
-</programlisting>
-</para>
- <para>
-This will cause the things that need to be done for event type 1 to be
-fired when event type 2 do arrive.
-</para>
- <para>
-This still happens at a lot of places in the code of ArgoUML, most
-notably in the modelChanged method of the children of
-FigEdgeModelElement.
-</para>
- </listitem>
- </orderedlist>
- </sect3>
- <sect3>
- <title>Possible investigation points and improvements</title>
- <para>
-Should we use our own event types?
-</para>
- <para>
-Should we replace
-the <classname>MElementListener</classname>
-with <classname>PropertyChangeListener</classname> and
-<classname>MElementEvent</classname>
-with <classname>PropertyChangeEvent</classname>?
-
-One reason we have not done so yet is that it involves a lot of work and
-testing.
-</para>
- <para>
-Should we change the implementation of the Event pump
-itself?
-
-Not the API but the implementation!
-</para>
- <para>
-At the moment the event pump does not use the AWT Event Thread for
-dispatching events.
-
-This can make ArgoUML slow (in the perception of the user).
-</para>
- <para>
-Use the standard
-data structure that Swing uses for event registration
-(i.e. <classname>javax.swing.EventListenerList</classname>).
-
-Would this be an improvement?
-</para>
- </sect3>
- </sect2>
-
-
- <sect2>
- <title>NSUML specifics</title>
- <para>
-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.
-</para>
-
- </sect2>
-
- <sect2>
- <title>The use of IDs in MDR</title>
- <para>
-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.
- </para>
- <para>
-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.
- </para>
- </sect2>
-
- <sect2 id="working-with-the-model">
- <title>How to work against the model</title>
-
- <para>
-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).
-</para>
- <para>
-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 <classname>org.argouml.model</classname> package.
-The NSUML or MDR and whatever other implementation we eventually
-come up with would provide the implementation of those interfaces.
-</para>
- <table>
- <title>How to work against the model</title>
- <tgroup cols="4">
- <colspec colnum="1" colname="What" colwidth="1*"/>
- <colspec colnum="2" colname="NSUML" colwidth="2*"/>
- <colspec colnum="3" colname="MDR" colwidth="2*"/>
- <colspec colnum="4" colname="Model" colwidth="3*"/>
- <thead>
- <row>
- <entry>What</entry>
- <entry>NSUML (use only within Model subsystem)</entry>
- <entry>MDR (use only within Model subsystem)</entry>
- <entry>Model subsystem</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>Test that an Object o has a certain type</entry>
- <entry>
-o instanceof M<replaceable>modelelementtype</replaceable> → boolean
-</entry>
- <entry>
-???CLASSNAME???​.isInstanceOf(​RefObject toTest, String className) → boolean
-</entry>
- <entry>
-Model.getFacade()​.isA<replaceable>modelelementtype</replaceable>(o) → boolean
-</entry>
- </row>
-
- <row>
- <entry>Get a single valued model element from an Object o</entry>
- <entry>
-((M<replaceable>modelelementtype</replaceable>)o)​.get<replaceable>property</replaceable>()
-→ model element
-</entry>
- <entry>
-((RefFeatured)obj)​.refGetValue(​String propName) → ???Type???
-</entry>
- <entry>
-Model.getFacade()​.get<replaceable>property</replaceable>(o) → Object
-</entry>
- </row>
- <row>
- <entry>Get a multi valued property from an Object o</entry>
- <entry>
-((M<replaceable>modelelementtype</replaceable>)o)​.get<replaceable>property</replaceable>()
-→ Collection
-</entry>
- <entry>
-((RefFeatured)obj)​.refGetValue(String propName) → Collection
-</entry>
- <entry>
-Model.getFacade()​.get<replaceable>property</replaceable>(o)
-→ Iterator or Collection (total confusion!)
-</entry>
- </row>
- <row>
- <entry>Create a new model element of type Type:</entry>
- <entry>
-MFactory​.getDefaultFactory()​.create<replaceable>Type</replaceable>()
-</entry>
- <entry>
-???CLASSNAME???​.creatInstance(​String "<replaceable>Type</replaceable>",
- List argument)
-→ RefObject
-</entry>
- <entry>
-Model​.get<replaceable>ModelElementDomain?</replaceable>Factory​.build<replaceable>modelelementtype</replaceable>(args)
-or
-Model​.get<replaceable>ModelElementDomain?</replaceable>Factory​.create<replaceable>modelelementtype</replaceable>()
-to create them completely empty.
-</entry>
- </row>
- <row>
- <entry>Delete a model element</entry>
- <entry>
-
- </entry>
- <entry>
-
- </entry>
- <entry>
-Model​.getUmlFactory()​.delete(​<replaceable>object</replaceable>)
- ... but only call this function from Project.moveToTrash(Object).
- </entry>
- </row>
- <row>
- <entry>
-Register for notification that a model element Object o has changed:
-</entry>
- <entry>
-((MBase) o)​.addMElementListener(​MElementListener el)
-</entry>
- <entry>
-((MDRChangeSource) obj)​.addChangeListener(???)
-</entry>
- <entry>
-Model.getPump()​.addModelEventListener(​(PropertyChangeListener)li,
- Object o, String[] eventnames)
-</entry>
- </row>
- <row>
- <entry>
-Register for notification on all model elements of a certain type Type:
-</entry>
- <entry>
-Not possible!
-</entry>
- <entry>
-((MDRChangeSource)obj​.refClass())​.addChangeListener(???)
-</entry>
- <entry>
-Model.getPump()​.addModelEventListener(​(PropertyChangeListener)li,
- (Object)Model​.getMetaTypes()​.getMODELELEMENTTYPE(),
- String[] eventnames)
-</entry>
- </row>
- <row>
- <entry>How do I get the model as XMI on the stream Stream:</entry>
- <entry>
-(new XMIWriter(MModel m, Writer Stream)).gen()
-</entry>
- <entry>
-new XMIWriter(???)
-</entry>
- <entry>
-Handled by the Persistence subsystem.
-</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </sect2>
-
- <!--
+ <!--
<sect2>
<title>Collaborations for Model</title>
<para>
@@ -727,73 +306,34 @@
</sect2>
-->
- <sect2 id="howdoi_model">
- <title>How do I...?</title>
- <itemizedlist>
- <listitem>
- <para>...add a new model element?</para>
- <para>
-<!-- TODO: This needs to be updated for Model subsystem -->
-Make a parameterless build method for your model element in one of
-the UML Factories (for instance <classname>CoreFactory</classname>).
-Use the UML 1.4 spec to choose the correct Factory.
-The package structure under <classname>org.argouml.model</classname>
-follows the chapters in the UML spec so get it and read it!
-In the build method, create a new model element using the appropriate
-create method in the factory.
-The build method e.g. is a wrapper around the create method.
-For all elements there are already create methods (thanks Thierry).
-For some elements there are already build methods.
-If you need one of these elements, use the build method before you
-barge into building new ones.
-Initialize all things you need in the build method as far as they
-don't need other model elements.
-In the UML spec you can read which elements you need to initialize.
-See for example <methodname>buildAttribute()</methodname> for an example.
-</para>
- <para>
-If you need to attach other already existing model elements to your
-model element make a
-<methodname>build<replaceable>XXXX</replaceable>(MModelelement
- toattach1, ...)
-</methodname>
-method in the factory where you made the build method.
-Don't ever call the create methods directly.
-If we use the build methods we will always have initialized
-model elements which will make a difference concerning save/load issues
-for example.
-</para>
- <para>
-Now you probably also need to create
-a Property Panel
-and
-a Fig object (See <xref linkend="howto_createnewfig_2"></xref>).
-</para>
- </listitem>
- <listitem>
- <para>...create a new create method?</para>
- <para>
-Create it in the correct factory.
-</para>
- </listitem>
- <listitem>
- <para>...create a new utility method?</para>
- <para>
-Create it in the correct helper.
-</para>
- </listitem>
- <listitem>
- <para>...delete a model element?</para>
- <para>
-Project.moveToTrash(Object obj).
-</para>
-<para>(See issue 2353.)</para>
- </listitem>
- </itemizedlist>
- </sect2>
- </sect1>
-
-
+ <section xml:id="howdoi_model">
+ <title>How do I�</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>â¦add a new model element?</para>
+ <para>
+ <!-- TODO: This needs to be updated for Model subsystem --> Make a parameterless build method for your model element in one of the UML Factories (for instance <classname>CoreFactory</classname>). Use the UML 1.4 spec to choose the correct Factory. The package structure under <classname>org.argouml.model</classname> follows the chapters in the UML spec so get it and read it! In the build method, create a new model element using the appropriate create method in the factory. The build method e.g. is a wrapper around the create method. For all elements there are already create methods (thanks Thierry). For some elements there are already build methods. If you need one of these elements, use the build method before you barge into building new ones. Initialize all things you need in the bu
ild method as far as they don't need other model elements. In the UML spec you can read which elements you need to initialize. See for example <methodname>buildAttribute()</methodname> for an example. </para>
+ <para>If you need to attach other already existing model elements to your model element make a <methodname>build<replaceable>XXXX</replaceable>(MModelelement toattach1, â¦) </methodname> method in the factory where you made the build method. Don't ever call the create methods directly. If we use the build methods we will always have initialized model elements which will make a difference concerning save/load issues for example. </para>
+ <para>Now you probably also need to create a Property Panel and a Fig object (See <xref
+ xlink:href="#howto_createnewfig_2" />). </para>
+ </listitem>
+ <listitem>
+ <para>â¦create a new create method?</para>
+ <para>Create it in the correct factory. </para>
+ </listitem>
+ <listitem>
+ <para>â¦create a new utility method?</para>
+ <para>Create it in the correct helper. </para>
+ </listitem>
+ <listitem>
+ <para>â¦delete a model element?</para>
+ <para>Project.moveToTrash(Object obj). </para>
+ <para>(See issue 2353.)</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+</section>
<!-- Local stuff for Emacs - please do not delete
Local Variables:
@@ -805,5 +345,4 @@
indent-tabs-mode: nil
End:
--->
-
+-->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemnotation.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemnotation.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemnotation.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemnotation.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemnotation.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystemnotation.xml 2008-01-15 19:22:21-0800
@@ -1,36 +1,44 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
-// Copyright (c) 2005-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.
+ // Copyright (c) 2005-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.
-->
-<sect1 id="notation">
+<sect1
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xml:id="notation">
+
<title>Notation</title>
+
<indexterm>
<primary>Notation</primary>
</indexterm>
-
+
<para>
Purpose - To handle generating, updating and editing
in different languages
@@ -47,21 +55,21 @@
<classname>org.argouml.notation</classname>
and its sub-folders.
</para>
-
- <figure id="fig.notation.1" float="1">
+
+ <figure xml:id="fig.notation.1" float="1">
<title>Notation subsystem part 1.</title>
-
+
<screenshot><mediaobject>
- <imageobject>
- <imagedata format="PNG" align="center"
- fileref="images/cookbook/notation1.png"/>
- </imageobject>
- </mediaobject></screenshot>
+ <imageobject>
+ <imagedata format="PNG" align="center"
+ fileref="images/cookbook/notation1.png"/>
+ </imageobject>
+ </mediaobject></screenshot>
</figure>
-
+
<para>
In the scope of issue 3140,
- the notation architecture has been discussed.
+ the notation architecturehas been discussed.
Later, a change has been performed to resolve dependency cycles.
</para>
<para>
@@ -70,13 +78,13 @@
shall be a user-choice with project scope -
and we will never refine the scope
to something more detailed.
- Hence we need not store the notation language per Fig.
+ Hence we need not store the notationlanguage per Fig.
So, this means that you can set
the notation language in the project properties,
and in the application-wide defaults.
</para>
-
+
<para>
The interface NotationProvider is at the center of the subsystem.
There is an object implementing the NotationProvider interface
@@ -90,7 +98,7 @@
which UML objects it represents,
generate and parse and provide a help text.
</para>
-
+
<para>
The Fig refreshes the text by calling
the toString() method of the Notationprovider,
@@ -109,27 +117,27 @@
This causes the Notationprovider to update the set of listeners, and
the Fig refreshes the rendering of its string.
</para>
-
- <figure id="fig.notation.2" float="1">
+
+ <figure xml:id="fig.notation.2" float="1">
<title>Notation subsystem part 2.</title>
-
+
<screenshot><mediaobject>
- <imageobject>
- <imagedata format="PNG" align="center"
- fileref="images/cookbook/notation2.png"/>
- </imageobject>
- </mediaobject></screenshot>
+ <imageobject>
+ <imagedata format="PNG" align="center"
+ fileref="images/cookbook/notation2.png"/>
+ </imageobject>
+ </mediaobject></screenshot>
</figure>
-
+
<para>
The NotationProvider objects
TransitionNotation, StateBodyNotation, etc.
are abstract,
since they are specialised in classes that implement them
for a certain language, i.e. one per language.
- So, we will have: TransitionNotationUML, TransitionNotationJava, ... etc.
+ So, we will have: TransitionNotationUML, TransitionNotationJava, ⦠etc.
</para>
-
+
<para>
The NotationProviderFactory2 is a singleton,
since it is the accesspoint for all Figs to create
@@ -138,8 +146,8 @@
Once/if ArgoUML would support multiple projects,
then we would need one NotationProviderFactory2
per project, since its language may differ per project.
-</para>
-
+ </para>
+
<para>
The NotationProviderFactory2 creates
a notation object
@@ -155,30 +163,30 @@
and ask the NotationProviderFactory2
to create a new NotationProvider child.
</para>
-
- <figure id="fig.notation.3" float="1">
+
+ <figure xml:id="fig.notation.3" float="1">
<title>Notation subsystem part 3.</title>
-
+
<screenshot><mediaobject>
- <imageobject>
- <imagedata format="PNG" align="center"
- fileref="images/cookbook/notation3.png"/>
- </imageobject>
- </mediaobject></screenshot>
+ <imageobject>
+ <imagedata format="PNG" align="center"
+ fileref="images/cookbook/notation3.png"/>
+ </imageobject>
+ </mediaobject></screenshot>
</figure>
-
+
</sect1>
<!-- Local stuff for Emacs - please do not delete
-
-Local Variables:
-mode: xml
-sgml-doctype: "cookbook.xml"
-sgml-parent-document: ("cookbook.xml" "sect1" nil)
-sgml-validate-command: "nsgmls -wxml -sv ../docbook-setup/xml.dcl \
+
+ Local Variables:
+ mode: xml
+ sgml-doctype: "cookbook.xml"
+ sgml-parent-document: ("cookbook.xml" "sect1" nil)
+ sgml-validate-command: "nsgmls -wxml -sv ../docbook-setup/xml.dcl \
cookbook.xml"
-indent-tabs-mode: nil
-End:
-
--->
+ indent-tabs-mode: nil
+ End:
+
+-->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystempersistence.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystempersistence.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystempersistence.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystempersistence.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystempersistence.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystempersistence.xml 2008-01-15 19:22:21-0800
@@ -1,31 +1,38 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
-// Copyright (c) 2005-2006 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.
+ // Copyright (c) 2005-2006 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.
-->
-<sect1 id="subsystem-persistence">
+<sect1
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xml:id="subsystem-persistence">
+
<title>Persistence</title>
<indexterm>
<primary>Persistence</primary>
@@ -33,52 +40,52 @@
<indexterm>
<primary>Saving/Loading</primary>
</indexterm>
-
+
<para>
-Purpose - To package and unpackage the
-persistence data from different subsystems to and from some storage medium.
-</para>
+ Purpose - To package and unpackage the
+ persistence data from different subsystems to and from some storage medium.
+ </para>
<para>
-The Persistence subsystem is located in
-<classname>org.argouml.persistence</classname>.
-</para>
-
+ The Persistence subsystem is located in
+ <classname>org.argouml.persistence</classname>.
+ </para>
+
<para>
-Currently the storage medium is
-a flat file (.uml - xml format) or
-a zipped file (.zargo - zip format)
-</para>
-
+ Currently the storage medium is
+ a flat file (.uml - xml format) or
+ a zipped file (.zargo - zip format)
+ </para>
+
<para>
-During save the persistence subsystem requests each subsystem for its
-persistence data and adds that data to output it is collating.
-</para>
-
+ During save the persistence subsystem requests each subsystem for its
+ persistence data and adds that data to output it is collating.
+ </para>
+
<para>
-During load the persistence subsystem unwraps the persistence data and passes
-these to the relevant subsystems for those subsystems to build themselves.
-</para>
-
+ During load the persistence subsystem unwraps the persistence data and passes
+ these to the relevant subsystems for those subsystems to build themselves.
+ </para>
+
<para>Edges and nodes are now saved and loaded in z order.
-Previously, edges were connected as they were loaded,
-and if the node had not already been read then this was a problem.
-We now load all nodes and edges (unconnected)
-and then connect the edges post load.
-<!-- See issue 3645 -->
-</para>
-
+ Previously, edges were connected as they were loaded,
+ and if the node had not already been read then this was a problem.
+ We now load all nodes and edges (unconnected)
+ and then connect the edges post load.
+ <!-- See issue 3645 -->
+ </para>
+
</sect1>
<!-- Local stuff for Emacs - please do not delete
-
-Local Variables:
-mode: xml
-sgml-doctype: "cookbook.xml"
-sgml-parent-document: ("cookbook.xml" "sect1" nil)
-sgml-validate-command: "nsgmls -wxml -sv ../docbook-setup/xml.dcl \
+
+ Local Variables:
+ mode: xml
+ sgml-doctype: "cookbook.xml"
+ sgml-parent-document: ("cookbook.xml" "sect1" nil)
+ sgml-validate-command: "nsgmls -wxml -sv ../docbook-setup/xml.dcl \
cookbook.xml"
-indent-tabs-mode: nil
-End:
-
--->
+ indent-tabs-mode: nil
+ End:
+
+-->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystempropertypanels.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystempropertypanels.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystempropertypanels.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystempropertypanels.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystempropertypanels.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystempropertypanels.xml 2008-01-15 19:22:21-0800
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
// Copyright (c) 1996-2006 The Regents of the University of California. All
@@ -25,922 +25,472 @@
// UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
-->
-<sect1 id="propertypanels">
- <title>Property panels</title>
- <indexterm>
- <primary>Property panels</primary>
- </indexterm>
+<section
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xml:id="propertypanels">
+
+ <title>Property panels</title>
+
+ <indexterm>
+ <primary>Property panels</primary>
+ </indexterm>
+
+ <para>Purpose - to provide a form view of the diagrams and objects in the model. The contents of the model is modifiable. </para>
+ <para>The Property panels will be located in <classname>org.argouml.uml.?</classname>. </para>
+ <para>The Property panels is a View subsystem. See <xref xlink:href="#view_control_subsystems"></xref>. </para>
+ <para>The PropPanels for the diagrams are in <classname>org.argouml.uml.diagram.ui</classname> and the property panels for UML objects are in <classname>org.argouml.uml.ui.<replaceable>UML path</replaceable></classname>. </para>
+
+ <section xml:id="addingapropertypanel">
+ <title>Adding the property panel</title>
+
+ <para>Property Panels for UML model elements are found as class <filename>PropPanel<replaceable>XXX</replaceable>.java</filename>, where <replaceable>XXX</replaceable> is the UML meta-class. They are in sub-packages of org.argouml.uml.ui corresponding to the <replaceable>XXX</replaceable> UML packages, which in turn correspond to their section in the chapter 2 of the UML 1.3 spec. </para>
+ <para>So for our example we create a new class <literal>PropPanelExtend</literal> in package <literal>org.argouml.uml.ui.behavior.use_cases</literal>. </para>
+ <para>Any associated classes that do not fall into the UML classification are provided in org.argouml.uml.ui. </para>
+ <para>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 <literal>lookupIcon()</literal> should be made (note that this is a utility method of the parent PropPanel class). For our example we had to add <literal>Extend.gif</literal>. </para>
+ <para xml:id="iconformat" > 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. </para>
+ <para>Finally the property panel must be added to the list of property panels in the <literal>run()</literal> method of the <literal>TabProps</literal> class, with a new call of <literal>panels.put()</literal>. If you don't do this, navigation listeners won't know about it!<!-- Huh? TODO: MVW: is this true?--> </para>
+ <para>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. </para>
+ <para>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(). </para>
+ <para>A button may be added to the toolbar with the utility method addButton(). </para>
+ <para>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. </para>
+ <para>The fields that you might add to a property panel include: </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Simple editable text. For example the Name field. Supported through the <literal>UMLTextField2</literal> class. </para>
+ </listitem>
+ <listitem>
+ <para>A drop down box (aka combobox) of options that can be selected. Supported by the <literal>UMLComboBox2</literal> class. Used e.g. for the type of a parameter. </para>
+ </listitem>
+ <listitem>
+ <para>A check box. This one does not use a seperate model class, thanks to the simplicity of the represented boolean value. Supported by the <literal>UMLCheckBox2</literal> class. Used e.g. for the concurrency checkbox on a composite state. </para>
+ </listitem>
+ <listitem>
+ <para>A radio button. These always come in a group. Supported by the <literal>UMLRadioButtonPanel</literal> class. Used e.g. for selecting the visibility on the properties panel of a class. </para>
+ </listitem>
+ <listitem>
+ <para>A list. Used e.g. for the Generalizations field on the proppanel of a class. The non-editable list is supported by the <literal>UMLList2</literal> class and its child <literal>UMLLinkedList</literal>. The latter also exists in the form of <literal>UMLMutableLinkedList</literal>, which allows adding, creation and deleting elements by popup menu. Used e.g. for the subvertex list for a composite state. </para>
+ <para>The list model is usually provided by a sub-class of <literal>UMLModelElementListModel2</literal>. There is a variant <literal>UMLModelElementOrderedListModel2</literal> intended for ordered links, which adds a few items to the pop-up menu, allowing sorting. This latter model is used e.g. for attributes of a class. </para>
+ </listitem>
+ <listitem>
+ <para>A drop down box of options that can be selected. This one exists in several versions, each having different possibilities. The most simple version is the <literal>UMLComboBox2</literal>. </para>
+ <para>The <literal>UMLEditableComboBox</literal> allows editing the selected item. </para>
+ <para>The <literal>UMLSearchableComboBox</literal> allows editing the selected item. See e.g. the Operation combobox on the callevent properties panel. </para>
+ <para>Then there is a variant with a seperate button for navigation to the property panel for the currently selected item. This is supported by the<literal>UMLComboBoxNavigator</literal> class. Used e.g. for the stereotype field. </para>
+ </listitem>
+ <listitem>
+ <para>An editable multiline text area. Supported by the <literal>UMLTextArea2</literal> class. Used e.g. for the text field of a UML Comment. </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Examples of these fields in more detail follow below.</para>
+
+ <section>
+ <title>Adding a simple list field</title>
+
+ <para>For example we need to add a field to the use case property panel for the extends relationships that derive from this use case. </para>
+ <para>This field consists of a label and a scrollable pane (<literal>JScrollPane</literal>) containing the list (<literal>JList</literal>), which may be empty, or contain extend relationships from this use case. </para>
+ <para>Rather than a straight <literal>JList</literal>, we use its child, <literal>UMLLinkedList</literal>, which adds several features to the standard JList specifically for ArgoUML's properties panels. </para>
+ <para>The constructor for <literal>UMLLinkedList</literal> requires two arguments, a list model and a flag to indicate whether to show an icon. </para>
+ <para>The list model should be a subclass of <literal>UMLModelElementListModel2</literal>, a subclass of the Swing <literal>DefaultListModel</literal> which implements <literal>AbstractListModel</literal>. The <literal>UMLModelElementListModel2</literal> implements two interfaces: one that listens to target changes, and one that listens to UML model changes. </para>
+
+ <section>
+ <title>The list model</title>
+
+ <para>In our example we create <literal>UMLUseCaseExtendListModel</literal>. 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. </para>
+ <para>A string naming an 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. </para>
+ <para>This list model should then be provided with a number of methods. The following are mandatory, since they are declared abstract in the parent. </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <literal>protected void buildModelList()</literal>
+ </term>
+ <listitem>
+ <para>(Re)Builds the list of elements. Called from targetChanged every time the target of the proppanel is changed. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>protected boolean isValidElement(Object/*MBase*/ o)</literal>
+ </term>
+ <listitem>
+ <para>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. </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <warning>
+ <para>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. </para>
+ </warning>
+
+ <para>The following are sometimes provided as an override of the parent, although for many uses the default is fine. </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <literal>public void open(int index)</literal>
+ </term>
+ <listitem>
+ <para>Perform the action associated with the <quote>open</quote> pop-up menu on the element at the given index. The default provided in the parent just navigates to that element. </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <literal>public boolean buildPopup(JPopupMenu popup, int index)</literal>
+ </term>
+ <listitem>
+ <para>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 <literal>UMLListMenuItem</literal>, which can record the index, rather than plain <literal>JListItem</literal>. 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. </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The following should be declared as needed to support particular pop-up functions. </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <literal>public void add(int index)</literal>
+ </term>
+ <listitem>
+ <para>Perform the actions associated with the <quote>add</quote> pop-up menu on the element at the given index. There is no default provided, so this must be given if the <quote>add</quote> operation is supported. The <literal>addAtUtil()</literal> method (see below) may prove helpful. </para>
+ <para>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. </para>
+ <warning>
+ <para>NOTE: The following was written regarding NSUML. It may be generally true for the Model subsystem, but this hasn't been verified. </para>
+ <para>NSUML routines generally set up the <quote>other</quote> 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). </para>
+ </warning>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>public void delete(int index)</literal>
+ </term>
+ <listitem>
+ <para>Perform the actions associated with the <quote>delete</quote> pop-up menu on the element at the given index. There is no default provided, so this must be given if the <quote>delete</quote> operation is supported. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>public void moveUp(int index)</literal>
+ </term>
+ <listitem>
+ <para>Perform the actions associated with the <quote>move up</quote> pop-up menu on the element at the given index. There is no default provided, so this must be given if the <quote>move up</quote> operation is supported. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>public void moveDown(int index)</literal>
+ </term>
+ <listitem>
+ <para>Perform the actions associated with the <quote>move down</quote> pop-up menu on the element at the given index. There is no default provided, so this must be given if the <quote>move down</quote> operation is supported. </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The following normally use the default method, but may be declared to override methods in the parent </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <literal>public void resetSize()</literal>
+ </term>
+ <listitem>
+ <para>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. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>public Object formatElement(MModelElement element)</literal>
+ </term>
+ <listitem>
+ <para>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. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>public void targetChanged()</literal>
+ </term>
+ <listitem>
+ <para>Called when the number of elements in the displayed list (including <quote>none</quote>) may have changed. Default invokes the necessary Swing operations to advise of a change in list size. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>public void targetReasserted()</literal>
+ </term>
+ <listitem>
+ <para>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. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>public void roleAdded(final MElementEvent event)</literal>
+ </term>
+ <listitem>
+ <!-- TODO: -->
+ <warning>
+ <para>This describes the old event interface. It needs to be updated.</para>
+ </warning>
+ <para>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. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>public void roleRemoved(final MElementEvent event)</literal>
+ </term>
+ <listitem>
+ <!-- TODO: -->
+ <warning>
+ <para>This describes the old event interface. It needs to be updated.</para>
+ </warning>
+ <para>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. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>public void recovered(final MElementEvent p1)</literal>
+ </term>
+ <term>
+ <literal>public void listRoleItemSet(final MElementEvent p1)</literal>
+ </term>
+ <term>
+ <literal>public void removed(final MElementEvent p1)</literal>
+ </term>
+ <term>
+ <literal>public void propertySet(final MElementEvent p1)</literal>
+ </term>
+ <listitem>
+ <!-- TODO: -->
+ <warning>
+ <para>This describes the old event interface. It needs to be updated.</para>
+ </warning>
+ <para>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. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>public void navigateTo(MModelElement modelElement)</literal>
+ </term>
+ <listitem>
+ <para>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). </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The following utility routines are also provided in the parent. They are not normally overridden. </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <literal>public int getUpperBound()</literal>
+ </term>
+ <listitem>
+ <para>get any upper bound (-1 is used if there is none). </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>public void setUpperBound(int newBound)</literal>
+ </term>
+ <listitem>
+ <para>set the upper bound (-1 is used if there is none). </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>public final String getProperty()</literal>
+ </term>
+ <listitem>
+ <para>returns the Model subsystem event name being monitored (null if all are being monitored). </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>protected final int getModelElementSize()</literal>
+ </term>
+ <listitem>
+ <para>returns the number of elements in the list. Invokes <literal>recalcModelElementSize()</literal> (see above) if necessary. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>final Object getTarget()</literal>
+ </term>
+ <listitem>
+ <para>returns the Model subsystem object associated with the container (some child of <literal>PropPanel</literal> usually) that holds this list model. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>final UMLUserInterfaceContainer getContainer()</literal>
+ </term>
+ <listitem>
+ <para>returns the the container (some child of <literal>PropPanel</literal> usually) that holds this list model. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>public int getSize()</literal>
+ </term>
+ <listitem>
+ <para>returns the size of the list. Including if there are no elements in the model, but the list has a default text when empty. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>public Object getElementAt(int index)</literal>
+ </term>
+ <listitem>
+ <para>returns the element at the given index in the list. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>static protected Collection addAtUtil(Collection oldCollection, MModelElement newItem, int index)</literal>
+ </term>
+ <listitem>
+ <para>helps in writing the <quote>add</quote> function. newItem is added at the specified index in the given oldCollection. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>static protected java.util.List moveUpUtil(Collection oldCollection, int index)</literal>
+ </term>
+ <listitem>
+ <para>helps in writing the <quote>move up</quote> function. Swaps the elements at offsets index and index-1. Not clear why it doesn't return a Collection. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>static protected java.util.List moveDownUtil(Collection oldCollection, int index)</literal>
+ </term>
+ <listitem>
+ <para>helps in writing the <quote>move down</quote> function. Swaps the elements at offsets index and index-1. Not clear why it doesn't return a Collection. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>static protected MModelElement elementAtUtil(Collection collection, int index, Class requiredClass)</literal>
+ </term>
+ <listitem>
+ <para>helps in writing the <literal>getElementAt()</literal>. Finds the element at a specific index. The last argument is ignored! </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ </section>
+
+ <section>
+ <title>Building the field</title>
+ <para>By convention the background of the list is set to the same as the background of the PropPanel and the foreground to Color.blue. </para>
+ <para>The list is then added to a <literal>JScrollPane</literal>. Although ArgoUML has historically not used scrollbars (<literal>JScrollPane.VERTICAL_SCROLLBAR_NEVER</literal> and <literal>JScrollPane.HORIZONTAL_SCROLLBAR_NEVER</literal>), it is more helpful to permit at least a vertical scrollbar where needed (<literal>JScrollPane.VERTICAL_SCROLLBAR_AS_NEEDED</literal> and <literal>JScrollPane.HORIZONTAL_SCROLLBAR_AS_NEEDED</literal>). </para>
+ <para>Finally the inherited method <literal>addCaption()</literal> is used to add the label for the field and <literal>addField()</literal> to add the associated scroll pane. </para>
+ <para>The second argument of each of these identifies the index of the caption/field pair in the vertical column of the grid for this property panel. The third argument identifies the column index. The final argument is a vertical weighting to expand the field if there is room in the property tab. This is usually set to the same non-zero value for all fields and corresponding captions that can have multiple entries, so they expand equally. If none of the fields should expand, the caption only of the last field in each column should be given a non-zero value. </para>
+ </section>
+
+ <section>
+ <title>Adding Property Tab Tool-bar Buttons</title>
+
+ <para>These are added by creating new instances of <literal>PropPanelButton</literal> (you don't need to assign them to anything - just creating will do). This has six arguments. </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The container, i.e this property panel (usually just use <literal>this</literal>). </para>
+ </listitem>
+ <listitem>
+ <para>The panel for the buttons. Use <literal>buttonPanel</literal> which is inherited from <literal>PropPanel</literal>. </para>
+ </listitem>
+ <listitem>
+ <para>The icon. Lots of these are already defined in <literal>PropPanel</literal>. </para>
+ </listitem>
+ <listitem>
+ <para>The advisory text for the button. Use <literal>localize(string)</literal> to ensure international portability. </para>
+ </listitem>
+ <listitem>
+ <para>The name of the method to invoke when this button is used. Some of the standard ones (e.g for navigation) are provided, but you will need to write any specials. </para>
+ </listitem>
+ <listitem>
+ <para>The name of the method (if any) to invoke to see if this button should be enabled. Use <literal>null</literal> if the button should always be enabled. </para>
+ </listitem>
+ </itemizedlist>
+ <para>In our example, the extend property panel has a <quote>add extension point</quote> button, with a method <literal>newExtensionPoint</literal> that we provide to create a new use case. </para>
+ </section>
+ <section>
+ <title>Support for stereotypes</title>
+
+ <para>The PropPanel should override the following (note the spelling of the method name). </para>
+ <para>
+ <literal>protected boolean isAcceptibleBaseMetaClass(String baseClass)</literal>. Returns <literal>true</literal> if the given base class is a class of the target in the <literal>PropPanel</literal>. </para>
+ <para>This is used to determine what stereotypes may be shown for this property panel. </para>
+ </section>
+
+ <section>
+ <title>Other sorts of fields</title>
+
+ <para>Another sort of field that may be useful is the ComboBox. This is useful to allow users to select from a pre-defined list of alongside a navigation arrow to go to the selected entry. </para>
+ <para>For example this is used to provide drop-down lists for the base and extension use cases of an Extend relationship in PropPanelExtend. </para>
+ <para>The model behind the drop down is created by using <literal>UMLComboBoxModel</literal>: <literal>UMLComboBoxModel(container, predicate, event, getter, setter, allowVoid, baseClass, useModel)</literal>. </para>
+ <para>The container is the <literal>PropPanel</literal> where we are setting up this ComboBox, the predicate is the name of a public method in that PropPanel that, given a model element, determines if it should be in the drop down, the event is the Model subsystem event name we are looking for (see earlier for the list), <literal>getter</literal> is the name of a public method in the PropPanel that yields the current entry in the combo Box (of type <literal>baseClass</literal>), <literal>setter</literal> (with a single argument of type <literal>baseClass</literal>) sets that entry, <literal>allowVoid</literal> if <literal>true</literal> will allow an empty entry for the box, <literal>baseClass</literal> is the UML metaclass from which all entries must descend, <literal>useModel</litera
l> is <literal>true</literal> to consider all the elements in the standard profile model for inclusion (so the Java types, standard stereotypes etc.). </para>
+ <para>For our <literal>PropPanelExtend</literal>, we provide a predicate routine the call for the <quote>base</quote> field is: </para>
+ <para><literal>UMLComboBoxModel(this, "isAcceptableUseCase", "base", "getBase", "setBase", true, MUseCase.class, true);</literal> </para>
+ <para>and we define the methods <literal>isAcceptableUseCase</literal>, <literal>getBase</literal> and <literal>setBase</literal> in <literal>PropPanelExtend</literal>. </para>
+ </section>
+
+ <section>
+ <title>How UMLTextField works</title>
+
+ <para>This information is provided by Jaap Branderhorst (September 2002). </para>
+ <para>
+ <classname>UMLTextField</classname> implements several kinds of event listeners: <itemizedlist>
+ <listitem>
+ <para>
+ <interfacename>MMelementListener</interfacename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <interfacename>DocumentListener</interfacename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <interfacename>FocusListener</interfacename>
+ </para>
+ </listitem>
+ </itemizedlist> Furthermore it is a <classname>UMLUserInterfaceComponent</classname>. </para>
+ <para>Since it is an <classname>UMLUserInterfaceComponent</classname> it must implement <methodname>targetChanged</methodname> and <methodname>targetReasserted</methodname>. <methodname>TargetChanged</methodname> is called every time the <classname>UMLTextField</classname> is selected. <methodname>targetReasserted</methodname> is of no interest for <classname>UMLTextField</classname>. It plays a role in keeping history but since history is not really implemented at the moment in ArgoUML it is of no interest. <methodname>targetChanged</methodname> does two things:
+ <itemizedlist>
+ <listitem>
+ <para>It calls the <methodname>targetChanged</methodname> method of the <classname>UMLTextProperty</classname> this <classname>UMLTextfield</classname> is showing. </para>
+ </listitem>
+ <listitem>
+ <para>It calls the <methodname>update</methodname> method. The <methodname>update</methodname> method is described further on. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>Besides <classname>UMLUserInterfaceComponent</classname> there are several other interfaces of interest. One of them is <interfacename>MMElementListener</interfacename>. </para>
+ <para>Every time a <interfacename>MModelElement</interfacename> is changed this will fire an <classname>MEvent</classname> to <classname>UMLChangeDispatch</classname>. <classname>UMLChangeDispatch</classname> will dispatch these events to all containers implementing <interfacename>UMLUserInterfaceComponents</interfacename> interested in this event, including <classname>UMLTextField</classname>. It will also dispatch the event to all children of an interested container implementing <interfacename>UMLUserInterfaceComponent</interfacename>. By this it is only necessary to register a <classname>PropPanel</classname> which holds an <classname>UMLTextField</classname> at <classname>UMLChangeDispatch</classname> to dispatch the event to the <classname>UMLTextField</classname> too. <interfacen
ame>MMelementListener</interfacename> knows several methods of which only one is of interest to <classname>UMLTextField</classname>s:
+ <itemizedlist>
+ <listitem>
+ <para>propertySet</para>
+ <para>Called every time a property in a <classname>MModelElement</classname> is set. This method calls <methodname>update</methodname> too if the <classname>UMLTextProperty</classname> really is affected. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>Furthermore <classname>UMLTextField</classname> implements <interfacename>DocumentListener</interfacename>. This is very typical for <classname>UMLTextField</classname>. At the moment it is not possible to change the style of the text in the <classname>UMLTextField</classname>. Therefore the method <methodname>changedUpdate</methodname> does not have a body. This method is only called when a <classname>DocumentEvent</classname> occurs that changes the style/layout of the text. The methods <methodname>insertUpdate</methodname> and <methodname>removeUpdate</methodname> are respectively called when a character is added to the document <classname>UMLTextField</classname> contains or removed. Since both methods are called when there is true user input and when the contents of the docu
ment are changed programmatically, the methods distinguish between them. <methodname>InsertUpdate</methodname> and <methodname>removeUpdate</methodname> are both handled via the protected method <methodname>handleEvent</methodname>. <methodname>HandleEvent</methodname> updates the property in <classname>UMLTextProperty</classname> if it is really changed. If the update comes via user input, it is checked if it is valid input. If it is not, a <classname>JOptionPane</classname> is shown with ' a warning and the change is not committed into the model. If it is not via user input, the input is not checked and the property is set. If the property is set, the update method is called. </para>
+ <para>The implementation of <interfacename>FocusListener</interfacename> makes sure that the checking of user input only happens when focus is lost. Otherwise, it would not be possible to enter 'intermediate' values that are not legal. For instance, say the value class is not legal. Without the implementation of <interfacename>FocusListener</interfacename>, it would not be possible to enter class diagram since handleEvent would pop-up a warning message box. </para>
+ <para>The method <methodname>update</methodname> updates both the actual <classname>JTextfield</classname> as the diagram as soon as some property is set. The updating of the diagram is done by calling the <methodname>damage</methodname> method of the figs that represent the property on the diagram. </para>
+ </section>
+ </section>
- <para>
-Purpose - to provide a form view of the diagrams and objects in the model.
-The contents of the model are modifiable from the panel.
-</para>
- <para>
-The Property panels will be located in
-<classname>org.argouml.uml.?</classname>.
-</para>
- <para>
-The Property panels is a View subsystem. See <xref linkend="view_control_subsystems"></xref>.
-</para>
- <para>
-The PropPanels for the diagrams are in
-<classname>org.argouml.uml.diagram.ui</classname>
-and the property panels for UML objects are in
-<classname>org.argouml.uml.ui.<replaceable>UML path</replaceable></classname>.
-</para>
-
- <sect2 id="addingapropertypanel">
- <title>Adding the property panel</title>
-
-
- <para>
-Property Panels for UML model elements are found as class
-<filename>PropPanel<replaceable>XXX</replaceable>.java</filename>,
-where <replaceable>XXX</replaceable> is the
-UML meta-class. They are in sub-packages of org.argouml.uml.ui
-corresponding to the UML package which contains the
-<replaceable>XXX</replaceable> metaclass in the UML specification.
-</para>
-
- <para>
-So for our example we create a new class
-<literal>PropPanelExtend</literal> in package
-<literal>org.argouml.uml.ui.behavior.use_cases</literal>.
-</para>
-
- <para>
-Any associated classes that do not fall into the UML classification
-are provided in org.argouml.uml.ui.
-</para>
-
- <para> 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 <literal>lookupIcon()</literal> should be
- made (note that this is a utility method
- of the parent PropPanel class). For our example we had to add
- <literal>Extend.gif</literal>. </para>
-
- <para id="iconformat">
- 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 <literal>Name.gif</literal>).
- This icon will automatically be used in the toolbar
- and in the Navigation pane.
- </para>
-
- <para> Finally the property panel must be added to the list of property
- panels in the <literal>run()</literal> method of the
- <literal>TabProps</literal> class, with a new call of
- <literal>panels.put()</literal>. If you don't do this, navigation
- listeners won't know about it!<!-- Huh? TODO: MVW: is this true?-->
- </para>
-
- <para> 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. </para>
-
- <para> 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(). </para>
-
- <para> A button may be added to the toolbar with the utility method
- addButton(). </para>
-
- <para> 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. </para>
-
- <para> The fields that you might add to a property panel include: </para>
-
- <itemizedlist>
- <listitem>
- <para> Simple editable text. For example the Name field. Supported
- through the <literal>UMLTextField2</literal> class. </para>
- </listitem>
-
- <listitem>
- <para> A drop down box (aka combobox) of options that can be selected.
- Supported by the <literal>UMLComboBox2</literal> class. Used
- e.g. for the type of a parameter.
-</para>
- </listitem>
-
- <listitem>
- <para> A check box. This one does not use a seperate model class,
- thanks to the simplicity of the represented boolean value. Supported
- by the <literal>UMLCheckBox2</literal> class. Used e.g. for the
- concurrency checkbox on a composite state.
-</para>
- </listitem>
-
- <listitem>
- <para> A radio button. These always come in a group. Supported by the
- <literal>UMLRadioButtonPanel</literal> class. Used e.g. for selecting
- the visibility on the properties panel of a class.
-</para>
- </listitem>
-
- <listitem>
- <para> A list. Used e.g. for the Generalizations field on
- the proppanel of a class. The non-editable list is supported by the
- <literal>UMLList2</literal> class and its child
- <literal>UMLLinkedList</literal>. The latter also exists in the form
- of <literal>UMLMutableLinkedList</literal>, which allows adding,
- creation and deleting elements by popup menu. Used e.g. for the
- subvertex list for a composite state.
- </para>
-
- <para>The list model is usually provided by a sub-class of
- <literal>UMLModelElementListModel2</literal>. There is a variant
- <literal>UMLModelElementOrderedListModel2</literal> intended for
- ordered links, which adds a few items to the pop-up menu, allowing
- sorting. This latter model is used e.g. for attributes of a class.
- </para>
- </listitem>
-
- <listitem>
- <para> A drop down box of options that can be selected. This one exists
- in several versions, each having different possibilities. The most
- simple version is the <literal>UMLComboBox2</literal>. </para>
- <para>The <literal>UMLEditableComboBox</literal> allows editing the
- selected item. </para>
- <para>The <literal>UMLSearchableComboBox</literal> allows editing the
- selected item. See e.g. the Operation combobox on the callevent
- properties panel. </para>
- <para> Then there is a variant with a seperate button for navigation to
- the property panel for the currently selected item. This is supported
- by the<literal>UMLComboBoxNavigator</literal> class. Used e.g. for
- the stereotype field.
- </para>
- </listitem>
-
- <listitem>
- <para> An editable multiline text area. Supported by the
- <literal>UMLTextArea2</literal> class. Used e.g. for the text field
- of a UML Comment.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>Examples of these fields in more detail follow below.</para>
-
- <sect3>
- <title>Adding a simple list field</title>
-
- <para> For example we need to add a field to the use case property panel
- for the extends relationships that derive from this use case. </para>
-
- <para> This field consists of a label and a scrollable pane
- (<literal>JScrollPane</literal>) containing the list
- (<literal>JList</literal>), which may be empty, or contain extend
- relationships from this use case. </para>
-
- <para> Rather than a straight <literal>JList</literal>, we use its child,
- <literal>UMLLinkedList</literal>, which adds several features to the
- standard JList specifically for ArgoUML's properties panels. </para>
-
- <para> The constructor for <literal>UMLLinkedList</literal> requires two
- arguments, a list model and a flag to indicate whether to show an icon.
- </para>
-
- <para> The list model should be a subclass of
- <literal>UMLModelElementListModel2</literal>, a subclass of the Swing
- <literal>DefaultListModel</literal> which implements
- <literal>AbstractListModel</literal>. The
- <literal>UMLModelElementListModel2</literal> implements two
- interfaces: one that listens to target changes, and one that listens to
- UML model changes.
- </para>
-
- <sect4>
- <title>The list model</title>
- <para> In our example we create
- <literal>UMLUseCaseExtendListModel</literal>. 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.
- </para>
- <para> 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.
- </para>
-
- <para> This list model should then be provided with a number of
- methods. The following are mandatory, since they are declared
- abstract in the parent.
- </para>
- <variablelist>
- <varlistentry>
- <term>
- <literal>protected void buildModelList()</literal>
- </term>
- <listitem>
- <para> (Re)Builds the list of elements. Called from targetChanged
- every time the target of the proppanel is changed. </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>protected boolean isValidElement(Object/*MBase*/
- o)</literal>
- </term>
- <listitem>
- <para> 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.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <warning>
- <para> 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. </para>
- </warning>
-
- <para> The following are sometimes provided as an override of the
- parent, although for many uses the default is fine. </para>
- <variablelist>
- <varlistentry>
- <term>
- <literal>public void open(int index)</literal>
- </term>
- <listitem>
- <para> Perform the action associated with the <quote>open</quote>
- pop-up menu on the element at the given index. The default
- provided in the parent just navigates to that element. </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>public boolean buildPopup(JPopupMenu popup, int
- index)</literal>
- </term>
- <listitem>
- <para> 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
- <literal>UMLListMenuItem</literal>, which can record the index,
- rather than plain <literal>JListItem</literal>. 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. </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para> The following should be declared as needed to support particular
- pop-up functions. </para>
- <variablelist>
- <varlistentry>
- <term>
- <literal>public void add(int index)</literal>
- </term>
- <listitem>
- <para> Perform the actions associated with the <quote>add</quote>
- pop-up menu on the element at the given index. There is no
- default provided, so this must be given if the
- <quote>add</quote> operation is supported. The
- <literal>addAtUtil()</literal> method (see below) may prove
- helpful. </para>
- <para> 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. </para>
- <warning>
- <para> NOTE: The following was written regarding NSUML.
- It may be generally true for the Model subsystem, but
- this hasn't been verified.
- </para>
-
- <para>NSUML routines generally set up the
- <quote>other</quote> 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). </para>
- </warning>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>public void delete(int index)</literal>
- </term>
- <listitem>
- <para> Perform the actions associated with the
- <quote>delete</quote> pop-up menu on the element at the given
- index. There is no default provided, so this must be given if
- the <quote>delete</quote> operation is supported. </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>public void moveUp(int index)</literal>
- </term>
- <listitem>
- <para> Perform the actions associated with the <quote>move
- up</quote> pop-up menu on the element at the given index. There
- is no default provided, so this must be given if the
- <quote>move up</quote> operation is supported. </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>public void moveDown(int index)</literal>
- </term>
- <listitem>
- <para> Perform the actions associated with the <quote>move
- down</quote> pop-up menu on the element at the given index.
- There is no default provided, so this must be given if the
- <quote>move down</quote> operation is supported. </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para> The following normally use the default method, but may be
- declared to override methods in the parent </para>
- <variablelist>
- <varlistentry>
- <term>
- <literal>public void resetSize()</literal>
- </term>
- <listitem>
- <para> 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. </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>public Object formatElement(MModelElement
- element)</literal>
- </term>
- <listitem>
- <para> 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. </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>public void targetChanged()</literal>
- </term>
- <listitem>
- <para> Called when the number of elements in the displayed list
- (including <quote>none</quote>) may have changed. Default
- invokes the necessary Swing operations to advise of a change in
- list size. </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>public void targetReasserted()</literal>
- </term>
- <listitem>
- <para> 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. </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>public void roleAdded(final MElementEvent
- event)</literal>
- </term>
- <listitem>
- <!-- TODO: --><warning>This describes the old event interface.
- It needs to be updated.</warning>
- <para> 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. </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>public void roleRemoved(final MElementEvent
- event)</literal>
- </term>
- <listitem>
- <!-- TODO: --><warning>This describes the old event interface.
- It needs to be updated.</warning>
- <para> 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. </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>public void recovered(final MElementEvent p1)</literal>
- </term>
- <term>
- <literal>public void listRoleItemSet(final MElementEvent
- p1)</literal>
- </term>
- <term>
- <literal>public void removed(final MElementEvent p1)</literal>
- </term>
- <term>
- <literal>public void propertySet(final MElementEvent p1)</literal>
- </term>
- <listitem>
- <!-- TODO: --><warning>This describes the old event interface.
- It needs to be updated.</warning>
- <para> 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.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>public void navigateTo(MModelElement
- modelElement)</literal>
- </term>
- <listitem>
- <para> 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). </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para> The following utility routines are also provided in the parent.
- They are not normally overridden. </para>
- <variablelist>
- <varlistentry>
- <term>
- <literal>public int getUpperBound()</literal>
- </term>
- <listitem>
- <para> get any upper bound (-1 is used if there is none). </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>public void setUpperBound(int newBound)</literal>
- </term>
- <listitem>
- <para> set the upper bound (-1 is used if there is none). </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>public final String getProperty()</literal>
- </term>
- <listitem>
- <para> returns the Model subsystem event name being monitored
- (null if all are being monitored). </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>protected final int getModelElementSize()</literal>
- </term>
- <listitem>
- <para> returns the number of elements in the list. Invokes
- <literal>recalcModelElementSize()</literal> (see above) if
- necessary. </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>final Object getTarget()</literal>
- </term>
- <listitem>
- <para> returns the Model subsystem object associated with the container
- (some child of <literal>PropPanel</literal> usually) that holds
- this list model. </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>final UMLUserInterfaceContainer getContainer()</literal>
- </term>
- <listitem>
- <para> returns the the container (some child of
- <literal>PropPanel</literal> usually) that holds this list
- model. </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>public int getSize()</literal>
- </term>
- <listitem>
- <para> returns the size of the list. Including if there are no
- elements in the model, but the list has a default text when
- empty. </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>public Object getElementAt(int index)</literal>
- </term>
- <listitem>
- <para> returns the element at the given index in the list. </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>static protected Collection addAtUtil(Collection
- oldCollection, MModelElement newItem, int index)</literal>
- </term>
- <listitem>
- <para> helps in writing the <quote>add</quote> function. newItem
- is added at the specified index in the given oldCollection.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>static protected java.util.List moveUpUtil(Collection
- oldCollection, int index)</literal>
- </term>
- <listitem>
- <para> helps in writing the <quote>move up</quote> function.
- Swaps the elements at offsets index and index-1. Not clear why
- it doesn't return a Collection. </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>static protected java.util.List moveDownUtil(Collection
- oldCollection, int index)</literal>
- </term>
- <listitem>
- <para> helps in writing the <quote>move down</quote> function.
- Swaps the elements at offsets index and index-1. Not clear why
- it doesn't return a Collection. </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>static protected MModelElement elementAtUtil(Collection
- collection, int index, Class requiredClass)</literal>
- </term>
- <listitem>
- <para> helps in writing the <literal>getElementAt()</literal>.
- Finds the element at a specific index. The last argument is
- ignored! </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect4>
- </sect3>
-
- <sect3>
- <title>Building the field</title>
-
- <para>
-By convention the background of the list is set to the same as the
-background of the PropPanel and the foreground to Color.blue.
-</para>
-
- <para>
-The list is then added to a <literal>JScrollPane</literal>.
-Although ArgoUML has historically not used scrollbars
-(<literal>JScrollPane.VERTICAL_SCROLLBAR_NEVER</literal> and
-<literal>JScrollPane.HORIZONTAL_SCROLLBAR_NEVER</literal>), it is more
-helpful to permit at least a vertical scrollbar where needed
-(<literal>JScrollPane.VERTICAL_SCROLLBAR_AS_NEEDED</literal> and
-<literal>JScrollPane.HORIZONTAL_SCROLLBAR_AS_NEEDED</literal>).
-</para>
-
- <para>
-Finally the inherited method <literal>addCaption()</literal> is used
-to add the label for the field and <literal>addField()</literal> to
-add the associated scroll pane.
-</para>
-
- <para>
-The second argument of each of these identifies the index of the
-caption/field pair in the vertical column of the grid for this
-property panel. The third argument identifies the column index. The
-final argument is a vertical weighting to expand the field if there is
-room in the property tab. This is usually set to the same non-zero
-value for all fields and corresponding captions that can have multiple
-entries, so they expand equally. If none of the fields should expand,
-the caption only of the last field in each column should be given a
-non-zero value.
-</para>
-
- </sect3>
-
- <sect3>
- <title>Adding Property Tab Tool-bar Buttons</title>
-
- <para>
-These are added by creating new instances of
-<literal>PropPanelButton</literal> (you don't need to assign them to
-anything - just creating will do).
-This has six arguments.
-</para>
-
- <itemizedlist>
- <listitem>
- <para>
-The container, i.e this property panel (usually just use
-<literal>this</literal>).
-</para>
- </listitem>
-
- <listitem>
- <para>
-The panel for the buttons.
-Use <literal>buttonPanel</literal> which is inherited from
-<literal>PropPanel</literal>.
-</para>
- </listitem>
-
- <listitem>
- <para>
-The icon.
-Lots of these are already defined in <literal>PropPanel</literal>.
-</para>
- </listitem>
-
- <listitem>
- <para>
-The advisory text for the button.
-Use <literal>localize(string)</literal> to ensure international
-portability.
-</para>
- </listitem>
-
- <listitem>
- <para>
-The name of the method to invoke when this button is used.
-Some of the standard ones (e.g for navigation) are provided, but you
-will need to write any specials.
-</para>
- </listitem>
-
- <listitem>
- <para>
-The name of the method (if any) to invoke to see if this button should
-be enabled.
-Use <literal>null</literal> if the button should always be
-enabled.
-</para>
- </listitem>
- </itemizedlist>
-
- <para>
-In our example, the extend property panel has a <quote>add extension
-point</quote> button, with a method
-<literal>newExtensionPoint</literal> that we provide to create a new
-use case.
-</para>
- </sect3>
-
- <sect3>
- <title>Support for stereotypes</title>
-
- <para>
-The PropPanel should override the following (note the spelling of the
-method name).
-</para>
-
- <para>
-<literal>protected boolean
-isAcceptibleBaseMetaClass(String baseClass)</literal>.
-Returns <literal>true</literal> if the given base class is a class of
-the target in the <literal>PropPanel</literal>.
-</para>
-
- <para>
-This is used to determine what stereotypes may be shown for this
-property panel.
-</para>
- </sect3>
-
- <sect3>
- <title>Other sorts of fields</title>
-
- <para>
-Another sort of field that may be useful is the ComboBox.
-This is useful to allow users to select from a pre-defined list of
-alongside a navigation arrow to go to the selected entry.
-</para>
-
- <para>
-For example this is used to provide drop-down lists for the base and
-extension use cases of an Extend relationship in
-PropPanelExtend.
-</para>
-
- <para>
-The model behind the drop down is created by using
-<literal>UMLComboBoxModel</literal>:
-<literal>UMLComboBoxModel(container, predicate, event, getter, setter,
-allowVoid, baseClass, useModel)</literal>.
-</para>
-
- <para>
-The container is the <literal>PropPanel</literal> where we are setting
-up this ComboBox, the predicate is the name of a public method in that
-PropPanel that, given a model element, determines if it should be in
-the drop down, the event is the Model subsystem event
-name we are looking for (see earlier for the list),
-<literal>getter</literal> is the name of a public method in the
-PropPanel that yields the current entry in the combo Box (of type
-<literal>baseClass</literal>), <literal>setter</literal> (with a
-single argument of type <literal>baseClass</literal>) sets that entry,
-<literal>allowVoid</literal> if <literal>true</literal> will allow an
-empty entry for the box, <literal>baseClass</literal> is the UML
-metaclass from which all entries must descend,
-<literal>useModel</literal> is <literal>true</literal> to consider all
-the elements in the standard profile model for inclusion (so the Java
-types, standard stereotypes etc.).
-</para>
-
- <para>
-For our <literal>PropPanelExtend</literal>, we provide a predicate
-routine the call for the <quote>base</quote> field is:
-</para>
-
- <para>
-<literal>UMLComboBoxModel(this, "isAcceptableUseCase", "base",
-"getBase", "setBase", true, MUseCase.class, true);</literal>
-</para>
-
- <para>
-and we define the methods <literal>isAcceptableUseCase</literal>,
-<literal>getBase</literal> and <literal>setBase</literal> in
-<literal>PropPanelExtend</literal>.
-</para>
- </sect3>
-
- <sect3>
- <title>How UMLTextField works</title>
- <para>
-This information is provided by Jaap Branderhorst (September 2002).
-</para>
-
- <para>
-<classname>UMLTextField</classname> implements several kinds of
-event listeners:
-<itemizedlist>
- <listitem>
- <para><interfacename>MMelementListener</interfacename></para>
- </listitem>
- <listitem>
- <para><interfacename>DocumentListener</interfacename></para>
- </listitem>
- <listitem>
- <para><interfacename>FocusListener</interfacename></para>
- </listitem>
- </itemizedlist>
-Furthermore it is a <classname>UMLUserInterfaceComponent</classname>.
-</para>
-
- <para>
-Since it is an <classname>UMLUserInterfaceComponent</classname>
-it must implement <methodname>targetChanged</methodname> and
-<methodname>targetReasserted</methodname>.
-<methodname>TargetChanged</methodname> is called every time the
-<classname>UMLTextField</classname> is selected.
-<methodname>targetReasserted</methodname> is of no interest for
-<classname>UMLTextField</classname>.
-It plays a role in keeping history but since history
-is not really implemented at the moment in ArgoUML
-it is of no interest.
-<methodname>targetChanged</methodname> does two things:
-<itemizedlist>
- <listitem>
- <para>
-It calls the <methodname>targetChanged</methodname> method
-of the <classname>UMLTextProperty</classname> this
-<classname>UMLTextfield</classname> is showing.
-</para>
- </listitem>
- <listitem>
- <para>
-It calls the <methodname>update</methodname> method.
-The <methodname>update</methodname> method is described further on.
-</para>
- </listitem>
- </itemizedlist>
-</para>
-
- <para>
-Besides <classname>UMLUserInterfaceComponent</classname>
-there are several other interfaces of interest.
-One of them is <interfacename>MMElementListener</interfacename>.
-</para>
-
- <para>
-Every time a <interfacename>MModelElement</interfacename> is
-changed this will fire an <classname>MEvent</classname>
-to <classname>UMLChangeDispatch</classname>.
-<classname>UMLChangeDispatch</classname> will dispatch
-these events to all containers implementing
-<interfacename>UMLUserInterfaceComponents</interfacename>
-interested in this event, including <classname>UMLTextField</classname>.
-It will also dispatch the event to all children of an interested container
-implementing
-<interfacename>UMLUserInterfaceComponent</interfacename>.
-By this it is only necessary to register a
-<classname>PropPanel</classname> which holds an
-<classname>UMLTextField</classname> at
-<classname>UMLChangeDispatch</classname> to
-dispatch the event to the <classname>UMLTextField</classname> too.
-<interfacename>MMelementListener</interfacename>
-knows several methods of which only one is of interest to
-<classname>UMLTextField</classname>s:
-<itemizedlist>
- <listitem>
- <para>propertySet</para>
- <para>
-Called every time a property in a
-<classname>MModelElement</classname> is set.
-This method calls
-<methodname>update</methodname> too if the
-<classname>UMLTextProperty</classname> really is affected.
-</para>
- </listitem>
- </itemizedlist>
-</para>
-
- <para>
-Furthermore <classname>UMLTextField</classname> implements
-<interfacename>DocumentListener</interfacename>.
-This is very typical for <classname>UMLTextField</classname>.
-At the moment it is not possible to change the style of
-the text in the <classname>UMLTextField</classname>.
-Therefore the method <methodname>changedUpdate</methodname> does not
-have a body.
-This method is only called when a <classname>DocumentEvent</classname>
-occurs that changes the style/layout of the text.
-The methods <methodname>insertUpdate</methodname>
-and <methodname>removeUpdate</methodname> are respectively called when a
-character is added to the document
-<classname>UMLTextField</classname> contains or removed.
-Since both methods are called when there is true user input
-and when the contents of the document are changed programmatically,
-the methods distinguish between them.
-<methodname>InsertUpdate</methodname> and
-<methodname>removeUpdate</methodname>
-are both handled via the protected method
-<methodname>handleEvent</methodname>.
-<methodname>HandleEvent</methodname> updates the property in
-<classname>UMLTextProperty</classname> if it is really changed.
-If the update comes via user input, it is checked if it is valid input.
-If it is not, a <classname>JOptionPane</classname> is shown with
-a warning and the change is not committed into the model.
-If it is not via user input, the input is not checked and the
-property is set. If the property is set, the update method is called.
-</para>
-
- <para>
-The implementation of <interfacename>FocusListener</interfacename>
-makes sure that the checking of user input only happens when focus is lost.
-Otherwise, it would not be possible to enter 'intermediate' values
-that are not legal.
-For instance, say the value class is not legal.
-Without the implementation of <interfacename>FocusListener</interfacename>,
-it would not be possible to enter class diagram since
-handleEvent would pop-up a warning message box.
-</para>
-
- <para>
-The method <methodname>update</methodname> updates both the actual
-<classname>JTextfield</classname> as the diagram as soon
-as some property is set.
-The updating of the diagram is done by calling the
-<methodname>damage</methodname> method of the figs that
-represent the property on the diagram.
-</para>
- </sect3>
- </sect2>
-
-</sect1>
+</section>
<!-- Local stuff for Emacs - please do not delete
@@ -953,4 +503,4 @@
indent-tabs-mode: nil
End:
--->
+-->
\ No newline at end of file
Modified: branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystems.xml
Url: http://argouml.tigris.org/source/browse/argouml/branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystems.xml?view=diff&rev=14048&p1=branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystems.xml&p2=branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystems.xml&r1=14047&r2=14048
==============================================================================
--- branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystems.xml (original)
+++ branches/work_docbook5_zearin/branch1/documentation/cookbook/subsystems.xml 2008-01-15 19:22:21-0800
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!-- $Id$ -->
<!--
// Copyright (c) 1996-2007 The Regents of the University of California. All
@@ -25,42 +25,50 @@
// UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
-->
-<chapter id="subsystems">
- <title>ArgoUML Design, The Big Picture</title>
- <indexterm>
+<chapter
+ xmlns="http://docbook.org/ns/docbook"
+ version="5.0"
+ xml:lang="en"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xml:id="subsystems">
+
+ <title>ArgoUML Design, The Big Picture</title>
+
+ <indexterm>
<primary>ArgoUML Design</primary> </indexterm>
- <para> Currently this is more of a base for discussion and ambition but hopefully
+ <para>Currently this is more of a base for discussion and ambition but hopefully
this will mature and prove useful. </para>
<indexterm>
<primary>subsystem</primary> </indexterm> <indexterm>
<primary>component</primary> </indexterm>
- <para> The code within ArgoUML is separated into subsystems that each have a few
+ <para>The code within ArgoUML is separated in subsystems that each have a few
responsibilities. </para>
- <para> In Issuezilla each subsystem has its issues sorted in a subcomponent with
+ <para>In Issuezilla each subsystem has its issues sorted in a subcomponent with
the same name as the subsystem. Furthermore the Diagrams subsystem has a set of
subcomponents for issues connected to the specific diagrams. </para>
- <para> This chapter gives an overall picture with a list of subsystems, their
+ <para>This chapter gives an overall picture with a list of subsystems, their
dependencies, and their main responsibility. <xref
linkend="inside_subsystems"></xref> explains each subsystem in
detail. </para>
- <para> The subsystems are organized in layers. The purpose of the layers is to
+ <para>The subsystems are organized in layers. The purpose of the layers is to
make it easy to see in what direction the dependencies are and thus allow us to
know what dependencies are to be removed in the cases where we have circular
- dependencies. This will also allow us to know which other subsystems are
+ dependencies. This will also allow us to know which other subsystems that are
involved when testing a subsystem. </para>
- <sect1 id="subsystems_definition">
+ <section xml:id="subsystems_definition">
<title>Definition of subsystem</title>
- <para> All ArgoUML code is organized in subsystems. </para>
- <para> Each subsystem has:
+ <para>All ArgoUML code is organized in subsystems. </para>
+ <para>Each subsystem has:
<itemizedlist>
<listitem>
<para>A name</para>
</listitem>
<listitem>
<para>A single directory/Java package where it resides</para>
- <para> Subparts of the subsystem can reside in subdirectories of this
+ <para>Subparts of the subsystem can reside in subdirectories of this
directory. Auxiliary parts, implemented in other products, of the
subsystems can reside somewhere else. Notice that each other
product used by ArgoUML is, in the design, located within one of the
@@ -68,14 +76,14 @@
change of choice of such a dependency is an internal matter for the
subsystem and should ideally not affect any other subsystem.
</para>
- <para> All public and protected methods of all public and protected
+ <para>All public and protected methods of all public and protected
classes in this directory constitute the API of that subsystem.
</para>
</listitem>
<listitem>
- <para> A section in the chapter <xref linkend="inside_subsystems"/>
+ <para>A section in the chapter <xref xlink:href="inside_subsystems"/>
. </para>
- <para> The section shall for each subsystem contain the
+ <para>The section shall for each subsystem contain the
responsibilities, the package name, the API, the Facade (if any),
all the plug-in interfaces (if any).
This shall be in the first part of the section i.e. not in a subsection.
@@ -84,32 +92,29 @@
</para>
</listitem>
</itemizedlist> </para>
- <para> Each subsystem can have:
+ <para>Each subsystem can have:
<itemizedlist>
<listitem>
- <para> a Facade class </para>
- <para>
-The facade can be used by all other subsystems when using the subsystem.
- </para>
- <para>
-The Facade class is called
-<classname><replaceable>SubsystemName</replaceable>Facade</classname>
-and is located in the subsystem package.
-How it is used is primarily documented in the class file itself (as javadoc)
-but the more complex picture is documented in the Cookbook (in
-<xref linkend="inside_subsystems"></xref>).
- </para>
+ <para>a Facade class </para>
+ <para>The facade can be used by all other subsystems when using the
+ subsystem. </para>
+ <para>The Facade class is called
+ <classname><replaceable>SubsystemName</replaceable>
+ Facade</classname> and is located in the subsystem package. How it
+ is used is primarily documented in the class file itself (as javadoc)
+ but the more complex picture is documented in the Cookbook (in <xref
+ linkend="inside_subsystems"></xref>). </para>
</listitem>
<listitem>
- <para> Plug-in interfaces. </para>
- <para> These are Facade objects where modules or plug-ins can connect
+ <para>Plug-in interfaces. </para>
+ <para>These are Facade objects where modules or plug-ins can connect
themselves to modify or augment the behavior of that subsystem.
</para>
</listitem>
<listitem>
- <para> The plug-in interfaces are also all located in the subsystem
+ <para>The plug-in interfaces are also all located in the subsystem
package and called
<classname><replaceable>SubsystemName</replaceable>
Plugin<replaceable>PluginType</replaceable></classname>.
@@ -121,12 +126,12 @@
</listitem>
<listitem>
- <para>
-If the subsystem uses a callback-technique the callback is always made to
-an interface defined by the subsystem.
-The interface is also in the subsystem package and it is called
-<classname><replaceable>SubsystemName</replaceable><replaceable>PluginType</replaceable>Interface</classname>.
-Example: <classname>ModelDiagramInterface</classname>,
+ <para>If the subsystem uses a callback-technique the callback is
+ always made to an interface defined by the subsystem. The interface
+ is also in the subsystem package and it is called
+ <classname><replaceable>SubsystemName</replaceable>
+ <replaceable>PluginType</replaceable>Interface</classname>
+ . Example: <classname>ModelDiagramInterface</classname>,
<classname>ModelTypeInterface</classname>. </para>
<para>
<mediaobject>
@@ -138,80 +143,76 @@
</mediaobject> </para>
</listitem>
</itemizedlist> </para>
- </sect1>
+ </section>
- <sect1 id="subsystems_relationships">
+ <section xml:id="subsystems_relationships">
<title>Relationship of the subsystems</title>
- <para> Each subsystem that is used by other subsystems provide two ways for
+ <para>Each subsystem that is used by other subsystems provide two ways for
other subsystems to use them:
<itemizedlist>
<listitem>
- <para> The Facade class </para>
- <para> The use of Facade class is not wide spread in ArgoUML. This is
+ <para>The Facade class </para>
+ <para>The use of Facade class is not wide spread in ArgoUML. This is
because ArgoUML is traditionally built as a whole and no subsystems
were clearly defined. </para>
- <para>
-A Facade class provides the most common functions other subsystems want to do
-when using that subsystem to reduce the need of having to use anything else
-but the Facade class.
-The Facade class should be very much more stable than the subsystem itself.
-Methods in the Facade should change very slowly and only be removed after
-several months (and one stable release) of deprecation.
- </para>
- <para> The Facade class is documented in the class file itself (as
+ <para>A Facade class provides the most common functions other
+ subsystems want to do when using that subsystems to reduce the need of
+ having to use anything else but the Facade class. The Facade class
+ should be very much more stable than the subsystem itself. Methods in
+ the Facade should change really slowly and only be removed after
+ several months (and one stable release) of deprecation. </para>
+ <para>The Facade class is documented in the class file itself (as
javadoc) and the more complex picture (if needed) is documented in
- the Cookbook (in <xref linkend="inside_subsystems"></xref>).
+ the Cookbook (in <xref xlink:href="inside_subsystems"></xref>).
</para>
</listitem>
<listitem>
- <para> An API with calls to public or protected methods. </para>
- <para> Traditionally, the subsystems in ArgoUML communicate through
+ <para>An API with calls to public or protected methods. </para>
+ <para>Traditionally, the subsystems in ArgoUML communicate through
public methods and public variables and the subsystems, as defined
by the responsibilities, are spread over several packages setting
aside the Java visibility rules. For this reason it is not well-known
or documented what public methods form part of a subsystem's API and
what public methods are internal to a subsystem. For this reason,
always exercise extreme caution when changing the signature of a
- public method. (See <xref linkend="groundrules"></xref>.)
+ public method. (See <xref xlink:href="groundrules"></xref>.)
</para>
- <para> In order to improve things, make it very clear when encountering
+ <para>In order to improve things, make it very clear when encountering
and understanding the purpose of a public method or class, if it is
part of the subsystem's API or not (by improving the javadoc for that
method or class). </para>
- <para> Try to help in moving the public API methods and classes from
+ <para>Try to help in moving the public API methods and classes from
wherever, to the subsystem's directory/package using the proper
deprecation procedure. </para>
- <para> In order not to worsen things, always add new API classes and
+ <para>In order not to worsen things, always add new API classes and
methods in the subsystem's directory/package. </para>
- <para> This way of communicating is still to be used when it is not
+ <para>This way of communicating is still to be used when it is not
convenient to use the Facade for a specific use of that subsystem.
</para>
</listitem>
</itemizedlist> Notice that the Facade is normally a part of the API or a
simplified version of the API. </para>
- <para> For each subsystem X in ArgoUML that uses the subsystem Y, the designer
+ <para>For each subsystem X in ArgoUML that uses the subsystem Y, the designer
of the subsystem X must decide if he wants to use the API of Y when using the
subsystem Y (putting a set of import org.argouml.Y.internals.blabla.*;
statements in each file of subsystem X that uses subsystem Y) or use the
Facade class of subsystem Y (putting only one import
org.argouml.Y.YFacade; in each file in the subsystem X that uses subsystem
Y). </para>
- <para>
-The API solution makes subsystem X depend on subsystem Y
-meaning that when we change the API of the subsystem Y we must also change
-subsystem X.
-The facade calls solution doesn't make the subsystem X
-depend on the API of subsystem Y but just the Facade of subsystem Y.
+ <para>The API solution makes the subsystem X depending on the subsystem Y
+ meaning that when we change the API of the subsystem Y we must also change
+ subsystem X. The facade calls solution doesn't make the subsystem X
+ depending on the API of subsystem Y but just the Facade of subsystem Y.
</para>
- <para> The choice between the usage of the API or the Facade shall be stated in
+ <para>The choice between the usage of the API or the Facade shall be stated in
the Cookbook's description of subsystem X in the list of used subsystems.
</para>
- </sect1>
+ </section>
- <sect1 id="external_subsystems">
+ <section xml:id="external_subsystems">
<title>External subsystems</title>
- <para> These subsystems are in fact imported libraries
+ <para>These subsystems are in fact imported libraries
and are not developed as part of ArgoUML.
</para>
<para>There is a very simple dependency structure:
@@ -220,13 +221,13 @@
<para>
All these subsystems are started and initiated (if needed)
from the Application subsystem,
- see <xref linkend="application"></xref>.
+ see <xref xlink:href="application"></xref>.
</para>
<itemizedlist>
<listitem>
- <para>Logging - see <xref linkend="logging"></xref>.
+ <para>Logging - see <xref xlink:href="logging"></xref>.
Location: <classname>org.apache.log4j</classname>
</para>
</listitem>
@@ -248,7 +249,7 @@
<listitem>
<para>OCL - see
- <xref linkend="ocl"></xref>.
+ <xref xlink:href="ocl"></xref>.
Location: <classname>tudresden.ocl</classname>
</para>
</listitem>
@@ -283,16 +284,16 @@
</imageobject>
</mediaobject> </para>
- </sect1>
+ </section>
- <sect1 id="infrastructure_subsystems">
+ <section xml:id="infrastructure_subsystems">
<title>Low-level subsystems</title>
- <para> These subsystems of ArgoUML
+ <para>These subsystems of ArgoUML
are infrastructure subsystems that just are there
for every other subsystem to use
- but they are not using any other part of ArgoUML.
</para>
- <para> Low-level subsystems have a simple dependency structure:
+ <para>Low-level subsystems have a simple dependency structure:
All other ArgoUML packages may depend on them,
but there are no dependencies "upwards",
nor between them.
@@ -304,37 +305,37 @@
<para>
All these subsystems are started and initiated (if needed) from the
Application subsystem,
- see <xref linkend="application"></xref>.
+ see <xref xlink:href="application"></xref>.
</para>
<itemizedlist>
<listitem>
<para>Internationalization -
-see <xref linkend="internationalization"></xref>.
+see <xref xlink:href="internationalization"></xref>.
</para>
</listitem>
<listitem>
<para>TaskManagement -
- see <xref linkend="taskmgmt"></xref>.
+ see <xref xlink:href="taskmgmt"></xref>.
</para>
</listitem>
<listitem>
<para>Configuration -
- see <xref linkend="configuration"></xref>.
+ see <xref xlink:href="configuration"></xref>.
</para>
</listitem>
<listitem>
<para>Swing extensions
- <!-- - see <xref linkend="swingext"></xref> -->.
+ <!-- - see <xref xlink:href="swingext"></xref> -->.
</para>
</listitem>
<listitem>
<para>
- The Model - See <xref linkend="model" />.
+ The Model - See <xref xlink:href="model" />.
</para>
</listitem>
@@ -346,9 +347,9 @@
</imageobject>
</mediaobject> </para>
- </sect1>
+ </section>
- <sect1 id="view_control_subsystems">
+ <section xml:id="view_control_subsystems">
<title>View and Control subsystems</title>
<para>
These subsystems rely on the information in the model subsystems
@@ -358,56 +359,56 @@
<para>
All these subsystems are all started and initiated
from the Application subsystem,
- see <xref linkend="application"></xref>.
+ see <xref xlink:href="application"></xref>.
</para>
<para>
<itemizedlist>
<listitem>
<para>Diagrams -
-see <xref linkend="diagrams"></xref>.
+see <xref xlink:href="diagrams"></xref>.
</para>
</listitem>
<listitem>
<para>GUI -
- see <xref linkend="guiframework"></xref>.
+ see <xref xlink:href="guiframework"></xref>.
</para>
</listitem>
<listitem>
<para>Property panels -
-see <xref linkend="propertypanels"></xref>.
+see <xref xlink:href="propertypanels"></xref>.
</para>
</listitem>
<listitem>
<para>Explorer -
-see <xref linkend="explorer"></xref>.
+see <xref xlink:href="explorer"></xref>.
</para>
</listitem>
<listitem>
<para>Notation -
-see <xref linkend="notation"></xref>.
+see <xref xlink:href="notation"></xref>.
</para>
</listitem>
<listitem>
<para>Code Generation -
-see <xref linkend="codegeneration"></xref>.
+see <xref xlink:href="codegeneration"></xref>.
</para>
</listitem>
<listitem>
<para>Reverse Engineering -
-see <xref linkend="reverseengineering"></xref>.
+see <xref xlink:href="reverseengineering"></xref>.
</para>
</listitem>
<listitem>
<para>Module loader -
-see <xref linkend="moduleloader"></xref>.
+see <xref xlink:href="moduleloader"></xref>.
</para>
</listitem>
</itemizedlist>
@@ -419,9 +420,9 @@
</imageobject>
</mediaobject> </para>
- </sect1>
+ </section>
- <sect1 id="top_level_subsystem">
+ <section xml:id="top_level_subsystem">
<title>Top Level subsystem</title>
<para>
A top level subsystem is the subsystem that contains the Main.main(),
@@ -435,7 +436,7 @@
<itemizedlist>
<listitem>
<para>
- Application - see <xref linkend="application"></xref>.
+ Application - see <xref xlink:href="application"></xref>.
</para>
</listitem>
</itemizedlist>
@@ -449,41 +450,37 @@
</imageobject>
</mediaobject>
</para>
- </sect1>
+ </section>
- <sect1 id="loadable_subsystems">
+ <section xml:id="loadable_subsystems">
<title>Loadable subsystems</title>
- <para>
-These subsystems should be connected only through the interfaces
-provided by other subsystems.
-This means that they can be individually enabled and disabled using
-the module loader.
-</para>
+
+ <para>These subsystems should be connected only through the interfaces provided by other subsystems. This means that they can be individually enabled and disabled using the module loader. </para>
<para>
<itemizedlist>
<listitem>
<para>Java Code generation, Reverse engineering -
-see <xref linkend="java"></xref>.
+see <xref xlink:href="java"></xref>.
</para>
</listitem>
<listitem>
<para>Other languages - Code generation, Reverse engineering -
-see <xref linkend="otherlanguages"></xref>.
+see <xref xlink:href="otherlanguages"></xref>.
</para>
</listitem>
<listitem>
<para>Critics and checklists -
-see <xref linkend="critics"></xref>.
+see <xref xlink:href="critics"></xref>.
</para>
</listitem>
<listitem>
<para>OCL -
-see <xref linkend="ocl"></xref>.
+see <xref xlink:href="ocl"></xref>.
</para>
</listitem>
@@ -495,7 +492,7 @@
<imagedata fileref="images/cookbook/Layer3.gif" format="GIF"/>
</imageobject>
</mediaobject> </para>
- </sect1>
+ </section>
</chapter>