FINDER is a design pattern detection tool for software written in Java. MoRe is a tool suite that helps the evaluation of design pattern detection results. This page describes how to install and use FINDER and MoRe. 

Minimum requirements:\\
FINDER depends on [[http://www.swag.uwaterloo.ca/grok/index.html|Grok]] which means that at the moment it can only be run on Unix systems. Your Unix installation must include tcsh. The amount of memory required depends on the size of the software system you will apply FINDER on. Unless you are extracting design patterns from very large software, this is unlikely to be an issue.\\

Prerequisites:\\
In order to run FINDER, you need to have [[http://www.swag.uwaterloo.ca/javex/index.html|Javex]], [[http://www.swag.uwaterloo.ca/grok/index.html|Grok]], and [[http://www.swag.uwaterloo.ca/qldx/index.html|QL]] installed in advance. These tools are developed by the Software Architecture Group (SWAG) at the University of Waterloo, and they can be found at [[http://www.swag.uwaterloo.ca|SWAG site]]. (Note: FINDER is not compatible with all versions of the aforementioned tools. Some low versions of Javex may not work properly in FINDER. We suggest using FINDER equipped with Javex 1.0.8+. Some latest versions of Grok such as v95 which currently is the default downloadable version may report some warnings at runtime, although it doesn't influence the final results. However, the Grok (v83) that comes with QL should always work.)\\

Make sure you have set up certain environment variables for using all these tools, so that FINDER knows where they are. You can test this by calling the three tools at terminal. Messages such as "command not found" should not be there. \\

However, these prerequisites do not apply to MoRe since MoRe is not involved in the phase of design pattern detection. In fact, it is only used to the evaluation of detection results. Also, MoRe is written in Java which means it is not restricted to Unix systems. \\

Installation:\\
Download and extract {{finderandmore_all.tar.gz|FINDER and MoRe}} (all in one package) anywhere in your system. A number of configuration files need to be configured in order to apply FINDER and MoRe. \\
Let's assume that the path to the top level extracted directory is <path>.\\
Add the following commands to your .tcshrc file (adjust accordingly for other shells):

''setenv FINDER_DIR <path>''\\
''setenv PATH ${PATH}:${FINDER_DIR}/bin''

In order to detect patterns by FINDER, you will need to edit the following 4 files in the conf directory:\\

  *software.xml 
    *directory -- path to the software java class files
    *name  -- software system name
    *source_directory -- path to the software source code. 
    (Note: FINDER relies on both class files and source code of the target system.)

  *scripts.xml  
    *scriptsDirectory -- path to FINDER scripts, which refers to finder/scripts. No need to make change.
    *candidateInstancesDirectory -- path to detection results output directory

  *designpatterns.xml
    *designpattern -- By commenting in/out each "designpattern" tag, you can choose certain design patterns to be included during the detection stage.
    *ql_script  -- path to the specific FINDER script for the related design pattern. They are located at finder/scripts/ql/. No need to make change.

  *run.properties
    *input.design.patterns.xml.file -- path to the above designpatterns.xml file
    *input.software.xml.file -- path to the above software.xml file
    *input.scripts.xml.file  -- path to the above scripts.xml file
    *output.exception.txt.file -- path to exception output file

To run FINDER, simply give:\\

''finderDPD "path to run.properties file"'' \\

\\
\\

The MoRe tool suite contains the following applications:
   *FINDER converter -- This tool converts FINDER raw results into MoRe Instances. It requires an argument which is an XML file that specifies the name of the software system, the output location of converted results, and all design patterns with corresponding raw result file name. A sample of the configuration file, is shown below. 

  <FinderConf xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <systemName>TAB2PS</systemName>
   <moreInstanceDestination>FINDERInstance/</moreInstanceDestination>
   <pattern patternName="Composite" inputFile="rawResults/TAB2PS.composite.out"/>
   <pattern patternName="Decorator" inputFile="rawResults/TAB2PS.decorator.out"/>
   <pattern patternName="Template Method" inputFile="rawResults/TAB2PS.templatemethod.out"/>
   </FinderConf>

  Usage: finderConverter "path to the configuration file"

   *PINOT converter -- [[http://www.cs.ucdavis.edu/~shini/research/pinot|PINOT]] is one design pattern detection tool developed by Nija Shi and Ron Olsson. PINOT converter converts PINOT raw results into MoRe Instances. Unlike FINDER that reports results for every pattern in a separate file, PINOT outputs all pattern detection results in a single file. Therefore, we do not use a configuration file for the usage of the converter. Instead, the converter accepts three parameters at the terminal. The first one gives the software system name, the second one is the input file name which contains PINOT raw results, and the last one specifies the location for the output of the converter which can be omitted for the current path. More specifically, usage of the PINOT raw result converter is:

  Usage: pinotConverter "software system name" "path to the raw result file" "output path (optional)"

   *SSA converter -- [[http://ieeexplore.ieee.org/xpl/login.jsp?tp=&arnumber=4015512&url=http%3A%2F%2Fieeexplore.ieee.org%2Fxpls%2Fabs_all.jsp%3Farnumber%3D4015512|SSA]] is also one design pattern detection tool developed by N. Tsantalis et al. SSA converter converts SSA raw results into MoRe Instances. The usage of SSA raw result converter is same to that of PINOT raw result converter. 

  Usage: ssaConverter "software system name" "path to the raw result file" "output path (optional)"

   *Presenter -- This tool presents design pattern detection results based on MoRe models.

   Usage: presenter "path to a MoRe instance (optional)"

   *Comparator -- This tool evaluates design pattern detection results based on two MoRe instances.
   Usage: comparator "path to the Automatic MoRe instance" "path to the Benchmark MoRe instance" "one of the options below"
   options:
   -gap-b      Gross anchor precision based on Benchmark roles.
   -gar-b      Gross anchor recall based on Benchmark roles.
   -dap-b      Detailed anchor precision based on Benchmark roles.
   -dar-b      Detailed anchor recall based on Benchmark roles.
   -dapd-b     DAP diagram based on Benchmark roles.
   -dard-b     DAR diagram based on Benchmark roles.
   -gap-i      Gross anchor precision based on intersection of roles.
   -gar-i      Gross anchor recall based on intersection of roles.
   -dap-i      Detailed anchor precision based on intersection of roles.
   -dar-i      Detailed anchor recall based on intersection of roles.
   -dapd-i     DAP diagram based on intersection of roles.
   -dard-i     DAR diagram based on intersection of roles.
   -precision  Regular precision
   -recall     Regular recall

Combination of two MoRe instances can also be obtained by the comparator in the following way:
   Usage: comparator "path to one MoRe instance" "path to another MoRe instance" "the target combined file" -c

Note: Since there are quite a few options, in most cases, we use the next tool instead to obtain all metric results for convenience.

   *CompareAll -- This tool compare detection results for all metrics of multiple patterns produced by two tools at one time. In order to do this, a configuration file is needed to specify the software system name, tool name of the automatic result set, tool name of the benchmark result set, comparison type (based on benchmark roles or intersection of roles), and a list of pairs of MoRe instances to be compared. A sample is shown below.

  <CompareAll xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <systemName>TAB2PS</systemName>
  <automaticTool>SSA</automaticTool>
  <benchmarkTool>FINDER</benchmarkTool>
  <baseType>intersection</baseType>
  <listOfComparison>
  <comparison patternName="Decorator" benchFile="FINDERInstance/TAB2PS_Decorator.xml"
   autoFile="SSAInstance/TAB2PS_Decorator.xml"/>
  <comparison patternName="State" benchFile="FINDERInstance/TAB2PS_State.xml" 
   autoFile="SSAInstance/TAB2PS_State.xml"/>
  <comparison patternName="Strategy" benchFile="FINDERInstance/TAB2PS_Strategy.xml" 
   autoFile="SSAInstance/TAB2PS_Strategy.xml"/>
  <comparison patternName="TemplateMethod" benchFile="FINDERInstance/TAB2PS_TemplateMethod.xml" 
   autoFile="SSAInstance/TAB2PS_TemplateMethod.xml"/>
  </listOfComparison>
  </CompareAll>

\\
\\
A sample (located in the "sample" directory) is also provided in our package for the purpose of illustration and testing. This sample is based on a small software system -- TAB2PS. In the "sample" directory, "TAB2PS" contains the software system, "sampleConf" contains all the above mentioned configuration files as an example, and "tab2ps_pinot.out" and "tab2ps_ssa.xml" are raw detection results provided by PINOT and SSA, respectively. In order to run the sample, simply give:\\

'runSample_tab2ps' \\

This command involves using FINDER to detect design patterns used in TAB2PS system, converting FINDER, PINOT and SSA raw results into MoRe instances, obtaining all the metric values among the results, and finally presenting the combination of all the results of Decorator pattern of the three tools as an example. \\