本文展示了如何使用IBM®Rational®Publishing Engine通过基于图表的报告方法通过IBM®Rational®Software Architect Design Manager生成设计文档。

在本系列的第3部分中讨论了基于模型的报告（请参见侧栏“ 基于模型的报告 ”）。 在基于图表的报告中 ，报告本身并非源自完整的模型。 而是从提取图开始，然后检索关于图上元素的信息，而与声明这些元素的位置无关，也就是说，无论它们与图在同一模型中还是在其他模型中。 图1显示了一个基于图表的报告示例：

图1.基于图的报告

基于图的报告或基于模型的报告

当您使用基于图的报告样式来为企业体系结构框架（例如，开放集团体系结构框架（TOGAF）或北约体系结构框架（NAF））生成报告时，它很方便，因为这些框架都是面向视图的。 例如，要遵守NAF，您必须创建包含应用程序不同视图的报告，可以使用UML图定义该报告。 与传统的基于模型的报告方法相比，这种基于图的报告样式提供了更大的灵活性：实际上，基于图的模型的内部结构在最终报告中（不一定）不明显，而在最终报告中则完全可见。基于模型的方法。

因此，与基于模型的报告相比，对基于图的报告的模型指导的要求不那么严格，但这并不意味着可以（或应该）忽略模型指导。 当您在团队中工作时，它们对于生成高质量模型仍然至关重要。 例如，您仍然应该具有定义图和UML元素的命名规则，或者定义UML元素文档中使用的字体大小和样式等等的规则，以便可以生成看起来很熟练的报告。

案例研究

基于图的报告会带来其他挑战和技术。 在大型模型的背景下，要求报告提取一个图表是不切实际的。 因此，基于图表的报告需要一种方法，该方法可以使用参数以灵活的方式控制报告，以便可以将文档分为数量有限的子文档，这些子文档最终可以收集（使用Microsoft Word master和附属文档的概念，例如）。

在本文的其余部分中，我将使用具有以下报告要求的实际案例介绍基于图的报告的解决方案：

• 特定子文档的报告生成可以从模型中的任何程序包（或模型本身）开始。
• 通过使用参数，可以定义是应提取包中的所有图还是仅提取具有特定名称的图。
• 应该可以在任何子包的图表上递归报告特定的递归深度。
• 报告应该能够或多或少地显示元素信息（取决于用户配置）。
• 应该有可能限制根据其类型显示信息的UML元素。
• 最顶层软件包的初始部分编号必须灵活—它可以是一章，一个子部分，一个子子部分，等等。

为了使基于图的报告能够满足这些需求，您必须在相应的模板中定义参数，在定义Rational Publishing Engine文档规范时可以配置这些参数。

整体设计

如果将解决方案分为两个级别，而不是定义一个大型的复杂模板来完成所有工作，则满足这些要求可能会更简单：

• 主模板 （也称为搜寻器 ），该主模板遍历模型，处理包和图并控制报表的结构。 由爬虫决定哪些信息进入报告以及从何处进入。
• UML类型特定的片段 ，在外部被引用，并呈现报告中涉及的UML元素类型的详细信息。 每个相关的UML类型将至少有一个UML代码段进行报告。

图2显示了总体设计。 该方法广泛使用参数来控制在报表中生成的内容。 为了使这种方法起作用，您必须能够将参数从搜寻器传递到代码片段—例如，要呈现的UML元素的URL。

图2.解决方案的设计

您可以定义各种搜寻器，每种搜寻器从模型中提取信息的方式都不同。 但是，不同的搜寻器可能共享相同的摘要集。 代码段中的更改会立即传播到使用该代码段的所有爬网程序，这将使该方法更加灵活，并且更容易适应需求的更改。

生成的结果是Microsoft Word文档。 然后可以使用Word master和附属文档的概念将来自不同世代的Word文档合并为一个更大的文档。 这样，您还可以将Rational Publishing Engine生成的输出与手写信息（如标题页，变更说明，目录，简介，结论等）组合在一起。

文档规范的参数化

基于图表的报告的文档规范通常可以采用图3所示的形式。请注意，数据源的范围仅限于UML模型。

图3.文档规范

为了使基于图表的报告正常工作，必须提供可唯一标识报告范围内顶级程序包的参数。 这种标识是通过变量PackageName和PackageId完成的，变量PackageName表示顶级软件包的简单名称，而PackageId则是唯一的软件包ID，因为可以在Rational Design Manager中找到它。 例如，如果包名称在模型中不是唯一的，则可以使用PackageId 。 变量DiagramName可用于将范围缩小到包中的特定图。

RecursionLevel定义从顶层包开始的递归深度。 它的默认值为0，表示不进行递归。 变量SectionLevel以整数形式定义顶级包（H1，H2，H3等）的节样式。 变量UMLTypes定义了元素的类型，应使用逗号或分号分隔的列表来提取信息。 它的默认值为“全部”，这意味着将为在图上找到的所有对象提取信息。 最后，如果仅应呈现名称， 构造型和描述（“ false”），或者应报告更多信息（例如类操作，属性等），则变量RenderElementDetails控制图中的UML元素。 ，也是如此（“ true”）。

图元素

基于图的报告的一项关键要求是，报告必须提取有关报告范围内图上元素的信息。 从技术上讲，这可以归结为遍历图上找到的所有对象引用。 此过程的关键模板片段如图4所示：

图4.提取图元素

对于找到的每个图（顶部容器，查询$ 37 ），模板将打印图名称，描述和图像，后跟一个图标题。 图的Rational Design Manager模式提供了一个名为references / Object的查询（底部容器，查询$ 40 ），以提取图上引用的对象。 该查询检索所有对象引用，例如在图上找到的对象的URL。

对于一个用例图，提取有关该图上用例和参与者的信息是有意义的，而例如关联可能不那么相关。 因此，通过条件检查来补充该迭代，该条件检查当前对象引用的具体类型是否在外部变量UMLTypes中列出的UML类型集合中 。 如果UMLTypes已设置为All，则条件也为true。 检索对象引用之后，您可以检索详细信息，这取决于当前元素的类型。

搜寻器和摘要

Rational Design Manager中基于图的报告的局限性在于，在图上找到的有关对象引用的信息仅限于URL和对象的具体类型。 基于模型的报告提供了更多信息，例如，基本信息，例如名称，描述和应用的构造型，足以呈现有关元素的概述信息。

对于基于图表的报告，必须使用逐个元素的动态数据源连接来检索此信息。 根据UML对象的具体类型，必须使用不同类型的数据源和查询。 因此，您可能想尝试一种方法，该方法定义搜寻器从外部引用的特定于UML类型的代码段，并呈现报告中涉及的UML元素类型的详细信息。 图5以绿色显示了外部引用的模板。 这些基本上是它们自身的模板。 使用此方法的优点是，对模板的更改在所有引用的爬网程序中都是立即可见的，这使得维护更加容易，并且可以更灵活地适应更改的需求。

图5.用于UML元素类型的分派器

图5还显示了主模板的中心部分。 该模板研究UML元素的具体类型，并将控件分派给模板片段，该片段负责生成元素类型的文档。 对象的URL最初分配给内部变量_ElementURL ，而对象的具体类分配给变量_Element_Type 。 变量_Element_Type （而不是直接查询）定义了条件，该条件控制使用哪个代码段生成有关对象的信息。 下一节将演示如何为UML类生成文档。

课程摘要

负责定义UML类文档的代码段从使用模式DM类的动态数据源连接开始（请参见图6）。 在运行时，这导致向Design Manager REST服务的请求以获取该类的详细信息。 变量_ElementURL的值用于定义数据源的URI属性。

图6. UML类的代码片段

接下来是查询$ 2 ，该查询遍历返回的所有类（仅一个类）。 类的名称和应用的构造型应用程序的列表（查询$ 14 ）在同一段落中呈现，然后在下一个段落中显示Description（查询$ 41 ）。 仅当RenderElementDetails设置为true时，才呈现类的详细信息（例如属性和操作）。 此变量的值从主模板传递到代码片段，并由用户在文档规范中设置（请参见图3）。

参数传递

参数传递涉及一些关键技术。 在代码段中 ，变量_ElementURL保留了关系图上引用对象的URL，在代码段中也将其声明为外部变量，在搜寻器中也将其声明为内部变量。 因此，启用了从主模板到代码段的参数传递，并且变量的值可以在代码段中用于配置动态数据源DM Class 。 但是，该变量对于最终用户在文档规范中不可见。

传递给代码段的其他变量是RenderElementDetails，UMLTypes和_DataSource 。 _DataSource定义了片段数据源连接用来定义诸如用户凭据（用户名，密码）之类的参数的继承数据源的名称。 动态数据源的配置如下：将URI属性设置为值表达式_ElementURL ，并将继承的数据源属性设置为_DataSource 。

注意
Rational Publishing Engine 1.2.0.1需要一种变通方法，以使搜寻器和代码片段之间的参数传递正常工作。 您可以在单独的模板中维护参数，然后将此模板导入代码段和搜寻器以使两个模板都知道变量。 然后将代码段导入到搜寻器中，在导入向导中选择“动态引用”作为导入类型，并使用“导入模板向导”中的命令来映射代码段中的变量以重复使用模板变量，如图7所示。现在，搜寻器和摘要中的内容已绑定在一起。

图7.参数传递

分层

Rational Software Architect支持分层。 您可以将图表上的元素分为可见或隐藏的类别或图层 。 这样，您可以很好地控制应在特定图中显示什么样的对象详细信息（例如类）。 例如，一个班级可能会提供与不同领域或主题相关的操作。 通过使用图层，您可以创建故意隐藏特定主题的图表。

当然，报告应限于仅渲染图中的可见元素。 图8显示了实现此目的的解决方案：

图8.分层

内部变量_DiagramVisibleRefs用于保存可见层中所有元素的URL。 定义条件只考虑那些可以在_DiagramVisibleRefs中找到其URL的对象，而不是在图表上打印所有对象引用（查询$ 67 ）（请参阅过滤分层对象的条件）。

但是，这样做需要一些技术。 _DiagramVisibleRefs初始化为@ 。 接下来是查询$ 74 ，该查询遍历图中的所有层并使用过滤器提取可见层。 查询$ 75遍历所有视图 ，然后查询$ 76遍历视图的所有元素 。 然后，变量_DiagramVisibleRefs分配如下：

_DiagramVisibleRefs  = _DiagramVisibleRefs + resourceID + "@";

的条件被用于测试，如果图中的元件的RESOURCEID可以在可变_DiagramVisibleRefs找到。 只有这样，才会调用UML元素的相应代码段以呈现该元素的信息。 请注意，除了使用字符串数组之外，还可以将动态数组（映射）与简单的查找功能结合使用来确定元素是否可见。

当元素不在图层上时

该解决方案具有一个副作用：它仅针对可见层中的元素呈现信息。 但是，图中的元素可能根本不在某个层上，因此当前模板会忽略它们。

您可以通过采用模型准则来更改此规则，即分层图上的所有元素都必须是层的一部分。 另外，您可以创建模板的变体，以检查隐藏元素而不是可见元素-例如，它遍历所有隐藏层并收集这些对象引用的资源ID。 然后应相应地更改图8中所示的条件，以便仅在未在变量中找到资源ID的情况下才呈现元素。 最后，将变量的名称更改为_DiagramHiddenRefs以使模板更具可读性是有意义的 。

但是，此小示例演示了生成高度精通的报告的一个基本方面：（遵循）模型准则和运作良好的报告模板。 没有前者，就无法实现后者。

履带式变体

您可以针对不同的报告需求开发专用的搜寻器，例如，一个实现基于图的报告范式，另一个实现传统的基于模型的范式。 为基于图的范例实现的搜寻器之所以被定义为扎根于UML模型，是出于以下原因：您可以为一个模型和同一模型定义大量文档规范，而无需进行额外的工作。 为此，请使用“数据源配置向导”为模型URL定义初始文档规范，并设置一些参数，例如“程序包名称”（以及可能的“程序包ID”）。 然后，可以从此初始文档规范中复制所有其他文档规范，而您要做的就是更改程序包名称和程序包ID（可能还有其他一些参数）。

开发专用履带的缺点

这种方法的一个缺点是，它需要大量使用内部参数来查找模型中的顶级程序包，计算程序包何时处于报告范围内以及计算当前节的样式。 图9显示了确定一个包是否属于报告范围（在指定的顶级包内部或外部）以及该包的节标题对应的样式是什么的计算表达式：

图9.计算节样式

Rational Publishing Engine 1.2.1具有大大改进的“数据源配置向导”，它使配置数据源更加容易。 如果您一次设置默认项目和工作区，则可以使用向导从那里导航到报告范围内的ULM模型。

从模型上下文开始的报告的另一种替代方法是直接报告程序包，并使用向导直接选择顶级程序包。 该方法具有两个优点。 首先，搜寻器模板中的逻辑要简单得多（不需要图9中的大多数计算）。 其次，模板速度更快，因为加载（大型）模型需要检索的信息较少，并且遍历模型以查找顶级包不需要花费任何执行时间。

部署方式

与基于模型的报告相比，基于图的报告更可能导致更大的文档规范集，因为每一代的范围通常较小（只是模型的一个子集，而不是整个模型）。 因此，开发生成所有文档规范构成报告的命令脚本很方便。 图10显示了如何执行此操作：

图10.批处理执行

或者，您可以使用多个模板引用来定义文档规范，然后以不同方式配置每个模板引用。

在Rational Publishing Engine的当前实现中，由于打开和检查代码片段与搜寻器的一致性需要时间，因此生成模板会带来一定的运行时开销。 在将模板发送到生产环境之前，请先将代码段实际导入到相应的搜寻器中，然后使用此模板的变体生成报告（但保留原始模板以供将来进行修订和修改）。

评估利弊

基于图的方法起源于模型中的一组图，然后报告在图中找到的UML对象引用，该方法在Enterprise Architecture Frameworks的上下文中生成报告，这要求为某个产品生成特定的视图。域。 基于图的方法的优点包括可以灵活选择和选择要在报表中呈现的内容。

但是您为此付出了代价-至少在当前的实施中。 由于图上的对象引用具有有限的可用属性（URL和具体类型），因此，您对图上的元素进行排序时具有开箱即用的功能（例如，按名称）。 可以完成排序，但是需要Javascript来查找和缓存模型元素信息，然后再对其进行排序和呈现。

另外，与基于模型的报告相比，基于图的报告具有运行时开销，因为仅对象引用可用。 基于模型的报告还直接提供名称，描述，构造型等，而无需通过调用REST服务来检索元素的详细信息。 最后，在合并的文档中可能会出现冗余：如果在文档的10个图表中引用了某个元素，则除非进行特定（可能很复杂）的操作，否则可能会报告10次。 其中可能包括保留已记录元素的地图，并在已打印元素的情况下结合使用书签和超链接。

结论

传统上，Rational Publishing Engine的用户使用基于模型的报告方法，其中报告从模型中的某些顶级包开始，然后递归遍历这些包并呈现图和包元素。 例如，在早期报告解决方案（例如IBM®Rational®SoDA）中，也已采用此方法为IBM®Rational®Unified Process和V-Model提供模板。 但是，基于图的方法提供了更大的灵活性。

传统的基于模型的报告和基于图表的报告范例都可以用于生成合并的文档。 您只需要从一开始就仔细考虑，这将是给定报告任务的最佳选择。 即文档的给定部分。 实际上，您都可以使用这两者来生成报告-例如，用于生成体系结构视图的基于图的爬网程序，以及用于生成数据模型词典的更传统的基于模型的爬网程序。

致谢

我要感谢Kevin Cornel在过去的几年中为Design Manager Reporting提供了宝贵的提示和技巧，并感谢我允许我介绍分层报告的技术。

翻译自: https://www.ibm.com/developerworks/rational/library/rational-publishing-engine-generate-compliance-documents-4/index.html