Deliverable 2 - Analysis report

jUCMNav – Eclipse Plugin

by

Olivier Clift-Noël
Jean-Philippe Daigle
Jason Kealey
Jordan McManus
Etienne Tremblay
--
Team SoftwareEngineering.Ca


Work presented to
Dr. Liam Peyton
for the
software engineering capstone project




University of Ottawa
February 18th, 2005


Table of Contents




Background

For our software engineering capstone project, we are developing jUCMNav, an Eclipse Plug-in to edit and to navigate Use Case Maps. The existing tool for manipulating this visual notation is not portable, is far form being user friendly, and has become unmaintainable. This document aims to define the project's requirements and features for jUCMNav. In order to refine these requirements, we have also produced the system's high level architecture, user scenarios, user interface mockups, file formats and defined the main algorithms.

Note that this document assumes basic knowledge of Eclipse terminology, and defining these words is outside the scope of our documentation effort. See http://www.eclipse.org for more information.

Requirements

Mandatory Requirements

We have agreed to fulfill these requirements during the course of our project:
Name Description Type Priority
ReqActionUndoOne jUCMNav SHALL allow the user to undo the latest transformation or action on the UCM model. Functional Urgent
ReqComp jUCMNav SHALL support the creation, deletion, naming, editing, resizing, and moving of UCM components. Functional Urgent
ReqCompCompBind jUCMNav SHALL support the (containment) binding of a component to another component. Functional Urgent
ReqCompCompUnbind jUCMNav SHALL support the unbinding of a component contained in (bound to) another component. Functional Urgent
ReqCompPathBind jUCMNav SHALL support the (containment) binding of a path element to a component. Functional Urgent
ReqCompPathUnbind jUCMNav SHALL support the unbinding of path elements contained in (bound to) a component. Functional Urgent
ReqConnections jUCMNav SHALL support connecting an end point to a start/wait/timer.
Functional Medium
ReqElemAndFork jUCMNav SHALL support the creation, naming, editing, and moving of UCM and forks. Functional Urgent
ReqElemAndJoin jUCMNav SHALL support the creation, naming, editing, and moving of UCM and joins. Functional Urgent
ReqElemDelete jUCMNav SHALL support the deletion of path elements. Functional Urgent
ReqElemDirectionArrow jUCMNav SHALL support the creation and moving of UCM direction arrows. Functional Medium
ReqElemDynamicStub jUCMNav SHALL support the creation, naming, editing, and moving of UCM dynamic stubs. Functional Medium
ReqElemEmptyPoint jUCMNav SHALL support the creation, naming, editing, and moving of UCM empty points. Functional Urgent
ReqElemEndPoint jUCMNav SHALL support the creation, editing, and moving of UCM end points. Functional Urgent
ReqElemOrFork jUCMNav SHALL support the creation, naming, editing, and moving of UCM or forks. Functional Urgent
ReqElemOrJoin jUCMNav SHALL support the creation, naming, editing, and moving of UCM OR joins. Functional Urgent
ReqElemResponsibility jUCMNav SHALL support the creation, naming, editing, and moving of UCM responsibilities. Functional Urgent
ReqElemStartPoint jUCMNav SHALL support the creation, naming, editing, and moving of UCM start points. Functional Urgent
ReqElemStartPointAttributes jUCMNav SHALL provide the following attributes for start points: name, workload Functional Urgent
ReqElemStaticStub jUCMNav SHALL support the creation, naming, editing, and moving of UCM static stubs. Functional Urgent
ReqElemStubActions jUCMNAV stubs SHALL allow the following actions: create plug-in, view plug-in, add plug-in, remove plug-in, rename plug-in, bind plug-in, properties. Functional Urgent
ReqElemTimer jUCMNav SHALL support the creation, naming, editing, and moving of UCM timers. Functional Medium
ReqElemWait jUCMNav SHALL support the creation, naming, editing, and moving of UCM wait items. Functional Medium
ReqExportBitmap jUCMNav SHALL support the export of a selection of maps (current, current and submaps, all maps) to individual bitmap files. Functional Medium
ReqHelpAbout jUCMNav SHALL have an About menu item that displays the tool version, contributors, acknowledgements, and copyright notices. Functional Medium
ReqHelpOnLine jUCMNav SHALL include a searchable on-line help on its functionalities. Functional Medium
ReqOpen jUCMNav SHALL support opening a document from its XMI serialization. Functional Medium
ReqSave jUCMNav SHALL support saving the document (in XMI) to a known filename. Functional Urgent
ReqSaveAs jUCMNav SHALL support saving the document (in XMI) to a file selected by the user. Functional Urgent
ReqSelectAll jUCMNav SHALL support the selection of all elements in the current UCM. Functional Medium
ReqSelectGroup jUCMNav SHALL support the selection of groups of elements, at least via multiple shift-clicks and via selection box dragging. Functional Medium
ReqSelectGroupDelete jUCMNav SHALL allow the user to delete the elements in a group of selected elements when all these elements are deletable. Functional Medium
ReqSelectGroupMove jUCMNav SHALL allow the user to move a group of selected items. Functional Medium
ReqSelectSingle jUCMNav SHALL support the single-click selection of a desired UCM component or path element. Functional Urgent
ReqSelectUnselectAll jUCMNav SHALL allow the user to unselect all selected elements. Functional Urgent
ReqSelectUnselectOne jUCMNav SHALL allow the user to unselect one element in a group selected elements. Functional Medium
ReqStaticSemanticCheck The system shall check, upon user’s request, all enabled static semantics checking rules on the URN model that is being opened in jUCMNav. Functional Medium
ReqStaticSemanticDisable The system shall allow users to disable static semantics checking rules. Functional Medium
ReqStaticSemanticEnable The system shall allow users to enable static semantics checking rules. Functional Urgent
ReqStaticSemanticModify The system should allow defined rules to be changed without the need to recompile jUCMNav Functional Medium
ReqStaticSemanticNew The system shall allow new rules to be added without the need to recompile jUCMNav Functional Medium
ReqStaticSemanticReport The system shall report rules violations to the user. Functional Medium
ReqStaticSemanticShareExport The system shall allow a user to save rules into a file. Functional Medium
ReqStaticSemanticShareImport The system shall allow a user to load rules saved in a file into the system. Functional Medium
ReqBrowseHistory jUCMNav SHALL support the browsing of the history of navigation (previous/next). GUI Medium
ReqBrowseModel jUCMNav SHALL support browsing and selecting the UCMs and their elements in a tree structure on a panel different from the main work area. GUI Urgent
ReqLabels jUCMNAV SHALL support labels anchored to elements and positioned via X-Y deltas. GUI Medium
ReqSelectFeedback jUCMNav SHALL provide visual feedback about selected model elements. GUI Urgent
ReqDocumentation jUCMNav code SHALL be accompanied with documentation on how to add new element/component types, menu items, functionalities, and tests. Non Functional Medium
ReqJavaVersion jUCMNav SHALL be executable on Java 1.5 Non Functional Urgent

The following requirements are also mandatory for jUCMNav but not within the scope of our project. It would be appreciated if we implemented these requirements but this could also be done in future projects (extending ours):
Name Description Type Priority
ReqCompType jUCMNav SHALL support different types, with different shapes (rectangle for team, parallelogram for process, rounded-corner rectangle for object, thick-line rectangle for agent, stickman for actor) Functional Low
ReqConnectionsAsync jUCMNav SHALL support connecting an empty point to a start/wait/timer.
Functional Low
ReqElemDynamicComponents jUCMNav SHALL support the dynamic components (slots). Functional Low
ReqExportEPS jUCMNav SHALL support the export of a selection of maps (current, current and submaps, all maps) to individual Encapsulated PostScript files. Functional Low
ReqMultiWindows jUCMNav SHALL support the editing of multiple UCM diagrams simultaneously. Functional Low
ReqPrintReport jUCMNav SHALL support the generation of printable reports that include the UCM diagrams and at least these options: UCM selection, date/time, and description of responsibilities, components, stubs, conditions, scenario definitions, and performance annotations. Functional Low
ReqSaveAuto jUCMNav SHALL provide an auto-save (to a different file with the same name but with a different extension) option with user-defined intervals. Functional Low
ReqSaveAutoRevert jUCMNav SHALL support the opening of the last auto-saved version of the document. Functional Low
ReqSaveBackup jUCMNav SHALL make a backup of the existing file before saving the latest version of the document. Functional Low
ReqSaveSchema jUCMNav SHALL support saving the document to a known filename valid according to the URN DTD. Functional Low
ReqAreaZoomScroll jUCMNav SHALL support the zooming the work area and scrolling. GUI Low
ReqCharConditions jUCMNav SHALL display conditions on branches between square brackets (e.g., [condition]). GUI Low
ReqCharStubInOut jUCMNav SHALL display the stub entry/exit segment labels (e.g., IN1, IN2, OUT1, OUT2) in gray, uppercase, and with a smaller font size. GUI Low

Optional Requirements

We have agreed to complete these requirements if time permits and they are relatively simple to implement, once our structure is in place.

Name Description Type Priority
ReqActionRedoMany jUCMNav SHOULD allow the user to redo many of the latest transformations or actions undone on the UCM model. Functional Low
ReqActionRedoOne jUCMNav SHOULD allow the user to redo the latest undone transformation or action on the UCM model. Functional Low
ReqActionUndoMany jUCMNav SHOULD allow the user to undo many of the latest transformations or actions on the UCM model. Functional Medium
ReqComments jUCMNav SHOULD allow the creation, resising, deletion, and display of user-defined comments anywhere on a diagram. Functional Low
ReqCompPools jUCMNav SHOULD support the creation, naming, editing, and moving of UCM pools. Functional Low
ReqCompUserTypes jUCMNav is INTENDED to suppor user-defined component types, with user-provided bitmaps. Functional Low
ReqElemAbort jUCMNav SHOULD support the creation, naming, editing, and moving of UCM aborts. Functional Low
ReqElemDynamicResponsibility jUCMNav SHOULD support the creation, naming, editing, and moving of UCM dynamic responsibilities. Functional Low
ReqElemEmptyResponsibility jUCMNav SHOULD support the creation, editing, and moving of UCM empty responsibilities. Functional Low
ReqElemFailurePoint jUCMNav SHOULD support the creation, naming, editing, and moving of UCM failure points. Functional Medium
ReqElemGoals jUCMNav SHOULD support the creation, naming, editing, and moving of UCM goals. Functional Low
ReqElemLoops jUCMNav SHOULD support the creation, naming, editing, and moving of UCM loops. Functional Low
ReqElemSharedResponsibilities jUCMNav SHOULD support the creation, naming, editing, and moving of UCM shared responsibilities. Functional Low
ReqElemSharedStubs jUCMNav SHOULD support the creation, naming, editing, and moving of UCM shared stubs. Functional Low
ReqElemStubOtherActions jUCMNAV stubs SHOULD allow the following actions: duplicate plug-in, import plug-in. Functional Medium
ReqElemTimestamp jUCMNav SHOULD support the creation, naming, editing, and moving of UCM timestamps. Functional Low
ReqExportMap jUCMNav SHOULD support the export of a selection of maps (current, current and submaps, all maps) to a file. Functional Low
ReqExportSVG jUCMNav SHOULD support the export of a selection of maps (current, current and submaps, all maps) to individual Scalable Vector Graphics files. Functional Low
ReqModelHyperlink jUCMNav SHOULD allow the user to anotate any model element with a hyperlink (Unified Resource Locator) and to visit this URL. Functional Medium
ReqModelMerge jUCMNav is INTENDED to support the merging of two UCM models. Functional Low
ReqModelSearch jUCMNav SHOULD support user-defined searches for elements in a UCM model. Functional Low
ReqModeMoveAll jUCMNav SHOULD offer a default mode where modifying sizes and positions of all elements is allowed. Functional Low
ReqModeMoveNothing jUCMNav SHOULD offer a mode where modifying sizes and positions of all elements is prevented. Functional Low
ReqModeMovePaths jUCMNav SHOULD offer a mode where modifying sizes and positions of components only is prevented. Functional Low
ReqOpenOldDTD jUCMNav SHOULD support the opening or import of .ucm files compliant to the UCM DTD 0.23. Functional Medium
ReqPrintDiagram jUCMNav SHALL support the printing of a diagram or a selection of diagrams. Functional Medium
ReqPrintPreview jUCMNAv SHOULD support the preview of the document on screen for user confirmation. Functional Low
ReqPrintProperties jUCMNav SHOULD support user-defined page properties for printing documents. Functional Low
ReqSelectGroupAlign jUCMNav SHOULD allow the user to align the elements in a group of selected items: top, center vertically, bottom, left, center horizontally, or right. Functional Medium
ReqSelectGroupDistr jUCMNav SHOULD allow the user to distribute the elements in a group of selected items: vertically or horizontally. Functional Medium
ReqCharBoundStartEnd jUCMNav SHOULD display between accolades the parent stub's IN/OUT labels bound to the start/end points, when the map is a plug-in (e.g., thestart{IN1}, theend{OUT3}). GUI Low
ReqCharMultiLingual jUCMNav SHOULD support a multi-lingual character code for capturing labels and descriptions. GUI Low
ReqCharSignatures jUCMNav is INTENDED to display the type signatures of start and end points between parenthesis. GUI Low
ReqCompColor jUCMNav SHOULD support line and fill colors for components. GUI Low
ReqHelpContextual jUCMNav SHOULD provide contextual help for its GUI components. GUI Low
ReqHelpToolTips jUCMNav SHOULD provide tool tips for all the GUI buttons and panels. GUI Medium
ReqOpenPrevious jUCMNav SHOULD allow the user to open recently accessed files (e.g. any of the last four) via the menu. GUI Low
ReqViewFullScreen jUCMNav SHOULD allow the user to navigate a UCM model in full screen mode (can be within a window with menu). GUI Low
ReqDisplayAbstractAPI jUCMNav SHOULD offer an abstract API or layer to support the display and export (e.g., to EPS) UCM diagrams. Non Functional Medium

Goals

We will take into consideration the following requirements and goals into consideration while designing the system, as they might impact some of our decisions. However, our efforts in this direction will not be evaluated.
Name Description Type Priority
ReqGoalAttributes jUCMNav is INTENDED to provide access to as many attributes from the metamodel as possible. Goal Medium
ReqGoalAutoLayout jUCMNav is INTENDED to support the automatic layout of UCM diagrams. Goal Low
ReqGoalBrowsing jUCMNav is INTENDED to support navigation of UCM model in a Web-browser-like way. Goal Urgent
ReqGoalCommandLine jUCMNAv is INTENDED to support a command line interface. Goal Low
ReqGoalCompositeScenarios jUCMNav is INTENDED to allow scenarios to be defined based on existing scenario definitions. Goal Low
ReqGoalGrlSupport jUCMNav INTENDS to support the complete User Requirements Notation, including GRL Goal Low
ReqGoalGuiStandards jUCMNav is INTENDED to comply to the Eclipse GUI standards as much as possible. Goal Low
ReqGoalMultiLanguage jUCMNav is INTENDED to support multiple languages for the GUI, including English and French. Goal Low
ReqGoalOpenAPI jUCMNav is INTENDED to be an open an extensible tool, which can be achieved via an open API. Goal Low
ReqGoalScripting jUCMNav INTENDS to support a scripting language enabling all the functionalities available via the GUI Goal Low
ReqGoalShortcuts jUCMNav is INTENDED to provide keyboard access to its functionalities and menus. Goal Low
ReqGoalTraversal jUCMNav INTENDS to support model traversal based on scenario definitions. Goal Low
ReqGoalWellFormedUCM jUCMNav is INTENDED to ensure that only well-formed UCMs will be constructed. Goal Low
ReqModelCompare jUCMNav is INTENDED to enable the comparison between two use case map models (including two versions of the same model) and emphasize the differences. Goal Low

Example Data and Scenarios

Throughout this report, you will see examples referring to The Pizza UCM. As we are building the new version of an existing tool, we are fortunate to have access to a library of existing Use Case Map models. The ideas embodied in them and their representation within the current tool will serve as a proving ground for our implementation.

This UCM, describing pizza ordering and preparation, is to be used as a concrete example for proof of concept screenshots and sample designs. Specifically, the contents of the pizza UCM will be used to explain the different views offered by our application, illustrate the use of an editor window, and explain file formats.

The Pizza UCM:
The Pizza UCM

Use Case Model or Functional Features of System

Common Information

As a single-user graph editing application, our use cases need only consider a single actor: an end user editing UCMs.

The astute reader will notice not all requirements are addressed by this collection of use cases - indeed, only high and medium priority requirements marked as MANDATORY are considered, as most OPTIONAL and FUTURE requirements are likely to only be relevant in future versions. Still, some of these have been included where clearly appropriate. Additionally, to prevent explosion of complexity, only main use cases defining core functionality are included in the current section.

jucmnav_UseCases_v3.png

Definition of common use cases

(Note that * will be used to indicate OPTIONAL or FUTURE requirements)

Open UCM File

Addressing: ReqOpen, ReqOpenOldDTD*

Preconditions:
  • A project is open in the Package Explorer, and it contains at least one UCM diagram. No UCMs are currently loaded in editors.
  • The UCM Eclipse perspective is loaded.

Steps:
  • User double-clicks on UCMFILENAME.UCM in the Package Explorer
  • System opens the UCM in a new tabbed editor, focusing on the first tab (first diagram) in the file.

Notes:
  • May offer the chance to switch to the UCM perspective if it is not already opened.


Save UCM File

Addressing: ReqSave, ReqSaveAs, ReqSaveSchema

Preconditions:
  • A UCM file is open in an editor and its model contains unsaved changes.
  • The UCM's editor is the currently active editor.

Steps:
  • User clicks the save button in the main Eclipse workbench toolbar.
  • System saves the UCM to disk and grays out the save button.

Notes:
  • Keyboard accelerators for this action are provided. (CTRL+S)


Export as graphics

Addressing: ReqExportBitmap, ReqExportSVG*, ReqExportEPS*

Preconditions:
  • A project is open in the Package Explorer, and it contains at least one UCM diagram.
  • File is either closed or open with no unsaved changes.

Steps:
  • User pulls up the context menu for a UCM diagram in the project.
  • User selects Export.
  • jUCMNav presents a menu of export destinations.
  • User selects UCM Graphic Export.
  • jUCMNav presents a wizard for exporting as a vector or raster graphics format.
  • User selects appropriate options and clicks Finish.
  • jUCMNav saves the UCM's diagram(s) as graphics file(s).

Notes:
  • Export action also available from the Workbench's File menu, and then applies to currently active UCM.


Create UCM File

Addressing:

Preconditions:
  • A project is open in the Package Explorer.

Steps:
  • User pulls up the context menu for the project in the Package Explorer.
  • User selects New > Use Case Map
  • jUCMNav shows a wizard page asking for the diagram's name, description and location.
  • User inputs UCM name and clicks Finish.
  • jUCMNav creates a blank UCM file in the project, and opens it a new editor pane.

Notes:
  • Action also available from the Workbench's File menu.


Modify UCM File

The following use cases all involve modification of an existing diagram in a UCM file.

Common preconditions:
  • A project is open, active and contains at least one UCM file.
  • UCM file is open in the current editor, with one diagram focused.

Select / Deselect element

Applies to all UCM elements, defined here to prevent duplication.

Addressing: ReqSelectAll, ReqSelectGroup, ReqSelectGroupDelete, ReqSelectGroupMove, ReqSelectSingle, ReqSelectUnselectAll, ReqSelectUnselectOne

Selection steps:
  • User clicks on an element in the currently active editor tab.
  • System selects element and changes its color to indicate selected state.

Multi-Selection steps:
  • User ctrl+clicks on an unselected element in the currently active editor tab.
  • System adds element to current selection and changes its color to indicate selected state.

Deselection steps:
  • User clicks anywhere on the edit area background.
  • System deselects all selected elements.

Notes:
  • Additional ways of achieving element selection: click an element in the UCM's outline view.
  • Additional ways of achieving deselection: "Unselect all" action.
  • Additional ways of achieving deselection of a single element in a group: ctrl+click that element again.
  • Additional ways of achieving multiple selection: Drawing a selection box around elements.
  • Additional ways of achieving multiple selection: "Select all" action.


Create and Edit Elements

Addressing: ReqElem(.*)

Create and Edit Paths
Encompassing:
  • Create / edit a path

Creation steps:
  • User selects path node creation tool.
  • User clicks in drawing area.
  • jUCMNav creates a start point where the user clicked.
  • The user moves his cursor to somewhere else, seeing a line connecting his cursor with the previous point.
  • The user clicks
  • jUCMNav adds an empty point where the user last clicked.
  • The process is repeated until the user right clicks or presses escape.
  • jUCMNav replaces the last empty point with an end point.

Edition steps:
  • The user clicks on node, holds the mouse button down and moves it elsewhere on the map.


Create and Edit Path Elements
Encompassing:
  • Create and Edit responsibility
  • Create and Edit timer
  • Create and Edit wait
  • Create and Edit static stub
  • Create and Edit dynamic stub
  • Create and Edit abort
  • Create and Edit and fork
  • Create and Edit or fork
  • Create and Edit and join
  • Create and Edit or join
  • Create and Edit failure point
  • Create and Edit timestamp

Creation Steps:
  • User selects and right-clicks on a single empty point and selects the 'add $ELEM' action, where $ELEM is the responsibility, static stub, dynamic stub, etc. to be added.
  • jUCMNav creates a new instance of that element at the pointer position.
  • When added, some path elements must be linked to multiple paths. If this is the case with $ELEM, a short path is created in order to ensure the validity of the use case map.

Editing Steps (changing a property):
  • User selects an element.
  • User edits a property in the element's property page.
  • jUCMNav applies the new property value to the element's display in the editor.

Editing Steps (moving an element):
  • User selects an element.
  • User drags the element to a new position.
  • jUCMNav updates the display to show the element at the drop position.


Create and Edit Components
Encompassing:
  • Create and Edit component
  • Create and Edit process, team and others (out of scope)

Creation Steps:
  • User drags an element from the toolbox to the editor area.
  • jUCMNav creates a new instance of that element at the drop position.

Editing Steps (changing a property):
  • User selects an element.
  • User edits a property in the element's property page.
  • jUCMNav applies the new property value to the element's display in the editor.

Editing Steps (moving an element):
  • User selects an element.
  • User drags the element to a new position.
  • jUCMNav updates the display to show the element at the drop position.


Delete Element

Addressing: ReqSelectGroupDelete, ReqElem(.*)

Steps:
  • User selects element to delete (see 'Select / Deselect element' use case).
  • User presses DELETE key.
  • System deletes element from the model and removes it from the view.

Notes:
  • Additional way of achieving element deletion: "Delete" action in element contextual menu.

Testing these features

To prevent introduction of errors during development of future iterations, we will establish a set of automated tests relying on testing repeatability of sending known sets of commands on a UCM model, and checking the resulting model against expected values. This sample map (or maps) and scenarios for testing have yet to be defined (details will be available in the timeframe of M3 & QA reports), but will consist in the simplest UCM showing off all implemented features of the editor.

Not everything can be automated away however, and some amount of human-computer interaction will be necessary to test that the interface indeed behaves as required. This will be facilitated by the current availability of the old UCMNav application, which provides a base model for allowable operations and what must be supported to build Use Case Maps.

Non-Functional Features

Usability

The software must be usable by experienced software developers. Therefore, we're not looking for extreme simplicity by the means of dozens of wizards. We're looking for a uniform way of manipulating the Use Case Map metamodel that follows the Eclipse user interface guidelines. We must make the tool as usable as possible without sacrificing efficiency. We will be carefully planning and reviewing the sequence of actions that the user must perform in order to get his job done. As a team who had no experience with the old tool nor the Use Case Map notation, we will share the perspective of novice users. DanielAmyot will ensure that our tool respects the efficiency requirements.

Maintainability

Our application must be easily extensible and maintainable. In order to achieve this goal, we will follow the architecture enforced by Eclipse, GEF and EMF. Our documentation of the high level architecture of the system will help new developers quickly target what portions of the code they need to update. Hence, the Eclipse plugin and extension point architecture will speed up future development but there is still a price to pay. Developers who are not familiar with Eclipse (like us at the start of this project) will have to surmount the steep Eclipse learning curve before being able to contribute efficiently to the application. We will also use coding and commenting standards to help share our knowledge to future developers and to speed up their learning process. Code reviews will help ensure we have followed our standards and will help increase code clarity.

Documentation

We must document how we extend our system so that future developers can repeat the same process. Specific operations will be listed for common tasks such as adding new path elements.

High Level Architecture

The choice of Eclipse as our development platform will play a big role in laying out the architecture. The main architectural decision is to use the Graphical Editing Framework (GEF) and the Eclipse Modeling Framework (EMF). Here we can see a deployment diagram of all the components that will guide our architectural choices:

modelDiagram.png
Figure 1: Deployment diagram

This view of our application is a very high level one but it gives a very clear picture of the project.

We have agreed with our client that we will be designing and implementing a graphical editor for the UCM (Use Case Maps) notation. Most of the design and implementation will focus on the MVC (Model-View-Controller) pattern so the core decisions will be based on this pattern. The GEF and EMF frameworks are built using several other useful patterns such as factory, proxy, iterator, chain of responsibility, and command that will also guide us. Furthermore, our client has specified a list of goals that probably will not manifest themselves in the implementation, but might affect architectural decisions.

It is not quite clear yet what meta-model we will be working with. Our client has a great deal of experience with the UCM notation and will be actively involved in the model design (that is, if he does not design the whole meta-model himself, based on previous drafts). In the mean time, we have drafted a class diagram describing a simplified meta-model:

Figure 2: Model Diagram

Discussion on the meta-model

Since we’re using EMF for the code generation of the meta-model, all the code is automatically generated to allow the MVC controllers to listen for model changes. This makes our job a lot easier with respect to managing notifications between the objects. EMF generates default notification types that can be interpreted by our controller to change the view to represent the new model changes.

GEF provides some guidelines about the model that we should respect:

  • The model stores all data that may be edited or viewed by the user. This means that we have to store even data about the visualisation of the model too. For example bounds or coordinates of a figure. We are still trying to figure out if we want to put all this in the same model or separate the view model and the real business model in our model representation.
  • Provide ways of persisting the model. We have to make sure that when the editor is closed by the user, our model can be saved and reopened to restore the model afterwards.
  • The model must remain ignorant of the view or the controller. So the model can never store reference to edit parts, editor etc. Such reference would ruin the MVC pattern and could potentially break the editor as well, because of inactive figures.
  • Provide a way for others to listen to changes in your model. This is done with the EMF model in our case. All the EMF generated classes implements the Notifier interface that can notify listener of a model change.

Discussion of the controllers

Each part of the model that has a visual representation in our editor should have a controller that listens to model changes and to visual representation changes (to update the model). Controllers in GEF are called EditParts. EditParts are associated with a model element and listen to all the changes from this part of the model. The EditPart does not really know how to change the model; it delegates this task to edit policies. EditParts receive requests. For example, the user wants to create a new object in the editor. A high level "create request" is sent to the parent EditPart of the editor. The EditPart also does not know how to handle this so it delegates it to the appropriate registered edit policy that knows how to handle such requests. The edit policy is then asked to generate a command which is able to perform the required request. In this particular case, a create command. Commands are stacked when executed so the undo/redo mechanism is already in place for us. All we have to do is ensure that all model changes reside a Command class and create the commands with edit policies. Each command should keep some information for undoing the change made on the model. Commands should not know the existence of EditParts and editors. Commands only know about the model and how to change it to meet some criteria.

The beauty of a model view controller pattern is that all the changes made on the model are reflected automatically on all the editors viewing this particular model. This way we can have multiple pages opened on the same model but all pages will stay synchronized with the model because of our application of the pattern. There is only one command stack for a particular input, so this implies that even if we change the model in a particular page and we go in another page and press undo, the model will be changed back to the right state.

Discussion of the view

The best way to explain the view is with an interaction diagram describing exactly what is happening behind the scenes when the user interacts with the jUCMNav. For the purpose of an example, we will observe what is happening with GEF when the user wants to move a UCM responsibility element in the editor (the view).

This is a really high level description of what is really happening internally when the user drags a figure around in the editor.

In this example, the user tries to move a responsibility in the editor. First of all, the editor notifies the responsibility’s EditPart that the responsibility moved in the view. The EditPart then delegates this request to the right edit policy. An edit policy is the entity that knows how to handle a certain type of request. In this case, this is a move request. So the layout edit policy generates a move command. As explained before, commands in GEF are the only object that can really modify the model, that way the user can undo/redo his actions. Then, the move command modifies the x and y variables of the responsibility instance. Since the responsibility’s EditPart is registered on this instance as an observer, the EditPart is notified right away of the change made in the model. So now the EditPart knows that it has to refresh the visuals in the view (the editor) because the model changed. So it only updates the view parts that really need to be updated; like the links between this responsibility and other nodes in the UCM graph.

User Interface Mockup

1. Views

1.1 Navigator

view_navigator_mockup.png
Above: Concept sketch.

Description
The Navigator view displays .ucm files included in the current project. Under each of those files, it lists the diagrams they contain, ordered alphabetically by name. It does not display sub-elements of a diagram such as stubs, a responsibility left to the Outline view.

Behaviour
On load: If a project is already open and active, this view displays the current project's structure and highlights the currently focused UCM diagram, from the topmost editor window (if applicable). (Eclipse UI Guideline 7.8)

Double-click: Double-clicking a UCM file or a diagram contained therein, opens that diagram for editing. If a UCM file is opened, the editor defaults to the topmost level of the first diagram. For a diagram, the topmost level of that diagram is shown.

Subitems' context menu: A context menu can be invoked by right-clicking on the project folder, on a UCM file, or on a UCM diagram. Note that several of the usual items found in Eclipse context menus for package explorer / navigator items either do not apply or are not targeted for implementation in our project's timeframe. Future versions will expand on this.
Project folder, UCM File, UCM Diagram context menu items (relevant extensions): Open, Delete, Import, Export

1.2 Outline

view_outline_mockup.png   jucmnav_outlineview_demo.png
Above: Concept with example data (Left) and Hello World implementation (Right).

Description
Contains a tree-view style list of all components of a diagram, using icons representative of the component type. Stubs are expandable into another level of the tree view. Icons are similar to those used in the toolbox. Components can be grouped by type or listed alphabetically.

Behaviour
On load: Upon opening this view, it derives its contents from the component contents of the top-most or active diagram being edited. (Eclipse UI Guideline 7.8)

Click: Clicking a node in the tree will focus that component and select it in the editor. Selecting multiple nodes will select the corresponding components in the editor.

Response: View responds to selection of a component in the editor by highlighting that component. Does the same for multiple selections.

Subitems' context menu: Show, Delete

1.3 Responsibilities

view_responsibilites_mockup1.png   view_responsibilities_demo.png
Concept (left) and Hello World implementation (right).

Description
Contains a list of all Responsibilities in a diagram, along with their textual description.

Behaviour
On load: Upon opening this view, it derives its contents from the component contents of the top-most or active diagram being edited. (Eclipse UI Guideline 7.8) The diagram's model is queried and the Responsibilities are enumerated.

Click: Clicking a Responsibility will focus that Responsibility and select it in the editor. No multiple selections are permitted.

Response: View responds to selection of a component in the editor by highlighting that component.

Subitems' context menu: None targeted for this release.

1.4 Properties

view_properties_mockup.png   view_properties_demo.png
Concept (left) and Hello World implementation (right).

Description
Contains a list of all Properties for the selected object in a diagram, along with their actual value.

Behaviour
On load: Upon opening this view, it derives its contents from the selected object in the diagram. The object is queried and the properties are enumerated along with their actual values.

Click: Clicking a property will focus the value of the selected property. No multiple selections are permitted. Once the value is focused, the user will be able to edit that value. The editor used to edit a property is determined by the nature of that property. If a value is changed, the change is reflected into the editor.

Typing: Typing will edit the selected value if it can be edited that way. If a value is changed, the change is reflected into the editor and other views.

Response: View responds to selection of a component in the editor.

Subitems' context menu: None targeted for this release.

1.5 Description Panel

view_description_mockup.png   view_description_demo.png
Concept (left) and Hello World implementation (right).

Description
Contains the description of the selected item in the editor.

Behaviour
On load: Upon opening this view, it derives its contents from the selected item of the top-most or active diagram being edited. The item is queried and the description is retrieved.

Click: Clicking in this view will place the cursor in the text box.

Typing: Typing in this view will edit the description.

Response: View responds to selection of an item in the editor by retrieving the description of the newly selected item.

Subitems' context menu: Basic text editing commands (Undo, Cut, Copy, Paste, Delete, Select All).

1.6 Palette

view_palette_mockup.png   view_palette_demo.png
Concept (left) and Hello World implementation (right).

Description
Contains all the element the user can insert in a UCM model.

Behaviour
On load: Upon opening this view, it will display all the items a user can insert in a UCM diagram. If there is no UCM model open, the content of this view is not populated.

Click: Clicking in this view will select the item the user wants to insert. Clicking in a UCM diagram will perform the selected action from the palette.

Response: View responds to selection of an item by changing the appearance of the selected item.

Subitems' context menu: None targeted for this release.

2. Editor

The actual editor window will simply be a tabbed blank canvas on which the Use Case Map is drawn and manipulated.

File Formats

As our tool will be used to modify files that contain multiple Use Case Map diagrams, we obviously need to discuss the persistence format. During the early phases of development, we will be storing our files in XMI (XML Metadata Interchange) format. Version 2.0 of this standard, defined by the Object Management Group, is implemented by EMF, the model framework that we will be using. Therefore, our first format for object persistence will be in XMI 2.0.

In the future, our model will be persisted using XML, following the URN 1.0 DTD and files saved according to the UCM 0.23 DTD should be readable as well. However, as these are optional for our project, we will not provide the details of these formats.

This is what our pizza mockup current looks like in XMI:
<?xml version="1.0" encoding="ASCII"?>
<network:Network xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:network="http:///network.ecore">
  <Nodes xsi:type="network:Component" x="76" y="148" width="128" height="316"/>
  <Nodes xsi:type="network:Component" x="274" y="41" width="491" height="142"/>
  <Nodes xsi:type="network:Component" x="278" y="215" width="486" height="319"/>
  <Nodes xsi:type="network:Component" x="276" y="567" width="491" height="123"/>
  <Nodes xsi:type="network:StartPoint" x="115" y="193" downstreamLinks="//@Links.0"/>
  <Nodes xsi:type="network:EndPoint" x="126" y="282" upstreamLinks="//@Links.16"/>
  <Nodes xsi:type="network:EndPoint" x="128" y="381" upstreamLinks="//@Links.18"/>
  <Nodes xsi:type="network:EndPoint" x="134" y="429" upstreamLinks="//@Links.32"/>
  <Nodes xsi:type="network:Responsibility" x="346" y="261" upstreamLinks="//@Links.1" downstreamLinks="//@Links.2"/>
  <Nodes xsi:type="network:Responsibility" x="408" y="247" upstreamLinks="//@Links.3" downstreamLinks="//@Links.4"/>
  <Nodes xsi:type="network:Component" x="303" y="242" width="428" height="167"/>
  <Nodes xsi:type="network:Component" x="308" y="425" width="425" height="80"/>
  <Nodes xsi:type="network:Responsibility" x="399" y="318" upstreamLinks="//@Links.14" downstreamLinks="//@Links.15"/>
  <Nodes xsi:type="network:Responsibility" x="450" y="363" upstreamLinks="//@Links.13" downstreamLinks="//@Links.17"/>
  <Nodes xsi:type="network:Responsibility" x="599" y="366" upstreamLinks="//@Links.20" downstreamLinks="//@Links.21"/>
  <Nodes xsi:type="network:Responsibility" x="396" y="143" upstreamLinks="//@Links.5" downstreamLinks="//@Links.6"/>
  <Nodes xsi:type="network:Responsibility" x="603" y="149" upstreamLinks="//@Links.9" downstreamLinks="//@Links.10"/>
  <Nodes xsi:type="network:Responsibility" x="367" y="599" upstreamLinks="//@Links.26" downstreamLinks="//@Links.27"/>
  <Nodes xsi:type="network:EndPoint" x="390" y="382" width="-1" height="-1" upstreamLinks="//@Links.29"/>
  <Nodes xsi:type="network:Responsibility" x="567" y="596" upstreamLinks="//@Links.23" downstreamLinks="//@Links.24"/>
  <Nodes xsi:type="network:Node" x="215" y="239" id="0" upstreamLinks="//@Links.0" downstreamLinks="//@Links.1"/>
  <Nodes xsi:type="network:Node" x="221" y="317" id="1" upstreamLinks="//@Links.15" downstreamLinks="//@Links.16"/>
  <Nodes xsi:type="network:Node" x="222" y="370" width="-1" height="-1" id="2" upstreamLinks="//@Links.17"
         downstreamLinks="//@Links.18"/>
  <Nodes xsi:type="network:Node" x="250" y="428" id="3" upstreamLinks="//@Links.28" downstreamLinks="//@Links.29"/>
  <Nodes xsi:type="network:Node" x="224" y="559" width="-1" height="-1" id="4" upstreamLinks="//@Links.27" 
         downstreamLinks="//@Links.28"/>
  <Nodes xsi:type="network:Node" x="168" y="602" id="5" upstreamLinks="//@Links.31" downstreamLinks="//@Links.32"/>
  <Nodes xsi:type="network:Node" x="445" y="640" id="6" upstreamLinks="//@Links.30" downstreamLinks="//@Links.31"/>
  <Nodes xsi:type="network:Node" x="466" y="614" id="7" upstreamLinks="//@Links.25" downstreamLinks="//@Links.26"/>
  <Nodes xsi:type="network:Node" x="521" y="631" id="8" upstreamLinks="//@Links.24"
         downstreamLinks="//@Links.25 //@Links.30"/>
  <Nodes xsi:type="network:Node" x="474" y="486" id="9" upstreamLinks="//@Links.22" downstreamLinks="//@Links.23"/>
  <Nodes xsi:type="network:Node" x="616" y="438" id="10" upstreamLinks="//@Links.21" downstreamLinks="//@Links.22"/>
  <Nodes xsi:type="network:Node" x="543" y="331" id="11" upstreamLinks="//@Links.12" downstreamLinks="//@Links.13"/>
  <Nodes xsi:type="network:Node" x="606" y="332" id="12" upstreamLinks="//@Links.19" downstreamLinks="//@Links.20"/>
  <Nodes xsi:type="network:Node" x="500" y="289" id="13" upstreamLinks="//@Links.11" downstreamLinks="//@Links.14"/>
  <Nodes xsi:type="network:Node" x="384" y="267" id="14" upstreamLinks="//@Links.2" downstreamLinks="//@Links.3"/>
  <Nodes xsi:type="network:Node" x="419" y="225" id="15" upstreamLinks="//@Links.4" downstreamLinks="//@Links.5"/>
  <Nodes xsi:type="network:Node" x="426" y="119" id="16" upstreamLinks="//@Links.6" 
         downstreamLinks="//@Links.7 //@Links.8"/>
  <Nodes xsi:type="network:Node" x="539" y="102" id="17" upstreamLinks="//@Links.8" downstreamLinks="//@Links.9"/>
  <Nodes xsi:type="network:Node" x="505" y="166" id="18" upstreamLinks="//@Links.7" downstreamLinks="//@Links.11"/>
  <Nodes xsi:type="network:Node" x="613" y="227" id="19" upstreamLinks="//@Links.10"    
         downstreamLinks="//@Links.12 //@Links.19"/>
  <Links source="//@Nodes.4" target="//@Nodes.20"/>
  <Links source="//@Nodes.20" target="//@Nodes.8"/>
  <Links source="//@Nodes.8" target="//@Nodes.34"/>
  <Links source="//@Nodes.34" target="//@Nodes.9"/>
  <Links source="//@Nodes.9" target="//@Nodes.35"/>
  <Links source="//@Nodes.35" target="//@Nodes.15"/>
  <Links source="//@Nodes.15" target="//@Nodes.36"/>
  <Links source="//@Nodes.36" target="//@Nodes.38"/>
  <Links source="//@Nodes.36" target="//@Nodes.37"/>
  <Links source="//@Nodes.37" target="//@Nodes.16"/>
  <Links source="//@Nodes.16" target="//@Nodes.39"/>
  <Links source="//@Nodes.38" target="//@Nodes.33"/>
  <Links source="//@Nodes.39" target="//@Nodes.31"/>
  <Links source="//@Nodes.31" target="//@Nodes.13"/>
  <Links source="//@Nodes.33" target="//@Nodes.12"/>
  <Links source="//@Nodes.12" target="//@Nodes.21"/>
  <Links source="//@Nodes.21" target="//@Nodes.5"/>
  <Links source="//@Nodes.13" target="//@Nodes.22"/>
  <Links source="//@Nodes.22" target="//@Nodes.6"/>
  <Links source="//@Nodes.39" target="//@Nodes.32"/>
  <Links source="//@Nodes.32" target="//@Nodes.14"/>
  <Links source="//@Nodes.14" target="//@Nodes.30"/>
  <Links source="//@Nodes.30" target="//@Nodes.29"/>
  <Links source="//@Nodes.29" target="//@Nodes.19"/>
  <Links source="//@Nodes.19" target="//@Nodes.28"/>
  <Links source="//@Nodes.28" target="//@Nodes.27"/>
  <Links source="//@Nodes.27" target="//@Nodes.17"/>
  <Links source="//@Nodes.17" target="//@Nodes.24"/>
  <Links source="//@Nodes.24" target="//@Nodes.23"/>
  <Links source="//@Nodes.23" target="//@Nodes.18"/>
  <Links source="//@Nodes.28" target="//@Nodes.26"/>
  <Links source="//@Nodes.26" target="//@Nodes.25"/>
  <Links source="//@Nodes.25" target="//@Nodes.7"/>
</network:Network>

Algorithms

Many requirements can be easily handled by the frameworks we are using (GEF and EMF). When reading the description of a requirement, it may seem like it would require an implementation of an algorithm, but in fact all we need to do is extend a few classes in the framework. For example, all the GUI work is handled by the GEF framework.

There are also many small algorithms that we will not describe here. For example, since GEF uses the Command pattern to provide undo/redo capabilities, we will need to implement execute(), undo() and redo() methods for each of these commands. These methods are essentially implementations of algorithms, but the descriptions of these algorithms follow naturally from the description of their requirements.

ReqGoalWellFormedUCM : jUCMNav is INTENDED to ensure that only well-formed UCMs will be constructed.

This does not need an implementation of an algorithm because of the way jUCMNav will be built. The user will never be allowed to construct an ill-formed UCM. If a new element must be on a path and it is not positioned on one, we'll create the shortest path possible to accommodate this new element.

Many requirements discuss opening, saving or exporting the model in XMI, XML following a DTD, BMP, JPEG, SVG, and even EPS. These requirements imply many complex algorithms. However, the scope of our project is limited to the formats for which the algorithms are already implemented for us: XMI, BMP, JPEG. Hopefully, we will have time to tackle the other formats but a discussion of their algorithms is too premature for the moment.

In conclusion, our system is not algorithm based. Because we are developing extensions and not complex algorithms, we have the opportunity to setup a truly iterative development process.
Topic attachments
I Attachment Action Size Date Who Comment
Network.emxemx Network.emx manage 43 K 17 Feb 2005 - 10:16 EtienneTremblay  
seg.jUcmnav.emxemx seg.jUcmnav.emx manage 115 K 17 Feb 2005 - 10:23 EtienneTremblay  
seg.network_1.0.0.zipzip seg.network_1.0.0.zip manage 341 K 17 Feb 2005 - 18:31 EtienneTremblay Plugin .zip -- Extract this in your eclipse plugin directory to test our Hello World.
Topic revision: r29 - 24 Aug 2005, JasonKealey
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback