Creating your first eclipse plugin

I recently had to write a plugin for eclipse, which needed the ability to run a pattern match on console output. This was the first time I was developing plugins for eclipse so I was pretty clueless as to where to start.

I couldn’t find a tutorial online which was focused specifically on this (or maybe I am really bad at search), so I’m writing one myself.

Note: By no means this a complete tutorial, I’m just presenting my development experience here.

Step 1 : First things first, Install PDE

You have to install PDE (Plugin Development Environment) in order to create plugins for eclipse.

If you have already done this, you can skip over to step 2

Open Eclispe IDE

Go to Help > Install New Software

In the install window, select The Eclipse Project Updates from the work with field.

In the list, select Eclipse Plugin Development Tools

Proceed with the license terms and click Finish.

Step 2: Creating a plugin project from a template

Create a plugin project

Create a new plugin project

Give some name for your project, I’m naming it my_first_plugin

Use the Hello, World Command template, click Finish

Template selection

Then eclipse will show a popup regarding the plugin Development perspective, click Yes.

Now you will be presented with a overview tab in the editor, which looks something like this

The overview tab

The overview tab is where you can add dependencies, extensions, extension points etc.

Now we are done setting up our project

Step 3 : The coding part

Project Explorer

Now let’s just run this and see what we’re getting

Right click on your project and choose run as Eclipse Application

Now we will be getting another eclipse window open, this is where we test our plugin in development.

Eclipse where we test our plugin

Now, in the toolbar, you can find this button with the eclipse icon

button

Click on it and we will get a message box

That’s our plugin for now, all it does is to create a message box which shows some text.

Let’s see how we can modify it to do something useful.

Activator.java

As we can see in the inline comments, the Activator class is used for controlling the lifecycle of our plugin.

The start method can be used for initialisations, akin to a constructor for a class, and the stop method can be used to clean up .

SampleHandler.java

from this code, we can understand that execute method contains the event handling code.

What do we want to do ?

Let’s make a plugin that will report the number of matches it finds in the console for a particular regular expression.

In order to make that, first we need to accomplish the following sub tasks

1. A way to access the console
2. A way to run pattern match on the console data
3. A way to display the result (Number of matches)

The third step can be ignored, since we already have a working message box, which could be tweaked accordingly. So now we are left with 2 sub tasks,

Sub Task 1 — Accessing the console

When we start the eclipse IDE, we might not have a console window open, in most cases a console window appears only when we run a project, hence we need to listen for consoles which are added or removed, that’s where the IConsoleListener Interface comes in,

org.eclipse.ui.console.IConsoleListener interface provides methods consolesAdded and consolesRemoved with an IConsole[] parameter which contains the console(s) that are added or removed.

When we try to implement IConsoleListener, eclipse will show an error stating that

IConsoleListener class cannot be resolved to a type

This is because we haven’t added the dependency yet, so let’s go ahead and add it.

In the overview, under dependencies tab, under Required plug-ins, click on Add

provide org.eclipse.ui.console in the field and click ok

We can see the dependency in the required plug-ins, don’t forget to save your project after this step.

Back to our code,

As we have added the dependency, we can now import the classes in org.eclipse.ui.console without any problems.

In the consolesAdded method, we have the list of consoles as an IConsole array (IConsole[]), Eclipse has different types of consoles, the one we are interested in is the TextConsole, so we need to filter the consoles to obtain only the TextConsoles

@Override
public void consolesAdded(IConsole[] consoles) 
{  
    for(IConsole console : consoles) {   
        if(console instanceof TextConsole) {
            ((TextConsole) console).addPatternMatchListener(this);
        }  
    } 
}

Only TextConsole class provides the addPatternMatchListener method.

Sub Task 2 — Pattern Matching on the console

We have to implement the IPatternMatchListener interface,

The getPattern method is used to provide the pattern which is to be used for matching

@Override
public String getPattern() {
    return pattern; 
}

When a match is found, the matchFound method is invoked, where we increment a counter.

@Override
public void matchFound(PatternMatchEvent arg0) {  
    this.matchCount++; 
}

Sub Task 3 — Viewing the results

Edit the message dialog to display the count

public Object execute(ExecutionEvent event) throws ExecutionException {  
    IWorkbenchWindow window =
        HandlerUtil.getActiveWorkbenchWindowChecked(event);
    MessageDialog.openInformation(window.getShell(), "Matches",
        this.matchCount + " matches found");
    return null;
}

After adding these methods, the code looks something like this.

Testing the plugin

Now that we have completed all our sub tasks, it’s time to run it

Run the project as an eclipse application, in the new eclipse window create a new java project and add a class to it, I have added the following sample code

for(int i=0; i<5; i++) {
    System.out.println(" blah "+i);
}

Before running this Java project, click on the plugin button once, (more on this later)

Run the java project and now if we click on the plugin button, we will get our output

Let’s try to understand the working of this program,

Before running the java project, we first click on the plugin button once, when we do this, the SampleHandler constructor gets called, which will register the console listener (IConsoleListener), Whenever a console is created in the Eclipse UI, SampleHandler will be notified via the addConsoles method.

When we run the java project, the following happens

1. A console is created in the eclipse UI to display the output of the java project
2. addConsoles method is notified of this new console, since it is an instance of TextConsole, a pattern match listener (IPatternMatchListener) is registered for this new console.
3. The pattern match listener now processes the data in the console to check for matches (remember, the pattern is obtained from getPattern).
4. If matches are found, we are notified via matchFound method, where we are incrementing the counter, hence for each match the counter value increments by one.
5. If we click on the plugin button, execute method gets notified, where we fire up a MessageDialog displaying the result.

Problems

You could have spotted a few problems with this implementation, of course it’s not perfect as of now, there are a couple of problems, they are left there intentionally and for you to solve

1. The counter value is never reset, this could be a problem when you run your java project multiple times.
2. Before running our project, we need to initialize our plugin by clicking on it once.

How would you overcome these problems ? Do let me know via the comments

You can find the full source code here

Happy coding :)