Feature

The Eclipse platform is an Open Source, integrated system of application development tools that you implement and extend using a plug-in interface. Eclipse provides a set of core plug-ins that configures the basic services for the platform's framework. A platform developer can build and integrate new tools in this application development system.

Business Intelligence Reporting Tool (BIRT) is a set of plug-in extensions that lets a developer add reporting functionality to an application. The APIs in BIRT define extension points that let the developer add custom functionality to the BIRT framework.

This article describes how to create a BIRT extension using the Eclipse Plug-in Development Environment (PDE). The example adds a custom report item, RotatedLabel, to the BIRT Report Designer Palette that a report developer can drag-and-drop into a report design, as shown in Figure 1.

The sample code for the plug-in creates a label in the runtime report that renders text at a specified angle. Figure 2 shows the display text rotated at an angle of 45 degrees.

A developer uses the Eclipse PDE to create, develop, test, debug, and deploy a plug-in. The Eclipse PDE supports host and runtime instances of the workbench project. The host instance provides the development environment. The runtime instance lets you launch a plug-in to test it.

To implement the report item extension, the plug-in developer does the following tasks:

• Configures the plug-in project in the Eclipse PDE
• Adds the report item to the Report Designer Palette using the report item UI extension point.
• Adds the report item definition to the Report Object Model (ROM) using the report item model extension point.
• Adds rendering behavior to the report item using the report item presentation extension point.
• Deploys the report item extension to the Eclipse plug-in environment

An Eclipse plug-in implements the following components:

• Plug-in manifest - An XML document that describes the plug-in's activation framework to the Eclipse runtime environment
• Plug-in runtime class - A Java class that defines the methods for starting, managing, and stopping a plug-in instance
• Extension-point schema definition - An XML document that specifies a grammar that you must follow when defining the elements of a plug-in extension in the Eclipse PDE

In the Eclipse PDE Workbench, the developer can create the framework for a plug-in extension by using the Manifest Editor to generate the plug-in manifest and class templates based on the definitions in the extension-point schemas.

In the Eclipse PDE, create a new project for the rotated label report item extension by choosing File->New->Project and selecting the Plug-in Project wizard. In Plug-in Project, modify the settings, as shown in Table 1.

In Plug-in Content, modify the settings, as shown in Table 2.

Figure 3 shows the host instance of the Eclipse PDE with the rotated label report item extension project open in the Manifest Editor.

After defining the plug-in project, specify the list of plug-ins that must be available on the classpath of the rotated label report item extension to compile and run. On PDE Manifest Editor, choose Dependencies. In Required Plug-ins, remove the following plug-ins:

• org.eclipse.ui
• org.eclipse.core.runtime
  Choose Add. Plug-in Selection appears. In Plug-in Selection, select the following plug-ins:
  
• org.eclipse.emf.ecore
• org.eclipse.birt.report.designer.ui
• org.eclipse.birt.report.model
• org.eclipse.draw2d
• org.eclipse.birt.report.engine
• org.eclipse.jface.text
• org.eclipse.core.runtime
• org.eclipse.birt.core
• org.eclipse.ui
• org.eclipse.birt.core.ui

The order of the list determines the sequence in which a plug-in loads at runtime. Use Up and Down to change the loading order as necessary. The rotated label report item extension doesn't need any changes to the loading order if you select the required plug-ins in the order listed in the previous step.

On PDE Manifest Editor, choose Extensions. On Extensions, declare the extension points required to implement the rotated label report item plug-in and add the extension element details. The Eclipse PDE uses the XML schema defined for each extension point to provide the list of valid attributes and values specified for the extension elements.

To add an extension point, choose Add. New Extension appears. In Available extension points, select the plug-in that contains the extension point.

The rotated label report item extension implements the following extension points:

• org.eclipse.birt.report.designer.ui.reportitemUI registers the graphical user interface (GUI) to use for the report item extension
• org.eclipse.birt.report.model.reportItemModel specifies how to represent and persist the report item extension in the Report Object Model (ROM)
• org.eclipse.birt.report.engine.reportitemPresentation specifies how to instantiate, process, and render the report item extension

To add an extension point element right-click on an extension point such as org.eclipse.birt.report.designer.ui.reportItemLabelUI. Choose New <extension point element> to add the extension element to the project. Figure 4 shows how to select the extension point element, report-ItemLabelUI, specified by the extension point, org.eclipse.birt.report.designer.ui.reportitemUI.

An XML schema specifies the following properties that identify each extension point in the runtime environment:

• ID - Optional identifier of the extension instance
• Name - Optional name of the extension instance
• Point - Fully qualified identifier of the extension point

On Extensions, these settings appear in Extension Details when an extension point is selected as shown in Figure 4.

The extension point, org.eclipse.birt.report.designer.ui.reportitemUI, specifies the following extension elements:

• reportItemLabelUI - The fully qualified name of the Java class that gets the display text for the report item component in the BIRT Report Designer
• model - ROM report item extension name that maps to this UI component
• palette - Icon to show and the category in which the icon appears in the Palette
• editor - Flags indicating whether the editor shows in the MasterPage and Designer UI and is resizable in the Editor
• outline - Icon to show in the Outline View
• propertyPage - Optional Property Edit Page to use for the report item extension in the Property Edit View

The extension point org.eclipse.birt.report.model.reportItemModel specifies reportItem and the following extension element properties:

• extensionName - Internal unique name of the report item extension
• class - Fully qualified name of the Java class that implements the org.eclipse.birt.report.model.api.extension.IReportItemFactory interface
• defaultStyle - Predefined style to use for the report item extension
• isNameRequired - Field indicating whether the report item instance name is required
• displayNameID - Resource key for the display name
  reportItem also specifies the following property extension elements:
  
• rotationAngle
• displayText

  rotationAngle and displayText each specify the following properties:
  

• name - Internal unique name of the property extension element
• type - Data type, such as integer or string
• displayNameID - Resource key for the display name
• canInherit - Flag indicating whether the property extension element can inherit properties
• detailType - Detail data type such as Boolean or string
• defaultValue - Default value of the property extension element
• isEncryptable - Flag indicating whether the property is encrypted
• defaultDisplayName - Display name to use if no localized I18N display name exists

  The extension point org.eclipse.birt.report.engine.reportitemPresentation specifies the following report Item extension elements:
  

• name - Unique name of the report item extension.
• class - Fully qualified name of the Java class that implements the org.eclipse.birt.report.engine.extension.IReportItemPresentation interface.
• supportedFormats - Supported rendering formats for this extended item. The value for this attribute is a comma-separated string, such as "HTML, PDF." The string is case-insensitive.