Source-linked AI summary
MigrationMiner: An Automated Detection Tool of Third-Party Java Library Migration at the Method Level
Hussein Alrubaye, Mohamed Wiem Mkaouer, Ali Ouni
TL;DR
Library migration requires developers to find replacement methods while preserving behavior, and existing work describes the process as manual, error-prone, and time-consuming. MigrationMiner analyzes Java projects to collect migration traces and method documentation; in its case study, manually inspected detected fragments achieved 100% precision.
Problem
Library migration requires finding replacement API methods while preserving program behavior, and existing studies describe the process as manual, error-prone, and time-consuming.
Source: §I · p. 1Method
MigrationMiner analyzes Java projects to detect migrations, extract and filter code fragments containing replaced methods, and collect associated API documentation.
Source: §I · p. 1Results
100% precision was achieved for detected fragments that were manually inspected in the case study; recall was not applicable because unrevealed fragments were not manually investigated.
Source: §IV · p. 4Takeaways & Limitations
The collected migration traces and documentation can provide by-example migration patterns for developers and practical insights for researchers.
Source: §I · p. 1
Abstract
from arXiv · showhide
In this paper we introduce, MigrationMiner, an automated tool that detects code migrations performed between Java third-party library. Given a list of open source projects, the tool detects potential library migration code changes and collects the specific code fragments in which the developer replaces methods from the retired library with methods from the new library. To support the migration process, MigrationMiner collects the library documentation that is associated with every method involved in the migration. We evaluate our tool on a benchmark of manually validated library migrations. Results show that MigrationMiner achieves an accuracy of 100%. A demo video of MigrationMiner is available at https://youtu.be/sAlR1HNetXc.
I. Introduction
Third-party library migration is difficult because developers must find replacements while preserving program behavior, and existing migrations are manual, error-prone, and time-consuming. MigrationMiner analyzes Java projects to detect migration changes and collect code fragments with associated method documentation.
I. Introduction
- Library migration requires finding replacement API methods while preserving program behavior, unlike upgrading between versions of the same library.Developers must explore the new library's API, documentation, and usage scenarios.Source: §I · p. 1
- Existing studies describe library migration as manual, error-prone, and time-consuming, with developers spending up to 42 days on migrations.The paper also reports that developers may be reluctant to migrate, leaving dependencies outdated or vulnerable.Source: §I · p. 1
- MigrationMiner detects library migrations, extracts and filters relevant code changes, and collects API documentation associated with the methods involved.Its output includes migration traces, code context, and corresponding documentation.Source: §I · p. 1
- MigrationMiner is presented as an open-source tool and dataset for extracting migration traces between different libraries.Developers can use extracted patterns as by-example support, while researchers can study migration challenges.Source: §I · p. 1
- MigrationMiner is publicly available as an open-source tool with a demo video.Source: §I · p. 1
II. Background
The background defines library migration and the units used to describe migration rules, method correspondences, periods, and code fragments.
II. Background
- A library migration replaces a source library with a target; the source is retired when none of its methods remain used in client code.The library need not be physically removed from the project.Source: §II · p. 2
- A migration rule is a source-to-target library pair, such as json →gson.Source: §II · p. 2
- A method mapping identifies correspondences between at least one source-library method and one or more target-library methods.Source: §II · p. 2
- A segment is the migration period: one or more code changes, each containing one or more fragments.Source: §II · p. 2
- A fragment is a code block witnessing at least one mapping, formed by retaining removed source-library methods and added target-library methods.Source: §II · p. 2
III. MigrationMiner
This section outlines MigrationMiner's architecture and typical usage scenario, describing component workflows through their inputs and outputs.
III. MigrationMiner
- The section presents MigrationMiner's architecture and a typical usage scenario.Source: §III · p. 2
- For each MigrationMiner component, the section explains its input, output, and workflow.Source: §III · p. 2
A. Data Collection
Data collection accepts open-source GitHub projects, mines their commits and library-configuration changes, and outputs potential library changes with their associated projects and commits.
A. Data Collection
- MigrationMiner accepts a list of open-source GitHub project links, allowing multiple projects to support automated mining.Source: A. Data Collection · p. 2
- The collection phase clones projects, checks out commits, records commit properties, and tracks changes to pom.xml library configurations.Mined project data is stored in a SQL database; the illustrated commit removes json and adds gson.Source: A. Data Collection · p. 2
- The collection phase outputs potential library changes together with their corresponding commits and projects.Source: A. Data Collection · p. 2
B. Migration Detector
The detector forms candidate migration rules from added and removed libraries, then filters them by relative frequency and method-level migration evidence.
B. Migration Detector
- The detector takes library changes, corresponding commits, and projects as input.Source: B. Migration Detector · p. 3
- It computes the Cartesian product of added and removed libraries to generate candidate mappings, which can include many false positives.Source: B. Migration Detector · p. 3
- It retains mappings above a user-set normalized-weight threshold, then keeps only rules with at least one source method replaced by a target method.The default threshold is trel = 1.Source: B. Migration Detector · p. 3
C. Segment Detection
Segment detection finds migration periods for each rule across projects by locating the end and then tracing backward to the start of the migration.
C. Segment Detection
- Static program analysis locates a segment’s end by scanning commits until project source files no longer depend on the retired library.Source: C. Segment Detection · p. 3
- From the end commit, the detector scans backward to find the first code change replacing a retired-library method.A library may remain in the project’s pom.xml even when none of its methods are used in client code.Source: C. Segment Detection · p. 3
- The detector tracks source and target library versions for each segment to avoid backward incompatibility when a library API changes between versions.Source: C. Segment Detection · p. 3
D. Fragment Detection
Fragment detection extracts migration-related code changes from commits in identified segments and discards rules without valid method-replacement fragments.
D. Fragment Detection
- The detector clones changed source files from segment commits and applies Git’s Unified Diff Utility to generate code fragments.Source: D. Fragment Detection · p. 3
- A valid fragment must contain removed methods from the source library and added methods from the target library.Source: D. Fragment Detection · p. 3
- For the json-to-gson example, it retains toJSONString() as removed and Gson() and toJson(Object) as added, while excluding unrelated changes.Source: D. Fragment Detection · p. 3
E. Documentation Collector
The documentation collector retrieves API documentation for methods involved in migration fragments and associates documentation with each method.
E. Documentation Collector
- For each fragment, the collector retrieves documentation for source and target methods by downloading the relevant library-release jars from Maven Central.Source: E. Documentation Collector · p. 4
- It converts documentation jars into HTML files with the doclet API, then parses class, method, parameter, return, package, and class-name descriptions.Source: E. Documentation Collector · p. 4
- The collector identifies the documentation associated with every method involved in a migration rule.Source: E. Documentation Collector · p. 4
IV. Case Study
The case study found all migration rules and corresponding fragments in its benchmark, and manually validated three additional rules. The additional detections had 100% precision, while recall was not assessed.
IV. Case Study
- The benchmark subset comprised seven Maven-compatible projects with three migrations, drawn from a dataset covering four rules across 16 projects.Source: §IV · p. 4
- 100% precision and recall were achieved when detecting all migration rules and corresponding fragments in the evaluated projects.The reported comparison is against manual detection on the benchmark.Source: §IV · p. 4, Table I · p. 4
- Three additional migration rules and their fragments were manually validated, yielding 100% precision; recall was not applicable because unrevealed fragments were not investigated.Source: §IV · p. 4
V. Conclusion and Future Work
MigrationMiner detects migrations between third-party Java libraries and has been used to study migrations in projects. Future work plans an interactive tool for method-level migration recommendations.
V. Conclusion and Future Work
- MigrationMiner is an open-source tool for detecting migrations between third-party Java libraries.Source: §V · p. 4
- The tool has been used to detect and study nine migrations in 57,447 projects, and the work was published at the 27th IEEE/ACM International Conference on Program Comprehension.Source: §V · p. 4
- Future work plans to extend MigrationMiner with an interactive tool for recommending library migration at the method level.Source: §V · p. 4