使用 Function Call Interface 扩展 IBM Workplace Forms 的功能

最新推荐文章于 2024-09-15 19:46:31 发布

cuinaozun7188

最新推荐文章于 2024-09-15 19:46:31 发布

阅读量193

点赞数

文章标签： java 开发工具数据库

通过使用功能强大的 Workplace Forms Server API 和 Function Call Interface (FCI) Library 工具扩展 IBM Workplace Forms 应用程序的功能。

IBM Workplace Forms Server API 为扩展 Workplace Forms 提供了功能强大的工具。使用 Function Call Interface (FCI)，您可以方便地向 Workplace Forms 应用程序添加定制函数。

FCI 是 Workplace Forms Server API 的一部分。它提供了 Java 和 C 语言下的框架，允许您通过创建称为扩展 (extension) 的定制组件来扩展表单的功能。这些扩展包含可以从可扩展表单描述语言（Extensible Forms Description Language，XFDL）表单内部调用的函数包。通过使用这些定制函数，不仅可以返回计算值，还可以直接操作表单。建立了定制函数的框架后，可以使用 Java 系统方法、Form. Library 方法，甚至其他 FCI 方法来实现每个函数的细节。

有关 FCI 的详细信息，请参阅 Workplace Forms Java API User's Manual，可以从 developerWorks Workplace Forms 文档页面下载该指南。本文适用于 Workplace Forms V2.5 及更高版本。

本文适用于熟悉 IBM Workplace Forms Viewer 和 Designer 的 Workplace Forms 开发人员。

使用 FCI Library 创建扩展

若要使用 FCI 库创建扩展，请执行以下六个步骤，下面几节将详细描述这些步骤。

建立开发环境

若要使用 FCI Library，必须将下面文件添加到 CLASSPATH 来配置集成开发环境：

\2.6\API\70\java\classes\pe_api.jar
\2.6\API\70\java\classes\uwi_api.jar

如果已经在计算机上安装了 Workplace Forms Server API，那么也可以在下面位置上得到这两个 JAR 文件：

\Lib\Java

注意：pe_api.jar 文件用于编译那些使用了 API（包括 Form. Library 和 FCI Library）的应用程序，而 uwi_api.jar 文件用于编译那些需要向后兼容性的应用程序。

创建 Extension 类

Extension 类包含 extensionInit 方法，此方法将初始化扩展并为函数调用提供服务。初始化 Workplace Forms 应用程序时，该 API 将在 Workplace Forms Viewer 的 Extension 文件夹和已打开的表单本身中检查现有扩展。如果发现存在现有扩展，则在每个 Extension 类中调用 extensionInit 方法。

Extension 类必须实现由 FCI Library 提供的 Extension 接口。该接口中定义了很多方法，但是 extensionInit 是惟一需要实现的方法，用于创建新的 FCI 扩展。该方法用于 FunctionCall 对象的实例化，包含定制包和函数的定义及实现。若要简化 Extension 类的创建，可以扩展预定义的超类 ExtensionImplBase，它已经为您实现了一些方法。采用这种方式，您只需要实现 extensionInit 方法。

若要创建名为 FCIExtension 的 Extension 类，请执行以下步骤：

在 Workplace Forms Designer 中，创建名为 FCIExtension.java 的新 Java 文件。
定义 Java 包，例如 com.IBM.extensions。
导入下面列出的文件（以及对 FCI Library 进行调用的 Java 文件所需的任何其他文件）。导入文件的列表必须在类或接口定义之前：
- import com.PureEdge.ifx.IFX;
- import com.PureEdge.ifx.ExtensionImplBase;
- import com.PureEdge.ifx.Extension;
- import com.PureEdge.xfdl.FunctionCall;
- import com.PureEdge.xfdl.FunctionCallManager;
- import com.PureEdge.xfdl.FormNodeP;
- import com.PureEdge.IFSUserDataHolder;
- import com.PureEdge.error.UWIException;
将 extensionInit 方法作为 Extension 类的一部分进行实现。

在 extensionInit 方法内部创建新的 FunctionCall 对象。若要执行上述操作，必须调用 FunctionCall 类构造函数并将其传递到 IFX Manager，如清单 1 所示：

清单 1. 新 FunctionCall 对象的示例

							
public class FCIExtension extends ExtensionImplBase implements Extension 
{ 
public void extensionInit(IFX IFXMan) throws UWIException
{ 
this.theFunctionObject = new FciFunctionCall(IFXMan);

}
}

IFXMan 对象代表 IFX Manager。该对象允许您访问那些要与扩展一起使用的其他服务和对象。UWIException 是一个通用的异常。

创建 FunctionCall 类

现在将创建 FunctionCall 类，它是由 Extension 类调用的且包含定制方法。该类还将注册 FunctionCall 对象以及它所支持的每个定制函数。FunctionCall 类必须实现由 FCI 提供的 FunctionCall 接口。没有必要实现 FunctionCall 接口中所定义的所有函数。通常，FunctionCall 类将扩展预定义的超类 FunctionCallImplBase 并且仅实现必需的方法。

在 FunctionCall 类的内部，必须声明要创建的每一个定制函数。因为 FunctionCall 类可以包含一个以上的定制函数，所以应当为每个定制函数定义惟一的识别号。

若要实现 FunctionCall 类，请执行以下步骤：

在 Workplace Forms Designer 中，创建新的 Java 文件 FciFunctionCall.java。
定义 Java 包。
导入下面的 API 包以及任何其他所需的文件：
- com.PureEdge.ifx.IFX
- com.PureEdge.xfdl.FormNodeP
- com.PureEdge.xfdl.FunctionCallManager
- com.PureEdge.xfdl.FunctionCallImplBase
- com.PureEdge.xfdl.FunctionCall
- com.PureEdge.error.UWIException
创建 FunctionCall 类。它应当能扩展超类 com.PureEdge.xfdl.FunctionCallImplBase 并实现 FunctionCall 接口。
为 FCI 所创建的每一个定制函数声明惟一的识别号。在本例中，创建了两个定制函数：functionA 和 functionB。
定义使用了 IFX Manager 的 FunctionCall 类构造函数。
声明 evaluate 方法。该方法包含定制函数，本文稍后将进一步进行详述。
通过调用 help 方法，向定制函数添加帮助。该方法包含定制函数，稍后将进一步对它进行详述。

在下面的示例中，FciFunctionCall 将声明两个定制方法 functionA 和 functionB，ID 号分别是 1 和 2：

清单 2. 声明了两个定制函数的 FciFunctionCall 示例

				
public class FciFunctionCall extends FunctionCallImplBase 
_implements FunctionCall { 
public static final int FUNCTIONA = 1; 
public static final int FUNCTIONB = 2;

public FciFunctionCall(IFX IFXMan) throws UWIException 
{ 
/* Additional code removed */
} 

public void evaluate(……) 
{ 
/* Additional code removed */
}

public void help(……) 
{ 
/* Additional code removed */
}
}

创建 FunctionCall Class 构造函数

在定制函数可用于 Workplace Forms 应用程序之前，必须注册 FunctionCall 对象以及它所支持的每个定制函数，以便识别出它所包含的函数和包。

FunctionCall 类构造函数将 IFX Manager 看作是自己的参数。在构造类的过程中，执行了所有注册工作，包括扩展注册和函数注册。实际上 IFX Manager 将控制 Workplace Forms 扩展。

若要注册 FunctionCall 对象，请执行以下步骤：

使用 getFunctionCall 对象来检索 Function Call Manager。它处理特定于函数调用的服务（例如，对特定函数的请求的处理），并由 FunctionCallManager 对象来表示。
调用 IFXMan 对象的 registerInterface 方法来注册扩展。
使用 FunctionCallManager 对象的 registerFunctionCall 方法来注册定制函数的包。

下面的示例将检索 Function Call Manager、注册扩展并注册两个定制函数 functionA 和 functionB。请注意每个函数的其中一个参数将包含定制函数的惟一 ID：

清单 3. 如何注册 FunctionCall 对象的示例

				
public FciFunctionCall(IFX IFXMan) throws UWIException
{ 
FunctionCallManager theFCM; 
// retrieve the Function Call Manager
if ((theFCM = IFSSingleton.getFunctionCallManager()) == null)
throw new UWIException("Needed Function Call Manager"); 

//register extension to the IFX Manager
IFXMan.registerInterface(this,   
	FunctionCall.FUNCTIONCALL_INTERFACE_NAME, 
	FunctionCall.FUNCTIONCALL_CURRENT_VERSION, 
	FunctionCall.FUNCTIONCALL_MIN_VERSION_SUPPORTED, 
	0x01000300, 0, null, theFCM.getDefaultListener( ));

//register FUNCTIONA functions to function Call Manager
theFCM.registerFunctionCall(this, "my_package", "functionA",
 	FciFunctionCall.FUNCTIONA, FunctionCall.FCI_FOLLOWS_STRICT_
	CALLING_PARAMETERS, "S,S", 0x01000300, "Here is functionA’s 
	description"); 

//register FUNCTIONB functions to function Call Manager
theFCM.registerFunctionCall(this, "my_package", "functionB",
	FciFunctionCall.FUNCTIONB, FunctionCall.FCI_FOLLOWS_STRICT_
	CALLING_PARAMETERS, "S,S", 0x01000300, "Here is functionB’s 
	description"); 
}

注意：有关 registerInterface 和 registerFunctionCall 方法的详细信息，包括这些方法的参数描述，请参阅 Workplace Forms Java API User's Manual。

创建定制函数

创建定制函数必须使用两个方法：

Evaluate。只要需要执行定制函数，就调用该方法。当从 Workplace Forms 应用程序调用定制函数时，Forms Library 将检索它的包及函数名称。然后调用 evaluate 方法，检查函数的惟一 ID 并执行相应的代码片段。在该方法中，可以返回值或直接在内存中操作表单。下面是 evaluate 方法的示例：

清单 4. evaluate 方法示例

							
public void evaluate(String thePackageName, String theFunctionName,
     int theFunctionID, int theFunctionInstance, short theCommand, 
     FormNodeP theForm, FormNodeP theComputeNode, IFSUserDataHolder 
     theFunctionData, IFSUserDataHolder theFunctionInstanceData, 
     FormNodeP[] theArgList, FormNodeP theResult) throws UWIException
{
//execute following procedure when a function is run
if (theCommand == FunctionCall.FCICOMMAND_RUN)
{
//check which custom function is called by the unique ID
if (theFunctionID == FciFunctionCall. FUNCTIONA_ID)
{
/* Additional code removed */
}
if (theFunctionID == FciFunctionCall. FUNCTIONB_ID)
{
/* Additional code removed */
}

}
}

注意：有关 evaluate 方法的详细信息，包括该方法的参数描述，请参阅 Workplace Forms Java API User's Manual。

Help。该方法用于向开发环境（例如 Workplace Forms Designer）中的表单设计人员提供帮助信息。应当详细解释定制函数，便于表单设计人员正确地选择并使用函数。下面是 help 方法的示例：

清单 5. help 方法示例

							
public void help(String thePackageName, String theFunctionName, 
     int theFunctionID,IFSUserDataHolder theFunctionData, 
     StringHolder theQuickDesc, StringHolder theFunctionDesc, 
     StringHolder theSampleCode, StringListHolder theArgsNameList, 
     StringListHolder theArgsDescList, ShortListHolder theArgsFlagList, 
     StringHolder theRetValDesc, ShortHolder theRetValFlag) 
     throws UWIException 
{
/* Additional code removed */
}

构建并打包扩展

创建了 Extension 和 FunctionCall 类之后，必须进行以下操作：

编译源代码来创建类文件。
创建 manifest 文件。应当指明 Java Archive (JAR) 文件中的哪些类是扩展的一部分。下面示例展示了典型的 manifest：

Manifest-Version: 1.0
Name: com/yourcompany/samples/FCIExtension.class
IFS-Extension: True
将 class 文件打包到用于分发的单一 JAR 文件中。下面的示例展示了用于构建 JAR 文件的语法，其中 com 是 class 文件的顶层包名：

jar -cvfm FCI.jar manifest.mf com

注意：有关创建 JAR 文件和 manifest 文件的更多信息，请参阅 Java 文档。

测试并分发扩展

创建完扩展后，安装该扩展以便进行测试。如果对它的性能感到满意，则可以采用下面两种方式中的一种来分发该扩展以便使用：

将 JAR 文件复制到 Workplace Forms Viewer 的 Extensions 文件夹。该文件夹为 \extensions。

或者
使用 Workplace Forms Designer 将扩展嵌入 XFDL 表单，如图 1 所示。在 Enclosures 选项卡上，展开 JAR 条目，右键单击 PAGE1，然后从菜单中选择 Enclose File。

图 1. 嵌入扩展

在 Workplace Forms Designer 中封装扩展

封装在表单中的 JAR 文件必须将 MIME 类型设置为 application/uwi-jar。有关 Workplace Forms Designer 和 MIME 类型的更多信息，请参阅 developerWorks Workplace Forms 文档页面上的 Workplace Forms Designer User's Manual。

扩展的安装位置确定了扩展所拥有的用户系统资源（例如系统文件）的访问权限。表 1 概括了在特定位置上安装扩展时设置的安全特性。

表 1. 与扩展安装位置对应的安全特性

扩展的安装位置	安全特性
作为 JAR 或 ZIP 文件安装在 Workplace Forms Viewer 的 Extensions 文件夹中	拥有用户系统资源的全部访问权限
作为 JAR 或 ZIP 文件进行打包并在表单内部直接进行封装	仅拥有封装该扩展的表单的访问权限，不能访问用户系统的其他部分或导致任何破坏

创建 FCI 扩展示例

现在将演示如何使用 FCI 方法来创建扩展，以及如何使用 XFDL 表单中的定制函数。我们将创建示例扩展，检索本地文件系统的文件信息并在表单中进行显示。也可以将该示例应用程序与数据库集成。若要实现上述目的，可以使用 Java API 来访问本地系统的文件信息，并使用 Form. API 直接在内存中操作 XFDL 表单。

图 2 展示了与扩展一起使用的 XFDL 表单。表单中嵌入了用于分发的示例 JAR 文件。

图 2. XFDL 表单

若要访问扩展的功能，则单击 Browse 按钮并选择计算机上的文件。示例定制函数将访问文件信息并在表单中显示结果。图 3 展示了显示扩展从本地文件系统检索到的文件信息的表单。

图 3. 带有文件信息的示例表单

创建示例 FunctionCall 类

首先，必须创建 FunctionCall 类，包括以下内容：

导入所有必需的包。
扩展 FunctionCallImplBase 类并实现 FunctionCall 接口。
为定制函数定义惟一的 ID。
注册 FunctionCall 对象。
注册定制函数。
创建包含定制函数的 evaluate 方法。

在附带文件“示例 FunctionCall 类”的示例 FunctionCall 类中，registerFunctionCall 方法将下面信息传递到 FunctionCallManager：

函数包是 sample_package。
函数名是 readFile。
readFile 仅接受一个参数。

有关 registerFunctionCall 方法的详细信息，包括该方法的参数描述，请参阅 Workplace Forms Java API User's Manual。

创建 Extension 类

接下来，需要创建 Extension 类，如清单 5 所示，包括以下内容：

导入所有必需的包。
创建 extensionInit 方法，并将 IFX Manager 传递到该方法。
调用在“创建示例 FunctionCall 类”一节中所创建的 FunctionCall 类构造函数。

清单 5. 示例 Extension 类

				
package com.ibm.wpforms.samples;

import com.PureEdge.error.UWIException;
import com.PureEdge.ifx.Extension;
import com.PureEdge.ifx.ExtensionImplBase;
import com.PureEdge.ifx.IFX;

public class FCIExtension extends ExtensionImplBase implements Extension {
public void extensionInit(IFX IFXMan) throws UWIException {
new FciFunctionCall(IFXMan);
}
}

分发定制函数

由于定制函数用于访问本地系统上的文件信息，因此不能将其嵌入 XFDL 表单。Workplace Forms Viewer 认为表单是不安全的，并且会抛出 Java 异常。因此，必须采用其他方式将定制函数分发给用户，例如通过共享的文件系统、电子邮件、下载或管理员安装。一旦置于用户系统之上， JAR 文件就必须被保存在使用扩展的 Workplace Forms 产品的 Extensions 文件夹中，例如 \extensions。

创建示例 XFDL 表单

在使用定制函数之前，必须创建触发函数的 XFDL 表单，如附带文件“示例 XFDL 表单”所示。带有演示表单的 FCI Extension Eclipse Project 示例在本文的下载部分可以找到。若要学习有关使用 Workplace Forms Designer 创建 XFDL 表单的更多内容，请参阅 Workplace Forms Designer User's Manual。

使用表单内部的定制函数

嵌入了定制函数后，可以在表单内部使用它。在本例中，将创建 Browse 按钮，允许用户搜索用户计算机上的文件并触发定制函数。若要实现上述操作，请执行以下步骤：

在 Workplace Forms Designer 中打开示例表单。
通过选择面板上的按钮并将其放置到表单页面来创建 XFDL 按钮项。
选中按钮，单击 Source 选项卡。
在表单的源代码中，向按钮添加定制选项：
向定制选项添加计算属性，确保它在 XFDL 名称空间中：
接下来，创建计算，当用户单击 Browse 按钮时，该计算将触发定制函数。如果按钮处于激活状态，则使用 Workplace Viewer fileOpen 函数来设置文件位置。如果选择了文件，则运行定制函数；否则，不进行任何操作。请参阅清单 6。

清单 6. 示例 Browse 按钮

				

	7507024Browse#C0C0C0Verdana10

结束语

Workplace Forms Server API 和 Function Call Interface Library 是功能强大又十分灵活的工具，用于扩展 Workplace Forms 应用程序的功能。我们希望通过按步执行本文所提供的操作步骤，具有一定经验的开发人员可以逐渐开发出自己的定制函数。

来自 “ ITPUB博客 ” ，链接：http://blog.itpub.net/14751907/viewspace-434641/，如需转载，请注明出处，否则将追究法律责任。

转载于:http://blog.itpub.net/14751907/viewspace-434641/