Bryan Daniel, 咨询软件工程师, IBM 开发人员技术支持中心
Jerald Schoudt, 内容管理器客户机架构师, IBM Content Manager 产品小组
2003 年 12 月
本文展示了如何使用 Information Integrator for Content 工具箱来为定制的 Web 客户机添加一个文档查看器。这里给出了用于构建对关键的结构化和非结构化信息的透明访问的方法，这种访问可能跨越整个企业，甚至可能超出企业范围。这里还包括一个示例程序。
简介
IBM Information Integrator for Content Version 8 提供了一套丰富的 API，从而允许开发人员构建对关键的结构化和非结构化信息的透明访问，这种访问可能跨越整个企业，甚至超出企业范围。 对各种不同数据源的访问是通过 连接器（connector）完成的，对于每种服务器类型（即 DB2 UDB、Content Manager V7、Content Manager V8、Domino.Doc 等），都有一个连接器。这些连接器由一套基本的类扩展而来，从而为访问数据提供了一个公共框架。除了提供对各种后端服务器的连接性以外，Information Integrator for Content 工具箱还包含一套文档查看器 API，这些 API 可用来将信息呈现给用户。
本文将重点关注 Information Integrator for Content 工具箱，并讨论如何使用它来增强定制的解决方案的文档查看功能。我们将讨论将一个 applet 查看器集成到定制的 Web 客户机中，以及定制的可能性。我们还将谈到运行全操作性 Web 客户机示例的详细说明。我们的目标就是演示如何在定制的客户机中使用文档查看器工具箱来提供查看功能，这种查看功能可以与 Content Manager eClient （ 图 1）提供的查看功能相媲美。
图 1 - applet 查看器示例
文档查看器工具箱是一套 Java API，它为文档的显示和用户注解文档提供了便利。这个工具箱包括一个基于 Swing 的图形类，如图 1 所示。此外，还有一组类对象，这些对象提供了文档转换和呈现功能。开发人员可以选择定制现有的图形接口，也可以构建自己的接口。该工具箱还包括大量的文档功能，其中包括旋转、缩放、增强、反转、打印以及创建/查看/修改注解。Content Manager eClient 利用该工具箱来提供它自己的查看功能。
一种常见的误解是，文档查看器工具箱不过是一个 applet 罢了。然而，这个工具箱其实还包括一个基于 Swing 的类，这个类可能在一个 applet 中用到，它包括很多其他的独立的类对象，这些对象可用于文档的转换、呈现以及注解。实际上，可以开发出自动化的注解程序，这种程序可以完全独立于 applet 组件。
如果要开发一个 Web 客户机，而且必须开发一个新的文档查看器用户界面，那么此工具箱中所包含的基于 Swing 的 GUI 类就提供了一项颇吸引人的选择。这个类提供用户界面实现，并依赖于回调类（开发人员必须实现这个类）来提供文档和注解服务功能。
架构
为定制的 Web 客户机开发的 applet 文档查看器包括两个组件 -- 一个 applet 和一个控制器 servlet（ 图 2）。其中 applet 及其支持类提供了文档图像的表示和呈现。而且，由于 applet 运行在客户机上，转换和呈现图像时所需的处理是在客户机上执行的。
图 2 - applet 查看器组件
控制器 servlet 直接与后端服务器通信（即，更新注解部分，获取文档和注解部分的位置，判定 mime 类型，等等）。为了使该 servlet 能够与 Content Manager Version 8 (CM V8) 服务器通信，必须安装 Information Integrator for Content (II4C) CM V8 连接器和 DB2 UDB 运行时。如果不使用 servlet，那么使用该 applet 的每个客户机都将需要安装 Information Integrator for Content CM V8 连接器和 DB2 UDB 运行时客户机。否则，该 applet 将无法连接到 CM V8 服务器。
该 applet 使用 CMBGenericDocViewer 类，这个类是基于 Java Foundation Class (JFC) 并且用于文档查看器的图形用户界面。就其本身而言，CMBGenericDocViewer 类只不过是一个 GUI。也就是说，它依赖于其他类来处理用户所请求的任何功能。 图 3描绘了 CMBGenericDocViewer 类。注意，它由一些缺省的工具条组成 -- Operation、Annotation 和 Page。通过查看器配置文件，可以控制哪些工具条可见，定制已有的工具条，以及创建新的工具条。在后面的小节中，我们将讨论如何添加自定义工具按钮到 operation 工具条中。
图 3 - CMBGenericDocViewer 对象
如前所述，CMBGenericDocViewer 类的作用是为文档查看器提供用户界面。它依赖于其他类对象来处理文档和注解功能。如图 2 所示，这个功能是通过两个回调类提供的 -- 一个文档服务回调类和一个注解服务回调类。初始化 CMBGenericDocViewer 对象时，需要 CMBStreamingDocServices 和 CMBAnnotationServices 类对象的一个实例。为了创建这些类的实例，必须实现两个回调类：
- CMBStreamingDocServices 需要 CMBStreamingDocServicesCallbacks 抽象类的实现，
- CMBAnnotationServices 类需要 CMBAnnotationServicesCallbacks 抽象类的实现。
下面的代码演示了如何创建 CMBGenericDocViewer 对象。
// Create streaming doc services object
streamingDocServices =
new CMBStreamingDocServices(
new StreamingDocServicesCallbacks(), engineProps);
// Create annotation services object
annServices =
new CMBAnnotationServices(
new AnnotationServicesCallbacks());
// Create generic doc viewer object
genDocViewer =
new CMBGenericDocViewer(
streamingDocServices, annServices, configProps);
// Add generic doc viewer GUI to applet pane
getContentPane().add(genDocViewer, BorderLayout.CENTER);
|
在以上代码中，StreamingDocServicesCallbacks 类是 CMBStreamingDocServices 抽象类的实现。CMBGenericDocViewer（applet GUI 组件）使用这个类来获取和更新文档部分及资源。同样地，AnnotationServicesCallbacks 是 CMBAnnotationServicesCallbacks 抽象类的实现。CMBGenericDocViewer 使用这个类来获取和更新注解。开发人员必须为一些必需的方法提供实现，但是可以毫无顾忌地忽略那些与所查看文档的类型无关的方法。例如，由于附带的示例程序是为 Content Manager Version 8 服务器定制的，所以CMBStreamingDocServicesCallbacks.getResources() 方法不包括任何实现代码（如果查看器要访问 Content Manager OnDemand 文档，那么就应该实现这个方法）。另一方面，CMBAnnotationServicesCallbacks.updateAnnotationPart() 方法很重要，必须实现这个方法，以便 CMBGenericDocViewer 类能够保存任何更新过的注解。
下面的代码代表 updateAnnotationPart () 方法实现的一个片断。注意在更新注解部分时 applet 控制器 servlet 所扮演的角色（记住，该 servlet 将运行在具有必需的类和库的机器上，以便允许与后端服务器的直接连接）。
清单 1. 标识代码示例的标题
// Aquire connection to AppletController servlet
URL url =
new URL(getCodeBase(), "AppletController");
URLConnection urlConnection = url.openConnection();
// Send updateAnnPart command to servlet
Properties properties =
new Properties();
properties.put("command", "updateAnnPart");
properties.put("docid", docid);
properties.put("annotation", data);
properties.put("index",
new Integer(index).toString());
sendCommand(urlConnection, properties);
// Get servlet return code
ObjectInputStream objInputStream =
new ObjectInputStream(urlConnection.getInputStream());
String rc = (String) objInputStream.readObject();
objInputStream.close();
// Write servlet return code to standard output
System.out.println("updateAnnotationPart rc = " + rc);
|
applet 查看器的主要优势在于，转换和呈现图像时所需的处理是在客户机上进行的。这样就大大减轻了中间层服务器的负载，从而提高了总体性能。CMBStreamingDocServices 对象依赖于文档引擎类来操纵图像。在本文附带的示例程序中，我们用到了 CMBMSTechDocumentEngine 和 CMBJavaDocumentEngine 类。这些文档引擎是用纯 Java 实现的，因此可以很容易地集成到 applet 环境中。其他引擎，例如 CMBODDocumentEngine，也是可用的，但这里还是用本地库（DLL）来提供功能比较好。因为这些引擎不是纯 Java 的，它们在 applet 环境中运行起来不是很容易。
例如，必须确保每一台客户机上都有适当的 DLL，并且，在 applet 试图访问这些本地客户机文件时，还需要处理相关的安全问题。文档引擎类打包在 cmbview81.jar 文件中，这就是图 2 将这个 jar 文件描绘为下载到客户机上的某一个文件的原因。下面的代码演示了如何将文档引擎类用于将文档服务对象转成流的形式：
// Create engine properties
engineProperties =
new Properties();
engineProperties.put("ENGINES","2");
engineProperties.put("ENGINE1_CLASSNAME",
"com.ibm.mm.viewer.mstech.CMBMSTechDocumentEngine");
engineProperties.put("ENGINE2_CLASSNAME",
"com.ibm.mm.viewer.CMBJavaDocumentEngine");
engineProperties.put("DOCTYPE_AUTODETECT", "true");
// Create engine properties
streamingDocServices =
new CMBStreamingDocServices(
new StreamingDocServicesCallbacks(), engineProperties);
|
使用 applet 文档查看器的另一个优势是，可以直接从一个资源管理器服务器那里获取文档。为了将一个文档装入查看器中，必须调用 CMBGenericDocViewer.loadDocument() 方法，并将需打开的文档的 inputstream 传递给该方法。在附带的示例程序中，这个 inputstream 是从一个 URL 连接中获得的。下面的代码描绘了这一过程：
// Get the document URL. getDocURL method makes
// a call to the controller servlet to obtain url.
String docURL = getDocURL(docid, "0");
System.out.println("docURL = " + docURL);
// Get inputstream to URL
URL url =
new URL(docURL);
URLConnection urlConnection = url.openConnection();
InputStream docInputStream = urlConnection.getInputStream();
// Load document in generic doc viewer object
CMBDocument currDocument = myGenDocViewer.loadDocument(
docInputStream, numParts, partMimeType, partMimeType,
null,
null);
|
注意，指向文档（存储在资源管理器服务器中）的 URL 是从控制器 servlet 获得的（该 servlet 通过调用 DKLobICM 对象的 getDataURL() 方法来获得文档 的 URL）。下面这个例子说明了一个文档 URL 可能的样子：
http://cmrmsrv/icmrm/ICMResourceManager?order=retrieve& itemid=A1001001A03I17B75900E40541&version=1&objname=A1001001A03I17B75900E40541& collection=CBR.CLLCT001&libname=ICMNLSDB&update-date=2003-09-17+22%3A59%3 A10.059039&token=A4E6.Dr6FkE 6_bjqcs YDddpw;&content-length=0
只要安全标志（对于这个 URL 就是 A4E6.Dr6FkE6_bjqcsYDddpw）是有效的，在应用程序中就可以重用这个 URL。缺省情况下，安全标志是 48 小时内有效的，不过在 Content Manager System Administration Client 中可以对其进行调整。
如果要直接从资源管理器获取文档，则对 applet 施加的那些约束就会带来问题。除非客户机显式地允许，否则 applet 只能与加载它的机器（Web 服务器）建立 socket 连接。如果资源管理器运行在其他机器上，则当该 applet 尝试直接获取文档时，它将抛出一个安全异常。为了允许这种功能，必须对包含该 applet 类文件的 jar 文件签名。通过这样做，用户就可以允许该 applet 查看器有这种类型的动作。签名 applet jar 文件的步骤可以在 AppletViewer.java 源文件中找到。
运行示例
本文附带的示例 Web 应用程序被打包成一个 EAR 文件，可以很容易地将其导入诸如 WebSphere Studio Application Developer V5.0 (WSAD) 之类的 J2EE 开发环境中。为了成功地在 WSAD 中运行示例 Web 应用程序，遵循以下步骤：
- 启动 WebSphere Studio Application Developer V5.0。
- 从菜单栏选择 Window->Open Perspective->Other->Web（也可以使用工具条按钮），进入 Web 透视图。Web 透视图用于实施实际的 Web 客户机开发。
- 导入 EAR 文件：
- 从菜单栏选择 File->Import。
- 选择“EAR file”，然后单击 Next。
- 指定 AppletViewerEAR.ear 文件的路径。
- 在 Project Name 项输入“AppletViewerEAR”。
- 单击 Finish。
- 必需的 JAR 文件必须添加到项目类路径中：
- 右键单击名为“AppletViewer”的项目文件夹，并选择“Properties”。
- 选择“Java Build Path”，转到“Libraries”选项卡。
- 单击“Add External JARs”添加以下 JAR 文件：
- c:\\cmbroot\\lib\\cmb81.jar
- c:\\cmbroot\\lib\\cmbcm81.jar
- c:\\cmbroot\\lib\\cmbsdk81.jar
- c:\\cmbroot\\lib\\cmbview81.jar
- c:\\cmbroot\\lib\\log4j.jar
- c:\\cmbroot\\lib\\cmblog4j81.jar
- c:\\program files\\ibm\\sqllib\\java\\db2java.zip
- 单击 OK。
- 名为 index.jsp 的 JSP 页面显示 NOINDEX item-type 中的文档，这些文档可以在 applet 查看器中查看。该页面用于模拟一个搜索结果列表。因此，它还需要到 Content Manager Version 8 服务器的连接。连接对象也将存储在会话中，以便 applet 控制器 servlet 能够使用。在 J2EE Navigator 窗口展开 AppletViewer->Web Content，双击 index.jsp 文件。定位到以下代码片断，如果需要的话，对其进行更新，以匹配您自己的环境。
// **** UPDATE TO MATCH YOUR ENVIRONMENT ****
String userid = "icmadmin";
String password = "password";
String server = "icmnlsdb";
// ***********************************************
|
- 定义好 Web 项目之后，还必须配置 WebSphere Test Environment。从菜单栏选择 Window->Open Perspective->Other->Server（也可以使用工具条按钮），进入 Server 透视图。
- 创建一个服务器及服务器配置：
- 在 Server Configuration 窗口中，右键单击 Servers，并选择 New->Server和 Server Configuration。
- 输入“applet Viewer WebSphere Server”作为服务器名。
- 选择“WebSphere Version 5.0 Test Environment”作为服务器类型。
- 单击 Finish。
- 配置服务器类路径：
- 在 Server Configuration 窗口中，展开 Servers，右键单击“applet Viewer Websphere Server”并选择 Open。
- 选择“Paths”选项卡。
- 在“Classpath”下面，单击“Add External JARs”添加以下 JAR 文件：
- c:\\cmbroot\\lib\\cmb81.jar
- c:\\cmbroot\\lib\\cmbcm81.jar
- c:\\cmbroot\\lib\\cmbsdk81.jar
- c:\\cmbroot\\lib\\cmbview81.jar
- c:\\cmbroot\\lib\\log4j.jar
- c:\\cmbroot\\lib\\cmblog4j81.jar
- c:\\program files\\ibm\\sqllib\\java\\db2java.zip
- 在“Classpath”下面，单击“Add External Folder”并添加“C:\\Program Files\\IBM\\Cmgmt”。
- 按 Ctrl-S保存更改。
- 如果还要在这台机器上运行 Content Manager Resource Manager 服务器，则 WebSphere Application Server 和 Test Environment 两者使用的端口就可能发生冲突。
- 关闭 applet Viewer WebSphere Server 属性。
- 为了加载 Java 插件，必须使用一个外部的 Web 浏览器：
- 从工具栏选择 Windows->Preferences。
- 选择“Web Browser”。
- 选择“Use external web browser”。
- 输入“C:\\Program Files\\Internet Explorer\\IEXPLORE.EXE”作为位置。
- 输入“%URL%”作为参数。
- 单击 OK。
- 右键单击“index.jsp”并选择“Run on Server”，以运行 applet 查看器示例。选择已有的名为“applet Viewer WebSphere Server”的服务器，单击 Finish。（可能还要选中“Do not show this dialog next time - Set this as the preferred server” 复选框。）
定制
通过配置属性文件，可以定制查看器提供的功能。这个配置文件可以作为参数传递给 CMBGenericDocViewer 类的构造函数。该文件包含一系列的参数，这些参数可以控制显示哪些工具条，在哪里显示这些工具条，以及哪些工具按钮是可见的。还可以定制诸如弹出菜单之类的功能，以及缺省的显示分辨率。例如，考虑这样的情况：假如需要一个“save as”按钮，以允许终端用户将需查看的文档保存到一个本地存储设备中。这个按钮可以放在已经定义好的“Save”按钮（将更改保存回后端服务器）旁边。
附带的示例程序使用 CMBViewerConfiguration.properties 文件来控制 CMBGenericDocViewer 配置（ 图 4）。通过检查这个文件，可以发现“Toolbars”参数定义了三个工具条：
- OperationToolbar
- PageToolbar
- AnnoToolbar
如果更仔细地观察，就可以发现 OperationToolbar 被放在 applet 查看器的顶部，并且其中已经有了一些工具按钮（包括 save_doc、separator、print、separator、cut、copy、paste、separator、undo 和 redo）。
图 4 - 一般文档查看器配置文件
要添加“save to disk”工具按钮，只需插入一个变量名。例如，可以调整 OperationToolbar 参数读取：
OperationToolbar.tools=
save_doc,saveAs_doc,separator,print,
separator,cut,copy,paste, separator,undo,redo,separator,rotate_90,
rotate_180,rotate_270,rotate_pages,separator,zoom_in, zoom_out,
zoom_custom,separator,fit_height,fit_width,fit_window, fit_actualsize,
separator,enhance, invert,separator,hide_show,showhidethumb,
separator, close_doc,close_all_doc,separator,help
|
将这个按钮添加到工具条之后，就必须对其进行配置。例如，要设置该工具按钮的图像和工具提示文本，可以将下面几行添加到配置文件：
saveAs_doc.icon = Save_normal.gif
saveAs_doc.tooltip = Save to disk
|
这两个更改将导致一个新的工具按钮出现在 applet 查看器中。当用户单击该按钮时，就会触发一个事件。不过，由于处理该事件的代码还没有实现，因此这里不会执行任何功能。不过，通过添加几行代码（在 AppletViewer.java 文件中可以找到），可以很容易地对此作出弥补。下面的代码将添加主类作为新工具条按钮所抛出事件的侦听器：
// Add this class as a listener for events thrown by the new
// "saveAs_doc" button added to the "OperationToolbar" toolbar
JToolBar tb = myGenDocViewer.getToolBar("OperationToolbar");
Component components[] = tb.getComponents();
// Have to go through toolbar components to
// find button that we are interested in.
for (int i = 0; i < components.length; i++)
{
if (components[i] instanceof JButton)
{
JButton button = (JButton) components[i];
Action act = button.getAction();
String name = (String) act.getValue("Name");
// If this is the "saveAs_doc" button, add
// this class as a listener object
if ( name.equalsIgnoreCase("saveAs_doc") )
button.addActionListener(this);
}
}
|
此时，主类将侦听它感兴趣的事件。接下来的一步就是决定事件被抛出之后应该做些什么。下面的方法所包含的代码将在用户单击 “saveAs_doc”工具条按钮时运行：
// Handle actionPerformed event
public void actionPerformed(ActionEvent e)
{
// Check if the saveAs_doc button was pressed
if (e.getActionCommand().equalsIgnoreCase("saveAs_doc"))
{
// output to applet console
System.out.println("User pressed saveAs_doc button!");
CMBDocument doc = myGenDocViewer.getSelectedDocument();
// Add implementation for this event. For example,
// write doc to disk, assuming applet security
// has been addressed via certificates/policyfiles...
}
}
|
查看器配置文件提供了很多可能性，添加一个新的工具按钮只不过是其中的一个可能性。对于不同选项的完整描述，可以在 Workstation Application Programming Guide中题为“Customizing the generic document viewer”的小节下找到。
结束语
本文描述了如何使用 Information Integrator for Content 工具箱来容易地为定制的 Web 客户机添加文档查看器。该工具箱包括一个图形用户界面组件（CMBGenericDocViewer），用于提供与终端用户的交互。而且，它还包括一组文档引擎（即 CMBMSTechDocumentEngine、CMBJavaDocumentEngine），用于提供查看器的图像转换和呈现能力。开发人员必须提供两个回调类（CMBStreamingDocServicesCallbacks 和 CMBAnnotationServicesCallbacks）的实现。这两个类为查看器（CMBGenericDocViewer）提供了执行诸如获取文档部分和保存注解对象之类功能的功能性。
为了能够完全理解所有这些组件是如何在程序中协同工作的，请务必试验本文附带的示例程序。
作者简介
 Bryan Daniel 是位于得克萨斯州达拉斯的 IBM 开发人员技术支持中心（Developer Technical Support Center）的一名咨询软件工程师。他为 Business Partner 社区提供 IBM Content Management 支持，同时也是 IBM Content Manager for Multiplatforms Version 8.1 System Administration Certification Study Guide一书的合著者。 |
|
 Jerald (Jerre) Schoudt 是加利福尼亚硅谷实验室 IBM Content Manager 产品小组的客户机架构师（Client Architect）。他负责开发 Content Manager Windows Client、eClient、Portlets 和 ODMA 客户机的架构。可以通过 jschoudt@us.ibm.com 与他联系。
|
|
