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 套件。