A plug-in directory typically contains an XML extension point schema definition (.exsd) file in a schema subdirectory. The XML schema documents the elements, attributes, and types used by the extension point. The Eclipse PDE uses this information to describe the elements and attributes in the property editors and other facilities of the Eclipse platform.

You use the Eclipse PDE to develop the plug-in content, test, and deploy a plug-in. The Eclipse PDE automatically generates the plugin.xml, build.properties, and run-time archive files.

The file, $INSTALL_DIReclipsepluginsorg.eclipse.birt.report.designer.uischema eportitemUI.exsd, documents the settings for a report item extension to the BIRT Report Designer user interface. The XML schema file, reportitemUI.exsd, has the following structure:

Listing 16-1 is a partial schema example showing reportitemUI.exsd. The ellipses (...) mark the places in the code where lines are omitted.

<?xml version='1.0' encoding='UTF-8'?>
<!-- Schema file written by PDE -->
<schema targetNamespace="org.eclipse.birt.report.designer.ui">
   <annotation>
      <appInfo>
         <meta.schema
           plugin="org.eclipse.birt.report.designer.ui"
           id="reportitemUI"
           name="Report Item UI Extension Point"/>
      </appInfo>
      <documentation>
         This extension point is used in conjunction with the
         Report Item extension point defined in the model. It
         is used to register the GUI to be used for the
         Extended report item.
      </documentation>
   </annotation>
   <element name="extension">
      <complexType>
         <sequence>
            ...
            <element ref="model"/>
            <element ref="builder" minOccurs="0" maxOccurs="1"/>
            <element ref="propertyPage" minOccurs="0"
               maxOccurs="1"/>
            <element ref="palette" minOccurs="0" maxOccurs="1"/>
            <element ref="editor" minOccurs="0" maxOccurs="1"/>
            <element ref="outline" minOccurs="0" maxOccurs="1"/>
            <element ref="description" minOccurs="0"
               maxOccurs="1"/>
         </sequence>
         <attribute name="point" type="string" use="required">
            ...
         </attribute>
      </complexType>
   </element>
   <element name="model">
      <complexType>
         <attribute name="extensionName" type="string"
            use="required">
            <annotation>
               <documentation>
                  The ROM Report Item Extension name that maps
                  to this UI
               </documentation>
            </annotation>
         </attribute>
      </complexType>
   </element>
   ...
   <element name="builder">
      <annotation>
         <documentation>
            Optional Builder for the element inside the Editor.
            Instantiated when a new item is dragged from the
            palette inside the editor.
         </documentation>
      </annotation>
      <complexType>
         <attribute name="class" type="string">
            <annotation>
               <documentation>
                  a fully qualified name of the Java class
                  implementing org.eclipse.birt.report
                  .designer.ui.extensions.IReportItemBuilderUI
               </documentation>
               <appInfo>
                  <meta.attribute kind="java"/>
               </appInfo>
            </annotation>
         </attribute>
      </complexType>
   </element>
   ...
</schema>

You install an Eclipse plug-in in a subdirectory of the $INSTALL_DIR/eclipse/ plugins directory. The plug-in manifest file, plugin.xml, describes the plug-in’s activation framework to the Eclipse run-time environment.

At run time, Eclipse scans the subdirectories in $INSTALL_DIR/eclipse/plugins, parses the contents of each plug-in manifest file, and caches the information in the plug-in registry. If the Eclipse run time requires an extension, Eclipse lazily loads the plug-in, using the registry information to instantiate the plug-in’s objects. The run-time environment for the BIRT Report Engine functions in a similar way.

The plug-in manifest file declares the plug-in’s required code and extension points to the plug-in registry. The plug-in run-time class provides the code segment. By lazily loading the plug-in’s code segment, the run-time environment minimizes start-up time and conserves memory resources.

The plug-in manifest file, plugin.xml, has the following structure:

Listing 16-2 shows the contents of the plug-in manifest file, org.eclipse.birt.sample.reportitem.rotatedlabelplugin.xml. This file describes the required classes and extension points for the BIRT report item extension sample, rotated label.

   <?xml version="1.0" encoding="UTF-8"?>
   <?eclipse version="3.2"?>
   <plugin>
      <extension
         id="rotatedLabel"
         name="Rotated Label Extension"
         point="org.eclipse.birt.report.designer.ui
            .reportitemUI">
         <reportItemLabelUI
            class="org.eclipse.birt.sample.reportitem
               .rotatedlabel.RotatedLabelUI"/>
         <model extensionName="RotatedLabel"/>
         <palette icon="icons/rotatedlabel.jpg"/>
         <editor
            canResize="true"
            showInDesigner="true"
            showInMasterPage="true"/>
         <outline icon="icons/rotatedlabel.jpg"/>
         <propertyPage
            class="org.eclipse.birt.sample.reportitem
               .rotatedlabel.RotatedLabelPropertyEditUIImpl"/>
   </extension>
   <extension
      id="rotatedLabel"
      name="Rotated Label Extension"
      point="org.eclipse.birt.report.model.reportItemModel">
      <reportItem
         class="org.eclipse.birt.sample.reportitem
            .rotatedlabel.RotatedLabelItemFactoryImpl"
         extensionName="RotatedLabel">
         <property
            defaultDisplayName="Rotation Angle"
            defaultValue="-45"
            name="rotationAngle"
            type="integer"/>
         <property
            defaultDisplayName="Display Text"
            defaultValue="Rotated Label"
            name="displayText"
            type="string"/>
      </reportItem>
   </extension>
   <extension
      id="rotatedLabel"
      name="Rotated Label Extension
      point="org.eclipse.birt.report.engine.reportitem
         Presentation">
      <reportItem
         class="org.eclipse.birt.sample.reportitem.rotated
            label.RotatedLabelPresentationImpl"
         name="RotatedLabel"/>
   </extension>
</plugin>

A plug-in runs within an instance of a plug-in run-time class. A plug-in run-time class extends org.eclipse.core.runtime.Plugin, the abstract superclass for all plug-in run-time class implementations. The Plugin run-time class defines the methods for starting, managing, and stopping a plug-in instance.

The Plugin run-time class typically contains a reference to an Open Services Gateway Initiative (OSGi) resource bundle that manages the execution context. Plugin implements the interface, org.osgi.framework.BundleActivator, which installs, starts, stops, and uninstalls the OSGi resource bundle. The OSGi resource bundle implements a service registry to support the following services:

The OSGi platform provides a secure, managed, extensible Java framework for deploying, downloading, and managing service applications. For more information about the OSGi platform, visit the OSGi Alliance web site at http://www.osgi.org/. For more information about the Java run-time and OSGi APIs, see the reference documentation for the Platform Plug-in Developer Guide in Eclipse Help.

Listing 16-3 is a code example showing the life-cycle and resource bundle methods for the report item plug-in, rotated label.

package org.eclipse.birt.sample.reportitem.rotatedlabel;

import org.eclipse.core.runtime.Plugin;
import org.osgi.framework.BundleContext;
import java.util.*;

/**
 * The main plugin class to be used in the desktop.
 */
public class RotatedLabelPlugin extends Plugin {
   // The Plugin ID
   public final static String ID =
      "org.eclipse.birt.sample.reportitem.rotatedlabel";
   //The shared instance.
   private static RotatedLabelPlugin plugin;
   //Resource bundle.
   private ResourceBundle resourceBundle;

   /**
    * The constructor.
    */
   public RotatedLabelPlugin() {
      super();
      plugin = this;
      try {
         resourceBundle = ResourceBundle.getBundle
            ("org.eclipse.birt.sample.reportitem.rotatedlabel
               .RotatedLabelPluginResources" );
      } catch (MissingResourceException x) {
         resourceBundle = null;
      }
   }
   /**
    * This method is called upon plug-in activation
    */
   public void start(BundleContext context) throws Exception {
      super.start(context);
   }

   /**
    * This method is called when the plug-in is stopped
    */
   public void stop(BundleContext context) throws Exception {
      super.stop(context);
   }

   /**
    * Returns the shared instance.
    */
   public static RotatedLabelPlugin getDefault() {
      return plugin;
   }

   /**
    * Returns the string from the plugin's resource bundle,
    * or 'key' if not found.
    */
   public static String getResourceString(String key) {
      ResourceBundle bundle =
         RotatedLabelPlugin.getDefault().getResourceBundle();
      try {
         return (bundle != null) ? bundle.getString(key) : key;
      } catch (MissingResourceException e) {
         return key;
      }
   }

   /**
    * Returns the plugin's resource bundle,
    */
   public ResourceBundle getResourceBundle() {
      return resourceBundle;
   }
}

Using the New Plug-in Project wizard, you can define the following properties for the plug-in:

In Eclipse 3.2, opting to create an OSGi bundle manifest, MANIFEST.MF, offers significant advantages. The OSGi bundle manifest, META-INF/MANIFEST.MF, contains a set of manifest headers that provide descriptive information about a bundle.

Eclipse 3.2 uses an implementation of the OSGi R4 framework specification. This framework defines the directives that specify the access rules for an exported package and the headers that facilitate class loading, start-up time, filtering, and other features.

BIRT release 2.1 uses the OSGi framework that comes with the Eclipse 3.2 platform. You must implement any plug-in that extends a BIRT release 2.1 extension point as an OSGi bundle.

Inside the Eclipse environment, you can develop and deploy a plug-in for BIRT Report Designer. Outside of the Eclipse environment, you can develop and deploy a plug-in for BIRT Web Viewer. BIRT Web Viewer is a J2EE web application consisting of servlets and JSPs that encapsulates the BIRT Report Engine API to generate reports.

The Eclipse PDE supports host and run-time instances of the workbench project. The host instance provides the development environment. The run-time instance allows you to launch a plug-in to test it.

Figure 16-4 shows the project for the report item extension sample, rotated label, in the host instance of the PDE Workbench. In the host instance, the PDE Workbench provides the following view and editor components:

In PDE Manifest Editor, you specify project settings and edit related files to create the plug-in framework on the following pages:

A modification to a setting in a PDE Manifest Editor page automatically updates the corresponding plug-in manifest or build properties file.

The Eclipse PDE can generate an Ant build script for compiling plug-in code, based on the settings in the build.properties file. The generated script is an XML file in which the elements are the required tasks for the build operation. The Ant build tool compiles the project, using the specified Java compiler.

Ant is an open source Java application available from the Apache Software Foundation. For more information on Ant and the Apache Software Foundation, visit the web site at http://ant.apache.org.

How to generate an Ant build script

In Package Explorer, right-click the project’s plugin.xml file and choose PDE Tools →Create Ant Build File. PDE Tools creates an Ant script file, build.xml, in the project folder.

You can launch an instance of the run-time workbench to test and debug the plug-in extension.

How to launch a run-time workbench

If all the dependent resources are available in the new environment, Eclipse can discover and activate the plug-in in the run-time environment. In this type of unmanaged distribution and installation, the user must find and install updates to the plug-in if a release occurs in the future.

A plug-in developer can also use a more structured approach and group plug-ins into features. A feature is a set of plug-ins that you install and manage together.

Features contain information that allow the Feature Updates and Product Configuration managers to locate published updates and discover new related features. Updates are typically published in a special internet directory called an update site, created and managed by a plug-in developer using the Update Site Editor.

How to install feature updates and manage the Eclipse configuration

The Eclipse PDE provides wizards and editors that support the use of features and update sites. Choose Help →Software Updates → Find and Install to access Feature Updates. Feature Updates allows you to search for updates and new features, as shown in Figure 16-26.

Figure 16-26. Searching for feature updates

Choose Help →Software Updates →Manage Configuration to access Product Configuration. Figure 16-27 shows Product Configuration.

Figure 16-27. Product Configuration

Product Configuration allows you to perform the following tasks:

You create an update site by building an update site project in the Eclipse PDE workspace. The update site project contains a manifest file, site.xml, that lists the features and plug-ins packages.

The build operation for an update site puts the JAR files for features in a features folder and the JAR files for plug-ins in a plug-ins folder. The Eclipse PDE also provides support for uploading an update site to a remote server or local file system for distribution.

How to create an update site project

For more information about deploying a plug-in, installing features, managing a product configuration, and building an update site, see the documentation for the Platform Plug-in Developer Guide in Eclipse Help.