{"id":18903862,"url":"https://github.com/hussien89aa/migrationmapper","last_synced_at":"2025-07-24T21:36:42.248Z","repository":{"id":270454937,"uuid":"223433036","full_name":"hussien89aa/MigrationMapper","owner":"hussien89aa","description":"Tool to find method mapping between two APIs by mining existing API Migration","archived":false,"fork":false,"pushed_at":"2021-04-26T20:01:58.000Z","size":1050,"stargazers_count":5,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-24T11:38:29.890Z","etag":null,"topics":["api-migration","api-mining"],"latest_commit_sha":null,"homepage":"http://migrationlab.net","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hussien89aa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-22T15:34:24.000Z","updated_at":"2025-05-18T15:51:25.000Z","dependencies_parsed_at":"2024-12-31T10:16:47.912Z","dependency_job_id":"c48c9c88-385e-413b-b968-ea2897b19305","html_url":"https://github.com/hussien89aa/MigrationMapper","commit_stats":null,"previous_names":["hussien89aa/migrationmapper"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/hussien89aa/MigrationMapper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hussien89aa%2FMigrationMapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hussien89aa%2FMigrationMapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hussien89aa%2FMigrationMapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hussien89aa%2FMigrationMapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hussien89aa","download_url":"https://codeload.github.com/hussien89aa/MigrationMapper/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hussien89aa%2FMigrationMapper/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264734542,"owners_count":23655689,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-migration","api-mining"],"created_at":"2024-11-08T09:06:41.219Z","updated_at":"2025-07-11T05:03:53.149Z","avatar_url":"https://github.com/hussien89aa.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"## MigrationMapper\n\u003cp align=\"justified\"\u003e\n\u003cb\u003eMigrationMapper\u003c/b\u003e is an open-source tool that provides the developer with an easy-to-use and comprehensive way of extracting, from a given list of input projects, existing method mapping between two third-party libraries using program analysis based on Abstract Syntax Tree (AST) code representation. In a nutshell, MigrationMiner (i) detects, (ii) extracts, (iii) filters, and (iv) collects code changes related to any performed migration, and (v) generates mappings between APIs of two libraries. A demo video of MigrationMapper is available on [Youtube](https://www.youtube.com/watch?v=D-01g2GjuTg)\n\n ### When you use this tool, please cite this paper.\n\u003cpre\u003e\n@inproceedings{alrubaye2019use,\n  title={On the use of information retrieval to automate the detection of third-party java library migration at the method level},\n  author={Alrubaye, Hussein and Mkaouer, Mohamed Wiem and Ouni, Ali},\n  booktitle={2019 IEEE/ACM 27th International Conference on Program Comprehension (ICPC)},\n  pages={347--357},\n  year={2019},\n  organization={IEEE}\n}\n\u003c/pre\u003e\n\n\n## Prerequisites\n\n* Install java JDK \u003e= 8 from [here](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html).\n* Install  MYSQL Server from [here](https://dev.mysql.com/downloads/installer/).\n* Install Python 3.8 or later from [here](https://www.python.org/downloads/).\n* Tool supports only MacOS and Linux based OS (ex, Ubuntu). If you are using Ubuntu, please install curl by running the following commands \"sudo apt install curl\".\n\n\n## How to install and run the tool\n\n#### To run the project on your local machine you can follow one of these two tutorials:\n \n #### A- Setup database\n* First you need to build the dataset, by running the following script Database/MigrationMapperDBSQL.sql.\nOpen a terminal and run the following commands\n```sql\n mysql -u root -p\n source ./MigrationMapperDBSQL.sql\n```\n\nAfter running the commands, the database should be created with all tables and views.\n\n#### B- Setup Python server\n\n* Install the following packages\n\n```\n% pip3 install Django\n% pip3 install jellyfish\n% pip3 install --user -U nltk\n% pip3 install numpy\n% pip3 install pandas\n% pip3 install sklearn\n```\n\n* download NLP  words\n```\n% python3\n\n\u003e\u003e\u003e import nltk \n\u003e\u003e\u003e nltk.download('punkt')\n\u003e\u003e\u003e nltk.download('stopwords')\n\u003e\u003e\u003e nltk.download('wordnet')\n```\n\n* Run python server for NLP text processing by going to folder 'python-service' and run \n```\n% python3 manage.py runserver\n\n```\n\n#### C- Setup MigrationMapper\n* Update [MigrationMiner/data/gitRepositories.csv](https://github.com/hussien89aa/MigrationMapper/blob/master/MigrationMapper/data/gitRepositories.csv) with the list of git repositories that you want to use as input (they will be searched for potential library migrations).\n* Update [MigrationMiner/data/config.json](https://github.com/hussien89aa/MigrationMapper/blob/master/MigrationMapper/data/config.json) to set your local MYSQL username and password  and github developer token in. to get github developer token Go to your github account under Settings \u003e Developer Settings \u003e Personal Access Tokens, add new token. Your token will be used so that Migration Miner can search a large number of GitHub projects without authentication issues.\n\n#### D- Run MigrationMapper: There are two ways to run the tool either using IDE or terminal which are:\n\n##### 1- Run MigrationMapper from the source code uisng IDE\n* Install Any Java IDE that support Maven Java project such as (Eclipse, IntelliJ IDEA, etc).\n* Open eclipse IDE then go to File-\u003e import-\u003e Maven-\u003e existing Maven Projects-\u003e Select MigrationMiner directory.\n* (Optional) We print alot of logs, to avoid console buffer overflow. In eclipse IDE go to   preferences-\u003e console-\u003e limit console buffer size to small number such as 10000.\n* Run the [Main.java](https://github.com/hussien89aa/MigrationMapper/blob/master/MigrationMapper/src/main/java/com/main/parse/Main.java).\n\n##### 2- Run MigrationMapper using the Jar file (MigrationMapper.jar)\n* Copy MigrationMapper.jar and [data](https://github.com/hussien89aa/MigrationMapper/blob/master/MigrationMapper/data/) folder that has gitRepositories.csv and config.json, which you need to update, to same directory.\n```\n--|\n  |- MigrationMapper.jar\n  |- data\n       |- gitRepositories.csv\n       |- config.json\n```\n\n* from terminal run\n```\n% java -jar MigrationMapper.jar\n\n```\n\n## Tool output\n\n##### A- Ouput as Relational Database\n* After running Main.java, the database Tables will be filled with any migration infomation found. For each potential migration, the following information can be found in database, whose schema is as follows:\n \n   * Repositories: List of projects that are scanned by the tool.\n   * AppCommits: List of projects' commits information (Commit Id, developer name, Commit text, and commit date).\n   * ProjectLibraries: List of libraries that were added or removed at every commit.\n   * MigrationRules:  List of migration Rules that were detected from the Dataset.\n   * MigrationSegments: List Of migration Fragments that were extracted from software migration.\n   * LibraryDocumenation: Library documentation associated with every library version that has been involved in any migration.\n   * MigrationMapping: List of method mapping between two APIs.\n##### B- Ouput as HTML\n   There will be a generated HTML file named \"MigrationMapperOutput.html\" that has the summary of all migrations detected, and for each migration, all its corresponding method mapping along with their Library documentation. An illutrative example of this file is in the following picture:\n   \n![main](http://attach.alruabye.net/migrationminer/methodMapping.jpg)\n\n\n##### C- Ouput as Objects\nAfter running Main.java, You could read the output as objects by writing the following code. or run [TestClient.java](https://github.com/hussien89aa/MigrationMapper/blob/master/MigrationMapper/src/main/java/com/main/parse/TestClient.java). That could help you to integrate the tool with your code.\n\n```java\n \n//Return list of migrations between two pairs of libraries( added/removed)\nLinkedList\u003cMigrationRule\u003e migrationRules= new MigrationRuleDB().getMigrationRulesWithoutVersion(1);\n\nfor (MigrationRule migrationRule : migrationRules) {\n System.out.println(\"== Migration Rule \"+ migrationRule.FromLibrary +\n      \" \u003c==\u003e \"+  migrationRule.ToLibrary +\"==\");\n\n /*\n *  For every migrations, retrieve list of detected Method mapping\n *  Between Two APIs\n */\n ArrayList\u003cSegment\u003e segmentList = new MigrationMappingDB().getFunctionMapping(String.valueOf(migrationRule.ID), false, false);\n\n for (Segment segment : segmentList) {\n\n  segment.print();\n\n  // Print all removed method signatures With Docs\n  printMethodWithDocs( migrationRule.FromLibrary,segment.removedCode);  \n\n  // Print all added method signatures With Docs\n  printMethodWithDocs( migrationRule.ToLibrary,segment.addedCode);\n\n } // End fragment for every migration\n\n}  // End library migration\n\n\n/* \n* This method takes list of methods signatures with library that methods belong to.\n* It will print the signatures and Docs for every method\n*/\nvoid printMethodWithDocs(String libraryName,ArrayList\u003cString\u003e listOfMethods ) {\n\n // For every add method print the Docs\n for(String methodSignature: listOfMethods){\n\n  // Convert  method signatures as String to Object\n  MethodObj methodFormObj= MethodObj.GenerateSignature(methodSignature);\n\n  //retrieve Docs from the library for method has that name\n  ArrayList\u003cMethodDocs\u003e  toLibrary = new LibraryDocumentationDB()\n                                           .getDocs( libraryName,methodFormObj.methodName);\n\n  //Map method signatures to docs\n  MethodDocs methodFromDocs = MethodDocs.GetObjDocs(toLibrary, methodFormObj);\n\n  if(methodFromDocs.methodObj== null) {\n   System.err.println(\"Cannot find Docs for: \"+ methodSignature);\n   continue;\n  }\n  methodFromDocs.print();      \n }\n}\n```\n \n## MigrationMapper has been used so far in the following papers:\n\n* Alrubaye, H., \u0026 Mkaouer, M. W. (2018, October). [Automating the detection of third-party Java library migration at the function level](https://dl.acm.org/citation.cfm?id=3291299). In Proceedings of the 28th Annual International Conference on Computer Science and Software Engineering (pp. 60-71). IBM Corp.\n* Alrubaye, H., Mkaouer, \u0026 M. W., Ali, O (2019).[ On the Use of Information Retrieval to Automate the Detection of Third-Party Java Library Migration At The Function Level](https://dl.acm.org/citation.cfm?id=3339129), 27th IEEE/ACM International Conference on Program Comprehension 2019.\n* Alrubaye, H (2020) [Towards the Automation of Migration and Safety of Third-Party Libraries](https://scholarworks.rit.edu/theses/10614/), Rochester Institute of Technology\n \n## License\n\nThis software is licensed under the [MIT license](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhussien89aa%2Fmigrationmapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhussien89aa%2Fmigrationmapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhussien89aa%2Fmigrationmapper/lists"}