Migrating Deprecated API to Documented Replacement: Patterns and Tool

Deprecation is commonly leveraged to preserve the backwards compatibility in API clients during API evolution. Client developers then usually encounter migration tasks when relying on a new version of API. Manually migrating a deprecated API to its replacement may be tedious and time-consuming. Existing research has focused on the requirements of automated migration however has limitations on the consistency and granularity of the generated migration pathway. In this paper, we propose an approach for migrating deprecated APIs to their replacements which are explicitly documented in the code documentation. A migration pattern including the migration type and the migration strategy is first introduced to describe the difference and the code change from a deprecated API to its replacement. An automated process is then designed and implemented to construct the pattern for a specific deprecated API by reviewing the code documentation and analyzing the API source code. Based on the patterns, a tool named DAAMT is developed to locate deprecated APIs and to provide migration suggestions for API clients. An experimental study on open-source Java projects and a user study is performing utilizing the approach. The results show that three-fourth of the deprecated APIs with documented replacements involved in the projects can be automatically migrated. In addition, the DAAMT tool can improve the efficiency and accuracy of the tasks compared with the manual migration.