The key tasks that a reporting application must perform are to set up the report engine, any required parameter values, and the task objects to generate the report document, and finally to render the report. The reporting application does not require the BIRT Report Designer user interface to generate a report.
The org.eclipse.birt.report.engine.api package contains the classes and interfaces that an application uses to generate reports. The main classes and interfaces are ReportEngine, EngineConfig, IReportRunnable, IRenderOption and its descendants, and IEngineTask and its descendants.
Setting up the report engine
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. Prepare the report engine’s properties with an EngineConfig object. After setting all the required properties, use the BIRT engine factory to create the report engine. The following sections describe the various configuration options and creation of the engine.
Configuring the BIRT home (OSGi only)
The BIRT home, which is the location of the BIRT plug-ins and libraries, is the key property that the OSGi report engine requires. The OSGi report engine cannot parse a report design nor render the report without a defined BIRT home. For a stand-alone application, the BIRT home is an absolute path to a file system location. For an application running from a web archive (.war) file on an application server, the BIRT home is a relative path in the WAR file. To set the BIRT home location, use one of the following techniques:
For a stand-alone application, use one of the following techniques:
Call EngineConfig.setBIRTHome( ) with an argument that is the path to the BIRT home directory, for example:
In the application’s environment, set up the BIRT_HOME and CLASSPATH variables to access the required libraries. For example, in a Windows batch file, include commands similar to the following ones before launching the stand-alone application:
set BIRT_HOME="C:\birt-runtime-<version>\ReportEngine"
SET CLASSPATH=%BIRT_HOME%\<required library 1>; %BIRT_HOME%\<required library 2 and so on>;%CLASSPATH%
To develop an application that uses a BIRT_HOME environment variable, set BIRT_HOME in the VM arguments in the Eclipse Run dialog. For example, in VM arguments, type text similar to the following line:
If the application runs from a WAR file, use a relative path from the WAR file root, as shown in the following example. This configuration uses PlatformServletContext.
config.setBIRTHome( "" );
If you use BIRT in an Eclipse-based application, such as an RCP application, and the BIRT plug-ins are located in the application’s plugins directory, you do not need to set BIRT_HOME.
Configuring the report engine
Set configuration properties using methods on an EngineConfig object.
Table 5-3 describes these properties and how to set them using EngineConfig methods. The EngineConfig class also provides getter methods to access these properties.
Table 5-3 EngineConfig properties
Property type
Setting the property
Configuring an emitter
To set the properties for the required report output format, call setEmitterConfiguration( ) with arguments providing the format and a IRenderOption object for that format.
Logging
To set the logging file location and level, call setLogConfig( ). To refine the logging file name and properties, use the other setLogXXX( ) methods.
OSGi configuration
To set specific OSGi start‑up parameters, call setOSGiArguments( ) or setOSGiConfig( ).
Platform context
To indicate whether the application is in a stand‑alone environment or packaged as a web archive (.war) file, create an implementation of the IPlatformContext interface. Then, call setPlatformContext( ).
Resource files
To set the location from which the reporting application accesses resource files such as libraries and properties files containing localized strings, call setResourcePath( ). To change the algorithm for locating these resources, call setResourceLocator( ).
Scripting configuration
To provide external values to scripting methods, call setProperty( ). To provide additional Java resources to scripting methods, call getAppContext( ) and add the object to the application context object.
Status handling
To provide a custom status handler, create an implementation of the IStatusHandler interface. Then, call setStatusHandler( ).
Temporary file location
To set up a custom location for temporary files, call setTempDir( ).
Setting up a stand-alone or WAR file environment
Two engine configuration properties depend on whether the environment in which the application runs is stand-alone or in a web archive (.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 plug-ins. The default platform context provides direct file system access to these plug-ins, as used by a stand-alone application. The HTML emitter configuration provides the functionality to process images and handle hyperlinking and bookmark actions.
Setting up the platform context
Because BIRT is an Eclipse-based application, it uses the OSGi platform to start up the plug-ins that make up the report and design engines. The BIRT application locates the plug-ins in the Java build path or in the BIRT home using the platform context, which is an implementation of the org.eclipse.birt.core .framework.IPlatformContext interface. This interface defines the method, getPlatform( ) that returns the location of the plugins directory. Use the IPlatformContext object as the argument to the EngineConfig object’s setPlatformContext( ) method.
The BIRT framework provides two implementations of the IPlatformContext interface. These implementations provide all the required functionality for the platform context.
The default implementation, PlatformFileContext, accesses the plug-ins in the BIRT home folder on the file system. For OSGi, the application either sets the BIRT home location in the EngineConfig object or the application environment contains BIRT_HOME and creating a PlatformFileContext object is not necessary.
For a web deployment, such as an application running from a WAR file on an application server, use the PlatformServletContext implementation. This class uses the resource-based access provided by the J2EE ServletContext class to locate the required plug-ins. The constructor for this class takes one argument, a ServletContext object. By default, PlatformServletContext finds plug-ins in the /WEB-INF/platform/ directory by using the ServletContext.getRealPath( ) method. Some application servers return null from this method. In this case, the PlatformServletContext object creates a platform directory in the location defined by the system property, javax.servlet.context.tempdir. The PlatformServletContext object copies the plug-ins and configuration folders to this location. Listing 5‑1 sets up a platform context for a reporting application that runs from a WAR file.
You can also implement your own version of IPlatformContext. In the same way as for the built-in platform contexts, call EngineConfig.setPlatformContext( ) to configure the engine to use the new implementation.
How to set up a report engine as a web application
1 Set up the platform context, as shown in Listing 5‑1.
Listing 5‑1 Setting up the platform context for WAR file deployment
config.setEmitterConfiguration( RenderOption.OUTPUT_FORMAT_HTML, ho );
In this listing, request is an HttpServletRequest object.
Setting up the HTML emitter
To generate a report in HTML format, the report engine uses an org.eclipse .birt.report.engine.api.HTMLRenderOption object to determine how to handle resources that the HTML emitter uses or creates. These resources include new image files for image elements and chart elements, and the locations of jumps from bookmark and drill-through actions. BIRT uses different image handlers for file system-based applications and applications deployed on the web. Use the EngineConfig object to set up the HTML emitter options when creating the report engine, as shown in Listing 5‑3, or set the options later when rendering a report to HTML.
To set up the HTML emitter, instantiate an HTMLRenderOption object. Use this object as the argument to ReportEngine.setEmitterConfiguration( ) to define the HTML rendering options when creating the report engine.
Call the HTMLRenderOption.setImageHandler( ) method to configure the image handler. This method determines how to save the image files by using an org.eclipse.birt.report.engine.api.IHTMLImageHandler object. Images defined in a report as a URL are not saved locally. BIRT provides two implementations of the IHTMLImageHandler interface. Both implementations create unique image file names for temporary images.
The default image handler implementation, HTMLCompleteImageHandler, saves images to the file system. Use this implementation for a stand-alone application or for a web application that uses file system deployment on the application server. This image handler finds the location for images by searching first for the image directory set in the HTMLRenderOption object, next the temporary files directory as set by the EngineConfig.setTempDir( ) method, and finally the location set by the system setting, java.io.tmpdir. All images in the generated HTML use file references to the created images.
For a web deployment, such as an application running from a WAR file on an application server, use the HTMLServerImageHandler implementation. This class saves images to the image directory set in the HTMLRenderOption object. The src attribute of images in the generated HTML appends the image name to the base image URL, also set in the HTMLRenderOption object. In this way, the report engine produces the images locally and shares the images using a URL. To use this implementation, set the image directory and the base image URL, as shown in Listing 5‑2. The example BIRT Web Viewer in the org.eclipse.birt.report.viewer plug-in uses this implementation.
If neither IHTMLImageHandler meets your needs, create a class that implements IHTMLImageHandler or extends an existing image handler. Typically, HTMLCompleteImageHander provides sufficient functionality for file system access, so an application does not extend the class. For the application server environment, extend from HTMLServerImageHandler. To configure the engine to use the new implementation, in the same way as for the built-in image handlers, call EngineConfig.setEmitterConfiguration( ).
Starting the platform
After setting up the PlatformContext, an application starts the platform by using the org.eclipse.birt.core.framework.Platform class. This class acts as a wrapper around the Eclipse OSGILauncher class and provides the method, startup( ), to start the platform. Calling this synchronized static method uses substantial system resources, so an application should call this method only once. If the report engine is deployed in a web application, call Platform.startup( ) in the servlet’s init( ) method or in the first request that uses the platform. To achieve this behavior, wrap the platform start-up code in a singleton, as shown in Listing 5‑1. When an application finishes using the platform, call Platform.shutdown( ). If you use the example Web Viewer or deploy the report engine in an Eclipse-based project such as a Rich Client Platform (RCP) application, do not start up or shut down the platform, because these applications control the OSGi start-up and shutdown.
Creating the report engine
BIRT provides a factory service to create the ReportEngine object. Call Platform.createFactoryObject( ) to create this factory, which implements the org.eclipse.birt.report.engine.api.IReportEngineFactory interface. The createFactoryObject( ) method uses a PlatformConfig object. Call IReportEngineFactory.createReportEngine( ) to create the report engine.
How to set up a report engine as a stand-alone application
Listing 5‑3 shows an example of setting up a report engine as a stand-alone application on a Windows system. The application uses the BIRT home located in the BIRT run-time directory. The report output format is HTML.
Listing 5‑3 Setting up the report engine for a stand-alone application
//Create an EngineConfig object.
EngineConfig config = new EngineConfig( );
//For OSGi, set up the path to your BIRT home directory.
catch ( BirtException e ) { e.printStackTrace(); }
Using the logging environment to debug an application
BIRT Report Engine uses the java.util.logging classes, Logger and Level, to log information about the processing that the engine performs. When an application runs in the Eclipse Workbench, by default, the messages appear in the console. When an application runs outside Eclipse, the default location of the log messages depends on the environment. The default logging threshold is Level.INFO. Typically, you change this level in your application to reduce the number of internal logging messages.
To set up the logging environment to write the engine’s log messages to a file, use the EngineConfig.setLogConfig( ) method. This method takes two arguments. The first argument is the directory in which to create the log file. The second argument is the lowest level at which to log information. Set the logging level to a high threshold so that the engine logs fewer messages. Typically, you want to see information at INFO level when you first develop a block of code. Use the ReportEngine.changeLogLevel( ) method to modify the amount of information that the engine logs. This method takes a single argument, which is a Level constant. When the code is stable, you no longer need to see all the engine’s INFO messages. At that point, delete or comment out the call to changeLogLevel( ). BIRT Report Engine creates a log file with a name of the format ReportEngine_YYYY_MM_DD_hh_mm_ss.log. To change this name, call EngineConfig.setLogFile( ). Use the EngineConfig methods, setLogRollingSize( ) and setLogMaxLogBackupIndex( ), to control the size and number of log files.
How to use BIRT logging
The following example shows how to use logging in an application. You set up the logging environment and modify it later in your application. The variable, config, is the EngineConfig object that the code’s active ReportEngine object, engine, is using.
1 Configure logging on the report engine object.
// Set up the location and level of the logging output.
config.setLogConfig( "C:/Temp", Level.SEVERE );
config.setLogFile( "myBIRTApp.log" );
2 In any newly written code, increase the amount of logging.
For a stand-alone application, use one of the following techniques: