DTD- und XSD-Generator

Jede Anwendungs-API verwendet Standard-XMLs für Eingabe, Ausgabe und Fehler. Diese XML-Dateien entsprechen der zugehörigen Dokumenttypdefinition (Document Type Definition, DTD).

Betrachten Sie z. B. die folgende XML-Datei:

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

Die entsprechende DTD für diese XML-Datei sieht wie folgt aus:

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

Um solche DTDs für die erweiterte XML zu erstellen, wird ein Tool namens xsdGenerator.xml im Verzeichnis <runtime_sandbox>/bin bereitgestellt. Dieses Tool konvertiert eine speziell formatierte XML-Datei in eine DTD und XSD (XML-Schemadefinition). Der Befehl zum Ausführen des Tools lautet wie folgt:

Bevor Sie den folgenden Befehl ausführen, stellen Sie sicher, dass Sie API-Dokumente generieren. Weitere Informationen finden Sie unter "Generierung und Zugriff auf Javadoc ".

sci_ant.sh -f xsdGenerator.xml generate

Sie können auch die folgenden Eigenschaften als Befehlszeilenargumente übergeben:

xsdgen.use.targetnamespace
xsdgen.use.datatypeimport

Beispiel:

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

In der folgenden Tabelle sind Informationen zu den Eigenschaften des XSD-Generators enthalten:

Felder	Beschreibung
xsdgen.use.targetnamespace	Optional: Der Standardwert ist "J". Bei Angabe von Y werden die XSD-Dateien mit einem definierten Zielnamensbereich generiert.
xsdgen.use.datatypeimport	Optional: Der Standardwert ist "J". Bei Angabe von Y verweisen alle XSD-Dateien auf eine einzelne allgemeine XSD-Datei, die alle allgemeinen Datentypdefinitionen enthält. Wenn für diesen Wert "N" festgelegt ist, wird jede XSD-Datei mit einer Kopie der Datenbankdefinitionen erstellt, die darin eingebettet sind.

Navigieren Sie zum Verzeichnis <runtime_sandbox>/xapidocs/extn/ und erstellen Sie einen Ordner input. Legen Sie dann die XML-Dateien in das erstellte input -Verzeichnis. Die resultierenden DTD- und XSD-Dateien werden in den Verzeichnissen <runtime_sandbox>/xapidocs/extn/output/dtd bzw. <runtime_sandbox>/xapidocs/extn/output/xsd abgelegt.

Hinweis: Wenn xsdgen.use.datatypeimport auf 'Y' gesetzt ist, wird die aktualisierte Datei datatypes.xsd im Verzeichnis <runtime_sandbox>/xapidocs/extn/output/xsd basierend auf dem zusammengeführten datatypes.xml einschließlich der Datentyperweiterungen generiert.

Betrachten Sie die folgende XML-Beispieldatei, die im Eingabeverzeichnis angeordnet und dann in eine XSD und DTD konvertiert werden kann:

<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>

Die folgende Tabelle enthält Beschreibungen von speziellen Attributen für XML-Dateien:

Felder	Beschreibung
yfc:QryTypeSupported	Mit diesem Attribut wird bestimmt, ob die Abfragetypfunktionalität für die Attribute in diesem Element unterstützt wird. Wenn der Wert "Y" festgelegt ist, wirkt sich dies auf alle Elemente aus.
yfc:ComplexQuerySupported	Mit diesem Attribut wird angegeben, ob ein komplexer Abfragetyp unterstützt wird. Dieses Attribut kann nur im Stammelement vorhanden sein.
yfc:XSDType	Der Name des Typs, der für die Schemadefinition des Stammelements verwendet wird.
yfc:DTDOccurrence	Dieses Attribut kann einen der folgenden Werte enthalten: REQUIRED – Dieses Element muss vorhanden sein, wenn das übergeordnete Element vorhanden ist. ZeroOrOne – Dieses Element ist optional, tritt aber möglicherweise nur einmal auf. ZeroOrMany – Dieses Element ist optional, tritt aber möglicherweise mehrmals auf. OneOrMany – Dieses Element ist erforderlich und tritt möglicherweise mehrmals auf.
yfc:UseEntityOrdering	Mit diesem Attribut wird bestimmt, ob alle untergeordneten Elemente der ersten Ebene eines Elements in der Reihenfolge angeordnet werden, in der sie in den XML-Dateien der Entitäten vorliegen. Dieses Attribut kann einen der folgenden Werte enthalten: True – Alle untergeordneten Elemente der ersten Ebene eines Elements werden in der Reihenfolge angeordnet, in der sie in den XML-Dateien der Entitäten vorliegen. False – Die untergeordneten Elemente der ersten Ebene eines Elements werden nicht in der Reihenfolge angeordnet, in der sie in den XML-Dateien der Entitäten vorliegen.
xmlns	Der Namespace, der für "targetNameSpace" in der Ausgabe-XSD verwendet wird. Dieses Attribut wird nur wirksam, wenn es im Stammelement vorhanden ist.

Die Attribute mit den Werten REQUIRED werden in der DTD und XSD als erforderliche Attribute generiert. Ein vorhandenes erforderliches Attribut kann jedoch nicht als "Optional" markiert werden.

Die Attributwerte können auch angegeben werden, um zusätzliche Bedingungen bereitzustellen. Eine Liste mit Optionen wird durch einen vertikalen Strich (|) getrennt. Der Wert des Attributs muss eine der angegebenen Optionen sein. Dies wird nur für Datentypen unterstützt, die auf den Zeichenfolgen basieren. Die Leerzeichen werden von den Werten abgeschnitten, wenn die Werte selbst vollständig aus Leerschritten bestehen. In diesem Fall bleibt die Aufzählungsoption unverändert.

Beispielsweise führt SomeAttr="A | B | C | |" zu den gültigen Optionen "A", "B", "C", " " und "".

Hinweis: Die DTDs unterstützen keine Aufzählungswerte, die nur Leerzeichen enthalten. Daher können Einschränkungen dieses Typs in der DTD nicht dargestellt werden.

Die Standard-Eingabe-und Ausgabe-XMLs, die als Basis für Ihre angepasste XML dienen können, befinden sich im Verzeichnis <runtime_sandbox>/xapidocs/xmlstruct/ . Beachten Sie außerdem, dass die Daten für "DTDOccurrence" und "REQUIRED", die für die Standardtabellen bereitgestellt werden, aus der Basisdatei im Verzeichnis xmlstruct abgeleitet werden und daher nicht bereitgestellt werden müssen. Wenn die Informationen bereits vorhanden sind, werden sie durch die neuen Informationen überschrieben, die in den kundenspezifischen XML-Datei enthalten sind. Alle erforderlichen Informationen zum Datentyp und zur Beziehung werden aus den XML-Dateien der Entität abgerufen.

Hinweis: Stellen Sie Ihre angepassten XMLs nicht in das Verzeichnis xmlstruct.

Wenn das Tool ausgeführt wird, dienen diese XML-Basisdateien daher als Standard für Ihre kundenspezifischen XML-Dateien, die nur die Änderungen enthalten müssen, die von Ihnen vorgenommen wurden, z. B. die erweiterten Elemente und Attribute. Auf diese Weise können die XML-Dateien im Verzeichnis xmlstruct bei zukünftigen Aktualisierungen problemlos geändert werden. Bei der erneuten Ausführung des XSD-Generierungstools werden diese Aktualisierungen automatisch übernommen.

Die entsprechende XML-Datei, die Ihrer kundenspezifischen XML-Datei zugeordnet ist, wird über den Dateinamen ermittelt. Ihre kundenspezifische XML-Datei kann z. B. mit einem optionalen Präfix beginnen, gefolgt von einem Unterstrich und dem Basisdateinamen. Eine kundenspezifische XML-Datei namens kundenspezifische_datei_YFS_getOrderDetails_input.xml verweist z. B. auf die Datei YFS_getOrderDetails_input.xml im Ordner xmlstruct.

Die Namenskonvention ist jedoch optional. Sie können Ihre kundenspezifische XML-Datei auch beispiel_kundenspezifische_api.xml nennen, wobei aber keine Basisdatei verwendet wird. In diesem Fall wird vom Tool eine Informationsnachricht ausgegeben, um anzuzeigen, dass keine XML-Basisdatei gefunden wurde.

Hinweis: Wenn die XML-Basisdatei für die Konvertierung verwendet werden soll, muss die Namenskonvention Ihrer angepassten XML mit einem entsprechenden Suffix versehen werden. Die Datei kundenspezifische_datei_YFS_getOrderDetails_input.xml würde z. B. die Basisdatei YFS_getOrderDetails_input.xml verwenden.

Die generierte XSD gibt den Zielnamespace wie folgt an:

<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">

Dieser Namespace wird vom Attribut "xmlns" für das Stammelement der Eingabe-XML-Datei übernommen und er erhält standardmäßig den Wert http://www.sterlingcommerce.com/documentation.

Die XSD- und DTD-Dateien enthalten die Abfragetypattribute, die in Listen-APIs verwendet werden, wenn QryTypeSupported="Y" im Stammelement der Eingabe-XML-Datei festgelegt ist. Gleichermaßen werden die komplexen Abfragetypen, die für die APIs "getItemList()" und "getOrganizationList()" definiert wurden, in den XSD- und DTD-Dateien dargestellt, wenn ComplexQuerySupported="Y" festgelegt ist.

In APIs sind jedoch die folgenden Ausnahmebedingungen in den DTDs dargestellt, da diese Einschränkungen in einer reinen DTD, XSD bzw. in beiden Dateien nicht dargestellt werden können:

Wenn eine XML-Datei mehrere "Extn"-Attribute enthält, definiert die generierte reine DTD-Datei (ohne generierte XSD) ein einzelnes "Extn"-Element, das als Kombination aller möglichen "Extn"-Elemente angezeigt wird.
Bedingt erforderliche Attribute. Angenommen, Sie müssen eine Gruppe von Attributen oder eine andere Gruppe von Attributen wie "OrderHeaderKey" oder "EnterpriseCode/OrderNo" angeben.
Die obligatorische Bedingung eines Knotens hängt von einem Attributwert ab. In der API "createOrder()" ist z. B. der Knoten "OrderLine" erforderlich, wenn folgende Option angegeben ist: DraftOrderFlag="N".

Gehen Sie wie folgt vor, um einen angepassten Datentyp für ein Attribut im generierten XSD zu definieren:

Stellen Sie sicher, dass Sie die Datei datatypes.xml erweitert haben und der neue angepasste Datentyp im Verzeichnis <runtime_sandbox>/xapidocs/api_javadocs/XSD/datatypes.xsdvorhanden ist. Wenn der neue Datentyp in datatypes.xsd nicht vorhanden ist, führen Sie den folgenden Befehl aus, um datatypes.xsd auf Basis der erweiterten Datei datatypes.xml neu zu generieren.
- Windows - deployer.cmd -t xapideployer
- Linux - ./deployer.sh -t xapideployer

Verwenden Sie den benutzerdefinierten Datentyp, z. B. CustomDataType in datatypes.xsd , um ein Attribut zu definieren, z. B. CustomAttribute in Ihrer Eingabe-XML, die sich im Verzeichnis <runtime_sandbox>/xapidocs/extn/input befindet.

Die nachfolgende Datei ist eine beispielhafte XML-Datei.

<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>

Führen Sie das Tool xsdGenerator.xml aus, um XSD für die Beispiel-XML zu generieren. Die generierte XSD enthält das angepasste Attribut CustomAttribute, das dem angepassten Datentyp CustomDataType zugeordnet ist.