Monday, September 13, 2010

The experience of creating an Eclipse refactoring (part 2)

The Last time around I commented on my motivation of learning about Eclipse plugins and specially the JDT and gave a small overview of the classes involved in a refactoring. In this post a I'll talk about the plugin's metadata and the classes that eventually launch the refactoring. I'll leave the implementation of the refactoring itself for the next post.

One thing that I forgot to mention in my previous post is that I'm working with Eclipse Helios (3.6).

The version of the code I used for this post can be downloaded here.

The refactoring that I'm presenting is called 'To Final' and adds the final modifier to private fields that are initialized inline and are not modified in the scope of the class. As I already mentioned my Refactoring is based on the article Unleashing The Power of Refactoring. The article is a little old now (4 years) but It's a comprehensive guide that will take you step by step. Just a word of caution before you get started, The refactoring explained there is 'Introduce Indirection' and is already present in recent eclipse versions. You might want to change its name to avoid confusions and second it uses Actions instead of the newer Commands framework to get the refactoring code started.

I'm going to walk through the metadata of my plugin and some code while commenting about the things I found important to remember. Let's get started


One thing that I found a little frustrating was the fact that I couldn't find a place where you can search which class is provided by which bundle. In other words if somehow I ran into a class that didn't belong to the dependencies that I already had in place I had to google for the package to which that class belongs to find the bundle that exported the given package.

In the previous version of the Manifest I had an import package for org.eclipse.jdt.core.refactoring. That happened when I answered yes to a Quick fix that recommended adding the import package line in the Manifest. Which leads me to ask the following question:
When should I use require-bundle and when import-package?.


In this plugin several extension points are being used let's go one by one.

Although is technically true that I'm adding a refactoring Contribution, I haven't done anything yet other then adding a class with a default implementation of the methods needed to compile. So nothing special here. I need to dig deeper in the History/Scripting deal and make sense of the Refactoring Contribution and Descriptor use. That's left for a future post.

I replaced the Action based implementation of the original plugin with the newer commands api. The command declares a sort of abstract action that may be invoked by the UI. In this particular case the command defined corresponds to the execution of the refactoring. As you can see there's no reference to a class because the command itself is only a placeholder for a set of behaviors. Each behavior is implemented by a Handler.

Each handler is responsible of the execution of a Command's behavior. Only one handler is active at a time and that is achieved by the use of conditions. For example in my plugin that sole handler that I have defined only is active if the current selection is an instance of whether an ITextSelection or a StructuredSelection. One thing I had a hard time understanding is the fact that the variables used by the with tag are predefined by the workbench.

Here's where the menu that starts the refactoring is defined. It took me a lot of time to get the menu to show up. I'm not sure why it didn't work at the beginning because I ended up taking this configuration from a working sample. I don't if it was me or in fact there's a problem reporting issues when a menu cannot be shown because while I was struggling with the menu not showing up I didn't see anything useful in the log.
I little thing you should know about is the locationURI attribute that defines where your menu is going to be placed.

The Classes

If you want to write your own refactoring. One that's started from the menu. You'll need an implementation of the RefactoringWizard. Let me try to explain how to get the refactoring code running :
  1. The menu 'My Refactorings/To Final...' dispatches the commmand
  2. The command itself is a placeholder for a set of handlers. The active handler is executed. In this particular case there's only one: ''
  3. The handler starts the Refactoring Wizard
  4. The Wizard executes the different steps that comprise the refactoring


ToFinalCmdHandler inherits from AbstractHandler.
When the 'To Final...' option under the 'My Refactorings' menu is clicked, the handler ToFinalCmdHandler is run and its entry point is the execute method.
In this method I update the data needed to create the refactoring instance using the current selection. Because the conditions that enable the handler require an active selection I can safely assume that there's one. Once the data is updated I launch the wizard with my newly created refactoring instance. I'll leave the implementation details for a future post where I'll talk about manipulating and transforming code using the JDT.


As I mentioned in the previous post in this series my Wizard is really dumb because it doesn't add any input page. Remember this refactoring eventually will become a QuickFix. The only thing to note here is that it receives an instance of ToFinalRefactoring (my refactoring). This is the glue that binds my refactoring to Eclipse's refactoring engine.

When I first started working with Eclipse the configuration part was the hardest for me. Maybe because I didn't take the time to read how the plugin model works or because I'm new to OSGI. Or is just the learning curve. Once I got to the point where everything showed up and got started the implementation of the refactoring was relatively easy. But will talk about that in a later post.

Sunday, July 25, 2010

The experience of creating an Eclipse refactoring

A long ago I started investigating on developing new Refactorings for Eclipse. I started with a lot enthusiasm, a cup of coffee and my Linux box. First things first, I downloaded the SDK version of Eclipse. Then I started browsing the net looking for resources beside the official documentation and the code itself. I was shocked when I found out that not only there wasn't a lot of resources, they barely exist!. I can list all the resources I found right here:
That was like 2 years ago but the outlook is not very different now.  At the beginning I thought that there must be a big community of developers creating language processing tools for automating some of their stuff with JDT.  I guess I was wrong or I'm not that good at googling.

In this post I'll talk  about how I got started and I'll introduce the main components of a refactoring in eclipse in a very concise way. I want this post to be more like an entry point for someone who wants to start exploring the JDT/LTK SDK and is a little lost like I was at the time.

Originally my intention was to create a set of refactorings to promote functional programming practices in java.  First I would try to add a Quick Fix to add the final modifier to private fields that are not changed inside the class in an attemp to promote unmutable objects. I hadn't developed in java for a while and I forgot that the final modifier in java works differently then C#'s readonly which was what I had in mind when I thought of the Quick Fix. But I proceeded anyway.

Because most of the resources I had found were related to refactoring I decided to start by implementing a refactoring named 'To Final" and after that, move it to a Quick fix.

 This was my plan of action:
  1. Create the project using the wizard
  2. Invoke a dummy refactoring
  3. From that point start building the core functionality.

Creating The Project.

This is an easy one. Eclipse has a bunch template projects to get started with the SDK. I started with the good old Hello World.

The Dummy Refactoring

Turns out a Dummy Refactoring is not so Dummy after all. There are two approaches on how to build refactorings.

The old-school way
It can be done using set of classes that work together to get the job done:

This class is responsible for providing all the pages (forms) for user input, also provides the preview and an error page.

This class provides a way to create refactorings for scripting and history. I didn't use it. Because of that my plugin cannot be used in scripts.
 This is the meaty part. This class is responsible of validating that the refactoring can be performed and return an object that describes the set of changes required to complete the refactoring. The aforementioned object is an instance of the class Change that is used to generate the preview and if the changes are accepted is used to perform the actual changes in the source code.

As far as I know the RefactoringDescriptor is used with the RefactoringContribution to automate refactoring executions. In my case I ignored this one too.

Refactoring the new way
The other way to include refactorings is by The use of processors and participants. This model of adding refactorings adds the flexibility of binding partincipants to the original refactoring. It can be seen as additional tasks that the refactoring needs to execute that can exist outside of the scope of the JDT. In fact is not a new way of creating refactorings. It's an extension to the original API.

What I did in the end
I based my refactoring on the resources from the article Unleashing the Power of Refactoring. Which is based in the old-school approach.  I tried to code everything myself but I have to confess I had to go to look in the resources more times than I'd like to admit.

The core functionality

I want to leave this part to my next instalment. I'll talk about the road blocks I found during the implementation of my plugin and how I implemented it.