Click here to close now.

Welcome!

Open Source Authors: Liz McMillan, Dan Ristic, Elizabeth White, Carmen Gonzalez, Pat Romanski

Related Topics: Open Source, Linux, Eclipse

Open Source: Article

Developing an Application Using the Eclipse BIRT Report Engine API

Provide report generation and rendering services

The Eclipse platform is an open source, integrated system of application development tools that you implement and extend using a plug-in interface. 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 Report Engine API that a developer can use to create a customized report generator application. The org.eclipse.birt.report.engine.api package contains a set of interfaces and implementation classes that supports integrating the runtime part of BIRT into an application.

The BIRT Report Engine can provide report generation and rendering services in the following environments:

  • Stand-alone engine: A Java developer uses a stand-alone engine to render a BIRT report from a report design (.rptdesign) file. In this environment, the Java developer creates a command-line application that writes a report to disk, either in HTML or PDF format.
  • BIRT report viewer: BIRT Report Designer uses the BIRT report viewer to view a report as paginated HTML. The BIRT report viewer is a Web application that runs in the Tomcat Application Server embedded in Eclipse. This viewer contains an embedded BIRT report engine.
  • Customized report designer: A customized report design environment uses an embedded BIRT report engine to preview a report.
  • Web application: A Web application similar to the BIRT report viewer uses an embedded BIRT report engine to generate a Web-based report.
This article describes how to develop a customized report generation application that performs the following tasks:
  • Creates and configures a report engine
  • Opens a report design or report document
  • Accesses data from a data source
  • Generates a report in a supported output format
  • Shuts down the engine
Creating and Configuring a Report Engine
The main interfaces and classes in the org.eclipse.birt.report.engine.api package are:
  • ReportEngine
  • EngineConfig
  • IReportRunnable
  • IRenderOption and its descendants
  • IEngineTask and its descendants
A report engine is an instantiation of the ReportEngine class. This object is the key component in any reporting application. It provides access to runnable report designs, parameters, the structure of a report design, and the task for generating a report from a report design. You can use the ReportEngine object to perform the following tasks:
  • Get a configuration object.
  • Open a report design or a report document.
  • Create an engine task to get parameter definitions and set parameter values.
  • Create an engine task to access data from a data set.
  • Get supported report formats and MIME types.
  • Create an engine task to run a report or render a report to an output format.
  • Create an engine task to extract data from a report document.
  • Clean up and shut down the engine.
A single report engine object can generate multiple reports from multiple report designs. Each application, whether it's stand-alone or Web-based, only needs to create one ReportEngine instance. The BIRT report engine is thread-safe, so this single-instance recommendation is not a restriction. At termination, the application should call shutdown( ) to unload extensions and delete temporary files.

The EngineConfig class contains the configuration settings for the report engine. Use the EngineConfig object to specify the settings for the following properties:

  • HTML emitter configuration for custom handling of images or actions for HTML output
  • Logging to set the logging file location and level
  • Platform context to indicate whether the application and engine home are in a stand-alone environment or packaged as a WAR file
  • Resource files to set the location where the reporting application can access libraries and properties files
  • Scripting configuration to provide external values and Java resources to scripting methods
The engine home is the key property that the report engine requires. The report engine cannot parse the report design or run the report without a defined engine home. For a stand-alone application, the engine home is an absolute path to a file system location. For an application running from a WAR file on an application server, the engine home is a relative path in the WAR file.

Two engine configuration properties depend on whether the environment in which the application runs is stand-alone or in a WAR file on an application server. These properties are the platform context and the HTML emitter configuration. The platform context provides the report engine with the mechanism to access files. The HTML emitter configuration provides the functionality for processing images and handling hyperlinking and bookmark actions.

A ReportEngine constructor takes the EngineConfig object as its argument. If the configuration object is null, the report engine uses the default configuration. If the configuration object is null, the environment must provide a BIRT_HOME variable that specifies the directory containing the engine plug-ins and JAR files.

Listing 1 shows how to set up a report engine in a stand-alone application. The application uses the engine home located in the BIRT runtime directory. The report output format is HTML. The application configures the HTML emitter and creates the report engine using the settings contained in the EngineConfig object.

Opening a Report Design or Report Document
BIRT Report Engine can generate a report from either a report design or an existing report document. To open a report design, call one of the openReportDesign( ) methods on ReportEngine. These methods instantiate an IReportRunnable object using a String object that specifies the path to a report design or an input stream.

To open a report document, call the ReportEngine.openReportDocument( ) method. This method instantiates an IReportDocument object using a String object that specifies the path to a report document (.rptdocument) file. This method returns the IReportDocument object. You must handle the EngineException that these methods throw.

The IReportRunnable object provides direct access to basic properties of the report design. The names of report design properties are static String fields, such as IReportRunnable.AUTHOR. To access a report design property, use the getProperty( ) method with a string argument that contains one of these fields.

To access and set the values of parameters, use methods on a parameter definition task object, described later in this article. Listing 2 shows how to open a report design and find a property value. If the engine cannot open the specified report design, the code shuts down the engine. The variable, engine, is a ReportEngine object.

The IReportDocument object provides access to the data in a report and the report's structure. IReportDocument provides methods to retrieve table of content entries, bookmarks, and page information.

To access table of content entries, use the findTOC( ) method. This method takes a TOCNode argument and returns a TOCNode object. To find the root table of contents entry, use a null argument. To find the subentries of a table of contents entry, use the getChildren( ) method. This method returns a list of TOCNode objects. From a TOCNode object, you can retrieve the display value of the entry and a Bookmark 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.


@ThingsExpo Stories
SYS-CON Events announced today that Alert Logic, the leading provider of Security-as-a-Service solutions for the cloud, has been named “Bronze Sponsor” of SYS-CON's 16th International Cloud Expo® and DevOps Summit 2015 New York, which will take place June 9-11, 2015, at the Javits Center in New York City, NY, and the 17th International Cloud Expo® and DevOps Summit 2015 Silicon Valley, which will take place November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA.
From telemedicine to smart cars, digital homes and industrial monitoring, the explosive growth of IoT has created exciting new business opportunities for real time calls and messaging. In his session at @ThingsExpo, Ivelin Ivanov, CEO and Co-Founder of Telestax, shared some of the new revenue sources that IoT created for Restcomm – the open source telephony platform from Telestax. Ivelin Ivanov is a technology entrepreneur who founded Mobicents, an Open Source VoIP Platform, to help create, deploy, and manage applications integrating voice, video and data. He is the co-founder of TeleStax, a...
SYS-CON Events announced today that Akana, formerly SOA Software, has been named “Bronze Sponsor” of SYS-CON's 16th International Cloud Expo® New York, which will take place June 9-11, 2015, at the Javits Center in New York City, NY. Akana’s comprehensive suite of API Management, API Security, Integrated SOA Governance, and Cloud Integration solutions helps businesses accelerate digital transformation by securely extending their reach across multiple channels – mobile, cloud and Internet of Things. Akana enables enterprises to share data as APIs, connect and integrate applications, drive part...
VoxImplant has announced full WebRTC support in the newest versions of its Android SDK and iOS SDK. The updated SDKs, which enable audio and video calls on mobile devices, are now compatible with the WebRTC standard to allow any mobile app to communicate with WebRTC-enabled browsers, including Google Chrome, Mozilla Firefox, Opera, and, when available, Microsoft Spartan. The WebRTC-updated SDKs represent VoxImplant's continued leadership in simplifying the development of real-time communications (RTC) services for app developers. VoxImplant (built by Zingaya, the real-time communication servi...
SYS-CON Events announced today that CommVault has been named “Bronze Sponsor” of SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY, and the 17th International Cloud Expo®, which will take place on November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. A singular vision – a belief in a better way to address current and future data management needs – guides CommVault in the development of Singular Information Management® solutions for high-performance data protection, universal availability and sim...
SYS-CON Events announced today that SafeLogic has been named “Bag Sponsor” of SYS-CON's 16th International Cloud Expo® New York, which will take place June 9-11, 2015, at the Javits Center in New York City, NY. SafeLogic provides security products for applications in mobile and server/appliance environments. SafeLogic’s flagship product CryptoComply is a FIPS 140-2 validated cryptographic engine designed to secure data on servers, workstations, appliances, mobile devices, and in the Cloud.
The IoT Bootcamp is coming to Cloud Expo | @ThingsExpo on June 9-10 at the Javits Center in New York. Instructor. Registration is now available at http://iotbootcamp.sys-con.com/ Instructor Janakiram MSV previously taught the famously successful Multi-Cloud Bootcamp at Cloud Expo | @ThingsExpo in November in Santa Clara. Now he is expanding the focus to Janakiram is the founder and CTO of Get Cloud Ready Consulting, a niche Cloud Migration and Cloud Operations firm that recently got acquired by Aditi Technologies. He is a Microsoft Regional Director for Hyderabad, India, and one of the f...
SYS-CON Events announced today that StorPool Storage will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. StorPool is distributed storage software that allows service providers, enterprises and other cloud builders to run data storage on standard x86 servers, instead of using expensive and inefficient storage arrays (SAN).
SYS-CON Events announced today that kintone has been named “Bronze Sponsor” of SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY, and the 17th International Cloud Expo®, which will take place on November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. kintone promotes cloud-based workgroup productivity, transparency and profitability with a seamless collaboration space, build your own business application (BYOA) platform, and workflow automation system.
SYS-CON Events announced today that Site24x7, the cloud infrastructure monitoring service, will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. Site24x7 is a cloud infrastructure monitoring service that helps monitor the uptime and performance of websites, online applications, servers, mobile websites and custom APIs. The monitoring is done from 50+ locations across the world and from various wireless carriers, thus providing a global perspective of the end-user experience. Site24x7 supports monitoring H...
SYS-CON Events announced today that Intelligent Systems Services will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. Established in 1994, Intelligent Systems Services Inc. is located near Washington, DC, with representatives and partners nationwide. ISS’s well-established track record is based on the continuous pursuit of excellence in designing, implementing and supporting nationwide clients’ mission-critical systems. ISS has completed many successful projects in Healthcare, Commercial, Manufacturing, ...
WebRTC is an up-and-coming standard that enables real-time voice and video to be directly embedded into browsers making the browser a primary user interface for communications and collaboration. WebRTC runs in a number of browsers today and is currently supported in over a billion installed browsers globally, across a range of platform OS and devices. Today, organizations that choose to deploy WebRTC applications and use a host machine that supports audio through USB or Bluetooth can use Plantronics products to connect and transit or receive the audio associated with the WebRTC session.
The best mobile applications are augmented by dedicated servers, the Internet and Cloud services. Mobile developers should focus on one thing: writing the next socially disruptive viral app. Thanks to the cloud, they can focus on the overall solution, not the underlying plumbing. From iOS to Android and Windows, developers can leverage cloud services to create a common cross-platform backend to persist user settings, app data, broadcast notifications, run jobs, etc. This session provides a high level technical overview of many cloud services available to mobile app developers, includi...
SYS-CON Events announced today that B2Cloud, a provider of enterprise resource planning software, will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. B2cloud develops the software you need. They have the ideal tools to help you work with your clients. B2Cloud’s main solutions include AGIS – ERP, CLOHC, AGIS – Invoice, and IZUM
The WebRTC Summit 2015 New York, to be held June 9-11, 2015, at the Javits Center in New York, NY, announces that its Call for Papers is open. Topics include all aspects of improving IT delivery by eliminating waste through automated business models leveraging cloud technologies. WebRTC Summit is co-located with 16th International Cloud Expo, @ThingsExpo, Big Data Expo, and DevOps Summit.
SYS-CON Events announced today that Tufin, the market-leading provider of Security Policy Orchestration Solutions, will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. As the market leader of Security Policy Orchestration, Tufin automates and accelerates network configuration changes while maintaining security and compliance. Tufin's award-winning Orchestration Suite™ gives IT organizations the power and agility to enforce security policy across complex, multi-vendor enterprise networks. With more than 1...
As enterprises move to all-IP networks and cloud-based applications, communications service providers (CSPs) – facing increased competition from over-the-top providers delivering content via the Internet and independently of CSPs – must be able to offer seamless cloud-based communication and collaboration solutions that can scale for small, midsize, and large enterprises, as well as public sector organizations, in order to keep and grow market share. The latest version of Oracle Communications Unified Communications Suite gives CSPs the capability to do just that. In addition, its integration ...
SYS-CON Events announced today that Cloudian, Inc., the leading provider of hybrid cloud storage solutions, will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. Cloudian, Inc., is a Foster City, California - based software company specializing in cloud storage software. The main product is Cloudian, an Amazon S3-compliant cloud object storage platform, the bedrock of cloud computing systems, that enables cloud service providers and enterprises to build reliable, affordable and scalable cloud storage solu...
SYS-CON Events announced today that Gridstore™, the leader in hyper-converged infrastructure purpose-built to optimize Microsoft workloads, will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. Gridstore™ is the leader in hyper-converged infrastructure purpose-built for Microsoft workloads and designed to accelerate applications in virtualized environments. Gridstore’s hyper-converged infrastructure is the industry’s first all flash version of HyperConverged Appliances that include both compute and storag...
SYS-CON Events announced today that IDenticard will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. IDenticard™ is the security division of Brady Corp (NYSE: BRC), a $1.5 billion manufacturer of identification products. We have small-company values with the strength and stability of a major corporation. IDenticard offers local sales, support and service to our customers across the United States and Canada. Our partner network encompasses some 300 of the world's leading systems integrators and security s...