创建一个 NIEM IEPD,第 4 部分: 组装 IEPD

设计美国政府部门之间的 XML 信息交换

在本系列的前三篇文章中,学习了建模一个 NIEM 交换,以及定义实现该模型的子集和扩展架构。现在来完成最后一步,将交换的架构、文档以及所有其他工件组装到一个完整的遵循 NIEM 的 IEPD 中。本文也会介绍验证和发布 IEPD 的过程。

Priscilla Walmsley, 常务董事, Datypic

Priscilla Walmsley 的照片Priscilla Walmsley 是 Datypic 公司的常务董事和高级顾问。她擅长 XML 技术、架构和实现。最近,她一直忙于通过 Trusted Federal Systems 公司和美国司法部一起开发 LEXS —— 一个基于 NIEM 的 IEPD 框架。她是 Definitive XML Schema(Prentice Hall,2001)和 XQuery(O'Reilly Media,2007)的作者,还是 Web Service Contract Design and Versioning for SOA(Prentice Hall,2008)的合著者。



2010 年 6 月 21 日

信息交换包文档(Information Exchange Package Documentation,IEPD) 是一个由描述国家信息交换模型(National Information Exchange Model,NIEM)交换的文档组成的文档集合。它一般包括架构、样例、各种文档和呈现指令。也包括几个 NIEM 特定的工件(比如元数据文档和编录文件),它们是遵循 NIEM 的交换中所必需的。

在本系列中,我讲述了一个简单的例子,即 Theft Report IEPD(参见 参考资料 中到前三篇文章的链接)。既然 UML 模型、组件映射表(Component Mapping Table,CMT)和架构都完成了,那么完成 IEPD 就只剩下很少的几步了:

常用缩写词

  • CMT:组件映射模板
  • HTML:超文本标记语言
  • IEPD:信息交换包文档
  • NIEM:国家信息交换模型
  • UML:统一建模语言
  • XHTML:可扩展超文本标记语言
  • XML:可扩展标记语言
  • XSLT:可扩展样式表转换
  1. 创建更多文档相关的工件,以进一步解释交换。具体来说,我需要添加:
    • 主文档。用于概要描述交换
    • 一个样例文档。用于展示实际的消息结构和测试架构
    • 呈现指示。用于提供样例文档的人类可读的视图
  2. 以遵循 NIEM 的方式组装 IEPD,这涉及到使用 NIEM "Work with IEPDs" 工具来上载工件和生成附加的文档文件。
  3. 使用 NIEM Conformance Validation Tool 验证 IEPD 的完整性和 NIEM 遵从性。
  4. 发布 IEPD,以便它可被其他用户发现。

IEPD 文档

要遵循 NIEM,IEPD 必须至少包含某种形式的主文档和一个变更日志,后者描述自最近版本以来发生的变更。可以在 IEPD 中包含任意文档(通常伴随着一个软件应用程序),要么包含在主文档中,要么作为单独的文件,比如:

  • UML 模型(顺序图、用例、类图)
  • 一个 CMT
  • 业务规则(即对没有表示在架构或模型中的数据的约束)
  • 需求定义
  • 测试和/或遵从性声明
  • 谅解备忘录和保证函

我到目前为止为 Theft Report IEPD 开发的文档工件是一个 UML 模型和一个 CMT。我需要添加主文档,以简单描述交换的目的和结构。我还要添加一个变更日志,它实际上是空的,因为这是交换的第一个版本。参见 下载 中一个完整的 IEPD,它包含这些文档。


创建样例文档

样例 XML 文档是 IEPD 的重要部分。仅仅根据架构,难以对 XML 文档形成概念,尤其是在谈论错综复杂的一组相关架构文档时。使用样例就能清楚地看出任何给定文档类型中哪个元素是根元素,并为每个元素提供典型数据的例子。

为交换架构中每个不同的根元素至少包含一个样例。如果将一种文档类型用于多种目的,那么应该为每种目的提供一个样例。为了测试架构和任何被编写来处理文档的软件,有必要创建一个包含每种可能元素的样例。对于复杂的交换,创建一个 典型 样例也是很有用的,其中包含任何给定文档可能包含的内容。

很多 XML 编辑器会为您生成样例文档,但是这些文档一般包含的是无意义的数据,不具有正确相关的 ID 和关联中使用的 IDREF 值。您应该编辑任何生成的样例,让它们更为典型且富有含义。由于各种处理程序处理架构位置提示的方式各不相同,所以我也建议您用多个处理程序验证样例。

对于 Theft Report IEPD,我只具有一个可能的根元素(tr:TheftReport)。清单 1 展示了我创建的一个完整样例的开始部分。它至少具有交换中允许的一种元素类型,并具有数据的代表值。

清单 1. 一个样例文档的开始部分
<?xml-stylesheet type="text/xsl" href="theftreport.xsl" ?>
<tr:TheftReport xmlns:tr="http://datypic.com/theftreport/exchange/1.0"
 xmlns:nc="http://niem.gov/niem/niem-core/2.0"
 xmlns:trext="http://datypic.com/theftreport/extension/1.0"
 xmlns:j="http://niem.gov/niem/domains/jxdm/4.1"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:s="http://niem.gov/niem/structures/2.0"
 xsi:schemaLocation="http://datypic.com/theftreport/exchange/1.0
                     ../schema/exchange/1.0/theftreport-exchange.xsd">
    <tr:TheftReportDate>2006-05-05</tr:TheftReportDate>
    <trext:Theft s:id="T1">
        <nc:ActivityDate>
            <nc:DateTime>2006-05-04T08:15:00</nc:DateTime>
        </nc:ActivityDate>
    </trext:Theft>
    <trext:Theft s:id="T2">
        <nc:ActivityDate>
            <nc:DateTime>2006-05-04T09:14:00</nc:DateTime>
        </nc:ActivityDate>
    </trext:Theft>
        <nc:ActivityConveyanceAssociation>
            <nc:ActivityReference s:ref="T1"/>
            <nc:ConveyanceReference s:ref="V1"/>
        </nc:ActivityConveyanceAssociation>
        <nc:ActivityConveyanceAssociation>
            <nc:ActivityReference s:ref="T2"/>
            <nc:ConveyanceReference s:ref="B1"/>
        </nc:ActivityConveyanceAssociation>
        <trext:Vehicle s:id="V1">
            <nc:ItemDescriptionText>2001 Subaru Outback</nc:ItemDescriptionText>
            <nc:ItemSerialIdentification>
                 <nc:IdentificationID>123455234234</nc:IdentificationID>
            </nc:ItemSerialIdentification>
            <nc:VehicleColorPrimaryCode>SIL</nc:VehicleColorPrimaryCode>
            <nc:ConveyanceRegistrationPlateIdentification>
                 <nc:IdentificationID>BGE112</nc:IdentificationID>
            </nc:ConveyanceRegistrationPlateIdentification>
            <trext:VehicleTaxClassCode>4</trext:VehicleTaxClassCode>
        </trext:Vehicle>
    ...

创建呈现指令

呈现指令是另一个有用的工具,用于帮助 IEPD 的用户和实现者掌握交换的情况。查看复杂的 XML 文档并理解其内容是很困难的 — 尤其是在典型的 NIEM 文档中,这样的文档具有大量结构元素和连接文档不同部分的关联。有些用户关注结构的复杂性和元素的名称,更甚于关注实际内容。

如果您编写呈现指令来将 XML 数据转换成人类可读的 HTML,那么可以减轻该问题。关联的对象可以被重新连结并一起显示在页面上,无关的结构可以被忽略,隐含的代码清单值可以被转换成可读的等价物。

XML 文档的呈现通常是利用 XSLT 电子表格做到的。对于简单的 HTML 呈现,我一般推荐采用 XSLT version 1.0,因为该版本在主要浏览器中都受到支持。在样例所在的同一目录中提供一个 XSLT 电子表格,可以让用户双击样例(或者在 XML 编辑器中打开)并看到所呈现的 HTML 版本。清单 1 第一行中的处理指令(以 <?xml-stylesheet 开始)指出使用哪个 XSLT 电子表格。

对于 Theft Report IEPD,我创建了一个相当简单的 XSLT 1.0 电子表格(包含在 下载 部分的 IEPD 中),它以用户友好的方式显示 Theft Report,如 图 1 所示。XSLT 连结每起盗窃事件及其关联的位置、车型、失主和证人,以符合逻辑地显示数据。(查看 图 1 的文本版本。)

图 1. 呈现的样例
呈现的样例报告的屏幕截图

组装 IEPD

NIEM 提供一个 “Work with IEPDs” 工具,用于聚集 IEPD 工件和组装完整的包(参见 参考资料 中的链接)。尽管可以手工组装 IEPD,但是使用工具通常更为容易,因为工具会自动生成 NIEM 遵从性所必需的两个 NIEM 特定的工件:元数据文档和编录文件,后者充当内容表格。并且产生的 IEPD 具有更加一致的文件结构。

要使用该工具,单击页面左边菜单中的 Create/Upload IEPD。这样会带您进入 图 2 所示的页面。

图 2. Create/upload an IEPD 页面
Work with IEPDs 工具中 Create/upload an IEPD 页面的屏幕截图

单击 Begin 之后,会询问您是否具有想要上载的现有 IEPD 压缩文件。如果已经具有一组压缩的 IEPD 工件,就可以单击 Yes 并上载该压缩文件。为 Theft Report 例子使用该工具时,我是单击 No 以单独上载每个文件。

单击 No,工具将显示 图 3 所示页面。该页面允许您指定根目录名称。对于 Theft Report,我选择 TheftReport 作为根目录。还是在该页面上,要向 IEPD 添加单个工件,可单击 Add Artifact 链接。

图 3. Upload Artifacts 页面
Work with IEPDs 工具中 Upload Artifacts 页面的屏幕截图

使用该页面添加扩展和交换架构、wantlist、子集、样例文档、呈现指令、CMT、UML 模型、变更日志及主文档。注意,应该将子集架构压缩到一个文件中;当工具重新生成 IEPD 时,它将被解压。

对于添加的每个工件,您应该选择一种类型。这样做是很重要的,因为它影响着生成编录文件的方式和用于组件的默认目录。您也可以在该页面选择一个目录路径。为了一致性,请对每个工件单击 use recommended path,工具将会填充路径。我对推荐的路径所做的惟一更改是,为交换和扩展架构包含了一个 1.0 子目录,因为我想要目录结构与名称空间名称形成镜像。我还为每个工件添加了一个描述。图 4 显示了结果。(查看 图 4 的文本版本。)

图 4. 添加的工件
Edit Artifacts 页面上添加的工件的屏幕截图,包含工件列表

在添加工件时,单击 Next 进入 图 5 所示的 Enter Metadata 页面。在该页面上,提供关于 IEPD 的元数据,比如名称、描述、版本、组织和联系点。工具使用该信息来生成一个叫做 metadata.xml 的 XML 文档,该文档与 IEPD 包含在一起。

图 5. Enter Metadata 页面
Work with IEPDs 工具中 Enter Metadata 页面的屏幕截图

关于该页面,稍微有点混淆的地方是,NIEM 遵从性所必需的字段并没有全都标记有黄色星号。稍后验证 IEPD 时,如果缺少任何必需的元数据,您会收到通知。一般来说,最好把相关的内容都填好。填写完元数据之后,单击 Next 进入 图 6 所示的摘要页面。

图 6. IEPD 摘要页面
Work with IEPDs 工具中 IEPD Details 摘要页面的屏幕截图

从该页面,可以单击 Validate IEPD 以确定您的 IEPD 是否包含所有必需的元数据。通过验证之后,单击 Upload IEPD 以将该 IEPD 保存在您的概要文件中,以便稍后您可以在 My IEPDs 下检索它。注意,上载 IEPD 并不自动使得它对网站的其他用户可见。

最后,要实际生成 IEPD,可从 IEPD Successfully Uploaded 页面单击 Download。通过从工具页面左边的菜单中单击 My IEPDs,可以在任何时候下载、修改或删除您的任何 IEPD。

来看一下生成的 IEPD,可以看到您上载的所有工件的副本,还有两个生成的文件。清单 2 中的 metadata.xml 文档为关于交换的信息提供一个标准化的 cross-IEPD 格式。

清单 2. 元数据文档
<?xml version="1.0" encoding="UTF-8"?>
<Metadata>
    <URI>http://www.datypic.com/theftreport</URI>
    <Name>Theft Report</Name>
    <Summary>Exchange to report thefts of motor vehicles and bicycles in the state
                on a daily basis</Summary>
    <Description>Contains information about a theft of a motor vehicle or bicycle,
                including the theft date, location, description and identifiers of
                the stolen property, and victim and witness information.</Description>
    <Version>1.0</Version>
    <URL>http://www.datypic.com/theftreport</URL>
    <CreationDate>03/01/2010</CreationDate>
    <LastRevisionDate>03/01/2010</LastRevisionDate>
    <NextRevisionDate>06/01/2010</NextRevisionDate>
    <NIEMVersion>2.0</NIEMVersion>
    <Security>Public</Security>
    <Maturity>2</Maturity>
    <Status>Final</Status>
    <Schedule/>
    <Lineage/>
    <Relationships/>
    <Keywords/>
    <Domain>Justice, </Domain>
    <ExchangePartners/>
    <Process/>
    <TriggeringEvent/>
    <Conditions/>
    <Endorsements/>
    <Sponsors>Datypic</Sponsors>
    <Purpose>Report thefts of motor vehicles and bicycles to interested parties</Purpose>
    <MessageExchangePatterns>publish/subscribe</MessageExchangePatterns>
    <CommunicationsEnvironment/>
    <ExchangePartnerCategories>Law Enforcement, DMV,
                                  Department of Revenue</ExchangePartnerCategories>
    <AuthoritativeSource>
        <Category>none</Category>
        <Organization>
            <Name>Datypic</Name>
            <Address1/>
            <Address2/>
            <City/>
            <State/>
            <Zip/>
            <Country/>
            <URL>http://www.datypic.com</URL>
        </Organization>
        <PointOfContact>
            <Name>Priscilla Walmsley</Name>
            <Address1/>
            <Address2/>
            <City/>
            <State/>
            <Zip/>
            <Country/>
            <Phone>231-555-1212</Phone>
            <Fax/>
            <Email>pwalmsley@datypic.com</Email>
        </PointOfContact>
    </AuthoritativeSource>
</Metadata>

catalog.html 文件是一个 XHTML 文档,充当 IEPD 中工件的内容表格。它以其人类可读的呈现形式显示在 图 7 中。由于有嵌入在 XHTML 中的 rddl:purpose,编录文件也是机器可读的。(查看 图 7 的文本版本。)

图 7. 呈现的 IEPD 编录文件
呈现的 IEPD 编录文件的屏幕截图

验证 IEPD

一旦创建了一个 IEPD,就可以使用 NIEM Conformance Validation Tool(参见 参考资料 中的链接)来测试它的遵从性。该过程确保 IEPD 中有了所有必需的工件。它也针对一些在 NIEM Naming and Design Rules (NDR) 文档中为遵循 NIEM 的架构定义的规则,而测试架构。

从 Conformance Validation Tool 主页面,单击 Begin 进入 图 8 所示的页面。它提示您上载一个文件,该文件将作为一个压缩文件,成为整个的 IEPD。工具使用编录文件来确定所有工件的位置和类型。在单击完要求您验证工件目的的页面之后,该页面出现一个叫做 My Validations 的新部分,其中显示您的 IEPD 的遵从性报告。

图 8. Conformance Validation 工具
Work with IEPDs 工具中 Conformance Validation 工具的屏幕截图

图 9 显示了遵从性报告的摘要页面,该报告采用 Microsoft® Office Excel® 格式。它具有几个工作表:

  • Summary图 9 中的基本统计信息。
  • NDR - All Rules 提供 NDR 中所有规则的列表,以及对于那些可被自动检查的规则,IEPD 中的架构是否检查通过。对于每个不能被自动检查的规则,一个下拉列表允许您指出您已经手动检查它。
  • NDR - Schemas 是所有架构文档的摘要,以及它们是不是遵循 NIEM。
  • NDR - Rules Auto Failed 是 NDR 规则违反的每个实例的列表。
  • IEPD - Metadata 是所有元数据字段的列表,如果它们是必需的,但是却没有,则显示为错误。
  • IEPD - Catalog 是所有工件类型的列表,如果它们是必需的,但是却没有,则显示为错误。

(查看 图 9 的文本版本。)

图 9. Conformance 报告摘要
Conformance 报告摘要的屏幕截图

可从 下载 小节得到 Theft Report IEPD 的遵从性报告的完整副本。


将 IEPD 提交到公共仓库

IEPD 是准备进行共享的。尽管 NIEM 通过提供公共定义和技术而有助于互操作,但是两个使用不同 NIEM 子集的 IEPD 的 XML 文档是不可互换的。因此,IEPD 的重用对于获得互操作性是至关重要的。

为了让其他人使用使用您的 IEPD,您的 IEPD 必须公共可用,以便被其他人发现。两个主要的 Web 站点提供现有 IEPD 的目录,而且将 IEPD 提交到这些站点很容易。

首先,您可以在 NIEM Web 站点本身列出您的 IEPD,使之在 Work with IEPDs 工具的 Search 功能下可用。要在 Work with IEPDs 工具中做到这一点,请打开 IEPD 摘要页面。单击右上角的 Edit 链接,然后单击 Edit Visibility/Sharing 以打开 图 10 中的 Edit Artifact Visibility 页面。

图 10. Edit IEPD Visibility
Work with IEPDs 工具中 Edit IEPD Visibility 页面的屏幕截图

从该页面,选择 Shared 让 IEPD 变得可见。即使 IEPD 本身是可见的,您也可以隐藏单个工件(通过取消选择它们旁边的复选框)。这允许用户看到 IEPD,即使单个工件被隐藏。完成后单击 Update Visibility

第二个可以提交 IEPD 的地方是 Office of Justice Programs (OJP) IEPD Clearinghouse。为此,访问 clearinghouse Web 站点(参见 参考资料 中的链接),并单击 Submit IEPD Information 以得到一个窗体,在该窗体上可以上载 IEPD。


LEXS:另一种创建整个 IEPD 的方法

既然理解了开发 NIEM IEPD 的过程,再来考虑一下这是否是您应该执行的任务。本系列 第 1 部分 建议您,在从新创建自己的 IEPD 之前,考虑重用现有的 IEPD。这不仅可以改善与其他应用程序的互操作性,并且省时省力。

但是,有时难以找到满足您的所有需求的 IEPD。在这样的情况下,一个很好的解决方案是 Logical Entity Exchange Specification (LEXS)。LEXS 是一个 NIEM IEPD 框架,它通过将文档分成一个摘要(digest)和一个结构化有效载荷(structured payload),平衡了互操作性和灵活性这两个对立的目标。摘要中包含最常用的 NIEM 组件,有固定的结构,可跨所有基于 LEXS 的 IEPD 进行互操作。结构化有效载荷允许单个基于 LEXS 的 IEPD 扩展和定制 LEXS 库模型。LEXS 也为处理消息交换、搜索、订阅、附加和呈现提供解决方案。参见 参考资料 中到 LEXS Web 站点的链接。


结束语

本系列描述创建 NIEM IEPD 的过程,本文是本系列的最后一篇文章。在这个系列中,您看到了如何建模一个交换、为模型创建一个适当的 NIEM 子集,以及编写自己的 NIEM 扩展。本文描述了最后一步:将架构、文档和其他工件组装成 IEPD。遵循这些针对遵从 NIEM 的交换的指导方针,将有助于您利用 NIEM 的承诺,即促进公共和私有组织之间的信息共享。


下载

描述名字大小
完整的 IEPDniem4iepd.zip157KB
IEPD 顺应性报告niem4confreport.zip26KB

参考资料

学习

  • 创建一个 NIEM IEPD,第 1 部分:建模您的 NIEM 交换(Priscilla Walmsley,developerWorks,2010 年 1 月):在这个 4 篇文章的系列中,使用 National Information Exchange Model (NIEM) 建立一个 “从开始到结束” 解决方案。NIEM 是一个由美国政府资助的项目,旨在促进公共领域和私有领域组织之间的信息共享。
  • 创建一个 NIEM IEPD,第 2 部分:映射和 NIEM 子集(Priscilla Walmsley,developerWorks,2010 年 2 月):在这个四部分系列文章的第 2 部分中,完成下一步 — 将模型映射到 NIEM,以决定交换可以重用 NIEM 的哪些部分。还学习创建 NIEM 模型的子集,以包含在 IEPD 中。
  • 创建一个 NIEM IEPD,第 3 部分:扩展 NIEM(Priscilla Walmsley,developerWorks,2010 年 3 月):在第 3 部分中,探究您在创建扩展和交换架构以定义自己定制的类型和属性时,对于不直接映射到 NIEM 的模型部分该怎么办。
  • NIEM:参考 NIEM Web 站点,了解关于 NIEM 目的和方法的其他信息。
  • IEPD Requirements:得到所有控制 IEPDs 遵循 NIEM 的规则。
  • Office of Justice Programs IEPD Clearinghouse:将 IEPD 提交到 clearinghouse。
  • LEXS:更多地了解使用 LEXS 作为创建自己的 IEPD 的另一种方式。
  • NIEM Practical Implementer's Course:参加这个在线免费课程,获取关于 NIEM IEPD 组装的更多详细指南。
  • My developerWorks:个性化您的 developerWorks 体验。
  • IBM XML 认证:了解如何才能成为一名 IBM 认证的 XML 和相关技术的开发人员。
  • XML 技术库:访问 developerWorks XML 专区,获得广泛的技术文章和技巧、教程、标准和 IBM 红皮书。
  • developerWorks 技术活动网络广播:随时关注技术的最新进展。
  • developerWorks 播客:收听面向软件开发人员的有趣访谈和讨论。

获得产品和技术

讨论

条评论

developerWorks: 登录

标有星(*)号的字段是必填字段。


需要一个 IBM ID?
忘记 IBM ID?


忘记密码?
更改您的密码

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件

 


在您首次登录 developerWorks 时,会为您创建一份个人概要。您的个人概要中的信息(您的姓名、国家/地区,以及公司名称)是公开显示的,而且会随着您发布的任何内容一起显示,除非您选择隐藏您的公司名称。您可以随时更新您的 IBM 帐户。

所有提交的信息确保安全。

选择您的昵称



当您初次登录到 developerWorks 时,将会为您创建一份概要信息,您需要指定一个昵称。您的昵称将和您在 developerWorks 发布的内容显示在一起。

昵称长度在 3 至 31 个字符之间。 您的昵称在 developerWorks 社区中必须是唯一的,并且出于隐私保护的原因,不能是您的电子邮件地址。

标有星(*)号的字段是必填字段。

(昵称长度在 3 至 31 个字符之间)

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件.

 


所有提交的信息确保安全。


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=10
Zone=XML
ArticleID=497172
ArticleTitle=创建一个 NIEM IEPD,第 4 部分: 组装 IEPD
publish-date=06212010