轉-Pentaho技術白皮書中文版（三）--構建新組件

這個指南描述了爲什麼及如何添加一個新組件進 Pentaho Business Intelligence (BI) 套件。假設你在讀這篇文檔以前，已經讀了且理解了如下兩篇指南：

Ø         技術白皮書

Ø         建立 Solutions 指南

或繼續閱讀這篇文檔中的如下章節：

?       Architecture

?       BI Component APIs

?       Internal API

?       Why Create a Pentaho Component?

體系結構

This page last changed on Dec 05, 2006 by bseyler.

體系結構的設計使得每一個組件僅需做最少許的操做，就可完成它的任務。一個組件沒必要知道有關 schedulers，工做流引擎，audit logs，或其餘組件的任何信息。

控制流

若是某人或某物須要 Pentaho Solution Engine 執行一個 action sequence 時，就執行 BI 組件。用戶，schedulers，web 服務，工做流引擎和 API 調用都可執行 Action sequences。在全部的狀況下，調用者可爲 action sequence 提供參數。除了請求中的參數，action sequence 可定義來自其餘地方的參數，例如一個 session。這一節和圖表描述了當執行一個 action sequence 時發生的事件的順序。

1.       啓動。在服務層調用一個對象，請求執行一個 action sequence。這些對象使用一個實現了 org.pentaho.core.services.IactionRequestHandler 的 request handler 對象，建立org.pentaho.solution.SolutionEngine 的一個實例，或使用 org. pentaho.core.solution.SolutionHelper 中的 helper 方法。在每種狀況下，parameters providers 被傳送到 solution engine。request handlers 和 solution helper 建立 SolutionEngine 的一個實例，並調用它的 'execute' 方法，指定要執行的 action sequence 的路徑和名字，以及 parameter provider。

能夠完成這個的對象實例有：

Ø         Servlet：org.pentaho.ui.servlet.ViewAction

Ø         UI 組件：org.pentaho.ui.component.ActionComponent

Ø         Web 服務：org.pentaho.ui.servlet.HttpWebService

Ø         Scheduler：org.pentaho.plugin.quartz.QuartzExecute

Ø         API：org.pentaho.core.solution.SolutionHelper

2. Solution Engine 的 'execute' 方法：

Ø         檢查已經提供了 action sequence 路徑和名字。

Ø         建立 IRuntimeElement 和 IruntimeContext 的實例，實例建立的詳細信息以及它和調用會話的關聯被添加進 audit log。若是 process 正長時間運行，Runtime Element 存儲 action sequence 的狀態，Runtime Context 將處理組件的執行。

Ø         調用 Solution Repository 裝載 action sequence。若是不能找到 action sequence，返回一個錯誤給調用者，failure 被 audited。

Ø         調用 Runtime Context 的 ‘validateSequence’ 方法。

3. Runtime Context 的 'validateSequence' 方法：

Ø         將 action sequence 的日誌級別設置須要的級別(可由初始調用者指定)

Ø         爲 action sequence 中定義的每一個 action 建立組件的一個實例。若是 sequence 包括兩個使用 EmailComponent 的 actions，建立組件的兩個實例。不會對兩個 actions 使用組件的相同實例。Runtime Context 須要 BI Components 有一個不接收參數的默認構造函數。

Ø         爲每個組件提供不一樣的對象，例如調用者的 session，須要的 logging level 和 Runtime Context。

Ø         調用每一個組件的 ‘validate’ 方法。

4. 組件的 'validate' 方法：

Ø       調用它本身的 ‘validateSystemSettings’ 方法來驗證任何它須要的 system-wide 設置。

Ø       調用它本身的 ‘validateAction’ 方法驗證對它可用的輸入，資源和輸出(如在 action sequence 中定義的)使之執行是足夠的。

若是對任何組件，這些驗證中的一個失敗了，action sequence 的執行被終止，狀態被返回給調用者。

5. Solution Engine 的 ‘execute’ 方法調用 Runtime Context 的 ‘executeSequence’ 方法。

6.  Runtime Context的 'executeSequence' 方法：逐步循環檢查 action sequence 中的 action 定義，對於每一個定義的 action，調用它的 ‘executeAction’方法。

7.  Runtime Context 的 'executeAction' 方法：

Ø       Audits 組件執行的起點。

Ø       解釋 action sequence 中定義的組件可用的參數，例如來自 request parameter provider，session parameter provider 或其餘組件的輸出。

Ø       調用組件的 ‘init’ 方法。

8.    組件的 ‘init’ 方法執行任何它須要的任何初始化步驟。

9.    Runtime Context 的 ‘executeAction’ 方法調用它的 ‘executeComponent’ 方法。

10.      Runtime Context 的 ‘executeComponent’ 方法調用組件的 ‘execute’ 方法。

11.      組件的 ‘execute’ 方法執行完成它的功能所必需的步驟。

12.      Runtime Context 的 ‘executeComponent’ 方法調用組件的 ‘done 方法。

13.      組件的 ‘done’ 方法執行任何須需的 clean-up 步驟。

14.      Runtime Context 的 ‘executeAction’ 方法 audits 組件執行的終點。

15.      Solution Engine 的 'execute' 方法

Ø       Audits action sequence 執行的終點

Ø       將 Runtime Context 返回給調用者

16.      終點。調用者可以使用 Runtime Context 來：

Ø       獲取執行的最終狀態

Ø       獲取 action sequence 的 output 對象

Ø       獲取調試或錯誤信息

 

Solution Engine	Runtime Context	BI Component
1. start	1. start	1. start
request handlers 和 solution helper建立 SolutionEngine 的一個實例，並調用它的 ‘execute’ 方法，指定要執行的 action sequence 的路徑和名字，以及 parameter provider。	request handlers 和 solution helper 建立 SolutionEngine 的一個實例，並調用它的 ‘execute’ 方法，指定要執行的action sequence 的路徑和名字，以及parameter provider。	request handlers 和 solution helper建立 SolutionEngine 的一個實例，並調用它的 ‘execute’ 方法，指定要執行的 action sequence 的路徑和名字，以及 parameter provider。
2. execute() Ø         檢查已經提供了 action sequence 的路徑和名字。 Ø         建立IRuntimeElement和IRuntimeContext 的一個實例。 Ø         調用Solution Repository 裝載 action sequence。 Ø         調用 Runtime Context的 'validateSequence' 方法。
	3. validateSequence() Ø         設置 logging level。 Ø         建立一個實例組件。 Ø         爲每一個組件提供它須要的不一樣系統對象。 Ø         調用每一個組件的 ‘validate’方法。
		4. validate() Ø         調用它的‘validateSystemSettings’ 方法驗證它須要的任何 system­wide 設置。 Ø         調用它的 'validateAction'方法驗證輸入，資源和輸出。
5. execute() 調用 Runtime Context的'executeSequence' 方法。.
	6.  executeSequence() 循環逐步檢查調用 ‘executeAction’ 的 action sequence 中的action 定義
	7.  executeAction() Audits 一個組件執行的起點。解釋調用組件的 ‘init’ 方法的參數。
		8. init() 方法執行任何須需的初始化步驟
	9. executeAction()調用 'executeComponent'。
	10.  executeComponent()調用組件的 'execute' 方法。
		11. execute() 執行完成其功能必需的步驟。
	12. executeComponent()調用組件的 'done 方法。
		13. done() 執行任何須需的 clean-up 步驟
	14. executeAction() Audits 組件執行的終點。
15.  execute() Audits action sequence 執行的終點。返回 Runtime Context 給調用者。
16.  end 調用者可以使用 Runtime Context： Ø         獲取執行的最終狀態。 Ø         獲取 action sequence 的輸出對象 Ø         獲取調試或錯誤信息。

 

如圖所見，在 Solution Engine 的‘execute’ 和組件的 ‘execute’ 間僅有幾層方法調用。這個輕量級的框架很強大，但並無給系統帶來太大的處理負載。

BI Components 並無在對 Solution Engine 的調用間緩存，必須是線程安全的。

若是一個 BI 組件須要建立任何全局資源或調用任何靜態的初始化方法，必須編寫實現了IPentahoSystemListener 的一個類，並在‘system/pentaho.xml’ 中註冊。實例請參考org.pentaho.plugin.kettle.KettleSystemListener 和org.pentaho.plugin.jfreereport. JFreeReportSystemListener。

每一個 BI 組件都須要知道完成它的任務所須要的參數。例如，scripting 組件須要被提供腳本以被執行，而一個報表組件須要被提供報表模板，還要有數據。

BI 組件 APIs

This page last changed on Dec 04, 2006 by mlowery.

有四種建立 BI 組件的方式：從頭開始建立 BI 組件，將現有類轉換成 BI 組件，建立ComponentBase(org.pentaho.plugin.ComponentBase)的子類，或建立 SimpleComponent (org.pentaho.plugin.core.SimpleComponent) 的子類。

爲成爲 BI 組件，Java 對象必須實現 org.pentaho.core.component.IComponent 接口。 IComponent 接口擴展了其它兩個接口：org.pentaho.core.audit.IAuditable和org.pentaho.util.logging.ILogger。Pentaho 提供了實現了這些接口的類。

Pentaho 類層次以下所示：

org. pentaho.core.system. PentahoBase (實現 ILogger 和 Serializable) --> org .pentaho.core.system .PentahoMessenger

--> org.pentaho.plugin.ComponentBase (實現 IComponent 和 IAuditable) --> org.pentaho.plugin.core.SimpleComponent

--> other Pentaho-provided BI Components

你可在任何你喜歡的包裏建立你的 BI 組件，無論它是不是 Pentaho 類的子類。若是你使用一個非 Pentaho 包，就沒有不可訪問的必需方法。

擴展 SimpleComponent

這是建立一個新組件的最簡單的方式，推薦新手使用。

1.       建立一個新的 Java 類，它是 org.pentaho.plugin.core.SimpleComponent 的子類（擴展）。

2.       實現一個 executeAction () 方法和一個 getLogger () 方法。這些方法的描述請參考下面的 ‘Component Methods’。

擴展 ComponentBase

若是你的組件須要驗證它的輸入和/或系統設置，或須要執行任何初始化和/或清理，你應該擴展org.pentaho.plugin.ComponentBase。

1.       建立一個新的 Java 類，它是 org.pentaho.plugin.ComponentBase 的子類（擴展）。

2.       適當的在 init，validateSystemSettings，validateAction，executeAction，done 和 getLogger 方法中添加代碼。

將一個 Java 對象轉換成一個 BI 組件

若是你有一個現有對象，你想將之轉換成一個 BI 組件，有兩個選擇：

Ø         建立一個新對象，其是現有對象的子類，實現了必需的接口。

Ø         修改你的對象以實現必需的接口。

哪一種選擇更適合於你的特定對象將依賴於你的特定環境，但咱們建議建立一個子類，以保證你的源文件大小可管理。

若是你沒必要使用這個方法，可在這些類中找到建立你的新類所必需的大多數代碼：org.pentaho.core. system.PentahoBase，org.pentaho.core.system.PentahoMessenger 和org.pentaho.plugin.ComponentBase。爲使這個過程更簡單，咱們已建立了一個類，org.pentaho.plugin.ComponentSubclassExample，其包含你須要的代碼。

爲將一個 Java 類轉換成一個 BI 組件：

1.  從org.pentaho.plugin.ComponentSubclassExample 複製 imports，成員變量和方法進你的 Java 類。

2.  適當的在 init，validateSystemSettings，validateAction，executeAction ，done 和 getLogger 方法中添加代碼。

從頭開始建立組件

爲從頭開始建立一個組件，必須建立一個實現了接口 org.pentaho.core.component.IComponent 的新類。爲實現全部三個接口，須要實現大約 30 個方法。不推薦使用這個選項，假若有其餘選擇，就沒有必要採用這種方法。

組件方法

若是使用推薦的 3 個方法之一建立新組件，如下的方法就是須要被定製的 BI 組件方法，以提供你必需的功能。列出了方法，以使之在正常處理中被調用。依據建立你的組件的方法，不是全部的方法都是必需的。更多信息請參考以上章節。

done

This page last changed on Nov 29, 2006 by mbatchelor.

調用這個方法，使組件有機會執行必需的 cleanup 操做。

executeAction

This page last changed on Dec 04, 2006 by mlowery.

調用這個方法，組件就能執行它的功能。在這個方法中，你可調用其餘內部 API 方法獲取輸入值，獲取資源，詢問用戶參數，和獲取輸出流。一般，在 execute 方法中，一個組件將：

1.       收集輸入值。這些多是參數或組件設置。若是輸入值是不完整的，組件可中止執行，或提示用戶額外的信息。

2.       收集資源。這些多是模板或定義文件。

3.       獲取某類輸出 pipe(例如一個輸出流)。

4.       建立輸出內容。

5.       返回執行狀態。

咱們將使用 PrintComponent (org.pentaho.plugin.print.PrintComponent) 的 executeAction () 方法做爲一個實例(爲了清晰作了一些小的修改)。.

protected boolean executeAction() {

String printFileName = null;

IActionResource printFileResource = null;

// see if we are printing a file if (isDefinedInput ("print-file")) {

// get name of file to print

printFileName = getInputStringValue ("print-file");

}

InputStream inStream = null;

// Get name of printer to use

if (isDefinedInput ("printer-name")) {

printerName = getInputStringValue ("printer-name");

}

// try to find requested printer

PrintService printer = getPrinterInternal (printerName);

if (printer == null) {

// requested printer is not available

if (!feedbackAllowed()) {

// we are not allowed to prompt user for a printer, we have to fail

error( " requested printer "+printerName+" is not available" );

return false;

}

// prompt user for an available printer

// get a list of available print services

PrintService[] services = PrinterJob.lookupPrintServices ();

ArrayList values = new ArrayList();

// add each print service to our list of printers

for (int i = 0; i < services.length; i++) {

String value = services[ i].getName ();

values.add (value);

}

// create a parameter for user to select from

createFeedbackParameter ("printer-name",

"select a printer", "", null, values, null, "select");

return null;

} promptNeeded();

return true;

}

// Get number of copies

int copies = 1;

if (isDefinedInput("copies")) {

copies = Integer.valueOf (getInputStringValue ("copies")).intValue ();

// Check for a valid printFileName or printFile Resource

if (printFileName != null) {

try {

inStream = new FileInputStream(printFileName);

} catch (FileNotFoundException fnfe) {

error(fnfe.toString(), fnfe);

return false;

}

// Set input source for sending to driver.

InputSource source = new InputSource(inStream);

try {

Driver driver = new Driver(source, null);

PrinterJob pj = PrinterJob.getPrinterJob();

pj . setPrintService (printer);

PrintRenderer renderer = new PrintRenderer(pj, copies);

driver. setRenderer (renderer);

driver. run ();

} catch (Exception ex) {

error( "Could not print document", ex);

return false;

}

return true;

}

getLogger

This page last changed on Nov 29, 2006 by mbatchelor.

這個方法建立一個 Log 對象，其用於記錄你的組件的日誌信息。它必須被你的組件(而不是一個超類) 建立，這樣日誌就能夠正確記錄你的對象的類名。

僅用一行就實現了這個方法。

public Log getLogger() {

return LogFactory.getLog(this.class);

}

init

This page last changed on Nov 30, 2006 by bseyler.

調用這個方法，以容許組件執行任何在調用 executeAction () 以前必需的初始化操做。

validateAction

This page last changed on Dec 04, 2006 by mlowery.

調用這個方法，使你的組件有機會驗證它有成功完成所需的輸入和資源。若是你從這個方法返回 ‘false’，將停止 action sequence 的執行。

這個方法應該僅用於檢查輸入是可用的，不該該用於檢查輸入的值，由於並不能保證在此刻運行的時候其可用。若是你的組件須要資源，例如在 action sequence 中，模板文件稱之爲 「new-employee-greeting」，你可經過調用 isDefinedResource (「new-employee-greeting」 做爲參數) 來檢查資源是可用的。

若是你的組件須要一個名爲 ‘employee-id’ 的輸入，你可經過調用 isDefinedInput (「employee-id」 做爲參數)檢查已經在 action sequence 中定義了它。

若是你的組件須要一個名爲 「employee-greeting-email-text」 的輸出，你可經過調用 isDefinedOutput (「employee-greeting-email-text」 做爲參數) 來檢查它已經在 action sequence 中定義了。

你的 validateAction () 方法如今應該以下所示：

public boolean validateAction() {

if (!isDefinedResource ("new-employee-greeting")) {

error( "A template called 'new-employee-greeting' has not been defined" );

return false;

}

if (!isDefinedInput ("employee-id")) {

error( "An employee id is needed" );

return false;

}

if (!isDefinedOutput("employee-greeting-email-text") ) {

error("An output called 'employee-greeting-email-text' has not been defined" );

return false;

}

return true;

}

注意咱們僅僅檢查以查看是否已經定義了輸入，但不獲取輸入值。EmailComponent 的 validateAction以下所示：

public boolean validateAction() {

// make sure that we can get a 'to' email address

if (!isDefinedInput("to")) {

error (Messages. getErrorString ("Email. ERROR _0001 _TO _NOT _DEFINED",

getActionName ())); return false;

}

// make sure that we can get a subject for email

if (!isDefinedInput ("subject")) {

error (Messages. getErrorString ("Email. ERROR _0002 _SUBJECT _NOT _DEFINED",

getActionName ())); return false;

// make sure that we have either a plain text or html message for email if (!isDefinedInput ("message-plain") && !isDefinedInput ("message-html")) {

error (Messages. getErrorString ("Email. ERROR _0003 _BODY _NOT _DEFINED",

getActionName ()));

return false;

}

return true;

}

注意這個方法並不檢查可選參數，例如 ‘cc’，‘bcc’，或 email 附件，但僅檢查組件成功運行所需的最少參數。

你沒必要要求每一個單獨的資源，輸入，或輸出。若是你願意，你可以使用 java.util.Set 對象，其包含可用 items 的名字。可經過調用 getResourceNames ()，getInputNames() 和 getOutputNames ()獲取這些 sets。例如：

Set inputNames = getInputNames();

if( !inputNames.contains( "param1" ) && !inputNames.contains( "param2" ) ) { error( "I need both param1 and param2" );

return false;

}

validateSystemSettings

This page last changed on Dec 04, 2006 by mlowery.

這個方法容許你的組件驗證它所需的任何系統設置，以保證正常運轉。例如，Kettle 組件(org.pentaho.plugin.kettle.KettleComponent) 檢查它的系統設置，以查看它是配置爲一個 file-based 仍是RBDMS-based repository，在另外一個實例中， email 組件(org.pentaho.plugin.email.EmailComponent) 使用它的系統設置鏈接到你的 email 服務器。

組件的 System-wide 設置應該存儲在 Pentaho solution 根目錄的 ‘system’ 文件夾的 XML 文檔中。系統設置對你的組件的每一個實例都是同樣的，當服務器或應用正運行時不會改變(直到被管理員手動改變)。

在系統文件夾中，你會看到子文件夾，例如 ‘kettle’，‘quartz’ 和 ‘smtp-email’。若是你的組件須要系統設置，你可建立一個文件夾來存儲你的設置，並將一個 XML 文件放進文件夾中。XML 文件可任意命名。在 XML 文檔中，你能夠任何你喜歡的格式排列設置。email 組件的設置文件提供設置文件的一個很好實例。在 solution 根目錄中，email 設置文件的路徑是 ‘system/smtp­email/email_config.xml’。

<email- smtp>

<!-- values within <properties> are passed directly to JavaMail API. For a list of valid properties see

http://java.sun.com/products/javamail/javadocs/index.html -->

<properties>

<!-- This is address of your SMTP email server for sending email. e.g. smtp.pentaho.org -->

<mail. smtp . host></mail. smtp . host>

<!-- This is port of your SMTP email server. Usually this is 25. For GMail this is 587 -->

<mail. smtp .port>2 5</mail. smtp .port>

<!-- transport for accessing email server. Usually this is smtp. For GMail this is smtps -->

<mail. transport .protocol>smtp</mail . transport .protocol>

<!-- Usually this is 'false'. For GMail it is 'true' --> <mail.smtp.starttls.enable>false</mail.smtp.starttls.enable>

<!-- Set to true if email server requires sender to authenticate --> <mail. smtp . auth>true< /mail. smtp. auth>

<!-- This is true if email server requires an SSL connection. Usually 'false'. For GMail this is 'true' -->

<mail. smtp. ssl>false</mail. smtp. ssl>

<!-- Output debug information from JavaMail API --> <mail. debug>false</mail .debug>

</properties>

<!-- This is default 'from' address that emails from Pentaho BI Suite will appear to come from e.g. joe.pentaho@pentaho.org --> <mail .from. default>j oe .pentaho@pentaho . org</mail .from. default>

<!-- This is user id used to connect to email server for sending email It is only required if email-authenticate is set to true

This is never sent or shown to anyone -->

<mail. userid></mail . userid>

<!-- This is password used to connect to email server for sending email It is only required if email-authenticate is set to true

This is never sent or shown to anyone --> <mail .password></mail .password>

</email-smtp>

email 組件經過調用 PentahoSystem.getSystemSetting() 訪問這些設置，例如：

String mailhost = PentahoSystem.getSystemSetting("smtp-email/email_config.xml", "mail.smtp.host", null);

getSystemSetting () 方法在系統配置文件中查找一個條目，並將之返回給組件。組件沒必要知道系統配置文件位於何處。

內部 API

This page last changed on Nov 30, 2006 by bseyler.

若是使用了以上 3 種推薦的建立組件的方法之一，內部組件 API 將可用。這個 API 提供了不少方法，使得組件可和他們正運行於其中的進程進行交互。

處理輸入

This page last changed on Dec 01, 2006 by bseyler.

方法提供了一種機制獲取組件的輸入。

getDataSource()

This page last changed on Dec 04, 2006 by mlowery.

參數：String

結果：javax.activation. DataSource

返回指定輸入的一個 DataSource。這個方法僅用於表示存儲於 Content Repository 中的 items 的輸入。在請求訪問一個輸出前，調用 isDefinedInput () 或 getInputNames () 很重要。由於若是你請求 action sequence 中沒有定義的輸出時，將會出錯。

getInputBooleanValue()

This page last changed on Dec 01, 2006 by bseyler.

參數：                                            String                                             inputName

                                                      boolean                                          defaultValue

結果：                                            boolean                                         

以 boolean 的形式返回輸入值。若是輸入值不是有效的 boolean，返回 defaultValue。在請求訪問一個輸出前調用 isDefinedInput () 或 getInputNames () 很重要，由於若是你請求 action sequence 中沒有定義的輸出時，將會出錯。

getInputLongValue()

This page last changed on Dec 01, 2006 by bseyler.

參數：                                            String                                             inputName

                                                      long                                               defaultValue

結果：                                            long                                              

以 long 的形式返回輸入值。若是輸入值不是有效的 long，返回 defaultValue。在請求訪問輸出前調用 isDefinedInput () 或 getInputNames () 很重要，由於若是你請求 action sequence 中沒有定義的輸出時，將會出錯。

getInputNames()

This page last changed on Dec 01, 2006 by bseyler.

參數：沒有

結果：java. util .Set

如 action sequence 所定義，返回可用輸入的名字。組件應使用這個方法(或 isDefinedInput ()) 驗證組件所須要的輸入在使用前是可用的。

getInputParameter()

This page last changed on Dec 01, 2006 by bseyler.

參數：String parameterName

結果：org.pentaho.core.runtime.Iaction   Parameter

返回表示一個輸入的 IActionParameter。使用這個 IActionParameter 對象，你能夠：

Ø         檢查一個 prompt 是否已經 pending for this input。

Ø         查找輸入值是否有有效值的一個列表。

Ø         查找是否已經指定了輸入值。

Ø         查找輸入是否有一個默認值。

Ø         查找輸入類型。

Ø         查找輸入值。

在請求訪問一個輸出前調用 isDefinedInput () 或 getInputNames () 很重要，由於若是你請求 action sequence 中沒有定義的輸出時，將會出錯。

getInputStream()

This page last changed on Dec 01, 2006 by bseyler.

參數：                                            String                                            inputName

結果：                                            java. io.InputStream                       

返回指定輸入的一個 InputStream。這僅僅當輸入值是 IContentItem 時有效。在請求訪問一個輸出前，調用 isDefinedInput () 或 getInputNames () 很重要，由於若是你請求 action sequence 中沒有定義的輸出時，將會出錯。

getInputStringValue()

This page last changed on Dec 01, 2006 by bseyler.

參數：                                            String                                            inputName

結果：                                            String                                           

以字符串的形式返回輸入值。若是值不是一個 String，調用它的 toString () 方法。在請求訪問一個輸出前，調用 isDefinedInput () 或 getInputNames () 很重要，由於若是你請求 action sequence中沒有定義的輸出時，將會出錯。

getInputValue()

This page last changed on Dec 05, 2006 by bseyler.

參數：                                            String                                            inputName

結果：                                            Object                                           

以一個 Object 的形式返回輸入值。在請求訪問一個輸出前調用 isDefinedInput () 或 getInputNames() 很重要，由於若是你請求 action sequence 中沒有定義的輸出時，將會出錯。

isDefinedInput()

This page last changed on Dec 01, 2006 by bseyler.

參數：                                            String                                            inputName

結果：                                            boolean                                         

返回是否已經在 action sequence 中定義了指定的輸入。組件應該使用這個方法(或 getInputNames ()) 驗證組件須要的輸入在使用前是可用的。

處理輸出

This page last changed on Dec 01, 2006 by bseyler.

這些是獲取組件的輸出信息的方法。包含但不侷限於內容和名字。

getDefaultOutputStream () - deprecated

This page last changed on Dec 01, 2006 by bseyler.

參數：沒有

結果：java. io.OutputStream

這個方法已經做廢了，若是你使用它的話，系統將在 audit log 和 server log 中記錄一條警告。提供它是爲了向後兼容性。新組件不該該使用這個方法。使用 getOutputStream () 代替之。

getOutputContentItem ()

This page last changed on Dec 01, 2006 by bseyler.

參數：String outputName

結果：org.pentaho.core.repository.IContentItem

對於特定輸出返回一個IContent Item 對象。content item 可用於訪問特定輸出的 output stream。在請求訪問一個輸出前，調用 isDefinedOutput () 或 getOutputNames () 很重要，由於若是你請求action sequence 中沒有定義的輸出時，將會出錯。

getOutputContentItem() - deprecated

This page last changed on Dec 01, 2006 by bseyler.

參數：沒有

結果：org.pentaho.core.repository.IContentItem

這個方法已經做廢了，若是你使用它的話，系統將在 audit log 和 server log 中記錄一條警告。提供它是爲了向後兼容性。新組件不該該使用這個方法。使用 getOutputStream ()，並傳送一個特定輸出的名字。

getOutputNames()

This page last changed on Dec 01, 2006 by bseyler.

參數：沒有

結果：java.util.Set

返回 action sequence 中定義的可用輸出的名字。組件應該使用這個方法(或 isDefinedOutput ()) 驗證組件的輸出在使用前已經可用。

getOutputPreference()

This page last changed on Dec 01, 2006 by bseyler.

參數：沒有

結果：int

一個組件可以使用這個方法找出 Runtime Context 對哪類輸出最感興趣。有效值存儲於org.pentaho.core.solution.IoutputHandler，是：

OUTPUT_TYPE_PARAMETERS

OUTPUT_TYPE_CONTENT

OUTPUT_TYPE_DEFAULT

getOutputStream ()

This page last changed on Dec 01, 2006 by bseyler.

參數：                                            String                                             outputName

                                                      String                                             mimeType

                                                      String                                             extension

結果：                                            java.io.OutputStream                     

從被請求的輸出中獲取一個輸出流。調用這個方法將在 Content Repository 中建立一個文件。在請求訪問一個輸出前調用 isDefinedOutput () 或 getOutputNames () 很重要，由於若是你請求 action sequence 中沒有定義的輸出時，將會出錯。

isDefinedOutput()

This page last changed on Dec 01, 2006 by bseyler.

參數：                                            String                                            outputName

結果：                                            boolean                                         

返回是否已經在 action sequence 中定義了指定輸出。組件應該使用這個方法(或 getOutputNames()) 驗證組件的輸出在使用前已經可用。

setOutputMimeType()

This page last changed on Dec 01, 2006 by bseyler.

參數：                                            String                                             outputName

結果：                                            String                                             mimeType

這設置指定輸出的 mime 類型。這用於 streamed 輸出。一些標準的 mime 類型有：

Ø         HTML：text/html

Ø         Plain text：text/plain

Ø         XML：text/xml

setOutputValue()

This page last changed on Dec 01, 2006 by bseyler.

參數：                                            String                                             outputName

                                                      Object                                            value

結果：                                            none                                             

設置輸出值。這個調用用於設置自動輸出值，例如一個 String。

在請求訪問一個輸出前，調用 isDefinedOutput () 或 getOutputNames () 很重要。由於若是你請求 action sequence 中沒有定義的輸出時，將會出錯。

處理資源

This page last changed on Dec 01, 2006 by bseyler.

These methods provide resource handling and feedback parameter management.

getResource()

This page last changed on Dec 05, 2006 by bseyler.

參數：String resourceName

結果：org.pentaho.core.solution.IactionResource

在請求訪問一個輸出前，調用 isDefinedResource () 或 getResourceNames () 很重要，由於若是你請求 action sequence 中沒有定義的輸出時，將會出錯。

getResou rceAsString ()

This page last changed on Dec 01, 2006 by bseyler.

參數：org.pentaho.core.solution.IActionResource resource

結果：String

以字符串的形式返回指定資源的內容。在請求訪問輸出前，調用isDefinedResource () 或getResourceNames () 很重要，由於若是你請求 action sequence 中沒有定義的輸出時，將會出錯。

if( isDefinedResource("message-template") ) { String template = getResourceAsString("message-template" ); }

getResourceDataSource()

This page last changed on Dec 01, 2006 by bseyler

參數：org.pentaho.core.solution.IActionResource resource

結果：javax.activation.DataSource

返回做爲一個 DataSource 對象的指定資源的內容。在請求訪問一個輸出以前，調用isDefinedResource () 或 getResourceNames () 很重要，由於若是你請求 action sequence 中尚未定義的一個輸出，將會出錯。

if( isDefinedResource("message-template") ) {

DataSource source = getResourceDataSource("message-template" );

}

getResou rceInputStream ()

This page last changed on Dec 01, 2006 by bseyler.

參數：org.pentaho.core.solution.IActionResource resource

結果：java.io.InputStream

返回特定資源內容的一個輸入流。在請求訪問一個輸出前，調用isDefinedResource () 或 getResourceNames () 很重要，由於若是你請求 action sequence 中尚未定義的一個輸出，將會出錯。

if( isDefinedResource("message-template") ) {

InputStream stream = getResourceInputStream("message-template" );

}

getResourceNames()

This page last changed on Dec 01, 2006 by bseyler.

參數：沒有

結果：java.util.Set

返回在 action sequence 中定義的可用資源的名字。這對檢查可用資源的名字頗有用，所以組件就不會請求不可用的資源。

isDefinedResource()

This page last changed on Dec 01, 2006 by bseyler.

參數：                                            String                                            resourceName

結果：                                            boolean

返回是否已經在 action sequence 中定義了指定資源。

處理用戶交互

This page last changed on Dec 01, 2006 by bseyler.

這些方法用於建立將顯示給用戶的提示信息。這對於自動生成參數頁頗有用。action sequence 中指定了用於建立頁面佈局的模板，它能夠是 HTML 模板或 XSLT 模板。若是沒有指定一個模板，使用一個默認的 XSLT (solution 文件夾中的 system/custom/xsl/DefaultParameterForm.xsl)。

createFeedbackParameter() - 3 個參數

This page last changed on Dec 01, 2006 by bseyler.

參數：                                            org. pentaho.core.runtime.Selecti nMapper selMap

                                                      String                                             fieldname

                                                      Object                                            defaultValues

結果：                                            none

TODO Insert explanation。

createFeedbackParameter() – 5 個參數

This page last changed on Dec 01, 2006 by bseyler.

參數：                                            String                                             fieldname

                                                      String                                             displayName

                                                      String                                             hint

                                                      String                                             defaultValue

                                                      boolean                                          visible

結果：                                            none                                             

這建立一個參數提示，其向用戶展示一個文本框。

fieldname: 指定這個提示的 form 元素的 id。當用戶點擊提交他們的選擇時這個 id 將出如今請求中。若是 action sequence 沒有定義匹配這個 id 的請求的輸入，組件將從不接收用戶選擇的值，在用戶無終止的被提示相同的信息的位置，就會出現死循環。

displayName:用戶將看做參數的 label 的文本。

hint:參數旁用戶可看到的幫助提示信息。

defaultValues: 當用戶看見提示頁時，自動爲其顯示的默認值。

visible: 一個flag，決定了用戶是否能看到 form 控件。若是這個設置成 ‘false’，建立一個 hidden form field。

createFeedbackParameter() – 7 個參數

This page last changed on Dec 01, 2006 by bseyler.

參數：                                            String                                             fieldname                     

                                                      String                                             displayName                 

                                                      String                                             hint                   

                                                      Object                                            defaultValues                

                                                      java/util/Set. html@javajava .util .Setval        ues       

                                                      java.util.Map                                   dispNames                   

                                                      String                                             displayStyle                  

結果：                                            none                                             

這建立一個參數提示，其向用戶展示一組可從中選擇的項目。組件必需指定選項列表。有關這個的一個很好的實例是 print 組件(org. pentaho.plugin.print.PrintComponent)，其建立了組件可用的打印機的一個列表，而後調用 createFeedbackParameter () 容許用戶選擇一個打印機。

fieldname: 爲這個提示指定 form 元素的 id。當用戶點擊提交他們的選擇時，這個 id 將出如今請求中。若是 action sequence 沒有定義匹配這個 id 的請求的輸入，組件將再也不接收用戶選擇的值，當用戶無終止的持續請求相同的東西時，就會出現死循環。

displayName: 用戶將看做參數的 label 的文本。

hint: 用戶將看到的參數旁的一個幫助提示。

defaultValues: 一個對象，其存儲了當用戶看見提示頁面時，自動爲用戶選擇的默認值。這個對象但是一個 String，或 String array。若是在 displayStyle 中指定的 control 類型不能選擇多個項，但爲 defaultValues 提供了一個 String array，不能預測選中的單一項。

values: 用戶可從其中選擇的值的有序列表。這個集合存儲了當用戶選擇什麼時，你但願組件接收的值。若是你但願用戶看到不一樣於這個列表中描述的名字的項目，組件必須提供一個 dispNames map。

dispNames: 一個 Map，其爲每一個值存儲了一個用戶友好的描述。若是 map 沒有爲給定值存儲一個描述，這個值必須顯示給用戶。若是沒有任何值的用戶友好的描述，你可爲這個參數傳送一個空值。

displayStyle: 指定用於爲用戶提供選擇的控件。容許的值有：

Style Tag	控件
radio:	Radio 按鈕
select:	一個下拉 select/ 組合框
list:	一個單一選擇列表框
list-multi:	一個多選列表框
check-multi:	檢查框的多選集合
check-multi-scroll:	檢查框的滾動，多選集合
check-multi-scroll-2-column:	檢查框的滾動，兩列，多選集合
check-multi-scroll-3-column:	檢查框的滾動，三列，多選集合
check-multi-scroll-4-column:	檢查框的滾動，四列，多選集合

實例

printer 組件建立打印機名的一個列表，用戶可從中選擇。它使用上次使用的打印機做爲默認選擇。它並不爲用戶提供提示信息，或提供打印機名的 display names 的一個映射。它指定一個選擇列表(組合框)應用於獲取用戶輸入。

ArrayList values = new ArrayList(); for (int i = 0; i < services.length; i++) { String value = services\[ i\] .getName(); values.add (value); } createFeedbackParameter ("printer-name", "Printer Name", "", lastPrinterName, values, null, "select"); promptNeeded();

feedbackAllowed()

This page last changed on Dec 01, 2006 by bseyler.

參數：none

結果：boolean

這返回 true，若是組件被容許請求參數。若是執行一個 action sequence 的請求來自一個 web 應用，將返回 ‘true’。若是請求來自一個 web 服務 client，一個 scheduler，或一個工做流引擎，沒有用戶向之作任何請求，這個方法返回 ‘false’。

getFeedbackOutputStream ()

This page last changed on Dec 01, 2006 by bseyler.

參數：none

結果：java. io.OutputStream

當一個組件須要就某個問題向用戶提供反饋，而不是須要輸入時，就使用這個方法。例如，當沒有定義 email 服務器設置，以就如何解決某個問題，向用戶展示情報信息時，email 組件就使用這個方法。

isPromptPending()

This page last changed on Dec 01, 2006 by bseyler.

參數：none

結果：boolean

這使得組件能查找是否其餘的組件已從用戶請求了參數。若是這個方法返回 true，組件不該該試圖執行或建立內容，但僅應該肯定它是否須要爲參數自身進行提示。

promptNeeded()

This page last changed on Dec 01, 2006 by bseyler.

參數：none

結果：none

這通知 Runtime Context 用戶須要被提示組件須要的參數。執行 action sequence 中的其餘組件以查看它是否也有要提示的參數。這使得系統可以爲用戶生成一個單獨的輸入表單，而不是向用戶展示輸入輸入表單的後繼。例如，若是 action sequence 中的第一個組件是一個報表組件，它須要一個 department id，sequence 中的第二個組件是一個打印組件，它須要一個打印機名，會出現一個single form，用戶可選擇部門和打印機。

promptNow()

This page last changed on Dec 01, 2006 by bseyler.

參數：none

結果：none

這通知 Runtime Context 用戶須要被提示組件須要的參數，action sequence 中後面的組件不該該有機會提供參數。這可用於安全目的，可用於阻止沒必要要的處理。例如，考慮具備兩個 action 定義的一個 action sequence。第一個是 Web Service business rule，若是在請求中沒有提供 customer id，它須要 customer id 的提示，第二個是報表組件，它接收第一個組件的結果做爲它的輸入。若是沒有提供 customer id，第一個組件須要提供提示。在這種狀況下，執行報表組件(致使解釋報表定義)以查看它是否須要任何參數的提示是沒有意義的，由於 action sequence 的上下文告訴了咱們它沒有。

setFeedbackMimeType()

This page last changed on Dec 01, 2006 by bseyler.

參數：                                            String                                            mimeType

結果：                                            none                                             

這設置反饋頁的 mime type。目前須要設置成 ‘text/html’。未來也支持其餘設備的 mime types。

爲什麼建立一個 Pentaho 組件?

This page last changed on Dec 04, 2006 by mlowery.

Pentaho BI 套件的基礎架構是一個輕量級的，但靈活有力，用於執行商業智能相關組件的框架。架構容許組件被順序集成在一塊兒，一個的輸出可做爲另外一個的輸入。組件可單獨使用或一塊兒使用以建立 endless number of results。可以使用 Java APIs，Web 服務，schedulers 和工做流引擎控制組件的執行。

架構有效，緊湊，可做爲一個庫部署進 Java 應用程序。

經過在 Pentaho 組件層建立集成了庫和引擎功能的單一 Java 類，新功能可當即和現有組件的功能合併，全部平臺執行方法變得可用。例如，一旦建立了一個新組件：

Ø         它可被調度

Ø         它可做爲一個 web 服務執行

Ø         它可和其餘組件構成序列，傳送數據給其餘組件，從其餘組件接收數據。

Ø         它可提示用戶它須要的參數

Ø         它的使用被自動審計和記錄。

Ø         BI 組件易於建立，易於部署進 Pentaho BI 套件。