Skip to content
BranchesTags

Repository files navigation

Java Eclipse Release MIT License DOI


Logo

jFamilyCounselor

Eclipse plugin bundling metric-based static code analyses that reveal fragments containing hidden type correlations
« Approach | Batch Demo »

What's New in v3.0

Version 3 extends jFamilyCounselor from an interactive-only Eclipse plugin into a tool that also scales to whole corpora, and broadens what it can analyse:

  • Headless batch mode — a new OSGi application, ro.lrg.jfamilycounselor.batch.app, runs the analyses without the Eclipse UI, exporting the same per-class CSVs, HTML reports and HFTC visualisations. This enables unattended, corpus-scale evaluation. See jfamilycounselor.docs/BATCH.md.
  • Five estimation approaches selectable per run: name, levenshtein, casts, instanceof, assignments — from cheap lexical screening to precise data-flow derivation.
  • Collections & generics support — the assignments approach now unwraps container element types (e.g. List<Wine> → Wine) and traces .add(new RedWine())-style additions, and partially covers generic code.
  • Performance — per-project caching of cones/products/used-types and parallel pair estimation on a dedicated fork/join pool; a full five-approach run of a ~500-type engine completes in minutes, and the lexical/pattern approaches scale past 1,000 relevant types.
  • A runnable demo — jfamilycounselor.demo/run-winebar-demo.sh analyses the three bundled WineBar example projects end-to-end and prints the detected families. No corpus or network needed.

The tool was evaluated on 37 Java projects (185 batch runs) spanning synthetic ground-truth projects, the LGTM #Family reference corpus, and a broad set of libraries and industrial systems.

Requirements

Minimal Requirements

  • Java Version: 17
  • Eclipse IDE for RCP and RAP Developers 2023-06 R

Notes

  • it is strongly recommended to use the specified versions
  • the plugin does not currently work when installed on Eclipse IDE for Java Developers
  • using a Java >= 17 with any Eclipse IDE for RCP and RAP Developers <= 2023-03 R is impossible due to a bug in Eclipse, ultimately addressed here

Plain Installation

  1. In Eclipse IDE for RCP and RAP Developers, go to Help > Install New Software... > Add... > Local...
  2. Open the jfamilycounselor.repository folder
  3. Install the deployable feature jFamilyCounselor that should appear under the LOOSE Research Group category (check/uncheck the Group items by category)
  4. Accept the license terms
  5. Trust the unsigned content of the unknown origin
  6. Restart Eclipse

Check Installation

  • Upon start, a log indicating that the plugin was loaded should be present in the Error Log view
  • Create workspace and import the Java projects from jfamilycounselor.example
  • Using the Package Explorer view, right-click on the WineBar project and select Browse in Insider (Note: Make sure the projects have the Java nature)
  • Alternatively, using the Package Explorer view, right-click on the WaiterTray class (NOT on the compilation unit WaiterTray.java) and select Browse in Insider (Note: A class is represented as a 'C' green encircled icon. Browsing in Insider a compilation unit will result in no entries in the Insider view)
  • In either scenarios, you should see an entry in the Insider view

Installation Problems

If the starting log, or the Browse in Insider option is missing, or nothing can be seen upon browsing, the installation was not successful. Retry with a clean installation in a different, newly installed Eclipse.

Development Environment Setup

jFamilyCounselor is developed using the XCore framework. In order to install XCore, copy the binaries in the dropins folder of Eclipse. The binaries are also present in the ro.lrg.insider/lib folder.

Before working with jFamilyCounselor, it is recommended to experiment with XCore. Skimming through the paper and following the XCore's tutorial (present on its repository Wiki) would be recommended. Also refer to the XCore Training section.

jFamilyCounselor's Workspace

In order to setup the jFamilyCounselor's workspace, configure it as specified in the tutorial and import the following projects:

  • jfamilycounselor
  • jfamilycounselor.test
  • jfamilycounselor.feature
  • ro.lrg.insider (also found here)

Check Setup

  • Use the launch configuration from the jfamilycounselor project to start an Eclipse Application
  • Follow the Check Installation steps

For further explanations on how to use jFamilyCounselor, please refer to the tool demo paper (coming soon).

XCore Training

Before working with jFamilyCounselor, it is recommended to experiment with XCore. Skimming through the paper and following the XCore's tutorial (present on its Wiki pages) would be recommended. Also, refer to the dev notes below whenever stumbling upon a bug/problem.

XCore Summary

XCore is a tool that dynamically generates the meta-model of static analyses. It works based on the following abstractions: properties, groups and actions.

  • a property represents a computation applied on an analysed element. For a class, the number of its fields, the number of its descendants, a boolean indicating whether the class contains static methods or not, all represent properties of that class
  • a group models a one-to-many relationship between elements. Some possible groups of a class are: the group of fields or methods the class declares, the group of interfaces it implements, etc.
  • an action triggers some behavior that is related to that element. For instance, we can trigger a job that exports the results of a Java project analysis as a CSV file

XCore Tutorial Summary

  • Make sure to have Eclipse RCP Plug-in Developer Resources installed
  • Stop project automatic builds
  • Create a new plugin project; add as Imported Packages: ro.lrg.xcore.metametamodel (Note: The names of the projects that use XCore should not contain dots, otherwise there might be bugs)
  • Enable the XCore annotation processor (which should be visible only if XCore's jar was placed in dropins)
  • Import the ro.lrg.insider plugin project and make the former project depend on it
  • Implement metrics (Note: In order to properly see the XCore property page, make sure to be in the Java perspective, not in Plugin Development and go to the Java's projects properties through the Package Explorer view)

Using jFamilyCounselor - Going to the WineBar

jFamilyCounselor is an Eclipse plugin that runs a metric-based static code analysis, capable of identifying fragments containing hidden familial type correlations in Java source code.

Note: Make sure the plugin is properly installed in order to continue.

Export a WineBar Report

  • In the Package Explorer view, right-click on the "WineBar" Java project > Browse in Insider
  • In the Insider view, right-click on WineBar > Actions > jfamilycounselor > AssignmentsBasedReport.
  • In the project's root folder there should be a directory containing the results: jFamilyCounselor/reports (Note: same goes for exporing visualisations - HFTC View)

Analyse the WaiterTray class

  • In the Package Explorer view, expand the project until reaching to the WaiterTray.java compilation unit.
  • In the Package Explorer view, expand the compilation unit so as to see the WaiterTray class (green 'C' icon) > right-click > Browse in Insider.
  • In the Insider view, right-click on ro.lrg.winebar.WaiterTray > Properties > jfamilycounselor > AssignmentsBasedApertureCoverage.
  • Right-click on ro.lrg.winebar.WaiterTray > Groups > jfamilycounselor > RelevantReferencesPairs.
  • Right-click on any entry > Properties > jfamilycounselor > AssignmentsBasedApertureCoverage.
  • Right-click on the entry for which the aperture coverage is minimum (0.5) > Groups > jfamilycounselor > AssignmentsBasedUsedTypes.

Headless Batch Analysis (v3)

To analyse a project — or a whole corpus — without the Eclipse UI, use the batch application. This is the mode used for the corpus evaluation.

Try it on the bundled examples (self-contained):

export ECLIPSE_HOME=/Applications/Eclipse.app/Contents/Eclipse   # your RCP/RAP install
cd demo
./run-winebar-demo.sh

This builds and installs the batch bundle if needed, runs all five approaches on the three WineBar example projects, and prints the detected families (each designed family class reports Aperture Coverage 0.50).

Analyse your own project:

cd demo
./analyze-project.sh <ProjectName> <import-dir1[,import-dir2,...]> [estimations] [out-dir]
python3 summarize.py <out-dir>

Under the hood, the demo wraps this call:

java -Xss16m -Xmx8g \
  -cp "$ECLIPSE_HOME/plugins/org.eclipse.equinox.launcher_*.jar" \
  org.eclipse.equinox.launcher.Main \
  -application ro.lrg.jfamilycounselor.batch.app \
  -data /tmp/jfc-workspace -nosplash \
  -import /path/to/project -analyze MyProject \
  -estimations name,levenshtein,casts,instanceof,assignments \
  -out /path/to/results

Full reference — arguments, classpath setup, reading results, troubleshooting — is in jfamilycounselor.docs/BATCH.md. Demo scripts: jfamilycounselor.demo/.

Notes on Using jFamilyCounselor

  • The cast-based approach records a slower progress at the beginning, and becomes better afterwards owing to caching
  • The implemented analyses perform heavy computations and use a lot of memory and CPU. It is recommended to allocate at least 6GB RAM for the Eclipse application that runs jFamilyCounselor in order to obtain results in a feasible amount of time
  • The visualisation might not be displayed immediately after export due to some permission issues. It is best to configure Eclipse to use an external browser to fix this problem.
  • The visualisation might not perform well for large projects when zooming
  • In a visualisation, is a correlation has multiple clients and the tooltip overflows, press F2 in order to lock the tooltip be so to scroll through the list; another press unlocks the tooltip
  • XCore currently does not run any computation on separate threads and long operations can block the UI. It is best to analyse projects following these steps:
    • Export a report using one of the XCore actions. The export is located in the project's root folder
    • Use the results to determine the types that might be interesting to be analysed manually
    • Browse those types in Insider individually and navigate through its defined groups to see, for instance, its relevant references pairs, or possible/used types of a particular pair

Notes on Developing jFamilyCounselor

  • For better performance, it might be needed to reconfigure the CacheSupervisor depending on the available amount of RAM
  • The ro.lrg.jfamilycounselor.plugin package contains all classes which are responsible for the metamodel's generation through XCore
  • In terms of vocabulary, a capability is nothing but a glorified singleton that wraps some logic which can be tested in isolation and composed with other capabilities
  • Always use the Java perspective, not the default Plugin Development; some XCore features function only when using the former

Deployment

The deployment of the plugin is done using the jfamilycounselor.feature. The deployable features are exported in the jfamilycounselor.repository folder.

Results. Corpus

Initial Results

The project that was intensively analysed is kettle-engine. In order to reproduce jFamilyCounselor's results presented in Rosu et al., Towards the Detection of Hidden Familial Type Correlations in Java Code, SCAM 2022, follow these steps:

Allocate more RAM

The plugin currently requires a lot of memory in order to perform the Assignments Based analysis on the target project. Therefore:

  1. Go to the Eclipse's installation path
  2. Search for the eclipse.ini file
  3. Update the -Xms and -Xmx flags:
-Xms6g
-Xmx8g

v3 Corpus Evaluation

Version 3 was evaluated on 37 Java projects (185 headless batch runs) via the batch mode. The corpus combines synthetic ground-truth projects (the bundled WineBar examples), the LGTM #Family reference set assumed to contain hidden correlations, and a broad set of libraries and industrial systems. The tool recovers the defining familial hierarchy of every analysable reference project — e.g. the SQL AST node hierarchy in Apache Derby, GeoElement in GeoGebra, cipher engines in BouncyCastle, deserialisers in jackson-databind, filter visitors in GeoTools — and correctly reports nothing on true-negative projects. The per-project setup, per-class CSVs, VALIDATION.txt notes and a MASTER_SUMMARY.csv are archived under evaluation/results-archive/ in the thesis repository.

The LGTM #Family reference corpus derives from the study: Luis Mastrangelo, Matthias Hauswirth, and Nathaniel Nystrom. 2019. Casting about in the dark: an empirical study of cast operations in Java programs. Proc. ACM Program. Lang. 3, OOPSLA, Article 158 (October 2019), 31 pages, DOI.

License

All code is available to you under the MIT license, available at http://opensource.org/licenses/mit-license.php and also in the LICENSE file

About

Eclipse plugin for detecting hidden familial type correlations

Resources

Readme
MIT license
Activity
Custom properties

Stars

0 stars

Watchers

1 watching

Forks

1 fork
Report repository

Releases

Contributors

Languages