DTD 和 XSD 生成器

每个 API 都使用标准输入，输出和错误 XML。这些 XML 符合相关的文档类型定义 (DTD)。

例如，考虑以下 XML：

<?xml version="1.0" encoding="UTF-8"> 
<Order EnterpriseCode="DEFAULT" OrderNo="S100" />

此 XML 的对应 DTD 为：

<!ELEMENT Order> 
<!ATTLIST Order OrderNo CDATA #IMPLIED> 
<!ATTLIST Order EnterpriseCode CDATA #REQUIRED>

要为扩展 XML 创建此类 DTD ，在 INSTALL_DIR/bin 目录中提供了名为 xsdGenerator.xml 的工具。此工具将特殊格式的 XML 文件转换为 DTD 和 XML 模式定义 (XSD)。用于运行该工具的命令为：

sci_ant.sh -f xsdGenerator.xml generate

您还可以将以下属性作为命令行参数传递：

xsdgen.use.targetnamespace
xsdgen.use.datatypeimport

例如

sci_ant.sh  -Dxsdgen.use.targetnamespace=N
-Dxsdgen.use.datatypeimport=N -f xsdGenerator.xml generate

下表包含有关 XSD 生成器属性的信息：

字段	描述
xsdgen.use.targetnamespace	可选。缺省值为 Y。如果设置为 Y ，那么将使用定义的目标名称空间生成 XSD 文件。
xsdgen.use.datatypeimport	可选。缺省值为 Y。如果设置为 Y ，那么所有 XSD 文件都将引用包含所有公共数据类型定义的单个公共 XSD 文件。如果设置为 N，那么创建的各个 XSD 文件中都会嵌入数据库定义的副本。

输入 XML 文件应放在 INSTALL_DIR/xapidocs/extn/input 目录中。生成的 DTD 和 XSD 文件分别放在 INSTALL_DIR/xapidocs/extn/output/dtd 和 INSTALL_DIR/xapidocs/extn/output/xsd 目录中。

注: When the xsdgen.use.datatypeimport is set to 'Y' it will generate the updated datatypes.xsd file in the <INSTALL_DIR>/xapidocs/extn/output/xsd directory based on the merged datatypes.xml including the data type extensions.

考虑以下可能放在输入目录中并转换为 XSD 和 DTD 的样本 XML：

<Item yfc:DTDOccurrence="REQUIRED" ItemKey="" ItemID="REQUIRED"
OrganizationCode="REQUIRED" UnitOfMeasure=""> 
   <PrimaryInformation Description="" ItemType="" /> 
   <AdditionalAttributeList> 
        <AdditionalAttribute Name="" Value=""/> 
    </AdditionalAttributeList> 
    <Extn ExtnAttr1="" ExtnRefId=""> 
       <CSTItemDataList yfc:DTDOccurrence="ZeroOrOne"> 
         <CSTItemData yfc:DTDOccurrence="ZeroOrMany" ItemDataKey="" 
Description=""> 
            <CSTItemExtraData yfc:DTDOccurrence="ZeroOrOne" CodeType="" 
DataType="" /> 
            <YFSCommonCode yfc:DTDOccurrence="REQUIRED" CodeName="" 
CodeType="" CodeValue="" />  
         </CSTItemData> 
       </CSTItemDataList> 
    </Extn> 
</Item>

下表包含 XML 的特殊属性的描述：

字段	描述
yfc:QryTypeSupported	此属性确定针对此元素中的属性是否支持查询类型功能。如果设置为 Y，那么它对于所有元素都有效。
yfc:ComplexQuerySupported	此属性指定是否支持复杂查询类型。此属性只能出现在根元素中。
yfc:XSDType	要用于根元素模式定义的类型的名称。
yfc:DTDOccurrence	此属性可以包含以下任何值： REQUIRED - 如果出现父元素，那么必须出现此元素。 ZeroOrOne - 此元素是可选的，但是只能出现一次。 ZeroOrMany - 此元素是可选的，但是可以出现多次。 OneOrMany - 此元素是必需的，但是可以出现多次。
yfc:UseEntityOrdering	此属性确定元素的所有第一级子代是否都按其在实体 XML 中的顺序进行排序。此属性可以包含以下任何值： true - 元素的所有第一级子代都按其在实体 XML 中的顺序进行排序。 false - 元素的第一级子代未按其在实体 XML 中的顺序进行排序。
xmlns	要用于输出 XSD 中的 targetNameSpace 的名称空间。此属性仅当出现在根元素中时才会生效。

值为 REQUIRED 的属性都作为 DTD 和 XSD 中的必需属性进行生成。但是，不能将现有必需属性标记为可选。

此外，还可指定属性值来提供其他约束。选项列表以竖线 (|) 分隔。属性的值必须是给定选项之一。这仅对基于字符串的数据类型受支持。如果值本身完全是空格，那么会除去值中的空格字符，在此情况下枚举选项保持不变。

例如，SomeAttr="A | B | C | |" 将生成以下有效选项：“A”、“B”、“C”、“ ”和“”。

注: DTD 不支持仅包含空格字符的枚举值。因此，在 DTD 中无法表示此类型的限制。

可以充当定制 XML 基础的缺省输入和输出 XML 位于 INSTALL_DIR/xapidocs/xmlstruct/ 目录中。另请注意，为标准表提供的 DTDOccurrence 和 REQUIRED 数据是从 xmlstruct 目录中的基本文件推断所得，因此不需要提供这些数据。如果提供了这些数据，那么会通过定制 XML 中出现的任何新信息来覆盖现有信息。任何必需数据类型和关系信息都获取自实体 XML。

注: 请勿将定制 XML 放在 xmlstruct 目录中。

因此，当运行该工具时，这些基本 XML 文件将充当定制 XML 文件的缺省内容，而定制 XML 文件只需包含您所作的更改，如扩展元素和属性。这允许在将来进行升级，以安全修改 xmlstruct 目录中的 XML 文件。重新运行 XSD 生成工具会自动选取这些更新。

xmlstruct 目录中与定制 XML 关联的相应 XML 文件通过文件名进行识别。定制 XML 可以用可选的前缀开头，后跟下划线和基本文件名。例如，名为 Custom_File_YFS_getOrderDetails_input.xml 的定制 XML 文件是指 xmlstruct 目录中的 YFS_getOrderDetails_input.xml 文件。

但是，命名约定是可选的。例如，您还可以将定制 XML 命名为 sampleCustomApi.xml，但是不使用任何基本文件。在此情况下，该工具会输出参考消息来指示找不到任何基本 XML。

注: 如果要使用基本 XML 文件进行转换，那么定制 XML 的命名约定必须以适当的后缀作为后缀。例如，Custom_File_YFS_getOrderDetails_input.xml 会使用名为 YFS_getOrderDetails_input.xml 的基本文件。

生成的 XSD 按如下所示指定目标名称空间：

<xsd:schema attributeFormDefault="unqualified" 
elementFormDefault="qualified"
targetNamespace="http://www.sterlingcommerce.com/documentation" 
xmlns:xsd=http://www.w3.org/2001/XMLSchema
xmlns:yfc="http://www.sterlingcommerce.com/documentation">

此名称空间根据输入 XML 的根元素上的 xmlns 属性来选取，并且缺省为 http://www.sterlingcommerce.com/documentation。

当在输入 XML 的根元素中设置了 QryTypeSupported="Y" 时，XSD 和 DTD 文件包含列出 API 中使用的查询类型属性。同样，当设置了 ComplexQuerySupported="Y" 时，在 XSD 和 DTD 文件中会表示针对 getItemList() 和 getOrganizationList() API 定义的复杂查询类型。

但是在 API 中，由于在纯 DTD 和/或 XSD 中无法表示这些约束，因此 DTD 中禁止以下异常：

如果 XML 包含多个 Extn 属性，那么生成的仅 DTD（而不是生成的 XSD）会定义单个 Extn 元素，该元素显示为所有可能的 Extn 元素的并集。
条件必需属性。例如，您需要指定一个属性组或另一个属性组，如 OrderHeaderKey 或 EnterpriseCode/OrderNo。
节点的强制条件取决于某个属性值。例如在 createOrder() API 中，如果 DraftOrderFlag="N"，那么 OrderLine 节点是必需的。

要为已生成的 XSD 中的属性定义定制数据类型，请执行以下步骤：

确保已扩展 datatypes.xml 文件，且新的定制数据类型存在于 INSTALL_DIR/xapidocs/api_javadocs/XSD/datatypes.xsd 目录中。如果新的数据类型不存在于 datatypes.xsd 中，请运行以下命令以根据 datatypes.xml 扩展重新生成 datatypes.xsd。
- 对于 Windows - 运行 deployer.cmd -t xapideployer
- 对于 Linux - 运行 ./deployer.sh -t xapideployer

使用定制数据类型 (例如， datatypes.xsd 中存在的 CustomDataType ) 来定义属性，例如， INSTALL_DIR/xapidocs/extn/input 目录中存在的输入 XML 中的 CustomAttribute 。

以下是样本 XML 文件。

<Item yfc:DTDOccurrence="REQUIRED" ItemKey="" ItemID="REQUIRED"
OrganizationCode="REQUIRED" UnitOfMeasure="">
   <PrimaryInformation Description="" ItemType="" CustomAttribute="">
     <yfc:doc>
       <Attributes>
         <Attribute DataType="CustomDataType" Name="CustomAttribute"/>
       </Attributes>
     </yfc:doc>
   <PrimaryInformation/>
</Item>

运行 xsdGenerator.xml 工具来为样本 XML 生成 XSD。生成的 XSD 包含已映射到 CustomDataType 定制数据类型的定制 CustomAttribute 属性。