BIRT Viewer 2.2 參數(shù)設(shè)置詳解
作者：會(huì)飛的球球
2007.08.24
BIRT作為一款功能強(qiáng)大的開(kāi)源報(bào)表工具，其版本的升級(jí)更新速度也非常快，從1.0到2.0，一直到最新的2.2.1版本，無(wú)論從功能上還是性能上都得到了極大的提高和擴(kuò)充。BIRT也提供了一個(gè)標(biāo)準(zhǔn)的J2EE實(shí)現(xiàn)組件，可以發(fā)布到支持J2EE應(yīng)用的web server服務(wù)器上，可以對(duì)生成的報(bào)表進(jìn)行預(yù)覽等操作。在大家使用BIRT Viewer的時(shí)候，可能會(huì)對(duì)它日益紛繁的參數(shù)設(shè)置如云里霧里，在網(wǎng)上論壇里也有很多人碰到這樣哪樣的問(wèn)題，同時(shí)官方的文檔也不細(xì)致不全。所以我就對(duì)這些參數(shù)進(jìn)行了一個(gè)簡(jiǎn)單系統(tǒng)的總結(jié)，希望能對(duì)大家的BIRT開(kāi)發(fā)有所幫助。這些參數(shù)以2.2.1版本為準(zhǔn)，請(qǐng)大家特別注意。
1. Servlet模式說(shuō)明
查看BIRT Viewer自帶的web.xml文件，可以看到有以下幾個(gè)pattern：
frameset ---- 采用Ajax框架，可以顯示工具條，導(dǎo)航條和TOC面板，實(shí)現(xiàn)復(fù)雜的操作，如分頁(yè)處理，導(dǎo)出數(shù)據(jù)，導(dǎo)出報(bào)表，打印等等。該模式下會(huì)自動(dòng)生成report document文件(預(yù)覽report design文件)到特定的目錄(用戶可以用參數(shù)指定，也可以定義在web.xml里)。采用Ajax，速度較慢。
run ---- 也采用Ajax框架，但不實(shí)現(xiàn)frameset的復(fù)雜功能，不會(huì)生成臨時(shí)的report document文件(預(yù)覽report design文件)，也不支持分頁(yè)，這個(gè)主要是應(yīng)用在BIRT Designer里的preview tab里，可以支持cancel操作，其它不怎么常用。采用Ajax，速度較慢。
preview --- 沒(méi)有用到Ajax框架，直接調(diào)用底層Engine API對(duì)報(bào)表進(jìn)行render，把生成的報(bào)表內(nèi)容直接輸出到瀏覽器。這種模式和run模式調(diào)用的是相同的Engine API，唯一區(qū)別在于run采用Ajax獲取報(bào)表內(nèi)容，而preview直接輸出到瀏覽器。如果要支持分頁(yè)，用戶需要在URL上定義__page和__pagerange參數(shù)，這兩個(gè)參數(shù)也會(huì)在后面詳細(xì)說(shuō)明。需要特別說(shuō)明的是，在這幾種預(yù)覽模式中，preview的速度是最快的。
document --- 該模式主要是為了從report design文件生成report document文件。用戶可以在URL上提定document文件生成存放的路徑(存放在server端)，如果未指定，會(huì)直接生成rptdocument發(fā)送到客戶端瀏覽器，用戶可以下載到客戶端。
output --- 該模式類似于frameset，會(huì)自動(dòng)生成report document文件(預(yù)覽report design文件)，區(qū)別在于output不采用Ajax，而是將生成的報(bào)表內(nèi)容直接輸出到瀏覽器。
parameter --- 該模式主要用于生成一個(gè)參數(shù)對(duì)話框，一般用戶不常用，用戶可以直接通過(guò)提供的JSP Tag--parameterPage去實(shí)現(xiàn)參數(shù)對(duì)話框，不需要直接調(diào)用。
download --- 用于導(dǎo)出報(bào)表數(shù)據(jù)為CSV格式，當(dāng)你使用frameset工具條里的導(dǎo)出數(shù)據(jù)功能時(shí)，會(huì)用到這個(gè)模式。
2. web.xml里的參數(shù)設(shè)置
web.xml文件里有許多參數(shù)，用戶應(yīng)該根據(jù)自已的需求出發(fā)對(duì)這些參數(shù)有一個(gè)深入的了解。下面我會(huì)對(duì)這些參數(shù)一一做以說(shuō)明。
[BIRT_VIEWER_LOCALE]
設(shè)置默認(rèn)的Locale信息，暫時(shí)沒(méi)有太大意義。因?yàn)長(zhǎng)ocale的信息，首先以URL上定義的__locale為準(zhǔn)，如果沒(méi)有定義，會(huì)找到當(dāng)前瀏覽器的Locale信息，最后才會(huì)用到這里定義的信息。
[BIRT_VIEWER_WORKING_FOLDER]
設(shè)置BIRT Viewer的工作目錄。用戶可以把report design或是report document文件存放在這個(gè)目錄下，這樣就可以在URL上采用相對(duì)路徑去預(yù)覽這些報(bào)表文件了。默認(rèn)是當(dāng)前根目錄。
當(dāng)前支持三種形式：
相對(duì)路徑 --- 這個(gè)相對(duì)當(dāng)前的WEB應(yīng)用的context root.
絕對(duì)路徑
JAVA系統(tǒng)變量 --- 可以在啟動(dòng)服務(wù)器時(shí)，定義JVM的系統(tǒng)變量，如java –Dmyworkingfolder=D:/reports。這樣就可以在web.xml中用${myworkingfolder}進(jìn)行引用了。
[BIRT_VIEWER_DOCUMENT_FOLDER]
設(shè)置生成的document文件的存放路徑。默認(rèn)是documents目錄。路徑設(shè)置同上。
[WORKING_FOLDER_ACCESS_ONLY]
簡(jiǎn)單的報(bào)表訪問(wèn)限制控制實(shí)現(xiàn)，如果設(shè)為true,哪就只能預(yù)覽存放在工作目錄下的報(bào)表文件。默認(rèn)值是false。
[BIRT_VIEWER_IMAGE_DIR]
設(shè)置生成的臨時(shí)圖片的存放路徑。默認(rèn)是report/images目錄。路徑設(shè)置同工作目錄設(shè)置。
[BIRT_VIEWER_LOG_DIR]
設(shè)置生成的日志文件存放路徑。默認(rèn)是logs目錄。路徑設(shè)置同工作目錄設(shè)置。
[BIRT_VIEWER_LOG_LEVEL]
設(shè)置日志的level，可選的值有：ALL|SEVERE|WARNING|INFO|CONFIG|FINE|FINER|FINEST|OFF。級(jí)別由高到低。
[BIRT_VIEWER_SCRIPTLIB_DIR]
設(shè)置用戶script lib文件的存放目錄( 在報(bào)表中用到的Java Event Handler Class )。默認(rèn)值是scriptlib。路徑設(shè)置同工作目錄設(shè)置。
[BIRT_RESOURCE_PATH]
設(shè)置用戶資源存放路徑，這些資源包括library文件，image文件等。默認(rèn)是當(dāng)前根目錄。路徑設(shè)置同工作目錄設(shè)置。
[BIRT_VIEWER_MAX_ROWS]
設(shè)置獲取dataset的最大記錄數(shù)。主要應(yīng)用于設(shè)計(jì)報(bào)表的時(shí)候，預(yù)覽報(bào)表如果記錄數(shù)太多，會(huì)花費(fèi)很多的時(shí)間，也可能會(huì)引起out of memory問(wèn)題。默認(rèn)是不限制。
[BIRT_VIEWER_MAX_CUBE_LEVELS]
設(shè)置CUBE查詢的最大級(jí)數(shù)。和前面的參數(shù)作用類似。默認(rèn)是不限制。
[BIRT_VIEWER_CUBE_MEMORY_SIZE]
設(shè)置在生成CUBE時(shí)，可以寫(xiě)在memory中的最大值，單位是MB。可以提高效率，寫(xiě)在內(nèi)存會(huì)比直接寫(xiě)在硬盤(pán)快很多。但同時(shí)也要注意內(nèi)存占用的問(wèn)題。
[BIRT_OVERWRITE_DOCUMENT]
該參數(shù)主要用于frameset/output模式，它們會(huì)生成臨時(shí)的document文件上。如果設(shè)為true，則每次刷新頁(yè)面時(shí)，都會(huì)重新去生成document文件，如果為false，則不會(huì)重新生成，只會(huì)用原來(lái)的document文件去生成報(bào)表內(nèi)容。
[BIRT_VIEWER_CONFIG_FILE]
定義properties文件的路徑，不可以修改。
[BIRT_VIEWER_PRINT_SERVERSIDE]
在frameset工具條上，提供有后臺(tái)服務(wù)器打印的功能，該參數(shù)可以設(shè)置是打開(kāi)還是關(guān)閉后臺(tái)打印的功能。默認(rèn)是打開(kāi)。可選值為: ON 和 OFF。
[HTML_ENABLE_AGENTSTYLE_ENGINE]
這個(gè)參數(shù)是會(huì)傳遞給Engine的，主要用于一些CSS的兼容性方面的問(wèn)題。默認(rèn)值是true。
3. viewer.properties參數(shù)設(shè)置
viewer.properties文件主要是定義一些擴(kuò)展的參數(shù)。
# configurable variable for JSP base href. Please uncomment the below line.
#base_url=http://127.0.0.1:8080
該設(shè)置主要應(yīng)用于代理服務(wù)器的情況下，在使用代理服務(wù)器后，從request里獲取的URI并非真正的URI，需要在這里定義。
# [EXTENSION SETTING]
viewer.extension.html=html
viewer.extension.pdf=pdf
viewer.extension.postscript=ps
viewer.extension.doc=doc
viewer.extension.xls=xls
viewer.extension.ppt=ppt
定義輸出的報(bào)表文件的后綴名，和format相關(guān)聯(lián)。
# [OUTPUT FORMAT LABEL NAME]
viewer.label.html=HTML
viewer.label.pdf=PDF
viewer.label.postscript=PostScript
viewer.label.doc=Word
viewer.label.xls=Excel
viewer.label.ppt=PowerPoint
定義導(dǎo)出報(bào)表對(duì)話框里的報(bào)表格式列表，和format相關(guān)聯(lián)，這樣名字會(huì)更有意義。
# [CSV SEPARATOR]
viewer.sep.0=,
viewer.sep.1=;
viewer.sep.2=:
viewer.sep.3=|
viewer.sep.4=\t
支持多種CSV分隔符，用戶也可以增加新的分隔符(只支持char，而不是string)。但同時(shí)需要修改JSP文件和Messages.properties文件。
# [LOGGERS]
# "logger."+class=level
# if no level is specified or the text "DEFAULT",
# then the default level from the web.xml will be used
logger.org.eclipse.datatools.connectivity.oda=DEFAULT
logger.org.eclipse.datatools.enablement.oda=DEFAULT
當(dāng)前的日志都是通過(guò)Engine輸出的，如果需要其它組件的日志輸出，可以在這里定義。注意格式必須為logger.org……。而且該組件必須實(shí)現(xiàn)了java的logger。
可以單獨(dú)為該組件設(shè)置日志級(jí)別，如果設(shè)為DEFAULT，就會(huì)使用web.xml里的設(shè)置。
4. URL參數(shù)
下面是一些主要用到的URL參數(shù)。
“__report”
定義要預(yù)覽的rptdesign文件路徑，支持相對(duì)路徑和絕對(duì)路徑，相對(duì)路徑是相對(duì)于web.xml中定義的工作目錄。
“__document”
定義要預(yù)覽的rptdocument文件路徑，同樣支持相對(duì)和絕對(duì)路徑。相對(duì)路徑是相對(duì)于web.xml中定義的工作目錄。在同時(shí)定義了__report和__document參數(shù)時(shí)，以__document為優(yōu)先，如未找到相應(yīng)的document文件，才會(huì)從design文件生成document文件(frameset/output)或是直接去render這個(gè)design文件(preview/run)。
“__title”
定義報(bào)表顯示的標(biāo)題。
“__showtitle”
是否顯示frameset模式下上方的標(biāo)題部分。true | false
“__toolbar”
是否顯示frameset模式下的工具條。true | false
“__navigationbar”
是否顯示frameset模式下的導(dǎo)航條。true | false
“__parameterpage”
是否強(qiáng)制彈出或不彈出報(bào)表參數(shù)對(duì)話框。true | false
“__format”
輸出報(bào)表的格式，默認(rèn)為html。現(xiàn)在支持：pdf | doc | xls | postscript | ppt
“__locale”
設(shè)置Locale信息，如 __locale=zh_CN， 注意必須是國(guó)家加語(yǔ)言。
“__svg”
設(shè)置chart輸出是否以SVG格式輸出。true | false
frameset和run模式下，會(huì)采用javascript判斷客戶端瀏覽器是否支持svg，但并非對(duì)所有瀏覽器有效。
“__bookmark”
設(shè)置頁(yè)面要定位的書(shū)簽名字。
“__istoc”
指定定位的書(shū)簽是不是一個(gè)TOC名字。如為true,就會(huì)根據(jù)__bookmark參數(shù)值去獲取一個(gè)真正的書(shū)簽名，從而實(shí)現(xiàn)正常的跳轉(zhuǎn)。這個(gè)主要用于定位到一個(gè)TOC上。
“__rtl”
指定HTML頁(yè)面輸出是否需要right to left。支持不同國(guó)家的閱讀習(xí)慣，如阿拉伯國(guó)家是從右到左的。
“__page”
指定要輸出的報(bào)表頁(yè)數(shù)，這個(gè)依賴于報(bào)表的分頁(yè)設(shè)計(jì)(page break)。
“__pagerange”
指定要輸出的報(bào)表頁(yè)數(shù)范圍。如1,3,5-9。
“__resourceFolder”
定義資源目錄路徑。同web.xml中的BIRT_RESOURCE_PATH設(shè)置。
“__asattachment”
是否以附件方式下載報(bào)表，如生成PDF或是其它格式里。默認(rèn)是inline。
“__masterpage”
是否要顯示master page。true | false
“__designer”
該參數(shù)主要是應(yīng)用在BIRT Designer環(huán)境下，如會(huì)讀取cache的報(bào)表參數(shù)等等，一般不用。true | false
“__overwrite”
該參數(shù)同web.xml定義的參數(shù)，不過(guò)web.xml里是全局設(shè)置，在URL上通過(guò)參數(shù)可以定義本次操作的設(shè)置。
“__imageID”
內(nèi)部參數(shù)，用于image的引用，一般不用。
“__maxrows”
設(shè)置Dataset查詢的最大記錄數(shù)，要注意這個(gè)設(shè)置是全局的，會(huì)影響后面所有的請(qǐng)求。主要用于BIRT Designer下，提高報(bào)表設(shè)計(jì)效率。同web.xml中的BIRT_VIEWER_MAX_ROWS設(shè)置。
“__maxlevels”
設(shè)置查詢獲取Cube的最大級(jí)數(shù)。同上面的__maxrows，也主要用于BIRT Designer設(shè)計(jì)環(huán)境。
同web.xml中的BIRT_VIEWER_MAX_CUBE_LEVELS設(shè)置。
“__cubememsize”
同web.xml中的BIRT_VIEWER_CUBE_MEMORY_SIZE參數(shù)設(shè)置。
“__instanceid”
如果查看BIRT輸出的HTML代碼，你就可以看到一些HTML Element會(huì)有一個(gè)iid的屬性(如table)，這個(gè)就是instanceid。這個(gè)是Engine動(dòng)態(tài)生成的，不可提前預(yù)知。所以你需要從HTML代碼中得到這個(gè)值。該參數(shù)主要是為了獲取reportlet(報(bào)表片斷，如只輸出報(bào)表中的一個(gè)Table或是一個(gè)Chart)。需要配合__isreportlet參數(shù)。
“__isreportlet”
指定當(dāng)前輸出是不是一個(gè)reportlet。true | false
特別說(shuō)明：為了輸出一個(gè)reportlet，BIRT現(xiàn)在提供兩種方式。
1． 為要輸出的對(duì)象(表格或是Chart)定義一個(gè)bookmark，然后可以用下面的URL輸出reportlet.
http://localhost:8080/birt/frameset?__report=test.rptdesign&__bookmark=bk&__isreportlet=true
2． 采用instanceid，但這個(gè)值事先是無(wú)法預(yù)知的，需要預(yù)覽一次后從HTML代碼中得到。然后用下面的URL輸出reportlet.
http://localhost:8080/birt/output?__report=test.rptdesign&__instanceid=iid&__isreportlet=true
還有就是要注意，reportlet只支持document文檔。如果是預(yù)覽design文檔去輸出reportlet，就必須要使用frameset/output(自動(dòng)生成document文檔)。
“__clean”
BIRT里臨時(shí)生成的一些文件都是和session相關(guān)的，比如臨時(shí)document文件，還有image文件。這些文件也可以通過(guò)session進(jìn)行管理，這個(gè)參數(shù)就是指定是否需要在session timeout的時(shí)候清除這些臨時(shí)文件。默認(rèn)值是true。
true | false
“__dpi”
可以設(shè)置輸出Chart的dpi數(shù)值。
“__fittopage”
暫時(shí)這個(gè)參數(shù)只對(duì)PDF和postscript格式報(bào)表有效，指定是否調(diào)整至適合頁(yè)面。
“__pagebreakonly”
暫時(shí)這個(gè)參數(shù)只對(duì)PDF和postscript格式報(bào)表有效，指定是否只采用BIRT報(bào)表內(nèi)定的分頁(yè)設(shè)置。這個(gè)參數(shù)一般需要和__fittopage聯(lián)合使用。
“__agentstyle”
同web.xml中的HTML_ENABLE_AGENTSTYLE_ENGINE參數(shù)設(shè)置。
========================== 后臺(tái)Server端打印相關(guān)參數(shù) ==========================
“__action”
定義執(zhí)行的指令名稱。當(dāng)前只支持print指令，用于后臺(tái)服務(wù)器打印。
“__printer”
后臺(tái)打印機(jī)名稱。
“__printer_copies”
對(duì)應(yīng)打印機(jī)的打印份數(shù)參數(shù)。
“__printer_collate”
對(duì)應(yīng)打印機(jī)的雙面打印參數(shù)。
“__printer_duplex”
對(duì)應(yīng)打印機(jī)的duplex參數(shù)。
“__printer_mode”
對(duì)應(yīng)打印機(jī)的模式參數(shù)。是單色還是彩色。
“__printer_pagesize”
對(duì)應(yīng)打印機(jī)的紙型參數(shù)。比如A4。
===============================================================================
========================== JSP Tag相關(guān)參數(shù) ===================================
“__id”
viewer的ID號(hào)，這個(gè)參數(shù)一般不常用，主要用于JSP Tag中，如在一個(gè)頁(yè)面插入兩個(gè)BIRT Viewer，而且預(yù)覽同一個(gè)報(bào)表文件，這時(shí)候因?yàn)樵谝粋€(gè)session下面，所以需要用不同的ID去生成單獨(dú)的document文件。不至于都生成同一個(gè)document文件上，從而引發(fā)沖突。
“__pattern”
在JSP Tag中用于指定要提交的Servlet Pattern名字，如frameset/output/run/preview等。主要用于采用parameter模式生成parameter dialog對(duì)話框時(shí)。
“__target”
可以指定提交到的窗口名稱。如_blank,_self等。
“__nocache”
指定是否會(huì)用到cache的報(bào)表參數(shù)值，這些cache的值一般保存在rptconfig文件里。在設(shè)計(jì)報(bào)表并預(yù)覽的時(shí)候，可以保存輸入的報(bào)表參數(shù)值。這個(gè)在runtime的時(shí)候不常用。
===============================================================================
========================== 報(bào)表參數(shù)相關(guān) ===================================
“__isnull”
指定當(dāng)前的報(bào)表參數(shù)為null值，后面是報(bào)表的參數(shù)名。
“__islocale”
指定當(dāng)前的報(bào)表參數(shù)值是和Locale/Format相關(guān)的，必須用特定的Locale/Format轉(zhuǎn)化參數(shù)值(從String轉(zhuǎn)化為Object)。格式為_(kāi)_islocale=paramName。
“__isdisplay__”
指定報(bào)表參數(shù)的displayText值,格式為_(kāi)_isdisplay__paramName=displayText。可以在報(bào)表中引用displayText值，如params[“p1”].displayText。
在URL上傳displayText時(shí)如下(報(bào)表參數(shù)名為p1)：
&__isdisplay__p1=hello
“__islocale__”
指定該報(bào)表參數(shù)值是Locale/Format相關(guān)的，同時(shí)給定了參數(shù)值。格式為_(kāi)_islocale__paramName=paramValue。
===============================================================================
========================== Export Data參數(shù) ===================================
“__exportEncoding”
該參數(shù)應(yīng)用于導(dǎo)出數(shù)據(jù)為CSV中，可以指定導(dǎo)出的文件編碼，如GBK或是GB2312等。
“__sep”
該參數(shù)應(yīng)用于導(dǎo)出數(shù)據(jù)為CSV中，可以指定數(shù)據(jù)分隔符，如逗號(hào)，冒號(hào)等。
“__exportdatatype”
該參數(shù)應(yīng)用于導(dǎo)出數(shù)據(jù)為CSV中，可以指定是否輸出數(shù)據(jù)類型。true | false
“ResultSetName”
要導(dǎo)出數(shù)據(jù)的記錄集名字。
“SelectedColumnNumber”
要導(dǎo)出的欄位數(shù)。
“SelectedColumn”
要導(dǎo)出的數(shù)據(jù)欄位名稱。
具體可以查看BirtSimpleExportDataDialog.js文件。
===============================================================================
5. 其它參數(shù)設(shè)置
在BIRT Viewer里還有一個(gè)比較特殊的參數(shù)應(yīng)用，就是用戶可以自定義自已的servlet，然后傳遞對(duì)象到Application Context中，在報(bào)表中就可以從全局的Application Context去獲取到這個(gè)對(duì)象。
這里相關(guān)的有兩個(gè)內(nèi)定的參數(shù)，AppContextKey和AppContextValue。下面是一個(gè)簡(jiǎn)單的示例。
public void service( HttpServletRequest request,
HttpServletResponse response ) throws ServletException,
IOException, BirtException
{
String myKeyName = "mykey";
List values = new ArrayList();
values.add( "hello" );
values.add( new Date() );
request.setAttribute( "AppContextKey", myKeyName );
request.setAttribute( "AppContextValue", values );
RequestDispatcher rd = request.getRequestDispatcher( "/frameset" );
rd.include( request, response );
}