简介

IBM InfoSphere Guardium Data Redaction 支持选择性地公开文档中的信息。编校服务器会自动删除自由文本文档和表单中的私有信息，如图 1 中所示。

这些功能有助于处理可能分散在各种位置的大量文档。当因为制度和业务而需要在文档中维护某些信息的隐私，同时专门向授权的人员显示相关信息时，编校系统可帮助实现这两个目标。

此产品包括基于浏览器的应用程序，它们具有直观的界面，允许您编校文档或查看编校的文档。它还提供了多个自动化访问选项。这些功能在企业内容管理 (ECM) 工作流中可能特别有用，其中受控的编校是文档管理的重要部分。

有 3 种使用这些编校服务的方法：

• 通过文档存储库或文件系统 —— 将原始文档复制到一个输入文件夹，在输出文件夹中接收编校的文件。
• 通过 SOAP API —— 建议将此方法用于非 Java 应用程序。
• 通过 Java 编校客户端 API —— 这是本文的讨论重点。

IBM InfoSphere Guardium Data Redaction 提供了一个编校客户端 API，以便您的自定义应用程序可通过 API 直接控制编校服务。本文将介绍编校客户端 API 的功能，以及如何在自定义应用程序中使用该 API。本文中以示例的形式描述了 3 种典型的场景。

注意：本文基于 IBM InfoSphere Guardium Data Redaction V2.1。

回页首

编校客户端 API

编校客户端 API 是一个 Java 类库，用于从程序访问编校服务器的服务。API 工具包包含在 IBM InfoSphere Guardium Data Redaction 中。

为 API 提供了开箱即用的示例代码和文档。当安装产品时，会将 API 库和示例程序复制到 <IBM_REDACTION_HOME>\client 文件夹中，其中 <IBM_REDACTION_HOME> 是安装文件夹。API 的 Java 文档也将复制到 <IBM_REDACTION_HOME>\docs\apidocs 文件夹中。

使用该 API，可通过两种模式从自定义应用程序使用编校服务：远程客户端模式和进程内客户端模式。在远程客户端模式中，远程（或本地）客户端机器上的程序通过 SOAP 连接调用编校服务器。在进程内客户端模式中，整个编校服务器作为客户端应用程序的一部分运行。程序的实现在两种模式下几乎相同。在这些示例中，首先介绍在远程客户端模式下，该 API 在每种典型场景中的使用。最后，将介绍两种模式之间的区别。

第一个场景是最基本的场景。一个客户端程序连接到服务器并编校文档。在第二个场景中，将许多文档发送到服务器，使用一个批处理存储库编校它们。第三个场景是一种高级情形，展示了应用程序对一组文档的编校的高级控制。

回页首

场景 1：本地文件系统编校

这是最简单的场景，演示了该 API 的基本用法。在此场景中，远程客户端机器上的一个程序向编校服务器发送了一个编校请求，如图 2 所示。

该场景包含以下步骤：

1. 建立编校服务器连接
2. 以二进制数据形式加载目标文档
3. 提交编校请求
4. 将结果保存为文档

建立编校服务器连接

要连接编校服务器，首先创建一个 RedactionToolkitClient 类对象。可以使用 createRemoteClient() 方法在远程客户端模式下创建对象。清单 1 展示了如何使用 createRemoteClient() 方法。

				
User user = new User("CustomApp01", "userid", "password");
RedactionToolkitClient client = RedactionToolkitClient.createRemoteClient("foo.bar.com", 
8097, user);

当调用 createRemoteClient() 方法时，会在远程客户端机器和编校服务器之间建立一个 SOAP 连接。因此，该方法需要编校服务器的 IP 地址和端口号。它还需要编校服务器的有效用户 ID 和密码。连接编校服务器和客户端之后，您的应用程序可通过 SOAP 引擎调用服务器的服务。该 API 提供了几个方法来调用编校服务。

以二进制数据形式加载目标文档

编校服务器支持多种文档格式，比如 PDF、Microsoft Word、tiff 图像和纯文本。对于所有格式，文档内容应该以二进制数组形式传递给服务器。因此，在文件系统中编校文档时，该文档必须在二进制模式下打开。

提交编校请求

redactDocumentByRules() 方法向服务器发送一个编校请求。此方法需要一些参数来指定请求的选项。表 1 列出了用于指定请求参数的类。

RedactionAttributes 类对象指定如何编校文档。清单 2 显示了如何设置这个类对象的编校属性。在此示例中，“image/png” 指定输出内容类型，GRAY 指定为输出颜色模式，“Classified” 指定为文档页面左上角的时间戳。RedactionAttributes.ColorMode.GRAY 是指定颜色模式的静态常量。

				
// Set Redaction Attributes
// Set output format
RedactionAttributes redactionAttributes = new RedactionAttributes("image/png");
// Set color mode
redactionAttributes.addAttribute(RedactionAttributes.ColorMode.COLOR_MODE , 
new AttributeValue(RedactionAttributes.ColorMode.GRAY.toString()));
// Set stamp
RedactionStamp stamp = new RedactionStamp(Boolean.TRUE, "Classified", 
RedactionStamp.StampPosition.UPPER_LEFT) ;
redactionAttributes.addRedactionStamp(stamp);

Document 类对象用于设置与输入文档相关的信息，获取已编校文档中的信息。DocumentAttributes 类用于保存 Document 类元数据，比如文档名称、内容类型、语言等。

在清单 3 中，输入文档的名称和内容类型由构造函数指定。当用 "" 指定为内容类型时，编校服务器会检查文档数据并识别类型。可以使用 addAttribute() 方法设置对象的文档语言（英语）。如果未指定语言，系统会在编校过程中自动识别它。文档的二进制数据、documentAttributes 实例和文档状态是在 Document 类对象中设置的。在此示例代码中，文档的二进制数据存储在 inputDocBytes 变量中。

				
byte[] inputDocBytes; //  binary document data 
...
// set file name and language   
DocumentAttributes documentAttributes = new DocumentAttributes("sales_results.pdf", "", 
null);
documentAttributes.addAttribute(DocumentAttributes.LANGUAGE, new AttributeValue("en"));
// set binary data, attributes and status 
Document document = new Document(inputDocBytes, documentAttributes, 
DOCUMENT_STATE.NOT_REDACTED);

IBM InfoSphere Guardium Data Redaction 有 13 种预定义的主要语义类别，如表 2 所示，您可以使用它们指定应该编校文档中的哪些词。也可以根据需要创建其他类别。

当使用 redactDocumentByRules() 方法将编校请求发送到服务器时，需要指定编校的目标数据类型。清单 4 给出了一个准备编校规则和调用该方法的示例。此示例指定必须编校电话号码、人员姓名和地址。

				
RedactionRules rules = new RedactionRules();
rules.add(new RedactionRule( 2, RedactionRule.PERMISSION_TYPE.REDACT)); // ID  2:
Phone Number
rules.add(new RedactionRule(10, RedactionRule.PERMISSION_TYPE.REDACT)); // ID 10: 
Person name
rules.add(new RedactionRule(11, RedactionRule.PERMISSION_TYPE.REDACT)); // ID 11: Address
Document outDocument = client.redactDocumentByRules(redactionAttributes, document, rules);

使用角色可以更容易地指定编校的数据类型。为每种角色指定各种语义类别的权限（即是否编校）。规则和角色相结合，称为一种策略模型，它应该在编校服务器上 <IBM_REDACTION_HOME>\server\conf 文件夹中的 XmlPolicyModel.xml 文件中定义。

redactDocumentForRole() 方法用于将角色指定为编校选项。清单 5 给出了一个使用 redactDocumentForRole() 方法的示例。RESTRICTED 角色 (ID 1000) 是一个产品的示例角色。通常，您应该使用预定义的语义类别定义适合您的业务逻辑的角色。

				
int ROLE_RESTRICTED = 1000; // RESTRICTED role in the sample policy model
// redact a document
Document outDocument = client.redactDocumentForRole(redactionAttributes, document, 
ROLE_RESTRICTED);

将结果保存为文档

redactDocumentByRules() 方法和 redactDocumentForRole() 方法都返回一个 Document 类对象作为编校的结果。来自此对象的二进制数据和文档名称用于将文档保存到一个本地文件。

此场景最适合需要同步处理的客户端。在编校结束之前，编校服务器的连接会一直处于活动状态。这允许客户端跟踪进度和控制编校的执行。编校参数随各个文档一起传递。要实现更高的吞吐量，客户端可从多个线程提交编校请求。第二个场景适合在不应阻止客户端应用程序时对大量文档进行编校。

回页首

场景 2：在批处理存储库中编校文档

存储库是文件系统或 ECM 系统中某个指定的文件夹，包含子文件夹。它用于输入和输出文档，以及编校中使用的其他工件。有两种存储库类型：批处理和按需处理。第二个场景中使用批处理存储库。将编校服务器设置为监控批处理存储库的输入文件夹中传入的文档，当文档复制到输入文件夹时，服务器会自动使用提前为存储库定义的选项对文档进行编校，并将结果放在输出文件夹中。

在此场景中，自定义应用程序分解为两部分，如图 3 所示。第一部分（自定义应用程序 A）将文档发送到批处理存储库。服务器处理文档之后，第二部分（自定义应用程序 B）连接到服务器并下载编校的文档。

表 3 显示了 RedactionToolkitClient 类的存储库相关方法。此场景使用其中一些方法实现。

发送文档

自定义应用程序 A 连接服务器并加载目标文档。这些操作类似于场景 1 中的前两步。

addDocumentToRepository() 方法将一个文档放在指定存储库的输入文件夹中。清单 6 显示了一个使用 addDocumentToRepository() 方法的示例。“batch” 是在安装产品时创建的一个示例批处理存储库。

				
DocumentAttributes documentAttributes = new DocumentAttributes("sales_results.pdf", "", 
null);
Document document = new Document(inputDocBytes, documentAttributes, 
DOCUMENT_STATE.NOT_REDACTED);
client.addDocumentToRepository(document, "batch");

应用程序继续上传，直到所有文档都已发送到存储库。在上传完最后一个文档后，程序终止。

服务器监控输入文件夹并自动开始处理文档。这使得在处理期间必须维护服务器的连接。使用存储在存储库的编校服务器上的配置文件中定义的选项来处理文档。

下载文档并清理存储库

随后，自定义应用程序 B 连接编校服务器并检查存储库的输出文件夹。queryDocumentRepository() 方法获得指定的存储库中的文档的引用。清单 7 显示了一个使用 queryDocumentRepository() 方法的示例。

				
String repositoryFolderName = "batch";
DocumentReference[] docRefs = null;
...
docRefs = client.queryDocumentRepository(new DocumentRepositorySearchCriteria
(repositoryFolderName, DocumentRepositorySearchCriteria.SEARCH_WITHIN.REDACTED));

要找到已编校的文档，应该将 DocumentRepositorySearchCriteria.SEARCH_WITHIN.REDACTED 指定为要搜索的文档类型，这表示该文档是已编校过的文档，而不是原始文档。查询的结果在一个 DocumentReference 类数组中返回。引用用于指定存储库文件夹中要下载或删除的文档。getRepositoryDocument() 方法可以获取实际的文档数据，即 Document 类对象。甚至在下载数据后，原始数据仍然保留在存储库中。您可以调用 deleteRepositoryDocument() 方法来清理存储库。清单 8 显示了一个使用 getRepositoryDocument() 和 deleteRepositoryDocument() 方法的示例。

				
for (int i = 0; i < docRefs.length; i++) {
    Document doc = client.getRepositoryDocument(docRefs[i]);
    ...
    // save the binary data to a local file
    ...
    // delete the document to ensure next query doesn't return it
    client.deleteRepositoryDocument(docRefs[i]);
}

批处理存储库用于通过可配置数量的线程一次编校许多文档。可为每个存储库指定一组编校选项，例如输出格式、颜色模式、角色等。如果不同的文档有不同的编校选项，那么必须为每组选项准备一个批处理存储库。相反，在使用按需存储库时，您可以控制服务器编校存储库中的每个文档的方式。

回页首

场景 3：使用按需存储库编校文档

在第三个场景中，自定义应用程序分解为 3 部分。上传和下载部分几乎与第二个场景中相同，但会将文档上传到某个按需存储库中。与批处理存储库不同，按需存储库不会自动开始编校输入文档。因此，必须在服务器机器上运行一个新部件（自定义应用程序 C）来请求服务器处理文档，如图 4 所示。

自定义应用程序 A 将文档上传到按需存储库。这可以重复和根据需要完成。服务器机器上的自定义应用程序 C 定期运行，比如一天一次，或者在它通过检查存储库来查找文档时。

应用程序 C 在服务器机器上运行，但是，它仍然通过 SOAP 连接连接到服务器进程，因为它像在其他自定义应用程序中一样使用了 createRemoteClient()。对存储库输入文件夹中的文档的引用使用 queryDocumentRepository() 方法和 DocumentRepositorySearchCriteria.SEARCH_WITHIN.NOT_REDACTED 选项来实现。redactRepositoryDocumentByRules() 或 redactRepositoryDocumentForRole() 方法用于编校按需存储库文件夹中的文档。

应用程序可使用 RedactionAttributes 类和业务逻辑所需要的角色或规则为每个文档指定不同的选项。例如，可通过引用每个文档名称为每个文档指定不同的角色。

清单 9 显示了一个使用 redactRepositoryDocumentForRole() 的示例。在此代码中，文件名前缀为 “ClassA” 的文档使用 RESTRICED 角色进行编校，将 “Classified” 时间戳添加到页面中。

				
for (int i = 0; i < docRefs.length; i++) {
    // Set output format
    int role = 1001; //  GENERAL role in the sample policy model
    RedactionAttributes redactionAttributes = new RedactionAttributes("image/tiff"); // 
set output format to tiff image

    if(docRefs[i].getDocumentName().startsWith("ClassA")){
        //add stamp and use RESTRICTED role
        RedactionStamp stamp = new RedactionStamp(Boolean.TRUE, "Classified", 
RedactionStamp.StampPosition.UPPER_LEFT) ;
        redactionAttributes.addRedactionStamp(stamp);
        role = 1000; //  RESTRICTED role in the sample policy model
    }
    client.redactRepositoryDocumentForRole(redactionAttributes, docRefs[i], role);
}

可扩展此场景，根据需要将文档编校流程集成到文档工作流中。编校服务器可访问一个 ECM 系统，并使用它的数据存储作为存储库。因此，自定义应用程序可以使用所需的业务逻辑监控和处理 ECM 系统上的文档。

回页首

使用进程内客户端模式

对于现场编校服务，要避免继续运行编校服务器（进而保留资源）或减少进程间通信开销，可使用进程内客户端模式编校文档。此模式为客户端应用程序提供了对编校服务器生命周期的控制。该服务器与客户端一起初始化。这意味着，自定义应用程序和编校服务器在相同的 JVM 进程中运行，如图 5 中所示。

要在进程内客户端模式下使用编校客户端 API。可以使用 createInProcessClient() 方法创建一个 RedactionToolkitClient 类对象，而不使用 createRemoteClient() 方法。与远程客户端不同，进程内客户端不使用 SOAP 连接。它以一个 JVM 进程的形式启动编校服务器。获取对象后，您的程序可与在远程客户端模式下相同的方式使用它的方法。唯一的区别是，必须在程序结束时调用 cleanup() 方法来释放不需要的资源，然后再停止 JVM 进程。

我们修改了第一个场景中的程序来使用进程内客户端，替换 createRemoteClient() 方法并添加 cleanup() 方法。

清单 10 显示了一个使用进程内客户端的示例。

				
User user = new User("CustomApplication04", "userid", "password");
RedactionToolkitClient client = RedactionToolkitClient.createInProcessClient(user);
// redact the documents with the client object here
client.cleanup();

进程内客户端比远程客户端更加高效，因为它减少了进程间通信开销。但是，远程客户端在客户端与服务器进程之间具有更紧密的耦合。进程间客户端还有其他一些问题。

编校服务器组件

程序必须在拥有编校服务器组件的相同机器上运行，它必须在与服务器组件相同的 JVM 上运行 (<IBM_REDACTION_HOME>\ibm-java2-jre-60\jre\bin\java.exe)。

示例配置文件同时用于编校服务器和进程内客户端。但是，Web 服务（编校管理器和安全查看器）、SOAP 服务和批处理器不能在进程内客户端模式中使用。

与编校服务器共存

进程内客户端甚至可在编校服务器运行时使用，除非编校服务器连接到 ECM 服务器。当编校服务器连接到 ECM 服务器上的存储库（数据存储）时，它会锁定存储库。因此，如果进程内客户端启动，并且也尝试连接 ECM 服务器，将发生冲突。

类路径

表 4 中列出的所有 jar 文件都必须添加到类路径中。

此外，如果 Content Manager 8 对象存储用作存储库，类路径中也需要表 5 中的 jar 文件和目录，其中 <IBMCMROOT> 是 IBM DB2 Information Integrator for Content 的安装文件夹。如果 InfoSphere Guardium Data Redaction 打算连接 IBM Content Manager 8，此产品是唯一的前提条件。

Java 启动选项需求

自定义应用程序必须使用这些选项来运行。可能还必须使用它们来修改内存池大小。

-Xms256m -Xmx1536m -Djava.security.auth.login.config="%IBM_REDACTION_HOME%/server/conf/login.conf"

回页首

结束语

编校客户端 API 的基本用法已在 3 种典型编校场景和 2 种模式（远程客户端和进程内客户端）中介绍。在自定义应用程序中通过此 API 来使用 InfoSphere Guardium Data Redaction，系统中的文档工作流可得以改进，业务流程可更加高效。

回页首

致谢

作者感谢 InfoSphere Guardium Data Redaction 开发团队的 thank Joshua Fox 和 Michael Pelts 的细心评审和宝贵建议。

参考资料

学习

• 了解共享信息同时使用 使用 IBM Optim Data Redaction 在保护隐私的同时共享信息 保护隐私的更多信息。
  
  
• 在 developerWorks 中国网站 Information Management 专区 中获取必要的资源来提升您在各种 IBM Information Management 产品上的技能。
  
  
• 在 developerWorks 中国网站 Information Management 专区 了解 Information Management 的更多信息。查找技术文档、操作文章、培训、下载、产品信息等。
  
  
• 在 Twitter 上关注 developerWorks。
  
  
• 观看 developerWorks 演示中心，从面向初学者的产品安装和设置演示到面向有经验开发人员的高级功能。
  
  

获得产品和技术

• 使用 IBM 产品评估试用版软件 构建您的下一个开发项目，可直接从 developerWorks 下载获得或花几小时使用 IBM SOA 人员沙箱 了解如何有效实现面向服务架构。
  
  

讨论

• 查阅 developerWorks 博客 并加入 developerWorks 中文社区，developerWorks 社区是一个面向全球 IT 专业人员，可以提供博客、书签、wiki、群组、联系、共享和协作等社区功能的专业社交网络社区。
  
  

作者简介

为本文评分

评论

回页首

内容

• 简介
• 编校客户端 API
• 场景 1：本地文件系统编校
• 场景 2：在批处理存储库中编校文档
• 场景 3：使用按需存储库编校文档
• 使用进程内客户端模式
• 结束语
• 致谢
• 参考资料
• 作者简介
• 评论