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
