ONJava.com -- The Independent Source for Enterprise Java
oreilly.comSafari Books Online.Conferences.

advertisement

AddThis Social Bookmark Button

Develop Your Own Plugins for Eclipse, Part 1 Develop Your Own Plugins for Eclipse, Part 1

by Jérôme Molière
08/18/2004

Eclipse is a nice IDE, of course, but it's arguably the best platform for hosting your own applications. Using Eclipse facilities spares you from re-coding, for the 100th time, a framework for dealing with online help, generating wizards, or saving a file to disk. Eclipse ships with many helpful features, such as a Lucene-ready engine for searching your help documentation. Like any object-oriented developer, you don't want to reinvent the wheel.

This article series is intended provide you the basic information necessary to quickly code your first plugin. The resources section will point to all of the necessary introductory materials. This first installment will introduce the application to be delivered, all of the vocabulary required, and will explain how to package your plugins. Please note that we'll use the term ${eclipse.home} to indicate the Eclipse home directory; i.e., the directory where eclipse.exe or the eclipse.sh file lives.

Configuring Your Servlet Engine in a Nutshell

Have you ever tried to configure Tomcat or Jetty? Have you ever compared Tomcat 4 and Tomcat 5 configuration files? It's a nightmare, and it forces you to take the documentation and track each parameter to check if there's a default value, what it is, ask yourself, "Why did I change the default?", etc. So we'll have a look at what may become your everyday friend: a small application aimed to quickly generate robust configuration files for your servlet container. Of course, production-ready servers and development engines don't all have the same constraints, so short of using black magic, how could this software generate the right file for the right usage? Asking you will be the key -- this application will be crafted as a wizard guiding you through the generation process. Figure 1 shows the welcome screen of this plugin. This small application is simple enough to be studied here, while exposing some interesting aspects of Eclipse coding practices.

Figure 1
Figure 1. The config file wizard plugin

Delivering Plugins to the Platform

Before going into further detail, let's fix the vocabulary with regards to coding with the Eclipse platform. While delivering a plugin, you act as a contributor, that is to say you extend the product features with your own work. This is the main principle of the Eclipse internals, where everything is a plugin. To clarify: everything but a small part from the Eclipse code is a plugin -- this small part is called the core and aims to offer the facilities required to launch the product and instantiate the plugins fetched. Figure 2 provides a basic idea of the Eclipse internal structure.

Figure 2
Figure 2. Eclipse internals overview

This figure is a simplified view of what's embedded in the default Eclipse package. For a real idea on what plugins are available at load time, please refer to the ${eclipse.home}/plugins directory. Figure 3 shows the contents from this directory as shipped in Eclipse 3.OM9.

Figure 3
Figure 3. Contents of the plugins directory

Strange, isn't it? A huge series of directories with names like Java packages. So we know now that any application must be delivered to the plugins directory, and that any plugin is contained in a directory named using a dot-based convention. We must now understand how this directory is composed.

Plugins and Metadata

What is the structure of these directories? Using a simple metaphor in the Java world, plugins are deployed in the Eclipse framework in a similar manner to web apps or EJBs in the J2EE world. That is to say, this .zip file will contain your code (if code is necessary) and resources (any config files, help content, images, etc.). All of this stuff must be properly organized in order for the core framework to be able to retrieve and load your plugin. This is where the magic of XML comes into play. XML metadata will be used for declaring what is in your plugin. This metadata is stored in the root directory of each plugin, in a file called plugin.xml. Using the default plugins shipped with Eclipse, we can examine such files, so let's have a look at the plugin that brings Lucene into the Eclipse framework:

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.0"?>
<plugin
   id="org.apache.lucene"
   name="%lucene_plugin_name"
   version="1.3.0.RC2"
   provider-name="%providerName">

   <runtime>
      <library name="parser.jar">
         <export name="*"/>
         <packages
         prefixes="org.apache.lucene.demo.html"/>
      </library>
      <library name="lucene-1.3-rc2.jar">
         <export name="*"/>
         <packages
         prefixes="org.apache.lucene"/>
      </library>
   </runtime>
</plugin>

This file declares a plugin (the tag plugin) for the Eclipse platform version 3. (Note that this is not an Eclipse-specific feature, but a common XML way to deal with technical plumbing meant to be seen by the XML processor.) The plugin attributes define a unique identifier, a name, a version, and the provider (the Eclipse team, you or anybody else). Then a runtime section is used to declare the libraries necessary for the getting the plugin to work. In this example, two libraries are required to have a functional Lucene plugin.

If you have ever added plugins to the Eclipse platform, you've probably seen that some plugins add entries to the contextual menus (right-click), while others add new views or perspectives. The plugin.xml file is the point where you'll provide information regarding what kind of extension your plugin will provide. A plugin can bring new features to your Eclipse platform while adding resources for any extension point. Eclipse define some extension points, such as menus, wizards, views, and perspectives. This is where the beauty of this product really shows: every item seen in the Eclipse user interface can be fully customized. Our future example will show how to declare that our application adds some entries to the Eclipse platform. But now, let's have a look at the simplest plugin that can be.

The First Dummy Plugin

I can't conclude this first article without giving you a little more to whet your appetite, so we'll try to make a simple first plugin. But please don't be too impatient, and don't expect much more from this plugin than being able to be loaded by the Eclipse platform. Using the following plugin.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.0"?>
<plugin
   id="com.javaxpert.eclipse.plugins.dummy"
   name="%plugin_name"
   version="1.0.0"
   provider-name="%providerName">

   <runtime>
      <library >
      </library>
      <requires/>
   </runtime>

</plugin>

and the following properties file (plugin.properties):

plugin_name=My first plugin
providerName=J.MOLIERE

you should be able to see your plugin loaded in the Eclipse platform (after stopping and restarting Eclipse) in the plugin-details info page available through the About menu. Figure 4 shows the About dialog box (plugins section) for Eclipse 3M9 with our plugin loaded.

Figure 4
Figure 4. Our dummy plugin in the Eclipse's About box

I can't conclude before giving some clues for understanding the plugin.xml file. This XML metadata declares a plugin with an identified name, and since it doesn't provide a new API to the platform, its library tag is empty. It also doesn't require any other plugin to work, so the requires tag is empty. The next article will show a more realistic plugin that requires other plugins to be loaded.

Conclusion

This is the end for this quick start with Eclipse plugin development. Now we have the basics; the next article will enter with a real plugin into the details of coding. Happy coding.

Jérôme Molière works as a software consultant for his own company, Mentor/J, and is the author of Java - 2 Conception et déploiement J2EE


Return to ONJava.com.