FEMIR

A Tool for Recommending Framework Extension Examples

Software frameworks enable developers to reuse existing well-tested functionalities instead of taking the burden of implementing everything from scratch. However, to meet application-specific requirements, the frameworks need to be customized via extension points. This is often done by passing a framework-related object as an argument to an API call. To enable such customizations, the object can be created by extending a framework class, implementing an interface, or changing the properties of the object via API calls. However, it is both a common and non-trivial task to find all the details related to the customizations. While tutorials and documentation can provide a solution to the problem, they are difficult to create and maintain. Our tool FEMIR addresses this problem. It utilizes partial program analysis and graph mining techniques to detect, group, and rank framework extension examples. The tool extends existing code completion infrastructure to inform developers about customization choices, enabling them to browse through extension points of a framework, and frequent usages of each point in terms of code examples.

Required Programs and Files

FEMIR is available as a plugin for the Eclipse 3.6.2 release (Windows Platform). The following table provides links to the Eclipse and plugin jar files that need to be downloaded.

The plugin depends on the Eclipse Zest library for drawing components. Your Eclipse distribution may not contain that required library. It is advised that you download the following zip file (Eclipse Visualization Toolkit). It contains all the visualization components for working in the Eclipse. Extract the zip file and put all the jar files in the plugin folder located inside your Eclipse installation folder. The plugin requires a database that contains the collection of framework extension graphs. It can be generated by using the plugin or you can collect the database from another user of the FEMIR. To test the tool, you can use the following code base of Java Swing library for mining framework extension points( codebase ). You need to download, unzip the file and then instruct FEM to generate framework extension points. For detailed instructions please read below.

Installing The Plugin

[1] Download the Eclipse and the plugin jar files using the above links. [2] Download the codebase zip file using the above link. [3] Now, go to the Plugins folder located inside your Eclipse installation folder. Now put the plugin jar files (downloaded in the previous step) inside the plugin folder and start Eclipse IDE. [4] Install the Eclipse visualization toolkit as instructed above. [5] The program also requires PPA for Java. You can download and install the plugin by visiting the following link: PPA for Java [6] Create a folder containing source code for mining framework extension points. Alternatively, you can download the provided code base and unzip that into a folder. [7] Open the Eclipse IDE and select the menu item window>Preferences>FEMIR. This opens the FEMIR preference page as shown in the Fig. 1. [8] Provide the location of the Java source code by clicking on the corresponding browse button. You need to configure this if you want to generate a framework extension graph database from Java source code files that contain usages of a target framework. [9] Provide the location of the output folder. This folder will contain the framework extension graph database files generated by the FEMIR for the corresponding source code stored in the source code folder. [10] Instruct FEMIR to detect framework extension points and their usage patterns by selecting the appropriate command from the menu (see below for more detailed instructions). [11] Restart Eclipse and FEMIR will suggest framework extension points and their usage graphs while developing code example (see below for more detailed instructions).

Working with FEMIR

There are two steps to work with FEMIR.

  1. Detect framework extension points and their usage. The component of FEMIR that is responsible for this operation is called the Miner. The component accepts input from source code files and the name of the framework. It then generates result files that can be used for recommendation.
  2. Recommend extension points and their usage using results from the previous step. The Recommender component takes the input of the result files and the source code files to recommend extension points in the completion popup menu. When a developer selects an extension point, the tool group the graphs and shows the patterns of using the extension point in a JFace TreeViewer component. Developers can select a node of the TreeViewer component to see the graph pattern and can examine implementation examples by selecting nodes of the graph.

Detect Extension Points and their Usages

[1] To generate/analyze framework extension graphs for a target framework, you need to include the source code location and the output folder in the FEMIR preference page.

FEMIR preference page

[2] To instruct FEMIR to detect extension points and their usages, select the Mine Extension Points command from the menu as shown below. FEMIR also allows to generate the framework extension points and their usage graphs from the Eclipse project open in your own IDE. If you are a framework developer, you can use FEMIR to generate the graph database and share that to your client so that they can understand the framework easily. To create the database from the projects open in your Eclipse IDE, follow the following steps. Select the project and right-click to open the context menu. Select the Find Extension Points option from the context menu as shown in the following figure. This will generate the database files in the output folder specified in the FEMIR preference page.

FEMIR menu

[3] Now, specify the framework name as a qualified type name. For example, to specify Java Swing framework you need to type javax.swing. and you need to type java.awt. to specify Java AWT framework.

Using the context menu to detect extension points and their usage graphs
FEMIR dialog that takes the target framework name as an input

[4] FEMIR will generate the framework extension graphs and all related result files will store in the output folder specified in the preference page.

Recommend Extension Points and Framework Extension Examples

[1] Configure the location of source code files and the results of framework mining in the preference page, if you have not done already. [2] When you type a dot after a receiver name, the code completion manager will show completion proposals. Type ctrl-space again to see the recommended extension point.

FEMIR shows extension points as completion proposals

[3] Select an extention point by pressing the enter button. FEMIR will mine, group and report framework extension patterns in the Extension Graphs Viewer view.

[4] If you select a node in the above view, FEMIR will visualize the graph pattern in the Femir Visualizer view (see the following figure).

Once the TreeCellRenderer extension point is selected (see Fig. 5), FEMIR shows all of its framework extension graphs grouped by categories (bottom view), as well as visualization of a selected graph from the Customize category (top left). By selecting a node of the graph user can examine the corresponding implementation example (top right).

[5] Selecting a node in the visualized graph will show the implementation example. Developers can examine the code and the adapt the code examples in their own implementation.

Contact

In case you find any difficulty running the tool or find any bugs, please let us know. To contact us please use the following email address: parvez.usask@gmail.com. Thanks.

Questions on Terminologies

Q: What is a software framework? A software framework is a reusable implementation of some generic functionality that saves both development time and effort for a client. Frameworks have key distinguishing features that separate them from libraries. These are an inversion of control, extensibility, default behaviour and non-modifiable framework code. Stack Overflow contains a great discussion on the properties of software frameworks.

Q: What do you mean by a framework extension point? One common way to customize the behaviour of a framework is to pass a framework-related object as an argument in an API call. The argument object essentially encapsulates a specific way to customize the framework. The object may be created by subclassing a framework class, implementing a framework interface, or customizing the properties of an existing object. We consider the formal parameter of the API call as an extension point. As an example of an extension point, the following figure (A) shows that the size of a JFrame is set to a Dimension object. Some additional but more interesting examples from JTree are TreeModel, TreeCellEditor, TreeCellRenderer, and TreeExpansionListener. These extension points allow a developer to gain finer control over the behaviour of framework classes such as JFrame and JTree.

The same extension point can be used in different ways. For example, there are three different ways to customize the cell rendering behaviour of JTree. One can call the setCellRenderer method with an object of the existing framework class DefaultTreeCellRenderer which implements the TreeCellRenderer interface. One can change the cell rendering behaviour by calling a set of methods on the DefaultTreeCellRenderer object prior to using that object as an argument (B). Alternatively, one can create a new class to implement the TreeCellRenderer interface and override the getTreeCellRenderComponent method (C). Finally, one can subclass DefaultTreeCellRenderer and pass it as the argument for setCellRenderer (D).

Q: What is a framework extension graph? A framework extension graph describes how a framework extension point is used. Figure 6 shows an example of a framework extension graph where a developer uses the TreeCellRenderer extension point. Here, the developer registers an instance of the DefaultTreeCellRenderer class using the setCellRenderer method argument of an instance of the framework class JTree. To customize the behavior the developer calls methods on the object of the DefaultTreeCellRenderer class. FEMIR analyzes API method calls that have at least one parameter and is related to the target framework type. Thus, the argument to the method call can be a framework class object. Alternatively, it can be created by extending a framework class, implementing framework interfaces or a combination of both. FEMIR then generates the graph structure by considering the receiver variable, the method call, the parameter, the argument, and those methods that are called on the receiver or argument variable. If the receiver or the argument is created by extending framework classes or implementing framework interfaces, FEMIR considers the extended classes, implemented interfaces, overridden methods and methods that are called in overridden method bodies to generate the framework extension graph.

</div>