Argo v05 Cookbook

This file prepared on 5/30/97.

This file describes how to do specific tasks in extending Argo and applying it to new domains. These descriptions are inteded for programmers who have some knowledge of Java(tm), and have read the Argo Overview, are considering making modifications to Argo.

Table of contents:

  1. How to use this cookbook
  2. How to define a new domain
  3. How to define a domain-specific design material
  4. How to define a domain-specific design perspective
  5. How to define a domain-specific decision category
  6. How to add a domain-specific critic

How to use this cookbook

Background: Cookbooks are intented to help people accomplish specific structured tasks. They mainly provide process information in the form of a sequence of steps, and domain-specific knowledge in the form of brief descriptions and links to background materials. The format of each cookbook entry (recipe) is similiar to this one.

Applicability: You should use a cookbook when there is a specific task you want to accomplish and there is a recipe in the cookbook that supports that specific task. Also, browse the cookbook to see what tasks are supported.

Ingredients: Each recipe lists the matierals that you may need to accomplish the task. Not all matierals are needed in all cases.

Steps:

  1. Find the recipe by scanning the cookbook's table of contents or by following a link from javadoc comments in the code or other documentation.
  2. Check the "Background" and "Applicability" sections to make sure that the recipe is what you were looking for. Scan the "Steps" to get an idea of what you will have to do. Read the "Results" section to see what the recipe will produce and how to check that the task was successfully completed.
  3. Prepare to follow the steps by gathering the needed ingredients.
  4. Perform the actions described in the recipe's steps.
  5. Optional: Follow steps marked "Optional" to achieve minor variants or advanced versions of the task.

Results: Each recipe lists the results that you can expect and how to verify that the task was completed successfully.


How to define a new domain

Background: Argo provides a domain-independent infrastructure for building domain-dependent design environments. The Argo infrastructure provides general support for design representation, critics, the ToDoList, the decision model, and domain-independent user interfaces. It is the task of a domain engineer to specialize the Argo infrastructure to a particular domain. We have defined domain models for C2 style software architecture, a simple design decision process model, and a very simple object-oriented design (eventually we may support UML). We will also be applying Argo to a requirements specification domain.

Applicability: Use this recipe when you want to apply Argo to a new domain.

Ingredients: A general understanding of the domain and of the Argo infrastructure. As you learn more about the domain you can modify the domain model. You should find it easy to start small and add more incrementally.

Steps:

  1. Make a new java package and directory for the code in your domain model.
  2. Create an overview file in that directory and start making notes about the assets you will need to model this domain.
    • Design Materials make up the design in this domain. For example, software components in a software architecture domain, classes in a OOAD domain, or furniture in an office floorplan domain.
    • Properties are attributes of the design materials. Often a property will be used on multiple design materials, so we factor out their definition to some extent.
    • Relationships between the design materials. For example, communication relationships between software components.
    • Design Perspectives are views of the design that emphasize certain design materials and relationships over others. Designers use multiple design perspectives to address all the diverse issues of design.
    • Decision Categories sketch out decisions that designers must make to complete a design.
    • Design Critics are agents that check for potential problems in the design and give the designer knowledge about how to make good designs.
    • Manipulations to the design that could be automated. (Needs-More-Work: this is not supported yet.)
  3. Define a new class to hold constants and properties specific to your domain. Be sure to follow Argo's naming conventions. For example, jargo/process/IDEF.java.
  4. Optional: Define abstract subclasses of jargo.kernel.Critic and jargo.kernel.DesignMaterial. These will serve as super classes for the critics and design materials you will define later.
  5. Optional: Define a subclass of jargo.kernel.Design that is specific to your domain. In Argo Design objects are containers that hold design materials. You should define a new type of design if you need critics that operate on an entire design rather than specific design material instances. For example, see jargo.softarch.Architecture.
  6. Optional: Define a main program to launch browsers and editors and congifure the GEF and Argo frameworks and load assets one or more domains. For example, see class jargo.softarch.klax.Main. The Argo naming convention for main programs is that they be defined in classes named "Main". You do not need a main program if you already have one and are simply adding a new domain for use with that main program.
  7. Define the assets of the domain model by following the appropriate recepies:
  8. Repeat these steps as needed to finish the domain model. Test your code frequently by constructing some simple designs. Typically it makes sense to go by design perspectives: choose one perspective and define all the design materials that will be shown there, then move on to the next design perspective.

Results: An initial version of a domain-modeling extension to Argo's infrastructure.


How to define a domain-specific design material

Background: Design materials are the types of design elements that can be used in a given domain. For example, software components in a software architecture domain, or funiture in a office floorplan domain. In Argo design materials are objects that are defined in subclasses of class jargo.kernel.DesignMaterial.

Applicability: Add a new DesignMaterial when you want to extend the domain model to a new type of design element.

Ingredients: An understanding of the design element to be modeled.

Steps:

  1. Subclass jargo.kernel.DesignMaterial or your abstract design material class to make a new class. Make sure you follow Argo's naming conventions. Part of defining a domain model is discovering commonalities between design elements and building a class hierarchy of design materials in your domain.
  2. Define attributes and behavior of the design matieral using arbitrary Java code. See numerous examples in package jargo.softarch. By convention design material classess do not define very many instance variables, instead they use the IProps interface and code inherited from class DesignMaterial to store needed values. Typically the names of these properties are coded as constant strings in a single class in the domain package, dor example see class jargo.softarch.C2. If you want to store values in instance variables and have them editable in the Property Sheet, you should consult the GEF documentation.
  3. Define node and node perspectives for your design matierals and arcs and arc perspectives for your relationships. Nodes and arcs are objects used in GEF's representation of connected graphs. Node perspectives and arc perspectives are used to visualize GEF's nodes and arcs. Nodes should subclass from uci.graphedit.NetNode, arcs should subclass from uci.graphedit.NetArc. If you want to strictly impose simple constraints on what can be connected, override canConnectTo() from class uci.graphedit.NetNode. Multiple perspectives can be defined for each node and multiple arc perspectives can be defined for each arc. Node perspectives subclass from your abstract node perspective class or uci.graphedit.Perspective arc perspectives subclass from uci.graphedit.ArcPerspective. The method perspectiveFor() is used to select a perspective for a given node or arc and a given design perspective. For examples see the following classes is jargo/softarch/: C2Node, C2CompNode, C2ConnNode, C2PerzComp1, C2PerzComp2, C2PerzConn1, C2PerzConn2, C2Arc.

For more information on developing the binding between an Argo model and a GEF diagram, see the GEF documentation.

Results: A new kind of domain-specific design matieral that can be selected from the palette, placed in a design, edited via the property sheet, shown in different perspectives, and related to other design materials.


How to define a domain-specific design perspective

Background: Expert designers consider a wide range of design issues, and they use multiple mental models of the design to address those diverse design issues. Argo provides design perspectives to allow designers to visualize the design in multiple ways that "match" their multiple mental models. Most of Argo's support for design perspectives is actually implemented in GEF.

Applicability: Define a new design perspective when you are ready to extend your domain model to address a new set of design issues that need to be visualized together. As a short-cut in defining a domain, design perspectives can be made overly broad, causing multiple unrelated issues can be visualized together. The need for a new design perspective often becomes clear when existing design perspectives become too hard to visualize (because they are crowded, large, or too non-planar).

Ingredients: Knowledge of the design issues of concern in this domain. Knowledge of what design materials and relationships are related to the design issues being supported by this perspective. Visualizations for design materials and relationships that are appropriate for use in this design perspective.

Steps:

  1. Instanciate and configure a new design perspective in your main program. Design perspectives are instances of class uci.graphedit.LayerPerspective. Each perspective is named and given a perspective type string. For example, see class jargo.softarch.klax.Main. For more details on defining a design perspective see the GEF documentation.
  2. Implement the perspectiveFor() method of your node classes to instanciate the proper kind of node perspective. Implement the perspectiveFor() method of your arc classes to instanciate the proper kind of arc perspective.
  3. Optional: Define spacial regions of the new design perspective where various design materials will be automatically placed. This is useful if a given design material should appear in multiple perspectives. When the designer places a design material in one perspective, that adds a node to GEF's connected graph representation, and each design perspective is notified. Design perspectives automatically add node perspectives for nodes that they accept. The position of these new node perspectives is determined by the regions, if define. (Needs-More-Work: move most of this to the GEF documentation.)

Results: A new design perspective that the design can use to visualize design elements related to specific design issues.


How to define a domain-specific decision category

Background: Decision categories make up Argo's decision model. The decision model lists decision categories that the designer is currently considering. This information is used to enable or disable critics so that they are timely to decisions being considered by the designer. When defining a new domain the domain engineer must define a decision model and relate critics to specific decision types. Decision categories currently are not modeled in great detail, they are simply descriptive strings.

Applicability: Use this recipe when you are defining or extending a domain and you have a broad understanding of the decisions that must be made by designers in that domain.

Ingredients: A place to put code that will be executed before critics will be activated, a name for a domain-specific decision category. Since Argo uses only decision categories, instead of modeling specific decisions, the domain engineer need not know everything about the decisions in great detail.

Steps:

  1. Define a String constant with the name of the decision category. Make sure to follow Argo's naming conventions. The string constant can be placed in the domain constant file, or somewhere else where it is accessible to critics.
  2. Find a piece of code that will be run before critics are activated. For example, use the static initalizer of the DesignMaterial class that the relevant critics will operate on.
  3. Add a line to that code that calls Designer.defineDecision(). For example see jargo.softarch.C2Critic.
  4. Update your process model so that it has a node for the new decision category.

Results: A new decision category in the decision process model that can control critics to keep them timely.


How to define a critic

Background: Critics continuously evaluate the design to identify potential problems and opportunities for improvement. Critics can check correctness, completeness, consistency, and proper use of notation. They can also identify places in the design where good alternatives exist but have not been considered, or situations in which the knowledge of other people in the design comunity have be useful to the designer. When a critic's analysis predicate evaluates to true, it produces a piece of design feedback to be presented to the designer.

Applicability: Use this recipe when you want to add a critic.

Ingredients: A subclass of DesignMaterial, a analysis predicate written in terms of properties of DesignMaterials, a short piece of text describing the issue and possible soultions, the URL of background information relevant to the issue, the email address of a person who authored or will maintain the critic, knowledge of which design decision category this critic supports.

Steps:

Results: A functioning critic that is automatically loaded and applied to DesignMaterials as needed.


Argo Home Page | Available documentation