Developing an Eclipse Plug-in

David Gallardo

Eclipse Overview
Eclipse Platform
Java Development Tools (JDT)

Another Tool Help

Workbench JFace SWT

Team

Your Tool

Plug-in Development Environment (PDE)

Workspace

Debug

Platform Runtime Eclipse Project

Their Tool

The Eclipse JDT and PDE

Plug-in development environment Java development tools

PDE
JDT Platform Java VM

Eclipse Platform
Standard Java2 Virtual Machine

Eclipse Plug-in Architecture

Plug-in - smallest unit of Eclipse function
Big example: HTML editor Small example: Action to create zip files

Extension point - named entity for collecting contributions

Example: extension point for workbench preference UI

Extension - a contribution
Example: specific HTML editor preferences

Eclipse Plug-in Architecture

Each plug-in Contributes to 1 or more extension points Optionally declares new extension points Depends on a set of other plug-ins Contains Java code libraries and other files May export Java-based APIs for downstream plug-ins Lives in its own plug-in subdirectory Details spelled out in the plug-in manifest Manifest declares contributions Code implements contributions and provides API plugin.xml file in root of plug-in subdirectory

Plug-in Manifest
plugin.xml
<plugin = Example Plug-in Tool" class = "com.example.tool.ToolPlugin"> <requires> <import plugin = "org.eclipse.core.resources"/> <import plugin = "org.eclipse.ui"/> </requires> id = com.example.tool" name <runtime> <library name = tool.jar"/> </runtime> <extension point = "org.eclipse.ui.preferencepages"> <page id = "com.example.tool.preferences" icon = "icons/knob.gif" title = Tool Knobs" class = "com.example.tool.ToolPreferenceWizard/> </extension> <extension-point name = Frob Providers id = "com.example.tool.frobProvider"/> </plugin>

Plug-in identification
Other plug-ins needed

Location of plug-ins code Declare contribution this plug-in makes

Declare new extension point open to contributions from other plug-ins

Eclipse Plug-in Architecture

Typical arrangement:
plug-in A extension point P interface I contributes plug-in B

extension

implements

class C

creates, calls Plug-in A Declares extension point P Declares interface I to go with P Plug-in B Implements interface I with its own class C Contributes class C to extension point P Plug-in A instantiates C and calls its I methods

Eclipse Platform Architecture

Eclipse Platform Runtime is micro-kernel All functionality supplied by plug-ins Eclipse Platform Runtime handles start up Discovers plug-ins installed on disk Matches up extensions with extension points Builds global plug-in registry Caches registry on disk for next time

Using the Eclipse PDE

Self-hosted development environment New PDE project wizard creates directory structure and populates Templates for specific types of plug-ins Manifest editor for plugin.xml configuration file
Identify dependencies Add extension points

Run and debug in a separate Eclipse window

Example: A log4j configuration file editor

Should look and work like other editors in Eclipse:
Distinguish and allow editing different types of textcomments and values Provide syntax coloring Provide code assistance (triggered by CtrlSpace and context-sensitive

Creating the plug-in project and extension point

Create new project Create the main text editor class Define the extension point in the manifest file and associate it with the editor class Add icon Run to see default editor behavior

A sample log4j.properties file

# Logger log4j.rootLogger=DEBUG, ConApp # Appender log4j.appender.ConApp=org.apache.log4j.ConsoleAppender # PatternLayout log4j.appender.ConApp.layout=org.apache.log4j.PatternLayout log4j.appender.ConApp.layout.ConversionPattern=%d [%t] %-5p %c - %m%n

Working with text

Differentiate between sections of text by providing a rule-base partition scanner:
Comments Values Everything else

Eclipse provides base classes for rule-based scanning, which well extend to support log4j syntax

Working with tokens

For each partition type, you need to provide a token scanner:
CommentScanner ValueScanner DefaultScanner

You also need to provide a token manager to track tokens and their colors
Support user-preferences Track colorsIn SWT, you need to dispose of resources you create

Add content assist

Provide a content assist processor for each partition that require content assist (also known as code completion) Return list of possible completions Define character that trigger content assist automatically

Connect to the backing file

Eclipse provides an interface IDocumentthat represents the document Assigns a partition scanner to the document And, conversely, assigns the document to the partition scanner JFace class FileDocumentProvider does most of the work

Bringing it all back home

The SourceViewerConfiguration class ties everything together:
Determines partition types, default partition Set up the partitions Provide damagers and repairers for each partion Turn on content assist

Finishing touches: The editor class

Now we can finish the editor class we started with:
Plug in the source configuration Plug in document provider Attach to Eclipse preference store Handle calls to redraw text when necessary Handle calls to update preferences Plug in content assist as a retargetable action

Demo
Import example source Walk through source code demonstrating the components previously described Run and demonstrate:
New Eclipse Menu item Default editor for log4j.properties Syntax coloring Content assist