Home

Cookbook for Developers of ArgoUML

1. CrConside Singleton C rConside rSingletong Resdi s String void predicate 2 dm Object dsgr Designer boolean from org argouml cognitice critics CrUML from org argouml uml cognitice critics CAREFUL attribute s and methods missing from org argouml patte rn cognitive critics 45 Inside the subsystems Critics are currently located in org argouml cognitive critics These are basic critics which are very general in nature For example ArgoUML keeps nagging when Model elements overlap which makes the Diagram hard to read This package also contains the base classes for the handling org argouml uml cognitive critics These are Critics which are directly related to UML issues well more or less For example it will nag when a class has too many operations because that makes it hard to maintain the particular class This package also contains Wizards used by these Critiques org argouml pattern cognitive critics These are critics related to patterns Currently they deal only with the Singleton pattern org argouml language java cognitive critics These are critics which deal with java specific issues Currently this is only a warning against model ing multiple inheritance The Base class for Wizards is org argouml kernel Wizard Checklists are located in the package org argouml cognitive checklist Helper classes for To Do Items To Do Pane Wizards and the Knowledge Types are located
2. What NS UML use only JMI MDR_ use only Model subsystem within Model subsys within Model subsys tem tem Test that an o instanceof CLASSNAME Model getFacade isAmodelele Object 0 Mmodelelement sInstanceOf RefObject ment t ype o boolean has a cer t ype boolean toTest String class tain type Name boolean Get a single Mmodelelement _ RefFeatured obj Model getFacade getopropert y o valued type o efGetValue String Object model ele getproperty mod propName ment from el element 222Type an Object o Get a multi Mmodelelement _ RefFeatured obj Model getFacade getopropert y o valued type o tefGetValue String Iterator or Collection total confu property getproperty Col propName Collection sion from an lection Object o Create a MFactory 22 2 CLASSNAME Model new model getDefaultFactory creatInstance String getMode1Element Domain Fact element of createType Type List argument ory type Type RefObject buildmodelelementtype args or Model getModelElement Domain Fact ory createmodelelementtype to create them completely empty 42 Inside the subsystems el elements of a certain type Type What NS UML use only JMI MDR_ use only Model subsystem within Model subsys within Model subsys tem tem Delete a Model getUmlFactory delete ob model ele ject ment Register for
3. one of the reasons for providing the generic Pluggable interface that PluggableThings extend create a pluggable notation create a pluggable diagram Let s say we want to enable a new diagram type as a plug in We use the interface PluggableDiagram that uses a method that returns an JMenultem object public JMenulItem getDiagramMenulItem The returned menu item will be added to the diagrams menu to allow to open a new diagram of this type In this example we do this by creating a helper class in the package org argouml application helpers that implements the created plug in interface PluggableDiagram and call it DiagramHelper pub imp lic abstract class DiagramHelper extends ArgoDiagram lements PluggableDiagram Default A public final localization key for diagrams static String DIAGRAM_BUNDLE DiagramType String naming the resource bundle to use for localization protected String _bundle public DiagramHelper _bundle getDiagramResourceBundleKey public void setModuleEnabled boolean v public boolean initializeModule return true public boolean inContext Object o return true public boolean isModuleEnabled return true public Vector getModulePopUpActions Vector v Object o return null public boolean shutdownModule return true public JMenulItem getDiagramMenulItem i retur
4. CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE SUPPORT UPDATES ENHANCEMENTS OR MODIFICATIONS package whatever The file and version is maintained by CVS using keyword substitution The year in the copyright no tice is maintained manually This differs from the Sun Code Conventions that requires the initial comment to be a C style com ment This is checked by Checkstyle e All instance variables are private This is not required by the Sun Code Conventions but an additional requirement for ArgoUML This is checked by Checkstyle e Use Javadoc for each class instance variable and method In general do not put comments in the body of a method If you are doing something complex enough to need a comment consider break 112 Standards for coding in ArgoUML ing it out into its own private commented method This is not required by the Sun Code Conventions but an additional requirement for ArgoUML This is partly checked by Checkstyle Checkstyle does currently only warn if a Javadoc comment is omitted for a public protected or default visibility variable or method Indicate places of future modifications with TODO reason This differs from the Sun Code Conventions that uses either XXX or
5. Any helper classes such as abstract implementation classes are also found in org argouml language At boot time each language registers their interfaces in the org argouml language Language register e Languages that generates a Notation implement the Notat ionGenerator interface e Languages that edits or parses the Notation implement the Notat ionEditor interface e Languages that generates Code templates implement the CodeGenerator interface e Languages that reverse engineer Code implement the CodeReverseEngineer interface Full MDA implementations of languages is not currently discussed I Linus April 2004 does not under stand how it is supposed to work 5 8 Java Code generations and Reverse En 68 Inside the subsystems gineering 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 The java things are located in org argouml language java The Java subsystem is a Loadable subsystem See Section 4 6 Loadable subsystems 5 8 1 How do 5 8 2 Which sources are involved The package org argouml uml reveng is supposed to hold those classes that are common to all RE pack ages 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 mom
6. Complete description on how to use ArgoUML in your project Complete reference on how to use ArgoUML Help text in ArgoUML Users of ArgoUML Give a quick help with a specific feature or button Give short ex planations of all commands and actions A complete set of quick help and explanations FAQ Users of ArgoUML Members of the users mailing list Cope for shortcomings in ArgoUML the help text the Manual and quick guide and the web site A list of issues that are not ad dressed 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 The Cookbook the User Manual and the Quick Guide are all written in docbook and generated into HTML and PDF during deployment See Chapter 10 Standards For Documentation Writing for details on how to write these 7 2 User Manual Plans 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 100 Organization of ArgoUML documentation This section describes the ambition and plans
7. Inside the subsystems e All modules that can be found are examined at startup They can be enabled and disabled individu ally 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 e Dependency between modules 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 implement ation is such that we have no register of dependencies The solution suggested is that the module loader persists in it s 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 The module loader also provides an API that the well behaving modules can use to test if the mod ules they depend on are enabled The less well behaving module can just throw an exception when they fail to enable themselves properly If a module cannot be disabled because some other module depends on it then this is signaled by re turning false from the disabling method e Where modules are loaded from 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 ext directory or if running from J
8. JRE with utils 33 ArgoUML Design The Big Picture Logging Internationalization RE Swing 4 4 Model subsystems These subsystems do not rely on any other part of ArgoUML to do their work except the infrastructure They can all be tested in full individually i e independent of any other subsystem They contain all the information used by all other subsystems so for that reason they represent the model in the MVC pattern All these subsystems are all started and initiated from the Application subsystem The Model See Section 5 1 Model To do items see Section 5 16 To do items GUI Framework To do Items Help System N ad 1 1 X I w l t 1 1 4 5 View and Control subsystems These subsystems rely on the information in the model subsystems in order to do their work All these subsystems are all started and initiated from the Application subsystem Application see Section 5 11 Application Diagrams see Section 5 3 Diagrams Property panels see Section 5 4 Property panels Explorer see Section 5 17 Explorer Code Generation see Section 5 7 Code Generation Subsystem 34 ArgoUML Design The Big Picture e Reverse Engineering see Section 5 6 Reverse Engineering Subsystem e Module loader see Section 5 18 Module loader PropertyPanel xplorer Panel i odule Loade odule Loade xplorer odo Item
9. Logging entries in log4j belong to exactly one level e The FATAL level designates very severe error events that will presumably lead the application to abort Everything known about the reasons for the abortion of the application shall be logged e The ERROR level designates error events that might still allow the application to continue running Everything known about the reasons for this error condition shall be logged e The WARN level designates potentially harmful situations This is if CG can t find all the informa tion required and has to make something up e The INFO level designates informational messages that highlight the progress of the application at coarse grained level This typically involves creating modules subsystems and singletons loading and saving of files imported files opening and closing files e The DEBUG Level designates fine grained informational events that are most useful to debug an ap plication This could be everything happening within the application This list is ordered according to the priority of these logging entries i e if logging on level WARN is en abled for a particular class package all logging entries that belong to the above levels ERROR and FATAL are logged as well For performance reasons it is advised to do a check before frequently passed DEBUG and INFO log4j messages see Example 5 3 Improving on speed performance The purpose of this test is to avoid the creation of th
10. MBase 0 MDRChangeSource Model getPump notification addMElementListener obj addModelEventListener that a mod MElementListener el addChangeListener PropertyChangeListener li Object o el element String eventnames Object has changed Register for Not possible MDRChangeSource ob Model getPump notification j refClass addModelEventListener on all mod addChangeListener PropertyChangeListener li Object Model getMetaTypes getMODELELEMENTTYPEQO String eventnames How do I get the model as XMI on the XMI m new Writer MModel Writer Stream gen new XMIWriter Handled by the Persistence subsystem stream Stream 5 1 6 How do l add a new model element Make a parameterless build method for your NSUML model element in one of the UML Factories for instance CoreFactory Stick to the UML 1 3 spec to choose the correct Factory The pack age structure under org argouml model uml1 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
11. file version info copyright notice Like this Id Copyright c 2005 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 Th nd 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 HE 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
12. 005 as EE aE PREE PASE seaetess Feb ER PERRE S 72 SLL Applications serai ero ees ae poe pose se nt oes vsig EEE EES IEEE oteisesdeseateve ss 73 5 11 1 What is loaded initialized 20 0 ee cee cence eeceeeca teen seen sean eeaeeeas 73 5 11 2 Details pane oet a E EE E E E EAE ones seeess 73 312 Help System se enoeet E keciny orca wits chives 2a peed tan esteti week habe Ea ye ate 74 9 13 International zations neo seceded heseeseaces ac chtd ow aun saws ed wosvens estes naeblaasdaye supose eens 74 5 13 1 Organizing translators 0 5 22 5 eedsk Saeko ekee deh se eta sede pete ek eee ee 75 5 13 2 Ambitions for localization eeeeeeeeeeeeseeteeetestestresrresrresresrrreseres 76 9 1323 HoW do Vs oerein edie ies SEEE EOE EESK EES EIEE ES E EES 76 SAF LOGGING seraa a e vas ata a E a E E AE EEES 78 5 14 1 What to Log in ArgoUML 00 cece cece cence ence eeeeeeeneeeaeeeaeena scans 79 5 14 2 How t Create Log Entries s eossoias iois oiei ae epore roaa p iieo irast S 79 5 14 3 How to Enable Logging eee eo a eE i 81 5 14 4 How to Customize Logging 00 ee ee cece eee cece eeeeeeeneeeaeeaaeenaeeaes 83 Cookbook for Developers of ArgoUML DAS RELCLENCES serie cig tages N a Seca E wea ved eee mates 83 DAS TRE With utils a S sayy ove sanday cedes Sowa a aaa tee Aden yea E Ea 83 516 To dO 1tems EEE E Peete eee A eal is alate Ue 83 DAT Explorer slack fo oon seen vedaes vs Masse oy shige o5 6a nen gos A seas Mea NTs
13. 5 C Check lists 44 Checking out from CVS 7 clean ant target 13 Code Generation 68 Code generation Java 69 Coding Standards 112 Compiling customized 9 Cygwin 9 Unix 9 Windows 9 component 31 Constraints 88 Contents of the CVS repository at Tigris 108 Critics 44 CVS branches 105 checking out from 7 how to work with 104 Mailing list 4 standards 104 CVS repository contents 108 Cygwin Compilation 9 D default properties 9 Details Panel 72 Developers Mailing List 4 Diagrams 49 DocBook 6 docs ant target 19 Documentation 19 work with 20 Dresden OCL Toolkit 89 E Explorer 83 F fop 6 G GEF 7 GUI Framework 72 guitests ant target 13 H Help system 74 118n 74 il8n teams 75 Internationalization 74 Internationalization teams 75 Issue Priority 131 Resolution 131 Issues 130 Closing 137 Mailing list 4 Resolving 134 Resolving Duplicate 136 Resolving Invalid 136 Resolving Rejected 136 Resolving Wontfix 136 Verifying Fixed 136 Verifying WORKSFORME 136 J Jason Robbins Dissertation 128 Java 69 Javadoc building 10 JDepend 6 Jimi 6 JUnit 6 JUnit testing 13 L L10n 74 Language teams 75 139 Index list property files ant target 9 Localization 74 LOG 79 log4j 7 Logger 79 Logging 78 M Mailing lists 4 Making a release 21 Martin Skinner Dissertation 128 Model 37 Module loader 86 N Na
14. 5 Do your work 6 Check in your changes in the branch evs commit m Blablab1la file 7 Continue working and checking in move my work from my working branch into the release This is done when your work with the feature xxxyyy is finished and you have decided received clearance to enter it in the main branch 1 Change directory to the directory where ArgoUML is checked out If you are just working on one feature at a time this is the place where you have a checked out copy on the branch in question If not this could be any checked out copy of the source that does not contain any uncommitted changes 2 Enter the argouml directory cd argouml or chdir argouml 3 Move the checked out copy that you are working on to the main branch cvs update A 4 Merge the changes from the branch into your checked out copy cvs update j work_xxxyyy_myname 5 Compile and run all your tests again This is to verify that the merge was all right no one else had done any changes that in the 106 CVS in the ArgoUML project meantime that has in any way modified the work made in the branch 6 Commit your changes in the main branch cvs commit m xxxyyy entered in the main branch 7 Discontinue your branch From this point on it is important that you do not reuse your branch for any work Only check it out for the purpose of examining how things were in the branch Make sure that all other de velopers that have been looking at your b
15. Completed 3 Choose a suitable example to run throughout 4 Break into several files XML entities to make the manual more manageable Completed 5 Identify all existing sources of material to be reused 6 Get writing I Jeremy Bennet 2002 suggest the priorities here are a 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 b User Manual examples c User Manual sections relating to additional ArgoUML cognitive design features d User Manual sections relating to UML for readers who don t know UML e Completion of Reference Manual material 7 Create an index Completed 7 2 4 2 Remaining Questions 1 The current manual shows copyright held by Phillipe and no legal notice What is the position of this material Solved 103 Chapter 8 CVS in the ArgoUML project The CVS 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 8 1 How to work against the CVS repository When you have done all the work and all the testing and are about to commit something please do 1 Compile ArgoUML build run or build package This
16. FIXME depending on if it works or not Four spaces should be used as the unit of indentation Tabs must be set exactly every 8 spaces not 4 and represent 2 indents This is exactly as it is stated in the Sun Code Conventions It is here just for the emphasis This is checked by Checkstyle If possible use lines shorter than 80 characters wide This is exactly as it is stated in the Sun Code Conventions It is here just for the emphasis 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 Id what ever import statements and Javadoc comments with see tags Open brace on same line at end Both for if while for and for class and functions definitions This is exactly as it is stated in the Sun Code Conventions It is here just for the emphasis Use deprecation when removing public and protected classes methods and attributes Whenever you have a public or protected method or attribute in a class or a public class that you want to remove change the signature in an incompatible way or make change visibility for you shall always deprecate it first After the next stable release you or someone else can remove it 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 allo
17. Note E From here on it is the old text that is more or less Publishing ArgoUML to be reworked How the ArgoUML web site works Tigris provides the ArgoUML site to be edited through CVS Everything that is checked in under 18 2 1 2 Building from source argouml1 www becomes immediately available at the URL http argouml tigris org with some added decorations Example The file argouml www project html is available at ht tp argoumL tigris org project html This is the way the site is maintained and updated The ArgoUML documentation For the ArgoUML project the same documentation shall be available in both HTML PDF and JavaHelp To this end the documentation is written in DocBook XML and generated into two versions of HTML one page per chapter and one page for the whole book PDF and JavaHelp We have tools that does the conversion from DocBook XML to HTML and PDF The conversion is done whenever you need to look at the result or when you want to present the final result on the web site There are currently three different books generated in this way each into its own directory They are cookbook this document manual and quick guide They are all generated and stored in the exact same way except for the name of the directory that is one of cookbook manual or quick guide Below I will reference these directories using book When a new version of the documentation is to be made available on the w
18. String offs VectorSet String getC larifie rd Icon j addControlRec name String controlData Object Object getControlReciname String Object isEnabled boolean setEnabled e boolean void snoozeOrde rd woid snooze 0 void unsnooze 0 void isRelevantToDecisions dsgr boolean isRe le vantToGoals dsgr boolean make Wizard ite m Wizard getWizardC lass ite m Class initWizard w Wizard void getDecisionCategoryd String Hse tDecisionCategoryic String void getC riticT ype 0 String getExpe rtEmaild String setEx pe rtEmailfaddr String void ge tHeadline idm Object dsgr String ge tHeadline offenders YectorSet dsgr String getHeadline String se tHeadline th String void getPriorityloffe nde rs VectorSet dsgr int setPriority p int void getPriorityd int getDe scription offenders YectorSet dsgr String setDe scriptionid String void getDe scriptionTe mplate 0 String 1 ge thtore InfoURLioffe nders VectorSet dsgr String setMore InfoURL m String void gethtore InfoURLO String Hse tArg name String value Object void Age tArginame String Object getAngs0 Hashtable setArgs h Hashtable void toDolte midm Object dsgr void
19. amwnable hultiEditarP ane At the moment there is only one editor tab in place This is the TabDiagram that shows an UMLDia gram the target The TabDiagram is spawn able This means that the user can double click the tab and the diagram will spawn as a separate window The target of the Mult iEditorPane is set via the set Target method of the pane This method is called by the set Target method of the ProjectBrowser The pane s set Target method will call each set Target method of each tab that is an instance of TabModelTarget Besides setting the target of the tabs the set Target method also calls Mult iEditorPane select Object o This selects the new target on a tab This probably belongs in the set Target method of the individual tabs and diagrams but that s how it s implemented at the moment 5 3 1 1 How do l e adda new tab to the MultiEditorPane Create a new class that s a child of JPane1 and put the following line in argo ini multi fully classified name of new tab class 50 Inside the subsystems 5 3 2 How do I add a new element to a diagram 5 3 3 To add a new element to a diagram two main things have to be done 1 Create new Fig classes to represent the element on the diagram and add them to the graph model org argouml uml diagram xxxx XxxxDiagramGraphModel java and renderer org argouml uml diagram xxxx ui XxxxDiagramRenderer java 2 Create a new property panel class that will
20. an icon The list model should be a subclass of UMLModelElementListModel12 a subclass of the Swing DefaultListModel which implements Abst ract ListModel The UMLModelElementList Model12 implements two interfaces one that listens to target changes and one that listens to UML model changes 5 4 1 1 1 The list model In our example we create UMLUseCaseExtendListModel Its constructor takes no arguments However we need to provide the parent class with a NSUML event name by invokeing the constructor of the parent class with the event name as parameter A string naming an NSUML event that should force a refresh of the list model A null value will cause all events to trigger a refresh The best way to identify the event you want to use is to look at the NSUML source for the container object MUseCaseImp1 in our example for calls to fireXXxxX The first argument is the name of the event in our case extend There is no definitive list but from the NSUML source these are all the names of events that are used e action e actionSequence e activator e activityGraph e actualArgument 55 Inside the subsystems addition aggregation alias annotatedElement argument association associationEnd associationEndRole associationRole attribute attributeLink availableContents availableFeature availableQualifier base baseClass baseElement behavior behavioralFeature binding body bound callAction cha
21. be displayed in the property tab window on the details pane This is described in Section 5 4 Property panels Throughout we shall use the example of adding the UML Extend relationship to a use case diagram This allows two Use Cases to be joined by a dotted arrow labeled extend to show that one extends the behavior of the other The classes involved in this particular example have all been well commented and have full Javadoc de scriptions to help when examining the code You will need to read the description here in conjunction with looking at the code How to add a new Fig The new item must be added to the tool bar Both the graph model and diagram renderer for the diagram will need modifying for any new fig object 5 3 3 1 Adding to the tool bar Find the diagram object in uml diagram XXXX ui UMLYYYYDiagram java where XXXX is the diagram type lower case and YYYY the diagram type bumpy caps For example uml dia gram use_case ui UMLUseCaseDiagram java This will be a subclass of UMLDiagram in uml diagram ui UMLDiagram java Each tool bar action is declared as a protected static field of class Action initiated as a new Cmd CreateNode for nodal UML elements or a new CmdSetMode for behavior or creation of line UML elements These classes are part of the GEF library The common ones select broom graphic annotations are inherited from UMLDiagram the diagram specific ones in the class itself For examp
22. build test reports junit output html index html The test cases Java source code is located under argouml tests org argouml 2 5 1 How to write a test case 13 Building from source Now this will make all you Java enthusiasts go nuts We have both class names and method names with a special syntax 2 5 1 1 About the Test case Class 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 src_new build xml search for test case classes with these names If you write a test case class that does not comply to this rule you still can run the test cases in this class manually by starting with build run with test panel but it wont be known and run by other developers and automatic build mechan isms so don t do it Test case classes that don t require GUI components in place have filenames like Test java They must be able to run on a headless system To make sure that this works always run your newly de veloped test cases with build tests using JDK 1 4 or later Test case classes that do require GUI components in place have filenames like GUITest java We should try to get as many tests from a GUITest class to the corresponding Test class because the latter are run by automatic builds regularly Every class org argouml x y z_ stored in the file src_new org argouml x y z java
23. build these are in the ant files for each module Run the ant targets generate or generateparser in each of these modules and then reload the source trees Select the class with the main method In the Java perspective select the project argouml i e the icon at the top of the Package Explorer Then in the menu select Run gt Run This will open the dialog for creating managing and run ning Run Configurations 120 Standards for coding in ArgoUML Select Java Application on the left and press the New button Name the configuration Run ArgoUML and press the Search button in the Main class box In the new dialog that appears Choose Main Type simply press OK This sets the Main class to org argouml application Main Press the Run button This will start ArgoUML From now on you can start ArgoUML by a single press on the Run icon in the toolbar 7 Verify that you can start ArgoUML from the debugger within Eclipse You can do this by clicking on the Debug icon in the toolbar 9 7 2 Eclipse to help with the ArgoUML coding style 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 On the other hand these settings affect your Eclipse Workspace rather than the ArgoUML pro
24. compiled source e tests optional This runs all the JUnit test cases available in the module This probably requires the junit jar tool from the argoum project 12 Building from source 2 4 3 Troubleshooting the development build 2 4 3 1 Compiling failed Any suggestions It might be that some other developer has made a mistake in checking in things that contain errors or forgotten to check in some files in a change Look at the last couple of hours on the developers mailing list http argouml1 tigris org servlets BrowseList listName dev It is probably on fire Another reason for problems is an unclean local source tree This means that if you have updated differ ent parts of your source tree at different times it might contain inconsistencies If you suspect this first try to fix it by doing build clean and cvs update d before trying to build again If that doesn t work re move your checked out copy completely and get it all again through CVS Another reason might be that you have an build properties or argouml build properties file that you have been working with earlier and that is doing something If in doubt remove those files If nothing helps ask the developers mailing list mailto dev argouml tigris org 2 4 3 2 Can t commit my changes You need to have a developer role in the ArgoUML project If you don t then you cannot do commit yourself Discuss what you have done and how best to test it on the deve
25. discuss this He will create the team and the project and make you the first member of the team and project once he is convinced that you have understood the responsibilities The Language Teams are listed on the web page of language teams on the Tigris site The project are argouml subprojects so they are listed at the bottom of the argoum web page find the languages internationalization code for the language your instance of ArgoUML is at tempting to run with en es en_GB The one you are currently using is shown in the Versions information in the about box Help Menu gt About ArgoUML Menuitem gt Version tab just after the Operating System information Search for the text looking like this Language sh Country KR This example means that you have your computer set to Swahili as spoken in Korea I think Notice that the Language and Country are localized and could appear in your language Start the translation work This is only applicable for members of the language team Look at the files in org argoum1 il18n under argouml src_new the argouml project Translate all the values in each of these files This is a lot of extremely qualified work including searching well known literature on UML and Software Engineering in order to get the correct terms for the domain Discuss with other UML and Software Engineering professionals with the same native language to get it right Create the files with the translations
26. for the User Manual 7 2 1 Target Audiences for the User Manual Target audiences are the following e Experienced users of UML in OOA amp D perhaps with other tools who wish to transfer to ArgoUML e Designers who know OOA amp D and wish to adopt a UML based process In the longer term it would be desirable to also target the following e Those who are learning design and wish to start with a UML based OOA amp D process e People interested in modularized code design with a GUI 7 2 2 Goals for the User Manual The goals are in priority order 1 A tutorial style explanation of ArgoUML in the context of an OOA amp D process 2 Descriptive reference material on all components of ArgoUML 3 Keep boundaries clearly defined to avoid duplication with the Cookbook FAQ Quick Guide on line help etc I probably Jeremy Bennet in 2002 think the existing User Manual is a good start particularly towards the second of these goals 7 2 2 1 What the User Manual is not currently To keep the effort feasible the user manual should avoid the following at least initially e Providing a quick overview the Quick Guide already does this e Listing all the errors and what they mean The help system does this one day the manual will link to that e Explaining the internal workings of ArgoUML The cookbook combined with Jason Robbins disser tation is already a good start for this 7 2 3 Suggested Manual Structure H
27. for user and dev argouml language code tigris org for persons discussing the building of the site or the translation Discussions on both lists should be carried out in the actual language 5 13 3 How do f1X an incorrect or missing translation This is the responsibility of the language team If you are a member of the language team commit the new translation If you are not send your corrections to the correct team by mail or enter an issue in issuezilla Each language team might want to handle this differently Whatever way it should is stated on the web site for that team The language team members are the ones with the Developer role in the language project If the language team does not do its work quickly enough or well enough in your opinion please volunteer to help them out by joining the team If the language team does not respond contact the project leader of the ArgoUML project For historic reasons there are currently June 2005 teams without projects of their own Projects will be created when something is to be done for these languages verify that all translations are up to date There is a simple tool you can use that is developed in the argouml gen project Currently June 2005 this tool is run regularly and a web page with the result published in the argoum stats project 76 Inside the subsystems start a new Language Team Contact the project leader of the ArgoUML project to
28. 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 1 The JTree org argouml ui explorer ExplorerTree has been customized to maintain consistent se lection state with the other model views It provides a pop up menu ExplorerPopup for perform ing actions on specific model elements There is specific functionality in DnDExplorerTree for Drag and drop and in ExportExplorer for copy diagram to clipboard 2 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 Ex plorerTreeNodes that maintain their own order on child nodes this will typically be an alphabetic al order on the model element names However it could be enhanced to include more powerful or ders like total subtree size 3 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 PerspectiveR ules that together provide a specialized view of the UML model This is very flexible and extens ible The org argouml ui explorer rules package contains a default set of PerspectiveRules Each node is displayed with a name and an Icon
29. 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 buildAttribute for an example If you need to attach other already existing model elements to your model element make a buildxXxXxx MModelelement toattachl 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 al ways have initialized model elements which will make a difference concerning save load issues for example Now you probably also need to create a Property Panel and a Fig object See Section 5 3 3 5 Creating a new Fig explanation 2 create a new create method Create it in the correct factory create a new utility method 43 Inside the subsystems Create it in the correct helper 5 2 Critics and other cognitive tools 5 2 1 Purpose to provide cognitive help for the User This help is based on the current model that the User works with The Critics are located in org argouml cognitive The Critics is a Loadable subsystem See Section 4 6 Loadable subsystems The Critics subsystem depends on the Model that it works against to take all decisions and the To Do Items used to present the information This subsystem contains the following main class types e Critics provide help to find artifacts in the model that do not obey simple design rules o
30. inher cont c lineup java inher func decl cont c lineup java throws 9 7 How to work with Eclipse 3 Linus Tolke If you are running Eclipse 3 you can find information on how to set the development environment fitting ArgoUML There are several sets of instructions here depending that you can apply separately depend ing on how much of the ArgoUML knowledge you would want to include in your Eclipse If any of these instructions don t work or could be improved in some way please help in making them better 9 7 1 Checking out through Eclipse 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 1 Set up the CVS Repository Change to the CVS Repository perspective and select Add CVS Repository Then enter the follow ing information e Host cvs tigris org e Repository path cvs e User Your Tigris user name e Password Your Tigris password e Connection type pserver default e Use Default Port default 2 Check out In the CVS Repository Exploring perspective unfold the newly created repository called something like pserver your user name cvs tigris org cvs and within it HEAD Select the argouml project right click on it and do Check Out As Check out as a project con figured using the New Project Wizard Press the button Finish Select Java Project and press Next Type the new project name argouml and press Next Ig
31. normally a part of the API or a simplified version of the API 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 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 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 4 3 Low level subsystems These subsystems are infrastructure subsystems that just are there for every other subsystem to use They are all insignificant enough not to be mentioned when listing dependencies All these subsystems are all started and initiated if needed from the Application subsystem Logging see Section 5 14 Logging Internationalization see Section 5 13 Internationalization GUI see Section 5 10 The GUI Help system see Section 5 12 Help System JRE with utils see Section 5 15
32. of the NSUML EventListener inter face which is not well documented In each case the default im plementation recomputes the size and advises Swing that the en tire list has changed Needs more investigation a request to navigate to the specified object as part of the Naviga tionListener interface The default in the parent just invokes nav igateTo on the container ultimately PropPanel tEvent pl The following utility routines are also provided in the parent They are not normally overridden get any upper bound 1 is used if there is none set the upper bound 1 is used if there is none returns the NSUML event name being monitored null if all are being monitored returns the number of elements in the list Invokes recal cModelElement Size see above if necessary returns the NSUML object associated with the container some child of PropPanel1 usually that holds this list model returns the the container some child of PropPanel1 usually that holds this list model returns the size of the list Including if there are no elements in the model but the list has a default text when empty returns the element at the given index in the list 64 Inside the subsystems dAtUtil Collection old helps in writing the add function newItem is added at the spe Collection MModelEle cified index in the given oldCollection ment newltem int index static protected help
33. 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 In this Cookbook you will find Information on how to compile ArgoUML Information on how different features of ArgoUML are implemented Information on how you should add modules and Plug ins to ArgoUML Information that you as a developer of ArgoUML need to know about how the project is organized and how to contribute In this Cookbook you will not find You will not find information on how to install and use ArgoUML You will not find information on what UML is and if or how you should use it in your project Introduction You will not find information on how to convince your project to use ArgoUML as a modeling tool 1 5 Mailing Lists All developers MUST subscribe to the mailing list for developers Please find the details at ht tp argoum1 tigris org servlets ProjectMailingListList http argouml tigris org servlets ProjectMailingListList It is also recommended to join the CVS 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 them selves and others Chapter 2 Building from source Building ArgoUML from source requires a CVS client a current JDK 1 4 or later and 150MB of free disk space All other tools including the Ant build tool upon which th
34. one system and used and edited on another NFS SMB this is not done correctly There could also be CVS clients out there not doing this correctly Systems known to the author Linus Tolke are Unix uses LF DOS Windows uses CR LF Mac uses CR Most of the time this really doesn t matter because the editors and java compiler on all systems are very forgiving There are however some cases when this is cumbersome 107 CVS in the ArgoUML project When an editor or developer decides to fix it This means that the editor or the developer goes through the file and removes M on every line or something else that touches every line in the file This is a problem because the subsequent commit will also touch every line in the file making that file unmergeable This means that every developer that had it modified in a branch or in a checked out copy will have no help from CVS when doing his merging Remember that you never know what other developers are working with This is fixed by not doing any such fixes and doing a evs diff before each check in so that your editor has not done this for you When CVS clients and file systems are not in sync This could result in one of several things Either each line gets an extra empty line when com mitted or the whole file turns out to be on the same line This is the case on several files in the repository at the moment August 2002 Linus and can be cumbersome for the develo
35. or less only Dresden OCL Toolkit and adaptation 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 Issue 1805 http argoum1 tigris org issues show_bug cgi id 1805 89 Chapter 6 Extending ArgoUML This section explains some general concepts which come in handy when developing additions to ArgoUML Warning There are two module loading mechanisms the old one and the new one This is so because we have made a change of the design used for this in order to simplify the writing of modules Eventually the old module loader will be removed so for all new additions the new mod ule loader shall be used 6 1 How do 1 e get the according NS UML element for a given FigXXX class Each FigXXX implements the method get Owner which returns the appropriate owner element which is responsible for this Fig element e get the according Fig element for a given MModelElement for this one needs to iterate through all fig elements and invoke get Owner Compare the result with the given MModelElement Beware that there might be more than one Fig Element per MModelElement 6 2 Modules and Plugins The ArgoUML tool provides a basis for UML design and potentially an executable architecture environ ment for more specialized applica
36. or no longer pertinent please compile again 7 Commit all files that are included in a change at the same time This reduces the chance of anyone getting an inconsistent set of files by updating in the middle of your commit 8 Commit often Remember that the repository is also a backup copy of your work If your change is so big and involves so many files that you would like to commit it for backup 104 CVS in the ArgoUML project reasons but it doesn t compile or doesn t work or for some other reason should not confuse the main branch in CVS create a branch to work in Then when your work is complete you merge the branch into the main branch Rationale These ground rules is for the purpose of not stopping or hindering the work for anyone Re member 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 Perspective If this will take you an extra two minutes before every commit remember that if you com mit something that will not work this will take everyone else guess 10 persons the extra time of look ing 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 up
37. representing the type of node it is in the UML model This is done using the org argouml uml ui UMLTreeRenderer for the Icon and the text is produced in the convertValueToText method in org argouml ui explorer ExplorerTree 5 17 4 How do e add another perspective e The perspectives can be configured using the org argouml ui explorer PerspectiveConfigurator by the User The changes to the pre defined built in defaults are stored in the argo user properties file 85 Inside the subsystems e Ifyou 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 PerspectiveManager e improve the PopUp menu There is no way of doing this currently without modifying the core of ArgoUML You could use SPI1 when it gets implemented e extend the Explorer in other ways The best way is to use the above APIs SPIs if they are not implemented then it would be best to im plement 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 e add new rules for new model elements You should create a GoRule PerspectiveRule in org argouml ui explorer rules There are plenty of examples to look at The important things to get right is of course that e you return the right children e return the objects that the TreeModel must
38. required e Answer clarification requests 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 e Close the issue This applies to an issue that is in verified state only 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 e Reopen the issue This applies to an issue that is in verified state only 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 12 3 2 The Resolver The Resolver is the software developer who attempts to resolve the issue Doing so requires at least ob server role The developer role is only needed to commit things into CVS e g submit changed Java code scripts or documentation 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 CVS The goal of the Resolver is to progress the issue to the status of Resolved The resolver may be
39. subclasses by that value F is 0 5 E is 1 DGs 2 So the placement is ABC here are the links but I can hardly paint them as ASCIIs FED 5 9 Other languages Each other language supported by ArgoUML has its own subsystem They are each different in level of support and implementation language Currently C has no reverse engineering but only code generation and a very simple one at that Java class files has only reverse engineering ava classfiles 5 10 The GUI Purpose Provide an infrastructure with menus tabs and panes available for the other subsystems to fill with actions and contents This subsystem has no knowledge of UML Critics Diagrams or Model The GUI Framework is located in org argouml This is implemented directly on top of Swing and Java2 The GUI framework provides the following options 72 Inside the subsystems e The menu with actions e The tool bar with actions e The Explorer formerly called Navigator Located in org argouml ui explorer Contains the tree structure with configurable per spectives e Tabbed pane Could contain several different panes e The TargetManager Located in org argouml ui targetmanager Thanks to the architecture of ArgoUML of Modelelements and Figs one rule has been decided upon by mvw tigris org The list of targets shall not contain any Fig that has an owner Instead the owner is enlisted Application Purpose to provide the en
40. test cases understand what he is supposed to do do it and document the result we try to go as far as pos sible with the JUnit test cases and have as few manual test cases as possible Le If one of these tests can be converted into a JUnit test case we shall try to do so because it can save us a lot of time On the other hand there are several things that cannot possibly be tested with JUnit tests so there probably are a lot of Manual Test Cases to be written Running the manual tests Anyone can run the manual tests on any version of ArgoUML If it doesn t work i e the expected result is not seen then this is a defect in that version of ArgoUML and should be reported using Issuezilla At every release the ambition is to run through all manual tests Initially when the amount of manual tests is small this is done by the release responsible while testing the newly compiled release Later on when the amount of manual tests makes it unpractical to this during the release work the work can be done by anyone or any group of people within the project after a development release is made and be fore a stable release is made A signed statement with list of run tests including version number a list hopefully empty of failed tests together with their Issuezilla DEFECT number the host type OS JDK version ArgoUML version shall be mailed to the dev list when these tests are completed Writing the manual tests Adding a new manual tes
41. the same person as the reporter Responsibilities 133 Processes for the ArgoUML project e Decide usefulness if this issue is really a bug or enhancement and if it is worth solving 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 e If applicable program and test a solution 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 e If applicable write test cases e Set the issue in the end on Resolved When the resolver is finished with the issue he puts it in Resolved status and indicates the resolu tion is Fixed Worksforme Invalid Wontfix or Duplicate Skills The resolver needs to know a lot of the insides of the ArgoUML code Java coding standard
42. the ArgoUML project 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 de velopers mailing list mailto dev argoum1 tigris org 12 1 The big picture for Issues Here is the big picture of the life of an Issue Resolver expmines the issue amp ssbe for himself Resolver co The Verifier does not agree The Verifier agrees with the Resolver about the resolution The Reporter op cks the resolution The Reporter does not accept the resolution The Reporter a gepts the resolution 130 Processes for the ArgoUML project 12 2 Attributes of an issue 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 Tigris definition of the resolutions http argouml tigris org project www docs issue_lifecycle html and for that reason it is not a complete list 12 2 1 Priorities The priorities are used in the following manner in ArgoUML e PI Fatal error These issues are blockers for all releases Examples ArgoUML cannot start Crashes program jvm or computer and Significant loss of user data e 2 Serious error These issues are blockers for stable releases Examples Information lost e 3 Not so serious error Examples Functions not working Strange behavior and
43. the time of writing this paragraph it is not possible to set the logging configuration file on a per project basis in NetBeans Instead the Global Options of Debbuging and Execution Execution Types External Execution External Process need to be changed 82 Inside the subsystems Example 5 7 External Execution Property Arguments cp filesystems classpath library Dlog4j configuration URL classname arguments 5 14 4 How to Customize Logging There are some sample configuration files provided in org argouml resource Modify these ac cording to your needs Or alternatively you can try configLog4j http www japhy de configLog4j to assist yourself in creating a log4j configuration file 5 14 5 References e The log4j project homepage at http jakarta apache org log4j http jakarta apache org log4j e The configlog4j homepage at http www japhy de configLog4j http www japhy de configLog4j 5 15 JRE with utils Purpose to provide the infrastructure to run everything The JRE is an infrastructure subsystem See Section 4 4 Model subsystems It is not distributed with ArgoUML but considered to be a precondition in the same respect as the user s host This is a Java3 JRE so swing and awt can be used together with reflection 5 16 To do items Purpose To keep track of the To do items Items are generated and removed automatically by the crit ics They could also be created by ot
44. to Contribute Changed some spelling errors in cook book in while at it See Section 1 3 How to contribute Changes to description of module loader making the new module loader a fact See Section 5 18 Module loader and Section 6 2 Modules and PlugIns Change to the description on how to extend ArgoUML Now module loader described See Chapter 6 Extending ArgoUML Changed the meaning of RESOLVED LATER See 10 f and g in Section 2 8 Making a release and Section 12 2 2 Resolutions Change to design of new module loader See Section 5 18 2 Design of the new Module Loader Deemphasized the layers and instead describe the subsystems in groups according to the MVC pattern See Chapter 4 ArgoUML Design The Big Picture and Chapter 5 Inside the subsystems Change to the definition of the priorities Now they are defined in terms of how much release blocker they are See Section 12 2 1 Priorities Added rationale for not using RESOLVED REMIND or RE SOLVED LATER See Section 12 2 2 Resolutions Reorganized the description on how to use Eclipse 3 Added instruc tions on how to use the Eclipse JUnit test runner See Section 9 7 How to work with Eclipse 3 Added this Change Log See Change Log Linus Tolke Linus Tolke Linus Tolke Linus Tolke Linus Tolke Linus Tolke Linus Tolke Linus Tolke Linus Tolke Linus Tolke Linus Tolke
45. to be replaced by interfaces without NSUML object and eventually removed The NSUML model itself does not define enough business logic to be directly used and the factories and helper classes provide a set of interfaces that wraps all functions of NSUML In the NSUML implementation factories contain delete methods but they are only used internally within the Model subsystem How to work against the model NS UML is used within the Model subsystem to keep all data structures in place Eventually we will change that to JMI MDR that is newer and better and will take us into UML 1 4 UML 1 5 and UML 2 0 Working directly against NS UML or JMI MDR will make changes in the NS UML or JMI MDR affect large portions of the code For this reason we have in the Model subsystem a set of classes that lay between the NS UML and JMI MDR that hides the APIs of NS UML or JMI MDR between something that will not change while moving between them This is the API classes of the Model sub system i e Factories Helpers Event Pump where to register for changes Here follows a list of how different things are done for the purpose of making the transition easy Everything within ArgoUML should access the Model subsystem through the interfaces in the org argouml model package The NS UML or JMI MDR and whatever other implementation we could eventually come up with would provide the implementation of those interfaces Table 5 1 How to work against the model
46. uml ui corresponding to the XXX NSUML packages which in turn correspond to their section in the chapter 2 of the UML 1 3 spec So for our example we create a new class PropPanelExtend in package org argouml uml ui behavior use_cases Any associated classes that do not fall into the UML classification are provided in org argouml uml ui Typically the constructor for the new proppanel class invokes the parent constructor and then builds the fields required on the property tab The parent constructor may need an icon If you need a new icon it should be placed in org argouml Images and a call to LookupIcon made note that this is a utility method of the parent PropPanel class For our example we had to add Extend gif Finally the property panel must be added to the list of property panels in the run method of the TabProps class with a new call of panels put If you don t do this navigation listeners won t know about it The content of the property panel is created as a grid with columns 1 column if there are only a few fields 2 or 3 if there are more Each row of each column contains a caption i e label and its corres ponding field A caption and its field may be added with one of a small number of utility methods which shield you from the layout stuff addField and addSeperator A button may be added to the toolbar with the utility method addButton Every field is built from Java Swing components However the
47. update the fig if the model is changed See FigAssociation and FigClass for an example 5 If you have text that can be edited override the method textEdited FigText text In this method the edited text is parsed If the parsing is simple and not Notation specific just do it in textEdited But for most cases delegate to ParserDisplay See the method parseAttribute in ParserDisplay for an example Stick to the Notation you are using to have the right parsing scheme There is work to be done here but please don t make it an even bigger mess 6 Make an Action that can be called from the GUI If you are lucky you just can use CndCreat eN ode See for examples UMLClassDiagram of using CndCreateNode 7 Adapt the method canAddEdge Object o on subclasses of GraphModel if you are build ing an edge so it will return true if the edge may be added to the subclass Subclasses are for ex ample ClassDiagramGraphModel and UseCaseDiagramGraphModel If you are build ing anode adapt canAddNode Object o 8 Adapt the method getFigEdgeFor on implementors of GraphEdgeRenderer if you are im plementing an edge so it will return the correct FigEdge for your object If you are implementing a node adapt the method getFigNodeFor on implementors of GraphNodeRenderer In ArgoUML classes like ClassDiagramRenderer implement these interfaces 9 Add an image file for the buttons to the resource directory org argouml Images This image file mus
48. use the Model subsystem the Linus Tolke ModelFacade does not exist anymore See Section 5 1 5 How to Vili Change Log When What Who 2005 01 29 2005 01 26 2005 01 07 2004 12 30 2004 11 01 2004 10 29 2004 10 19 2004 10 11 2004 09 17 2004 09 16 2004 09 15 2004 08 17 2004 08 17 2004 08 02 2004 07 28 2004 07 25 work against the model Change to Model subsystem chapter Removed references to Um lEventPump and clearified how to remove elements using the Uml Factory See Section 5 1 3 2 1 How do I register a listener for a certain type event and Section 5 1 5 How to work against the model Change to requirement of JDK version support See Section 3 3 1 Choice of JRE ArgoUML will support any JRE compatible with a Sun specification of any JRE from Sun that has not begun the Sun End of Life EOL process Added copyright notices to the files Change the default year in the copyright notices Yes I am a little early See Chapter 9 Standards for coding in ArgoUML and Sec tion 9 7 How to work with Eclipse 3 Change to the way we generate documentation The FILENAME id files are no longer used See Section 2 7 Generating documenta tion Change to the description on how to generate documentation Better explanation of how it works See Section 2 7 Generating docu mentation Change to How
49. you where some JDK 1 5 features have crept in e Find forgotten and incorrect Javadoc comments In the menu select Window gt Preferences Then select Java gt Compiler Suggested settings for these tabs Only things diverting from the Eclipse defaults are listed e Javadoc gt Malformed javadoc comments Warning Private Report errors in tags e Javadoc gt Missing javadoc tags Warning Protected Check overriding and implementing methods These problems are also found by Checkstyle so if you are running checkclipse See Sec 122 Standards for coding in ArgoUML tion 9 7 4 Settings for checkclipse put this in Ignore instead Code that hides other code In the menu select Window gt Preferences Then select Java gt Compiler Suggested settings for these tabs Only things diverting from the Eclipse defaults are listed e Style gt Possible accidental boolean assignment Warning e Advanced gt Local variable declaration hides another field or variable Warning e Advanced gt Field declaration hides another field or variable Warning Find Code that shall be removed In the menu select Window gt Preferences Then select Java gt Compiler Suggested settings for these tabs Only things diverting from the Eclipse defaults are listed e Unused code gt Local variable is never read Warning e Unused code gt Parameter is never read Warning e Unused code gt Unused or unread pri
50. 1 Run ArgoUML using argouml jar 2 Run ArgoUML using the ant script In the first case the configuration file is specified directly on the command line whereas in the latter case this parameter is specified in the build xml which in that case needs to be modified ArgoUML is then started as usual with build run Example 5 5 Command Line for argouml jar localhost billy java Dlog4j configuration URL jar argouml jar Example 5 6 Modification of build xml lt lt Run ArgoUML from compiled sources lt lt target name run depends compile gt lt echo message Executing Name gt lt Uncomment the sysproperty and change the value if you want gt lt java classname org argouml application Main fork yes classpath build dest classpath gt lt sysproperty key log4j configuration value org argouml resource filename lcf gt lt sysproperty gt lt java gt lt target gt 5 14 3 2 when running ArgoUML from WebStart To view the console output the WebStart user has to set Enable Java Console in the Java Web Start preferences In the same dialog there is also an option to save the Console Output to a file As you cannot provide any userspecific parameters to a WebStart Application from within WebStart it is currently not possible to choose log4j configuration when running ArgoUML from Java Web Start 5 14 3 3 when running ArgoUML from NetBeans At
51. 105 CVS in the ArgoUML project Don t forget to update the corresponding issue if any in Issuezilla i e set it to RESOLVED FIXED get my update or patch into CVS if I don t have CVS write rights Contact any of the active developers on the list and send them your updates They re very nice about it the first few times Supposing that you have checked out CVS as guest then after you have mailed a diff or file to an active developer and he has entered it in CVS your checked out copy contains the change but is not in sync and the next cvs update will result in an merge error The simplest way to solve this is to do remove all files modified by you before doing the cvs update The cvs update will restore all the files from the CVS repository and you can start with the next update get a list of the currently active working branches You can t from CVS You need to follow the announcements of created and discontinued branches on the mailing list to know what branches are interesting create a branch for my work on xxxyyy and start work on that branch This assumes that you have a checked out copy of ArgoUML 1 Change directory to the directory where ArgoUML is checked out 2 Enter the argouml directory cd argouml or chdir argouml 3 Create your branch evs tag b work_xxxyyy_myname myname is is a self explaining code for you your Tigris login 4 Change your checked out copy to be on the branch cvs update r work_xxxyyy_myname
52. 2 Helpers respectively In the beginning of 2003 in the work to replace NSUML the need for this interface not to use any NSUML classes was seen The ModelFacade was introduced to wrap model factories model helpers and direct calls to NSUML but not the model event pump In April 2004 a ModelEventPump interface was introduced to wrap the Um1ModelEventPump using PropertyChangeEvents 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 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 fmodelelement1 MBase flistenerl MElementListener fmodelelement3 MBase listener MElementListener modelelementi MBase A flistenert MElementListener imodelelement2 MBase pump UmiModelEventPump flistener2 MElementListener imodelelement3 MBase flistener3 MElementListener The model event pump will rep
53. 2 Rules for the building process ssseessseeesseesesrrerrererererrererrsrrerreresrrressreeeere 115 9 3 Checklist for using sub products cee ceee cece cece eee ce cece cece ecaeene eens eeueeeeeeeeeees 115 OAs Settings for EClps 2 2h s4 cha shevtswohd 4 a a sang dehdaceos Gah aa das chaste aabaoeh ens tebe 117 95 Settings tor NetBeans sss issed toh teh hissed heh E aah eee te es 118 9 6 Settings for EMACS css sets iiss sesnswsbete sds vee seaceseviaa gases TESE EEOSE Epa S Ree 118 9 7 How to work with Eclipse 3 oo eee cee c cee ceeeceeeceeeeaeeea cena seas eeueeeneeeneees 119 9 7 1 Checking out through Eclipse 2 0 0 0 cece cece cece ence ence eeeeeeceeeeeeeeneeenes 119 9 7 2 Eclipse to help with the ArgoUML coding style eee eeee eee 121 9 7 3 Eclipse to automatically find problems in the code eee eee 122 9 7 4 Settings for checkclipse 0 00 0 cece eee cece ceeece ence eeceeeeneeeeeeeeeeeeeeeeeenees 123 9 7 S Run the JUUNIT TESIS ee n hee A See ES eee a A 123 10 Standards For Documentation Writing 0 0 0 eee cece cree ce eeceeeae eens een eeneeeeeeeeees 125 LO Te Introd Wet one evecsny peated E Sos tot eiceedinste cede eh hivet nd E A E een thal EAS 125 102 Style och seed Sarees pense teva tees ete a os cote done saws ed ene Sorgen wade a EE TEA 125 10 3 Document Conventions 0 0 0 0 cece cece cece ce cece ence E EN a EE E ESA 125 10 4 DocBook Conventions erip oey e E
54. 48 Inside the subsystems 5 3 Diagrams Purpose To present the diagrams to the user and allow the user to manipulate the diagrams through the view The Diagrams are be located in org argouml uml diagram The Diagrams is a View subsystem Section 4 5 View and Control subsystems The Diagrams are depending on the Model subsystem and the GUI The classes in this subsystem are extensions of the GEF base classes GraphModels Figs Selections etc together with some supporting classes This subsystem has no direct access to a specific implementation of the OMG model repository However it does update such a repository via the interface of the Model Subsystem There is an intention Bob Tarling to split this subsystem into several smaller subsystems one for each diagram type This is to allow for indiviual diagram reuse by other applications and to allow us to fast track developers onto a specific subproject containing that subsystem Michael MacDonald and se quence diagrams in mind 5 3 1 Multi editor pane 49 Inside the subsystems The multi editor pane is the pane with the diagram editor in it Normally it is placed in the upper right corner of the application One of the feature requests is to make the pane dockable so maybe it won t be there in the future The multi editor pane consists of tabs that hold editors as you can see in the class diagram TabbedPane JPanel Salntertacer gt TabSp
55. Argo to use a plug in Note Ce This description is for the old module loader 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 If you are using a standard ArgoUML source structure then you should be able to execute build install or ant install 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 build run in the src_new directory If you need to install the jar the hard way try the following steps e Start up ArgoUML e Go to the menu Edit gt Settings and look at the Environment tab Find the entry labeled argo ext dir Create that directory if it does not already exist e Copy the plug in jar and any other jars required by it into that directory e Start up ArgoUML again and you should see the plug in s startup banner if it has one of course 98 Chapter 7 Organization of ArgoUML documentation Linus Tolke This chapter describes what goes into which part of the documentation These ideas are formulated by Linus Tolke 7 1 Overview There are seven significantly different bits of documentation in the ArgoUML project By documenta tion I mean some information of the product that is developed alongside the product and that has a per sistent value 1 The code variable names class names The javadoc 3 The cookboo
56. Cookbook for Developers of ArgoUML An introduction to Developing ArgoUML Edited by Linus Tolke Markus Klink Cookbook for Developers of ArgoUML An introduction to Developing ArgoUML by Linus Tolke and Markus Klink The purpose of this Cookbook is to help in coordinating and documenting the development of ArgoUML This version of the cookbook is loosely connected to the version 0 19 6 of ArgoUML Copyright c 1996 2005 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 accompany ing 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 pro gram for any reason INNO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR DIR ECT 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 ADV
57. Do whatever Expected output whatever Do whatever Expected output whatever 2 6 3 The list of tests This section contains all the tests each in a subsection of its own 2 6 3 1 Modules are enabled TEST1 REVa Does not test any current requirements Preparations Download and install ArgoUML together with the modules Do Start in a window that allows you to see the output on Stdout Expected output Loaded Module Java from classes Loaded Module GeneratorCpp Loaded Module GeneratorCSharp Loaded Module GeneratorPHP 17 Building from source Do Press F7 or select menu Generation gt Generate All Classes Expected output A window pops up with Class Name Java Cpp CSharp and PHP Do Select menu File gt Import sources then open the drop down box Select language for import to the far right Expected output The drop down box contains Java and Java from classes 2 6 3 2 Class diagram TEST2 REVa Requirements tested Section 3 2 1 ArgoUML shall be a correct implementation of the UML 1 3 model and Section 3 2 2 ArgoUML shall implement everything in the UML 1 3 model Do Select the Class Diagram Click the Package symbol on the Edit pane tool bar Click on the dia gram Click the Class symbol on the Edit pane tool bar Click on the diagram Click the Interface sym bol on the Edit pane tool bar Click on the diagram Expected output The Class diagram and the explorer now c
58. EE E RE ENE sea tedareh wen EEES 126 10 5 For Emacs Users soise cose echckesunde deh secede rE EEE e eS OEE EESE EES EESE Enni 127 II Further Reading s eces eiro aa e a E a eE a bes PAE o 128 11 1 Jason Robbins Dissertation 2 0 0 0 0 eee cee cece cee ceeecaeeee cena cena een ceneeeeeeees 128 Del 12 ADStHACE isi eec vores sacs paces saiek sceccpinaidets vetet dgeaceandes aneo ds eacsmutilos Vokeb sas sO piss 128 111 2 Where to find 16 4 at scan Meiosis foresee A ES a 128 11 2 Martin Skinners Dissertation cece cece eee cee ce eeceeeea cena eens eeu eeneeeeeeeeees 128 vi Cookbook for Developers of ArgoUML TIZI Absttact sretna a e EEN E e KEE eee es 128 112 2 Where to find it meas s e A En e E eTe Sa 129 12 Processes for the ArgoUML project anro aTa a E A een E E O A SS 130 12 1 The Big picture LOL ISSUES issofri eae e a r a E E a EE EENS 130 12 2 Attri bUtes OF AaNSSUe e cecseescevebevisaegePaeslees Avewssa sine E A sires a Eai 131 1D 2 1 PHOTIMES is 0s seco coasts o AAA e A ET E EE TAGs 131 12 224 RESOMMONS i cseing Ses iw e aer EE ERE E E EN EE 131 12 3 Roles OF The Workers ceim maie a E GA INA EEE PRATA E AREPO AARS RRA 133 12 3 1 The Reporter cesso ineton a Ere E E E SEINE EE 133 12 3 2 ThS Resolyer sorit a a E E E a 133 12 2373 The Verifier e vanes eR ORAE aE E A SEERE EAE E N ES S EPES 134 12 4 How to resolve an Issue 2 00 0 cee ceceeeceeceeceeceececeeceeeeecaeeeeaeeeea
59. Exceptions logged e P4 Confusing behavior Examples Incorrect help texts and documentation Inconsistant behavior UI not updated and Incor rect javadoc e P5 Small problems Examples Spelling errors Ugly icons Excessive logging Missing javadoc 12 2 2 Resolutions e LATER 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 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 e REMIND Not used 131 Processes for the ArgoUML project Rationale Each issue have basically four states NEW STARTED REOPENED To be resolved RESOLVED To be verified VERIFIED To be closed 4 CLOSED Finished The statistics is based on this and persons looking for issues to resolve look among the To be re solved group the web pages to help in this are set up in this way This is also in synch with our re lease process 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 re solver this is corresponds to NEW REOPEN for the first group STARTED for the second and RE SOLVED for t
60. HOME where you have installed jdk Change the current directory to the directory you are building chdir your checked out copy of argoum1 src_new Start Ant with no parameters to get a list of build targets with descriptions build Compile and run ArgoUML using build run You can do this over and over again when you have modified something or want to compile and run again If you do this from Cygwin you work just like for Unix 2 4 1 3 Customizing and configuring your build It is possible to customize your compilation of ArgoUML If you issue the command build list property files you can see what files are searched for properties Don t change the argouml src_new default properties file unless you are working with updating the development environment itself Instead create one of the other files locally on you ma 9 Building from source chine The properties in these files have precedence over the properties in argouml src_new default properties Remember that if you do this you have modified your development environment To be sure that you will not break anything for anyone else when checking in things developed using this modified environ ment remove these files temporarily for the compiling and testing you do just before you commit 2 4 1 4 Building Javadoc By running ANT again using build prepare docs the Javadoc documentation is generated and put into argouml build javadocs 2 4 1 5 Building one of th
61. ISED OF THE POSSIBILITY OF SUCH DAMAGE THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MER CHANTABILITY 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 Table of Contents PeChan ge Loge sicis c5 nse tee sedate eatietssnteee oane EEE peel chia TEE E o E EEEIEE viii L INTOMUCHON Assess sites os eds wales Hote o rerea eE Si ce sada s REES e EOE NESE SEEE EPEA sss eteaugels sens 1 Pel Thanks eane enea e Sew s uted oa os uedaws eves E E dt eaueeeteet ees 1 1 2 About the project rreson ireo ios eis baba sedate eee bub oo evet EE RE bene E aS 1 1 3 How 10 CONILIDULE s are anmdies pence ges py stone sentee Seis po R EE REEERE EEE Sebo OSEE R oes 1 1 4 About this Cookbook sea ous ea es E E E O EE EEE A E otal 3 1 4 1 In this Cookbook you will find oo eee cee cence cence eeeeeeeeeeeaeeeaeeenes 3 1 4 2 In this Cookbook you will not find 2 0 eee ee ce eeceeeceeeeeeeeaeeenes 3 ES Mai line Lists scssssocisocse sas reeet ood ges enanees EEEE EE EPEE TEOS I mages SIOE SEP Opep Peas 4 2 Building from SQULCE sisin sea Gosia Suge ea S E delet veugeaete eee E EEEE 5 PA EN O TE E Ta sates ooh E E E EE E E E 5 2 2 Preparations sien iuern piee en EREE EA EEE E E EEEE REEE TEE EErEE 5 2 2 1 Which t
62. Linus Tolke Linus Tolke Linus Tolke Linus Tolke Linus Tolke ix Chapter 1 Introduction 1 1 Thanks We the authors would like to take the opportunity to thank everyone involved in the creation of this documentation and especially the people behind setting up the DocBook environment In particular thanks go out to Alejandro Ramirez Phillipe Vanpeperstraete and Andreas Rueckert Thank you 1 2 About the project ArgoUML is an open source project so it depends on people that volunteer to work on it Especially in the area of development there is still so much to do This Cookbook is dedicated to everyone interested in taking part in the ArgoUML project as such and should help to transfer the knowledge from the old experts to them Please feel free to send more questions and or answers to the dev mailing list mailto dev argouml tigris org 1 3 How to contribute You can help there are big tasks and small tasks waiting for you Here is a suggestion on how you could become part of the ArgoUML Project This could be perceived as a ladder to climb but remember that if so it is firstly a ladder of levels of commitment and time spent by you You get no prize for climbing higher you just get more responsibility in the project 1 Use ArgoUML 2 Report found bugs 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 the
63. See details on where to find the result in Section 2 5 The JUnit test cases If the tests did not pass See Section 2 8 1 The release did not work 23 Building from source 10 i Sign all jar files Test the release manually The purpose of this is to make sure that there isn t any problem introduced by the release procedure and that the jar files contains the correct list of jars Start using the command cd VERSION_X Y Z F argouml build java jar argouml jar cd EEE and do some ad hoc testing Set the release tag The following command will do it for you cd VERSION_X Y Z_F for proj in do cd Sproj amp amp cvs tag VERSION_X_Y_Z done cd Run the script argouml tools bin pack release sh This will Create the files ArgoUML VERSION libs tar gz ArgoUML VERSION libs zip ArgoUML VERSION modules tar gz ArgoUML VERSION modules zip ArgoUML VERSION srce tar gz ArgoUML VERSION src zip ArgoUML VER SION app tgz ArgoUML VERSION tar gz ArgoUML VERSION zip and in dex html There should also be a subdirectory argouml argouml VERSION jws with jar and jnlp files Copy the files in place in the svn directory A tree with all files is located in argouml version It is copied to svn argouml downloads trunk www Commit the release in the SVN download project The commands you would do for this are cd svn argouml downloads trunk www svn ad
64. 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 Do the following 1 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 The list of all RESOLVED FIXED and RESOLVED WORKSFORME issues http argoumL tigris org issues buglist cgi component argoum amp issue_status RESOLVED amp resol ution FIXED amp resolution WORKSFORME 2 Run the specified release of ArgoUML You can also use any later release Use ArgoUML provided for downloads or through Java Web Start 3 Test the problem in the issue and verify that the problem is no longer there or the feature is provided 4 Do one of the following e Ifthe problem is gone the feature is present put the Issue in Status VERIFIED and add the ver sion of the ArgoUML used for the test in in the comment 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 subcompon ent Documentation amp Help e 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 5 If you during th
65. UML meta classes I Jeremy Bennett February 2002 be lieve this code is not yet working so you can probably leave it out You can have multiple calls to this method for different meta classes After this add a method public boolean predicate2 Object dm Designer dsgr This is the de cision routine for the critic dm is the UML entity an NSUML object that is being checked The second argument dsgr is for future development and can be ignored The Critic class conveni ently defines two boolean constants NO_PROBLEM and PROBLEM_FOUND to be returned according to whether the object is OK or triggers the critic dm may be any UML object so the first action is to see if it is an artifact of interest and if not return NO_PROBLEM The remaining code should examine dm and return NO_PROBLEM or PROBLEM_FOUND as appro priate Having written the code you need to add the text for the headline and description to the cognitive re source bundles These are in the package org argouml il8n in the file crit ics properties You need to add two keys for the head and description which will be named respectively critics CrxxxxxYyyyZzzz head and criticsCrxxxxxYyyy2Zzzz desc There are plenty of examples to look at there The other files for British English Spanish respect ively are the responsibility of the corresponding language team Notify the language teams that there is work to be done In method Init of the class org argouml uml cog
66. WARRANTIES INCLU ING 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 package_declaration typecomment S type_declaration 9 7 3 Eclipse to automatically find problems in the code This instruction is to set up Eclipse to automatically find what in the ArgoUML project could be con sidered problems in the code You can apply these individually depending on what level of help you need in your coding I Linus Tolke recommend that you set them all on the Warning level This makes them visible for you You can then decide to fix them or not depending on how you feel about the code you are working with e Compiler compliance level See in the menu Window gt Preferences Then select Java gt Compiler At the right hand side se lect the tab Compliance and classfiles gt Compiler compliance level 1 4 In the ArgoUML project we have decided to keep source compliance to JDK 1 4 See Section 3 3 1 Choice of JRE ArgoUML will support any JRE compatible with a Sun specification of any JRE from Sun that has not begun the Sun End of Life EOL process This setting enables Eclipse to tell
67. a level totally inde pendent of how they are actually linked into ArgoUML Within the ArgoUML project some parts of the code are for different reasons developed and kept separ ate from the main ArgoUML source code These parts can be modules or plug ins on the java level but on the source code level they are called modules This section describes how they are organized and how you create such source code modules 6 3 1 Requirements on modules 97 Extending ArgoUML New modules that are added to ArgoUML shall reside in whole new packages Either you put your mod ule classes in your own domain your package name or if you want to emphasize the con nection to ArgoUML you can use org argouml your package name where your package name is the name of your addition 6 3 2 How do e create a new source code module Suggestion copy from the menutest module as described here Make a copy of argouml modules menutest into argouml modules your name Add any jar you need to argouml modules your name 1ib and add references to each of the jars in argouml modules your name build xml Edit argouml modules your name module properties Edit argouml modules your name src org manifest mf Reorganize the source files as necessary Remove the directory argouml modules your name src org argouml ui and create your own classes like org argouml your package name inargouml modules your name src org argouml your package name e get
68. a prams oro eeo eno Eee hE E EE ES EEE E S occas EN E REE Ee 49 5 3 1 Multi editor pane rererere neresi eani PEE OEE S i TE EEEE STREET e 49 5 3 2 How do I add a new element to a diagram oes eeeeee ee eeeeeee eens 31 9 3 3 How to add a new Fig sco sseos seii eiieeii ee pa n EE eTa 51 5 4 Property panels si ssseiseirsps cc dstuves cosenceedoseweeeostanesesstaveus ESEE ENE EEPOSE IENNE ESSIE EES 53 5 4 1 Adding the property panel si is rciris ioter deadsscsnesassoteaaseedeaesseys 54 Did PELSISLENCE senesne en cous ea a E E EE e E NE E EEAS 67 5 6 Reverse Engineering Subsystem ssessssssrsseesrreresrerrsrrerrsresrrrrerrrrrsrrerrererreees 68 5 7 Code Generation Subsystem rrene ea p a p ean Ep SERR E E Epi 68 5 8 Java Code generations and Reverse Engineering sesesssrrersrrerrsrerrrrrerrerrerre 69 5 8 1 HOW COD ssid os cdusn Si coopaet has desuancdac edt bongs e a aa tobrreas S Mactteesht 69 5 8 2 Which sources are involved 10 0 0 eee cee cee ceeeceeece teen teen eeea eens eeaeeas 69 5 8 3 How is the grammar of the target language implemented 0 69 5 8 4 Which model diagram elements are generated 0c cesses ee eeee eee ee 69 5 8 5 Which layout algorithm is used 0 0 0 0 cee eeeceeeceeece teen seca een eeue eens 69 5 9 Other languages 6 53 co5 oss ie cecds ve puokece inte ces ta eee ousle TEER ESEESE REE ESEE tenons 72 9 10 The GU Mas reren ageecdntins gab oten oes
69. a purpose in the project If you don t want to acquire a Tigris login to do this you can use the guest account with the password guest Since the checked out copy remembers the login you used to do the check out if you do this you will have to remember to delete this copy and start over if you get a developer role in the project and want to do commits directly 2 4 Build Process The ArgoUML build process is driven by Apache Ant and it is highly recommend that you stick to that There are people known to build from Eclipse and NetBeans but always make sure that your work com piles with the plain vanilla build process There are also some Java files generated by magic scripts in Ant that you need to create before opening with the IDE Ant is a tool written in Java developed for Apache that reads an XML file with rules telling what to compile to what result and what files to include in what jar file The rule file is named build xml There is one of those in every separate build directory src_new src whatever documentation andmodules whatever 2 4 1 How ANT is run from the ArgoUML development environment For your convenience the ant tool of the correct version is present in the CVS repository of ArgoUML in the file argouml tools ant 1 4 1 lib ant jar Normally ant is started with the command tools ant 1 4 1 bin ant arg and in the modules tools ant 1 4 1 bin ant arg On windows the command tools ant 1 4 1 bin ant a
70. act that by necessity the different persons working with internationalization have different native languages and that complicates the communications To handle this problem for GNU applications there is a community set up around gettext with one lan guage team per language working with all gettext applications There are also tools to help the trans lator do his job delivered with gettext that are the same for all the applications In each of these lan guage teams discussions are held that ensure a consistent use of words over all these applications It is for me Linus Tolke May 2002 unclear if and how such a community exists for Open Source Java tools and ArgoUML cannot simply benefit from the gettext communities since we don t use gettext and cannot use the same tools To get things done we organize our own Language Teams for ArgoUML Each language team is actu ally just one or several persons that know that language and are eager to work with translating ArgoUML The language team has the following responsibilities 1 Constitute the foundation of the ArgoUML community for that language 2 Tranlate all localized strings and resources This is a constant work with keeping up with the changes that will be made to the ArgoUML code and ArgoUML modules since ArgoUML is under fast development 3 The terminology used shall be correct This requires work in keeping up with the current literature in the domain
71. 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 11 Make announcements Add the index file to the directory argouml www download so that it will show up at the URL http argoumL tigris org download release 01234 5 html http argoum tigris org download releaseX XX html Add new file to the File Sharing area under the correct release Since a release is made the Status of the files is Baselined Use the URL added in the previous paragraph as Link Write a News announcement in the argouml project The announcement shall include a statement on what kind of release this is information on what major things that have changed for stable re leases this is a list of what has changed since the last stable release It could also include the list of resolved issues a list of serious known problems with this release stable releases shouldn t have any technical details on how the release was built and the plan for the following release Write a short note on the users list for development releases and announce lists for stable re leases or major breakthroughs Include the link to the new item Freshmeat currently Thierry Lach does the Freshmeat announcements which require a login so just infor
72. and store them in argouml language code src org argouml il8n They will have names like action_language code properties button_language code properties checkbox_language code properties combobox_language code properties When this is done the first iteration of the Tool translation is completed The work will probably be more maintenance like from here on Join an existing Language Team Discuss with the Language Team in question by mailing the members They will hopefully have work prepared for you and greet you with open arms add or modify code with localized things This is only applicable for developers working with the ArgoUML Java source or some argouml module 1 Everywhere the user would see a string in the GUI you should localize a key This means that instead of writing a string you write a call to a localizer method with a key label or tag as argument and the localizer method finds the resolution of the key is in one of the property files You select one of the files for you key and name the key accordingly The key is a String The key has a special syntax like this 77 Inside the subsystems wordl word2 word3 where word is the same as the first part of the filename that the key resides in Example The key action about argouml resides in the files action properties and action_lan guage code properties You will have to call the class org argouml il8n Translator to convert t
73. andleEvent up dates the property in UMLTextProperty 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 JOptionPane 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 The implementation of FocusListener 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 FocusListener it would not be possible to enter class diagram since handleEvent would pop up a warning message box The method update updates both the actual JText field as the diagram as soon as some property is set The updating of the diagram is done by calling the damage method of the figs that represent the property on the diagram 5 5 Persistence Purpose To package and unpackage the persistence data from different subsystems to and from some storage medium The Persistence subsystem is located in org argouml persistence Currently the storage medium is a flat file uml xml format or a zipped file zargo zip format During save the persistence subsystem requests each subsystem for its persistence data and adds that 67 Inside the subsystems data to output it i
74. ass 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 Ist one etc Example 69 Inside the subsystems F ank 0 F ank 1 F ank 2 In the next diagram a link goes to an object that is not in the row above Rank Q0 Rank 1 Rank 2 In this case insert virtual objects which are linked to the actual target and link to them 70 Inside the subsystems Rank 0 Rank 1 Rank 2 The objects are sorted within their row then to minimize crossing links between them Compute the av erage 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 ABC rank 0 DEF rank 1 We give the super classes an index in their rank assuming that they are already sorted A 0 B 1 C 2 D E F have the following links A B C could be interfaces so I allow links to multiple super classes here D gt C E gt A and C F gt A and B Compute the average value of the indexes D 2 C has index 2 1 link E 0 2 2 1 A 0 C 2 divide by 2 links F 0 1 2 0 5 A 0 B 1 2 links 71 Inside the subsystems Then sort the
75. avaWebStart they can be downloaded from the site 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 guaran tee that it is available e The scope of the modules Modules are always enabled and disabled on a per application per jvm basis and not on a per project or per frame basis 5 19 OCL Purpose To allow for editing of strings in the OCL language The OCL is located in org argouml ocl The OCL is a Layer 3 subsystem See Section 4 6 Loadable subsystems The OCL editor GUI interface is org argouml uml ui TabConstraints shown in the bottom right hand panel details panel org argouml ocl ArgoFacade adapts the tudresden ocl gui OCLEditor for ArgoUML There are some other helper classes in org argouml ocl 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 ArgoFacade is reused by GeneratorJava and TabConstraints 88 Inside the subsystems Currently this subsystem is more
76. available rules Status not implemented 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 The APIs collectively represent the Explorer subsystem facade and the SPIs represent plug ins 5 17 3 Details of the Explorer Implementation The Explorer is currently shown in the Explorer Pane org argouml ui NavigatorPane the 84 Inside the subsystems upper left hand pane of ArgoUML Except for the Explorer Pane The Explorer is located in org argouml ui explorer The explorer has been refactored since version 0 15 2 so that it has a slightly more standard Java Swing implementation The explorer perspectives provide the different views of the project They are implemented by sets of PerspectiveRules that get the child nodes for any parent node in the tree JTree eH Intert PropertyChangeSupport aS See cee DefaultMutableTreeModel PropertyChangeListene ExplorerTree z A x fy a 4 a j j 1 A L lt lt interfaces gt lt H 4explorerTreeModel DefaultMutableTreeNodel ExplorerNSUMLEventAdaptoy ExplorerEventAdaptor Bs TreeModellUMLEventListene lt lt Interface gt lt lt Interface gt gt Comparable Comparator a ExplorerTreeNode 777 77 77 4 f Spaa UmIModelEventPump The Explorer
77. ave the general name YYYYDiagramGraphModel java where YYYY is the diagram name in bumpy caps For example the use case diagram graph model is in uml dia gram use_case UseCaseDiagramGraphModel java The graph model is defined as UMLMutableGraphSupport a child of the GEF class Mutable GraphSupport and should implement Mut ableGraphModel GEF 5 3 3 3 Changing the renderer The renderer is responsible for creating graphic figs as required on the diagram It is found in the same directory of the corresponding diagram class and has the general name YYYYDiagramRender er java where YYYY is the diagram name in bumpy caps For example the use case diagram graph model is in uml diagram use_case ui UseCaseDiagramRenderer java This provides two routines getFigNodeFor which provides a fig object to represent a given NSUML node object and getFigEdgeFor which provides a fig object to represent a given NSUML edge object In our example we must extend getFigEdgeFor so it can handle NSUML MExtend objects producing a FigExtend 5 3 3 4 Creating a new Fig explanation 1 New objects that are to appear on a diagram will require new Fig classes to represent them In our ex ample we have created FigExtend They are placed in the same directory as the diagram that uses them The implementation must provide constructors for both a generic fig and one representing a specific NSUML object It should provide a setFig method t
78. bes uae pasa wen E A E EEE 83 5 17 1 REQUITEMENES ssn irois bebe usec ieee iae ieee e a E i osai 83 5 7 2 Public APIs and SPIS peier ae a es on EEE EEE EES 84 5 17 3 Details of the Explorer Implementation 00 ceee nee eeeeeeeeeeeeee 84 DTA HOW dO E sose sdscdes aes coin EE ash sbivta nf sadadeas sooieageresmeeueeys 85 5 18 Module Loader visn ehh scat nek as oat Doce cose eV cab iaigy Cadeaa eee E EEE RE a i 86 5 18 1 What the ModuleLoader does 0 00 cece cece eee ceee cece eeeeeeeneeea esau eens eeaes 87 5 18 2 Design of the new Module Loader eee cee ceee cence eeca teen seen eeaes 87 DOP OC Daag eect Seek oc alee Muster eat eas E eedvbek wa eedeean sheen mk tsetse le gs 88 6 Extending ATUM onere hac sanseseaaesesuadesscuetdas dau ngaee ayes tae aibegtes a ae A ES 90 Oo HOW dO Les aseeie ki tei ts delle a Goa ate sek eae R REE NS 90 6 2 Modules and PLUGIN 2 020 suwecedsynesesoysuedesey soe sbopetudestes OEE Svar ssheSedebehswenusenteders 90 6 2 1 Differences between modules and plugins cece eee eeeeeeeneee eens 90 6 2 2 MOdUIES sisisi riire o eeina Sneed eases ssabensiataettiesss bandas eemees SE 91 6 2 3 PIMSINS esiseina Tose tee beat Gee ES EE E AEOS TEE eecventieeceesetevens 94 6 2 4 Tip for creating new modules from Florent de Lamotte eeeeceeeeeneeee 97 6 3 How are modules organized in the java code 20 0 ceee eee ceee ce eeca tena een eeneees 97 6 3 1 Requirem
79. check out ArgoUML be cause many things in Argo relate to GEF and it is quite handy to have the source code available GEF is also residing at Tigris so you can do a simple cvs d user cvs tigris org cvs co gef with the same checkout arguments you had when you checked out ArgoUML to get it e The OCL package to parse and run the Object Constraint Language things Details about the package are available from SourceForge OCL Compiler http dresden ocl sourceforge net e log4j a library with infrastructure for logs e antlrall the run time part of the ANTLR tool 2 3 Download from the CVS repository The CVS repository at Tigris is accessible using the pserver protocol The CVS root is cvs at cvs tigris org You use your Tigris login and Tigris password The first thing you will need to do is select the CVS client Most of the description below is about the command line CVS tool which is available for most operating systems Whatever tool you use do not checkout into a directory that contains spaces in a directory name some where in the path E g c Documents and Settings My Documents Java Devel opment violates this advise 3 times Reason You can not build the documentation BTW Building ArgoUML itself works In case you use the command line CVS client the above means that you will set the CVSROOT variable to pserver login cvs tigris org cvs where login is your Tigris login This needs to be done before the first c
80. d argouml VERSION svn commit m Upload the release VERSION Go through Issuezilla and check things Things to check are a That there is a Version created in Issuezilla for the newly created release 24 Building from source The purpose of this is to make it possible for everyone to report bugs on the new release b 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 c Change the target milestones of all the not yet resolved issues for this release to d Change the target milestones of any fixed issue in component argouml with target milestone to that of the current release This is probably some developer that has fixed an issue by forgot to set the target milestone correctly e Move all issues reported on current to this release for the component argouml 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 f Reopen RESOLVED REMIND This can also be a good time to change all RESOLVED REMIND Search for them and Re open them g Check RESOLVED LATER It could
81. d in Argo Module which Pluggable extends see Section 6 2 2 2 The ArgoModule interface used in the old implementation the interface provides the following method boolean inContext Object context inContext allows a plug in to decide if it is available under a specific context One example of a plugin with multiple criteria is the PluggableMenu PluggableMenu requires the first context to be a JMenultem which wants the PluggableMenu attached to as the context so that it can de termine that it would attach to a menu The second context is an internal non localized description of the menu such as File or View so that the plugin can further decide 6 2 3 2 How do e create a pluggable settings tab e create a pluggable menu item Look at the modules junit and menutest for examples of how to add to menus using the Pluggable Menu interface The implementation of inContext that you provide should be similar to public boolean inContext Object o if o length lt 2 return false if o 0 instanceof JMenuItem amp amp Create Diagrams equals o 1 return true return false The string Create Diagrams is a non localized key string passed in ProjectLoader at about line 440 in the statement appendPluggableMenus _createDiagrams Create Diagrams There is no restriction on a single class implementing multiple plugins quite the contrary that is 94 Extending ArgoUML
82. d this list will probably grow e SVN access to the argouml downloads project to upload the result e A machine This is probably the machine you use for your development if you are an argoum developer The machine needs Internet access it is not a small download and upload so at least 128KB Internet connection to keep the time reasonable lt 2 hours the correct version of Java installed should be a JDK 1 4 2 CVS and SVN installed Unix or Cygwin to be able to run the scripts e That you have set the CVSROOT correctly Make sure it is set to pserver user cvs tigris org cvs Here are the steps to be done when one actually does a release 1 Set the argo core version to not include the PRE part This is done in the default properties file in src_new and documentation and then commit the files 2 Tag the CVS repository with the freeze tag 21 Building from source Normally this tag is VERSION_X_Y_Z_F e g VERSION_0_9_7_F The according command line CVS command is evs rtag VERSION_X_Y_Z_F argouml Note ce Because of a problem on the Tigris site this doesn t work The workaround is that you make sure you have a complete checked out and copy of ArgoUML go to the root directory argoum1 and run the command evs tag VERSION_x Y z F You also need to set the tag in the sub projects so the following command is more like it for proj in argouml argouml csharp argouml nb argouml il8n zh do cd Sproj amp a
83. date 1 minute compile 1 minute This amounts to 10 hours wait and 1 5 hours extra work for all developers in the project 8 2 Creating and using branches We use the following standards in ArgoUML e Released versions get the tag VERSTION_X_X_X e 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 work_explanation_owner where e work is a literal e explanation is something like javahelp propertypanel cppcodegeneration e owner is a self explaining code for the owner of the branch e g tlach Thierry Lach or mkl Markus Klink Merging branches together is causing some work So please use them sparingly and announce your in tentions before on the mailing list 1 How dol e commit stuff You have made the change tested it and are satisfied with it Do a cys update d and see that only the files you have changed are marked as modified If files are updated or patched by this command please recompile and test again Do a evs diff on each of the files and verify that only the lines you have changed are modified Do a single cvs commit for all the files included in the change This reduces the risk that someone else updates in the middle of your work and also reduces the amount of notifications of commits sent out Include changes to documentation and JUnit tests if applicable
84. dex public void delete int index public void moveUp int index public void moveDown int index Perform the actions associated with the add pop up menu on the element at the given index There is no default provided so this must be given if the add operation is supported The ad dAtUtil method see below may prove helpful In this routine you may create a new NSUML entity There seem to be three ways to do this in order of preference 1 use a utility from the MMUtil class 2 use the NSUML Factory class to cre ate what you want 3 use new on a MXXXImp1 class Whilst 1 is best most of the MMUt i 1 routines are not yet general enough Be sure to set it up don t forget e g namespace etc Remember also to change anything that references the newly created entity p Warning The NSUML routines generally set up the other end of a relationship automatically if you set up one end If you try to do both on a NxM relationship you will probably end up doing it twice If you do encounter this the rule of thumb is to explicitly set the ordered end if you do it the other way round NSUML will assume you mean the other end to be at the end of its ordered list Perform the actions associated with the delete pop up menu on the element at the given index There is no default provided so this must be given if the delete operation is supported Perform the actions associated with the
85. e The script is located here and the JimiProClasses zip is taken from this in stallation so if you can build the PDF documentation correctly in this a lot is gained e somedirectory FREEZETAG the created that will be created where the whole build will take place e svn argouml downloads trunk www where the files to be uploaded will go Notice that this is starts one step up on the same level as somedirectory It will be accessed using a path like svn argouml downloads trunk www This is achieved using the following commands Cd lt svn co N http argouml downloads tigris org svn argouml downloads This will a Check out the source in a new directory The new directory is named after the freeze tag that you have set Make the ant executable Build the core ArgoUML This is done in the argouml src_new directory of the newly created copy by using the package ant target Build the sub projects and modules to be included in the release Download docboox xsl This is normally done using the docbook xsl get ant target Copy the file JimiProClasses zip This is done automatically from the working copy you have alongside If not you will be asked to copy this in manually Jimi is downloaded separately See Jimi Build the PDF documentation Run through the automatic tests This is done by issuing the command build alltests in the argouml1 src_new directory There should not be any failed tests
86. e argument 5 14 2 How to Create Log Entries You should not use System out printin in ArgoUML Java Code The only exception of this rule is for output in non GUI mode like to print the usage message in Main java To make log entries from within your own classes you just need to follow the three steps below 1 Import the org apache log4j Logger class 2 Geta Logger 3 Start Logging 79 Inside the subsystems Example 5 2 For log4j version 1 2 x import org apache log4j Logger public class theClass private static final Logger LOG Logger getLogger theClass class public void anExample LOG debug This is a debug message LOG info This is a info message LOG warn This is a warning LOG error This is an error LOoG fatal This is fatal The program stops now working Notice that we in the ArgoUML project have decided to have all loggers private static final with a static initializer The reason for making them private is that this reduces the coupling between classes i e there is no risk that one class uses some other class Logger to do logging The reason for making them static is that our classes are more or less all either lightweight like a representation of an object in the model or a singleton For the lightweight classes having a reference to a logger object per object is a burden and for the singleton objects it doesn t care if the logger is static or not T
87. e 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 follow that 2 1 Quick Start If you are using Eclipse 3 0 or later see Section 9 7 How to work with Eclipse 3 for quick setup in structions If you are using Windows the follow commands will build ArgoUML from source and run it If you us ing Unix Linux the comparable commands modified slightly for your particular shell will do work Work gt set CVSROOT pserver guest cvs tigris org cvs Work gt cvs login use guest as password Work gt cvs checkout argouml srce argouml src_new argouml tools argouml lib Work gt set JAVA_HOME C Programs jdkwhatever Work gt cd argouml src_new G Cc Cc C Cc C Work argouml src_new gt build run After a couple of minutes the newly compiled ArgoUML will open in a new window Notes F Tip JDK 1 4 or later is required Tip E On Windows the directory path for the JDK installation directory must not contain any spaces That was the compact version for Windows JDK Note JDK cannot be installed in a directory that contains space in its name Modifying these steps slightly as appropriate for your shell should work on Unix Linux systems as well If you don t understand these instructions or they don t work please read the rest of the chapter for more d
88. e each of the missing files The Unknown files are scheduled to be added by cvs add each of the added files This removing of missing files and adding of unknown files may seem backward but it is from the perspective of CVS The missing files are the ones that were present in the previous version of the documentation and do not have a replacement either because that chapter does not exist anymore or that the tool generates filenames differently The Unknown files are files with filenames that for the same reason appear from one version of the documentation to the next 6 Commit the changes thus publishing it on the web site cvs commit m New version of the documentation published 7 The PDF book is uploaded to the download page 2 3 How we work with documentation The developers or authors that work with the documentation or with the tools to generate the document ation or anyone else interested in how it works can generate the documentation like described above and examine the result in argoum1 build It is only the last part about checking in and uploading the result under argouml www documentation that requires write access in the CVS and some con figuration management since it more or less is releasing the manual In order to do this you need to check out the whole of the argouml document ation directory You also need the directory argouml 1lib and argouml1 tools that contain the tools used Ant FOP Saxon The subdirec
89. e in your listener 2 When you implement your listener it is wise to NOT DO the following propertyChanged MElementEvent event do my thing for event type 1 do my thing for event type 2 ete This will cause the things that need to be done for event type 1 to be fired when event type 2 do ar rive This still happens at a lot of places in the code of ArgoUML most notably in the modelChanged method of the children of FigEdgeModelElement 5 1 3 4 Possible investigation points and improvements Should we use our own event types Should we replace the MElement Listener with PropertyChangeListener and MElemen tEvent with PropertyChangeEvent One reason we havn t done so yet is that it involves a lot of work and testing Change the implementation of the Event pump itself Not the API but the implementation 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 Use the standard data structure that Swing uses for event registration ie javax swing EventListenerList Would this be an improvement 41 5 1 4 5 1 5 Inside the subsystems NSUML specifics This is currently implemented using NSUML internally to implement the UML model The plan is to re place NSUML with some JMI compliant model instead probably MDR and for that reason all APIs to the Model subsystem using NSUML objects are
90. e modules If you want to run ArgoUML with modules enabled the build xm1s are set up to do this in two ways 1 Test just one module a Build ArgoUML the package This is done with ant package in the argouml src_new directory b Run the module This is done with ant run command in the argouml1 modules whatever directory 2 Test several modules together a Build ArgoUML the package This is done with ant package in the argouml src_new directory b Compile and install the modules This is done with ant install command in each of the argouml modules whatever directories c Start ArgoUML This is done with ant run in the argouml src_new directory This will start ArgoUML with all modules available 2 4 2 Developing in a subproject This describes how to do development in one of the ArgoUML sub projects If you are in a hurry C Work gt mkdir argouml build Download and unpack the latest release of ArgoUML into this directory C Work gt set CVSROOT pserver guest cvs tigris org cvs C Work gt cvs login use guest as password 10 Building from source Work gt cvs checkout argouml XX Work gt set JAVA_HOME C Programs jdkwhatever Work gt cd argouml XX C C C Work argouml XxX gt ant run An ArgoUML starts with the module from the subproject argouml XX enabled That was the short version provided that you are using Windows JDK you have ant installed and the subproject in question doe
91. e readme files licenses and other distribution files stored in this directory in much the same way as the libraries in 1 ib 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 li cense LGPL GPL Freeware are OK WWW This is all the static contents of the web site See Section 2 7 1 How the ArgoUML web site works The ArgoUML subprojects are projects on Tigris that belong to the ArgoUML project To simplify the administration they are all set up in a similar way and also similar to the src and modules directories This is what their cvs repository looks like e build xml The file controlling the build of that subsystem When built the result end up in a newly created build directory e lib optional jar files with products shipped with the module in that subproject 4 Src The source code e tests optional The JUnit test cases for that subproject e tools optional Any special tools needed to build that subproject The tools from the argouml tools directory can also be used so this is just the new ones be WWW The web pages for that subproject 111 Chapter 9 Standards for coding in ArgoUML 9 1 Rules for writing Java code The coding style for ArgoUML is the following e Each file starts with some header info
92. e sub product is distributed in a set of jar files add the jar files to the list of files that are to be included when releasing ArgoUML One place in build xml target dist javawebstart One place in manifest template Class Path In each of the Java Web Start files resources In the Info plist ClassPath Check by having some class from the sub product loaded immediately when starting ArgoUML and start with java jar argouml jar using each of the Java Web Start files and from the Appbund on a Mac See Section 12 8 How to relate issues to problems in subproducts for a discussion on how to handle bugs found in sub products and updates of the version of a sub product 9 4 Settings for Eclipse 2 Linus Tolke These style guides correspond to the following settings in Eclipse 2 117 Standards for coding in ArgoUML e In Preferences gt Java gt Code Formatter gt New Lines None of the boxes Insert a new line before opening brace Insert new lines in control statements Clear all blank lines Insert new line between else if or Insert a new line inside an empty block are checked e In Preferences gt Java gt Code Formatter gt Line Splitting Maximum line length is 80 e In Preferences gt Java gt Code Formatter gt Style None of the boxes Compact assignment or Indentation is represented by a tab are checked Number of spaces representing a tab 4 This should probably be read a
93. eMode 1 is t rue to consider all the elements in the standard profile model for inclusion so the Java types standard stereotypes etc For our PropPanelExtend we provide a predicate routine the call for the base field is UMLComboBoxModel this isAcceptableUseCase base getBase set Base true MUseCase class true GI fi and we define the methods isAcceptableUseCase getBase and set Base in PropPanell tend 5 4 1 6 How UMLTextField works This information is provided by Jaap Branderhorst September 2002 UMLTextField implements several kinds of event listeners e MMelementListener e DocumentListener e FocusListener Furthermore it is a UMLUserInterfaceComponent Since it is an UMLUserInterfaceComponent it must implement targetChanged and tar getReasserted TargetChanged is called every time the UMLTextField is selected tar getReasserted is of no interest for UMLTextField It plays a role in keeping history but since history is not really implemented at the moment in ArgoUML it is of no interest target Changed 66 Inside the subsystems does two things e It calls the targetChanged method of the UMLTextProperty this UMLText field is show ing e It calls the update method The update method is described further on Besides UMLUserInterfaceComponent there are several other interfaces of interest One of them is MMElement Listener Every time a MModelEle
94. eases two stable releases and if we all are happy with it then remove the old module loader Design e We use a Loadable Proxy Pattern for the modules e Each module can be enabled and disabled individually Dependencies between modules is allowed although not yet handled gracefully e Each module is required to have one 1 class that implements ModuleInterface 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 e The modules are allowed to use all the APIs available from all the subsystems within ArgoUML and from other modules This is a big improvement over the old module loader in that e 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 e We can have the module have different classes to register at different parts of ArgoUML e We can have dynamic registrations that the module add and remove over time depending on some criteria that the module decides e We don t need to search through all modules at every possible point where ArgoUML can be augmented 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 87
95. eb site the responsible docu ment release person does the following 1 He checks out everything needed and a copy of the argoum1 www If wanted the CVS repository could be tagged and then the tag can be checked out This makes it possible to know exactly how a certain version of the documentation was generated The documentation is generated using build docs This generates all three books and the result appears in argouml build documentation defaulthtml book 3 argouml build documentation printablehtml book and argouml1 build documentation pdf book This has been done several times before while preparing the release so no problems are expected If there are problems then the preparations were not good enough and the process is best stopped right here 3 All the old files are removed from the checked out copy of argouml www documentation defaulthtml book g argouml www documentation printablehtml book 4 New files are copied into the checked out copy of www on top of the previous files there replacing them All the files are copied from argouml build documentation defaulthtml book to argouml www documentation defaulthtml book The same for printablehtml and pdf 5 No longer used files in argouml www documentation are removed from CVS and new files are added cvs n update 19 Building from source Watch for Missing and Unknown files The missing files are scheduled to be removed by cvs remov
96. ecoieba ste hess otis les Mas E EEEE 30 4 ArsoUML Design The Big Picture c025 sscc0 ss essias sboctadssateages stovessessaaghsetiveadestsoensess 31 4 1 Definition of subsystem aene eee REEE A ceca OEN E EEES 31 4 2 Relationship of the subsystems sssessseesereeesresrsrrerrsrrerrrrerrrersrrerrsrrerrereeeese 32 4 3 Low level subsystems se eiennenn dae EEE EA EE IRE EE 33 44 Model subsystems Sree oe E A E E ete ea O A 34 4 5 View and Control subsystems p rossen reene tao SES EEP EEES EENES Eper EErEE 34 4 6 Loadable subsystems eee oe TEE E E TEE AE TE SEE EARE 35 3 Inside the SUBSYSTEMS sisisi n een o a apa E EE E E E E EE 37 Del Model AEE E EEE E EEEE E E EE 37 D Led Factores A E sash devas da ees mncdlss Potebaas otageuesys 38 S L2 Helpers sereni a roae gehores tons E cease AEE EEE EE E ds 38 5 1 3 The mod l eyent PUMP ccros ssie a n E scenes 38 SILA NSUML specifics socieco saone o eE E EEEIEE nET eE ERE 42 5 1 5 How to work against the model 20 0 0 e cece eeceeeea seca eenneeneeeas 42 5 16 HOw doTn sess cas sunksees sethee ds bedhead e wk Soad aah laaeey eR AE ane dee loaeeeeeens 43 5 2 Critics and other cognitive tools 0 0 0 0 eeceeeceeeceeeeeeeceeceeeeeeeeaeeea seen sean eeaes 44 52l Main CLASSES one eo a hve eatage setter Sousa tis a A E E aE Some E Aoa 44 AA OW Le 252 E E A E shabseiet at yeety 46 5 2 3 org argouml cognitive critics class diagram eeseessererreresrerrrsresrreees 48 5 3 Dl
97. ect makes certain decisions tions on how to do the chores around maintenance build a re lease publish a release build the documentation part of the release test ArgoUML test the docu mentation Agreed project rules like what level of quality is aimed for and description of pro cesses that achieves that level Web in CVS site Everyone i e de velopers in the project users of the product people searching for UML tools for the purpose of trying testing evaluating and using the tools Be an entry point for the other parts of the documentation Be the main download area for the ArgoUML product Be the central point of the ArgoUML user com munity Be the central point of the ArgoUML development project References to all the other parts of the documentation Current project information like the con tents of the upcoming releases and the plan for the nearest future Easy access illustration for users to be Some illustrations that do not work well in the other parts of the documentation This is done as a complement to the other parts Examples tours Manual and quick guide Users of ArgoUML Persons that want to evaluate ArgoUML for the purpose of starting to use it Per sons that are training to use UML and ArgoUML Describe how ArgoUML is in stalled and used Describe how UML is used with ArgoUML Complete installation instructions for all supported installation schemes
98. ects 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 in terfaces is argouml itself so this distinction is mostly formal There are two ways to get the argouml in place w r t your module The ArgoUML source way and the quicker ArgoUML distribution way Using the ArgoUML source way you check out the argouml project alongside the subproject you are go ing 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 up date and rebuild the argouml project regularly Using the ArgoUML distribution way you check out only your module and then download the 11 Building from source ArgoUML distribution and work against that This is the approach described in the beginning of this section You will need to download and replace the ArgoUML distribution whenever you need a newer version to work against You could also at any point upgrade to the ArgoUML source way to get to the bleeding edge The build xml ant configuration file in the subproject and the argouml main project are set up to allow for both of these ways 2 4 2 2 Workin
99. eeecaeeeeaeeneras 134 12 5 How to verify an Issue that is FIXED 200 00 eee cece ce ee eens ce eeeeeeeeeeeeees 136 12 6 How to verify an Issue that is rejected 10 0 0 ee cece cece eee eeee ne eeneeeneeeeeeeeees 136 12 7 HOW to Close an Isse sesa ani a ERE E E EE ETER DEEE des poses 137 12 8 How to relate issues to problems in subproducts se eseesseseesrerrsreerrerrerrereeee 137 MAER eioan aaa T a E T EA E E E EE 139 vii Change Log This will also be a log of major design decisions A major design decision is a decision that changes re sponsibilities or functions of the subsystems Table 1 Changes done When What Who 2005 07 22 Removed the modules junit See Section 2 8 Making a release Linus Tolke 2005 07 19 Change to the descriptions of the Model Diagrams and Persistence Linus Tolke subsystems See Section 5 1 Model Section 5 3 Diagrams and Section 5 5 Persistence a Design decision Bob Tarling ed a 2005 07 14 The Diagrams subsystem does not store any data All data it works on is stored in the Model subsystem 2005 07 18 Change to the short list of subsystems and responsibilities See Linus Tolke Chapter 5 Inside the subsystems 2005 06 18 Restructured all main chapters are now in seperate files No content Michiel van der changes Wulp 2005 06 15 Change to how internationalization is done Subprojects See Sec Linus Tolke tion 5 13 Internatio
100. eel like you really want to use a method that is deprecated instead of the replace ment 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 devel opment team Comment There is an ongoing work probably perpetually to change the calls to deprecated meth ods 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 actu ally trying to upgrade the sub tool See Section 12 8 How to relate issues to problems in sub products Don t use very long package and class names To make the code readable keep class names shorter than 25 chars and have at most four levels of packages 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 org argouml model uml behavioralelements collaborations class name and org argouml uml ui behavior common_behavior class name While establishing the subsystems we use a two level ap
101. elp As follows 1 A tooltip that explains the data and format expected by the particular field This can be omitted when there is a header stating the data of the field and the format is obvious 2 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 in teraction with the popup dragging scrolling or closing REQ4 REVa Rationale Throughout a complex application like ArgoUML there are lots of text fields Unless there is a possibility to always get this kind of help the user might not be able to make out what he is actually supposed to do in that field Stakeholder User of ArgoUML 3 2 Requirements for UML 3 2 1 ArgoUML shall be a correct implementation of the UML 1 3 model REQ5 REVa Rationale The vision of ArgoUML is to provide a tool that helps people work with an UML model The UML model might later on be used in some other tool If the implementation is not correct then ArgoUML will not be compatible with that other tool or the user will be confused There might be a lot of tough decisions when it comes to if it is ArgoUML or some other tool that deviates from the UML 1 3 but there shall never be any doubt that the intention of ArgoUML is to implement UML correctly Stakeholder User of ArgoUML 3 2 2 ArgoUML shall implement everything in the UML 1 3 model REQ6 REVa Rat
102. ending ArgoUML 6 2 2 2 The ArgoModule interface used in the old implementation Each class must derive from the ArgoModule interface This interface provides the following meth ods String getModuleName void String getModuleDescription void String getModuleVersion void String getModuleAuthor void provides information about the ArgoUML module boolean initializeModule void initializeModule is called when the class loader has created the module and before it is ad ded into the modules list init ializeModule should initialize any required data and or attach it self as a listener to ArgoUML actions initializeModule for all modules is invoked after the rest of ArgoUML has been initialized and loaded Any menu modifications or system level resources should already be available when the module initialization process is called initializeModule should return true if the initialization is successful or if no initialization is necessary The only available mechanism for handling dependencies between modules is the order in which they are read from the file void shutdownModule void The shut downModule method is called when the module is removed It provides each module the capability to clean up or save any required information before being cleared from memory void setModuleEnabled boolean tf boolean isModuleEnabled void Reserved for future implementation Vector getModulePopUpActions void Reserved
103. ent but there might be other languages like C in the future With this concept you could mix several lan guages within a project The DiagramInterface is used to visualize generated NSUML meta model ob jects then 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 5 8 3 How is the grammar of the target language imple mented It s an Antlr http www antlr org http www antlr org grammar based on the Antlr Java parser ex ample The main difference is the missing AST Abstract Syntax Tree generation and tree parser So the original example generates an AST a treelike data structure and then traverses this tree while the ArgoUML code parses the source file and generates NSUML 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 5 8 4 Which model diagram elements are generated The context classes hold the current context for a package class etc When the required information for an object is available the corresponding NSUML object is created and passed to the DiagramInterface to visualize it 5 8 5 Which layout algorithm is used 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 cl
104. ents on modules scies sisese rri esre eeu eees 97 0 3 2 HOW do Lea re o r oe ks setae tg EEA dass peed ESEE EEEIEE E EENE 98 7 Organization of ArgoUML documentation 2 0 0 0 cee ceeeceee cee ce eceeeeeeeeneeea esau sean eeues 99 TAS OVERVIEW eree Sass doh haces A E we Sua A weg nada bea EE ast ncee daar esounns 99 1 2 User Manual Plans lt cc tec sig siue edie in tate de a atid eee en oad 100 7 2 1 Target Audiences for the User Manual cece ceeeeeeceeeceeeee teen eeenes 101 7 2 2 Goals for the User Manual 0 cece eeece cece ence eee eeceeeeeeeeeeeeeeenees 101 7 2 3 Suggested Manual Structure 0 cece cceeceeece ence eeceeeeeeeeaeeeaeeenes 101 7 2 4 Actions Priorities and Questions cccececceceeeeceeeeeeeeeeeeeeeeneaeenenes 103 8 CVS in the ArgoUML projects iscsicss cagsss ssensigshetisessseros cess cee ses ssoban ga E SEEE E EPPES TORES 104 8 1 How to work against the CVS repository 2 0 0 0 eee cence ne ce ence eeeeeeeeeeenees 104 8 2 Creating and using branches cece cece eitea pena o aE s e 105 8 3 Other CVS comments sccesccsveeecsssee sterenn EErEE E ENNE EESO VENN edssspyeenessaeeersonneye 107 8 4 CVS repository contents 35 5 5 55 ss soos sss eesosa nE SEEE paesa SPESE Spa KE SEE 108 9 Standards for coding in ArgoUML 20 0 cece cee ce ee ceeeceeeea ceca eens cena eeueeeneeeenees 112 9 1 Rules for writing Java coder istono aen r r E rE N Nn 112 9
105. ere 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 101 Organization of ArgoUML documentation I Jeremy Bennet 2002 suggest that the tutorial book be based around an OOA amp D process any pref erences and that each UML concept is introduced with each step of the process followed by an explan ation of how to do it under ArgoUML A simplecase study will be needed throughout 7 2 3 1 Tutorial Manual Structure 1 Introduction a b d Origins and overview of ArgoUML Scope of the User Manual Include cross reference to other documentation Cookbook FAQ Quick Guide on line help ArgoUML website etc Overview of the User Manual Explains that ArgoUML will be explained in the context of an OOA amp D process and with an example running through Assumptions At this stage assume the user knows OOA amp D but not UML 2 UML Based OOA amp D e Background to UML what it is history etc UML based processes for OOA amp D ArgoUML Basics projects drawing exploring details What ArgoUML has that other tools are missing critics to do list based in cognitive psycho logy theory The Case Study 3 Requirements Capture a Use Case Diagrams this section will be relatively large because its the first time we use ArgoUML to create
106. estStatics compileTestConstructors and compileTestMethods that was thought to include correct calls to all static methods all public constructors and all other public methods that are not otherwise tested These methods are never called They serve as a guarantee that the public interface of a class will never lose any of the functionality provided by its signature in an uncontrolled way in just the same way as the test methods serve as a guarantee that no features will ever be lost true true UMLAction NO_ICO Functions never actually called Provided in order to make sure that the static interface has not changed 15 Building from source 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 2 6 Manual Test Cases 2 6 1 2 6 2 The manual test cases are here to help us test ArgoUML in order to cover things that are not testable with the JUnit test cases Since it is a little bit more cumbersome to run them a tester must read the
107. et up for the benefit of the development of ArgoUML 3 4 1 Logging The code shall contain entries logging important information for the purpose of helping De velopers of ArgoUML in finding problems in ArgoUML it self REQ10 REVa Rationale When the developers are searching for some problem or when they ask any of the users to help them pinpoint some problem such logging messages are very helpful Stakeholder Developers of ArgoUML 30 Chapter 4 ArgoUML Design The Big Picture Currently this is more of a base for discussion and ambition but hopefully this will mature and prove useful The code within ArgoUML is separated in subsystems that each have a few responsibilities In Issuezilla each subsystem has its issues sorted in a subcomponent with the same name as the subsys tem Furthermore the Diagrams subsystem has a set of subcomponents for issues connected to the spe cific diagrams This chapter gives an overall picture with a list of subsystems their dependencies and their main re sponsibility Chapter 5 Inside the subsystems explains each subsystem in detail The subsystems are organized in layers The purpose of the layers is to make it easy to see in what direc tion 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 that are involved when testing a subsystem 4 1 Defin
108. etailed instructions on how to build ArgoUML 2 2 Preparations In order to develop with ArgoUML it is absolutely mandatory to get the CVS version of ArgoUML How this is done is described in Download from the CVS repository Notice that the CVS contents is not only a set of source files but instead it is the complete development environment for all work within the ArgoUML project 2 2 1 Which tools do I need to build ArgoUML These are the tools not included in the CVS repository that you need to work with ArgoUML Building from source e A computer with an Internet connection and free disk space for your work 100MB is enough to download everything from the repository Currently March 2003 it is 68MB 150MB is enough to download all and build the tool and the documentation Currently March 2003 itis 114MB 250MB is enough to build it all Javadocs documentation classes packages e CVS for getting the files and committing source code updates or an IDE with a CVS client built in e JDK at least version 1 4 2 includes the Java compiler For building the documentation from DocBook format you futhermore needs these tools e DocBook XSL style sheets There exists rules in the argouml documentation build xml for downloading this cor rectly e Jimi Used by FOP for including PNG pictures Detailed instructions 1 Download the file jimil_0O zip from java sun com http java sun com products jimi It co
109. fects 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 exten ded 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 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 6 2 2 5 Using Modules When modules are used they can t be distinguished from the rest of the ArgoUML environment 6 2 2 6 How do l e tell when a module is enabled The method isEnabled in ModuleLoader2 returns true if the module with that name is enabled and false otherwise F gt Note This only works for modules enabled in the new module loader For modules loaded using the old module loader it is not possible to determine if they are enabled 93 Extending ArgoUML 6 2 3 Plugins 7 Note This description is for the old moduleloader 6 2 3 1 Plugin Architecture Each class must derive from the Pluggable interface In addition to the methods declare
110. file are so small that it shouldn t make any difference 2 8 Making a release 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 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 Note Ce g This is under rework now that the distribution is to be done using a SVN project The artifacts in play here are argouml src_new build xml argouml tools bin build release sh argouml tools bin pack release sh and other build xml files The plan for the future is that the build xml files contain rules on how to compile and package things into jar files After that the argouml tools bin build release sh and argouml tools bin pack release sh will be taken care of signing packing into tar zipped archives packing sources and uploading The build xml will have rules that places the complete runnable release in argoum1 build These are the same rules used by developers when compiling for testing The build release sh and pack release sh script takes it from there Prerequisites what you need to be able to do this e CVS access to the argouml project to set tags You also need CVS access to the included sub projects to set the tags there argouml csharp argouml nb an
111. for future implementation The plan is to have this called for each module when the module should add its entries in PopUpAc tions 92 Extending ArgoUML String getModuleKey void Returns a string that identifies the module 6 2 2 3 Module Architecture for the new implementation The controlling class for the new implementation is org argouml moduleloader ModuleLoader2 It is a singleton created when first used It is first used in the main initialization routine When created it searches through all available modules and creates a list of their main objects implementing ModuleInterface Currently September 2004 this also means that the found mod ules are by default selected i e they are marked to be enabled 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 and the result wasn t so good I Linus hopes this can be eventually fixed 6 2 2 4 The Modulelnterface interface in the new implementation Each class used by the ModuleLoader2 must implement the ModuleInterface interface This interface has methods for enabling disabling and identifying the module When a module is enabled it is expected to register some class wherever it af
112. 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 ex pand 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 5 4 1 3 Adding Property Tab Tool bar Buttons These are added by creating new instances of PropPanelButton you don t need to assign them to anything just creating will do This has six arguments e The container i e this property panel usually just use this e The panel for the buttons Use but tonPanel which is inherited from PropPanel e The icon Lots of these are already defined in PropPanel e The advisory text for the button Use localize string to ensure international portability e The name of the method to invoke when this button is used Some of the standard ones e g for nav igation are provided but you will need to write any specials e The name of the method if any to invoke to see if this button should be enabled Use nu11 if the button should always be enabled In our example the extend property panel has a add extension point button with a method newEx 65 Inside the subsystems tensionPoint that we provide to create a new use case 5 4 1 4 Support fo
113. found that this problem is in the sub product assign the issue to the right person To follow up you should do the following 1 Look at each new release of that subproduct to see if the bug report is in fact stated as fixed in that release 2 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 subproduct instead of the old one the planned releases of the subproduct with promises to solve other bug reports and the current release plan of ArgoUML From this you decide wether it is time to do the update of the subproduct within ArgoUML or to wait 3 If you decide that it is time to update you assign all issues against that subproduct to you if not already then you do the work The work is to add the new version of the subproduct 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 subproducts bug reporting tool 138 Index A Ant 6 ANT 8 how it is used 8 Ant target clean 13 docs 19 guitests 13 list property files 9 prepare docs 10 run 9 run with test panel 14 tests 13 ANTLR 6 ArgoUML Design 31 argouml build properties 9 B build properties 9 build xml 8 Building ArgoUML 8 Javadoc 10 tools
114. g in a subproject Each subproject has its own web site with documentation and plans of the subproject The subproject has its own CVS mailing list that you need to join to monitor the commits It also has its own dev mailing list where the people working within that subproject discusses the subproject Join both of these mailing list to see what is going on in the subproject The sub projects don t use their own Issuezilla database but instead they are subcomponents in the ArgoUML Issuezilla Because of this you need to acquire an Observer role in the argouml project to work in a subproject 2 4 2 3 Targets in build xml in a subproject The following targets have the same documented meaning in all sub projects e clean optional Removes files that are generated by running any of the other targets e compile optional Compiles the code The result is in build classes e generate optional This is a step that if it exists must be run before compile The result of this is some files that is a prerequisite for compile e install This builds the whole module and copies it into the ext directory in the argouml installation The purpose of the ext directory is so that argouml can be started with several different modules star ted at once e jar optional This builds the whole module and puts the resulting jar file s in build e run This starts argouml with this module active This is the way to start this module with the newly
115. g while working with ArgoUML For this reason he might be terribly confused if some other view that happens to show the same element is not showing the same thing Stakeholder User of ArgoUML All views of a model element shall be update as soon as the model element is updated 3 1 3 REQ2 REVb Rationale If a user makes an update of a part of the model an immediate feedback in all other parts that are currently showing might help him to get it right Stakeholder User of ArgoUML Editable views of the model should update the model on each keystroke and mouse click REQ11 REVa Rationale If a user makes an update of a part of the model an immediate feedback in all other parts that are currently showing might help him to get it right 27 ArgoUML requirements Stakeholder User of ArgoUML 3 1 4 Any text fields that require validation should not be editable directly from a view REQ12 REVa Rationale If a text field requires validation there exists by definition a possibility that the text field is in an invalid state at any time during editing Therefore the model cannot be updated until the field is completed in a valid state or rejected Stakeholder User of ArgoUML TODO Is this the correct stakeholder 3 1 5 With dialogs the model is not updated until the dialog is accepted by the user with valid fields REQ13 REVa Rationale It is a common feature of GUIs that a dialog displays a snapshot
116. generously on certain parts but that makes the index strangely biased Capitalize the part of the indexterms that are terms 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 Le if the indexterm contains a small word typically to of for in and normally not capit alized let the secondary start with that small word 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 10 4 DocBook Conventions e The top level document of the document is in documentname xml Each chapter or preface glossary appendix etc is a separate file defined as a system entity and included from this top level file e There are some useful entities defined for common terms in the beginning of this top level docu ment E g use of amp argouml will ensure consistent naming of the product ArgoUML and allow us to change it later to Argo UML Argouml or whatever In the build script there is some magic that translates tagname to a real value E g VERSION in the documentname xml file into 0 16 e XML comments are used throughout to explain what various sections are trying to achieve e Cross
117. getModulePopUpActions Vector popUpActions Object context p p b p b public String getModuleDescription b b b b public String getModuleKey and from Pluggable the methods public boolean inContext Object context 96 Extending ArgoUML and thus provides the basic mechanism that plug ins need 2 Decide in what context this is to be enabled and add calls there It is useful for those plugins which actually use context to provide a helper method Object buildContext classtypel parameterl classtype2 para meter2 which will serve two purposes First it will provide a simple way of creating the Object parameter Second it helps to document the context parameters within the class itself Again using P luggableMenu as an example it contains the function public Object buildContext JMenuItem parentMenulItem String menuType which is used as follows if module inContext module buildContext _help Help _help add module getMenulItem _help Help 6 2 4 Tip for creating new modules from Florent de Lamotte T Note This description is for the old moduleloader Florent wrote a small tutorial for creating modules It can be found on the ArgoPNO website http argopno tigris org documentation argouml html 6 3 How are modules organized in the java code The previous section describes how modules and plug ins are connected on the jav
118. goes for all changes even changes in comments 2 If your changes include removing files make a clean compile build clean followed by build run or build package 3 If your changes include removing public or protected operations and attributes make a clean com pile build clean followed by build run or build package The build mechanism does not yet have reliable dependency checker enabled so this is the best way to make sure 4 If your changes include adding abstract operations make a clean compile build clean followed by build run or build package The build mechanism does not yet have reliable dependency checker enabled so this is the best way to make sure 5 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 If in doubt run all JUnit test cases 6 Do a evs update in src_new to make sure that you do not forget to commit any file and to make sure that no one else has committed anything in the mean time Remember that if you do not commit all the files from src_new that cvs update 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 If someone else have updated a file cvs update shown U
119. guage wurde bei CIS entwickelt und erlaubt den Entwickler Contextbased Constraints dem Spezifikationsmodell hinzuzuf gen Dadurch entsteht ein Modell das tiber 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 unterstiitzten Before starting a detailed design a specification model of the component based system assists the soft ware developer in early problem detection as soon as possible in the development process The Compon ent 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 de scription of the system s static structure At this time there is no tool to integrate the component spe cification 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 128 Further Reading 11 2 2 Where to find it LINK Martin Skinners dissertation http www cocons org publications CCL_plugin_for_ArgoUML pdf 129 Chapter 12 Processes for the ArgoUML project This chapter contains processes used when working with
120. h Set build path 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 gt Properties Enter Java Build Path Under Source Remove everything Add argouml src_new and argouml src model src simply add a check mark in front of these folders Also add argouml tests argouml modules classfile src and the src directories of all other modules The purpose of this is to have Eclipse recompile these and find compilation errors as soon as your changes to any API has affected them Under Libraries Press the Add JARs button and add all files in argoum1l 1ib Press the Add JARs button and add the file argouml tools junit 3 7 junit jar Every time any of these jars is updated in the project you will have to update this in your environment by entering this dialog removing the old ones and adding the new ones Set the Default output folder to argoum1 bin This will not confuse it with any of the ant built things Press OK You will be asked to accept that all resources previously built can be removed Press Yes Eclipse shall rebuild Verify that there are no errors just warnings left among the problems If there are errors in some of the modules you will be able to continue your work in spite of that but it is better if you stop here and investigate the problem Some of the modules cpp idl classfile contain ANTLR generated code The rules to
121. he OMG UML Model and Dia gram Interchange Model The decision of which implementation to use is controlled by the Model class which contols the imple mentations as alternative strategies as in the Strategy Pattern GOF p315 The Model class provides the rest of ArgoUML with various interfaces through which ArgoUML can manipulate the repository Currenty there are factory and helper interfaces for controlling the lifetime and properties of elements in the repository An interface is also made available to the Diagram Interchange Model should the repository implement ation contain such A ModelEventPump interface is provided through which ArgoUML can listen for changes in the repos itory in a consistent way Implementations of this pump convert from the repoiroys specific events to 299 There are discussion underway to provide a facade GOF p185 to this model Once the facade is com plete this is likely to take over as a replacement model interface This will allow the complexities of the existing interfaces to be rationalized without affcting the facade user The factories contain all methods that deal with creating and building model elements The helpers con tain all utility methods needed to manipulate the model elements Per section of chapter 2 of the UML 1 3 specification there is one factory and one helper Both helpers and factories and the Facade and ModelEventPump are interfaces that are fetched through static methods i
122. he correct action at that point Modules can be internal and external The only difference is that the internal modules are part of the argouml jar and the external are delivered as separate jar files e Plugins Note This description is for the old moduleloader A plug in in ArgoUML is a module that implements the org argouml application api Pluggable interface The Pluggable interface acts as a passive dynamic component i e it provides methods to simpli fy the attaching of calls at the correct places There are several Pluggable interfaces that each simplify the addition of one kind of object Examples PluggableMenu PluggableNotation One Module can implement several Pluggable interfaces This is essentially and implementation of the Dynamic Linkage pattern as described in Patterns in Java Volume 1 by Mark Grand ISBN 0 471 25839 3 The whole of ArgoUML Core is the Environment the classes inheriting Pluggable are the AbstractLoadableClass 6 2 2 Modules 6 2 2 1 Module Architecture for the old implementation The controlling class of the module plugin extension is org argouml application modules ModuleLoader ModuleLoader is a singleton cre ated in the ArgoUML main initialization routine ModuleLoader will e read in the property file e for each of the classes found 1 create the specified classes 2 call initializeModule on this class 3 place the class object into the internal list of modules 91 Ext
123. he reason for making this final is that it shall never be modified by the class The reason for having a static initializer is that then all classes can do this in the same way and we don t ever risk to forgot to create the Logger For performance reasons a check before the actual logging statement saves the overhead of all the con catenations data conversions and temporary objects that would be created otherwise Even if logging is turned off for DEBUG and or INFO level Example 5 3 Improving on speed performance if LOG isDebugEnabled LOG debug Entry number i is entry il if LOG isInfoEnabled LOG info Entry number i is entry il Warning Since this has a big impact also on the readability only use it where it is really needed like places passed several times per second or hundreds of times for every key the user presses For more information go to the log4j homepage at http jakarta apache org log4j 80 Inside the subsystems http jakarta apache org log4j 5 14 2 1 Reasoning around the performance issues Most of the log statements passed in ArgoUML are passed with logging turned off This means that the only thing log4j should do is to determine that logging is off and return Log4j has a really quick al gorithm to determine if logging is on for a certain level so that is not a problem The problem is instead explained by noticing the following log state
124. he third For a verifier this corresponds to RESOLVED for the first group and VERI FIED for the third group 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 To amend this we have made two things 1 Decided that we don t use the RESOLVED REMIND states 2 At every release as part of the release process clean up issues that for some mysterious reason ended up in these states See Section 2 8 Making a release 10 f 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 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 If you know that an issue cannot be resolved now because it requires that another issue is solved be fore register the
125. heckout After that the root will be remembered by the checked out copy If you use one of the CVS clients with a graphical user interface like WinCVS GruntSpud or an IDE with a built in CVS client like Eclipse then configuration will be done by filling in fields These fields mean the following e Type pserver e User Your Tigris login name e Host cvs tigris org e Repository cvs Building from source If you used the command line CVS client before then your Tigris password is stored in the file cvspass Some graphical UI CVS clients are able to use this password in others you ll have to enter it again The next thing to do is to login It is done using the command evs login This only needs to be done once and then the account on your machine remembers this Then you do the actual checking out cvs checkout directory The CVS repository directories you need to check out to work with ArgoUML are argoum1 1ib argouml tools argouml src_new argouml src and argouml tests If you want to build the documentation you check out the directories argouml lib argouml1 tools and argouml documentation If you want to work with the web site you check out the directory argouml www If you give the argument argoum1 all of ArgoUML is checked out That is no problem except for the extra use of bandwidth and disk space but if you have plenty of both get it all and eventually you will see how everything is used for
126. hem to wherever they are used This is how a real example would look like import org argouml il8n Translator String localized Translator localize key 2 Add your key and resolution in English U S in the non localized properties file in argouml src_new org argouml1 il18n and test that the GUI looks good for the default language Which property file ArgoUML will eventually use depends on the localization settings of the running ArgoUML instance While developing you should use en_US or some language that does not have a translation so that you can work with the default language 3 Contact all language teams so that they can update their files 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 4 If you have strings that are sentences where you have dynamic values like a file name a class name or some property to enter at a certain place remember that all languages would not write it exactly like that Use MessageFormat to build every such sentence There is a conveni ence function for this in Translator called messageFormat Notice that if you somewhere change the meaning of a specific localized string it would be a good idea to use a new key for the new meaning This will make it easier for the translation team to spot the modification There allegedly a
127. her means The To do items are located in org argouml The To do items is a Model subsystem See Section 4 4 Model subsystems 5 17 Explorer Purpose to provide tree views of the model elements diagrams and other objects Note the Explorer used to be called the Navigator The Explorer is located in org argouml ui explorer and sub packages The Explorer is a Layer 2 subsystem See Section 4 5 View and Control subsystems 5 17 1 Requirements 83 Inside the subsystems The Explorer must react to user and application events User events include R1 selection of a node which must notify the other views to make the same selection R2 right click on a node which brings up a pop up menu R3 selection of another perspective in the Combo box which must change the explorer to that per spective A perspective provides a different view of the model that will focus on one or other part of the model R4 node expansion and collapse 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 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 R7 copy diagram to clipboard functionality for windows java 1 4 users R8 tool tip showing node name and type R9 standard multiple d
128. 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 9 2 Rules for the building process For the build xml files we use the following rules Be careful when downloading stuff ArgoUML is supposed to be a self contains development environment Some times it is better to have things downloaded from the ant script instead of from the CVS 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 Public targets shall have description Non public targets shall not have description write xml com ments or echos instead Use ant built ins for everything 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 9 3 Checklist for using sub products Linus Tolke In the ArgoUML project we use several sub products to solve parts of the problem for us These sub products are an important part of the ArgoUML tool and must be handled in a good way if ArgoUML is going to be successful When this is written March 2004 we have had problems with the discontinuance of one of the sub products NSUML and will c
129. icate whether the text represents valid UML syntax 0 0 0 0 eee 28 3 1 7 There shall be no indication of an exception on the screen or in the log if it has occured merely because of a user mistyping or not being aware of UML syntax 28 3 1 8 All text fields shall have context sensitive help eee eceee eee renee 29 3 2 Requirements for UML rosso e enei rope rE EEAS a EEEE ES VEEE case ovvaaidvessesseass 29 3 2 1 ArgoUML shall be a correct implementation of the UML 1 3 model 29 3 2 2 ArgoUML shall implement everything in the UML 1 3 model 29 3 3 Requirements On java and JVM 0 0 e cece eee cn ee ca eeca eee ceaeeee eeu ecueeeneeeeeeeeees 29 Cookbook for Developers of ArgoUML 3 3 1 Choice of JRE ArgoUML will support any JRE compatible with a Sun specific ation of any JRE from Sun that has not begun the Sun End of Life EOL process 29 3 3 2 D Wnload and start ereinen e oot iiv eee Hanis Ue esshes ce eet 30 3 3 3 Console output Logging or tracing information shall not be written to the con sole or to any file unless explicitly turned on by the user 0 0 0 0 eee 30 3 4 Requirements set up for the benefit of the development of ArgoUML 30 3 4 1 Logging The code shall contain entries logging important information for the purpose of helping Developers of ArgoUML in finding problems in ArgoUML itself soa deeded be aed govt issu aice Pte vedanta c
130. in the pack age org argouml cognitive ui 5 2 2 How do create a new critique Currently the only way to add a new critique is to write a class that implements it so that is described here There have however been ideas on a possibility to build critics in some other way in the future as a set of rules instead of java code Create a new critic class of the form CrXxxxYyyyZzzz extending CrUML Typically your new class will go in the package org argouml uml cognitive critics but it could go in one of the other cognitive critics packages Write a constructor which takes no arguments and calls the following methods of CrUML e setHeadline to set up the locale specific text for the critic headline the one liner that ap pears in the to do pane and the critic description the detailed explanation that appears in the to do tab of the details pane The String parameter is ignored e addSupportedDecision UMLDecision decAAAA where AAAA is the design issue category this critic falls into examples include STORAGE PATTERN METHODS e setPriority ToDoItem BBB_PRIORITY where BBB is one of LOW MEDIUM or HIGH to set 46 Inside the subsystems the priority for the critic in the to do pane e addTrigger UML Meta Class where UML Meta Class is a UML Meta Class with initial lower capital e g associationEnd The intention is that critics should only trigger for elements or children of particular
131. ionale The ambition is to implement all of UML This means that no matter how you use UML ArgoUML will always be a working tool Stakeholder User of ArgoUML 3 3 Requirements on java and jvm 3 3 1 Choice of JRE ArgoUML will support any JRE compatible with a Sun specification of any JRE from Sun that has not begun the Sun End of Life EOL process 29 ArgoUML requirements REQ7 REVb Rationale The JREs and the adjoining libraries especially swing are always improving to include new features and new ideas The developers of ArgoUML would like to use these new features Note J2SE 1 3 1 begun its Sun End of Life EOL process on October 25 2004 Stakeholder Developers of ArgoUML 3 3 2 Download and start It shall be possible to install ArgoUML locally on the machine and use without Internet connection REQ8 REVa Rationale ArgoUML is an application that edits an UML model There is no need to have any network defined while doing this Stakeholder User of ArgoUML 3 3 3 Console output Logging or tracing information shall not be written to the console or to any file unless explicitly turned on by the user REQ9 REVa Rationale ArgoUML is an application that edits an UML model Any information written to anywhere but the files that the user specifies the user won t know what to do with and it will be perceived as garbage generated by the ArgoUML application Stakeholder User of ArgoUML 3 4 Requirements s
132. irectory If the sub product in question be longs to a subsystem that is moved to a separate directory you should put it in the 1ib directory for that subsystem For the time being there is only one 1ib directory e Building Assuming that the sub product 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 One place in default properties Four places in build xml targets init tree places prerequisites package two places new target check subproduct and One possibly place in AboutBox java Constructor Notice espe cially that build xml shall not contain any version information Notice also that the text in AboutBox java shall not contain anything that needs to be localized but just the sub product name reference and possibly version Check by having some class from the sub product loaded immediately when starting ArgoUML and start using build run e Running from modules With the current modules set up Gn argouml modules the idea is that we are supposed to be able to start ArgoUML from any of the modules directory This means that whenever changing the list of modules you will have to update the classpaths in all these modules Go through the list of files argouml modules build xml and update Check by having some class from the sub product loaded immediately when starting ArgoUML and start in each of these directories e Distribution Assuming that th
133. is have discovered other problems than the one stated in the Issue create new Is sues for those new problems according to the rule for creating Issues 6 Do this as many times as you like until there are no Issues left 12 6 How to verify an Issue that is rejected 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 Do the following 1 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 The list of all RESOLVED INVALID RESOLVED WONTFIX and RESOLVED DUPLICATED _ issues http argoumL tigris org issues buglist cgi component argoum amp issue_status RESOLVED amp resol ution INVALID amp resolution WONTFIX amp resolution DUPLICATE 2 Read through the description provided 3 Do one of the following e If you agree with the statement and feel that the rejection is done for correct reasons put the Is 136 Processes for the ArgoUML project sue in Status VERIFIED e If you don t agree put the Issue in status REOPENED and give a description as to why you don t agree 4 Do this as many times as you like until there are no Issues left 12 7 How to Close an Issue This is performed by the person that originally raised the Issue or by the QA responsible for that area You need to be a member of the pr
134. iscontinuous selection with mouse and keyboard R10 the user can configure the perspectives using a dialog Perspectives can be added deleted re named 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 Application events include 5 17 2 R11 change in selection in another view any relevant rows to be highlighted R12 the UML model changes the tree must update to reflect additions deletions and name changes in the model R13 change of project the tree must update the root node should be expanded with the default dia gram selected Public APIs and SPis The Explorer Subsystem provides will provide the following APIs API1 Addition Removal of a Perspective from the PerspectiveManager Status implemented API2 Addition Removal of a Perspective Rule from a Perspective Status implemented API3 Selection of the Perspective to be displayed by the Explorer Status not implemented API4 Selection of Ordering for Explorer nodes an Ordering is a comparator that orders child nodes in the Explorer Status not implemented The Explorer Subsystem provides will provide the following SPIs SPI1 Configurable Node pop up menu Status not implemented SPI2 New PerspectiveRules can be defined and registered with the library of
135. ition of subsystem All ArgoUML code is organized in subsystems Each subsystem has e A name e A single directory Java package where it resides Subparts of the subsystem can reside in subdirectories of this directory Auxiliary parts implemen ted 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 existing subsystems This means that a change of version or indeed a change of choice of such a sub product is an internal matter for the subsystem and should ideally not affect any other subsystem All public and protected methods of all public and protected classes in this directory constitute the API of that subsystem e A section in the chapter Chapter 5 Inside the subsystems 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 It should also document the design of the subsystem This is in subsections Each subsystem can have e a Facade class The facade can be used by all other subsystems when using the subsystem The Facade class is called SubsystemName Facade and is located in the subsystem package 31 ArgoUML Design The Big Picture How it is used is primarily documented in the class file itself as javadoc but the more complex pic ture is d
136. ject settings so if you have other projects in the same Eclipse Workspace there might be conflicts For this reason it might be a good idea to do the ArgoUML work in an Eclipse Workspace separate from your other projects e Code conventions See in the menu Window gt Preferences Then select Java gt Code Style gt Code Formatter Set the Code Formatter to Java conventions built in e TAB character width is 8 Solution for Eclipse 3 0 See in the menu Window gt Preferences Then select Java gt Editor Then select the tab Appearance Set the Displayed tab width to 8 Solution for Eclipse 3 1 In Eclipse 3 1 the Tab size is part of the profile that the Code Formatter uses Alas the Java conventions built in profile contains a bug at this point ht tps bugs eclipse org bugs show_bug cgi id 104765 so the best solution is to create and use a new profile with the fix In Window gt Preferences gt Java gt Code Style gt Code Formatter set the Code Formatter to Java conventions built in as above press Show select the Indenta tion tab change Tab size to 8 press Apply and give the name Fixed Java conventions e New file templates See in the menu Window gt Preferences Then select Java gt Code Style gt Code Templates At the right hand side open the tree for Comments and set the Code Templates for Overriding methods to S see_to_overridden In the same tree for Code Tem
137. k The web site in CVS 5 The manual and quick guide The FAQ Help texts within the running ArgoUML These different bits have all different purpose and audience and the purpose of this chapter is to try to define that Table 7 1 Bits of documentation Bit Audience Main purpose Contains Source Implement ArgoUML in a main See Chapter 9 Standards for cod Code tainable and understandable way ing in ArgoUML for details on Other developers how to write the code that will main tain and improve on the code 2 The compiler Javadoc Developers writing Make it easy to see what the func Description of the functions of all code that communic tions of every class are and how classes all public and protected ates or in other ways to use them methods variables and constants interact with this class Cookbook Developers writing Make it easy to learn how Instructions on how to add new code maintaining the ArgoUML works and how to ex functions and behavior Instruc 99 Organization of ArgoUML documentation Bit Audience Main purpose Contains documentation or the web site tend it Be a collection of know ledge around how everything is set up Be a store of the agreed solution around fundamental design decisions i e design de cisions that are so big that it is meaningless to store them in the javadoc Be a collection of know ledge around how and why the proj
138. l cookbook and quickguide is written using DocBook XML V4 1 2 http www oasis open org docbook This section covers some conventions for use of DocBook and for the documentation in general It also includes some information for tooling configura tion e g for Emacs with the psgml package 10 2 Style e 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 e I in the document refers to the author and is only used to denote the authors personal opinion Avoid using it e Use the active voice e Use plain rather than elegant language e Use specific and concrete terms rather than vague generalities e Break up your writing in short sections Each section dealing with one topic e Use the present tense e Opt for an informal rather than a formal style 10 3 Document Conventions e All titles of chapters sections etc are capitalized throughout e All titles of figures tables etc have the first word only capitalized e Spelling is US English According to The Webster s Second Unabridged e Use full URLs throughout all documents Rationale These documents may also be published in oth er formats then html on the ArgoUML web site e Do not include lists of what changes have been done to the files This information is kept by CVS the version control tool This is changed si
139. l pattern cognitive critics CrSingletonViolated and org argouml uml cognitive critics CrConstructorNeeded e fix a critique 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 the critics haven t been updated to reflect the latest changes in ArgoUML so this is a procedure which is well worth digging into since it gives you also some exposure to re lated NSUML elements e change the text of a critique 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 the critic but if you change that you will notice that it doesn t have any effect e get my critic to trigger This is a suggested way to troubleshoot if the critic doesn t trigger 1 Check that the settings for critics are enabled Toggle Auto Critique 2 Check that your critic is registered in org argouml uml cognitive critics Init with the right class e g check inheritance structure against UML spec 3 Check that your particular critic is enabled in Browse Critics 4 IMPORTANT Check that the design material is actually found in org argouml uml cognitive critics ChildGenUML This method is incomplete and might not find all model elements 5 2 3 Org argouml cognitive critics class diagram
140. lace 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 5 1 3 2 Public API You might wonder how does this all work Well very simple in fact A model event from now on a Event has a name that uniquely identifies the type of the event In most 39 Inside the subsystems 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 There fore most listeners that need Events are only interested in one type of Event since they are only inter ested in the status of 1 property 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 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 Section 5 1 3 2 1 How do I register a listener for a certain type event and Section 5 1 3 2 2 How do I remove a listener for a certain event 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
141. lder conf 108 CVS in the ArgoUML project Not used Empty documentation Directory where the source of the documentation is e cookbook XML source code for this cookbook e docbook setup XML Tools and configuration files used for the formatting of the documentation from the XML source to HTML and PDF e images Pictures for all documents are collected here e javahelp Not used Empty e manual XML source code for the User Manual e quick guide XML source code for the Quick Guide extra Not used Empty lib A set of jar files This directory contains the jar files of products shipped with ArgoUML such as log4j NSUML 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 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 in formations the same way as shared libraries in Unix world foo x y z jar bar x y z jar etc When separating ArgoUML into modules the jar files connected to a specific module is instead stored together with the
142. le in UMLUseCaseDiagram java we have the following for creating Use Case nodes protected static Action _actionUseCase new CmdCreateNode ModelFacade USE_CASE UseCase The first argument is the class of the node to create from NSUML the second a textual tool tip For creating associations we have protected static Action _actionAssoc new CmdSetMode ModeCreatePolyEdge class edgeClass MAssociationImpl class 51 Inside the subsystems Association The first argument is a GEF class that defines the type of behavior wanted in this case creating a poly edge The second and third arguments are a named parameter used by ModeCreatePolyEdge edgeClass and its value MAssociationImpl class The final argument is a tooltip The tool bar is actually created by defining a method initToolBar which adds the tools in turn to the tool bar a protected member named _toolBar The default constructor for the diagram is declared private since it must not be called directly The de sired constructor takes a name space as an argument and sets up a graph model UseCaseDiagram GraphModel1 layer perspective and renderer UseCaseDigramRenderer for nodes and edges 5 3 3 2 Changing the graph model The graph model is the bridge between the UML meta model representation of the design and the graph model of GEF They are found in the parent directory of the corresponding diagram class and h
143. lemented in the defaultMoreInf oURL method in the org argouml cognitive critics Critic class e Only use glossterm for the term or its abbreviation acronym glossdef and glossseealso within glossentry Other entries are not implemented in the style sheets and so do not appear in the glossary e 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 e The indentation size is 2 e Make a new line after each sentence or before expressions The Docbook source is source that is handled by CVS 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 what sentences has been changed and what has not in the diff reports from CVS The contributions that Jeremy Bennet did for the 0 10 User Manual are not written like this Change it while changing the paragraphs e All block graphics should be encapsulated within figure allowing reference from around the text Set attribute float to 1 to allow the figure to float makes life easier for printed version e All block graphics should be provided through mediaobject and provided with both an im ageob ject and comprehensive description in a textobject This gives the potential of mean ingful content where a diagram cannot be displayed f
144. 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 e add it to the list in loadRules e 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 e tell the explorer to refresh 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 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 e navigate programmatically to a certain explorer element so that its path is exploded 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 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 n
145. locale for the users computer 4 ArgoUML default language Enlish U S This is done independently of if ArgoUML has that language prepared or not Example 5 1 Starting with nonexisting language If ArgoUML is started with Swahili on the command line that doesn t exist while the user has French that does exist configured ArgoUML will work in Swahili and all languages will show up in English U S i e the default language because Swahili doesn t exist 74 Inside the subsystems The Internationalization is located in org argouml1 i18n in the class path In the checked out copy of ArgoUML it is located partly in argouml src_new org argouml il8n functionality and non localized default language US English and partly in argouml language src org argouml1 il18n all files for a specific language one new tigris project for each lan guage For the time being some languages are also placed in argouml src il8n language src org argouml The Internationalization is an Infrastructure subsystem See Section 4 3 Low level subsystems In ArgoUML internationalization sometimes called i18n is done using the property files that are loaded into PropertyResourceBundles 5 13 1 Organizing translators The problems with internationalization are not so much the technical problems as to how it works but more so the problems are with getting keeping and coordinating the correct competences to do the job This comes from the f
146. lopers mailing list mailto dev argouml tigris org Eventually someone will commit it for you Furthermore the checkout of your copy needs to be done with your Tigris id that has the Developer role If you for some reason have earlier checked out a copy as guest and then made modifications changed the CVSROOT variable you still cannot commit changes done in the repository since the checked out copy contains information on who checked out For this reason it is best to apply for an Observer role in the project if you are going to work with the source at all The Observer role is probably granted within a couple of days we welcome everybody and then you can check out with your Tigris id This means that when you eventually are granted a Developer role you can continue working with the same checked out copy 2 5 The JUnit test cases ArgoUML has a set of automatic test cases using JUnit framework for testing the insides of the code The purpose of these are to help in pin pointing problems with code changes before even starting ArgoUML The JUnit test cases are residing in a separate directory and run from ant targets in the src_new build xml They are never distributed with ArgoUML but merely a tool for developers By running the command build tests guitests in src_new these test cases are started each in their own JVM Each test case writes its result on the Ant log The result is also generated into a set of files that can be found at
147. m him 2 8 1 The release did not work 25 Building from source This shouldn t happen This really shouldn t happen The reason that this has happened is that one of the developers has made a mistake You now must de cide a way forward 2 8 1 1 Fix the problem yourself If the problem is obvious to you and you can fix it quickly do so This is done by doing the following e Make the release tag into a branch cvs rtag b r VERSION_X_Y z FBRANCH_ X Y Z e Update your checked out copy to be on that branch cys update r BRANCH_X Y Z e Fix the problem in your checked out copy e Commit the problem in the branch cys commit m Fix of problem blabla e Continue the build process This is done by restarting the build dist release command and from that point on working in the branch instead of at the tag e Explain to the culprit what mistakes he has made and how to fix it 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 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 2 8 1 2 Delay the release waiting for someone to fix the problem Create the branch as described in Section 2 8 1 1 Fix the proble
148. m 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 Monitor the changes made to the branch to verify that no one commits anything else but the solutions to the problems When you get notified that it is completed update your checked out copy and continue the release work 26 Chapter 3 ArgoUML requirements Linus Tolke This chapter contains a description on how ArgoUML should work and behave for the users These things might not be implemented yet and the solutions might not even be clear but it is a defini tion of the goal 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 Every requirement has a number REQI REQ2 REQ3 that never changes a revision REVa RE Vb REVc that changes when the requirement change a text that is the requirement text to imple ment a rationale that is the description on why this is important a stakeholder that is one of the stake holders in the vision for who this is important 3 1 Requirements for Look and feel 3 1 1 This describes how the ArgoUML look and feel shall behave When multiple visual components are showing the same model element they shall be updated in a con sistent manner throughout the application 3 1 2 REQ1 REVa Rationale There is no way of telling where the user is lookin
149. me artefact There might be special skills involved but it differs widely depending on the nature of the Issue Do the following 10 11 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 The list of all of them http argoumL tigris org issues buglist cgi component argouml amp issue_status NEW amp issue_status REOPENED 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 Accept the Issue and reserve it by assigning it to yourself Set the Target Milestone to the release you have chosen Make sure you have a checked out copy of ArgoUML or else check out a new one How this is done is described in Chapter 2 Building from source Mark the issue as Started this could be done while assigning also Change the code to solve the problem Compile and test your new code 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 If your solution did not work as intended continue changing it until it does If you feel that your estimation of the complexity of the problem and your
150. ment Tints iy LOG debug Entry number i is entry il It is quite innocent looking isn t it Well that is because the java compiler is very helpful when it comes to handling strings and will convert it to the equivalent of StringBuffer sb new StringBuffer sb append Entry number sb append i sb append is sb append entry i toString LOG debug sb toString If the entry i is some object with a lot of calculations when toString is called and the logging state ment is passed often some action needs to be taken If the toString methods are simple you are still stuck with the overhead of creating a StringBuffer and a String from the sb toString statement 5 14 3 How to Enable Logging log4j uses the command line parameter Dlog4j configuration URL to configure itself where URL points to the location of your log4j configuration file Example 5 4 Various URLs org argouml resource filename lcf 0 http localhost shared argouml filename lcf file home username filename Ilcf Reference to a configuration file filename cf within argouml jar Reference to a configuration file filename cf on a remote server localhost Reference to a configuration file filename cf on your localmachine 81 Inside the subsystems 5 14 3 1 when running ArgoUML from the command line There are currently two possibilities of running ArgoUML from the command line
151. ment is changed this will fire an MEvent to UMLChangeDispatch UM LChangeDispatch will dispatch these events to all containers implementing UMLUserInter faceComponents interested in this event including UMLText Field It will also dispatch the event to all children of an interested container implementing UMLUserInterfaceComponent By this it is only necessary to register a PropPanel which holds an UMLTextField at UMLChangeDis patch to dispatch the event to the UMLTextField too MMelementListener knows several methods of which only one is of interest to UMLText Fields e propertySet Called every time a property in a MModelElement is set This method calls update too if the UMLTextProperty really is affected Furthermore UMLText Field implements Document Listener This is very typical for UMLText Field At the moment it is not possible to change the style of the text in the UMLText Field There fore the method changedUpdate does not have a body This method is only called when a Docu mentEvent occurs that changes the style layout of the text The methods insertUpdate and re moveUpdate are respectively called when a character is added to the document UMLText Field con tains 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 InsertUpdate and removeUpdate are both handled via the protected method handleEvent H
152. module modules Contains source level modules of ArgoUML Source level modules are modules that can be compiled and deployed independently after the rest 109 CVS in the ArgoUML project of ArgoUML Each module is located in its own subdirectory This is the list as it looks now March 2003 jscheme Module that allows to extend ArgoUML using scheme junit Old directory with JUnit tests These should be migrated to and all new JUnit tests should be cre ated in the directory tests menutest Test module that tests the plug in interface for the menus php Language generating Notation and reverse engineering for PHP Cpp Code generation for C csharp Code generation for C This is now moved to a subproject so this will eventually be removed sre Source code This contains one directory for each subsystem within ArgoUML Each subsystem will have a subdirectory with the same structure lib optional jar files with products shipped with ArgoUML build xml The file controlling the build of that subsystem SEG The source code tests optional The JUnit test cases for that subsystem Ssrc_new All source code for ArgoUML including pictures of icons tests 110 CVS in the ArgoUML project Source code for JUnit tests of everything that is in the src_new directory See Section 2 5 The JU nit test cases e tools All tools used during the build process Tools also have th
153. move up pop up menu on the element at the given index There is no default provided so this must be given if the move up operation is supported Perform the actions associated with the move down pop up menu on the element at the given index There is no default provided so this must be given if the move down operation is supported The following normally use the default method but may be declared to override methods in the parent public void resetSize public Object format ment MModel ment Called when an external event may have changed the size of the list The default just sets a flag which will ensure recal cModelElementSize see above is invoked as needed 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 per fectly satisfactory 63 Inside the subsystems public void tar getChanged public void targetReas serted public void roleAd ded final MElementEvent event public void roleRe moved final MElemen tEvent event public void re covered final MElemen tEvent pl public void listRoleItemSet final ElementEvent pl pub tyset bublyoidordmdevdg tinal MEO MMadeyShempht pub nodevblamprbper final MElemen public int getUpper Bo
154. mp cvs tag VERSION_X Y ZF done Open the repository for commits toward the next version This is done by setting the argo core version in default properties in src_new and documentation to PRE Number of next release committing and telling everyone on the developers mailing list Check the key to sign the jar files for Java Web Start Run the command keytool list v and give the keystore password secret You should have a key named argoum that is valid several months in the future This is to make sure that you have a valid key for the purpose of signing the Java Web Start version of the files 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 A key is generated with the command keytool genkey alias argouml storepass secret By default these keys have a validity of just three 3 months but by giving the validity days the validity can be extended Run the script argoum1 tools bin build release sh and give the answers to the ques tions Note Ce You need to have this file checked out Actually the script assumes the following set up e somedirectory the directory where the script is started from e somedirectory argouml the place where a checked out copy of ArgoUML resides and the documentation can be built 22 Building from sourc
155. n 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 Chapter 5 Inside the subsystems 32 ArgoUML Design The Big Picture An API with calls to public or protected methods Traditionally the subsystems in ArgoUML communicate through public methods and public vari ables 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 meth ods 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 Sec tion 8 1 How to work against the CVS repository 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 Try to help in moving the public API methods and classes from wherever to the subsystem s direct ory package using the proper deprecation procedure In order not to worsen things always add new API classes and methods in the subsystem s directory package This way of communicating is still to be used when it is not convenient to use the Facade for a spe cific use of that subsystem Notice that the Facade is
156. n new JMenuItem Argo localize _bundle diagram _ type public String getDiagramResourceBundleKey return DIAGRAM_BUNDLE The extension of ArgoDiagram is specific to this example the plug in will provide a new ArgoUML diagr am 95 Extending ArgoUML o Important o Don t forget to do the localization stuff because the plug in might be used in all lan guages ArgoUML offers do the localization stuff not plug in specific but important create a pluggable resource bundle create a new pluggable type 1 Create the plug ins interface In the package org argouml application api create an interface that extends Pluggable in the same package The class name must begin with Pluggable GP Note 5 One of the main purposes of a plugin is to provide the capability to add an extern ally defined class that will be used by ArgoUML in the same way as a similar in ternal class This means that modifications are needed all over ArgoUML in order to call the pluggable interface Therefore this must be done in ArgoUML itself and cannot be done in any module It now inherits from ArgoModule the methods public boolean initializeModule public boolean shutdownModule public void setModuleEnabled boolean tf public boolean isModuleEnabled public String getModuleName public String getModuleVersion public String getModuleAuthor public Vector
157. n the Model object Because the same interface is used internally each implementation must provide objects for each of these interfaces 37 5 1 1 5 1 2 5 1 3 5 1 3 1 Inside the subsystems Factories The factories contain in most cases a create method for each model element Example createClass resides in CoreFactory interface Besides that there are several build methods to build classes The build methods have a signature like public Object buildMODELELEMENTNAME params i Each build method verifies the wellformedness rules as defined in the UML spec 1 3 The reason for this is that NS UML does not enforce the wellformedness rules even though 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 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 re using 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 Question Am I allowed to call the factories from any thread Answer The current checks are not writ ten to allow for multiple threads so don t Helpers The helpers contain all utility methods for manipulating model elements For e
158. nalization 2005 06 12 Change to the description on how to set up an Eclipse environment Linus Tolke See Section 9 7 1 Checking out through Eclipse 2005 06 11 Change to how to make an announcement See Section 2 8 Making Linus Tolke a release 2005 05 23 Change to release building description See Section 2 8 Making a Linus Tolke release 2005 05 06 Added instructions on how we work with sub projects See Sec Linus Tolke tion 2 4 2 2 Working in a subproject and Chapter 8 CVS in the ArgoUML project 2005 05 01 Change to the tools for releases See Section 2 8 Making al Linus Tolke release 2005 04 29 Added a diagram explaining Explorer See Section 5 17 3 Details Michiel van der of the Explorer Implementation Wulp 2005 03 10 Change to process for verifying issues Any release after the one Linus Tolke where the issue is fixed can be used for verifications See Sec tion 12 5 How to verify an Issue that is FIXED 2005 03 06 Change to description of how to build src directory is now in Linus Tolke volved See Chapter 2 Building from source 2005 03 01 Removed the modules component See 10 Linus Tolke 2005 02 01 Change to Model subsystem See Section 5 1 Model 37 Sec Linus Tolke tion 5 3 Diagrams Added the Persistence subsystem More work is needed See Section 5 5 Persistence 2005 01 30 Change to the description on how to
159. nce 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 The Cookbook has a Change Log See Change Log that is updated for every significant change but that is for the purpose of making it easier for the readers e When problems in the current implementation of ArgoUML are mentioned or perhaps even emphas 125 Standards For Documentation Writing ized using the warning 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 men tioned in the format issue xxx i e there should only be a space between the word issue and the issue number This allows the tigris web site to generate links when viewing the manual source e 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 amp argoversion if you mean in the current version of the document as defined in default properties when the document is deployed There are some old refer ences to current or currently also If you encounter them try to remove them e For documents that contain an index 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
160. nd add all jars from argouml tools ant 1 4 1 1ib 4 Press the Add Jars button and add jdepend jar from argouml tools jdepend 2 2 Lab 5 Press the Add Jars button and add junit jar from argouml tools junit 3 8 1 6 Press OK to store the new Ant classpath entries These first items need only be done once as a set up 7 Run ant with the alltests target This is done by selecting in the menu Run gt External Tools gt External Tools This will open the Create manage and run configurations dialog Select the Ant Build at the left and press the New button Rename to ArgoUML AllTests Then in the Targets tab select the alltests target deselect all other targets press the Apply button and fi nally press Run This run configuration is remembered by Eclipse so after this the drop down next to the Run tool can be used In the same way you can make other run configurations for the other ant targets in the build xml file Once you have found a failing test case and would like to investigate that further you can run it as a JU nit test case from within Eclipse making full use of the Eclipse debugger This is done by browsing to the test case in the package explorer you browse to argouml gt tests gt whatever package gt whatever class right click on it and select Run gt Debug JUnit Test 124 Chapter 10 Standards For Documentation Writing 10 1 Introduction The documentation currently manua
161. ngeability changeExpression child classifier classifierInState classifierRole classifierRole1 56 Inside the subsystems client clientDependency collaboration collaboration 1 comment communicationConnection communicationLink componentInstance concurrency condition connection constrainedElement constrainedElement2 constrainingElement constraint container contents context createAction defaultElement defaultValue deferrableEvent deploymentLocation discriminator dispatchAction doActivity dynamicArguments dynamicMultiplicity effect elementImport 57 Inside the subsystems elementImport2 elementResidence entry event exit expression extend extend2 extendedElement extender extenderID extension extensionPoint feature generalization guard icon implementationLocation include include2 incoming initial Value instance instantiation inState interaction internalTransition isAbstarct isAbstract isActive 58 Inside the subsystems isAsynchronous isConcurent isDynamic isInstantiable isLeaf isNavigable isQuery isRoot isSpecification isSynch kind link linkEnd location mapping message messagel message2 message3 message4 method modelElement modelElement2 multiplicity name namespace nodeInstance objectFlowState occurrence operation 59 Inside the subsystems ordering outgoing ownedElement owner ownerScope package parameter
162. nitive critics Init add two statements private static Critic crxxxxxYyyyZzzz new CrxxxxxYyyyZzzz E Agency register crxxxxxYyyyZzzz DesignMaterialCls If you want to add a critic to a design material which is not already declared for example the Extend class you will have to add a third statement to the Init method as well which is java lang Class XxxYyyyZzCls MXxxYyyyZzImpl class where MXxxYyyyZzImp1 class should be part of the NovoSoft UML package Finally you should get a new section added to the user manual reference section on critics The pur pose of this is to collect all the details and rationale around this critic to complement the short text in the description It should go in the ref critics xml file and have an id tag named critics CrXxxYyyyZzzZz write the test in a critique The critiques tests are essentially a combination of conditions that are to be fulfilled The conditions are often simple tests on simple model elements The class org argouml cognitive critics CriticUtils contains static routines that are commonly needed when writing predicatez2 for example to test if a class has a constructor If you find you are writing code that may be of wider use than just your critic you should add it to CriticUtils rather than putting it in your critic 47 Inside the subsystems For commented examples to copy look at org argouml pattern cognitive critics CrConsiderSingleton org argoum
163. nore the build path settings We will come back to them later Press Finish which starts the checking out process You are probably directed to the Java Perspective with a question if you want or not At this point it doesn t matter Just press Yes or No The download takes a while since the download is around 60Meg Remark If you are on a modem or other low bandwidth connection this is not recommended since 119 Standards for coding in ArgoUML you will download all of the web site the source for the documentation and all modules things that you could do without unless you would want to work on them If you find a way to do this with less bandwidth use please help improving this description Theoretically we can come down to around 16Meg which would take around two hours on a 56K modem Build using ant Browse to argouml src_new build xml select the build xml1 file right click on it and do Run Ant This pops up the External Tools pop up with the Targets tab already selected Se lect compile default target in the Targets tab deselect all other targets and finally press Run There are some files that are built using rules in the build xml file This is the antlr files and the file containing a version Refresh the project This must be done after having built using ant to find the newly created Java files Select the top resource of the argouml project in the Navigator on the left right click and select Refres
164. ntains a file JimiProClasses zip 2 Copy this file into the argouml tools lib directory 2 2 2 Which tools are part of the ArgoUML development environment These tools are provided by the development environment that you get when you check out from CVS e Ant the tool to manage compiling and packaging e ANTLR for regenerating the built in parser e JUnit for running the JUnit test cases e JDepend for examining the code For building the documentation from DocBook format these tools are also provided with the develop ment environment that you get when you check out from CVS e Saxon for building documentation from DocBook format e fop for generating PDF versions of the DocBook format To build a PDF file with the pictures included you need Jimi that is downloaded separately See Jimi Building from source 2 2 3 What libraries are needed and used by ArgoUML These libraries are provided in the development environment that you get when you check out CVS They are checked by the Java compiler when compiling needed for running ArgoUML and therefore distributed with ArgoUML e NSUML the Novosoft UML library The ArgoUML project doesn t develop the Java classes for storing saving and loading an UML Model That work is done by NSUML and is used by ArgoUML e GEF graph editing framework available from gef tigris org http gef tigris org It is also recommended that you check out GEF at the same time as you
165. o set a particular figure as the representation It should provide a method canEdit to indicate whether the Fig can be edited It should provide an event handler modelChanged to cope with advice that the model has changed 5 3 3 5 Creating a new Fig explanation 2 Assuming you have your model element already defined in the model and your PropPanel for that model element you should make the Fig class 1 For nodes that are Figs that are enclosed figures like FigClass extend from FigNode ModelElement For edges that are lines like FigAssociation extend from FigEdge 52 Inside the subsystems ModelElement 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 2 Create a default constructor in the Fig In this default constructor the drawing of the actual figure is done Here you draw the lines and text fields See FigClass and FigAssociation for an ex ample of this 3 Create a constructor FigMyModelelement Object owner Set the owner in this method by calling set Owner Make a method set Owner that overrides it s super Let the method call it s super Set all attributes of the Fig with data from it s owner in this setOwner method See setOwner of FigAssociation for an example 4 Create an overridden method protected void modelChanged This method must be called and is if you implement the fig correctly if the owner changes In this method you
166. ocumented in the Cookbook in Chapter 5 Inside the subsystems e Plug in interfaces These are Facade objects where modules or plug ins can connect themselves to modify or augment the behavior of that subsystem e The plug in interfaces are also all located in the subsystem package and called SubsystemName PluginPluginType Example ModelPluginDiagram ModelPluginType e 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 SubsystemName Plu ginTypeInterface Example ModelDiagramInterface ModelTypelInterface ClassFromSomeOtherComponent ComponentPluginWhatever1 PluggableClass1 ComponentPluginWhatever2 PluggableClass2 4 2 Relationship of the subsystems Each subsystem that is used by other subsystems provide two ways for other subsystems to use them e The Facade class 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 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 deprecatio
167. of ArgoUML 4 Help with the improvements on ArgoUML by pin pointing where ArgoUML needs to be modified to allow for localization 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 5 See that the used libraries also provide their part in that language This is mostly GEF since GEF is central both when it comes to the fact that it has localized strings 75 Inside the subsystems of its own but also because it handles parts of the localization This means discussing with the teams developing the underlying package as to how best to provide the localization for those parts Either by providing localization for that team to include in the pack age or by having ArgoUML overriding that package in that respect 5 13 2 Ambitions for localization An ArgoUML subproject is created for each Language Team The subproject has the following that is used in building a community A web site Ideally the site should match the main ArgoUML site page by page with a footer on every page with flags of all the languages that that specific page exist in so that it is easy to travel between lan guages Missing pages should be linked to the main ArgoUML counterpart Alas there is no tool support on Tigris to help in this Mailing lists The users argouml language code tigris org should be
168. of its model at the time of creation and only updates that model on the user acceptance of the entire dialog This is a familiar look and feel for users Stakeholder User of ArgoUML 3 1 6 The user shall receive some visual feedback dur ing the edit process of textual UML to indicate whether the text represents valid UML syntax REQ14 REVa Rationale Writing a correct syntax of anything is complicated Good compilers are helpful in pinpoint ing where the problem is what line and what token is in error The text fields in ArgoUML are not de veloped in the same way as source code and we have no compiler step to verify it all Instead this valida tion 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 Stakeholder User of ArgoUML 3 1 7 There shall be no indication of an exception on the screen or in the log if it has occured merely because of a user mistyping or not being aware of UML syntax REQ3 REVa Rationale An exception in the log or on the screen is always the sign of a serious error in the applica tion 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 Stakeholder User of ArgoUML 28 ArgoUML requirements 3 1 8 All text fields shall have context sensitive h
169. oject any role This can also be done by someone who would raise the issue but did not because it was already present in Issuesilla 1 Pick any Issue that is Verified and that you have raised or that you have found and refrained from raising because somebody else already had written it The list of all VERIFIED issues http argoum1 tigris org issues buglist cgi component argouml amp issue_status VERIFIED 2 See that you are satisfied with the solution This could involve reading through the resolution and starting the tool to verify it 3 Doone of the following e Ifyou are satisfied put the Issue in Status CLOSED e If you are not satisfied but the problem is solved as it is written in the Issue put the Issue in Status CLOSED and open a new Issue with the rest of the problem e Ifyou 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 12 8 How to relate issues to problems in sub products ArgoUML uses products internally and is very dependant on that these products are functioning well This are products like GEF NS UML ocl log4j xerces jre Occasionally a problem found in ArgoUML is found to be a problem in one of these subproducts and cannot or is extremely complicated to fix within ArgoUML If this happens this is the way to handle this problem This can be performed by any member of the project any role There might be special
170. on ordering and task specific design understanding To date software design tools have not included features that spe cifically address key cognitive needs of designers in part because there has been no practical method for developing and evaluating these features 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 11 1 2 Where to find it LINK Robbins Dissertation http argoum1 tigris org docs robbins_dissertation 11 2 Martin Skinners Dissertation Enhancing an UML Modeling Tool with Context Based Constraints for Components 11 2 1 Abstract 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 Lan
171. ontains one package one class and one in terface Do Select the class Drag from the four quick buttons located along the sides of the class and release somewhere on the diagram Click on the fifth quick button bottom left of the class Select the inter face Drag from the quick button located along the bottom of the interface symbol and release some where on the diagram Expected output When releases on the diagram a new class is created both on the diagram where re leased and in the explorer The type of the association corresponds with the quick button type The asso ciation created when clicking the fifth quick button goes back to the class itself 2 7 Generating documentation 2 7 1 This describes how the documentation is generated i e both what to do and how the setup works If you are in a hurry Work gt set CVSROOT pserver guest cvs tigris org cvs Work gt cvs login use guest as password Work gt cvs checkout argouml documentation argouml tools argouml lib Work gt set JAVA_HOME C Programs jdkwhatever Work gt cd argouml documentation Work argouml documentation gt build defaulthtml G C C C The HTML version of the Cookbook Quick Guide and User Manual are built and the result end up in C Work argouml build documentation defaulthtml cookbook C Work argouml build documentation defaulthtml quick guide and C Work argouml build documentation defaulthtml manual respectively
172. ontinue to have it for well some time in the future until we have managed to replace it The problem with NSUML could probably not have been foreseen or avoided if this check list would have been in place when NSUML was taken into the project but some more apparent risks with sub product candidates might be Here is the list of things to check in the sub product and to discuss with yourself and maybe with the ArgoUML development team before considering to use it in the ArgoUML project License We must be allowed to develop against release with distribute and use the sub product indefinitely without monetary or other compensation 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 Java version The sub product must have a policy that matches the ArgoUML project policy on Java version re 115 Standards for coding in ArgoUML quirements 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 JDK 1 3 and 1 4 We cannot have a sub product that restricts us in this aspect Distribution We require the
173. ools do I need to build ArgoUML sssssesseseesssseresreerrsrrerrrrerrerreree 5 2 2 2 Which tools are part of the ArgoUML development environment 6 2 2 3 What libraries are needed and used by ArgoUML eee eee e ee ees 7 2 3 Download from the CVS repository 2 0 00 cece cece eee eeece cece eee eeea cena eens eeaeeeneeeenees 7 24 Buld Process svete wish eedewotocade eh E EE EE ied yecd se pees he lay E E E R Ea 8 2 4 1 How ANT is run from the ArgoUML development environment 8 2 4 2 Developing in a SUbproject 0 0 ee cece ee cece eee ce eeceeeca teen eeee eens eeneeees 10 2 4 3 Troubleshooting the development build 0 0 0 0 eee ee eee eeeee teen eens 13 25 The JUMit test Cases soiorns decsveive de EE isa e EE aE A RES ese cseee ested A ss 13 2 5 1 HOW to Write a test CaSG 4 5 eers re eeren eE shade ssa dbndaass AE Ee a e 13 2 6 Manual T st Cass ireo eors ere e er e EE r REE EEEE EEE EES s REESS 16 2 6 1 Running the manual tests corses sssas dosere ioniese isie EEEE Ere Es ESTEE 16 2 6 2 Writing the manual tests 0 0 0 0 cece cece eee eeeceeeceeeeeeecaeeea seen eens eeue eens 16 2 6 3 The JASt Of TES S scssds2s desig sat ane e saat tgass E EEEE EEEIEE 17 2 7 Generating documentation isere eee r eE oE E on EEEE A AEREE EEEn 18 2 7 1 How the ArgoUML web site works sssesssseeesseserssrerrsrrerreresrerrerrerrsrree 18 2 7 2 The ArgoUML documentation eseesseeeseeereeeerrererr
174. or any reason Where appropriate the me diaobject should be wrapped by screenshot e Inline graphics can be done through inlinegraphic rather inlinemediaobject A textual alternative is of little value in these circumstances Where appropriate the mediaobject should be wrapped by guiicon For Emacs Users If you use the psgml library within emacs then editing and verifying XML gets easier Information on using this facility is inluded with psgml e Emacs local variables appear in a few lines of comment at the bottom of each XML file Please don t delete these e Adding setq sgml set face t to your emacs file will cause all tags and entities to ap pear in boldface e Adding setq sgml auto activate dtd t to your emacs file will ensure the Doc Book DTD is parsed as soon as the file is loaded 127 Chapter 11 Further Reading 11 1 Jason Robbins Dissertation Cognitive Support Features for Software Development Tools The dissertation of Jason Robbins is a MUST READ for everyone concerned about ArgoUML Be care ful though since it is based on an old version of ArgoUML but many of the concepts remain intact 11 1 1 Abstract Software design is a cognitively challenging task Most software design tools provide support for edit ing viewing storing sharing and transforming designs but lack support for the essential and difficult cognitive tasks facing designers These cognitive tasks include decision making decisi
175. or even for all events fired by a cer tain type of model element For these cases the pump has functionality too This is described in section Section 5 1 3 2 3 Hey I saw some other methods for adding and removing 5 1 3 2 1 How do I register a listener for a certain type event This is really very simple Use the model addModelEventListener PropertyChangeListener listener Object modelelement String like this Model getPump addModelEventListener this modelelementIAmInterestedin IamInter Now your object this gets only the Events fired by modelElementIAmInterestedIn that have the name IamInterestedInThisEventnameType 5 1 3 2 2 How do I remove a listener for a certain event This is the opposite of registering a listener It all works with the method removeModelEventListener PropertyChangeListener listener Object modelElement Str on the ModelEvent Pump like this Model getPump removeModelEventListener this modelelementIAmInterestediIn IamIn Now your object is not registered any more for this event type 5 1 3 2 3 Hey saw some other methods for adding and removing 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 addModelEventListener PropertyChangeListener listener Object modelelement As you can see no names of events you can regis
176. orting This latter model is used e g for attributes of a class 54 Inside the subsystems e 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 UMLComboBox2 The UMLEditableComboBox allows editing the selected item The UMLSearchableComboBox allows editing the selected item See e g the Operation com bobox on the callevent properties panel Then there is a variant with a seperate button for navigation to the property panel for the currently selected item This is supported by theUMLComboBoxNavigator class Used e g for the stereo type field e An editable multiline text area Supported by the UMLTextAreaz2 class Used e g for the text field of a UML Comment Examples of these fields in more detail follow below 5 4 1 1 Adding a simple list field For example we need to add a field to the use case property panel for the extends relationships that de rive from this use case This field consists of a label and a scrollable pane JScrol1Pane containing the list JList which may be empty or contain extend relationships from this use case Rather than a straight JList we use its child UMLLinkedList which adds several features to the standard JList specifically for ArgoUML s properties panels The constructor for UMLLinkedList requires two arguments a list model and a flag to indicate whether to show
177. ot infinitely often contain elements from the model but I don t think anyone has don t it Obviously finding all occurrences cannot be done 5 18 Module loader 86 Inside the subsystems Purpose to provide the mechanisms to load and unload the auxiliary modules The Module loader is located in org argouml moduleloader An old module loader is located in org argouml application modules ModuleLoader with interfaces Pluggable in org argouml application api Eventually this will be removed 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 For details on how to build a module see Section 6 2 Modules and PlugIns 5 18 1 What the ModuleLoader does The ModuleLoader is looking for module jars It actually scans through all jars available in the ext dir ectory See Edit Settings Environment tab If you turn on logging on the debug level while running ArgoUML you should be able to see what jar files it finds and what it does with them A module jar contains the classes resources and a manifest file The manifest file points out the class to be loaded Also notice that the Specification Title and Vendor must be specified correctly for this to work 5 18 2 Design of the new Module Loader The plan is to implement this new Module Loader then have them both working side by side for several rel
178. other issue as depends on and leave the issue in the up for grabs pile as not re solved 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 WORKSFORME This means that it works in a released version of ArgoUML State the version in the comment 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 prob lem was fixed 132 Processes for the ArgoUML project 12 3 Roles Of The Workers The roles described below are per issue i e for every issue there is at least a reporter a resolver and a verifier 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 12 3 1 The Reporter The Reporter is the person who enters the issue in Issuezilla Skills The reporter is an ArgoUML user should not need any knowledge of what the ArgoUML project is actually doing Responsibilities e Report an issue The address to enter new issues is _ http argouml tigris org issues enter_bug cgi http argoum tigris org issues enter_bug cgi For entering new issues registering as described in 1 3 is not
179. 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 If you at this point feel that your personal plans have changed so that you won t have time to pur sue the work change the Issue back to NEW with your experiences sofar 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 com mit 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 Commit your changes and the JUnit test cases stating the number of the Issue in the comment 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 Resolve the Issue with the resolution FIXED Sit back and feel the personal satisfaction of having completed a something that will be part of the ArgoUML product If you during this have discovered other problems create new Issues stating those new problems according to the rule for creating Issues 135 Processes for the ArgoUML project 12 5 How to verify an Issue that is FIXED
180. parent participant partition partition powertype powertypeRange predecessor presentation qualified Value qualifier raisedSignal receiver reception recurrence referenceState representedClassifier representedOperation requiredTag resident residentElement script sendAction sender 60 Inside the subsystems signal slot source sourceFlow specialization specification state state state2 state3 stateMachine stereotype stereotypeConstraint stimulus stimulus 1 stimulus2 stimulus3 structuralFeature subject submachine submachineState subvertex supplier supplierDependency tag taggedValue target targetFlow targetScope templateParameter 61 Inside the subsystems templateParameter2 templateParameter3 top transition trigger type useCase value visibility when This list model should then be provided with a number of methods The following are mandatory since they are declared abstract in the parent protected void buildMod elList protected boolean isVal idl me Ele nt Object MBase o g Warning The following description is old and the property panels have undergone some fundament al 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 Re Builds the list of elements Called from targetChanged every time the target of the proppanel is changed Returns true if the gi
181. pers These cases should be fixed because the files are no longer readable For the first case remov ing every other line the empty ones can in some cases be done without CVS having problems with merging later on For the second case with a single long line this will be very problematic so even though it might cause problems for other developers it is better to do this as soon as possible When this is fixed let the fix be the only thing done in that commit To avoid this in the future always do a evs diff before doing your change to make sure that only the lines that you have actually modified will be changed by CVS and not the whole file Files that are binary that shall be stored in CVS shall be marked as binary They are marked with the admin flag kb This means that the line ending conversion mechanism will not be applied on those files and they will be exactly the same on all systems This is good for jars GIFs and other such 8 4 CVS repository contents This chapter describes what parts of the CVS 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 This chapter is organized as the CVS repository itself and everything is in alphabetical order This is what the main argouml project looks like build Directory where the built things end up There is actually no real need to keep this in CVS It is there just as a place ho
182. plates open the Code node and select New Java Files Set it to Id s Copyright c 2005 The Regents of the University of California All 121 Standards for coding in ArgoUML 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 Th nd 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 INDIR d SPECIAL INCIDENTAL OR CONSEQUENTIAL DAMAGES INCLUDING LOST PROFITS EC EN IF ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION EV THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY 5
183. proach much like the rest of the Java world For the subsystem API we always use org argouml subsystem package name i e the classes are in the subsystem s directory and all subsystems have package names that is a single level below org argouml 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 This is the plan for the subsystems and new classes Don t move old classes just yet That would cre ate more confusion that it would help For everything else follow Code Conventions for the Java Programming Language http java sun com docs codeconv html CodeConvTOC doc html called Sun Code Conventions 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 argouml tools checkstyle checkstyle_argouml xml To run Checkstyle run the command build checkstyle from the argouml src_new directory This requires you to have checked out the directories argouml tools argouml tests and argouml src_new 114 Standards for coding in ArgoUML The last couple of Checkstyle result are also available in the Xenofarm result Checkstyle will also check some of the rules from the Sun Code Conventions that are not stated
184. ptyList new ArrayList Object o emptyList get 0 catch IndexOutOfBoundsException iobe fail Index out of bounds exception was thrown package org argo import junit fra uml uml ui mework public class GUITestUMLAction xtends public void testIndexOutOfBoundsExceptionNotRaised Example 2 1 An example without Javadoc comments TestCase public GUITestUMLAction String name super na Testing all three co public void UMLActio assert public void UMLActio assert public void UMLActio assert package org argo import junit framework me testCreatel n to new Disabled testCreate2 n to new Disabled testCreate3 n to new Disabled and the corresponding no GUI class uml uml ui public class TestUMLAction nstructors Q O O Enabled xtends TestCase public TestUMLAction String name super name UMLAction new String hexagon to shouldBeEnabled UMLAction new String hexagon to shouldBeEnabled UMLAction new String hexagon to shouldBe because the code is shorter easier to maintain and you get a better error message from the JUnit frame A lot of times it is useful just to run the compiler to verify that the signatures are correct on the inter faces Therefor Linus has thought it is a good idea to add methods called compileT
185. r best practices e Checklists provide help for the user to suggest and keep track of considerations that the user should make for each design element Checklists are currently 0 9 5 and 0 9 6 turned off e ToDoltems provide a way for the Critics to communicate their knowledge to the User and let the User start Wizards e Wizards are step by step instructions that fix problems found by the Critics Main classes Here is an illustration of the main classes implementing critics 44 Inside the subsystems C riticd getC riticke yo ConfigurationKey getC riticCategoryd String getC riticName 0 String critique dm Object dsgr void postite miite m dm Object dsgr void predicate dm Object dsgr boolean stillValid i dsgr boolean supportsid boolean getSupportedDecisionsd Vector addSupportedDecision d void Supportsig boolean getSupportedGoalsd Yector addSupportedGoalig void containsKnowledge Type type String boolean add Knowledge Type itype String void getKnowledge Type sO YectorSet setKnowledge Type sikt YVectorSet void setKnowledge Type sitl String void setKnowledge Type sitl String t2 String void setKnowledge Type sitl String t2 String t3 String void static reasonCode Forts String int getTrigge rMaskd long addTrigge ris String void matchReason patte rnCode long boolean expandide sc
186. r in what subsystem Documentation Style Source and Tagged values belong 5 11 2 1 How do l 73 Inside the subsystems e add a tab in the Details Panel Create your TabXXX class in org argouml uml ui by copying from another TabYYY java e g TabSrc TabStyle Then register your TabXXX in org argouml argo ini by adding a line giving the compass point to place the tab Like south TabXxXX e remove a tab from the Details Panel Remove the line for the tab from org argouml argo ini 5 12 Help System Purpose to provide the menu actions that start the help and other documentation To provide infrastruc ture that makes context sensitive help possible The Help System is not yet implemented The Help System will be located in org argouml help The Help System is a Model subsystem See Section 4 4 Model subsystems Javahelp or some other help function will probably be used 5 13 Internationalization Purpose to provide the infrastructure that the other subsystems can use to translate strings to provide the infrastructure that makes it possible to plug in new languages to administer the default language to administer all supported languages When ArgoUML starts it starts with the language given by the first decisive language information of 1 Command line argument The prepared Java Web Start alternatives also uses this to override everything else 2 The users saved configuration 3 The default
187. r stereotypes The PropPanel should override the following note the spelling of the method name protected boolean isAcceptibleBaseMetaClass String baseClass Returns true if the given base class is a class of the target in the PropPanel This is used to determine what stereotypes may be shown for this property panel 5 4 1 5 Other sorts of fields 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 For example this is used to provide drop down lists for the base and extension use cases of an Extend re lationship in PropPanelExtend The model behind the drop down is created by using UMLComboBoxModel UMLComboBoxMod el container predicate vent getter setter allowVoid baseClass useModel The container is the PropPanel 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 NSUML MElementEvent name we are looking for see earlier for the list getter is the name of a public method in the PropPanel that yields the current entry in the combo Box of type baseClass setter with a single argument of type baseClass sets that entry allow Void if true will allow an empty entry for the box baseClass is the NSUML meta class from which all entries must descend us
188. ranch also knows that it is discontinued look at someone else s work in a branch You need the name of the branch i e the work_xxxyyy_hisname There are two alternatives e Check out ArgoUML or part of it on that branch cvs co r work_xxxyyy_hisname argouml e Update your copy of ArgoUML to be on that branch cvs update r work_xxxyyy_hisname Make sure that your copy does not have any uncommitted code or else your uncommitted code will be present in your checked out copy on the branch This could on the other hand be useful if you want to test if your uncommitted code works also with the additions on that branch 8 3 Other CVS comments This is included in the cookbook because it seems that there are persons within the project that don t have the in depth knowledge of CVS nor the interest or need to acquire it For that reason some simple questions are answered here for use of CVS in the project Why do I get double lines Why do I get M at the end of each line Why do I get the whole checked out file on a single line CVS is line oriented It stores in the repository the concept of a new line after each line It is the CVS clients the program you have installed on you machine responsibility to convert the conceptu al new line to the correct new line character on your system a Note This is only so for normal files not marked with kb in CVS If files are moved from one system to another or for that matter checked out on
189. re exists an issue in Issuezilla de scribing 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 3 Subscribe to the users mailing list Discuss how you use ArgoUML in your project and how you promote ArgoUML in your organiza tion You can also help other users with their ArgoUML related problems 4 Apply for an Observer role This shows that you are committed to the project and also allows you to comment on issues 5 Familiarize yourself with the project and how we work Suggestion on how to go about this a Read through most of the User manual and install and run the latest version of ArgoUML b Subscribe to the issues list You will get updates on all issues so you can monitor what we are doing in the project It could be a lot of mails If it turns out you don t like watching issues in this way you unsub scribe Introduction h Subscribe to the CVS list 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 Read the process part of the Developers Cookbook at Chapter 12 Processes for the ArgoUML project This will give you the idea of how the ArgoUML project attempts to release with good quality and especiall
190. re 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 correct ness Notice also that you shouldn t localize log entries comments exception names names of environ ment variables and tags and tokens used in save files This is because the development project of ArgoUML is a one language community en_US and 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 Also a user changing the language should not have his files or configuration cor rupted by this change 5 14 Logging Purpose to provide an api for debug log and trace messages 78 Inside the subsystems The purpose of debug log and trace messages is To provide a mechanism that allows the developer to enable output of minor events focused on a specific problem area and to follow what is going on inside ArgoUML The Logging is located in org argouml The Logging is a Layer 0 subsystem Logging is currently implemented using log4j ArgoUML uses the standard log4j http jakarta apache org log4j logging facility The following sec tions deal with the current implementation in ArgoUML By default logging is turned off and only the version information of all used libraries are shown on the console 5 14 1 What to Log in ArgoUML
191. referencing requires use of id attributes Many of these used in the manual are of the fol lowing format but the use of this format is not obligatory any more To avoid confusion use a prefix of ch for chapter app for appendix s for sectl through sect5 fig for figure tab for table and g1 for glossentry A second prefix of tut or ref is allowed to distinguish tutorial and reference material The re mainder 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 fig ref navigation_pane for a figure showing the explorer with the diagram in naviga tion_pane gif There is one exception to this and that is the description of the critics in the manual Each paragraph 126 10 5 Standards For Documentation Writing about a critic is instead marked with critics followed by the classname implementing that crit ic 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 spe cific critic is described in a sect1 sect2 sect3 or sect 4 Reorganizing the manual would otherwise affect also the java code The conversion to the correct tagname or really the correct URL is currently imp
192. rg runs the program ant bat To keep you from having to write this and keeping track if you are working with a module or not there are two scripts one for Unix and one for Windows that are called build sh and build bat re spectively present in most of the directories that contain a build xml file These two scripts run the equivalence of the above paths By setting JAVA_HOME to different values you can at different times build with different versions of JDK and Java Building from source To use different versions of ANT you are responsible for installing your own version Also you must execute where ever you placed your new ant target rather than build target 2 4 1 1 Compiling for Unix Here is what you need to do in order to compile and run your checked out copy of ArgoUML under Unix JAVA_HOME where you have installed jdk export JAVA_HOME This is for sh style shells like sh ksh zsh and bash If you use csh style shells like csh and tcsh you will instead have to write setenv JAVA_HOME where you have installed jdk Change the current directory to the directory you are building cd your checked out copy of argouml src_new Start Ant with no parameters to get a list of build targets with descriptions build sh Compile and run ArgoUML using build sh run You can do this over and over again when you have modified something or want to compile and run again 2 4 1 2 Compiling for Windows l 2 set JAVA_
193. s 4 6 Loadable subsystems 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 Note The old mod ule loader does not have the possibility to disable modules The new one has but is not widely used July 2005 e Java Code generation Reverse engineering see Section 5 8 Java Code generations and Reverse Engineering e Other languages Code generation Reverse engineering see Section 5 9 Other languages e Critics and checklists see Section 5 2 Critics and other cognitive tools e OCL see Section 5 19 OCL 35 ArgoUML Design The Big Picture Other languages pc Model To do Items 36 Chapter 5 Inside the subsystems o Warning This chapter is currently under rework with new subsystem organization Things that are not actually in place are TargetManager 5 1 Model 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 The Model is located in org argouml model The Model is a Model subsystem See Section 4 4 Model subsystems Currently there is a full implementation using NSUML to store the OMG UML Model Development is in progress for an MDR implmentation storing both t
194. s and also the current status of the project with goals requirements and release plans 12 3 3 The Verifier 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 The test must be done on the Target Milestone version of the issue or any later version released to the public Responsibilities e Check that the issue is solved in the stated version of ArgoUML e Mark the issue as verified If the Verifier can conclude that the problem does not exist or the feature enhancement is now present the issue is marked as verified e Reopen the issue if the solution is not fully correct If the solution is not correct or the feature enhancement does not work it is the duty of the Verifier to reopen the issue 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 12 4 How to resolve an Issue This can be performed by any member of the project any role Persons without the Developer role need 134 Processes for the ArgoUML project a person with the Developer role to actually commit the work if the resolution involves changing so
195. s Number of spaces repres enting a level of indentation e In Preferences gt Java gt Java Editor gt Appearance Displayed tab width 8 Insert space for tabs see Formatting preferences checked There seems to be no way of having tabs set at width 8 and the indentation level set at 4 at the same time so we must let Eclipse generate code without tabs to obey the Sun Coding standard 9 5 Settings for NetBeans Linus Tolke These style guides correspond to the following settings in NetBeans e In Tools gt Options gt Editing gt Editor Settings gt Java Editor Tab Size 8 e In Tools gt Options gt Editing gt Indentation Engines gt Java Indentation Engine 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 9 6 Settings for Emacs Linus Tolke These style guides correspond to the default Java settings in Emacs eu java c basic offset 4 c comment only line offset 0 0 c offsets alist inline open 0 topmost intro cont statement block intro knr argdecl intro 5 substatement open 118 Standards for coding in ArgoUML label statement case open statement cont arglist intro c lineup arglist intro after paren arglist close c lineup arglist access label 0
196. s collating During load the persistence subsystem unwraps the persistence data and passes these to the relevant sub systems for those subsystems to build themselves 5 6 Reverse Engineering Subsystem Purpose Point where the different languages register that they know how to do reverse engineering and common reverse engineering functions for all languages The Reverse Engineering is located in org argouml uml reveng The Reverse Engineering Subsystem is a Control subsystem See Section 4 5 View and Control sub systems 5 7 Code Generation Subsystem Purpose Point where the different languages register that they know how to do code generation and common functions for all languages The Code Generation is located in org argouml language The Code Generation subsystem is a Control subsystem See Section 4 5 View and Control subsys tems Currently up until April 2004 very much of this subsystem is located in org argouml uml generator and we have a need to modify the interfaces of the subsystem to no longer include any NSUML types This move will be carried out by creating new interfaces in org argouml language and deprecating the old ones This is my Linus Tolke suggested way of how it is going to work The different languages or notations supplied with ArgoUML are found in sub packages of link org argouml language Any definition or foundation interfaces are found in the directory org argouml language
197. s in writing the move up function Swaps the elements at java util List offsets index and index 1 Not clear why it doesn t return a Col moveUpUtil Collection lection oldCollection int in d atic protected helps in writing the move down function Swaps the elements at java util List move offsets index and index 1 Not clear why it doesn t return a Col DownUtil Collection old lection Collection int index static protected helps in writing the getElementAt Finds the element at a MModelElement elementAt specific index The last argument is ignored Util Collection collec tion int index Class 5 4 1 2 Building the field By convention the background of the list is set to the same as the background of the PropPanel and the foreground to Color blue The list is then added to a JScrollPane Although ArgoUML has historically not used scrollbars JScrollPane VERTICAL_SCROLLBAR_NEVER and JScroll Pane HORIZONTAL_SCROLLBAR_NEVER it is more helpful to permit at least a vertical scrollbar where needed JScrollPane VERTICAL_SCROLLBAR_AS NEEDED and JScroll Pane HORIZONTAL_SCROLLBAR_AS_ NEEDED Ct Finally the inherited method addCaption is used to add the label for the field and addField to add the associated scroll pane The second argument of each of these identifies the index of the caption field pair in the vertical column of the grid
198. s not require any of the ArgoUML tools to build If you don t understand this or it doesn t work read the rest of the chapter that describes why and how in more detail 2 4 2 1 The sub project s relation to ArgoUML The purpose of a subproject to ArgoUML is to develop things that are run within ArgoUML In ArgoUML we call them modules in other tools they are called add ins or plug ins If you want to start working with a module of your own you could do it by letting the ArgoUML project leader set up a subproject to ArgoUML for you The benefits are e You will inherit all the infrastructure from the ArgoUML project This includes a site for your CVS repository mailing lists web server a common way to set up the project releases bug fixes Xenofarm builds static checks and coding guidelines and license e You get a community of ArgoUML developers that might monitor your work The draw backs are e You are forced to use the ArgoUML infrastructure CVS BSD license coding guidelines e You are forced to make your module Open Source 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 ne cessary The sub projects are developed close to the ArgoUML project and reside in the same CVS repository We try to provide a working set of tools and instructions to fit the whole set of proj
199. se are extended by ArgoUML to help in the provision of action methods for fields in the property tab Several fields involve lists and these re quire in addition list models to compute the members of the list The fields that you might add to a property panel include e Simple editable text For example the Name field Supported through the UMLTextFieldz2 class e A drop down box aka combobox of options that can be selected Supported by the UMLCom boBox2 class Used e g for the type of a parameter e A check box This one does not use a seperate model class thanks to the simplicity of the represen ted boolean value Supported by the UMLCheckBox2 class Used e g for the concurrency checkbox on a composite state e A radio button These always come in a group Supported by the UMLRadioButtonPaneli class Used e g for selecting the visibility on the properties panel of a class e A list Used e g for the Generalizations field on the proppanel of a class The non editable list is supported by the UMLList2 class and its child UMLLinkedList The latter also exists in the form of UMLMutableLinkedList which allows adding creation and deleting elements by popup menu Used e g for the subvertex list for a composite state The list model is usually provided by a sub class of UMLModelElement ListModel12 There is a variant UMLModelElementOrderedListModel2 intended for ordered links which adds a few items to the pop up menu allowing s
200. should have a JUnit test case class called org argouml x y Testz_ stored in the file tests org argouml x y Testz java containing all the Unit Test Cases for that class that don t need the GUI components to run Tests that do need GUI components to run should be part of a class named org argouml x y GUITestz stored in the file tests org argouml x y GUITestz java If you only want to run your newly written test cases and not all the test cases you could start with the command build run with test panel and give the class name of your test case like org argouml x y Testz or org argouml x y GUITestz You will then get the output in the window You could run all tests in this way by specifying the special test suite org argouml util DoAllTests in the same way Every test case class imports the JUnit framework import junit framework and it inherits TestCase i e junit framework TestCase 2 5 1 2 About the Test case Method Methods that are tests must have names that start with test i e all small t e s t This is a require ment of the JUnit framework Try to keep the test cases as short as possible There is no need in cluttering them up just to beautify the output Prefer Example from JUnit FAQ public void testIndexOutOfBoundsExceptionNotRaised throws IndexOutOfBoundsException ArrayList emptyList new ArrayList Object o emptyList get 0 over 14 Building from source try ArrayList em
201. skills involved depending on the nature of the problem In this description issue means a issue in issuezilla bug re port means a bug report in some other project and problem denotes the conceptual problem Do the following 1 During your examination of an issue you find that the problem is in one of the ArgoUML sub products GEF NS UML ocl jre 2 Make sure that the issue is assigned to you 137 Processes for the ArgoUML project 3 Write a comment in the issue stating which one of the subproducts that has the problem and what the problem is within that subproduct 4 Post a bug report in that subproducts bug reporting tool or find that a bug report already re gistered I am assuming that there is such a tool for the subproduct 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 commu nicated 5 Accept the issue set it to STARTED and enter the reference from the subproducts bug reporting tool and if possible the URL to the bug reporting tool or to the bug report in question I am assuming that there is a bug reporting tool for the subproducts If there isn t for the product in question then include all communications both ways in the issue You are now responsible to follow up on the upcoming releases of the subproduct If you don t think that you are the best person for this you should be since it was you that
202. something 4 Analysis a Concept Class Diagrams b System Sequence Charts and Collaboration Diagrams c System State chart Diagrams 5 Design a Class Diagrams for Realization b Sequence Charts and Collaboration Diagrams for Realization c State chart Diagrams for realization d Package Diagrams 6 Build a Deployment Diagrams 102 Organization of ArgoUML documentation b Code Generation in ArgoUML 7 2 3 2 Reference Manual Structure 1 Material on each of the diagram types each of the artifacts that can appear on the diagrams and de tails of the features of each artifact type 2 An Index 7 2 4 Actions Priorities and Questions 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 in dividually closed I Linus Tolke 2004 will make issues of the things I think are left to be done and re move this section unless someone beats me to it 7 2 4 1 Actions and priorities 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 1 Get buy in for the approach Completed 2 Agree document structure broadly
203. srrerrererrerrerrerrsree 19 2 7 3 How we work with documentation eesesseesseeeerseesrerrerreersrrerreresrreees 20 2 8 Makin ga releases co on yore nn E E ss cans EE EEE E 21 2 8 1 The release did not work 2 0 00 eee cece cence ence eee eeceeeeeeeceeesaeeeaeeeneeags 25 3 ArgoUML requirement spisser o eier seb tan stig sab SEEN sees seas e TE GE TES 27 3 1 Requirements for Look and feel 2 0 0 0 cece ec eee e cece cen eeeeeeae eeu eeneeeneeeenees 27 3 1 1 When multiple visual components are showing the same model element they shall be updated in a consistent manner throughout the application 27 3 1 2 All views of a model element shall be update as soon as the model element is Update dss ceri e eE E KE E E Orie eea bate eweadonob oder untte O ERA wees 27 3 1 3 Editable views of the model should update the model on each keystroke and MOUSE CCK Goa see 4 iee sash tees sent handsbesnen ey toda e Gabo a a ale edaeds oblaas wevtaeetsreehs 27 3 1 4 Any text fields that require validation should not be editable directly from a VICW is aise APEE EE pyors stoop sumgen sy Senge spe eeece E E Sete dsnatea dosh sends entepentehs coud 28 3 1 5 With dialogs the model is not updated until the dialog is accepted by the user Withvalid fields sssee settechonodtaneeesdnewogou na selauedaeuss Wegdaeagnesases o ENESES e EEE 28 3 1 6 The user shall receive some visual feedback during the edit process of textual UML to ind
204. sub products to make it possible for us to take the distribution enter it in our CVS re pository and write rules to automate the use of the sub product while developing releasing and run ning ArgoUML This automated use must be able to run without relying on access to some server and without user intervention The API documentation of the sub product assumed to be Javadoc we can use from some web site belonging to that sub product 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 Road map The project developing the sub product must have a plan that fits the ArgoUML plan for the future Rationale If a sub product will soon go somewhere else i e stop doing what we require or stop sup porting what we require then we will soon have troubles with that sub product Working project The project that develops the sub product should be a working project Check that there is some per son 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 Rationale We don t want to rely on a sub product where there is no chance of ever getting a bug that we encounter fixed We are also part of an ever evolving
205. t and obeys the design Repeat This can go on until the developer helping you knows that you have good knowledge of the project quality and design and the main problem for you two is that the sending waiting com 2 Introduction mitting updating et c is extra work 8 Apply for a Developer role This allows you to do commits on your own and you can now increase the pace in which you are working while also increasing your responsibilities in the project This role is granted by the Project leader after he is convinced that you have learned the enough about the project w r t e Understanding and accepting the goals e Understanding where we are in the development process e Understanding the terminology used in the project e Understanding how we use CVS in the project e Understanding the set of tools ant JUnit and how to use them 9 Focus your work in a specific area Everybody has different interests and the best contribution is made when someone is allowed to pursue his own interests Hopefully ArgoUML provides you with interesting challenges to your taste 10 Accept responsibility for a specific area With this you are part of the core team developing ArgoUML 1 4 About this Cookbook 1 4 1 1 4 2 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
206. t be of GIF format and have a drawing of the button image to be used in itself This image is also used on the PropPanel The name of the Image file should be model element gif 10 Add buttons to the action you created on those places in the GUI that have a need for it This should be at least the button bar in each diagram where you can draw your model element Prob ably the parent of your model element e g class in case of operation will want a button too so add it to the PropPanel of the parent In case of the diagrams add it in UMLdiagram java so in UMLClassDiagranm if it belongs there In case of the PropPanels most of them don t use ac tions they implement them directly as methods in the PropPanel themselves Please don t do that but use an action so we have one place of definition 5 4 Property panels Purpose to provide a form view of the diagrams and objects in the model The contents of the model is modifiable The Property panels will be located in org argouml uml The Property panels is a View subsystem See Section 4 5 View and Control subsystems The PropPanels for the diagrams are in org argouml uml diagram ui and the property panels 53 5 4 1 Inside the subsystems for UML objects are in org argouml uml ui UML path Adding the property panel Property Panels for UML model elements are found as class PropPanelxXxx java where XXX is the UML meta class They are in sub packages of org argouml
207. t to the group of already existing manual tests or improving one of the existing tests helps the project forward Remember that the first priority is to test things with the JUnit tests be cause they can be to some extent run automatically and have their result reported automatically but then manual tests are the next big improvement Every test has several attributes to make sure that we can identify the test and help the developers and testers 16 Building from source Aname This name is the title of the subsection where the test is described e A number These start with TEST1 and are allocated in sequence and maintained manually in this document TEST2 TEST3 TEST4 They are never reused when made available by removing a test case e A revision Every test case has a revision These start with REVa and are increased with one every time the test case is changed e A list of requirements tested This list is references to the requirements as stated in Chapter 3 ArgoUML requirements e Preparations i e what to do before the test This is Optional The default is that you have just started ArgoUML e A description on what to do an what to expect This is a description in plain English telling the tester exactly what to do and what to expect If this description doesn t work or is ambiguous in any way the tester should consider the test to be DE FECT and report it in Issuezilla This is probably best written like this
208. ter for here Furthermore you can add a listener that is interested in several types of events but coming from model element This is a convenience method for not having to call the methods explained in section Sec tion 5 1 3 2 1 How do I register a listener for a certain type event more than once It works via 40 Inside the subsystems addModelEventListener PropertyChangeListener listener Object modelelement You can pass the method an array of strings with event names in which your listener is interested 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 im pacts Therefore use it with care The method is addClassModelEventListener PropertyChangeListener listener Object modelClass 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 Of course you can remove your listeners from the event pump This works with methods starting with remove instead of add 5 1 3 3 Tips 1 Don t forget to remove your listener from the event pump if it s not interested in some event any more 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 se
209. tions This is solved by a clear interfaces between the ArgoUML core and the extensions Extensions are called modules 6 2 1 Differences between modules and plugins s gt Note This description is only relevant for the old moduleloader since the plugins concept is not used in the new one In the old moduleloader implementation the classes within the modules that attach to ArgoUML core are called plugins In the new moduleloader implementation they don t have any special name e Modules A module is a collection of classes and resource files that can be enabled and disabled in ArgoUML Currently this is decided by the modules availability when ArgoUML starts but in the future it could 90 Extending ArgoUML be made possible to enable modules from within a running ArgoUML This module system is the extension capability to the ArgoUML tool It will give developers of ArgoUML and developers of applications running within the ArgoUML architecture the ability to add additional functionality to the ArgoUML environment without modifying the basic ArgoUML tool This flexibility should encourage additional open source and or commercial involvement with the open source UML tool The module extensions will 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 t
210. tories of argouml documentation cookbook manual and quick guide each contain one of the three books The subdirectory docbook setup contains two things It contains the configuration files that control how the generation is done It contains the XSL rules for all the genera tion The subdirectory images contains all the required pictures for all the books When in the documentation you run build sh defaulthtml or one of the other targets that builds the documentation all books are built What happens is the target internal dispatcher e The manual argomanual xml is copied by ant to manual argomanual gener ated xml1 while doing substitution of tokens VERSION to become the version as specified in default properties e The file manual argomanual generated xml is processed by the special docbook setup create imglist xs1 xsl script that generates a list of included images e All included images are copied The purpose of this is to only get the images actually used copied with the document that uses them and not all images e The HTML is generated by processing the file manual argomanual generated xml The file manual argomanual generated xml is a temporary file that only exists while pro cessing the XML If editing the XML with a DocBook editors you open the file manual argomanu 20 Building from source al xml and edit the unsubstituted file The differences between the unsubstituted file and the substi tuted
211. try point when starting ArgoUML Responsibility to start the ball rolling The Application is located in org argouml application The entry point is called org argouml application Main 5 11 1 What is loaded initialized It all begins in org argouml application Main set up main application frame org argouml ui ProjectBrowser the project org argouml kernel Project numerous classes and finally as a background thread cognitive support org argouml cognitive Designer and some more classes The ProjectBrowser initializes the menu tool bar status bar and the four main areas navigation pane org argouml ui NavigatorPane editor pane org argouml ui MultiEditorPane to do pane org argouml cognitive ui ToDoPane and details pane org argouml ui DetailsPane Then the actual project is set to either a read from file project see ArgoParser SINGLETON readProject URL and Ar goParser SINGLETON getProject in org argouml xml argo ArgoParser or a newly generated project see Project makeEmptyProject 5 11 2 Details pane Currently May 2003 the Details pane contains several tabs Property Panels See Section 5 4 Property panels Critics explanations and wizards belonging to the Critics subsystem See Sec tion 5 2 Critics and other cognitive tools Documentation Style Source Constraints an OCL con straints of the current object See Section 5 19 OCL and Tagged values Warning It is not clea
212. und O public void setUpper Bound int newBound public final String get Property protected final int get Modell final final ElementSize Object getTarget UMLUserInterface Container getContainer public int getSize public Object getEle mentAt int index Called when the number of elements in the displayed list including none may have changed Default invokes the neces sary Swing operations to advise of a change in list size Called when the navigation history has been changed and naviga tion buttons may need changing Not clear why anything is needed but default recomputes the list size and invokes the ne cessary Swing operations part of the NSUML EventListener interface Called when an add event happens i e some NSUML object has been added The de fault provided looks to see if the event is the role name we de clared 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 part of the NSUML EventListener interface Called when a re move event happens i e some NSUML 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 these are all required as part
213. vate members Warning e Unused code gt Unnecessary semicolon Warning e Unused code gt Unnecessary cast or instanceof operation Warning e Unused code gt Unnecessary declaration of thrown checked exception Warning 9 7 4 Settings for checkclipse 9 7 5 Checkclipse is a plug in for Eclipse which needs to be installed separately It enables style checking ac cording the rules set for the ArgoUML project 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 gt Properties select Checkclipse appears only if Checkclipse is correctly in stalled and then fill the fields like this Enable Checkstyle Checked Checkstyle Configuration File argouml tools checkstyle checkstyle_argouml xml Checkstyle Properties File argouml tools checkstyle checkstyle properties File Filter Definition argouml tools checkstyle checkclipse filefilters Leave the two other fields empty Run the JUnit tests There is perhaps some fancy way of doing this but while we figure that out this revert to ant way can be used to run the tests 123 Standards for coding in ArgoUML 1 Inthe menu select Window gt Preferences Select Ant gt Runtime at the left hand side Select the tab Classpath Select Ant Home Entries 2 Press the Add Jars button and add optional jar from argouml tools ant 1 4 1 3 Press the Add Jars button a
214. ven element is valid i e it may be added to the list of elements This function is called for many UML ele ments 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 The following are sometimes provided as an override of the parent although for many uses the default is fine public void open int in dex public boolean build Popup JPopupMenu popup int index Perform the action associated with the open pop up menu on the element at the given index The default provided in the parent just navigates to that element 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 giv en index in the list This is built using UMLListMenuIten which can record the index rather than plain JList Item 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 62 Inside the subsystems invoked on the given element The default implementation always returns true The following should be declared as needed to support particular pop up functions public void add int in
215. vigator Tree 83 Notation 49 NSUML 7 understanding 97 O Object Explorer 83 OCL 88 P Persistence 67 Pluggable interface 86 prepare docs ant target 10 Priorities on Issues 131 Processes 130 Property panels 53 PropertyResourceBundles 75 R Repository contents 108 Resolution of Issues 131 Resolving Duplicate Issues 136 Invalid Issues 136 Rejected Issues 136 Wontfix Issues 136 ResourceBundles 74 Reverse Engineering 68 Java 69 Roles 133 Round trip Engineering Java 69 run ant target 9 run with test panel ant target 14 S Saving Loading 67 Standards Coding 112 CVS 104 subproducts 137 subsystem 31 T Test cases an example 15 writing 13 Testing ArgoUML 13 13 tests ant target 13 To Do Items 83 Tools needed for building 5 used 6 Translators 75 Troubleshooting committing changes 13 development build 13 during the release work 25 U Unit testing of ArgoUML 13 13 Unix compilation 9 V Verifying Works for me Issues 136 W Web Site documentation 19 maintaining 18 Windows Compilation 9 Wizards 44 Workers 133 Writing test cases 13 X XSL style sheets 6 140
216. w an excep tion to this rule for methods attributes and classes that are not See Section 4 2 Relationship of the subsystems Write deprecation statements like this deprecated by your name in the upcoming release Use link whatever i a complete explanation on what to do instead This is not checked by Checkstyle 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 De precation shows the intent between decision to remove a method and the point where it is actually 113 Standards for coding in ArgoUML 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 Don t use deprecated methods or classes 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 Rationale 2 If you f
217. world Soon we want the tool to do more for us We should then be able to wish that and eventually get an updated sub product Notice that we should not and don t need to do this in a passive way We should explain to the sub product team what we want and why Especially for sub products that we have already in ArgoUML but also for project that we consider taking in This is to increase the likelihood that they will have us in mind when planning and evolving Here are the steps to go through and the recommended order once the decision is taken to use the sub product in ArgoUML Documentation Describe in the Cookbook in the appropriate subsystem section what part of the problem that the sub product solves and how it is used in ArgoUML Javadoc Enter the package list file in a special directory under argouml 1lib javadocs Update the list of links used when building the Javadocs One place in default properties One or two places in build xml targets javadocs and javadocs api 116 Standards for coding in ArgoUML Test by referencing some class from the sub product building the Javadoc and check that the link is working e Repository Assuming that the sub product is distributed in a set of jar files add the jar files to the 1ib directory in a versioned way together with the license file Use filenames like subproduct version jar and subproduct LICENSE txt A future plan is to have each subsystem in their own d
218. xample they contain methods to get all model elements of a certain class out of the model see getAl1Modelelement sOfKind in ModelManagementHelper To find a utility method you need to know where it is As a rule of thumb a utility method for some model element is defined in the helper that corresponds with the section in the UML specification For example all utility methods for manipulating classes are defined in CoreHelper There are a few exceptions to this rule mainly if the utility method deals with two model elements that correspond to different sections in the UML specification Then you have to look in both corresponding helpers and you will probably find what you are searching for Question Am I allowed to call the helpers from any thread Answer The current checks are not written to allow for multiple threads so don t The model event pump Introduction 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 1 The model factories responsible for creation and deletion of model elements 2 The model helpers responsible for utility functions to manipulate the model elements and 3 The model event pump responsible for sending model events to the rest of ArgoUML 38 Inside the subsystems The model factories and the model helpers are described in Section 5 1 1 Factories and Section 5 1
219. y how we use Issuezilla Get the Observer role granted From this on you can comment on bugs yourself directly in Issuezilla You can also verify issues according to the verification process see Section 12 5 How to verify an Issue that is FIXED This will help you understand the terminology used in the project and also gives you an idea of the current quality of ArgoUML and what needs to be done in the future This is also a very low commitment level task that could be completed in a couple of minutes depending on your choice of issue Read the rest of the Developers Cookbook There is a lot of stuff discussed in here that is interesting for your understanding of the project and the code Check out the source from CVS and build Subscribe to the dev list The purpose of this is to see what the developers are discussing in the project Monitor the discussions and as soon as you see something discussed where you have an opinion jump right in Familiarize yourself with the code For this a good knowledge of Java is more or less a prerequisite Suggestion on how to go about this a b Take active part in the discussions on the dev list Solve issues registered in Issuezilla Convince someone to commit your changes Establish a relationship with one developer that has volunteered to help you with the commits That developer will check that your code reaches the quality level that we strive for in the projec

Cookbook for Developers of ArgoUML

Contents

Download Pdf Manuals

Related Search

Related Contents