Welcome!

Open Source Cloud Authors: Zakia Bouachraoui, Elizabeth White, Liz McMillan, Pat Romanski, Yeshim Deniz

Related Topics: Open Source Cloud, Java IoT, Eclipse

Open Source Cloud: Article

How to Develop an Application Using the Eclipse BIRT Design Engine API

Creating a customized report design application

This article is the second in a series on developing an application using Eclipse BIRT Engine APIs. It focuses on developing an application using the Eclipse BIRT Design Engine API. The last article focused on the Eclipse BIRT Report Engine API.

The Eclipse Business Intelligence Reporting Tool (BIRT) is a set of plug-in extensions that enable a developer to add reporting functionality to an application. BIRT provides a Design Engine API that a developer can use to create a customized report design application. The org.eclipse.birt.report.engine.api package contains a set of interfaces and implementation classes that supports integrating the design-time part of BIRT into a reporting application.

Programming with a Report Design
A reporting application typically generates a report from a report design. In this type of reporting application, you develop a report design and include the design along with the application at deployment. Any changes to the generated report depend on the values of report parameters and the data from the data set. To access the report design, the application uses an IReportRunnable object.

Sometimes business logic requires changes to the report design before generating the report. You can make some changes by using parameters and scripting. Other changes can only occur by modifying the report design itself.

A reporting application can make changes to the report design and the Report Object Model (ROM) elements that make up the design. To access the structure of the report design, the application obtains a ReportDesignHandle object from the design engine. To access the design engine, an application must first instantiate a report engine, as in any other reporting application.

The ReportDesignHandle object provides access to all properties of the report design and to the elements that the report design contains. The model API provides handle classes to access all ROM elements. For example, a GridHandle object provides access to a grid element in the report design. All ROM element handles, including the report design handle, inherit from DesignElementHandle. Report items inherit from ReportElementHandle and ReportItemHandle.

After making changes to a report design or its elements, the application can write the result to a stream or a file. The report engine can then open an IReportRunnable object on the resulting design and generate a report.

An application typically accesses the items in a report design to do one of the following tasks:

  • Modify an existing report design programmatically to change the contents and appearance of the report output. An application can modify page characteristics, grids, tables, and other report items in the design, the data source, and the data set that extracts data from a data source.
  • Build a report design and generate report output entirely in an application without using BIRT Report Designer.
A reporting application can access and modify the structures in a template or a library file like the structures in a report design. The techniques described in the rest of this article are applicable to these files as well as to report designs.

The functionality of a template is identical to a report design. For this reason, the ReportDesignHandle class provides access to a template. The LibraryHandle class provides access to a library. Both these classes derive from the ModuleHandle class, which provides the fields and methods for the common functionality, such as accessing elements in the file.

The package that contains the classes and interfaces to work with the items in a report design, library, or template is org.eclipse.birt.report.model.api.

BIRT Model API Capabilities
A report developer can write an application that creates and modifies a report design programmatically. The BIRT model API has the same capabilities as BIRT Report Designer. For example, the following list shows some of the ways in which you can use the BIRT model API to manipulate a report design programmatically:

Modify a report item in a report design:

  • Format a report item, change the font, font color, fill color, format, alignment, or size. Modify the expression or other property of a report item.
  • Change the data set bound to a table or list.
    Add a report item to a report design:
  • Add a simple report item such as a data item, label, or image.
  • Set the value to display in the new report item, such as the expression of a data item or the text in a label item.
  • Create a complex item such as a grid, table, or list.
  • Add other items into a grid, table, or list.
    Change the structure of a report design:
  • Add or delete a group or column in a table or list.
  • Add a report parameter.
    Modify non-visual elements in a report design:
  • Specify a data source for a data set.
  • Set a design property such as a report title, author, wallpaper, or comment.
  • Set a page property such as height, width, or margins.
Opening a Report Design Programmatically for Editing
To access a report design and its contents, the application must instantiate a report engine then use a ReportDesignHandle object. You instantiate a ReportDesignHandle by calling a method on another class such as the model class, SessionHandle, or the report engine interface, IReportRunnable.

The SessionHandle object manages the state of all open report designs. Use a SessionHandle to open, close, and create report designs, and set global properties, such as the locale and the units of measure for report elements. The SessionHandle can open a report design from a file or a stream. Create the session handle only once. BIRT supports only a single SessionHandle for a user of a reporting application.

Configuring the Design Engine To Access a Design Handle
The DesignEngine class provides access to all the functionality of the ROM in the same way that the ReportEngine class provides access to report generation functionality. To create a DesignEngine object, you first create a DesignConfig object to contain configuration settings for the design engine. The DesignConfig object sets up custom access to resources and custom configuration variables for scripting. Instantiate a DesignEngine object with the DesignConfig object as an argument to the constructor.

Create the SessionHandle object by calling the method, newSessionHandle( ) on the DesignHandle object. To open the report design, call the method, openDesign( ), on the SessionHandle object. This method takes the name of the report design as an argument and instantiates a ReportDesignHandle object.


More Stories By Jason Weathersby

Jason Weathersby is a member of the extended BIRT development team at Actuate Corporation and has backgrounds in both computer science and technical writing. He has many years experience in technical consulting, training, writing, and publishing about reporting, business intelligence tools, and database technologies.

More Stories By Tom Bondur

Tom Bondur is a member of the extended BIRT development team at Actuate Corporation and has backgrounds in both computer science and technical writing. He has many years experience in technical consulting, training, writing, and publishing about reporting, business intelligence tools, and database technologies.

More Stories By Jane Tatchell

Jane Tatchell is a content development manager in the Developer Communications group of Actuate Engineering.

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.


IoT & Smart Cities Stories
Moroccanoil®, the global leader in oil-infused beauty, is thrilled to announce the NEW Moroccanoil Color Depositing Masks, a collection of dual-benefit hair masks that deposit pure pigments while providing the treatment benefits of a deep conditioning mask. The collection consists of seven curated shades for commitment-free, beautifully-colored hair that looks and feels healthy.
The textured-hair category is inarguably the hottest in the haircare space today. This has been driven by the proliferation of founder brands started by curly and coily consumers and savvy consumers who increasingly want products specifically for their texture type. This trend is underscored by the latest insights from NaturallyCurly's 2018 TextureTrends report, released today. According to the 2018 TextureTrends Report, more than 80 percent of women with curly and coily hair say they purcha...
The textured-hair category is inarguably the hottest in the haircare space today. This has been driven by the proliferation of founder brands started by curly and coily consumers and savvy consumers who increasingly want products specifically for their texture type. This trend is underscored by the latest insights from NaturallyCurly's 2018 TextureTrends report, released today. According to the 2018 TextureTrends Report, more than 80 percent of women with curly and coily hair say they purcha...
We all love the many benefits of natural plant oils, used as a deap treatment before shampooing, at home or at the beach, but is there an all-in-one solution for everyday intensive nutrition and modern styling?I am passionate about the benefits of natural extracts with tried-and-tested results, which I have used to develop my own brand (lemon for its acid ph, wheat germ for its fortifying action…). I wanted a product which combined caring and styling effects, and which could be used after shampo...
The platform combines the strengths of Singtel's extensive, intelligent network capabilities with Microsoft's cloud expertise to create a unique solution that sets new standards for IoT applications," said Mr Diomedes Kastanis, Head of IoT at Singtel. "Our solution provides speed, transparency and flexibility, paving the way for a more pervasive use of IoT to accelerate enterprises' digitalisation efforts. AI-powered intelligent connectivity over Microsoft Azure will be the fastest connected pat...
There are many examples of disruption in consumer space – Uber disrupting the cab industry, Airbnb disrupting the hospitality industry and so on; but have you wondered who is disrupting support and operations? AISERA helps make businesses and customers successful by offering consumer-like user experience for support and operations. We have built the world’s first AI-driven IT / HR / Cloud / Customer Support and Operations solution.
Codete accelerates their clients growth through technological expertise and experience. Codite team works with organizations to meet the challenges that digitalization presents. Their clients include digital start-ups as well as established enterprises in the IT industry. To stay competitive in a highly innovative IT industry, strong R&D departments and bold spin-off initiatives is a must. Codete Data Science and Software Architects teams help corporate clients to stay up to date with the mod...
At CloudEXPO Silicon Valley, June 24-26, 2019, Digital Transformation (DX) is a major focus with expanded DevOpsSUMMIT and FinTechEXPO programs within the DXWorldEXPO agenda. Successful transformation requires a laser focus on being data-driven and on using all the tools available that enable transformation if they plan to survive over the long term. A total of 88% of Fortune 500 companies from a generation ago are now out of business. Only 12% still survive. Similar percentages are found throug...
Druva is the global leader in Cloud Data Protection and Management, delivering the industry's first data management-as-a-service solution that aggregates data from endpoints, servers and cloud applications and leverages the public cloud to offer a single pane of glass to enable data protection, governance and intelligence-dramatically increasing the availability and visibility of business critical information, while reducing the risk, cost and complexity of managing and protecting it. Druva's...
BMC has unmatched experience in IT management, supporting 92 of the Forbes Global 100, and earning recognition as an ITSM Gartner Magic Quadrant Leader for five years running. Our solutions offer speed, agility, and efficiency to tackle business challenges in the areas of service management, automation, operations, and the mainframe.