org.argouml.cognitive.critics
Class Critic

java.lang.Object
  |
  +--org.argouml.cognitive.critics.Critic
All Implemented Interfaces:
Poster, java.io.Serializable
Direct Known Subclasses:
CompoundCritic, CrUML

public class Critic
extends java.lang.Object
implements Poster, java.io.Serializable

"Abstract" base class for design critics. Each subclass should define its own predicate method and define its own relevance tags.

A critic supports design goals and decisions, which can be adjusted accordingly. It will post todo items which may or may not be relevant to the particular designer.

Steps to follow when adding a critic are listed in the Argo cookbook under define_critic.

See Also:
Serialized Form

Field Summary
private  java.util.Hashtable _args
          Arguments used to configure the critic.
protected  javax.swing.Icon _clarifier
           
private  java.util.Hashtable _controlRecs
          Control records used in determining if this Critic should be active.
private  java.lang.String _criticType
          The decision type of this critic.
private  java.lang.String _decisionCategory
          The decision category that this critic is relevant to.
private  java.lang.String _description
          The description of the ToDoItem produced.
private  java.lang.String _emailAddr
          The email address of the author/maintainer of this critic.
private  java.lang.String _headline
          The headline of the ToDoItem produced.
private  boolean _isActive
          Internal flag that stores the end result of all ControlMech evaluations of this critic.
protected  VectorSet _knowledgeTypes
           
private  java.lang.String _moreInfoURL
          The moreInfoURL of the ToDoItem produced.
static int _numCriticsFired
           
private  int _priority
          The priority of the ToDoItem produced.
protected  java.util.Vector _supportedDecisions
           
protected  java.util.Vector _supportedGoals
           
protected  long _triggerMask
           
private static Logger cat
          logger
static javax.swing.Icon DEFAULT_CLARIFIER
          The icon representing the resource.
static java.lang.String ENABLED
          The keys of some predefined control records.
static java.lang.String KT_COMPLETENESS
           
static java.lang.String KT_CONSISTENCY
           
static java.lang.String KT_CORRECTNESS
           
static java.lang.String KT_DESIGNERS
          Types of knowledge that critics can deliver
static java.lang.String KT_EXPERIENCIAL
           
static java.lang.String KT_OPTIMIZATION
           
static java.lang.String KT_ORGANIZATIONAL
           
static java.lang.String KT_PRESENTATION
           
static java.lang.String KT_SEMANTICS
           
static java.lang.String KT_SYNTAX
           
static java.lang.String KT_TOOL
           
static boolean NO_PROBLEM
           
static boolean PROBLEM_FOUND
           
static java.lang.String SNOOZE_ORDER
           
 
Constructor Summary
Critic()
          Construct a new critic instance.
 
Method Summary
 java.lang.Object addControlRec(java.lang.String name, java.lang.Object controlData)
          Add some attribute used by ControlMech to determine if this Critic should be active.
 void addKnowledgeType(java.lang.String type)
           
 void addSupportedDecision(Decision d)
           
 void addSupportedGoal(Goal g)
           
 void addTrigger(java.lang.String s)
           
 void beActive()
          Make this critic active.
 void beInactive()
          Make this critic inactive.
 boolean canFixIt(ToDoItem item)
          TODO: Not implemented yet.
 boolean containsKnowledgeType(java.lang.String type)
           
 void critique(java.lang.Object dm, Designer dsgr)
          Examine the given Object and Designer and, if appropriate, produce one or more ToDoItem's and add them to the offending design material's and the Designer's ToDoList.
 java.lang.String defaultMoreInfoURL()
          This function calculates the default url to describe this critic.
 java.lang.String expand(java.lang.String desc, VectorSet offs)
          Customize the description string just before it is displayed.
 void fixIt(ToDoItem item, java.lang.Object arg)
          TODO: Not implemented yet.
protected  java.lang.Object getArg(java.lang.String name)
           
 java.util.Hashtable getArgs()
           
 javax.swing.Icon getClarifier()
           
 java.lang.Object getControlRec(java.lang.String name)
          Reply the named control record, or null if not defined.
 java.lang.String getCriticCategory()
          Returns a default critic category.
 ConfigurationKey getCriticKey()
          Returns the ConfigurationKey that the critic uses to determine if it is enabled or disabled.
 java.lang.String getCriticName()
          Returns a default critic name.
 java.lang.String getCriticType()
          Reply a string used to contol critics according to type.
 java.lang.String getDecisionCategory()
          Reply a string used to determine if this critic would be relevant to current design decisions.
 java.lang.String getDescription(VectorSet offenders, Designer dsgr)
          Reply the description used in feedback produced by this Critic.
 java.lang.String getDescriptionTemplate()
           
 java.lang.String getExpertEmail()
          Reply the email address of the person who is the author or maintainer of this critic.
 java.lang.String getHeadline()
          Reply the headline used in feedback produced by this Critic.
 java.lang.String getHeadline(java.lang.Object dm, Designer dsgr)
          Reply the headline used in feedback produced by this Critic.
 java.lang.String getMoreInfoURL()
           
 java.lang.String getMoreInfoURL(VectorSet offenders, Designer dsgr)
          Reply the moreInfoURL used in feedback produced by this Critic.
 int getPriority()
           
 int getPriority(VectorSet offenders, Designer dsgr)
          Reply the priority used in feedback produced by this Critic.
 java.util.Vector getSupportedDecisions()
           
 java.util.Vector getSupportedGoals()
           
 long getTriggerMask()
           
 java.lang.Class getWizardClass(ToDoItem item)
          Return the Class of wizard that can fix the problem identifed by this critic.
 void initWizard(Wizard w)
          Initialize a newly created wizard with information found by the critic.
 boolean isActive()
          Reply true iff this Critic can execute.
 boolean isEnabled()
          This is a convient method for accessing one well-known control record.
 boolean isRelevantToDecisions(Designer dsgr)
          Reply true if this Critic is relevant to the decisions that the Designer is considering.
 boolean isRelevantToGoals(Designer dsgr)
          Reply true iff this Critic is relevant to the goals that the Designer is trying to achieve.
 Wizard makeWizard(ToDoItem item)
          Create a new Wizard to help the user fix the identified problem.
 boolean matchReason(long patternCode)
           
 void postItem(ToDoItem item, java.lang.Object dm, Designer dsgr)
           
 boolean predicate(java.lang.Object dm, Designer dsgr)
          Perform the Critic's analysis of the design.
static int reasonCodeFor(java.lang.String s)
           
protected  void setArg(java.lang.String name, java.lang.Object value)
           
 void setArgs(java.util.Hashtable h)
           
protected  void setDecisionCategory(java.lang.String c)
          Set the decisionCategory, usually done in the constructor.
 void setDescription(java.lang.String d)
           
 void setEnabled(boolean e)
           
 void setExpertEmail(java.lang.String addr)
          Set the email address of the person who is the author or maintainer of this critic.
 void setHeadline(java.lang.String h)
          Set the headline used in feedback produced by this Critic.
 void setKnowledgeTypes(java.lang.String t1, java.lang.String t2)
           
 void setKnowledgeTypes(java.lang.String t1, java.lang.String t2, java.lang.String t3)
           
 void setKnowledgeTypes(VectorSet kt)
           
 void setMoreInfoURL(java.lang.String m)
           
 void setPriority(int p)
           
 void snooze()
          Disable this Critic for the next few minutes.
 SnoozeOrder snoozeOrder()
          Reply the SnoozeOrder that is defined for this critic.
 boolean stillValid(ToDoItem i, Designer dsgr)
          Return true iff the given ToDoItem is still valid and should be kept in the given designers ToDoList.
 boolean supports(Decision d)
           
 boolean supports(Goal g)
           
 ToDoItem toDoItem(java.lang.Object dm, Designer dsgr)
          Reply the ToDoItem that the designer should see iff predicate() returns true.
 java.lang.String toString()
          Reply a string that describes this Critic.
 void unsnooze()
          Lift any previous SnoozeOrder.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

cat

private static Logger cat
logger


PROBLEM_FOUND

public static final boolean PROBLEM_FOUND
See Also:
Constant Field Values

NO_PROBLEM

public static final boolean NO_PROBLEM
See Also:
Constant Field Values

ENABLED

public static final java.lang.String ENABLED
The keys of some predefined control records.

See Also:
Constant Field Values

SNOOZE_ORDER

public static final java.lang.String SNOOZE_ORDER
See Also:
Constant Field Values

KT_DESIGNERS

public static java.lang.String KT_DESIGNERS
Types of knowledge that critics can deliver


KT_CORRECTNESS

public static java.lang.String KT_CORRECTNESS

KT_COMPLETENESS

public static java.lang.String KT_COMPLETENESS

KT_CONSISTENCY

public static java.lang.String KT_CONSISTENCY

KT_SYNTAX

public static java.lang.String KT_SYNTAX

KT_SEMANTICS

public static java.lang.String KT_SEMANTICS

KT_OPTIMIZATION

public static java.lang.String KT_OPTIMIZATION

KT_PRESENTATION

public static java.lang.String KT_PRESENTATION

KT_ORGANIZATIONAL

public static java.lang.String KT_ORGANIZATIONAL

KT_EXPERIENCIAL

public static java.lang.String KT_EXPERIENCIAL

KT_TOOL

public static java.lang.String KT_TOOL

_emailAddr

private java.lang.String _emailAddr
The email address of the author/maintainer of this critic.


_priority

private int _priority
The priority of the ToDoItem produced.


_headline

private java.lang.String _headline
The headline of the ToDoItem produced.


_description

private java.lang.String _description
The description of the ToDoItem produced.


_moreInfoURL

private java.lang.String _moreInfoURL
The moreInfoURL of the ToDoItem produced.


_args

private java.util.Hashtable _args
Arguments used to configure the critic. TODO: Could this be removed from the main critics class?


DEFAULT_CLARIFIER

public static javax.swing.Icon DEFAULT_CLARIFIER
The icon representing the resource.


_clarifier

protected javax.swing.Icon _clarifier

_decisionCategory

private java.lang.String _decisionCategory
The decision category that this critic is relevant to. The idea of each critic being relevant to exactly one type of decision is a very simple one. Subclasses that have more sophisticated decision relevance logic should override isRelevantToDecisions. You can also define new ControlMech's.

Decision categories are defined in the DecisionModel of a particular domain.

See Also:
ControlMech

_supportedDecisions

protected java.util.Vector _supportedDecisions

_supportedGoals

protected java.util.Vector _supportedGoals

_criticType

private java.lang.String _criticType
The decision type of this critic. For example, correctness, completeness, consistency, alternative, presentation, optimization, organizational, tool critics, etc.


_isActive

private boolean _isActive
Internal flag that stores the end result of all ControlMech evaluations of this critic.


_controlRecs

private java.util.Hashtable _controlRecs
Control records used in determining if this Critic should be active.


_knowledgeTypes

protected VectorSet _knowledgeTypes

_triggerMask

protected long _triggerMask

_numCriticsFired

public static int _numCriticsFired
Constructor Detail

Critic

public Critic()
Construct a new critic instance. Typically only one instance of each critic class is created and stored in a static variable, as per the Singleton pattern. Each domain extension should define a static initializer block to make one instance of each critic and call Agency.register(java.lang.String, java.lang.String) with that instance.

Method Detail

defaultMoreInfoURL

public final java.lang.String defaultMoreInfoURL()
This function calculates the default url to describe this critic. This syntax is synchronized with:
  1. Tags in the manual.
  2. Name of the ArgoUML site.
  3. How the manual is deployed on the site.
so this must be updated when any of these change.


getCriticKey

public ConfigurationKey getCriticKey()
Returns the ConfigurationKey that the critic uses to determine if it is enabled or disabled. The string resulting from the ConfigurationKey argo.critic.critic_category.critic_name. critic_category would describe the type of critic and is taken from getCriticCategory(). critic_name would describe the function of the critic and is taken from getCriticName(). Some examples: argo.critic.layout.Overlap argo.critic.uml.ReservedWord argo.critic.java.ReservedWord argo.critic.idl.ReservedWord

Since:
0.9.4
See Also:
Configuration.makeKey(java.lang.String), getCriticCategory(), getCriticName()

getCriticCategory

public java.lang.String getCriticCategory()
Returns a default critic category. Critics should override this to provide specific classification information.

Since:
0.9.4

getCriticName

public java.lang.String getCriticName()
Returns a default critic name. By default this is the simple class name. Critic implementations should override this to provide a better (more descriptive) string.

Since:
0.9.4

critique

public void critique(java.lang.Object dm,
                     Designer dsgr)
Examine the given Object and Designer and, if appropriate, produce one or more ToDoItem's and add them to the offending design material's and the Designer's ToDoList. By default this is basically a simple if-statement that relies on predicate() to determine if there is some appropriate feedback, and toDoItem() to produce the ToDoItem. The predicate() and toDoItem() pair of methods is simple and convient for many critics. More sophisticated critics that produce more than one ToDoItem per critiquing, or that produce ToDoItem's that contain information that was already computed in the predicate, should override critique. If you override this method, you should call super.critique().

See Also:
# @see Critic#toDoItem

postItem

public void postItem(ToDoItem item,
                     java.lang.Object dm,
                     Designer dsgr)

predicate

public boolean predicate(java.lang.Object dm,
                         Designer dsgr)
Perform the Critic's analysis of the design. Subclasses should test the given Object to make sure that it is the type of object that is expected. Each object in the design registers its own critics with the run-time system. The dm parameter is bound to each design object that registered this critic, one per call. Returning true means that feedback should be delivered to the Designer. By convention, subclasses should return their superclass predicate method if their own predicate would return false.


stillValid

public boolean stillValid(ToDoItem i,
                          Designer dsgr)
Return true iff the given ToDoItem is still valid and should be kept in the given designers ToDoList. Critics that are not enabled should always return false so that their ToDoItems will be removed. Subclasses of Critic that supply multiple offenders should always override this method.

By default this method basically asks the critic to again critique the offending Object and then it checks if the resulting ToDoItem is the same as the one already posted. This is simple and it works fine for light-weight critics. Critics that expend a lot of computational effort in making feedback that can be easily check to see if it still holds, should override this method.

TODO: Maybe ToDoItem should carry some data to make this method more efficient.

Specified by:
stillValid in interface Poster

supports

public boolean supports(Decision d)
Specified by:
supports in interface Poster

getSupportedDecisions

public java.util.Vector getSupportedDecisions()
Specified by:
getSupportedDecisions in interface Poster

addSupportedDecision

public void addSupportedDecision(Decision d)

supports

public boolean supports(Goal g)
Specified by:
supports in interface Poster

getSupportedGoals

public java.util.Vector getSupportedGoals()
Specified by:
getSupportedGoals in interface Poster

addSupportedGoal

public void addSupportedGoal(Goal g)

containsKnowledgeType

public boolean containsKnowledgeType(java.lang.String type)
Specified by:
containsKnowledgeType in interface Poster

addKnowledgeType

public void addKnowledgeType(java.lang.String type)

setKnowledgeTypes

public void setKnowledgeTypes(VectorSet kt)

setKnowledgeTypes

public void setKnowledgeTypes(java.lang.String t1,
                              java.lang.String t2)

setKnowledgeTypes

public void setKnowledgeTypes(java.lang.String t1,
                              java.lang.String t2,
                              java.lang.String t3)

reasonCodeFor

public static int reasonCodeFor(java.lang.String s)

getTriggerMask

public long getTriggerMask()

addTrigger

public void addTrigger(java.lang.String s)

matchReason

public boolean matchReason(long patternCode)

expand

public java.lang.String expand(java.lang.String desc,
                               VectorSet offs)
Description copied from interface: Poster
Customize the description string just before it is displayed.

Specified by:
expand in interface Poster

getClarifier

public javax.swing.Icon getClarifier()
Specified by:
getClarifier in interface Poster

isActive

public boolean isActive()
Reply true iff this Critic can execute. This fact is normally determined by a ControlMech.


beActive

public void beActive()
Make this critic active. From now on it can be applied to a design material in critiquing.


beInactive

public void beInactive()
Make this critic inactive. From now on it will be idle and will not be applied to a design material in critiquing.


addControlRec

public java.lang.Object addControlRec(java.lang.String name,
                                      java.lang.Object controlData)
Add some attribute used by ControlMech to determine if this Critic should be active. Critics store control record so that stateful ControlMech's do not need to store a parallel data structure. But Critic's do not directy use or modify this data.


getControlRec

public java.lang.Object getControlRec(java.lang.String name)
Reply the named control record, or null if not defined.


isEnabled

public boolean isEnabled()
This is a convient method for accessing one well-known control record. The enabled control record is a boolean that the user can turn on or off to manually enable or disable this Critic. It is normally combined with other ControlMech determinations with a logic-and.


setEnabled

public void setEnabled(boolean e)

snoozeOrder

public SnoozeOrder snoozeOrder()
Reply the SnoozeOrder that is defined for this critic.


snooze

public void snooze()
Disable this Critic for the next few minutes.

Specified by:
snooze in interface Poster

unsnooze

public void unsnooze()
Lift any previous SnoozeOrder.

Specified by:
unsnooze in interface Poster

isRelevantToDecisions

public boolean isRelevantToDecisions(Designer dsgr)
Reply true if this Critic is relevant to the decisions that the Designer is considering. By default just asks the Designer if he/she is considering my decisionCategory. Really this is something for a ControlMech to compute, but if a subclass of Critic encapsulates some information you may need to override this method.


isRelevantToGoals

public boolean isRelevantToGoals(Designer dsgr)
Reply true iff this Critic is relevant to the goals that the Designer is trying to achieve. By default, all Critic's are relevant regardless of the GoalModel. Really this is something for a ControlMech to compute, but if a subclass of Critic encapsulates some information you may need to override this method.

TODO: I would like a better default action, but goals are typed and their values must be interperted by critics. They are not as generic as the DecisionModel.


makeWizard

public Wizard makeWizard(ToDoItem item)
Create a new Wizard to help the user fix the identified problem. This version assumes subclasses override getWizClass to return the appropriate Class of wizard. Critic subclasses that need to initialize their wizard might override this to call super.makeWizard() and then work with the result.


getWizardClass

public java.lang.Class getWizardClass(ToDoItem item)
Return the Class of wizard that can fix the problem identifed by this critic. This method returns null, subclasses with wizards should override it.

Returns:
null if no wizard is defined.

initWizard

public void initWizard(Wizard w)
Initialize a newly created wizard with information found by the critic. This is called right after the wizard is made in makeWizard() and after the wizard's ToDoItem is set. Any critic that supports wizards should probably override this method, and call super initWizard() first.


getDecisionCategory

public java.lang.String getDecisionCategory()
Reply a string used to determine if this critic would be relevant to current design decisions. Strings returned from here are compared to strings in the DecisionModel.


setDecisionCategory

protected void setDecisionCategory(java.lang.String c)
Set the decisionCategory, usually done in the constructor. I have not yet thought of a case where dynamically changing the Critic's decisionCategory is useful.


getCriticType

public java.lang.String getCriticType()
Reply a string used to contol critics according to type. Examples include: correctness, completeness, consistency, optimization, presentation, and alternative.


getExpertEmail

public java.lang.String getExpertEmail()
Reply the email address of the person who is the author or maintainer of this critic.

Specified by:
getExpertEmail in interface Poster

setExpertEmail

public void setExpertEmail(java.lang.String addr)
Set the email address of the person who is the author or maintainer of this critic.

Specified by:
setExpertEmail in interface Poster

getHeadline

public java.lang.String getHeadline(java.lang.Object dm,
                                    Designer dsgr)
Reply the headline used in feedback produced by this Critic.


getHeadline

public java.lang.String getHeadline()
Reply the headline used in feedback produced by this Critic.


setHeadline

public void setHeadline(java.lang.String h)
Set the headline used in feedback produced by this Critic.


getPriority

public int getPriority(VectorSet offenders,
                       Designer dsgr)
Reply the priority used in feedback produced by this Critic.


setPriority

public void setPriority(int p)

getPriority

public int getPriority()

getDescription

public java.lang.String getDescription(VectorSet offenders,
                                       Designer dsgr)
Reply the description used in feedback produced by this Critic.


setDescription

public void setDescription(java.lang.String d)

getDescriptionTemplate

public java.lang.String getDescriptionTemplate()

getMoreInfoURL

public java.lang.String getMoreInfoURL(VectorSet offenders,
                                       Designer dsgr)
Reply the moreInfoURL used in feedback produced by this Critic.


setMoreInfoURL

public void setMoreInfoURL(java.lang.String m)

getMoreInfoURL

public java.lang.String getMoreInfoURL()

setArg

protected void setArg(java.lang.String name,
                      java.lang.Object value)

getArg

protected java.lang.Object getArg(java.lang.String name)

getArgs

public java.util.Hashtable getArgs()

setArgs

public void setArgs(java.util.Hashtable h)

toDoItem

public ToDoItem toDoItem(java.lang.Object dm,
                         Designer dsgr)
Reply the ToDoItem that the designer should see iff predicate() returns true. By default it just fills in the fields of the ToDoItem from accessor methods of this Critic. Critic Subclasses may override this method or the accessor methods to add computed fields to the ToDoItem. TODO: Critic's may want to add new fields to a ToDoItem to make stillValid more efficent.

See Also:
critique(java.lang.Object, org.argouml.cognitive.Designer)

canFixIt

public boolean canFixIt(ToDoItem item)
TODO: Not implemented yet. The idea is that some problems identified by Critic's can be fixed with certain design manipulations (or transforms) that can be applied automatically to resolve the problem. This method replies true iff the given problem can be fixed. The fixIt() method actually does the fix.

Specified by:
canFixIt in interface Poster
See Also:
fixIt(org.argouml.cognitive.ToDoItem, java.lang.Object)

fixIt

public void fixIt(ToDoItem item,
                  java.lang.Object arg)
TODO: Not implemented yet. If the given ToDoItem can be fixed automaically, and the user wants that to happen, then do it. Obviously, this depends on the specific Critic and problem. By default this method does nothing.

Specified by:
fixIt in interface Poster
See Also:
canFixIt(org.argouml.cognitive.ToDoItem)

toString

public java.lang.String toString()
Reply a string that describes this Critic. Identical to getCriticName()

Overrides:
toString in class java.lang.Object


ArgoUML © 1996-2004 (20040306)ArgoUML HomepageArgoUML Developers' pageArgoUML Cookbook