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