In the course of a framework's evolution, changes ranging from a simple refactoring to a complete rearchitecture can break client programs. Finding suitable replacements for framework elements that were accessed by a client program and deleted as part of the framework's evolution can be a challenging task. SemDiff is a recommendation system that suggests adaptations to client programs by analyzing how a framework adapts to its own changes. SemDiff also provides a repository analysis framework that can be used by researchers to study the evolution of any software products developed with CVS or Subversion.

Analyzing a CVS Repository

This tutorial will guide you through the steps of analyzing the history of an Eclipse project, org.eclipse.jdt.junit4.runtime. We will assume the following directory structure:

• /home/myuser/semdiff/db -> This is the directory that will contain SemDiff's database.
• /home/myuser/semdiff/junit/log -> This is the directory that will contain the eclipse project cvs log.
• /home/myuser/semdiff/junit/source -> This is the directory that will contain the eclipse project source file.

Note to Windows user: you can replace all paths by C:\your_path. For example, C:\semdiff\db is a valid path for Windows.

Overview

1. Initialize SemDiff database so it has the right structure.
2. Define a local profile to tell SemDiff to perform the analysis on your machine (as opposed to communicating with a remote instance).
3. Create a repository to indicate to SemDiff where to find project versions information.
4. Retrieve repository history log.
5. Analyze the first 10 transactions.

Steps

1. Install SemDiff

2. In the SemDiff menu, select "Init Database". Enter the following information:

   • Username: sa
   • Password:<Leave it empty>
   • Connection String: jdbc:hsqldb:file:/home/myuser/semdiff/db/hsql;hsqldb.default_table_type=cached
   • Driver: Choose "org.hsqldb.jdbcDriver"
   • Dialect: Choose "org.hibernate.dialect.HSQLDialect"

3. Push on OK. A dialog should appear telling you that the initialization went well.

4. Open the repository view. Go to Window -> Show View -> Other... -> SemDiff -> SemDiff Repositories

5. In the SemDiff Repositories view, click on the "Manage Profiles" button. Push on Add Profile.

6. A dialog will appear, select "Local Profile", then Next >. Enter the following values:

   • Name: My Local Profile
   • Username: sa
   • Password: <Leave it empty>
   • Connection String: jdbc:hsqldb:file:/home/myuser/semdiff/db/hsql
   • Driver: Choose "org.hsqldb.jdbcDriver"
   • Dialect: Choose "org.hibernate.dialect.HSQLDialect"
   • Local director: <Leave it empty>
   • Same as Repository: <Checked>

7. Push on Finish, then OK.

8. Your profile should appear in the SemDiff Repositories View. Push on the "Add Repository" button (the green cross). A dialog should appear.

9. Select the CVS repository type, push Next >. Enter the following values:

   • Name: Eclipse JUnit 4 Runtime
   • Description: Eclipse JUnit 4 Runtime
   • Log directory: /home/myuser/semdiff/junit/log
   • Server directory: /home/myuser/semdiff/junit/source
   • Repository connection string: :pserver:anonymous@dev.eclipse.org:/cvsroot/eclipse
   • Repository paths: org.eclipse.jdt.junit4.runtime
   • Date format: yyyy-MM-dd hh:mm:ss Z <The default value already entered>

10. Push on Finish. Select the new repository, Eclipse JUnit4 Runtime, and activate it (the green circle button, or right-click on the repository and select "Set Active Repository").

11. Select the menu SemDiff -> CVS Repository -> Generate RLog. Wait until it is completed.

12. Select the menu SemDiff -> Run Detectors. A dialog will appear. Enter 0:10 and then push OK.

13. Open the Transactions view. Go to Window -> Show View -> Other... -> SemDiff -> Transactions

14. Push on the Goto transaction button (the yellow arrow) and enter 6.

15. You can now see information about the transaction 6. You can also right click on any item to see the source of the versions of the file.

Concepts

There are a few concepts that you need to understand before using SemDiff. Some are general concepts commonly discussed in the software evolution literature, while some other are specific to SemDiff.

• Profile: a profile enables you to define or connect to a set of SemDiff repositories. A profile is typically associated with a database (either local or remote) or a remote SemDiff instance. Local profiles enable you to create and manage your own repositories. Choose this profile type if you wish to perform your own analysis. Remote profiles (not yet supported) enable you to manage a SemDiff instance remotely (client-server architecture with a thin client). Almost no computation is performed on the client machine. Choose this profile type if you wish to perform your own analysis on a remote machine you control. Remote DB profiles enable you to access repositories stored on a remote DB. All computations are performed on the client and you cannot modify the data, but you can perform your own analysis and store the results locally.

• Repository: a SemDiff repository is associated with a source repository (CVS and Subversion are currently supported) and stores all transactions and analysis data. For example, you can have a repository that is associated with the Eclipse CVS server and with the org.eclipse.ui and org.eclipse.jdt.core modules. By default, the SemDiff repository will contain all transactions (change sets) committed in these modules, the files that were changed, the Java elements that were changed, and the method calls that were added and removed in each transaction.

• Transaction: a transaction in SemDiff represents a unit of work in the evolution of a program. It is also called change set in the literature. A transaction contains all files that were committed (added, removed, or modified) together. Because not all version control systems explicitly keep track of files that were committed together (e.g., CVS), SemDiff uses a common strategy to infer the transactions from such systems. A transaction is also the main unit of work for SemDiff: analyses are performed on each transaction and the results are stored in each transaction.

• Detector: a detector in SemDiff is responsible for performing one analysis on transactions. By default, SemDiff ships with two detectors. StructDiff performs syntactic analysis on each file in a transaction and determines which Java elements were changed (e.g., method abc() was modified in file App.java between versions 1.1 and 1.2). CallDiff performs partial static analysis on each file in a transaction and determines which calls were added or removed (e.g., a call to method xyz() was added in version 1.2 of method abc() in file App.java). A detector can depend on an arbitrary number of detectors (cycles are detected and forbidden). For example, CallDiff depends on StructDiff. It is possible to define your own detectors through the detector extension point.

• Call Recommendation: SemDiff was originally created to recommend adaptive changes when a client program broke because of the evolution of a framework or library. If a call to a framework no longer works (e.g., the method no longer exists) and you captured the framework's history in a SemDiff repository, you can ask SemDiff to recommend you equivalent method calls. For example, if you were calling method m1(), which no longer exists, SemDiff might recommend you to call method m1_2() as a replacement. To get a recommendation, just select the method call in the Java Editor, right-click to open the context menu and select SemDiff -> Get Call Recommendations.

• Partial Program Analysis: because SemDiff only retrieves files that were changed together in a transaction, it does not have access to the whole program when performing its analyses. Certain detector, like CallDiff, must perform basic static analysis (e.g., determine the methods that are called), which is usually not possible if the whole program is not available. SemDiff thus relies on a technique, Partial Program Analysis (PPA), which enables static analysis for partial Java programs. Because PPA must be installed for SemDiff to work, you will encounter various options (e.g., menu items) related to PPA. Information about these options are available on the PPA for Eclipse website.

Initializing a Database

To use SemDiff, you need to setup a database that will store the various results computed by SemDiff. SemDiff supports two databases: HSQLDB and PostgreSQL. Once you have selected the database you want to use, you need to initialize it: when selecting the menu option "SemDiff / Init Database", SemDiff creates the appropriate schema (tables, constraints, etc.) in the database.

• HSQLDB. HSQLDB database is bundled with SemDiff so you do not need to install it. To initialize the database, select the menu option "SemDiff / Init Database". Then, enter the following information:

  • Username: sa
  • Password:<Leave it empty>
  • Connection String: jdbc:hsqldb:file:/home/myuser/semdiff/db/hsql;hsqldb.default_table_type=cached
  • Driver: Choose "org.hsqldb.jdbcDriver"
  • Dialect: Choose "org.hibernate.dialect.HSQLDialect"

  /home/myuser/semdiff/db is the path where the database will be located and hsql is the name of the db. You can change them as you like. hsqldb.default_table_type=cached means that HSQLDB will put some of the data in memory and some of the data on the disk. This is the desired behavior since large repositories would probably not fit in your memory. HSQLDB web site contains more information on the options available for JDBC connection strings.

• PostgreSQL. You need to manually install PosgreSQL if you want to use it. In our experience, this database usually provides better performance than HSQLDB for large repositories. We have tested PostgreSQL 8.3 with SemDiff, but previous versions should work too. Before SemDiff can initiale a PostgreSQL database, you must create a database instance. A good tool to do that is pgAdmin. Once you have created a database instance, you can initialize it by selecting the menu option "SemDiff / Init Database". Then, enter the following information:

  • Username: <a valid postgresql username>
  • Password: <your password>
  • Connection String: jdbc:postgresql://localhost:5432/database_name
  • Driver: Choose "org.postgresql.Driver"
  • Dialect: Choose "org.hibernate.dialect.PostgreSQLDialect"

  localhost:5432 is the address of the machine hosting PostgreSQL and database_name is the name of your database instance. PostgreSQL web site contains more information on the options available for JDBC connection strings.

Creating a Profile
How to create a profile. The various types of profiles.

Creating a Repository
How to create a repository. The various types of repositories.

Analyzing a Repository
How to launch the analysis of a repository.

Getting a Recommendation
How to use the recommender.

Creating a Custom Detector
How to create a custom detector.