Read Me

ConcernTagger v2.0
==================

Overview
--------
ConcernTagger is an Eclipse plug-in for mapping requirements, features, etc. 
("concerns") to source code (types, methods, and fields) and for computing
metrics (degree of scattering, linked SLOCs, etc.) based on this mapping.

Package Contents
----------------

project/                        - Source code and Eclipse project for COncernTagger
workspace/                      - Eclipse workspace for ConcernTagger
docs/                           - Toad Data Model for ConcernTagger database
                                  schema (www.quest.com)
studies/                        - Sample project studies and their datasets
emma-2.0.5312/                  - Source code for customized version of the Emma
                                  Code Coverage Profiler

edu.columbia.concerntagger_<version>.jar - ConcernTagger Eclipse plugin
LICENSE.html                    - License file
README.txt                      - This file

Requirements
------------
- Eclipse 3.3M4
- Java6

ConcernTagger has only been tested with Eclipse 3.3M4 and Java6 and on Windows XP
and Linux.

Installation
------------
1. Install Eclipse into a directory (ECLIPSE_HOME):

http://download.eclipse.org/eclipse/downloads/drops/S-3.3M4-200612141445/index.php 

2. Unzip the ConcernTagger zip file into a different directory (INSTALLDIR) from
   Eclipse.

3. Copy <INSTALLDIR>/edu.columbia.concerntagger_<version>.jar to
   <ECLIPSE_HOME>/plugins. When you run Eclipse, you should see a new
   "Concerns" category in Window -> Show View -> Other...

Mapping Elements to Concerns
----------------------------
1. Open a "Concern View" window Window->Show View->Other...->Concerns->Concern View.
2. Create your concerns by right clicking in the window and selecting "New Concern..."
   or using the "New Concern" button.
3. Open any view that allows you to see Java program elements, for example, the
   Package Explorer, Editor, Search, Types, Packages, and Members views.
4. Link a type, method, or field (aka "component" or "element") to a concern
   in any of the following ways:

	-> Drag one or more elements and drop them onto a concern
	-> Right click one or more elements, select "Link", and select a concern
	-> Select one or more elements, select one or more concerns, right click the
	   concern selection, and select "Link"

5. Unlink an element in any of the following ways:

	-> Select one or more elements in the Concern View and press the DELETE key
	-> Select one or more elements in the Concern View, right click the
	   selection, and select "Remove"
	-> Select one or more elements, select one or more concerns, right click the
	   concern selection, and select "Unlink"
	-> Right click one or more elements, select "Unlink", and select a concern

Obtaining Metrics
-----------------
1. After you've finished mapping, open the "Concern Metrics" view
   from Window->Show View->Other...->Concerns->Concern Metrics

   You should see metrics like:

   Concern Name   DOSC   DOSM  CDC  CDO  SLOC
   ConcernA      0.543  0.632    1    3   179
   ConcernB      0.322  0.292    2    3   139
   ConcernC      0.543  0.464    1    3    67
   ConcernD      1.000  1.000    0    0     0

  The DOSC and DOSM are described in

  Marc Eaddy, Alfred Aho, and Gail C. Murphy, "Identifying, Assigning,
  and Quantifying Crosscutting Concerns," to appear in the ICSE Workshop
  on Assessment of Contemporary Modularization Techniques (ACoM 2007),
  Minneapolis, MN, May 22, 2007.
  http://www.cs.columbia.edu/~eaddy/publications/Identifying,%20Assigning,%20and%20Quantifying%20Crosscutting%20Concerns.pdf

  and

  Marc Eaddy, "Modeling, Measuring, and Modularizing Crosscutting Concerns,"
  Ph.D. Thesis Proposal, Dec 2006. http://www.cs.columbia.edu/~eaddy/thesis/proposal.

  CDC and CDO are described in:

  F. C. Filho, N. Cacho, E. Figueiredo, R. Maranhao, A. Garcia, and 
  C. M. F. Rubira, "Exceptions and Aspects: The Devil is in the Details,"
  Intl. Conf. on Foundations of Software Engineering, 2006.

Importing Data
--------------
You can import concerns and links using ARFF files.

[Details Needed]

Release Notes
=============

2.1
---
+ Now calculates tangling metrics (DOF)
+ Can now sort scattering and tangling metrics by column

2.0.1
-----
+ Changed (un)assign to (un)link
+ Now linking an anonymous class/method always links the enclosing method
+ FIX: Sometimes highlighting is incorrect
+ FIX: Moving a concern doesn't always refresh the concern tree

2.0 (JUly 25, 2007)
-------------------
+ Can now unlink elements by right-clicking them and selecting 'Unlink'
+ Can now link/unlink an element to multiple concerns
+ Can now remove all links for all the concerns in the concern domain
+ Added mnemonics for the "Link" and "Unlink" right-mouse menu items
+ Renamed "Add to Concern" to "Link"
+ Linked elements in Concern Tree are now highlighted when selected in
  Package Explorer, Editor, or other Java element viewer/editor
+ Displays different icons for the concern depending on if it has children
  and/or direct links
+ Can now save metrics from Metrics and Intersection Views
+ Can now intersect two concern domains (e.g., requirements and bugs)
+ Can now export concerns and links to ARFF file
+ FIX: Concern should only be highlighted if all selected elements are
  linked to it
+ FIX: Linking a concern using drag-n-drop or the "Link" right-mouse menu
  item no longer freezes the UI
+ FIX: Selecting multiple elements in Package Explorer or the Editor no longer
  freezes the UI
+ FIX: DnD is ignored if one of the selected elements is already linked
+ FIX: DnD doesn't work correctly when you drag a class from one concern to
  another
+ FIX: Right-click "Link" menu is empty for elements in Search Results
+ FIX: Fixed bugs when importing concerns and links

1.5.3
-----
+ Supports multiple concern domains
+ Supports hierarchical concerns
+ Supports multiple views of the same concern domain
+ Supports importing concerns and links stored in
  Attribute-Relation File Format (.arff) files
+ Can now remove concerns and links using the DELETE key
+ Highlighting in Project Explorer is now fast and flicker-free
+ Concerns in Concern Tree are now highlighted when components
  they are linked to are selected in Package Explorer
+ Improved error messages and user feedback
+ FIX: Fixed bug where we can get a ton of error messages
+ FIX: Fixed bug where dragging in the Concern Tree caused items to
  open too quickly, making it difficult to "stay on target"

1.5.2
-----
+ Added total and % mapped metrics
+ Metrics tool now outputs the total number of members, the total
  number of linked members, and the percentage of linked members
+ FIX: Fixed bugs where sometimes a newly added concern didn't appear in
  the Concern Tree or right-mouse menus

1.5.1
-----
+ Brand new code model. Now includes files.
+ Calculates SLOCC instead of LOCC
+ Can now tag inner classes and enums.  Inner classes are treated as
  individual classes and do not count towards the SLOC of the outer class.
+ Can now tag entire classes (i.e., at the class level in addition to
  method level)
+ Fixed metrics logic
+ Does not reset view to top when an element is dropped onto a concern
+ Projects are now imported (after prompting the user) when one of their
  elements is mapped

1.1
---
+ 'Link' right-mouse menu item only visible for types, fields and methods
+ Can now map static constructors
+ Can now view concern metrics as a view in Eclipse
+ Disabled all prompts related to saving/loading a concern file.
  Everything is automatically stored in the database now.
+ Removed "PersistToDB" and "Generate Code Model" buttons.  This
  is now done automatically.
+ No longer need to create the initial database tables.  They are
  created automatically as needed.
+ No longer requires sqltools.rc file
+ Unlinked concerns are ignored when calculating metrics
+ Fix bug related to sequence generation that caused a database error
+ Now prompts when user selects "Remove Concerns"

1.0
---
+ Stores concern list, code model, and mapping data in SQL database
+ Calculates scattering metrics and the concern diffusion metrics

FAQ
===
Q. When I right-click on an item in Package Explorer, why don't I see 
   the Link and Unlink menu items?
A. Make sure you right-click on a project that contains source code.

Known Issues
============
1. You can only map elements that conform to JDK 1.4 and below.
   ConcernTagger does not support generics.
2. We do not support making changes to the Java project after it has been
   imported.  If the name or signature of an element changes, the link will
   still be present but the icon will show a question mark indicating that
   the link is invalid.

   Workaround: Remove the old link and re-link the element.

3. SLOCs are calculated from start of method name, not start of identifier.
4. SLOCs incorrectly includes comment-only lines that appear within
   statements and expressions, e.g.,

	int i = 5 +
		// comment
		2;

5. Multi-item drag & drop doesn't work on Linux.

6. Importing static initializers no longer works (reported as Member Not Found)

WISH LIST
=========
o Support non-Java languages (C#, Ruby, C)
o Support view that combines links (e.g., alter AND remove predicates)
o Statement-level assignment

TODO
====

Editor/Explorer Right-Mouse Menus
---------------------------------
o Indicate concernComponentRelation being used for the link. It is too easy to
  create the wrong edge.
o Needs accelerator key
o Add to right-click Link/Unlink: "Unlink 4 Selected concerns"

Concern View
------------
o Disable default Concern Tree manipulations caused by DnD
o Add "-Active" suffix to currently active concern view
o Add "Make Read Only" to Concern View drop down menu
o Support filtering so that only linked concerns are shown
o Right-click a single concern: "Show in Package Manager"
o Right-click multiple concerns: "Move to concern..."
o Support Copy, Cut, and Paste
o Color "Foreign" concern dark grey
o Support dropping a member onto a class (not just a concern)
o Sort elements the same way Package Explorer does
o BUG: Parent icon is not updated after making it childless via DELing its
  children or by adding its first child via DnD
o BUG: Can't DnD class from one concern to another if the destination concern
  already has some links from the same class
o Menu item to show only assigned concerns

Concern Linking
------------------
o Color links to "Foreign" concern dark grey
o Character- and statement- level linking

Inconsistency Checks
--------------------
o For every unlinked element, if it has no subelements or if any subelement is not
  linked, report a warning: "Cannot infer concerns for parent because not all
  children are linked" OR "Element is not linked"
o Handle inconsistency when the same element is linked to a parent and child concern
o Linking a type should automatically link its subtypes (CAG4)
o Linking a method should automtaically link its overrides (CAG5)
o Linking a method should automatically link methods that call it (CAG3)
o Linking a field should automatically link methods that use it (CAG3)
o Warn if link for member user does not include member's link
o Warn if reference to a linked class doesn't include link
o Warn if a concern has no links
o warn if member link is not included in parent's link
o Disagreements with automated link
	o For each concern, show set of elements linked by both techniques
		- Element in manual but not automated -> False Negative (yellow)
		- Element in automated but not manual -> False Positive (grey value
                  based on number of tangled concerns)
		- Element in both (green)
o For every linked element, compare the concerns linked to the element with its
  subelements and report discrepancies: "Parent introduces concerns" OR "Parent
  ignores/suppresses some child concerns"
o Show concerns linked to dead code / unused elements

Concern Metrics
---------------
o Calculate DOF
	o Ignore "Foreign" concern when computing metrics
o Menu item to show only assigned leaf concerns

Misc
----
o HasLink shouldn't import model; ImportLinks should
o Only import projects on the build path
o Smarter project importing. Allow user to view imported projects and delete them.
o Custom source editor with character- and line-level highlighting
o SourceForge: CVS, bug tracking
o Concern call graph view

Credits
=======
Marc Eaddy	(eaddy@cs.columbia.edu)
Vibhav Garg	(vibhavgarg@gmail.com)

Acknowledgements
================
We thank Martin Robillard and Frédéric Weigand-Warr from McGill University
for developing the original Concern Mapper program, on which much of ConcernTagger's
source code is based (http://www.cs.mcgill.ca/~martin/cm/).