如何自动化 M2Doc 生成，包括设置？

Posted 2023-02-18

【中文标题】如何自动化 M2Doc 生成，包括设置？

【英文标题】：How to automate M2Doc generation including the settings?

【发布时间】：2021-10-23 18:13:22

【问题描述】：

我已应用 guidance on programmatic usage of M2Doc（也与 this help）通过 API 成功生成文档，该文档之前使用 M2Doc GUI 准备（配置 .docx 和 .genconf 文件）。它似乎也适用于已配置的 .docx，但没有 .genconf 文件。

现在我想更进一步，简化我们应用程序中的用户界面。用户应该附带一个 .docx，在其中包含 m:... 字段，特别是对于变量定义，然后在我们的 Eclipse 应用程序中，只需将模型元素分配给变量列表。最后按“生成”。其余的我想通过 M2Doc API 处理：

从 .docx 中获取变量列表 告诉 M2Doc 变量对象（以及它们的类型和其他所需信息，如果单独需要的话） 为 M2Doc 提供足够的信息来处理 Word 字段中的 projectmodel::PJDiagram.allInstances() 等 AQL 表达式

我试图为此分析 M2Doc 源代码，但有一些问题要实现目标：

解析/生成 API 不会在 .docx 或 .genconf 文件中创建任何配置信息，对吗？至少生成 .docx 配置信息的 API 是什么？ 源代码中提到“如果您使用的是一代”——这是什么意思？使用 .genconf 文件（这对于生成 API 来说似乎是可选的）？ 我可以从哪里获取 M2Doc 在 .docx 中找到的变量列表（在解析期间？），以便我可以将其呈现给用户进行对象（模型元素）分配？ 除了移交变量对象外，我是否必须告诉 M2Doc 变量的类型以及它们位于哪个资源文件中？我的猜测是否定的，因为使用没有存储任何 M2Doc 信息的空白 .docx 文件也适用于变量本身（不适用于使用其他类型或 .oclAsType() 类型转换的任何其他 AQL 表达式）。 如何向 M2Doc 提供上述 AQL 表达式的类型信息，我通常通过 nsURI 配置告诉它？我交出了我的应用程序的完整资源集，但这似乎还不够。

任何帮助将不胜感激！

到目前为止，为了让您对我的代码有个印象，请参见下文 - 请注意，它实际上是 javascript 而不是 Java，因为我们的应用程序具有内置的 JS-Java 接口。

//=================== PARSING OF THE DOCUMENT ==============================
var templateURIString = "file:///.../templateReqs.docx";
var templateURI = URI.createURI(templateURIString);

// canNOT be empty, as we get nullpointer exceptions otherwise
var options = "TemplateURI":templateURIString;

var exceptions = new java.util.ArrayList();

var resourceSetForModels = ...; //here our application's resource set for the whole model is used, instead of M2Doc "createResourceSetForModels" - works for the moment, but not sure if some services linking is not working

var queryEnvironment = m2doc.M2DocUtils.getQueryEnvironment(resourceSetForModels, templateURI, options);
        
var classProvider = m2doc.M2DocPlugin.getClassProvider();

// empty Monitor for the moment
var monitor = new BasicMonitor();

var template = m2doc.M2DocUtils.parse(resourceSetForModels.getURIConverter(), templateURI, queryEnvironment, classProvider, monitor);

// =================== GENERATION OF THE DOCUMENT ==============================

var outputURIString = "file:///.../templateReqs.autogenerated.docx";
var outputURI = URI.createURI(outputURIString);

variables["myVar1"] = ...; // assigment of objects...

m2doc.M2DocUtils.generate(template, queryEnvironment, variables, resourceSetForModels, outputURI, monitor);

谢谢！

【参考方案1】：

用于解析生成的 API 不会修改模板文件或 .genconf 文件。要修改模板的配置，您需要使用 TemplateCustomProperties 类。这将允许您注册您的元模型和服务类。然后使用此信息来配置 IQueryEnvironment，因此您可能还想直接在代码中配置 IQueryEnvironment。

此上下文中的生成指的是 .genconf 文件。注意 genconf 文件也是一个 EMF 模型，因此如果对您来说更容易，您也可以在内存中制作一个来启动您的生成。但是是的，.genconf 文件的使用是可选的，就像在您的代码示例中一样。

对于模板中的变量列表，您可以使用类 TemplateCustomProperties：

TemplateCustomProperties.getVariables() 将列出使用其类型声明的变量 TemplateCustomProperties.getMissingVariables() 列出模板中使用但未声明的变量

您还可以找到使用的元模型 (EPackage nsURI) 和导入的服务类的文件列表。

在生成时不需要变量的类型，只有在您想要验证模板时才需要。在生成时，您需要将映射从变量名称传递到其值，就像您在示例中所做的那样。变量的值可以是模型中的任何对象（一个 EObject）、一个字符串、一个整数……如果你想使用类似 oclIsKindOf(pkg::MyEClass) 的东西，你需要注册 pkg 的 nsURI先看下一点。

您提供的代码应该允许您使用类似 projectmodel::PJDiagram.allInstances() 的东西。此服务需要在 M2DocUtils.getQueryEnvironment() 中初始化的 ResourceSetRootEObjectProvider()。但是您需要在模板中声明元模型的 nsURI（请参阅 TemplateCustomProperties）。这将在 IQueryEnvironment 中注册它。您也可以使用 IQueryEnvironment.registerEPackage() 自行注册。

这应该可以帮助您找到 AQL 环境配置中缺少的部分。您的代码看起来不错，添加配置部分后应该可以工作。

【讨论】：

嗨@Yvan，感谢您的建议，现在只需使用 API 就可以很好地工作。我只是在纠结一点：如果 .docx 模板中没有它们，注册 nsURI 是行不通的。我尝试了以下方法： a) TemplateCustomProperties 似乎没有提供添加到其 nsURIs 属性的方法。 b) 直接在 queryEnvironment 注册 EPackages，就像在 configureQueryEnvironmentWithResult 中似乎不起作用：... ePackage=...getEPackage(nsURI); queryEnvironment.registerEPackage(ePackage); generateDocument(...,querEnvironment,...) 有什么建议吗？

顺便问一下，DocumentTemplateImpl有方法close()，但是接口DocumentTemplate是不是有原因不定义吗？会非常有用，因为现在我必须使用三个较低级别的 close() 方法（在 DocumentTemplateImpl 中调用）。

对于我的第一条评论：我终于意识到（花了一点时间......） parse 方法已经需要注册 nsURI。有了它就可以了！