Home

Cookbook for Developers of ArgoUML

1. sss 38 5 3 DIARAMS ERE EDITT 38 5 3 1 How do I add a new element to a diagram ssssssss essa eens eeaeeees 39 5 3 2 Howto add new Fig 5 seo NS AE eer ete erc EE 39 54 Property panels x 3 vos sister vaumacstereedeo betonte eene eorr aea te ro edi EEEE EPESA evo EONS erbe ped oor 41 Cookbook for Developers of ArgoUML 5 4 1 Adding the property panel stoeie e E emen enhn mentre 41 3 9 Reverse Engineering Component 5 Edere teo tive ie lese et t dev Ae ae Nea 54 5 6 Code Generation Component erre ere ER eR dae eR e nee eden ea D A EE e ERE Un 55 5 7 Java Code generations and Reverse Engineering sesesseeeee HH 55 2 2 1 OW dO Lsn k eoi dee ee e perro terr tue 55 3 7 2 Which sources ate involved ii bei ee EIE Ee ETE FOR PG aes 55 5 7 3 How is the grammar of the target language implemented 0 20 00 cece cece eee eese 55 5 7 4 Which model diagram elements are generated sss 55 5 7 5 Which layout algorithm is used sss HH emere 56 5 8 Other languages oi cess i t rete eio o Gatto re EE ses bared sas dette Pes battens EEEE 58 219 The GUL Framework esasen esce ges fh setts ero oto erogare dese dopo oreet ione dedu pur eos Per ces 59 5 9 1 Multreditorpane DOR tee uie ee ERES 60 25 922 D tails pane isset e fecit ete Meade oe fe e TOPLESS e Coe INE Meola o dee Ee E 61 2 T0 Help System oe EN e Ie e p ete re et bes
2. 2 As soon as the model element changes then all views shall update For text fields this can be at every key stroke REQ2 REVI 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 3 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 REVI Rationale An exception in the log or on the screen is always the sign of a serious error in the application that should be reported as a DEFECT If a mistyping generates such a problem the user might loose interest in Ar goUML as a tool because he percieves it as not working correctly Stakeholder User of ArgoUML 4 All text fields shall have context sensitive help 19 ArgoUML requirements As follows a 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 b Pressing F1 or choosing help from the menu shall display a popup window explaining for data and format required by the current input field Input focus shall be left on the field during any user interaction with the popup dragging scrolling or closing REQ4 REVI Rationale Throughout a complex application like ArgoUML there are lots of text fields Un
3. How to resolve an Issue This can be performed by any member of the project any role Persons without the Developer role need a person with the Developer role to actually commit the work if the resolution involves changing some artefact There might be special skills involved but it differs widely depending on the nature of the Issue Do the following l 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 is sue_status REOPENE http argouml tigris org issues buglist cgi component argouml amp issue status NEW amp D 2 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 3 Accept the Issue and reserve it by assigning it to yourself Set the Target Milestone to the release you have cho sen 4 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 5 Mark the issue as Started this could be done while assigning also 98 Processes for the ArgoUML project 6 Change the code to solve the problem 7 Compile and test your new code This should include developing a
4. ssssssee meme enm enne mennee 72 S O GEMENS 72 osExtending ArgoUML uro etre ettet etr a o used soe Cet oe eati oto do teo ioeo quee dete vean DR dean tester Cede eo OSL OW dO ee 2a ux ep E UERSUM exito uec et o A a eve esso ro etse US 73 6 2 Modulesand Pl gIns nesmen ree eere eret e eot eee nro e Pe Uie rene ees see N Ue oy ordre pu Da es ar 73 6 2 1 Differences between modules and plugins sese 73 AM PD 74 6 2 3 PIM GING oo eee Ed duse DS es WA RY diate 75 6 2 4 Tip for creating new modules from Florent de Lamotte eeeeeeee 78 6 3 How are modules organized in in the java code sssesssss sean eeaes 79 6 3 1 2HoW dol 2 ice er C Eee EOS ETE E PRO Ree e br ERR EEI ER SS POE Dh gi 79 7 Organization of ArgoUML documentation 0 cece ceec cece cece cece eem e ee me men me he mee eree rennen 82EVS in the ArgoUML project de terere Erie a e dp eee Parere IPESE Ex IR deo RR TREES 8 1 How to work against the CVS repository sess IH hehehe 82 8 2 Creating and using branches ce eL Ie ERA ete da eds 83 8221 HOW CO RT MT 83 8 3 Other C VS comments ente eee epi ve repa deett TE deae teo ied te deque pae de Lee gea 85 8 4 CVS xepository contents serie eie eh ier Serve oe ae ubl eese ae eie Meena E EIL oe E NER Ten EN 86 9 Standards for coding in ArgoUML otan e i a E eem e me men en mhe hes hene ren rent men t enne nne 9 1 Settings tor Eclipse od eret reet oo o
5. If you need to attach other already existing modelelements to your modelelement make a 33 Inside the components buildXXXX 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 always have initialized mod elelements 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 2 5 Creating a new Fig explanation 2 e create a new create method Create it in the correct factory e create a new utility method 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 Layer 3 component See Section 4 7 Layer 3 Description of components The Critics component depends on the Model that it works against to take all decisions and the To Do Items used to present the information This component contains the following main class types Critics provide help to find artifacts in the model that do not obey simple design rules or best practises 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
6. These are basic critics which are very general in nature For example Argo ments overlap which makes the Diagram hard to read This package also contains the base classes for the handling org argouml uml cognitive critics UML keeps nagging when Modelele 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 e 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 agains modelling 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 Knowledg org argouml cognitive ui 5 2 2 How dol e create a new critique e Types are located in the package 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 of java code in the future as a set of rules instead Create a new critic class of the form CrxxxxYyyyZzzz
7. 2 3 Build PROCESS ices er edere pe Po cepe dee Pee Ud e C RUN D RP oe ue ee 6 2 3 1 How ANT is run from the ArgoUML development environment eene 6 2 3 2 How documentation is presented sss hene nme nme 8 2 3 3 Troubleshooting the development build sse 10 2 4 The JUnittest cases se DE ee Rd n e Se Das WE Pe qe sed oS weeded RUE 10 2 4 SHOW tO Write a TEST Case 1 eer eere ten dee teo eor teneor eer E ue Des ee HE due bo Nen eH EET EF P PR A dre vo 11 25 Manual Test Cases Et 13 2 5 1 Running the manual tests riti t rede ett ses a T a E Ene tede 13 2 5 2 Writing the manual tests esses e ee ee meme hee hen ent entree 13 2 5 3 The list OF feSIS eren rtr e ttp tere OEE eE OEE ei EREE PRESE POSESIE PNE SEST 14 2 6 Making arelease 2 ee br Eve ere eee der DE Se E odes se e geen eed e dera R RE gees 15 2 6 1 The release dad not Work 3 ri emet re mte Ere Stag ask E ga SERRE Ene UB 18 3 ATSOUME requirements seseo conten DE rete ages wane Ure ten urea E gus e o e Se RE URP R e REO die ave D oe E Exx ep ERE OPER 3 1 Requirements for Look and feel esses enne m ennemi hen nne 19 32 Requirements Tor UML 2 1d ie eese teat decent o brsaesee dens t edu Ur dex a ao Eo tes 20 3 3 Requirements on java and JVM i meni cece ee cee cence Ie ee ee hene ene eet eet ente enr e nennen 20 3 4 Requirements set up for the benefit of the development of Ar
8. extending CrUML Typically your new class will go in the package org argouml uml cognitive critics but it could tive critics packages Write a constructor which takes no argouments and calls the following met e setResource CrxxxxYyyyZzzz to set up the locale specific text that appears in the to do pane and the critic description the detailed tab of the details pane go in one of the other cogni hods of CrUML for the critic headline the one liner explanation that appears in the to do e addSupportedDecision CFUML decAaAAAa where AAAA is the design issue category this critic falls into examples include STORAGE PATTERN METHODS setPriority ToDoItem 5BB PRIORITY where BBB is one of LOW MI EDIUM or HIGH to set the priority for 36 Inside the components the critic in the to do pane e addTrigger UML MetaClass where UML MetaClass is a UML MetaClass with initial lower capital e g associationEnd The intention is that critics should only trigger for elements or children of particular UML metaclasses I Jeremy Bennett february 2002 believe this code is not yet working so you can proba bly leave it out You can have multiple calls to this method for different metaclasses After this add a method public boolean predicate2 Object dm Designer dsgr This is the decision routine for the critic dm is the UML entity an NSUML object that is being checked The second argument dsgr is for
9. Description of components These components are primarily connected through the pluggable interfaces meaning that they can be individually disabled using the module loader 27 ArgoUML Design The Big Picture Java Code generation Reverse engineering This is the ArgoUML connection to the java language The Java Component is described in detail in Section 5 7 Java Code generations and Reverse Engineering Other languages Code generation Reverse engineering Languages are plugged into the notation the import reverse engineering and code generation See Section 5 8 Other languages Critics and checklists This is the critics The Critics Component is described in detail in Section 5 2 Critics and other cognitive tools OCL This is the editing of the OCL strings The OCL Component is described in detail in Section 5 17 OCL Other languages pet To do Items 28 Chapter 5 Inside the components e Warning This chapter is currently under rework with new component organization 5 1 Model Purpose to provide the data structures that keep track of the model and the diagrams This comes with a complete set of methods to modify the model and register interest in changes to the model The Model is located in org argouml model The Model is a Layer 1 component See Section 4 5 Layer 1 Description of components This is implemented using NSUML to implement the UML model Argo
10. Doacvs 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 commited 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 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 inconsistant 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 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 82 CVS in the ArgoUML project Rationale These ground rules is for the purpose of not stopping or hindering the work for anyone Remember that there might be several developers working with different agendas and different efficiency slower or faster and the commits is the melting point of this Perspective If this will take you an extra two
11. JMenuItem getDiagramMenuItem return 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 diagram Important Don t forget to do the localization stuff because the plug in might be used in all languages Ar goUML offers e do the localization stuff not plug in specific but important e create a pluggable resource bundle e 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 pack age The class name must begin with Pluggable Note One of the main purposes of a plugin is to provide the capability to add an externally defined class that will be used by ArgoUML in the same way as a similar internal 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 77 Extending ArgoUML public boolean initializeModule public boolean shutdownModule public void setModuleEnabled boolean tf public boolean isModuleEnabled public String getModuleName public String getModuleDescription public String getModuleVersion public S
12. MUST READ for everyone concerned about ArgoUML Be careful though since it is based on an old version of ArgoUML but many of the concepts remain intact 10 1 1 Abstract Software design is a cognitively challenging task Most software design tools provide support for editing viewing storing sharing and transforming designs but lack support for the essential and difficult cognitive tasks facing de signers These cognitive tasks include decision making decision ordering and task specific design understanding To date software design tools have not included features that specifically address key cognitive needs of designers in part because there has been no practical method for developing and evaluating these features 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 re spect to the cognitive theories that inspired it and the set of features is evaluated with a combination of heuristic and empirical techniques 10 1 2 Where t
13. 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 Wiz ards 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 34 Inside the components M Critico H getCriticKey0 ConfigurationKe y H getC riticCategoryd String H getCriticName 0 String H critique dm Object dsgr void postite miite m dm Object dsgr void predicate dm Object dsgr boolean stillValid i dsgr boolean supportsid boolean H getSupportedDecisionso Vector H addSupportedDecisionid void H supportsig boolean H getSupportedGoalsQ Vector H addSupportedGoalig void H containsKnowledge Type type String boolean H addKnowledge Type itype String void getKnowledgeType sO VectorSet setKnowledge Type sikt VectorSet 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 addT rigge ris String void matchReason patte rnCode long boolean ex pandide sc String offs VectorSet String H getC larifie rd Icon from org argouml cognitice critics H addControlReciname String controlData Object Object H getControlRec nam
14. are also provided in the parent They are not normally overridden public public int getUpperBoug t any upper bound 1 is used if there is none void setUpperBosetihenppeebbund gl is used if there is none 51 Event pl PO Inside the components public final String ger tunpsetheyNSUML event name being monitored null if all are being monitored protected final int getetursEHiesmantler zf lements in the list Invokes recalcModelElement Size see above if necessary final Object getTarget returns the NSUML object associated with the container some child of PropPanel usually that holds this list model final UMLUserInterfaceteturnsithe the eodtaineri seme child of PropPanel usually that holds this list model public int getSize returns the size of the list Including if there are no elements in the model but the list has a default text when empty public Object getElememetnrnsithe element at the given index in the list static protected Collebelpsnim wtitingr tlie Cadd 5 frictions Inevditam cis iaddedMaMothel speer amp ed index terthe int index given oldCollection static protected java helps iniwritinguhetmove ap fanctiom Swapo theeelements tioffsetsdndex and in dex 1 Not clear why it doesn t return a Collection static protected java helps ihiwritingvehecwmove down function Swaps the el meantsiattoffseie index and index 1 Not clear why it doesn t return a Collection sta
15. are no Issues left 11 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 INV ALID RESOLVED WONTFIX and RESOLVED DUPLICATED issues resolu 100 Processes for the ArgoUML project amp resolution WONTFIX amp resolution DUPLICATE Read through the description provided Do one of the following Ifyou agree with the statement and feel that the rejection is done for correct reasons put the Issue 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 Do this as many times as you like until there are no Issues left 11 7 How to Close an Issue 11 8 ucts 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 project any role This can also be done by someone who would raise the issue but did not be cause it was already present in Issuesilla Pick any Issue that is Verified and that you have raised or that you have found and refrained from raising be cause somebody else already had written it The list of al
16. be joined by a dotted arrow labelled extend to show that one extends the behavior of the other The classes involved in this particular example have all been well commented and have full Javadoc descriptions to help when examining the code You will need to read the description here in conjunction with looking at the code 5 3 2 How to add a new Fig The new item must be added to the toolbar Both the graph model and diagram renderer for the diagram will need modifying for any new fig object 5 3 2 1 Adding to the toolbar Find the diagram object in um1 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 dia gram ui UMLDiagram java Each toolbar action is declared as a protected static field of class Action initiated as a new CmdCreateNode 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 example in UMLUseCaseDiagram java we have the following for creating Use Case nodes protected static Action _actionUseCase new CmdCreateNode MUseCaseImpl class UseCase The first argument is the class of the node to create from NSUML the
17. extend it Be a collection of knowl edge around how every thing is set up Be a store Description of the func tions of all classes all public and protected methods variables and constants Instructions on how to add new functions and behavior Instructions on how to do the chores around maintenance build a release publish a release build the docu Developers writing code of the agreed solution 80 Organization of ArgoUML documentation Bit Audience Main purpose Contains around fundamental de sign decisions i e design decisions that are so big that it is meaningless to store them in the javadoc Be a collection of knowledge around how and why the project makes certain decisions mentation part of the re lease test ArgoUML test the documentation Agreed project rules like what level of quality is aimed for and descrip tion of processes that achieves that level The web site in CVS Everyone i e developers 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 docu mentation Be the main download area for the ArgoUML product Be the central point of the ArgoUML user commu nity Be the central point of the ArgoUML devel opment project References to all the other parts of the docu mentation Current project informat
18. future development and can be ignored The Critic class conveniently 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 appropriate Having written the code you need to add the text for the headline and description to the cognitive resource bun dles These are in the package org argouml i18n in the file UMLCognitiveResourceBundle java You need to add two keys for the head and description which will be named respectively CrxxxxYyyyzzzz head and CrXxxxYyyyZzzz desc There are plenty of examples to look at there The other files UMLCognitiveRe sourceBundle_en_GB java UMLCognitiveResourceBundle es java for British English Spanish respectively are the responsibility of the corresponding language team Notify the language teams that there is work to be done In method rnit of the class org argouml uml cognitive critics Init add two statements public static Critic crXxxxxYyyyZzzz new CrXxxxxYyyyZzzz 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 a
19. 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 relationship in PropPanelExtend The model behind the drop down is created by using UMLCombBoxModel UMLCombBoxModel container predicate event 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 comboBox of type baseClass setter with a single argu ment of type baseClass sets that entry allowVoid if true will allow an empty entry for the box baseClass is the NSUML metaclass from which all entries must descend useModel is true 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 setBase true MUseCase class true and we define the methods isAcceptableUseCase getBase and setBase in PropPanelExtend 5 4 1 6 How UMLTextField works This information is provided by Jaap Branderhorst September 2
20. hard way try the following steps Edit gt SettingsEnvironments argo ext dir 79 Chapter 7 Organization of documentation Linus Tolke ArgoUML This chapter contains written down ideas on what goes into what part of the documentation These ideas are formu lated by Linus Tolke There are seven significantly different bits of documentation in the ArgoUML project By documentation I mean some information of the product that is developed alongside the product and that has a persistant value 1 The code variablenames class names 2 The javadoc 3 The cookbook 4 The web site in CVS 5 The manual and quick guide 6 Help texts within the running ArgoUML 7 The FAQ 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 The code 1 Other developers that will maintain and improve on the code 2 The compiler Implement ArgoUML in a maintainable and un derstandable way See Chapter 9 Standards for coding in ArgoUML for more information The javadoc The cookbook Developers writing code that communicates or in other ways interact with this class maintaining the docu mentation or the web site Make it easy to see what the functions of every class are and how to use them Make it easy to learn how ArgoUML works and how to
21. have precedence over the properties in argoum1 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 environment remove these files temporarily for the compiling and testing you do just before you commit Building from source 2 3 1 4 Building javadoc By running ANT again using build prepare docs the javadoc documentation is generated and put into argoum1 build javadocs 2 3 1 5 Building one of the 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 argoum1 src_new directory b Runthe module This is done with ant run command in the argoum1 modules whatever directory 2 Test several modules together a Build argouml the package This is done with ant package in the argoum1 src new directory b Compile and install the modules This is done with ant install command in each of the argoum1 modules whatever directories c Start argouml This is done with ant run in the argoum1 src_new directory This will start ArgoUML with all modules available 2 3 2 How documentation is presented This describes how the documentation arrives on the web site 2 3 2 1 How the ArgoUML web site works Tigris provides the
22. in your uml model ArgoFacade is reused by GeneratorJava and TabConstraints Currently this component is more or less only Dresden OCL Toolkit and adaptation Because of a problem with the interpretation of the UML specification and the OCL specification the implementa tion of constraints in ArgoUML is only possible for Classes Interfaces and Features Attributes and Operations See Issue 1805 http argouml tigris org issues show bug cgi id 1805 72 Chapter 6 Extending ArgoUML This section is not yet updated to discuss layers This section explains some general concepts which come in handy when programming in ArgoUML 6 1 How dol get the according NS UML element for a given Figxxx class Each Figxxx implements the method getowner which returns the appropriate owner element which is re sponsible for this Fig element get the according Fig element for a given MModelElement for this one needs to iterate through all fig elements and invoke getOwner Compare the result with the given MModelElement Beware that there might be more than one Fig Element per MModelElement 6 2 Modules and Pluglns This section is not yet updated to discuss layers 6 2 1 Differences between modules and plugins The ArgoUML tool provides a basis for UML design and potentially an executable architecture environment for other applications This is solved by clear interfaces between the ArgoUML core and the extens
23. initializeModule should initialize any required data and or attach itself 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 initial ization 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 74 Extending ArgoUML from the file void shutdownModule void The shutdownModule 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 for future implementation The plan is to have this called for each module when the module should add its entries in PopUpActions e String getModuleKey void Returns a string that identifies the module 6 2 2 3 Using Modules When modules are used they can t be distinguished from the rest of the ArgoUML environment 6 2 2 4 How dol e create a module tell when a module is loaded 6 2 3 Plugins 6 2 3 1 Plugin Architecture Each class must derive from the P
24. issue stating which one of the subprojects that is the problem and what the problem is 3 Posta bug in that subproducts bug reporting tool or find the bug already registered I am assuming that there is such a tool for all the subproducts If there isn t for the product in question then ex plain the problem to the responsible person for this product so that we are sure that the problem is communi cated 4 Set the Issue in Issuezilla to RESOLVED WONTFIX and enter the reference from the subproducts bug report ing tool and if possible the URL to the bug reporting tool or to the bug in question The person responsible for the sourceing of the subtool in question Currently December 2002 the subproduct re sponsible role is not explicitly pointed out but could be anyone that feels that something must be done does the fol lowing for each new release of a subproduct 1 Looks at the new release of that subproduct to see if any of the outstanding issues against that subproduct are in fact fixed in the release 2 If any of the issues are fixed then he weights together the importance of the issues fixed 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 other issues promised to be fixed and the current release plan of ArgoUML From this he decides wether it is time to do the update of the subproduct within ArgoUML or to wait 3 f he decides that it is
25. like public MODELELEMENT buildMODELELEMENTNAME params Each build method verifies the wellformednessrules 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 wellformed UML can lead to non wellformed 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 create methods in the factories You are strongly advised to use a build method or if there is none that suits your needs to build one thereby reusing the allready existing build meth ods and utility methods in the helpers One reason for this is that the eventlisteners for the newly created modelele ment are setup correctly TODO Am I allowed to call the factories from any thread 5 1 2 Helpers The helpers contain all utility methods for manipulating modelelements For example they contain methods to get all modelelements of a certain class out of the model see getA11ModelelementsOfKind in Modelmanagemen tHelper To find a utility method you need to know where it is As a rule of thumb a utility method for some modelelement 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 modelelements th
26. minutes before every commit remember that if you commit something that will not work this will take everyone else guess 10 persons the extra time of looking at the compilation error or see the tool crash 1 minute wonder why 1 minute search for the error in his own changes 3 minutes search for the error somewhere else 1 minute glance at the mailing list to see if someone else has noticed this and send a mail 1 minute wait for some response 1 hour wait update 1 minute compile 1 minute This amounts to 10 hours wait and 1 5 hours extra work for all developers in the project 8 2 Creating and using branches We use the following standards in ArgoUML e Released versions get the tag VERSION X X X 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 explanationis something like javahelp propertypanel cppcodegeneration owner is a self explaining code for the owner of the branch e g tlach Thierry Lach or mklink Markus Klink Merging branches together is causing some work So please use them sparingly and announce your intentions before on the mailing list 8 2 1 How dol e commit stuff You have made the change tested it and are satisfied with it Do a cvs update d and see that only the files you have changed
27. option to the pop up menu allowing connection to existing model ele ments used for the Extension Points field for example e A set of check boxes for modifiers Supported by the PropPanelModifiers class 42 Inside the components Examples of these in more detail now follow 5 4 1 1 Adding a simple list field For example we need to add a field to the use case property panel for the extends relationships that derive from this use case This field consists of a label and a scrollable pane 8crollPane containing the list JList possibly empty or extends relationships from this use case ti H Rather than a straight JList we use its child UMLList which implements the MouseListener and NSUML ement Listener interfaces The constructor for UMLList requires two arguments a list model and a flag to indicate whether the list is naviga ble i e responds to the mouse The list model should be a subclass of UMLModelElementListModel a subclass of the Swing AbstractList Model that implements the NSUML ElementListener interface 5 4 1 1 1 The list model In our example we create UMLExtendListModel Its constructor should take three arguments 1 The container where this list is being built Le the PropPanelUseCase from which we can then derive the NSUML MuseCase which is the target of the extends relationship 2 A string naming an NSUML event that should force a refresh of the list
28. org argouml language java The Java component is a Layer 3 component See Section 4 7 Layer 3 Description of components How dol 5 7 2 Which sources are involved 5 7 3 The package org argouml uml reveng is supposed to hold those classes that are common to all RE packages At the moment this is the Import class which is mainly responsible to recognize directories get their content and parse ev ery known source file in them These are only java files at the moment but there might be other languages like C in the future With this concept you could mix several languages within a project The DiagramInterface is used to visualize generated NSUML metamodel objects 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 How is the grammar of the target language imple mented It s an Antlr http www antlr org grammar based on the Antlr Java parser example The main difference is the missing AST Abstract Syntax Tree generation and treeparser 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 7 4 Which model diagram elements are generated The context classes hold t
29. process Tools also have the readme files licenses and other distribution files stored in this directory in much the same way as the libraries in 1ib 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 al low distribution Quick summary BSD License Apache license LGPL GPL Freeware are OK WWW This is all the static contents of the web site See Section 2 3 2 1 How the ArgoUML web site works 88 Chapter 9 Standards for coding in ArgoUML The coding style for ArgoUML is the following Each file starts with some header info file version info copyright notice classes in this file if more than one original author if you want Like this Id Copyright c 2003 The Regents of the University of California All 7A taxed Classes blabla blabla all classes of interest in this file Original Author who ever All instance variables are private and their names begin with an underscore If the variable should be accessible then add public or protected accessor methods with the same name as the variable without the underscore with get or set prepended For example _lineWidth setLineWidth and getLineWidth In general write short code If a method will fit comfortably on one line then put it on one line Use javadoc for each class instance variable and me
30. shall be translated This begins with this Cookbook then the Developers part of the ArgoUML web site and also includes the javadoc comments in the code of ArgoUML and design documentation of included packages such as GEF NSUML We don t do this in the ArgoUML project 5 11 3 How dol 63 Inside the components Verify that all translations are up to date Run checkstyle Search for comments on keys start a new Language Team The Language Teams are loosely defined by the web page of language teams on the Tigris site As soon as the language code and names at least one are in place the team is created From that point it is the Language Teams responsibility to do a good job find the languages internationalization code for the language you will add en es en GB The one you are currently using is shown in the log when ArgoUML starts Search for lines looking like Lan guage sh Country unknown Start the work Look at the files in org argoum1 i18n under argouml1 src new Translate all the texts in each of these classes of files This is a lot of extremely qualified work including searching well known litterature on UML and Software Engi neering in order to get the correct terms for the domain Discuss with other UML and Software Engineering pro fessionals with the same native language to get it right Create the files with the translations and store them in argouml src new org argouml ii18
31. time to update he adds the new version of the subproduct does all the needed work within ArgoUML tests and commits everything puts the issues indeed fixed in VERIFIED WONTFIX and also closes the bugs registered in the subproducts bug reporting tool 102 Index E A ANT 4 6 6 how it 1s used 6 ANTLR 4 ArgoUML Design 23 H build xml 6 l Building 4 6 8 ArgoUML 6 javadoc 8 tools 4 Check lists 34 Checking out from CVS 5 checklists 28 Code Generation 27 55 Code generation 55 Java 55 Coding Standards 89 Compiling 7 7 7 7 7 7 argouml build properties 7 build properties 7 customized 7 Cygwin 7 Unix 7 J Windows 7 Constraints 72 Contents of the CVS repository at Tigris 86 Critics 28 34 CVS 3 5 82 82 83 branches 83 checking out from 5 how to work with 82 Mailing list 3 standards 82 L CVS repository contents 86 Cygwin Compilation 7 Details Panel 59 Developers Mailing List 3 Diagrams 27 38 Docbook 5 M Documentation 8 10 work with 10 Dresden OCL Toolkit 72 Explorer 27 fop 5 GEF 5 GUI Framework 26 59 Help system 26 61 I18n 25 61 Internationalization 25 61 Issue 95 96 Priority 95 Resolution 96 Issues 3 94 98 99 99 99 100 100 100 100 101 Closing 101 Mailing list 3 Resolving 98 100 100 100 100 Duplicate 100 Invalid 100 Rejected 100 Wontfix 100 Verifying 99 99 99 Fixed 99 Works for me 99 WORKSFO
32. to d Move all issues reported on current to this release 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 e Other stuff This can also be a good time to change all RESOLVED REMIND and RESOLVED LATER Search for them and Reopen them Update the web page The Lists of Issues http argouml tigris org documentation issuezilla frequentlyusedlists html page contains a link to each version and needs to be updated Make announcements Write a News announcements and a short note on the dev users and announce lists Announcer should make sure that he she is already subscribed to all lists with a reference to the news item The announcement shall include a statement on what kind of release this is information on what has changed for stable releases this is a list of what has changed since the last stable release 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 Freshmeat currently Thierry Lach does the freshmeat announcements which require a login so just inform him 17 Building from source 2 6 1 The release did not work This shouldn t happen This really shouldn t happen The reason that this has happened is th
33. to be highlighted 3 model changed the tree must update to reflect additions deletions and name changes in the model 5 15 3 Key Classes The Explorer contains Swing components and there is currently no abstraction layer to help implement a IDE plu gin for example There is a JTree subclass DisplayTextTree for the tree with a TreeModel Perspective The Perspective is made of several Go rules this enables Argo to convert the graph like structure of a uml model into a tree and it is easily extensible 70 Inside the components I I I I I I l PerspectiveSupport JAbstractGoRule i 3 I I I I N subTreeModels ETA PCT N DisplayTextTree DnDArgolJTree DefaultTreeCellRendere UMLTreeCellRendere There are several different ways of implementing a TreeModel in Swing ArgoUML already has a model the NSUML MModel instance so we create a class NavPerspective that encapsulates the MModel instance and implements TreeModel contains methods that enable the JTree to calculate the tree structure This implementa tion does not build load a tree model on instantiation rather it provides children nodes for any given parent node when the user requests a node expansion The NavPerspective delegates the task of calculating child nodes to the Go rules making the tree model very flexible However the price for this at the moment is slow node expansion times for large mode
34. 002 UMLText Field implements several kinds of event listeners e MMelementListener DocumentListener 53 Inside the components e FocusListener Furthermore it is a UMLUserInterfaceComponent Since it is an UMLUserInterfaceComponent it must implement targetChanged and targetReasserted TargetChanged is called everytime the UMLTextField is selected targetReasserted is of no interest for UMLTextField It plays a role in keeping history but since history is not really implemented at the moment in Ar goUML it is of no interest target Changed does two things e Itcalls the targetChanged method of the UMLText Property this UMLText field is showing e Itcalls the update method The update method is described further on Besides UMLUserInterfaceComponent there are several other interfaces of interest One of them is MMEle mentListener Every time a MModelElement is changed this will fire an MEvent to UMLChangeDispatch UMLChangeDis patch will dispatch these events to all containers implementing UMLUserInterfaceComponents interested in this event including UMLTextField It will also dispatch the event to all childs of an interested container implementing UMLUserInterfaceComponent By this it is only necessary to register a PropPanel which holds an UML TextField at UMLChangeDispatch to dispatch the event to the UMLTextField too MMelementListener knows several methods of which only one is of interest to UMLT
35. 5 3 2 5 Creating a new Fig explanation 2 Assuming you have your modelelement already defined in the model and your PropPanel for that modelelement you should make the Fig class 1 For nodes that are Figs that are enclosed figures like FigClass extend from FigNodeModelElement For edges that are lines like FigAssociation extend from FigEdgeModelElement The name of the Fig has to start with yes indeed Fig The rest of the name should be equal to the modelelement name 40 Inside the components 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 example of this 3 Create a constructor FigMyModelelement Object owner Set the owner in this method by calling se towner Make a method setOwner 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 exam ple 4 Create an overriden 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 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 s
36. ArgoUML site to be edited through CVS Everything that is checked in under argoum1 www be comes immediatly available at the url http argouml tigris org with some added decorations Example The file argoum1 www project html is available at http argouml tigris org project html This is the way the site is maintained and updated 2 3 2 2 The ArgoUML documentation For the ArgoUML project the same documenation 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 Building from source 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 web site the responsible document release person does the following 1 He checks out everything needed and a copy of the argoum1 www The module argouml docs is there for this p
37. C rankO DEF rank 1 We give the superclasses 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 superclasses here D gt C E gt AandC F gt AandB Compute the average value of the indices 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 Then sort the subclasses by that value F is 0 5 E is 1 D is 2 So the placement is ABC here are the links but I can hardly paint them as ASCIIs FED 5 8 Other languages Each other language supported by ArgoUML has its own component 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 58 Inside the components ava classfiles 5 9 The GUI Framework Purpose Provide an infrastructure with menus tabs and panes available for the other components to fill with ac tions and contents This component has no knowledge of UML Critics Diagrams or Model The GUI Framework is located in org argouml 2 2 The GUI Framework is a Layer 1 component See Section 4 5 Layer 1 Description of components This is implemented directly on top of Swing and Java2 The GUI has currently the following main parts e The menu e
38. Cookbook for Developers of ArgoUML An introduction to ArgoUML Programming by Markus Klink and Linus Tolke Cookbook for Developers of ArgoUML An introduction to ArgoUML Programming by Markus Klink and Linus Tolke 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 14 of ArgoUML Copyright c 1996 2003 The Regents of the University of California All Rights Reserved Permission to use copy modify and distribute this software and its documentation without fee and without a written agreement is hereby granted provided that the above copyright notice and this paragraph appear in all copies This software program and documentation are copyrighted by The Regents of the University of California The software program and documentation are supplied AS IS without any accompanying services from The Regents The Regents does not warrant that the operation of the program will be uninterrupted or error free The end user understands that the program was developed for research pur poses 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 CALI FORNIA HAS BEEN ADVISED OF
39. 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 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 pursue 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 com mit your changes in the main branch but please commit your changes if any into a work branch and state the name of the branch in the issue That will make it possible for someone to make use of your work so far 8 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 9 Resolve the Issue with the resolution FIXED 10 Sit back and feel the personal satisfaction of having comple
40. Per oem 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 opera tion is supported void moveUp int Per foem the actions associated with the move up pop up menu on the element at the given index There is no default provided so this must be given if the move up oper ation is supported void moveDown iPerfomnthe 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 public public public public public public void resetSize Called when an external event may have changed the size of the list The default just sets a flag which will ensure recalcModelElementSize see above is invoked as needed Object formatEld amp mstum anobjert iaweriablyfstring that represents an element The default provided in the parent defers this to the container which in turn defers it to the current profile This is usually perfectly satisfactory void targetChanG adled when the number of elements in the displayed list including none may have changed Default invokes the necessary Swing operations to advise of a change in list size void targetReas amp alleddwhen the navigati
41. RME 99 Jason Robbins 92 Dissertation 92 Java 28 55 Javadoc building 8 jdepend 5 JRE 25 JUnit 5 JUnit testing 10 L10n 61 Language teams 62 layer 23 Localization 61 log4j 5 Logging 25 Mailing lists 3 Making a release 15 Martin Skinner 92 Dissertation 92 Model 26 Module loader 27 Index Navigator Tree 27 Notation 27 NSUML 5 78 understanding 78 Object Explorer 27 OCL 28 72 Pluggable interface 27 Priorities 95 on Issues 95 Processes 94 Property panels 27 Repository contents 86 Resolution 96 of Issues 96 ResourceBundles 61 Reverse Engineering 27 54 55 Java 55 Roles 96 Round trip Engineering 55 Java 55 Standards 82 89 Coding 89 CVS 82 subproducts 101 Testcases 11 12 an example 12 writing 11 Testing ArgoUML 10 11 To Do Items 26 69 Tools 4 4 needed for building 4 used 4 Translators 62 Troubleshooting 10 10 18 commiting changes 10 development build 10 during the release work 18 Unit testing of ArgoUML 10 11 Unix 7 compilation 7 Web Site 8 8 documentation 8 maintaining 8 Windows 7 Compilation 7 Wizards 34 Workers 96 Writing testcases 11 XSL stylesheets 5 104
42. Reporter ot Ee tete DER Der E e Dee poU Tei Oe E 96 11 3 2 The R680lV6E 9 roe oot oto ero o oe yee e eere exe eee siege eger geste estu pe Sedulo Rune e exe Ree d 97 11 3 3 The Vetifiet eer reete eter TE EE a E Re OE TURO E Eee o Er SES 98 YT Howto resolven ISSUE 1 otro eR eet teo Lot Mes cubes Iove tes Coe see Sheet d dae e ena dee dn 98 11 5 How to verify an Issue that is FIXED sse HH herren 99 11 6 How to verify an Issue that is rejected ssssseesssessee meme hene 100 11 7 How to Close n Issue ic reete re ee ae e Yee e rp HI oe e e cede 101 11 8 How to relate issues to problems in subproducts sssee e 101 Inc weds vi List of Tables 7 1 Bits of documentation List of Examples 2 1 Anexample without javadoc comments e ena eaae eene nennen hee ren senten see ree RE EES NAGS 12 3 1 For log4j version 1 2 X secet sesh sage eere gerer eed etes Ure deis pede Pete ove Woes Tone Pete eed eT ge dn 66 5 2 Improving on speed performance ctr e I Fe EO Fe ER o Dep ve e Rp yas Portae eto irre gren 67 5 3 EGG M RRm 67 5 4 Command Line for argouml jar sss eee hene enhn e e hen he me mee EEEE S 68 3 5 Modification of build xml 3405002095 oi eei nes ioe ette citet as eed rte er A quet mte eben sett e
43. S repository The CVS repository is a shared resource in the project This means that once you commit your stuff it has the poten tial 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 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 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 compile build clean followed by build run or build package The build mechanism does not yet have reliable dependancy 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 dependancy 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
44. THE POSSIBILITY OF SUCH DAMAGE THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DIS CLAIMS 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 UNIVER SITY OF CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE SUPPORT UPDATES ENHANCEMENTS OR MODI FICATIONS Table of Contents BW M M M INE CM DE 1 LED AbOUtthE Project huis cie ien a alas ere eee a ete eine nie oL chon ooeroee a ater a eas bag ee a 1 1 3 How to contribute roO eee NU ER as CEE eR eee 1 1 4 About this Cookbook 5 1 ci eorr pte roe ette Se oto Po PRESTO EE ss Sunde apse S epe uer S PEOR NEER 3 1 4 1 In this Cookbook you will find sese emen 3 1 4 2 In this Cookbook you will not find sssssses HH emen 3 1 5 Mailing Lats e DES ORE C dO Ra e ERR as Te D REDE EE NEN ES 3 2 upauvucuu RH EE 2 1 Getting started ne urere ERR E aden ds pau Saves Sede EE Qi EDEN e rere drei 4 2 1 1 Which tools do I need to build ArgoUML sssese HH 4 2 1 2 Which tools are part of the ArgoUML development environment cece eee eee 4 2 1 3 What libraries are needed and used by ArgoUML 0 00 eee cee cece eee ceeeeaeeca tenn eeaee 5 2 2 Download from the CVS repository essessesseseee II e mee meme hen hen t entren 5
45. TI REV1 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 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 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 14 Building from source 2 5 3 2 Class diagram TEST2 REV 1 Requirements tested 1 and 2 Do Select the Class Diagram Click the Package symbol on the Edit pane toolbar Click on the diagram Click the Class symbol on the Edit pane toolbar Click on the diagram Click the Interface symbol on the Edit pane toolbar Click on the diagram Expected output The Class diagram and the explorer now contains one package one class and one interface 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 buttom left of the class Select the interface Drag from the quick but ton located along the buttom of the interface symbol and release somewhere on the diagram Expected o
46. The toolbar e Explorer pane Navigator pane Upper left Contains a tree of the model Multi editor pane Upper right Contains the diagrams could eventually be something else 59 Inside the components To do pane Lower left To do items different views Details pane Lower right Contains a wizard from a To do item a property panel of the current object some other view of the current ob ject 5 9 1 Multi editor pane The multieditorpane 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 multieditorpane consists of tabs that hold editors as you can see in the classdiagram TabbedPane zzInterfacez7 MultiEditarP ane At the moment there is only one editor tab in place This is the TabDiagram that shows an UMLDiagram the target The TabDiagram is spawnable This means that the user can double click the tab and the diagram will spawn as a separate window The target of the MultiEditorPane is set via the setTarget method of the pane This method is called by the setTarget method of the ProjectBrowser The pane s setTarget method will call each setTarget method of each tab that is an in stance of TabModelTarget Besides setting the target of the tabs the setTarget method also calls MultiEditor Pane select Object o This selects the new
47. UML uses several factories and helperclasses to manipulate the NSUML model The NSUML model itself does not define enough business logic to be directly used and the factories and helperclasses provide a centralized place for accessing this business logic Per section of chapter 2 of the UML 1 3 specification there is one factory and one helper They are placed in their own packages The package name convention is org argouml model uml SECTIONNAME where sectionname is one of the following foundation foundation core foundation extensionmechanisms foundation datatypes behavioralelements behavioralelements commonbehavior behavioralelements statemachines behavioralelements usecases behavioralelements collaborations behavioralelements activitygraphs modelmanagement Each package has at least a helper and a factory in it The factories contain all methods that deal with creating and building modelelements The helpers contain all utility methods needed to manipulate the modelelements Both helpers and factories are singletons The static method to access them is getFactory for the factory and getHelper for the helper 29 Inside the components 5 1 1 Factories The factories contain at least for each modelelement a create method Example createClass resides in CoreFac tory in the package org argouml model uml foundation core Besides that there are several buildmethods to build classes The build methods have a signature
48. V EROS EDS D E SEU Cees Re de eet 61 5 LI dnternationalizatiom ooo eor ebore ape Ee aves sseivegen wees Shop sum EET Eoo Pe Ege up ERT Shep Mua ES EE TTE E Eee RU 61 S4 TT Organizing translators ee tres ro hm M e DEDI MI OH 62 5 11 2 Ambitions for localization roter te tpe eee o br Poe REPE PRI urba 63 SERE Mshunum Mc E 63 RM Iu DM cess votes saces E E E tebe edhbadess reed saargse asst EE 65 5 12 1 What to Log in ArgOUML cniris cece ence ence II eI e me mH mee eI en mehreren 65 3 12 2 Howto Create Log Entries iecit tre ree ret seh EEEE S 66 5 12 3 How to Enable Logging 0 eee cece cence ence HI HI emen hee eem entente 67 5 12 4 How to Customize Logging eneo rera EAEE E ERE mem meme enm hen trennen 69 BESSER ae r a a a e a a E E A EER 69 5 13 TRE with Util se ic ES RECO qu RR E pir pe Ee A IRE Bad ede 69 RE MEUSE swans sh esegs eps Sutas A E E ss Sueduaton E A NEEE ERS EEEE y emacs 69 JAN EXplorer i urn Renee te ree WU sina Oia eU pu tn ege eect cedet Sised stapes 69 5 15 1 Details of current implementation sssssssssseee ee emen me nme 70 5 152 Requirements dele soper Reste PEE Der ripper dete bir peis 70 5 15 3 Key Classes insere Herbert Dee RPM ERE EORR REPRE PPP ER RER RIT 70 SMS How do D iei e e E E ETE E a EEEE EE I EEEE EES 71 5 T6 Moduleloader te rtc Gp a EIE REI sas datas pe EO E AETI 72 5 16 1 What the ModuleLoader does
49. ade class is called componentNameFacade and is located in the component package How it is used is primarily documented in the class file itself as javadoc but the more complex picture is documented in the Cookbook in Chapter 5 Inside the components Each component can also have one or several plug in interfaces That is Facade objects where modules or plug ins can connect themselves to modify or augment the behavior of that component The plug in interfaces are also all located in the component package and called ComponentNamePluginPlug inType Example ModelPluginDiagram ModelPluginType If the component uses a callback technique the callback is always made to an interface The interface is also in the component package and it is called ComponentNamePlug inType Interface Example ModelDiagramInterface ModelTypeInterfac 23 ArgoUML Design The Big Picture ClassFromSomeOtherComponent lt lt Interface gt gt ComponentSomeOtherlnterface I l l l l ComponentPluginWhatevert PluggableClass1 ComponentPluginWhatever2 PluggableClass2 4 2 Relationship of the components Each component that is used by other components provide two ways for other components to use them 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 components were clearly defined A Facade class provides the most common functions other components w
50. age or creating a team for the language is pointless if there is no win dow system available for the language in questions I mean if neither the people working with Windows Linux KDE or Gnome or java has collected enough interest to do a translation of the basic infrastructure there is no point in doing so for ArgoUML My Windows 2k has 80 supported languages so I would think that this is a no issue 3 User environment translation This is the next level of ambition that can be set out by a Language Team that works really well and has plenty of translation resources left It means that not only the ArgoUML tool should be translated but also everything around it that the user sees i e the User Manual the Quick Guide the FAQ the Users part of the ArgoUML Web site Setting this level of ambition for a language is pointless if the problem domain does not exist in that language I mean if the professionals that use UML or other Software Engineering tools in their every day work don t use their native language to discuss UML concepts then there is no use in translating these concepts to their lan guage they will not use the translation because they are more comfortable with the English concepts Note that the UML Specification does only exist in English and a natural part of this level of ambition would probably be to translate that 4 Development environment translation Here I mean that everything that the developer of ArgoUML sees
51. an true UMLAction NO ICON assert Disabled to shouldBeEnabled and the corresponding no gui class package org argouml uml ui import junit framework public class TestUMLAction extends TestCas public TestUMLAction String name super name Functions never actually called Provided in order to make sure that the static interface has not changed private void compileTestStatics boolean t1 UMLAction HAS ICON boolean t2 UMLAction NO ICON UMLAction getShortcut new String 12 Building from source 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 5 Manual Test Cases 2 5 1 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 test cases understand what he is supposed to do do it and document the result we try to go as far as possible with the JUnit test cases and have as few manual test cases as possible I e If one of these tests can
52. ant to do when using that components 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 component itself Methods in the Facade should change really slowly and only be removed after several months and one stable release of deprecation 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 components e Calls to public methods Traditionally components interface through public methods and public variables For this reason always exer cise extreme caution when changing the signature of a public method See Section 8 1 How to work against the CVS repository This way of communicating is still to be used when it is not convenient to use the Facade for a specific use of that component For each component X in ArgoUML that uses the component Y the designer of that component X must decide if he wants to use calls to public methods when using the component Y putting a set of import 24 ArgoUML Design The Big Picture org argouml Y internals blabla statements in each file in the files of component X that uses component Y or just use the Facade class of component Y putting only one import org argouml Y Y Facade in each file in the compo nent X that uses component Y The public calls solution makes the component X depending on the compon
53. are marked as modified If files are updated or patched by this command please recompile and test again Do a cvs 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 Don t forget to update the corresponding issue if any in Issuezilla i e set it to RESOLVED FIXED e 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 83 CVS in the ArgoUML project Supposing that you have checked out CVS as guest then after you have mailed a diff or file to an active devel oper 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 be fore 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 mail ing list to know what bran
54. at correspond to different sections in the UML specification Then you have to look in both corresponding helpers and you will prob ably find what you are searching for TODO Am I allowed to call the helpers from any thread 5 1 3 The model event pump 5 1 3 1 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 modelelements 2 The model helpers responsible for utility functions to manipulate the modelelements and 3 The model event pump responsible for sending model events to the rest of ArgoUML In other paragraphs the model factories and the model helpers are already introduced Therefore we won t discuss them here again The model event pump is the gateway between the model elements and the rest of ArgoUML Events fired by the modelelements are catched 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 30 Inside the components 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 comparision to the situation without the pump The main improvement is that you can register for just o
55. at one of the developers has made a mistake You now must decide a way for ward 2 6 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 Make the release tag into a branch cvs rtag b r VERSION x Yy z F BRANCH x Y z e Update your checked out copy to be on that branch cvs update r BRANCH x Y z e Fix the problem in your checked out copy Commit the problem in the branch cvs commit m Fix of problem blabla 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 ei ther 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 6 1 2 Delay the release waiting for someone to fix the problem Create the branch as described in Section 2 6 1 1 Fix the problem yourself Then tell the culprit and everyone on the developer list what the problem is and that it is to be fixed in the release branch a s a p Monitor the changes
56. 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 man ual tests makes it unpractical to this during the release work the work can be done by anyone or any group of peo ple within the project after a development release is made and before 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 2 5 2 Writing the manual tests Adding a new manual test 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 because they can be to so
57. ches 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 5 Do your work 6 Check in your changes in the branch evs commit m B1ablabla 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 en ter 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 un commited 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 a
58. commits towards the next version This is done by setting the argo core versionin default properties to Number of next release commiting and telling everyone on the developers mailing list Notice that this cannot be done in the tagged copy but you either need to go back to your other working tree or need to check out the file argouml src new default properties specifically to do this Upload the files onto the tigris website Only a project owner can do that Please write the descriptions of the files like this libraries libraries needed to compile sources 16 Building from source 10 11 source code without libraries If you want to build ArgoUML from source the cvs version is recommended For the gnu version add also Unpack with GNU tar complete set binary distribution including all libraries e application bundle binary distribution runnable as application bundle Contact Jason Robbins to make the new Webstart version available Jason Robbins takes care of the signing and publishing of the Webstart 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 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 c Change the target milestones of all the not yet resolved issues for this release
59. component i e it provides methods to simplify the attach ing of calls at the correct places There are several Pluggable interfaces that each simplify the addition of one kind of object Examples P luggableMenu 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 Plug gable are the AbstractLoadableClass 6 2 2 Modules 6 2 2 1 Module Architecture The controlling class of the module plugin extension is org argouml application modules ModuleLoader ModuleLoader is a singleton created in the ArgoUML main initialization routine ModuleLoader will read in the property file for each of the classes found l create the specified classes 2 callinitializeModule on this class 3 place the class object into the internal list of modules 6 2 2 2 The ArgoModule interface Each class must derive from the ArgoModule interface This interface provides the following methods 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 added into the mod ules list
60. creating a log4j configuration file 5 12 5 References 5 13 5 14 5 15 http jakarta apache org log4j http jakarta apache org log4j http www japhy de configLog4 j http www japhy de configLog4j JRE with utils Purpose to provide the infrastructure to run everything The JRE is a Layer 0 component See Section 4 5 Layer 1 Description of components 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 To do items Purpose To keep track of the To do items Items are generated and removed automatically by the critics They could also be created by other means The To do items are located in org argouml The To do items is a Layer 1 component See Section 4 5 Layer 1 Description of components Explorer Purpose to provide tree views of the model elements diagrams and other objects 69 Inside the components The Explorer will be located in ozg argouml ui navigator The Explorer is a Layer 2 component See Section 4 6 Layer 2 Description of components Several tree views are provided by means of Perspectives Objects showin in the trees are the model elements dia grams and other objects such as profiles groupings of model elements etc The Explorer is currently shown in the Explorer Pane the upper left hand pane of ArgoUML See S
61. ct with a lot of calculations when toString is called and the logging statement is passed often some action needs to be taken If the toString methods are simple you are still stuck with the overhead of cre ating a StringBuffer and a St ring from the sb toString statement 5 12 3 How to Enable Logging log4j uses the command line parameter D10g4j configuration URL to configure itself where URL points to the location of your log4j configuration file Example 5 3 Various URLs 67 Inside the components org argouml resource filename lcf http localhost shared argouml filename lcf e file home username filename lcf amp name lcf name lcf name lcf 5 12 3 1 when running ArgoUML from the command line There are currently two possibilities of running ArgoUML from the command line rgouml jar 2 In the first case the configuration file is specified directly on the command line whereas in the latter case this pa rameter 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 4 Command Line for argouml jar localhost billy java Dlog4j configuration URL jar argouml jar Example 5 5 Modification of build xml lt Run ArgoUML from compiled sources t target name run depends compile gt lt echo message Executing Name Uncomment the syspropert
62. dValue target targetFlow targetScope templateParameter templateParameter2 templateParameter3 top transition trigger type useCase value 49 Inside the components e visibility when 3 A flag to indicate that a label none should be used when the list is empty Quite usually it is sufficient to just invoke the constructor of the parent class This list model should then be provided with a number of methods The following are mandatory since they are de clared abstract in the parent protected int recalcMoRetHinputesctheawmber of elements in the list zero if empty protected MModelElemenRefernadlhe elereentrat Ahel 1venindex jn the list or null if there isn t one The following are sometimes provided as an override of the parent although for many uses the default is fine public void open int if eferm the action associated with the open pop up menu on the element at the given index The default provided in the parent just navigates to that element public boolean buildPofuldse popoe mempforptheilst andicet rn whether it should be displayed Any ac tions will be associated with the item at the given index in the list This is built using UMLListMenultem 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 d
63. 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 it is 114MB 250MB is enough to build it all javadocs documentation classes packages CVS for getting the files and committing source code updates JDK at least version 1 3 includes the java compiler 2 1 2 Which tools are part of the ArgoUML development envi ronment These tools are provided by the development environment that you get when you check out from CVS ANT the tool to manage compiling and packaging ANTLR for regenerating the built in parser Building from source JUnit for running the JUnit test cases JDepend for examining the code For building the documentation from docbook format these tools are also provided with the development environ ment that you get when you check out from CVS e saxon for building documentation from docbook format Docbook XSL stylesheets fop for generating pdf versions of the docbook format To build a pdf file with the pictures included you need Jimi 2 1 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 Ar goUML nsuml the Novosoft UML library ArgoUML project doesn t include
64. ds are stretched to fit a column Vertical padding is distributed in proportion to weighty amongst all fields in the column that have non zero weighty values Tip You should always ensure at least one field or caption in each column has a non zero value for weighty If you wish everything fixed size and floated to the top make the value for the final caption in the column non zero Every field is built from Java Swing components However these are extended by ArgoUML to help in the provision of action methods for fields in the property tab Several fields involve lists and these require in addition list models to compute the members of the list The fields that you might add to a property panel include e Simple editable text For example the Name field Supported through the UMLText Field class e A drop down box of options that can be selected with an icon to the right allowing navigation to the property panel for the currently selected item For example the Stereotype field Supported in general by the UMLCom boBox class and more speficically by its subclass for stereotypes UMLStereotypeComboBox A non editable text box with a pop up menu that allows opening addition deletion moving up and moving down of entries For example the Generalizations field Supported by the UMLList class The list model is usu ally provided by a sub class of UMLModelElementListModel There is a varient UMLModelEle mentListLinkModel which adds a link
65. e String Object isEnabled boolean setEnabledie boolean void snoozeOrde rd woid snooze 0 void unsnooze void H isRelevantToDecisionsidsgr boolean isRelevantToGoalsidsgr boolean make Wizard ite m Wizard H getWizardC lasstite m Class initWizardtw Wizard void getDecisionCategoryd String WsetDecisionCategoryic String void getCriticType 0 String H getExpe rtEmail String setExpe rtEmailiaddr String void getHeadline idm Object dsgr String H getHeadline offe nde rs VectorSet dsgr String H getHeadline 0 String setHeadline th String void H getPriorityioffe nde rs VectorSet dsgr int setPriority p int void H getPriority int H getDe scriptionioffe nders VectorSet dsgr String setDe scriptionid String void H getDe scriptionTe mplate 0 String H getMore Info URL offe nde rs VectorSet dsgr String setMore InfoURL m String void H getMoreInfoURLO String WsetArginame String value Object void Age tArginame String Object otii Hashtable setArgsih Hashtable void toDolte midm Object dsgr void CrUML from org argouml uml cognitice critics CAREFUL attribute s and methods missing CrConside Singleton from C rConside rSingletong Besdis String void predicate 2 dm Object dsgr Designer boolean 35 Inside the components Critics are currently located in org argouml cognitive critics
66. e 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 conceptual new line to the correct new line character on your system F 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 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 forgiv ing There are however some cases when this is cumbersome 1 When an editor or developer decides to fix it 85 CVS in the ArgoUML project This means that the editor or the developer goes through the file and removes M on every line or some thing 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 un mergeable 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 developer
67. e an opinion jump right in 3 Apply for an Observer role This shows that you are commited to the project and also allows you to enter and comment on issues etc 4 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 just unsubscibe again c 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 mails If it turns out you don t like watching what is going on in the project in this way just unsub scibe again d Read the process part of the Developers Cookbook at Chapter 11 Processes for the ArgoUML project Introduction This will give you the idea of how the ArgoUML project attempts to release with good quality and espe cially how Issuezilla works Get the Observer role granted From this on you can report bugs yourself directly in Issuezilla You can also verify issues according to the verification process see Section 11 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 ne
68. e feret oeitel 68 5 6 External Execution Property Arguments sess e em ee He mee men heme hee ree rennen 69 viii 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 Ar goUML 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 price for climbing higher you just get more responsibility in the project and more work 1 Use ArgoUML 2 Subscribe to the dev list Monitor the discussions and as soon as you see something discussed where you hav
69. e of JRE REQ7 REVI Rationale The JREs and the adjoining libraries especially swing are always improving to include new fea tures and new ideas The developers of ArgoUML would like to use these new features Interpretation This means that we currently want to support JREs 1 3 0 1 3 1 1 4 0 and 1 4 1 When a JRE compatible to Sun JRE 1 5 1 has come out for all major platforms Solaris Linux Windows Mac support for 1 3 0 and 1 3 1 will be discontinued Stakeholder Developers of ArgoUML 2 Download and start It shall be possible to install ArgoUML locally on the machine and use without Internet connection REQ8 REVI 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 Console output Logging or tracing information shall not be written to the console or to any file unless explicitly turned on by the user REQO9 REVI 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 set up for the benefit of the de velopment of ArgoUML 1 Logging The code shall contain entries logging important information for the purpose of helping Developers of Ar goUML in finding problems in ArgoUML itse
70. e priorities are used in the following manner in ArgoUML 95 Processes for the ArgoUML project PI Fatal error ArgoUML cannot start Crashes program jvm or computer e P2 Serious error Information lost e P3 Not so serious error Functions not working Strange behavior Exceptions logged e P4 Confusing behavior Incorrect help texts and documentation Inconsistant behavior UI not updated Incorrect javadoc e P5 Small problems Spelling errors Ugly icons Excessive logging Missing javadoc 11 2 2 Resolutions LATER and REMIND Not used e 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 problem was fixed 11 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 11 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 Responsibil
71. ection 5 9 The GUI Framework There is also a Explorer Configurator dialog which allows the user to tailor the existing perspectives and create new perspectives to their needs although the settings are not persisted 5 15 1 Details of current implementation Some of the classes are actually reused by the other tree view i e the todo critics list The Explorer provides some history capability although this is disabled presently and should problably be factored out to navigate back to previously selected model elements Currently the Explorer Pane is mixed with the GUI framework and actions in org argouml ui The Explorer is also dependant on go rules which are rules that help identify children nodes for and particular parent Go rules are mixed with Diagrams and Property panels under org argouml uml diagram ui and org argouml uml diagram diagram ui Explorer was previously called Navigator Tree or Navigator Pane 5 15 2 Requirements The Explorer must react to user and application events User events include selection of a node which must notify the other views to make the same selection right click on a node which brings up a popup menu selection of another perspective in the Combox box which must change the tree model to that perspective node expansion and collapse Bor pma Application Events include 1 change of project the tree must update 2 change in selection in another view any relevant rows
72. eds 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 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 Take active part in the discussions on the dev list Solve issues registered in Issuezilla Convince someone to commit your changes Repeat This can go on until you find that your main problem is the to get someone to actually commit your changes not because they are hard to convince but because they don t have time to do commits to keep up with your pace 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 There are a lot of special requirements on you to get this granted Noted here for Linus to keep track on what to verify Understanding and accepting the goals Understanding where we are in the development process Introduction e Understanding the terminology used in the project e Good knowledge of CVS Understanding the set of tools ant junit and how to use them 7 Focus your work in a specific area Everybody has dif
73. elete disabled if there are no elements and move up and move down disabled if they cannot be invoked on the given element The default implementation always returns true The following should be declared as needed to support particular pop up functions public void add int in erfiorm 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 addAtUtil1 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 create what you want 3 use new on a MXXXImpl class Whilst 1 is best most of the MMUt il routines are not yet general enough Be sure to set it up don t forget e g namespace etc Remember also to change any thing that references the newly created entity Lj 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 rela tionship 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 50 Inside the components public public public void delete int
74. ent Y meaning that when we change the insides of the component Y we must also change component X The facade calls solution doesn t make the compo nent X depending on the component Y but just the Facade of component Y If the public calls solution or facade calls solution is used shall be described in the Cookbook s description of com ponent X in the list of used components 4 3 Definition of layer Layers are used to organize and clairify the relationships between the different components within ArgoUML ArgoUML is built from the bottom and up Components on a higher level are relying on components on a lower level and never the other way around A component cannot even rely on a component in the same layer This means that when testing a component it can always be tested with just that component and components on lower levels 4 4 Layer 0 Description of components Layer 0 contains some infrastructure components that just are there for every other layer to use They are all insignificant enough not to be mentioned when listing dependencies Logging Calls can be spread all over that would go through some rule set and then end up on file on the output or not at all e nternationalization This is the set of files that is a repository of localized strings Every other module uses these strings in all com muncations with the user The Internationalization Component is described in detail in Section 5 11 Internationalizati
75. er et Porn ass ny eO ee Fee ee Pee x dto urne pa ei ous eetainece 90 9 2 Settings Tor NetBeans tese tese ever ects ee cua deb rb ee ege tuy ece a pci ee e ede rag deed 90 9 3 Settings Tor Bmacs uie perm e rt Der eeepc ta tet aea er e PR ed e ERe t RET etie ien 90 IO Further Reading neret ere eie pee eti mere e emere ted ere veles pU eere rii 10 1 Jason Robbins Dissertation ete o etr reete sesh m ss rep EP EPEE e e ERR REPRE YE secs 92 IUE dicum EE 92 10 1 2 Where to find it e cett P e e reete ppt erbe ERE Cree PIRE ORE Ee 92 Cookbook for Developers of ArgoUML 10 2 Martin Skinners Dissertation scncese inie inia E E eene meme meme nennen menie see rennen EE seen ee 92 LOD ATA DSPACE iss eerie eoe ie DR be e eet uU eee tex i dite tor tiere Ete e eis 92 10 2 2 Whereto Imdat a eb er e rper ves e e eo exe EP ean ods Ds e PUR UR 92 1 Processes for the ArgoUMIPproJect 5 2 eno os pete ctore aethere deret Dore er eo Deep es Pe aste ee ge 1I The big picture for Issues toto toe Rr Sept recep ios date deep Pe Se tege porre SE SOR Se ove s 94 TT 2 Attributes of an158U6 ost eroe Ea ER MER V PURSE Neu ARE FREUE AER CE EO VO RE Ere E CER E 95 11 2 3 Priorities ee rere Rr E ROTER ES ENTE M Doe ee PETRO EE CERE ies 95 Del 222 Resolutions cao eer rr rm ENSE E HEP ME FORI ETT RENE EEPI M rre RE e EP PME SUE 96 11 3 Roles OF The Workets e cnet ores esee event Pee ete Ed Ee qe ee ER PEE U RD EROR d 96 1123 15 The
76. eration is done It contains the xsl rules for all the generation The subdirectory images contains all the required pictures for all the books 2 3 3 Troubleshooting the development build 2 3 3 1 Compiling failed Any suggestions It might be that some other developer has made a misstake 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 argouml 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 different parts of your source tree at different times it might contain inconsistencies If you suspect this first try to fix it by doing build clean and cvs update d before trying to build again If that doesn t work remove your checked out copy com pletely 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 3 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 Dis cuss what you have done and how best to test it on the developers mailing list mailto dev argouml tigris org Event
77. ets ProjectMailingListList It is also recommended to join the CVS and Issues mailing lists Both give you a good idea of what is going on De velopers should also work with Issuezilla registering or fixing problems found by themselves and others Chapter 2 Building from source If you are in a hurry QOO0Q000 Work gt set CVSROOT pserver guest cvs tigris org cvs Work gt cvs login use guest as password Work gt cvs checkout argouml src Work gt set JAVA HOME C MPrograms jdkwhatever Work gt cd argouml src_new Work argouml src_new gt build run A window from the newly compiled ArgoUML opens after a while That was the compact version for Windows JDK Note jdk cannot be installed in a directory that contains space in its name If you don t understand this or it doesn t work read the rest of the chapter that describes all the nitty details about why and how 2 1 Getting started 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 1 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 A computer with a free disk space for your work 100MB is enough to
78. event exit expression extend extend2 45 Inside the components extendedElement extender extenderID extension extensionPoint feature generalization guard icon implementationLocation include include2 incoming initialValue instance instantiation inState interaction internalTransition isAbstarct isAbstract isActive isAsynchronous isConcurent isDynamic isInstantiable isLeaf isNavigable isQuery isRoot 46 Inside the components isSpecification isSynch kind link linkEnd location mapping message messagel message2 message3 message4 method modelElement modelElement2 multiplicity name namespace nodeInstance objectFlowState occurrence operation ordering outgoing ownedElement owner ownerScope package parameter parent 47 Inside the components participant partition partition 1 powertype powertypeRange predecessor presentation qualified Value qualifier raisedSignal receiver reception recurrence referenceState representedClassifier representedOperation requiredTag resident residentElement script sendAction sender signal slot source sourceFlow specialization specification state state 1 48 Inside the components state2 state3 stateMachine stereotype stereotypeConstraint stimulus stimulus1 stimulus2 stimulus3 structuralFeature subject submachine submachineState subvertex supplier supplierDependency tag tagge
79. ext Fields e propertySet Called everytime a property in a MModelElement is set This method calls update too if the UMLTextProp ert y really is affected Furthermore UMLTextField implements DocumentListener This is very typical for UMLTextField At the mo ment it is not possible to change the style of the text in the UMLText Field Therefore the method changedUpdate does not have a body This method is only called when a DocumentEvent occurs that changes the style layout of the text The methods insertUpdate and removeUpdate are respectively called when a character is added to the document UMLTextField contains or removed Since both methods are called when there is true userinput and when the contents of the document are changed programmatically the methods distinguish between them Inser tUpdate and removeUpdate are both handled via the protected method nandleEvent HandleEvent updates the property in UMLTextProperty if it is really changed If the update comes via userinput it is checked if it is valid input If it is not a JOptionPane is shown with a warning and the change is not commited into the model If it is not via userinput 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 userinput only happens when focus is lost Otherwise it would not be possible to enter intermediate value
80. ferent interests and the best contribution is made when someone is allowed to pursue his own interests Hopefully ArgoUML provides you with interesting challanges to your taste 8 Accept responsibility for a specific area With this you are part of the core team developing ArgoUML 1 4 About this Cookbook This document the Cookbook for Developers of ArgoUML is provided with the hopes of being helpful for the de velopers of ArgoUML when it comes to learning and understanding how ArgoUML work in order to improve on its functions and features It can also be of interest for persons that wish to analyse the ArgoUML project for whatever purpose that may be 1 4 1 In this Cookbook you will find Information on how you can 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 con tribute 1 4 2 In this Cookbook you will not find You will not find information on how to install and use ArgoUML You will not find information on what UML is and if or how you should use it in your project You will not find information on how to convince your project to use ArgoUML as a modelling tool 1 5 Mailing Lists All developers MUST subscribe to the mailinglist for developers Please find the details at http argouml tigris org servl
81. g is turned off for DEBUG 66 Inside the components and or INFO level Example 5 2 Improving on speed performance if cat isDebugEnabled cat debug Entry number i is entry i if _cat isInfoEnabled _cat info Entry number i is entry i e 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 http jakarta apache org log4j 5 12 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 real quick algorithm to determine if log ging is on for a certain level so that is not a problem The problem is instead explained by noticing the following log statement int i cat debug Entry number i is entry i 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 cat debug sb toString If the entry i is some obje
82. goUML eene 21 4 ArgoUML Design The Big Picture eben ete eene ree epo e pe dempto de delere 4 1 Definition of component 7 pet sos ET Ere eerte Eee eet En Tp kr te ree P HE ge Et ERE S Reg 23 4 2 Relationship of the components ssssssssesssssseee ene mene me ee he he hene hene rinse rennen nee 24 4 3 Definition of layer ier mere tree RR D CERERI UE ERR 25 4 4 Layer 0 Description of components ssssssssssesssessene eee he me m enm enm entes mre nennen 25 4 5 Layer 1 Description of components tre Rt Eee ECCE EC SERERE IP e ba RR cess re Perte repete 25 4 6 Layer 2 Description of components 0 cece eee eee ce ceca ceca cena eene eens enm ent enm he mee eene enne 26 4 7 Layer 3 Description of components ssssssssssesssessene eee hen ee enm ent ente eher nenne 27 EOM SS SRI COMPONENIS ERU EUM 5 1 Model 5 5 eos RS re ERU D ER Ov dee an Uva a e dre obe UR 29 5 T Factories EE 30 d2 Helpers i ee Sr ie e NU pce be een cubated EEAS 30 5 1 3 The model event pumpress 1 sss e bett ete toe ee eset ee lege iet eu A esee ede 30 SLA HOWdO Er 33 5 2 Cntics and other Cognitive tools sssrinin resso er eie ote rrt rer rt re er Errem 34 3 2 1 Main class s oo ete Eee eris EE Ne e niet n eee sessed ates 34 3 2 2 How do ai see rt sch trt Ert ret e mE EE PERS 36 5 2 3 org argouml cognitive critics class diagram
83. he XXX NSUML packages which in turn correspond to their sec tion in the chapter 2 of the UML 1 3 spec This packaging is essential for their lookup through Java reflection 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 NSUML classification are provided in org argouml uml ui Typically the constructor for the new 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 ar gouml Images and a call to ResourceLoader lookupIconResource made note this is a method of a GEF class This is usually added to PropPanelModelElement For our example we have 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 property panel is created as a grid with a predefined number of columns 2 if there are only a few fields 3 if there are a lot Into each row of each column is placed a caption and a corresponding field Adding a caption or field is through one of a small number of utility methods which require you to specify which column and which row and also a weighty parameter to specify the amount of padding to be added when fiel
84. he 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 55 Inside the components 5 7 5 Which layout algorithm is used The classes in org argouml uml diagram static structure layout hold the Classdiagram layout code No layout for other diagram types yet It s based on a ranking scheme for classes and interfaces The rank of a class interface de pends on the total number of direct or indirect superclasses 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 superclasses A B An implemented interface is treated simi lar to a extended class The objects are placed in rows then that depend on their rank rank 0 1st row rank 1 2nd row below the 1st one etc Example F ank 0 RF ank 1 RF ank 2 In the next diagramm a link goes to an object that is not in the row above 56 Inside the components Rank Q0 Rank 1 Rank 2 In this case insert virtual objects which are linked to the actual target and link to them Rank 0 Rank 1 Rank 2 The objects are sorted within their row then to minimize crossing links between them Compute the average value of the vertical positions of all linked objects in the row above Example we have 2 ranks O and 1 with 3 classes each 57 Inside the components AB
85. here ArgoUML needs to be modified to allow for localization As ArgoUML is originally built without localization we still have a big backlog of stuff in the GUI that is not localizable just by modifying the resource bundles Each such thing is a Defect and shall be corrected 4 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 of its own but also because it handles parts of the localization 62 Inside the components This means discussing with the teams developing the underlaying package as to how best to provide the local ization for those parts Either by providing localization for that team to include in the package or by having Ar goUML overriding that package in that respect 5 11 2 Ambitions for localization Let me Linus Tolke May 2002 try to define the levels of ambition for us to try to make it possible to discuss where we are going 1 No translation This is the lowest level of ambition that is a do nothing level This goes for all languages where we have not done anything like Swahili Polish South African English 2 Tool translation This is the basic level of ambition that each Language Team should aim for It means that in ArgoUML all strings are localized so that ArgoUML is giving a complete appearance of being a tool for that language Setting this level of ambition for a langu
86. ility to connect and register to the component or com ponents it is going to work with using that components Facade or Plugin interface For details on how to build a module see Section 6 2 Modules and PlugIns 5 16 1 What the ModuleLoader does 5 17 The ModuleLoader is looking for module jars It actually scans through all jars available in the argo ext dir direc tory 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 classes to be loaded Also notice that the Specification Title and Vendor must be specified correctly for this to work 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 component See Section 4 7 Layer 3 Description of components 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 Historicaly 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
87. imple 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 CmdCreateNode See for examples UMLClassDiagram of using CmdCreateNode 7 Adapt the method canaddEdge Object o on subclasses of GraphModel if you are building an edge so it will return true if the edge may be added to the subclass Subclasses are for example ClassDiagramGraph Model and UseCaseDiagramGraphModel If you are building a node adapt canAddNode Object o 8 Adapt the method getFigEdgeFor on implementors of GraphEdgeRenderer if you are implenting an edge so it will return the correct FigEdge for your object If you are implementing a node adapt the method get FigNodeFor 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 must be of Gif format and have a drawing of the button image to be used in itself This image is also used on the Prop Panel The name of the Image file should be modelelement gif 10 Add buttons to the action you created on those places in the g
88. inked into ArgoUML Within the ArgoUML project some parts of the code are for different reasons developed and kept separate from the main ArgoUML source code These parts can be modules or plugins 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 mod ules 6 3 1 How dol create a new source code module Suggestion copy from the junit module as described here Make a copy of argoum1 modules junit into argouml modules yourname Remove junit jar from argouml1 modules yourname lib Add any jar you need to argoum1 modules yourname lib Edit argoum1 modules yourname module properties Edit references to junit jar in argouml modules yourname build xml to any new jars you need Edit argoum1 modules yourname src org manifest mf Reorganize the source files as necessary Something like org argouml yourname as the package root get Argo to use a plugin Once you ve created a jar file with a plugin 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 plugin This will copy the jar file to the proper directory in the main Ar goUML build target You can test your plugin by running build run in the src new directory If you need to install the jar the
89. ion like the contents of the up coming releases and the plan for the nearest fu ture Easy access illustra tion for users to be Some illustrations that do not work well in the other parts of the docu mentation This is done as a complement to the other parts Examples tours The manual and quick guide Users of ArgoUML Per sons that want to evalu ate ArgoUML for the purpose of starting to use it Persons that are train ing to use UML and Ar goUML Describe how ArgoUML is installed and used De scribe how UML is used with ArgoUML Complete installation in structions for all sup ported installation schemes Complete de scription on how to use ArgoUML in your project Complete refer ence on how to use Ar goUML Help texts within the Users of ArgoUML Give a quick help with a A complete set of quick running ArgoUML specific feature or but help and explanations ton Give short explana tions of all commands and actions The FAQ Users of ArgoUML Cope for shortcomings in A list of issues that are Members of the users mailing list ArgoUML the help text the Manual and quick guide and the web site not addressed in the other part of the docu mentation It is written in questions an swers format and the contents is governed by the issues discussed re cently in the user com munity 81 Chapter 8 CVS in the ArgoUML project 8 1 How to work against the CV
90. ions Extensions are called modules and the classes within the modules that attach to ArgoUML core are called plugins 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 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 addi tional 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 the correct action at that point Modules can be internal and external The only difference is that the internal modules are part of the ar gouml jar and the external are delivered as separate jar files Plugins A plug in in ArgoUML is a module that implements the org argouml application api Pluggable inter face 73 Extending ArgoUML The Pluggable interface acts as a passive dynamic
91. is is done by checking out from the tag using the command cvs co r VERSION x v z F ar gouml modules and cvs co r VERSION x v z F argouml tests in a newly created directory These commands assume that you have set the CVSROOT correctly If not you will have to use commands like cvs d pserver user 2 cvs tigris org cvs co instead 3 Build the release This is done in the argouml src_new directory of the newly created copy by issueing the command build dist release Linus It takes around 10 minutes on my machine JDK1 3 1_01 700MHz 256MB May 2003 It takes around 30 minutes on a Lysator machine simultaneously doing a lot of other things JDK1 3 1 06 sun4d 256MB July 2003 On a Cygwin Unix system you need to first make the ant executable with the command chmod x tools ant 1 4 1 bin ant and then issue the command with build sh instead of build 15 Building from source The output should be the files ArgoUML VERSION libs tar gz ArgoUML VERSION libs zip ArgoUML VERSION modules tar gz ArgoUML VERSION modules zip ArgoUML VERSION src tar gz ArgoUML VERSION src zip ArgoUML VERSION app tgz ArgoUML VERSION tar gz and ArgoUML VERSION zip in the argouml directory in your new copy Test the release Either the ArgoUML VERSION tar gz Or ArgoUML VERSION zip file is tested by unpacking starting and then running through the test cases Currently there isn t any defined test cases for manual testing There are two
92. 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 Committhe changes thus publishing it on the web site cvs commit m New version of the documentation published Building from source 7 The pdf book is uploaded to the download page 2 3 2 3 How developers work with documentation Developers that work with the documentation or with the tools to generate the documentation or anyone else inter ested in this can generate the documentation like described above and examine the result in argoum1 build It is only the last part about checking in and upploading the result under argoum1 www documentation that requires write access in the CVS and synchronisation with the rest of the project In order to do this you need to check out the whole of the argoum1 documentation directory You also need the directory argoum1 1ib and argouml tools that contain the tools used ANT Fop saxon The subdirectories of argoum1 documentation cookbook manual and quick guide each contain one of the four books The subdirectory docbook setup contains two things It contains the configuration files that control how the gen
93. ities e Report an issue The address to enter new issues is http argouml tigris org issues enter bug cgi http argouml tigris org issues enter bug cgi For entering new issues registering as described in 1 3 is not 96 Processes for the ArgoUML project required 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 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 re quires at least observer role in the ArgoUML project 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 11 3 2 The Resolver The Resolver is the software developer who attempts to resolve the issue Doing so requires at least observer role The developer role is only needed to commit things into CVS e g submit changed Java code scripts or documen tation Remark Someo
94. job This comes from the fact 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 language team per language working with all gettext applications There are also tools to help the translator do his job delivered with gettext that are the same for all the applications In each of these language teams discussions are held that ensure a consistant 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 with ArgoUML Each language teams are actually just one or several persons that know that language and are eager to work with translating ArgoUML The language team has the following responsibilities 1 All localized strings and resources shall be tranlated into the language This is a constant work with keeping up with the changes that will be made to the ArgoUML code since Ar goUML is under fast development 2 The terminology used shall be correct This requires work in keeping up with the current literature in the domain of ArgoUML 3 Help with the improvements on ArgoUML by pin pointing w
95. l VERIFIED issues http argouml tigris org issues buglist cgi component argouml amp issue status VERIFIED See that you are satisfied with the solution This could involve reading through the resolution and starting the tool to verify it Do one of the following e If you are satisfied put the Issue in Status CLOSED 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 If you are not satisfied and the problem is not solved put the Issue in status REOPENED with a description on what you are not satisfied with How to relate issues to problems in subprod ArgoUML uses some product internally and is to some respect very dependant on the well functioning of these products This are products like GEF NS UML ocl log4j xerces jre Occasionally a bug found in ArgoUML is found to be a problem in one of these subproducts and cannot or is ex tremely complicated to fix within ArgoUML If this happens this is the way to register that Issue in Issuezilla This can be performed by any member of the project any role There might be special skills involved depending on the nature of the Issue 101 Processes for the ArgoUML project Do the following 1 During your examination of an issue you find that it is a problem in one of the ArgoUML subproducts GEF NS UML ocl jre 2 Write a comment in the
96. led jdk export JAVA HOME This is for sh style shells like sh ksh zsh and bash If you use csh style shells like csh and tcsh you will instead have to write setenv JAVA HOME where you have installed jdk 2 Change the current directory to the directory you are building cd your checked out copy of argouml src new 3 Start ant using build sh This gives you a list of targets with descriptions 4 Compile and run Argoum 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 3 1 2 Compiling for Windows 1 set JAVA_HOME where you have installed jdk 2 Change the current directory to the directory you are building chdir your checked out copy of argouml1 src_new 3 Start ant using build This gives you a list of targets with descriptions 4 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 3 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 argoum1 src new default properties file unless you are working with updating the de velopment environment itself Instead create one of the other files locally on you machine The properties in these files
97. less there is a pos sibility 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 ArgoUML shall be a correct implementation of the UML 1 3 model REQ5 REVI 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 ArgoUML shall implement everything in the UML 1 3 model REQ6 REVI Rationale The ambition is to implement all of UML This means that no matter how you use UML ArgoUML will always be a working tool Stakeholder User of ArgoUML 3 3 Requirements on java and jvm 1 Choice of JRE We will support any JRE compatible with the Sun specification one version behind the most recent stable JRE from Sun A stable JRE is considered to be one that has had a second non beta release 20 ArgoUML requirements This is to allow ArgoUML to gradually take on board new stable features of the Java language while still offer ing users some choic
98. lf REQI10 REV1 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 21 ArgoUML requirements 22 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 components that each have a responsibility Chapter 5 Inside the components explains each component in details This chapter just gives an overall picture The components are organized in layers The purpose of the layers is to keep a clear view of what components pro vide services to others and to allow us to know how much is involved when testing each component TODO Insert UML diagram describing the relation between components and layers This chapter contains a list of all components and what layer they are in and the definition of the responsibility of each component 4 1 Definition of component All ArgoUML code is organized in components Each component has Aname A single directory java package where it resides Subparts of the component can reside in subdirectories of this directory Auxiliary parts of the components can reside somewhere else Each component has a single Facade class that can be used by all other components when using the component The Fac
99. ls GoFilteredChildrer GoXYz NavPerspective model Each node is displayed with a name and an Icon representing the type of node it is in the UML model This is done using the org argouml uml ui UMLTreeRenderer for the Icon and the text is produced in the convertval ueToText method in DisplayTextTree Event handling is done in DisplayTextTree and NavigatorPane 5 15 4 How dol e add another perspective e at runtime perspectives can be changed using the NavigatorConfigDialog hard code it Perspectives are build in the NavigatorPane so you can add your one there Also create new Go rules that are subclasses of AbstractGoRule then register them with the Perspetive instance using addSub TreeModel TreeModel e improve the PopUp menu Look in the NavigatorPane class The menu is built at runtime in reaction to a mouse event 71 5 16 Inside the components Module loader Purpose to provide the mechanisms to load and unload the Layer 3 and auxiliary modules The Module loader will be located in org argouml The Module loader is a Layer 2 component See Section 4 6 Layer 2 Description of components Currently the module loader is located in org argouml application modules ModuleLoader with interfaces in org argouml application api This handles the enabling and disabling of every module An idea on how it could work It is then the modules responsib
100. luggable interface In addition to the methods declared in ArgoModule which Pluggable extends see Section 6 2 2 2 The ArgoModule interface 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 determine 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 75 Extending ArgoUML 6 2 3 2 How dol 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 PluggableMenu inter face The implementation of inContext that you provide should be similar to public boolean inContext Object o if o length 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 state ment appendPluggableMenus createDiagrams Create Diagrams There is no restriction on a single class implementing multiple plugins quite the contra
101. machine remembers this Then you do the actual checking out cvs checkout modulename The CVS module you need to check out to build ArgoUML is argoum1 src This will check out the directories argouml lib argouml tools argouml src argouml src new and argouml tests If you want to build the documentation you check out the module argouml doc This will check out the directories argouml lib argouml tools and argouml documentation If you want to work with the web site you check out the directory argoum1 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 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 3 Build Process The ArgoUML build process is driven by ANT and it is highly recommend that you stick to that There are people known to build from JBuilder or Netbeans but always make sure that your work compile with the plain vanilla build process Ant is a tool written in java developed for Apache that reads an xml file with rules telli
102. made to the branch to verify that no one commits anything else but the solutions to the prob lems When you get notified that it is completed update your checked out copy and continue the release work 18 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 definition 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 REQ1 REQ2 REQ3 that never changes a revision REVI REV2 REV3 that changes when the requirement change a text that is the requirement text to implement a rationale that is the de scription on why this is important a stakeholder that is one of the stakeholders in the vision for who this is impor tant 3 1 Requirements for Look and feel This describes how the ArgoUML look and feel shall behave 1 When multiple visual components are showing the same model element they shall be updated in a consistent manner throughout the application REQI REVI Rationale There is no way of telling where the user is looking while working with ArgoUML For this reason he might be terribly confused if some other view that happens to show the same element is not showing the same thing Stakeholder User of ArgoUML
103. me extent run automatically and have their result reported automatically but then manual tests are the next big im provement Every test has several attributes to make sure that we can identify the test and help the developers and testers Aname This name is the title of the subsection where the test is described Anumber These start with TESTI and are allocated in sequence and maintained manually in this document TEST2 TEST3 TESTA They are never reused when made available by removing a test case 13 Building from source Arevision Every test case has a revision These start with REV1 and are increased with one every time the test case is changed Alist 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 ambigous in any way the tester should consider the test to be DEFECT and report it in Is suezilla This is probably best written like this Do whatever Expected output whatever Do whatever Expected output whatever 2 5 3 The list of tests This section contains all the tests each in a subsection of its own 2 5 3 1 Modules are enabled TES
104. 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 MUseCaseImpl in our example for calls to irexxx 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 action actionSequence e activator e activityGraph e actualArgument addition aggregation alias annotatedElement argument association e associationEnd e associationEndRole 43 Inside the components associationRole attribute attributeLink availableContents availableFeature availableQualifier base baseClass baseElement behavior behavioralFeature binding body bound callAction changeability changeExpression child classifier classifierInState classifierRole classifierRole1 client clientDependency collaboration collaboration 1 comment communicationConnection communicationLink componentInstance 44 Inside the components concurrency condition connection constrainedElement constrainedElement2 constrainingElement constraint container contents context createAction defaultElement defaultValue deferrableEvent deploymentLocation discriminator dispatchAction doActivity dynamicArguments dynamicMultiplicity effect elementImport elementImport2 elementResidence entry
105. mon 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 Sec 31 Inside the components tion 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 modelelement or even for all events fired by a certain type of modelele ment 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 doll register a listener for a certain type event This is really very simple Use the model addModelEventListener MElementListener listener MBase modelelement String eventName like this UmlModelEventPump getPump addModelEventListener this modelelementIAmInterestedIn IamInterestedI Now your object this gets only the MEvents fired by modelElementIAmInterestedIn that have the name IamInter estedInThisEventnameType 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 MElementListener listener MBase modelElement String eventName on Um1ModelEvent Pump like this UmlModelE
106. n They will have the names UMLResourceBundle language code java UMLCognitiveResourceBundle language code java ActionResourceBundle language code java SettingsResourceBundle language code java MenuResourceBundle_language code java DiagramResourceBundle language code java TreeResourceBundle language code java and NotationResourceBundle language code java Add the language to the JUnit list of tested languages and run the JUnit tests The purpose of this is for you to get the simple JUnit tests to work for your language also This is in the file argouml modules junit src org argouml util CheckResourceBundle java Search for the supportedLanguages array Now you have completed the first iteration of the Tool translation ambition The work will probably be more maintenance like from here on join an existing Language Team Discuss with the Language Team on where the team is in its work and what you can do add or modify code with localized things 1 Write your code using the same way of handling strings as the surrounding code This means that strings are denoted by labels or tags and then the resolution of the tag is in a DomainResourceBundle java file The name for the domain is most often specified in a variable like protected static final String BUNDLE Domain 64 Inside the components or protected static final String RESOURCE_BUNDLE Domain in a base class
107. n iobe fail Index out of bounds exception was thrown because the code is shorter easier to maintain and you get a better error message from the JUnit framework A lot of times it is useful just to run the compiler to verify that the signatures are correct on the interfaces Therefor Linus has thought it is a good idea to add methods called compileTestStatics compileTestConstructors and compileTestMethods that was thought to include correct calls to all static methods all public constructors and all other public methods that are not otherwise tested These methods are never called They serve as a guarantee that the public interface of a class will never lose any of the functionality provided by its signature in an uncon trolled way in just the same way as the test methods serve as a guarantee that no features will ever be lost Example 2 1 An example without javadoc comments package org argouml uml ui import junit framework public class GUITestUMLAction extends TestCase public GUITestUMLAction String name super name Testing all three constructors public void testCreatel UMLAction to new UMLAction new String hejsan assert Disabled to shouldBeEnabled public void testCreate2 UMLAction to new UMLAction new String hejsan true assert Disabled to shouldBeEnabled public void testCreate3 UMLAction to new UMLAction new String hejs
108. n 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 fig ure out exact dependencies Easiest way is to rename the files to include versioning informations the same way as shared libraries in Unix world foo x y z jar bar x y z jar etc modules Contains source level modules of ArgoUML Source level modules are modules that can be compiled and deployed independantly after the rest of Ar goUML Each module is located in its own subdirectory This is the list as it looks now March 2003 e jscheme Module that allows to extend ArgoUML using scheme e junit 87 CVS in the ArgoUML project Old directory with JUnit tests These should be migrated to and all new JUnit tests should be created in the directory tests menutest Test module that tests the plugin interface for the menus php Language generating Notation and reverse engineering for PHP cpp Code generation for C csharp Code generation for Cft SEC Source code This will contain one directory for each component within ArgoUML They will all compile and be tested with controlled dependencies to other components src_new All source code for ArgoUML including pictures of icons tests All source code for JUnit tests of everything that is in the src_new directory See Section 2 4 The JUnit test cases tools All tools used during the build
109. nable 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 component Logging is currently implemented using log4j ArgoUML uses the standard log4j http jakarta apache org log4j logging facility The following sections 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 12 1 What to Log in ArgoUML 65 Inside the components Logging entries in log4j belong to exactly one level The FATAL level designates very severe error events that will presumably lead the application to abort Every thing 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 The WARN level designates potentially harmful situations This is if CG can t find all the information required and has to make something up The INFO level designates informational messages that highlight the progress of the application at coarse grained level This typically involves creating modules components and singletons loading and saving of files imported files opening and closing files The DEBUG Level designates fine grained inf
110. ne type of event and not for all events fired by some modelelement modelelement1 MBase l listener1 MElementListener fmodelelement2 MBase flistener2 MElementListener modelelement3 MBase Jlistener3 MElementListener modelelement1 MBase Jlistener1 MElementListener imodelelement2 MBase fpump UmiModelEventPump i j y flistener2 MElementListener imodelelement3 MBase listener MElementListener The model event pump will replace all other event mechanisms for model events in the future These mechanisms like UMLChangeDispatch and ThirdPartyEventlisteners for those who are interested are DEPRECATED Do not use them therefore and do not use classes that use them 5 1 3 2 Public API You might wonder how does this all work Well very simple in fact A modelevent from now on a MEvent has a name that uniquely identifies the type of the event In most cases the name of the MEvent 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 MEvent and the property changed in the model Therefore most listeners that need MEvents are only interested in one type of MEvent since they are only interested 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 com
111. ne 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 the same person as the reporter Responsibilities 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 enhance ment issue which is not really an enhancement Another thing that could be is a bug that appears in very excep tional 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 an other issue instead 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 re serve the issue He can also signal progress by setting the issue to the state Started If applicable write test cases Set the issue in the end on Resolved When the resolver is finished wi
112. ng 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 documenta tion and modules whatever 2 3 1 How ANT is run from the ArgoUML development envi ronment 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 1lib 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 arg runs the program ant bat To keep you from having to write this and keeping track if you are working with a module or not there are two scripts one for Unix and one for Windows that are called build sh and build bat respectively present in most of the directories that contain a build xml file These two scripts run the equivalence of the above paths By setting JAVA_HOME to different values you can at different times build with different versions of jdk and java To use different versions of ANT you are responsible for installing your own version Also you must execute where ever you placed your new ant target rather than build target Building from source 2 3 1 1 Compiling for Unix Here is what you need to do in order to compile and run your checked out copy of ArgoUML under Unix 1 JAVA HOME where you have instal
113. nt specification model into the development process The goal of this master s thesis was to design such a tool thereby supporting the Continuous Software Engineering CSE philosophy 10 2 2 Where to find it 92 Further Reading LINK Martin Skinners dissertation http www cocons org publications CCL plugin for ArgoUML pdf 93 Chapter 11 Processes for the ArgoUML project This chapter contains processes used when working with the ArgoUML project These processes are provided with the hope of being helpful for the members of the project and if they feel too com plicated ambitious or overworked please raise the issue of simplifying them on the developers mailing list mailto dev Q argouml tigris org 11 1 The big picture for Issues Here is the big picture of the life of an Issue 94 Processes for the ArgoUML project Resolver co The verifier does not agree The V rifier agrees with the Resolver about the resolution The Reporter amp cks the resolution The Reporter does not accept the resolution The Reporter g gepts the resolution 11 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 11 2 1 Priorities Th
114. ny changes that in the 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 84 CVS in the ArgoUML project 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 developers that have been looking at your branch 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 evs 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 uncommited code or else your uncommited 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 uncommited 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 lin
115. o find it LINK Robbins Dissertation http argouml tigris org docs robbins dissertation 10 2 Martin Skinners Dissertation Enhancing an UML Modelling Tool with Context Based Constraints for Components 10 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 Language wurde bei CIS entwickelt und erlaubt den Entwickler Contextbased Constraints dem Spezifikationsmodell hinzuzuf gen Dadurch entsteht ein Modell das ber die Beschreibung der statische Struktur des Systems hinausgeht Zur Zeit existiert allerdings kein Werkzeug dass das Komponentenspezifikations modell in den Entwicklungsprozess integriert Ziel dieser Diplomarbeit war der Entwurf eines solchen Werkzeugs um die Philosophie des Continuous Software Engineering CSE zu unterst tzten Before starting a detailed design a specification model of the component based system assists the software devel oper in early problem detection as soon as possible in the development process The Component Constraint Lan guage CCL developed at CIS enables the developer to add context based constraints CoCons to a component specification model This produces a model which goes beyond the simple description of the system s static struc ture At this time there is no tool to integrate the compone
116. on e JRE with utils Every other component can use the classes available with the JRE Logging Internationalization RE Swing 4 5 Layer 1 Description of components Layer 1 is the lowest layer The components in this layer do not rely on any other part except layer 0 of ArgoUML 25 ArgoUML Design The Big Picture to do their work They can all be tested in full individually i e independant of any other component The Model The Model contains a modifyable view of the UML model and the diagrams The Model presents several different views and access methods for the information Among other things the in formation can be saved loaded examined and observed The Model is described in detail in Section 5 1 Model To do items This is the To do items They can be created deleted and saved The To Do Items Component is described in detail in Section 5 14 To do items The GUI Framework This is the framework with menus tabs and panes available for the other components to fill with actions and contents The GUI Framework Component is described in detail in Section 5 9 The GUI Framework Help system Not yet implemented This is the component that the other components can call to present some help for the user The Help System Component is described in detail in Section 5 10 Help System SUL Framework To do Items Help System Me PE V t 4 6 Layer 2 Description of componen
117. on history has been changed and navigation buttons may need changing Not clear why anything is needed but default recomputes the list size and invokes the necessary Swing operations void roleAdded fartadf the NiS amp ivityEwentistener interface Called when an add event happens i e some NSUML object has been added The default provided looks to see if the event is the role name we declared or we are listening to all events and if so looks to see if it relates to an element in our list If so Swing is notified that the element has been added void roleRemove partiofahe NSUMh Hveatlistenen interface Called when a remove 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 re moved void recovered fhaselrerallaequired as partof theiiNSUMIo Exentlastener intentses which is mpi wetht void removed final MEldeeumeEnted Ip eachocase the defanltimplenrentattonr tecompt amp e s theosize canid advises public Swing that the entire list has changed Needs more investigation void navigateTo MMquest t eavigatentedtheespeeHfred object as part of the NavigationListener interface The default in the parent just invokes navigateTo on the container ultimately Prop Panel The following utility routines
118. ormational events that are most useful to debug an application 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 enabled 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 all DEBUG and INFO log4j messages see Example 5 2 The purpose of this test is to avoid the creation of the argument 5 12 2 How to Create Log Entries You should not use System out println in ArgoUML Java Code The only exception of this rule is for output in non GUI mode like to print the usage message in Main java To make log entries from within your own classes you just need to follow the three steps below iN Example 5 1 For log4j version 1 2 x import org apache log4j Logger public class theClass private static Logger _cat Logger getLogger theClass class getName j public void anExample _cat debug This is a debug message _cat info This is a info message _cat warn This is a warning cat error This is an error _cat fatal This is fatal The program stops now working For performance reasons a check before the actual logging statement saves the overhead of all the concatenations data conversions and temporary objects that would be created otherwise Even if loggin
119. port and should implement Mutable GraphModel GEF VetoableChangeListener Java and MElementListener NSUML 5 3 2 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 YYYYDiagramRenderer java where YYYY is the dia gram name in bumpy caps For example the use case diagram graph model is in uml dia gram use case ui UseCaseDiagramRenderer java This provides two routines getFigNodeFor which provides a fig object to represent a given NSUML node ob ject 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 2 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 example 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 ob ject It should provide a setFig method to 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
120. reating 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 buttonPanel which is inherited from PropPanel The icon Lots of these are already defined in PropPanel 52 Inside the components e The advisory text for the button Use 1ocalize 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 navigation 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 newExtensionPoint that we provide to create a new use case 5 4 1 4 Support for 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
121. reports junit output html index html The testcases java source code is located under argoum1 tests org argouml How to write a test case Now this will make all you java enthusiasts go nuts We have both classnames and method names with a special syntax The name of the test case 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 searches for test cases with these names If you write a test case that does not comply to this rule you still can run the test case manually after having started with build run with test panel but it wont be known and run by other developers and automatic build mechanisms so don t do it Testcases that doesn t require GUI components in place have filenames like Test java They must be able to run on a headless system To make sure that this works always run your newly developed test case with build tests us ing jdk1 4 or later Testcases that do require GUI components in place have filenames like GUITest java We should try to get as many tests from the 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 scc new org argouml x y z java should have a JUnit test case called org argouml x y Testz stored in the file tests org argouml x y Testz java containing all the Unit Te
122. ry that is one of the rea sons for providing the generic Pluggable interface that PluggableThings extend e create a pluggable notation e 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 JMenuItem getDiagramMenuItem 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 imple ments the created plug in interface PluggableDiagram and call it DiagramHelper public abstract class DiagramHelper extends ArgoDiagram implements PluggableDiagram Default localization key for diagrams x public final static String DIAGRAM BUNDLE DiagramType String naming the resource bundle to use for localization xf protected String bundle public DiagramHelper 76 Extending ArgoUML publ publ publ publ publ publ publ _bundle getDiagramResourceBundleKey ic ic de gue Le que ig void setModuleEnabled boolean v boolean initializeModule return true boolean inContext Object o return true boolean isModuleEnabled return true Vector getModulePopUpActions Vector v Object o return null boolean shutdownModule return true
123. ry 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 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 holder COnf Not used Empty documentation Directory where the source of the documentation is 86 CVS in the ArgoUML project 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 images Pictures for all documents are collected here e javahelp Not used Empty 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 used by the 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 Li cense Apache License LGPL are OK GPL is not Don t forget to arrange for the modules version and license information to appear whe
124. s 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 2 Settings for NetBeans These style guides correspond to the following settings in NetBeans In Tools gt Options gt Editing gt Editor Settings gt Java Editor Tab Size 8 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 3 Settings for Emacs These style guides correspond to the default java settings in Emacs java c basic offset 4 c comment only line offset 0 0 90 Standards for coding in ArgoUML c offsets alist inline open 0 topmost intro cont statement block intro knr argdecl intro 5 substatement open label t statement case open statement cont arglist intro c lineup arglist intro after paren arglist close c lineup arglist access label 0 inher cont c lineup java inher func decl cont c lineup java throws 91 Chapter 10 Further Reading 10 1 Jason Robbins Dissertation Cognitive Support Features for Software Development Tools The dissertation of Jason Robbins is a
125. s 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 2 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 commited 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 cumber some for the developers These cases should be fixed because the files are no longer readable For the first case removing 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 ex actly the same on all systems This is good for jars gifs and other such files 8 4 CVS reposito
126. s 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 classdiagram since handleEvent would popup a warning messagebox The method update updates both the actual JText field as the diagram as soon as some property is set The up dating of the diagram is done by calling the damage method of the figs that represent the property on the diagram 5 5 Reverse Engineering Component Purpose Point where the different languages register that they know how to do reverse engineering and common re verse engineering functions for all languages The Reverse Engineering is located in org argouml uml reveng 54 Inside the components The Reverse Engineering Component is a Layer 2 component See Section 4 6 Layer 2 Description of compo nents 5 6 Code Generation Component Purpose Point where the different languages register that they know how to do code generation and common func tions for all languages The Code Generation is located in org argouml language The Code Generation component is a Layer 2 component See Section 4 6 Layer 2 Description of components 5 7 Java Code generations and Reverse Engineer ing 5 7 1 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 coverted into a model The java things are located in
127. s 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 purpose 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 CrXxxYyyyZzzz 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 predicate2 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 For commented examples to copy look at org argouml pattern cognitive critics CrConsiderSingleton org argouml pattern cognitive critics CrSingletonViolated and org argouml uml cognitive critics CrConstructorNeeded 37 Inside the components 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 res
128. second a textual tool tip For creating associations we have protected static Action _actionAssoc new CmdSetMode ModeCreatePolyEdge class edgeClass MAssociationImpl class 39 Inside the components 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 toolbar is actually created by defining a method initToolBar which adds the tools in turn to the toolbar a protected member named toolBar The default constructor for the diagram is declared private since it must not be called directly The desired construc tor takes a namespace as an argument and sets up a graph model UseCaseDiagramGraphModel layer perspec tive and renderer UseCaseDigramRenderer for nodes and edges 5 3 2 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 have the general name yyyy DiagramGraphModel java where vvvv is the diagram name in bumpy caps For example the use case diagram graph model is in um1 diagram use_case UseCaseDiagramGraphModel java The graph model is defined as a child of the GEF class MutableGraphSup
129. sets of automatic test cases e Run the JUnit test cases in argouml tests by issueing the command build alltests in the argoum1 src new directory Linus It takes around 12 minutes on my machine JDK1 3 1 01 700MHz 256MB May 2003 It takes around three hours on a Lysator machine simultaneously doing a lot of other things and the X session over a 50kb s modem JDK1 3 1_06 sun4d 256MB July 2003 There should not be any failed tests See details on where to find the result in Section 2 4 The JUnit test cases e Run the JUnit test cases in modules junit by cd ing to modules junit and running build run invok ing JUnit tests from the Tools menu specifying the Test Case TestAll and running without Reload classes every run checked See details in Section 2 4 The JUnit test cases The corresponding build sh is not available for a Cygwin Unix system so you must run the ant command directly First make the ant executable with the command chmod x tools ant 1 4 1 bin ant if you havn t made it above and then issue the command tools ant 1 4 1 bin ant run instead of the build run command No problems shall be found If the tests did not pass See Section 2 6 1 The release did not work Tag the whole repository with the release tag This tag is VERSION x v Z e g VERSION 0 9 7 The according command line CVS command is cvs tag VERSION x xr Z when your are standing in the argoum1 directory Open the repository for
130. st Cases for that class that don t need the GUI components to run Classes that have things that needs to be tested that do need GUI components to run should also have 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 The test case imports the JUnit framework import junit framework and it inherits TestCase i e junit framework TestCase Methods that are tests must have names that start with test i e all small t e s t This is a requirement of the JU nit framework Try to keep the test cases as short as possible There is no need in cluttering them up just to beautify the output Pre fer Exampel from JUnit FAQ public void testlIndexOutOfBoundsExceptionNotRaised throws IndexOutOfBoundsException ArrayList emptyList new ArrayList Object o emptyList get 0 11 Building from source over public void testIndexOutOfBoundsExceptionNotRaised try ArrayList emptyList new ArrayList Object o emptyList get 0 catch IndexOutOfBoundsExceptio
131. stem is not yet implemented The Help System will be located in org argouml help The Help System is a Layer 1 component See Section 4 5 Layer 1 Description of components Javahelp or some other help function will probably be used 5 11 Internationalization 61 Inside the components Purpose to provide the infrastructure that the other components can use to translate strings to provide the infras tructure that makes it possible to plug in new languages to administer the default English U S language to admin ister all supported languages The Internationalization is located in org argoum1 i18n The Internationalization is a Layer 0 component See Section 4 4 Layer 0 Description of components The internationalization is currently changing from ListResourceBundles to Property files This chapter is not up dated to fit the change Please read carefully In ArgoUML internationalization sometimes called i18n is done using the ListResourceBundle classes and parts of it is handled by the GEF infrastructure There are several sets of Bundle files for different domains within ArgoUML Each domain has a name and is han dled by a file This is set up in org argouml application Main 5 11 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
132. t 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 related 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 5 2 3 Org argouml cognitive critics class diagram 5 3 Diagrams Purpose to generate a graphical view of the diagrams in the model with tools The contents of the diagrams and 38 Inside the components model is modifyable TODO Notation The Diagrams will be located in org argouml 2 The Diagrams is a Layer 2 component Section 4 6 Layer 2 Description of components The Diagrams are depending on the Model and the GUI framework 5 3 1 How do I add a new element to a diagram 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 and renderer 2 Create a new property panel class that will be displayed in the property tab windown 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
133. t fired by all modelelements of a certain 32 Inside the components class and to register for a set of types of events fired by all modelements of a certain class Of course you can remove your listeners from the event pump This works with methods starting with remove in stead of add 5 1 3 3 Tips 1 Don t forget to remove your listener from the eventpump 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 see 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 etc This will cause the things that need to be done for event type 1 to be fired when event type 2 do arrive 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 The future Some people might wonder if we cannot make a better interface between the model and the rest of ArgoUML if we use our own event types These people are right There are plans to replace the MElementListener with Property ChangeListeners and using the PropertyChangeEvents instead of the MElementEvent This has not been done yet since this involves a lot of work and testing Next to this it is likely tha
134. t the implementation of the Event pump itself is going to change Not the API but the im plementation 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 Besides that the current implementation does not use the standard data structure that Swing uses for event registria tion i e javax swing EventListenerList We are in the process of researching if it is a good thing to use this standard instead of our own implementation 5 1 4 How do l add a new model element Make a parameterless build method for your NSUML modelelement in one of the UML Factories for instance CoreFactory Stick to the UML 1 3 spec to choose the correct Factory The package structure under org argouml mode l uml follows the chapters in the UML spec so get it and read it In the buildmethod cre ate a new modelelement using the appropriate create method in the factory The build method e g is a wrapper around the create method For all elements there are already create methods thanks Thierry For some elements there are already build methods If you need one of these elements use the build method before you barge into building new ones Initialize all things you need in the build method as far as they don t need other modelele ments In the UML spec you can read which elements you need to initialize See for example buildAt tribute for an example
135. target on a tab This probably belongs in the setTarget method of the in dividual tabs and diagrams but that s how it s implemented at the moment 60 Inside the components 5 9 1 1 How dol add a new tab to the MultiEditorPane Create a new class that s a child of JPanel and put the following line in argo ini multi fully classified name of new tab class 5 9 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 component See Section 5 2 Critics and other cognitive tools Documentation Style Source Constraints an ocl view of the current object See Section 5 17 OCL and Tagged values p Warning It is not clear in what component Documentation Style Source and Tagged values belong 5 9 2 1 How dol 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 TabXXX e remove a tab from the Details Panel Remove the line for the tab from org argouml argo ini 5 10 Help System Purpose to provide the menu actions that start the help and other documentation To provide infrastructure that makes context sensitive help possible The Help Sy
136. ted a something that will be part of the ArgoUML product 11 If you during this have discovered other problems create new Issues stating those new problems according to the rule for creating Issues 11 5 How to verify an Issue that is FIXED 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 resolu AAAOSIFOHRESG 99 Processes for the ArgoUML project FORME 2 Run the specified release of ArgoUML as 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 ofthe following e Ifthe problem is gone the feature is present put the Issue in Status VERIFIED e If the problem is still there the feature does not work put the Issue in Status REOPENED with a descrip tion of what is still there is still missing 5 If you during this have discovered other problems than the ones that are stated in the Issue create new Issues stating those new problems according to the rule for creating Issues 6 Dothis as many times as you like until there
137. th the issue he puts it in Resolved status and indicates the resolution is Fixed Worksforme Invalid Wontfix or Duplicate 97 Processes for the ArgoUML project Skills The resolver needs to know a lot of the insides of the ArgoUML code Java coding standards and also the current status of the project with goals requirements and release plans 11 3 3 The Verifier 11 4 The Verifier may be neither the Reporter nor the Resolver of the issue The task of the Verifier is to check the qual ity 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 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
138. the developing of Java classes for the purpose of storing saving and loading an UML Model That work is done by NSUML and is used by ArgoUML 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 check out ArgoUML because 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 log4j a library with infrastructure for logs e antlrall the run time part of the antlr tool 2 2 Download from the CVS repository The CVS repository at Tigris is accessable using the pserver protocol The CVS root is cvs at cvs tigris org You use your Tigris login and Tigris password Building from source This means that you will set the cvsRoor variable to pserver login cvs tigris org cvs where login is your Tigris login This needs to be done for the first checkout After that the root will be remembered by the checked out copy The next thing to do is to login It is done using the command cvs login This only needs to be done once and then the account on your
139. thod In general do not put comments in the body of a method If you are doing something complex enough to need a comment consider breaking it out into its own private commented method Indicate places of future modifications with TODO reason Name all classes with an initial uppercase letter and all variables and methods with a lowercase one I use the allTogetherWithCaps naming style Name static variables with an underscore and an inital capital letter e g _PossibleLanguages Name constants with all upper case and underscores e g GRIP MARGIN To emphasize clusters of classes we are using what we call the binomial naming style I am sure others have thought of this also The root class of the cluster has a short name e g Layer other members of the cluster use that name as a prefix e g LayerGrid This makes many of the class name longer than they might be normally e g Grid would be shorter But this provides a lot of context without having to look at a class inheritance dia gram It is also very nice when you have to look at an alphabetical list of classes I try to name class clusters so that they are not lexigraphically close others e g the Net cluster used to be named Model but that lexigraphi cally overlapped the Mode cluster Four spaces should be used as the unit of indentation Tabs must be set exactly every 8 spaces not 4 and repre sent 2 indents This is exactly as it is stated in the Sun Code Con
140. tic protected MMode helpsmanwridientha ogetti enene A regt Fomdscthelelemenh at spedifi dndex TBhe last quiredClass argument is ignored 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 JScroll Pane VERTICAL SCROLLBAR NEVER and JScrollPane HORIZONTAL SCROLLBAR NEVER it is more helpful to permit at least a vertical scrollbar where needed UScrollPane VERTICAL SCROLLBAR AS NEEDED and JScrollPane HORIZONTAL SCROLLBAR AS NEEDED Finally the inherited method addCaption is used to add the label for the field and addField to add the asso ciated scrollpane The second argument of each of these identifies the index of the caption field pair in the vertical column of the grid for this property panel The third argument identifies the column index The final argument is a vertical weighting to expand the field if there is room in the property tab This is usually set to the same non zero value for all fields and corresponding captions that can have multiple entries so they expand equally If none of the fields should expand the caption only of the last field in each column should be given a non zero value 5 4 1 3 Adding Property Tab Toolbar Buttons These are added by c
141. to what you are doing and there is a convenience method in the class org argouml application api Argo so normal strings are written import org argouml application api String localized Argo localize BUNDLE tag 2 Add your tag and resolution in English in the non localized DomainResourceBundle java file How do I choose the tag Jean Hugues de Raigniac has made a small investigation as to how this is done in the java world and found that there is no real consensus on how to do this He suggests a hierarchical choice of tags like this docpane label since Since docpane label deprecated Deprecated docpane label see See stylepane label bounds Bounds stylepane label fill Fill stylepane label no fill No Fill 3 Contact all the language teams so that they can update their files Notice that if you somewhere change the meaning of a specific localized thing it would be a good idea to use a new tag for the new meaning This will make it easier for the translation team to spot the modification There eledgedly are tools in the java world to spot this kind of changes Until we have the tools and processes in place to handle them it is better to rely on this simpler mechanism to guarantee correctness 5 12 Logging Purpose to provide an api for debug log and trace messages The purpose of debug log and trace messages is To provide a mechanism that allows the developer to e
142. tring getModuleAuthor public Vector getModulePopUpActions Vector popUpActions Object context public String getModuleKey and from Pluggable the methods public boolean inContext Object context 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 parameter2 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 PluggableMenu as an example it contains the function public Object buildContext JMenuItem parentMenuItem String menuType Which is used as follows if module inContext module buildContext help Help help add module getMenuItem help Help 6 2 4 Tip for creating new modules from Florent de Lamotte Florent wrote a small tutorial for creating modules It can be found on the ArgoPNO website http argopno tigris org documentation argouml html 78 Extending ArgoUML 6 3 How are modules organized in in the java code This section is not yet updated to discuss layers The previous section describes how modules and plugins are connected on the java level totally independant of how they are actually l
143. ts Vv These components rely on components of layer in order to do their work 26 ArgoUML Design The Big Picture Diagrams This is the diagram view of the model The notation is a property that belongs in the Diagrams so the different language register their provided notation in the Diagrams component The Diagrams Component is described in detail in Section 5 3 Diagrams Property panels This is the prop panel view of the model The Property Panels Component is described in detail in Section 5 4 Property panels Explorer This is the tree view of the model The Explorer Component is described in detail in Section 5 15 Explorer Code Generation This is the common code for and the point where each language with Code Generation possibility registers The Code Generation Component is described in detail in Section 5 6 Code Generation Component Reverse Engineering This is the common code for and the point where each language with Reverse Engineering possibility registers The Reverse Engineering Component is described in detail in Section 5 5 Reverse Engineering Component Module loader This is the load mechanism for loading all Layer 3 components and other modules into ArgoUML The Module Loader Component is described in detail in Section 5 16 Module loader Property Panel Navigator Panel Reverse Engineering Code Generation Module Loader GUI Framework 4 7 Layer 3
144. ually 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 vari able 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 con tinue working with the same checked out copy 2 4 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 scc new build xml They 10 2 4 1 Building from source 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 build test
145. ui that have a need for it This should be at least the button bar in each diagram where you can draw your modelelement Probably the parent of your modelele ment 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 soin UMLClassDiagram if it belongs there In case of the PropPan els most of them don t use actions 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 modifyable The Property panels will be located in org argouml The Property panels is a Layer 2 component See Section 4 6 Layer 2 Description of components Currently the PropPanels for the diagrams are in org argouml uml diagram ui and the property panels for the other object are in org argouml uml ui NS UML path 5 4 1 Adding the property panel E d Warning 41 Inside the components This description is old and the property panels has undergone some fundamental changes since it was written It would be good if someone that knows how it works now could write a description on how it works now Property Panels are found as class PropPanelXXX java where XXX is the UML metaclass They are in sub packages of org argouml uml ui corresponding to t
146. urpose 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 2 The documentation is generated using build docs This generates all three books and the result appears in argouml build documentation defaulthtml book argouml build documentation printablehtml book and argouml 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 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 argoum1 www documentation are removed from CVS and new files are added cvs n update Watch for Missing and Unknown files The missing files are scheduled to be removed by cvs remove 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
147. utput When releases on the diagram a new class is created both on the diagram where released and in the explorer The type of the association corresponds with the quick button type The association created when clicking the fifth quick button goes back to the class itself 2 6 Making a release To simplify for the person that is actually doing the release work and to make sure that everything is done in the ex act same way every time and nothing is forgotten this list of what to do when releasing is maintained It is provided with the hopes of being helpful To understand this you need knowledge of how cvs works and how you normally build and test ArgoUML This instruction is supposed to work on a windows system running build bat The author Linus Tolke has for some time been running it on a cygwin system running build sh assuming that this will be the same as on any unix system How it is actually run on a cygwin unix system is also noted What needs to be done when one actually does a release 1 Tag the whole CVS repository with the freeze tag Normally this tag is VERSION x v z F e g VERSION 0 9 7 F The according command line CVS command is cvs rtag VERSION x v z F argouml Because of a problem on the Tigris site this doesn t work Instead make sure you have a complete checked out copy of ArgoUML go to the root directory ar gouml and run the command cvs tag VERSION x v z F 2 Check out a new copy of the source Th
148. ventPump getPump removeModelEventListener this modelelementlIAmInterestedIn IamInterest 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 modelelements This works with the method addModelEventListener MElementListener listener MBase modelelement As you can see no names of events you can register for here Furthermore you can add a listener that is interested in several types of events but coming from 1 modelelement This is a convenience method for not having to call the methods explained in section Section 5 1 3 2 1 How do I register a listener for a certain type event more than once It works via addModelEventListener MElementListener listener MBase modelelement String eventNames You can pass the method an array of strings with eventnames in which your listener is interested Thirdly there is a very powerfull method to register your listener to ALL events fired by a ALL modelelements of a certain class You can understand that using this method can have severe performance impacts Therefore use it with care The method is addClassModelEventListener MElementListener listener Class modelClass There are also methods that allow you to register only for one type of even
149. ventions It is here just for the emphasis If possible use lines shorter than 80 charaters wide This is exactly as it is stated in the Sun Code Conventions It is here just for the emphasis 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 89 Standards for coding in ArgoUML For everything else follow Code Conventions for the Java Programming Language http java sun com docs codeconv html CodeConvTOC doc html 9 1 Settings for Eclipse These style guides correspond to the following settings in Eclipse 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 In Preferences gt Java gt Code Formatter gt Line Splitting Maximum line length is 80 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 as Number of spaces representing a level of indentation In Preferences gt Java gt Java Editor gt Appearance Displayed tab width 8 Insert space for tabs see Formatting preference
150. y and change the value if you want java classname org argouml application Main fork yes classpath build dest classpath gt lt sysproperty key log4j configuration value org argouml resource filename lcf sysproperty java target 5 12 3 2 when running ArgoUML from WebStart To view the console output the WebStart user has to set Enable Java Console in the Java WebStart preferences In the same dialog there is also an option to save the Console Output to a file 68 Inside the components 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 12 3 3 when running ArgoUML from NetBeans At 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 Example 5 6 External Execution Property Arguments cp filesystems classpath library Dlog4j configuration URL classname arguments 5 12 4 How to Customize Logging There are some sample configuration files provided in org argouml resource Modify these according to your needs Or alternatively you can try configLog4j http www japhy de configLog4j to assist yourself in

Cookbook for Developers of ArgoUML

Contents

Download Pdf Manuals

Related Search

Related Contents