<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> | |
<html> | |
<head> | |
<title>BIRT Extension Mechanism : Part 1</title> | |
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> | |
<link href="../article.css" type="text/css" rel="stylesheet"> | |
</head> | |
<body> | |
<h1>BIRT Extension Mechanism : Part 1</h1> | |
<div class="summary"> | |
<h2>Abstract</h2> | |
<p>This article introduces the extension mechanism of BIRT report | |
model, engine and designer, shows how to create custom extended report items | |
step by | |
step.</p> | |
<div class="author">By Zhiqiang | |
Qian, Actuate Corporation</div> | |
<div class="copyright">Copyright © [2008] | |
[Actuate Corporation].</div> | |
<div class="date">August 7, 2008</div> | |
</div> | |
<div class="content"> | |
<h2>Introduction</h2> | |
<p>For many people, <a href="http://eclipse.org/birt">BIRT(Business | |
Intelligence and Reporting Tools)</a> may | |
only mean a regular reporting tool. But in fact, the real strength of | |
BIRT is not only its built-in reporting functionality, but also | |
its | |
extension capabilities. By extensions, user can easily extend the | |
functionality of BIRT, creating custom extended report items, adding custom | |
emitters, and even having custom editor pages. The powerfulness of extensions | |
enables user to create | |
custom reporting features that can meet very specific requirements. In | |
this | |
article, we will explorer how to leverage the BIRT extension mechanism to | |
extend the BIRT capabilities. The given samples will | |
cover most of the essential extension points that provided by BIRT report | |
model, engine and designer.<br> | |
</p> | |
<h2>The Basics</h2> | |
<p>BIRT already contains the basic Label and Text report items, | |
but these items can only show horizontal text. Sometimes, user | |
would | |
like to show angled text, in this case, alternative solution is needed. | |
In following sections, we are introducing how to implement a | |
RotatedText | |
extended report item through BIRT extensions, and how to enhance | |
the functionality step by step by implementing more extension points.</p> | |
<p>Note: This example is a modified version based | |
on RotatedText sample on BIRT CVS, the original code | |
can be retrieved <a href="http://dev.eclipse.org/viewcvs/index.cgi/?root=BIRT_Project">here.</a></p> | |
<p>To implement an extended report item, basically we need look at following extension points:</p> | |
<ul> | |
<li>org.eclipse.birt.report.model.reportItemModel</li> | |
<li>org.eclipse.birt.report.designer.ui.reportitemUI</li> | |
<li>org.eclipse.birt.report.engine.reportitemPresentation</li> | |
</ul> | |
<br> | |
<img style="width: 514px; height: 156px;" alt="" src="images/extensions.png"><br> | |
<p>These three extensions are the basics to implement an extended | |
report item. In brief, | |
"org.eclipse.birt.report.model.reportItemModel" provides the report | |
model extensibility, "org.eclipse.birt.report.designer.ui.reportitemUI" | |
provides the report designer extensibility and | |
"org.eclipse.birt.report.engine.reportitemPresentation" provides the | |
report engine extensibility. Now we will introduce them one by one.</p> | |
<h3>1) org.eclipse.birt.report.model.reportItemModel</h3> | |
<p>This extension point is provided by BIRT Report Model, normally user | |
uses this extension point to define the extended report item model.</p> | |
<img style="width: 1036px; height: 224px;" alt="" src="images/model-extension.png"> | |
<p>First we need define a new extended report item model | |
extension as "RotatedText", this name is the identifier | |
for the extended item, it's also the only symbol that connects between the report model | |
and designer extensions.</p> | |
<p>Then we define the model factory class as | |
"org.eclipse.birt.sample.reportitem.rotatedtext.RotatedTextItemFactory". | |
This factory class will be used to create and initialize the | |
IReportItem instance, usually this class can also implement an | |
additional IMessages interface to provide localization support:</p> | |
<pre style="font-family: monospace;">public class RotatedTextItemFactory extends ReportItemFactory<br>{<br> public IReportItem newReportItem( DesignElementHandle modelHanlde )<br> {<br> if ( modelHanlde instanceof ExtendedItemHandle && RotatedTextItem.EXTENSION_NAME.equals( ( (ExtendedItemHandle) modelHanlde ).getExtensionName( ) ) )<br> {<br> return new RotatedTextItem( (ExtendedItemHandle) modelHanlde );<br> }<br> return null;<br> }<br><br> public IMessages getMessages( )<br> {<br> // TODO implement this to support localization<br> return null;<br> }<br>}<br></pre> | |
<p>There are some extra properties here that are not used by this example, we just introduce them briefly:</p> | |
<ul> | |
<li>defaultStyle</li> | |
<ul> | |
<li>specify the default style name, this will be used by BIRT | |
to find and match the default style for this extended report item | |
automatically.</li> | |
</ul> | |
<li>isNameRequired</li> | |
<ul> | |
<li>specify if the name is required for this extended report item.</li> | |
</ul> | |
<li>displayNameID</li> | |
<ul> | |
<li>specify the display name ID for this extended report item, the | |
ID will be passed to IMessags interface to get the localized | |
extended report item name.</li> | |
</ul> | |
<li>extendsFrom</li> | |
<ul> | |
<li>specify the name of the report item that this extended report | |
item extends from, if this is not specified, the item will by default extend from | |
"ExtendedItem".</li> | |
</ul> | |
<li>hasStyle</li> | |
<ul> | |
<li>specify if this extended report item supports styled properties, for some non-UI report items, it can be set to "false".</li> | |
</ul> | |
</ul> | |
<p>Now we need define two new properties for the RotatedText extended report item:</p> | |
<ul> | |
<li>rotationAngle </li> | |
</ul> | |
| |
| |
the rotation angle, integer type, default as 0.<br> | |
<img style="width: 1001px; height: 279px;" alt="" src="images/rotationangle-property.png"> | |
<ul> | |
<li>text</li> | |
</ul> | |
| |
| |
the text content, string type, default as "Rotated Text".<br> | |
<img style="width: 1000px; height: 274px;" alt="" src="images/text-property.png"><br> | |
<br> | |
<p>We can see a lot of things in the | |
property setting page that we haven't used yet, normally they are for more complex property types, we | |
just skip them here.<br> | |
<br> | |
Once we completed the model definition, we need give a basic IReportItem | |
implementation. This class is used to encapsulate the extended report | |
item model, providing some convenient property accessing APIs:</p> | |
<pre>public class RotatedTextItem extends ReportItem<br>{<br> public static final String EXTENSION_NAME = "RotatedText"; //$NON-NLS-1$<br> public static final String TEXT_PROP = "text"; //$NON-NLS-1$<br> public static final String ROTATION_ANGLE_PROP = "rotationAngle"; //$NON-NLS-1$<br><br> private ExtendedItemHandle modelHandle;<br><br> RotatedTextItem( ExtendedItemHandle modelHandle )<br> {<br> this.modelHandle = modelHandle;<br> }<br><br> public String getText( )<br> {<br> return modelHandle.getStringProperty( TEXT_PROP );<br> }<br><br> public int getRotationAngle( )<br> {<br> return modelHandle.getIntProperty( ROTATION_ANGLE_PROP );<br> }<br><br> public void setText( String value ) throws SemanticException<br> {<br> modelHandle.setProperty( TEXT_PROP, value );<br> }<br><br> public void setRotationAngle( int value ) throws SemanticException<br> {<br> modelHandle.setProperty( ROTATION_ANGLE_PROP, value );<br> }<br>}<br></pre> | |
<p>We can see most of the methods here are just getter/setters. For | |
simple extended report item, this is normally already enough.</p> | |
<h3>2) org.eclipse.birt.report.designer.ui.reportitemUI</h3> | |
<p>This extension point is provided by BIRT Designer, user uses this | |
extension point to define the UI behavior for extended report | |
items.<br> | |
<br> | |
<img style="width: 1001px; height: 233px;" alt="" src="images/ui-extension.png"><br> | |
<br> | |
First we need bind the Designer extension with Model extension, to do | |
this, we simply specify the extension name as "RotatedText".</p> | |
<p>Next step, we specify some settings for this extended report item:</p> | |
<ul> | |
<li>Palette Settings</li> | |
<ul> | |
<li>specify the icon to be shown in Palette view, and the | |
palette category as well. If the category is not specified, it will use | |
the default "Report Items" category.</li> | |
</ul> | |
</ul> | |
<img style="width: 495px; height: 111px;" alt="" src="images/palette-detail.png"><br> | |
<br> | |
<ul> | |
<li>Editor Settings</li> | |
<ul> | |
<li>specify the report item visibility in different editor pages, and whether resizing control should be enabled. </li> | |
</ul> | |
</ul> | |
<img style="width: 495px; height: 133px;" alt="" src="images/editor-detail.png"><br> | |
<br> | |
<ul> | |
<li>Outline Settings</li> | |
<ul> | |
<li>specify the icon to be shown in Outline view, normally this is the same as in Palette view.</li> | |
</ul> | |
</ul> | |
<img style="width: 497px; height: 90px;" alt="" src="images/icon-detail.png"><br> | |
<p> | |
The last step, specify the implementation class for UI provider:</p> | |
<img style="width: 498px; height: 94px;" alt="" src="images/labelui-detail.png"><br> | |
<p>The UI provider defines how to display and interact with the | |
extended report item within the editor. BIRT designer support three types of | |
basic UI providers:</p> | |
<ul> | |
<li>Label UI Provider</li> | |
<ul> | |
<li>user implements the IReportItemLabelProvider interface, it simply just requires an text content.</li> | |
</ul> | |
<li>Image UI Provider</li> | |
<ul> | |
<li>user implements the IReportItemImageProvider interface, it simply just requires an image content.</li> | |
</ul> | |
<li>Figure UI Provider</li> | |
<ul> | |
<li>user implements the IRportItemFigureProvider, This provider uses Figure interface from <a href="http://www.eclipse.org/gef/">GEF</a>, providing more flexibility and interactivity support.</li> | |
</ul> | |
</ul> | |
<br> | |
<p>In this example, we choose to implement the simplest Label UI | |
Provider first, in consequent examples, we may introduce other type of UI providers.</p> | |
<p> | |
Our Label UI Provider implementation class is | |
"org.eclipse.birt.sample.reportitem.rotatedText.RotatedTextLabelUI", | |
the code looks very simple:</p> | |
<pre>public class RotatedTextLabelUI implements IReportItemLabelProvider<br>{<br> public String getLabel( ExtendedItemHandle handle )<br> {<br> try<br> {<br> IReportItem item = handle.getReportItem( );<br> if ( item instanceof RotatedTextItem )<br> {<br> return ( (RotatedTextItem) item ).getText( );<br> }<br> }<br> catch ( ExtendedElementException e )<br> {<br> e.printStackTrace( );<br> }<br> return null;<br> }<br>}</pre> | |
<p>You can see what it does is just reading the property from model and returning a text value.<br> | |
<br> | |
Once we completed the designer extension, we can run the desginer first and have a glance for what we already have now:<br> | |
<br> | |
OK, the Palette view already contains the new RotatedText extended report item.</p> | |
<img style="width: 341px; height: 408px;" alt="" src="images/palette.png"> <br> | |
<p>Right-click in the editor, we can see the RotatedText item is also available in the context menu.</p> | |
<img style="width: 487px; height: 395px;" alt="" src="images/layout.png"><br> | |
<p>Now try insert one RotatedText item to report, in Outline view, we can see the new RotatedText node.<br> | |
</p> | |
<img style="width: 347px; height: 438px;" alt="" src="images/outline.png"><br> | |
<p>Select the RotatedText item, open the Properties view, it immediately | |
lists all the properties that belong to this extended report item. Among | |
them, we can see "Rotation Angle" and "Text | |
Content" as well as other inherited properties. User can edit the | |
property value in this view. | |
</p> | |
<img style="width: 728px; height: 346px;" alt="" src="images/properties.png"><br> | |
<p>Now designer extension is done, let's step to the Report Engine extension.</p> | |
<h3>3) org.eclipse.birt.report.engine.reportitemPresentation</h3> | |
<p>This extension point is provided by BIRT Report Engine, user uses | |
this extension point to define the presentation behavior of the | |
extended report item.<br> | |
</p> | |
<div style="text-align: left;"><img style="width: 1003px; height: 166px;" alt="" src="images/engine-extension.png"><br> | |
<p>First we also need specify the extension name as "RotatedText" to link it | |
with Model extension, and specify the presentation implementation | |
class | |
as | |
"org.eclipse.birt.sample.reportitem.rotatedtext.RotatedTextPresentationImpl". | |
The presentation implementation class need implement the | |
IReportItemPresentation interface.<br> | |
<br> | |
Our plan to implement the rotated text effect is to create an image | |
dynamically, in this image, we use SWING graphics API to render the | |
rotated text. </p> | |
<p>Here is the code that all we need:</p> | |
<pre>public class RotatedTextPresentationImpl extends ReportItemPresentationBase<br>{<br> private RotatedTextItem textItem;<br><br> public void setModelObject( ExtendedItemHandle modelHandle )<br> {<br> try<br> {<br> textItem = (RotatedTextItem) modelHandle.getReportItem( );<br> }<br> catch ( ExtendedElementException e )<br> {<br> e.printStackTrace( );<br> }<br> }<br><br> public int getOutputType( )<br> {<br> return OUTPUT_AS_IMAGE;<br> }<br><br> public Object onRowSets( IRowSet[] rowSets ) throws BirtException<br> {<br> if ( textItem == null )<br> {<br> return null;<br> }<br><br> int angle = textItem.getRotationAngle( );<br> String text = textItem.getText( );<br> BufferedImage rotatedImage = SwingGraphicsUtil.createRotatedTextImage( text, angle, new Font( "Default", 0, 12 ) ); //$NON-NLS-1$<br> ByteArrayInputStream bis = null;<br><br> try<br> {<br> ImageIO.setUseCache( false );<br> ByteArrayOutputStream baos = new ByteArrayOutputStream( );<br> ImageOutputStream ios = ImageIO.createImageOutputStream( baos );<br> ImageIO.write( rotatedImage, "png", ios ); //$NON-NLS-1$<br> ios.flush( );<br> ios.close( );<br> bis = new ByteArrayInputStream( baos.toByteArray( ) );<br> }<br> catch ( IOException e )<br> {<br> e.printStackTrace( );<br> }<br> return bis;<br> }<br>}<br></pre> | |
<p>The logic is pretty straightforward, the main part is to | |
generate an image dynamically in the onRowSets() method. To return | |
the image, we simply create an in-memory stream to hold the image | |
content.</p> | |
<p>Here is the utility class that implements the key rotation rendering algorithm:</p> | |
<pre>public class SwingGraphicsUtil<br>{<br> public static BufferedImage createRotatedTextImage( String text, int angle, Font ft )<br> {<br> Graphics2D g2d = null;<br> try<br> {<br> if ( text == null || text.trim( ).length( ) == 0 )<br> {<br> return null;<br> }<br> BufferedImage stringImage = new BufferedImage( 1, 1, BufferedImage.TYPE_INT_ARGB );<br> g2d = (Graphics2D) stringImage.getGraphics( );<br> g2d.setFont( ft );<br> FontMetrics fm = g2d.getFontMetrics( );<br> Rectangle2D bounds = fm.getStringBounds( text, g2d );<br> TextLayout tl = new TextLayout( text, ft, g2d.getFontRenderContext( ) );<br> g2d.dispose( );<br> g2d = null;<br> return createRotatedImage( tl, (int) bounds.getWidth( ), (int) bounds.getHeight( ), angle );<br> }<br> catch ( Exception e )<br> {<br> e.printStackTrace( );<br> if ( g2d != null )<br> {<br> g2d.dispose( );<br> }<br> }<br> return null;<br> }<br><br> private static BufferedImage createRotatedImage( Object src, int width, int height, int angle )<br> {<br> angle = angle % 360;<br> if ( angle < 0 )<br> {<br> angle += 360;<br> }<br> if ( angle == 0 )<br> {<br> return renderRotatedObject( src, 0, width, height, 0, 0 );<br> }<br> else if ( angle == 90 )<br> {<br> return renderRotatedObject( src, -Math.PI / 2, height, width, -width, 0 );<br> }<br> else if ( angle == 180 )<br> {<br> return renderRotatedObject( src, Math.PI, width, height, -width, -height );<br> }<br> else if ( angle == 270 )<br> {<br> return renderRotatedObject( src, Math.PI / 2, height, width, 0, -height );<br> }<br> else if ( angle > 0 && angle < 90 )<br> {<br> double angleInRadians = ( ( -angle * Math.PI ) / 180.0 );<br> double cosTheta = Math.abs( Math.cos( angleInRadians ) );<br> double sineTheta = Math.abs( Math.sin( angleInRadians ) );<br> int dW = (int) ( width * cosTheta + height * sineTheta );<br> int dH = (int) ( width * sineTheta + height * cosTheta );<br> return renderRotatedObject( src, angleInRadians, dW, dH, -width * sineTheta * sineTheta, width * sineTheta * cosTheta );<br> }<br> else if ( angle > 90 && angle < 180 )<br> {<br> double angleInRadians = ( ( -angle * Math.PI ) / 180.0 );<br> double cosTheta = Math.abs( Math.cos( angleInRadians ) );<br> double sineTheta = Math.abs( Math.sin( angleInRadians ) );<br> int dW = (int) ( width * cosTheta + height * sineTheta );<br> int dH = (int) ( width * sineTheta + height * cosTheta );<br> return renderRotatedObject( src, angleInRadians, dW, dH, -( width + height * sineTheta * cosTheta ), -height / 2 );<br> }<br> else if ( angle > 180 && angle < 270 )<br> {<br> double angleInRadians = ( ( -angle * Math.PI ) / 180.0 );<br> double cosTheta = Math.abs( Math.cos( angleInRadians ) );<br> double sineTheta = Math.abs( Math.sin( angleInRadians ) );<br> int dW = (int) ( width * cosTheta + height * sineTheta );<br> int dH = (int) ( width * sineTheta + height * cosTheta );<br> return renderRotatedObject( src, angleInRadians, dW, dH, -( width * cosTheta * cosTheta ), -( height + width * cosTheta * sineTheta ) );<br> }<br> else if ( angle > 270 && angle < 360 )<br> {<br> double angleInRadians = ( ( -angle * Math.PI ) / 180.0 );<br> double cosTheta = Math.abs( Math.cos( angleInRadians ) );<br> double sineTheta = Math.abs( Math.sin( angleInRadians ) );<br> int dW = (int) ( width * cosTheta + height * sineTheta );<br> int dH = (int) ( width * sineTheta + height * cosTheta );<br> return renderRotatedObject( src, angleInRadians, dW, dH, ( height * cosTheta * sineTheta ), -( height * sineTheta * sineTheta ) );<br> }<br> return renderRotatedObject( src, 0, width, height, 0, 0 );<br> }<br><br> private static BufferedImage renderRotatedObject( Object src, double angle, int width, int height, double tx, double ty )<br> {<br> BufferedImage dest = new BufferedImage( width, height, BufferedImage.TYPE_INT_ARGB );<br> Graphics2D g2d = (Graphics2D) dest.getGraphics( );<br> g2d.setColor( Color.black );<br> g2d.setRenderingHint( RenderingHints.KEY_TEXT_ANTIALIASING, RenderingHints.VALUE_TEXT_ANTIALIAS_ON );<br> g2d.setRenderingHint( RenderingHints.KEY_ANTIALIASING, RenderingHints.VALUE_ANTIALIAS_ON );<br> AffineTransform at = AffineTransform.getRotateInstance( angle );<br> at.translate( tx, ty );<br> g2d.setTransform( at );<br> if ( src instanceof TextLayout )<br> {<br> TextLayout tl = (TextLayout) src;<br> tl.draw( g2d, 0, tl.getAscent( ) );<br> }<br> else if ( src instanceof Image )<br> {<br> g2d.drawImage( (Image) src, 0, 0, null );<br> }<br> g2d.dispose( );<br> return dest;<br> }<br>}<br></pre> | |
<h2>The Result</h2> | |
<p>Now all required extension points are done, let's have a test.<br> | |
<br> | |
Create a report that contains some RotatedText items first:<br> | |
</p> | |
<img style="width: 865px; height: 273px;" alt="" src="images/design-layout.png"><br> | |
<p>Here we inserted quite a few RotatedText items with different angle settings.<br> | |
<br> | |
Preview the report as HTML, it results like this:<br> | |
</p> | |
<img style="width: 703px; height: 218px;" alt="" src="images/html-output.png"><br> | |
<p>Preview the report as PDF, it results like this:<br> | |
</p> | |
<img style="width: 757px; height: 482px;" alt="" src="images/pdf-output.png"><br> | |
<br> | |
<p>Done! So far we've successfully implemented a RotatedText extended | |
report item for BIRT, and integrated it with Designer and Report Engine.<br> | |
</p> | |
</div> | |
<h2>Summary</h2> | |
<p>BIRT provides very good extension mechanism, which allows user | |
to create custom reporting features. This article introduced how to write | |
a custom RotatedText extended report item for BIRT.</p> | |
<h2>Resources</h2> | |
<p>[1] <a href="extension-tutorial-1.zip">The complete source code</a>: you can extract and import it into Eclipse workspace as a plugin project directly</p> | |
<p>[2] BIRT Official Site: <a href="http://eclipse.org/birt">http://eclipse.org/birt</a></p> | |
<p>[3] How to access Eclipse CVS: <a href="http://wiki.eclipse.org/CVS_Howto">http://wiki.eclipse.org/CVS_Howto</a></p> | |
<p><br> | |
<br> | |
</p> | |
<br> | |
</div> | |
</body> | |
</html> |