birt runtime 報表接口(1)

當啓動runtime項目後咱們就可使用url去訪問項目瞭如：

http://localhost:8080/birt/frameset?__report=blank.rptdesign

如上是一個frameset模式，並經過__report指定了要展現的報表。

先說birt runtime提供的模式

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 ――該模式主要用於生成一個參數對話框，通常用戶不經常使用，用戶能夠


download ――用於導出報表數據爲CSV格式，當你使用frameset工具條裏的導出數據功能時，會用到這個模式。


extract ——用於導出報表數據爲CSV格式，當你使用frameset工具條裏的導出數據功能時，會用到這個模式。
咱們在web.xml也能夠看出

<servlet>
	<servlet-name>EngineServlet</servlet-name>
		<servlet-class>org.eclipse.birt.report.servlet.BirtEngineServlet</servlet-class>
	</servlet>

	<servlet-mapping>
		<servlet-name>ViewerServlet</servlet-name>
		<url-pattern>/frameset</url-pattern>
	</servlet-mapping>

	<servlet-mapping>
		<servlet-name>ViewerServlet</servlet-name>
		<url-pattern>/run</url-pattern>
	</servlet-mapping>

	<servlet-mapping>
		<servlet-name>EngineServlet</servlet-name>
		<url-pattern>/preview</url-pattern>
	</servlet-mapping>

	<servlet-mapping>
		<servlet-name>EngineServlet</servlet-name>
		<url-pattern>/download</url-pattern>
	</servlet-mapping>

	<servlet-mapping>
		<servlet-name>EngineServlet</servlet-name>
		<url-pattern>/parameter</url-pattern>
	</servlet-mapping>

	<servlet-mapping>
		<servlet-name>EngineServlet</servlet-name>
		<url-pattern>/document</url-pattern>
	</servlet-mapping>

	<servlet-mapping>
		<servlet-name>EngineServlet</servlet-name>
		<url-pattern>/output</url-pattern>
	</servlet-mapping>

	<servlet-mapping>
		<servlet-name>EngineServlet</servlet-name>
		<url-pattern>/extract</url-pattern>
	</servlet-mapping>

url參數說明

__report    定義要預覽的rptdesign文件路徑，支持相對路徑和絕對路徑，相對路徑是相對於web.xml中定義的工做目錄。 默認爲${birt home}

<context-param>
		<param-name>BIRT_VIEWER_WORKING_FOLDER</param-name>
		<param-value></param-value>
	</context-param>

__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查詢的最大記錄數，要注意這個設置是全局的，會影響後面全部的請求。主要用於BIRTDesigner下，提升報表設計效率。同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, 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文件上，從而引起衝突。
_vpattern 在 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 要導出的數據欄位名稱。