Step-by-step tutorial on applying Featureous to the AnagramGame example application

  1. Create the AnagramGame example project.
  2. Go to the project's properties and set the source/binary format in "Sources" to JDK 5, so that we can use annotations.
  3. Select the project in project explorer and press "Trace Project" button in the main toolbar of the IDE.
  4. A screen will appear saying that "aop.xml" file was created for you in META-INF directory.
  5. Click OK, find the file in the explorer and open it.
  6. Substitute the 3 occurrences of the string "" with the outermost package of the AnagramGame, i.e. with "com.toy.anagrams". This tells the runtime tracer what classes to trace at runtime.
  7. Save and close the "aop.xml".
  8. In order to be able to annotate feature-entry-point methods in source code you need to use a JAR library that defines the annotation you will use. This library was created for you in the "lib" folder of the AnagramGame project, when you have pressed the "Trace Project" button.
  9. Go to AnagramGame project's properties and add the "ft.jar" file from the "lib" directory as a library.
  10. Now you can use the "dk.sdu.mmmi.featuretracer.lib.FeatureEntryPoint" annotation to annotate feature-entry-point methods in the source code of AnagramGame.
  11. In order to annotate features, first you will have to identify them. From the programs GUI the following features can be recognized: "program startup" - triggered by initializing the program, "program exit" - triggered in [File->Exit] and the close button of the window, "about window" - triggered by [File->about], "new word" - triggered by the "New Word" button, "guess word" - triggered by the "Guess" button. Depending on what you want to analyze you could decide to group some features together (e.g. "program exit" + "program startup" could become "program lifecycle management"), or annotate only a subset of all features.
  12. Now, you need to find methods to annotate in the source code of AnagramGame. You perform annotation by putting the "@FeatureEntryPoint( )" on a method and parameterizing it with the String-based identifier of an appropriate feature. In the com.toy.anagrams.ui.Anagrams class annotate the following methods:
    main - "program startup"
    exitMenuItemActionPerformed, exitForm - "program exit"
    aboutMenuItemActionPerformed - "about window"
    nextTrialActionPerformed - "new word"
    guessedWordActionPerformed - "guess word"
  13. Save all changes and build the program.
  14. Execute the "Trace Project" action again to run the annotated program in a traced mode.
  15. Trigger all the features by interacting with the program (Trigger the "exit program" feature as the last one).
  16. After you are done and the program closes, you will see 5 trace files created in the "FeatureTraces" directory in the anagramProject. These files are the input to analyzing your feature in Featureous.
  17. Bring up the main window of Featureous by executing [Window->Other->Show Featureous].
  18. To automatically load the trace files of the main project to Featureous press the "Update traces" button (icon with two arrows) or open them manually by pressing "Add feature traces…" ("plus" icon).
  19. Now you can analyze the features through an number of views. E.g. you can see the contents of features in the "Trace Inspector Window", you can see how features depend on each other in terms of object-reuse and producer-cosumer relations in "Feature relations characterization" (the 2nd icon in the views toolbar of features), you can see the "feature-code correlation graph" to see how packages and classes participate in implementing features, see the call graphs of features, etc. What you will do at this stage depends on what you want to achieve through the analysis, i.e. learning how a feature is implemented, seeing what classes are reused by multiple features, finding a division line when extracting features into separate modules, assessing how difficult it will be to modify a feature, finding reusable classes and methods, etc. For most of the views, you can use feature explorer to select the set of featues for which a view is to be constructed.