「Birt」创建报表引擎

报表引擎是ReportEngine类的一个实例，是任何报表应用程序的关键部分。首先用EngineConfig对象来为ReportEngine准备参数，然后用BIRT报表引擎工厂来创建引擎。

创建一个配置对象：

EngineConfig config = new EngineConfig();

设置BIRT home

BIRT home就是BIRT plug-ins和类库的路径，它是报表引擎的关键参数。

你可以用下面的方式进行BIRT home设置：

■对于独立的应用程序可以通过下面的方式设置：

config.setBIRTHome ( "C:/birt-runtime-<version>/ReportEngine" );

■也可以再你自己的环境变量中设置：

set BIRT_HOME="C:/birt-runtime-<version>/ReportEngine"

SET CLASSPATH=%BIRT_HOME%/<required library 1>;

■ 在Web应用程序里要首先取得绝对路径让后设置到config

config.setBIRTHome( servletContext.getRealPath( "/WEB-INF" ) );

■在WAR 文件的Web应用程序中可以使用PlatformServletContext.

config.setBIRTHome( "" );

■ 在Eclipse中,通过VM运行参数设置

-DBIRT_HOME="C:/birt-runtime-<version>/ReportEngine"

 

设置引擎的其他参数

通过配置对象进行配置的参数还有日志，OSGI(Open Services Gateway Initiative)，平台上下文，资源文件，临时资源文件，脚本等，这些都是可选的参数，详细信息可以参考EngineConfig的API。

 

不同运行环境的差异

应用程序是独立运行的还是以web形式运行的决定了平台上下文和HTML发射器（emitter，不知道是不是生成器更合适一点）的配置的不同。平台上下文提供了报表引擎连接plug-in的机制，默认使用独立运行的方式。HTML发射器提供了处理图片和处理超链接和标签事件的功能。

 

设置上下文

BIRT是一个基于Eclipse的应用程序，因此它使用OSGI平台来启动插件来产生报表和设计引擎。BIRT需要的plug-in存储在BIRT主目录下，通过platform context进行配置，它实现了接口org.eclipse.birt.core.framework.IPlatformContext。context作为EngineConfig的一个参数通过setEngineContext( )进行设置。

BIRT中提供了两个IPlatformContext的实现：

PlatformFileContext通过文件系统目录配置context，用于独立运行的应用程序和web应用程序中部署的基于系统文件目录的BIRT应用程序。

IPlatformContext context = new PlatformFileContext( );

config.setEngineContext( context );

对于web应用上部署的BIRT应用程序，使用PlatformServletContext。它使用基于资源连接的J2EE ServletContext来定位BIRT plug-in。它默认使用“/WEB-INF/platform/”

IPlatformContext context =

new PlatformServletContext(request.getSession().getServletContext());

config.setPlatformContext(context);

如果默认的BIRT提供的实现不能满足你的要求，可以定义自己的实现。

 

设置HTML emitter

当使用HTML格式生成一个报表，引擎通过一个HTMLRenderOption对象来定义如何处理HTML emitter使用的资源（图像滤镜，图像元素，图表，书签等）。桌面应用程序和web应用程序用来处理图像的方法是不同的。使用HTML emitter首先要创建HTMLRenderOption，使用方法：

HTMLRenderOption ho = new HTMLRenderOption( );

ho.setImageHandler( new HTMLCompleteImageHandler( ));

config.setEmitterConfiguration( RenderOptionBase.OUTPUT_FORMAT_HTML, ho );

创建引擎时可以不必设置HTML emitter，你可以需要生成HTML报表时再去进行配置。

IHTMLImageHandler是用来处理图像的接口，BIRT提供了两个IHTMLImageHandler的实现：

HTMLCompleteImageHander可以将图像保存到文件目录。它首先使用HTMLRenderOption设置的图像目录，如果没有则使用EngineConfig.setTempDir( )设置的临时文件目录，如果还没有则使用java.io.tmpdir定义的系统临时文件目录。生成的HTML中引用的图像也是引擎创建的。

HTMLServerImageHandler应用在web应用程序中，它将图像文件保存在HTMLRenderOption设置的图像文目录中。HTML的图像的src指向生成的图像文件的路径也是在HTMLRenderOption中配置的。这样报表引擎就可以在本地文件中创建图像文件，并且通过URL共享。

ho.setImageDirectory("output/image");

ho.setBaseImageURL("http://myhost/prependme?image=");

如果IHTMLImageHandler的实现不能满足你的要求，你可以开发自己的实现。或者继承并重写已有的image handler。HTMLCompleteImageHander已经提供了足够的图像文件接口因此一般情况下不需要我们进行扩展。

 

启动平台

设置完成平台上下文环境，你可以通过org.eclipse.birt.core.framework.Platform类启动一个平台。Platform是一个Eclipse OSGI平台的包装类，提供一个同步的静态方法startup( )用来启动平台，该操作的开销比较大，因此你的应用程序最好只调用一次。平台使用结束后调用Platform.shutdown( )关闭。如果你是在Web应用程序里使用报表引擎，请在servlet的init方法中调用startup方法或者在第一次处理用到平台的请求时。最好启动平台的代码封装为一个单例。如果你使用Birt提供的Web Viewer或使用基于Eclipse的富客户端程序（RCP），你就不需要启动平台，因为应用程序已经自己启动了OSGi。

 

创建报表引擎

BIRT提供一个工厂服务用于创建ReportEngine对象。Platform.createFactoryObject( )创建一个实现了org.eclipse.birt.report.engine.api.IReportEngineFactory接口的工厂对象。该方法需要一个PlatformConfig对象。因为EngineConfig是继承自PlatformConfig，你可以使用EngineConfig来创建一个工厂。最后通过IReportEngineFactory.createReportEngine( )方法和刚才使用的EngineConfig对象创建报表引擎。

 

实例

在独立运行的应用程序中创建一个报表引擎，如下：

// Create an EngineConfig object.

EngineConfig config = new EngineConfig( );

// Set up the path to your BIRT home directory.

config.setBIRTHome( "C:/Program Files/birt-runtime-2_2_1/ReportEngine" );

// Explicitly set up the stand-alone application

IPlatformContext context = new PlatformFileContext( );

config.setEngineContext( context );

// Start the platform for a non-RCP application.

Platform.startup( config );

IReportEngineFactory factory = ( IReportEngineFactory ) Platform.createFactoryObject

( IReportEngineFactory.EXTENSION_REPORT_ENGINE_FACTORY );

// Set up writing images or charts embedded in HTML output.

HTMLRenderOption ho = new HTMLRenderOption( );

ho.setImageHandler( new HTMLCompleteImageHandler( ));

config.setEmitterConfiguration( RenderOptionBase.OUTPUT_FORMAT_HTML, ho );

// Create the engine.

IReportEngine engine = factory.createReportEngine( config );

 

说明：上面一个在windows系统上的独立运行的应用程序，它使用BIRT run-time提供的BIRT home，报表输出格式是HTML。

 

在Web应用程序上创建一个报表引擎，如下：

// Example class to create the report engine

public class BirtEngine {

private static IReportEngine birtEngine = null;

public static synchronized IReportEngine getBirtEngine( ServletContext sc ) {

if (birtEngine == null) {

EngineConfig config = new EngineConfig( );

config.setBIRTHome( "" );

IPlatformContext context = new PlatformServletContext( sc );

config.setPlatformContext( context );

try{

Platform.startup( config );

IReportEngineFactory factory = ( IReportEngineFactory )

Platform.createFactoryObject( 

IReportEngineFactory.EXTENSION_REPORT_ENGINE_FACTORY );

birtEngine = factory.createReportEngine( config );

}catch ( Exception e ) { e.printStackTrace( ); }

}

return birtEngine;

}

}

说明：上面的代码是一个用单例模式实现的报表引擎的创建的类，EngineConfig配置了两个参数 BIRTHome和PlatformContext。

 

在上面例子的基础上进行更多的配置

// In a different class, get the report engine

reportEngine = BirtEngine.getBirtEngine( request.getSession( ).getServletContext( ));

// Set up the engine

EngineConfig config = reportEngine.getConfig( );

HTMLRenderOption ho = new HTMLRenderOption( );

ho.setImageHandler( new HTMLServerImageHandler( ));

ho.setImageDirectory("output/image");

ho.setBaseImageURL("http://myhost/prependme?image=");

config.setEmitterConfiguration( RenderOptionBase.OUTPUT_FORMAT_HTML, ho );

 

使用日志环境调试应用程序

BIRT报表引擎使用java.util.logging的Logger和Level类来处理引擎平台的日志信息。你在Eclipse中运行一个应用程序运行信息默认的是显示在控制台上的。在非Eclipse环境中运行信息的输出就要有运行环境决定了。默认的日志级别是Level.INFO，你可以通过改变日志级别来减少系统内部的日志信息。

使用EngineConfig.setLogConfig( )可以让日志输出到磁盘文件中。该方法需要两个参数，第一个参数是日志输出的目录，BIRT 引擎会在指定目录中创建一个名称格式为ReportEngine

_YYYY_MM_DD_hh_mm_ss.log的日志文件。第二个参数是日志信息的最低级别，级别越高输出的日志信息越少。ReportEngine.changeLogLevel( )方法可以让你修改日志级别。

 

如何使用BIRT日志 如下：

// Set up the location and level of the logging output.

config.setLogConfig( "C:/Temp", Level.ERROR );

engine.changeLogLevel( Level.INFO );