-We combine multiple dimensions of knowledge about APIs so that we can support API migration by wrapping or transformation in new ways. That is, we assess wrapper-based API re-implementations and provide guidance for migrating API methods. We demonstrate our approach with two major GUI APIs for the Java platform and two wrapper-based re-implementations for migrating between the GUI APIs.
API migration is a kind of software migration; it may
be necessary to meet requirements for software
modernization, application integration, and others. API migration
is realized by wrapping or transformation. We refer to [
For instance, consider the following re-engineering scenario. Two Java applications need to be integrated, but they use different GUI APIs, say SWING and SWT. Based on the exercised features and possibly other considerations, one of the two APIs is favored for the integrated application. The disfavored API (the “source API”) can be re-implemented in terms of the favored API (the “target API”) as a wrapper so that the migration requires little, if any, rewriting of the application’s code. Incidentally, there are two advanced open-source wrappers that serve both directions of migration: SWINGWT1 and SWTSWING2.
In previous work [
Contribution: In the present paper, we describe an approach for the combination of multiple dimensions of knowledge about APIs so that API migration can be supported in new ways. That is, we assess wrapperbased API re-implementations and provide guidance for migrating API methods. To this end, we leverage a modelbased approach to the integration of knowledge about APIs into a repository for convenient use in declarative queries. Throughout the paper, we use the SWING/SWT APIs and the above-mentioned wrappers as subjects under study.
Road-map: Sec. II describes the integrated
repository. Sec. III and Sec. IV cover different forms of
supporting API migration. Related work is discussed in Sec. V,
and the paper is concluded in Sec. VI. The paper and
accompanying material are available online.3
1http://swingwt.sourceforge.net/: re-implements SWING in terms of SWT
2http://swtswing.sourceforge.net/: re-implements SWT in terms of SWING
3http://softlang.uni-koblenz.de/apirep/
Acknowledgement We are grateful to Daniel Ratiu for providing
us with data related to the programming ontology of [
We integrate three data sources with API knowledge into a repository. Let us describe those data sources, the metamodel of the integrated repository, and the repository technology as such.
APIMODEL (developed by the present authors)—a
model of API implementations (including SWING,
SWT, SWINGWT, SWTSWING) with an underlying
metamodel that is a (very) limited Java metamodel
for structural properties and calling relationships;
APIUSAGE (developed by La¨mmel et al. [
The APIMODEL source contributes basic knowledge about types and methods of genuine API implementations, and their coverage by the typically incomplete wrapperbased re-implementations. The APIUSAGE source helps to assess, for example, the relevance of genuine methods that are not implemented in a wrapper. The APILINKS source helps to derive candidate classes and methods that could be used in a wrapper-based API re-implementation.
Fig. 1 shows the metamodel (a UML class diagram) of our integrated repository where metaclasses are tagged by data sources APIMODEL, APIUSAGE, and APILINKS. We must note that the metamodel does not cover all elements of the sources, but is streamlined to fit our objectives.
The metaclass NamedElement represents packagequalified names of packages, classes, and methods. Because of the composition relationships in the metamodel, NamedElements are also qualified by the name of an API, in fact, by a particular implementation, which could be a genuine implementation or a wrapper-based reimplementation.
The metaclasses Package, Class, and Method represent the package hierarchy with the Java classes and their methods, further with extension relationships between classes (see association Extends) and calling relationships between methods (see association Calls). As a means of prioritization, we leave out interfaces; they are trivially copied by wrappers.
Classes of genuine API implementations are linked with the corresponding classes of wrappers (see association CorrespondsTo). Here we note that wrappers may use different package prefixes. Also, these links improve convenience for those queries that need to navigate between the different API implementations. The metaclass Concept models concepts in the sense of APILINKS’ ontology. Classes and methods can be linked with concepts; see associations IsClass and IsMethod. Hence, classes and methods of different APIs may be linked transitively.
The metaclass MethodUsage represents the usage data
that was integrated from APIUSAGE. That is, for each
API method, we maintain the number of calls to the
method (if any) within the SourceForge projects covered
by APIUSAGE [
The repository leverages the model-based TGraph
approach [
That is, a is an argument of the query for the name of the API; the query selects (“reports”) all classes c such that the qualified name of c matches with a and there are no outgoing edges of the type CorrespondsTo (see -->fCorrespondsTog) from c.
Consider again our introductory scenario for API migration. Which wrapper, SWINGWT or SWTSWING, should we favor? Such decision making should take into account wrapper qualities, e.g., its completeness or compliance— both relative to the genuine API implementation. In case we want to improve a given wrapper, we should also track progress by simple metrics. Accordingly, we propose some concepts for wrapper assessment.
We can trivially compare the APIMODEL data between genuine API implementation and wrapper to get a basic sense of completeness in terms of (the percentage of) genuine packages, classes, and methods that are covered (say, re-implemented) by the wrapper. Table I collects such metrics for the SWING/SWT wrappers. The numbers show that the wrappers are highly incomplete.
Packages Classes Methods
SWINGWT 25 (78.12 %) 533 (18.61 %) 4533 (26.60 %)
SWTSWING 16 (51.61 %) 372 (56.97 %) 3426 (42.59 %)
Some forms of non-compliance of a wrapper with the genuine API implementation can be determined by simple queries on our repository, e.g., differences regarding generalization hierarchies or the declaring classes for methods. Consider the following extension chain for SWING’s
java.lang.Object |_ java.awt.Component |_ java.awt.Container |_ javax.swing.JComponent
|_ javax.swing.AbstractButton
The chain itself is preserved by SWINGWT. However, SWING declares the method addActionListener on the class AbstractButton whereas SWINGWT declares the method already on the class Component.
Declarations on supertypes Empty implementations Missing methods
Class missing Class present
Table II shows numbers for some metrics for (lack of) wrapper compliance. In reference to the above example of the method addActionListener, we measure the number of methods that are declared “earlier” on a supertype in the wrapper. Further, we measure methods with empty implementations, i.e., implementations without any outgoing method calls, while the corresponding genuine implementations had outgoing method calls. (The substantial number of empty implementations may be surprising, but these wrappers are nevertheless reportedly useful in practice.) Finally, we also subdivide missing methods into those that are implied by missing classes vs. those that are missing from existing classes.
Let us qualify wrapper (in-) completeness with APIUSAGE data. If the developers of the wrappers applied the right judgement call for leaving out classes and methods, then the missing methods should be less relevant in practice than the implemented ones. Table III lists usage metrics for the SWING/SWT wrappers.
SWINGWT
SWTSWING Unimplemented methods
Any usage
Cumulative usage Empty methods
Any usage
Cumulative usage Non-empty methods
Any usage Cumulative usage
In the table, we break down SWING’s and SWT’s methods into categories according to the wrappers as follows: unimplemented, empty, and non-empty implemented methods. For each category, we show the percentage of methods with “any usage” (say, any calls) in the SourceForge projects in the scope of the APIUSAGE source. We also show “cumulative usage” for each category, i.e., the contribution of the category to all API method calls. These are contrasting numbers which show, for example, that the many unimplemented and empty methods (see again Table II) are exercised much less frequently than the fewer non-empty methods.
A given wrapper may be effectively incomplete in that a missing method is actually exercised by the application under API migration. In this case, we seek guidance for migrating the API method in question. Such guidance is universally useful for API migration—even when transformation is used instead of wrapping. A practical approach to guidance would need to combine elements of API type matching, IDE support (such as autocompletion and stub generation), and others. We focus here on the aspect of proposing method candidates to be called in methods of wrapper-based API re-implementations.
We can use APILINKS’ trace links between API methods and concepts to propose method candidates. The idea is that if methods of the source and target APIs are related to the same concept, then the latter may be useful in re-implementing the former. Further, let us sort all such candidates by their cumulative usage, say, by their relevance as far as APIUSAGE is concerned.
Qualified candidate name Cumulative usage (%) swing.javax.swing.ImageIcon.ImageIcon swing.java.awt.image.BufferedImage.BufferedImage swing.java.awt.Frame.getIconImage swing.java.awt.....MemoryImageSource swing.java.awt.Frame.setIconImage swing.javax.swing.text.html.ImageView.ImageView swing.java.awt.....ImageGraphicAttribute Suppose you need to migrate SWT’s Button.setImage to SWING. Table IV shows the method candidates that were automatically determined by a GReQL query. Consider the first line with the constructor of ImageIcon. We show the line in bold face to convey the fact that there is an existing wrapper, SWTSWING, whose method implementation of setImage readily involves the constructor of ImageIcon.
Further inspection reveals that SWING’s JButton, which is a counterpart to SWT’s Button, does not provide an Image property and, hence, we cannot simply migrate SWT’s Button.setImage to a corresponding setter of SWING. Extra state and a more complex idiom (indeed involving ImageIcon) is needed.
The above example shows that APILINKS may suggest reasonable candidates—in principle. We would like to assess APILINKS’s relevance more generally. In particular, we could compare APILINKS-based links with actual calling relationships in existing wrapper implementations, as they are available through APIMODEL’s data. Table V lists corresponding metrics for the SWING/SWT wrappers.
Unimplemented methods with links Implemented methods with links Correct links SWINGWT 10.83 % 28.06 % 42.75 %
SWTSWING 0.35 % 24.98 % 37.20 %
The coverage of API parts by APILINKS’ trace links
is an artifact of the underlying semi-automatic ontology
extraction approach [
In the table, we break down SWING’s and SWT’s methods into the categories of unimplemented and implemented methods according to the wrappers. For both categories, we show the percentage of methods that are linked (transitively) with one or more methods of the corresponding target API. The numbers are such that implemented methods happen to be much better linked than unimplemented ones.
At the bottom of the table, we also list the percentage of correct APILINKS’ trace links. We say that a link from the method m of the source API s to a method m0 of the target API t is correct, if a given wrapper-based reimplementation of s in terms of t implements m in a way that it directly calls m0. When we specify the percentage, we consider as the baseline (100%) only those methods m that both have associated trace links to t and actually call some method of t. It turns out that APILINKS predicts a correct link in more than 1/3 of the cases. We have to note though that APILINKS typically proposes multiple candidates—with a median of 8.
Work on API migration has previously focused on
transformation and wrapper-generation techniques for API
upgrades [
Most of the techniques that we integrate are inspired by
program comprehension research. For instance, our
comparison of different API implementations is a simple form
of object-model matching [
The complexity of API migration requires many skills and techniques. Of course, one must understand the API’s domain, and the application under migration. Basic software engineering skills such as testing, design by contract, effective use of documentation are critical as well. Still API migrations are largely unstructured today, and they come with unpredictable costs. We submit that techniques for assessment and guidance, such as those discussed in this short paper, are needed to tackle non-trivial API migrations in the future.
Clearly, our work is at an early state, and makes only a limited contribution to the larger API migration theme. There is a need for a comprehensive approach for guided API migration, which should combine diverse elements of assessment, mapping, matching, code completion, code generation, and testing.