将BIRT整合到自己的Java项目中

1. BIRT的runtime下载包中有一个birt.war文件，将它解开，复制WEB-INF/plantform目录下的congiguration和plungins目录到项目lib/birt-2.1.2目录,复制WEB-INF/lib目录下的jar到 项目lib/birt-2.1.2/lib。顺便说一下，我的项目目录结构是这样的：
   src/java
   lib/birt-2.1.2/
   lib
   confguration
   plugins
   web/WEB-INF
   如果项目需要使用BIRT，则复制lib下的jar到WEB-INF/lib，并复制confguration和plugins到WEB-INF/platform目录。为了方便，还编写了一个ANT任务：
   
   <targetname="copy-birt">
   <mkdirdir="${web.dir}/WEB-INF/lib"/>
   <mkdirdir="${web.dir}/WEB-INF/platform"/>
   <mkdirdir="${web.dir}/WEB-INF/platform/plugins"/>
   <mkdirdir="${web.dir}/WEB-INF/platform/configuration"/>
   <copytodir="${web.dir}/WEB-INF/lib"includeEmptyDirs="no">
   <filesetdir="${birt.lib}"includes="*.jar"/>
   </copy>
   <copytodir="${web.dir}/WEB-INF/platform/plugins"includeEmptyDirs="yes">
   <filesetdir="${birt.plugins}"includes="**/*.*"/>
   </copy>
   <copytodir="${web.dir}/WEB-INF/platform/configuration"includeEmptyDirs="yes">
   <filesetdir="${birt.config}"includes="**/*.*"/>
   </copy>
   </target>
2. 在web目录下建立reports目录，下设images,rptdoc,pdf三个目录，报表设计文件放在reports目录下，images用于存放生成的图片，rptdoc用于存放报表设计文件对应的document文件，pdf目录用于存放生成的pdf报表。
   上述几个目录的名字可自由定义。
3. 关于Viewer
   BIRT自带一个viewer，但是功能方面不够，尤其是不支持中文。所以有必要自己实现一个viewer，看下一篇吧。

关于编写viewer，关键在于使用ReportEngine API，这个在birt官方文档上有很详细的描述。 这里将几个主要环节总结一下：

1. 启动ReportEngine
   这里需要注意启动ReportEngine的开销问题和图片链的协议的问题。使用IReportEngineFactory比每次new一个出来性能方面要好很多。使用HTMLEmitterConfig可以使得生成的HTML报表中的图片的src指向一个web资源而非file资源。
   
   publicIReportEnginegetEngine(){
   try{
   if(platformContext==null){
   platformContext=newPlatformServletContext(servletContext);
   }
   engineConfig=newEngineConfig();
   engineConfig.setEngineHome(
   servletContext.getRealPath("/WEB-INF/platform/"));
   //要求ENGINEHOME位于WEB-INF/Platform
   engineConfig.setPlatformContext(platformContext);
   //ThiscallsetstheLogdirectorynameandlevel
   engineConfig.setLogConfig(getLogDir(),Level.FINE);
   
   //设置Emitter，渲染HTML的时候，image的地址是HTTP协议而不是File协议
   HTMLEmitterConfigemitterConfig=newHTMLEmitterConfig();
   emitterConfig.setActionHandler(newHTMLActionHandler());
   HTMLServerImageHandlerimageHandler=newHTMLServerImageHandler();
   emitterConfig.setImageHandler(imageHandler);
   engineConfig.getEmitterConfigs().put("html",emitterConfig);
   
   //设置日志level
   engineConfig.setLogConfig(getLogDir(),Level.WARNING);
   //启动Platform，创建ReportEngine
   Platform.startup(engineConfig);
   IReportEngineFactoryfactory=(IReportEngineFactory)Platform
   .createFactoryObject(IReportEngineFactory.EXTENSION_REPORT_ENGINE_FACTORY);
   engine=factory.createReportEngine(engineConfig);
   engine.changeLogLevel(Level.WARNING);
   
   log.debug("Anewenginestartup.");
   }catch(BirtExceptione){
   e.printStackTrace();
   }
   
   returnengine;
   }
2. 运行报表
   我理解为编译报表文件。BIRT在渲染报表之前，要将报表编译为.rptdocument，再根据这个文件将报表渲染为HTML格式或PDF格式。编译报表使用IRunTask：
   
   protectedvoidrun(StringrptDesign){
   assert(context!=null);
   
   IReportEngineengine=context.getEngine();
   //Openareportdesign
   IReportRunnabledesign=null;
   try{
   design=engine.openReportDesign(context
   .getFullRptDesignFilename(rptDesign));
   //Createtasktorunthereport-usethetaskto
   //executethereportandsavetodisk.
   IRunTasktask=engine.createRunTask(design);
   Stringdoc=context.getFullRptDocumentFilename(rptDesign);
   //runthereportanddestroytheengine
   task.run(doc);
   
   log.debug("saverptdesignto"+doc);
   task.close();
   }catch(EngineExceptione){
   e.printStackTrace();
   }
   }
3. 渲染报表
   BIRT支持HTML格式和PDF格式，这两种报表生成的过程相同，只是设置不同的RenderContext和RenderOptions。我们把相同的部分提取为父类的公共方法，不同的部分留给子类实现：
   
   IReportDocumentiReportDocument=engine.openReportDocument(docFilename);
   //CreateRenderTask
   IRenderTasktask=engine.createRenderTask(iReportDocument);
   task.addScriptableJavaObject("jsBirtObject",
   getScriptableObject(scriptObj));
   if(params!=null&&!params.isEmpty()){
   task.setParameterValues(params);
   }
   setRenderContext(task);//设置RenderContext，具体由子类实现
   setRenderOptions(task,out);//设置RenderOptions，具体由子类实现
   task.render();
   task.close();
   }catch(EngineExceptione){
   e.printStackTrace();
   }finally{
   engine.shutdown();
   }
4. 渲染PDF和HTML报表
   
   • PDF
     
     /**
     *@seeAbstractBirtReportParser#setRenderContext(IRenderTask)
     */
     @Override
     protectedvoidsetRenderContext(IRenderTasktask){
     PDFRenderContextrenderContext=newPDFRenderContext();
     renderContext.setEmbededFont(true);
     HashMapcontextMap=newHashMap();
     contextMap.put(EngineConstants.APPCONTEXT_PDF_RENDER_CONTEXT,renderContext);
     task.setAppContext(contextMap);
     }
     
     /**
     *@seeAbstractBirtReportParser#setRenderOptions(IRenderTask,OutputStream)
     */
     @Override
     protectedvoidsetRenderOptions(IRenderTasktask,OutputStreamout){
     RenderOptionBaseoptions=newRenderOptionBase();
     options.setOutputStream(out);
     options.setOutputFormat(RenderOptionBase.OUTPUT_FORMAT_PDF);
     task.setRenderOption(options);
     }
   • HTML
     我们要生成一个HTML的一部分，而非包含<html/>标记的完整的HTML文档
     
     /**
     *@seeAbstractBirtReportParser#setRenderContext(IRenderTask)
     */
     @Override
     protectedvoidsetRenderContext(IRenderTasktask){
     HTMLRenderContextrenderContext=newHTMLRenderContext();
     renderContext.setBaseURL(context.getBaseURL());
     //YoumustdefineHTMLServerImageHandlertouseaURL
     renderContext.setBaseImageURL(context.getBaseImageURL());
     //renderContext.setImageDirectory("myimages");
     renderContext.setImageDirectory(context.getImageDirectory());
     renderContext.setSupportedImageFormats("JPG;PNG");
     HashMapcontextMap=newHashMap();
     contextMap.put(EngineConstants.APPCONTEXT_HTML_RENDER_CONTEXT,renderContext);
     task.setAppContext(contextMap);
     }
     
     /**
     *@seeAbstractBirtReportParser#setRenderOptions(oIRenderTask,OutputStream)
     */
     @Override
     protectedvoidsetRenderOptions(IRenderTasktask,OutputStreamout){
     HTMLRenderOptionoptions=newHTMLRenderOption();
     options.setOutputStream(out);
     options.setEmbeddable(true);
     task.setRenderOption(options);
     }