- Purpose
- To provide cognitive help for the User. This help is based on the current model that the User works with.
- Layer
- Located
org.argouml.cognitive
This subsystem contains the following main class types:
- Critics provide help to find artifacts in the model that do not obey simple design "rules" or "best practices".
- Checklists provide help for the user to suggest and keep track of considerations that the user should make for each design element. Checklists are currently (0.9.5 and 0.9.6) turned off.
ToDoItems provide a way for the Critics to communicate their knowledge to the User and let the User start Wizards.
- Wizards are step by step instructions that fix problems found by the Critics.
Public API
Here is an illustration of the main classes implementing critics
Critics are currently located in:
org.argouml.cognitive.critics
- These are basic critics, which are very general in nature. For example ArgoUML keeps nagging when Model elements overlap, which makes the Diagram hard to read.
- This package also contains the base classes for the handling.
org.argouml.uml.cognitive.critics
- These are Critics which are directly related to UML issues (well, more or less). For example, it will nag when a class has too many operations, because that makes it hard to maintain the particular class.
- This package also contains Wizards used by these Critiques.
org.argouml.pattern.cognitive.critics
- These are critics related to patterns. Currently they deal only with the Singleton pattern
org.argouml.language.java.cognitive.critics
- These are critics which deal with java specific issues. Currently this is only a warning against modeling multiple inheritance.
The Base class for Wizards is org.argouml.kernel.Wizard.
Checklists are located in the package org.argouml.cognitive.checklist.
Helper classes for To Do Items, To Do Pane, Wizards and the Knowledge Types are located in the package org.argouml.cognitive.ui.
How do I...?
- ...create a new critique?
- Currently the only way to add a new critique is to write a class that implements it so that is described here. There have however been ideas on a possibility to build critics in some other way in the future, as a set of rules instead of java code.
Create a new critic class, of the form CrXxxxYyyyZzzz, extending CrUML. Typically your new class will go in the package org.argouml.uml.cognitive.critics, but it could go in one of the other cognitive.critics packages.
- Write a constructor, which takes no arguments and calls the following methods of CrUML:
- setHeadline(""); to set up the locale specific text for the critic headline (the one liner that appears in the to-do pane) and the critic description (the detailed explanation that appears in the to-do tab of the details pane). The String parameter is ignored.
- addSupportedDecision(UMLDecision.decAAAA); where AAAA is the design issue category this critic falls into (examples include STORAGE, PATTERNS, METHODS).
setPriority(ToDoItem.BBB_PRIORITY); where BBB is one of LOW, MEDIUM or HIGH, to set the priority for the critic in the to-do pane.
- addTrigger("UML Meta-Class"); where UML Meta-Class is a UML Meta-Class, with initial lower capital, e.g. "associationEnd". The intention is that critics should only trigger for elements (or children) of particular UML meta-classes. I (Jeremy Bennett February 2002) believe this code is not yet working so you can probably leave it out. You can have multiple calls to this method for different meta-classes.
- After this add a method public boolean predicate2(Object dm, Designer dsgr);. This is the decision routine for the critic. The parameter dm (short for Design Material) is the UML entity (a Model subsystem object) that is being checked. The second argument, dsgr (short for Designer) is for 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.
- The parameter 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 bundles. These are in the package org.argouml.i18n, in the file critics.properties. You need to add two keys for the head and description, which will be named respectively critics.CrXxxxxYyyyZzzz-head and critics.CrXxxxxYyyyZzzz-desc. There are plenty of examples to look at there. Headlines shall be unique, see issue 618. The other files 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 Init of the class org.argouml.uml.cognitive.critics.Init, add two statements:
private 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 as well, which is:
java.lang.Class XxxYyyyZzCls = MXxxYyyyZzImpl.class;where MXxxYyyyZzImpl.class should be part of the NovoSoft UML package. CategoryFix: Remove NovoSoft reference.
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.
- ...fix a critique?
- Locate the critique and insert some logging code. You should make sure that you understand all the implications of changes, therefore it is a good idea to see what makes the critic nag in the first place. But rest assured: some of the critics haven't been updated to reflect the latest changes in ArgoUML, so this is a procedure which is well worth digging into, since it gives you also some exposure to related UML elements.
- ...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.
- ...get my critic to trigger?
- This is a suggested way to troubleshoot if the critic doesn't trigger.
- Check that the settings for critics are enabled (Toggle Auto Critique)
- Check that your critic is registered in org.argouml.uml.cognitive.critics.Init with the right class (e.g. check inheritance structure against UML spec)
- Check that your particular critic is enabled in Browse Critics
- (IMPORTANT) Check that the design material is actually found in org.argouml.uml.cognitive.critics.ChildGenUML. This method is incomplete and might not find all model elements!
Design of the subsystem
org.argouml.cognitive.critics.* class diagram: [attachment:argocogcritics.png]
Used sybsystems
This subsystem uses the following other subsystems:
<<Subsystem>> Model for information to base decisions on.
<<Subsystem>> To Do items to present information.