Générateurs DTD et XSD

Toutes les API Sterling Selling and Fulfillment Foundation utilisent des codes XML d'entrée, de sortie et d'erreur standard. Ces codes XML se conforment à la définition de type de document (DTD) associée.

Prenons, par exemple, le code XML suivant :

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

La DTD correspondant à ce code XML est :

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

Pour créer de telles DTD pour des codes XML Sterling Selling and Fulfillment Foundation étendus, l'outil xsdGenerator.xml est fourni dans le répertoire REP_INSTALL/bin. Il convertit un fichier XML spécifiquement formaté en une DTD et en une définition de schéma XML (XSD). La commande pour l'exécution de l'outil est :

sci_ant.sh -f xsdGenerator.xml generate

Vous pouvez également transférer les propriétés suivantes en tant qu'arguments de ligne de commande :

xsdgen.use.targetnamespace
xsdgen.use.datatypeimport

Par exemple :

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

Le tableau suivant contient des informations relatives aux propriétés du générateur XSD :

Zones	Description
xsdgen.use.targetnamespace	Cette option est facultative. La valeur par défaut est Y. Si la valeur est Y, les fichiers XSD sont générés avec un espace de nom cible défini.
xsdgen.use.datatypeimport	Cette option est facultative. La valeur par défaut est Y. Si la valeur est Y, tous les fichiers XSD font référence à un fichier XSD commun unique contenant toutes les définitions de type de données commun. Si la valeur est N, chaque fichier XSD est créé avec une copie des définitions de base de données intégrée.

Les fichiers XML d'entrée doivent être placés dans le répertoire REP_INSTALL/xapidocs/extn/input. Les fichiers DTD et XSD résultants sont placés dans les répertoires REP_INSTALL/xapidocs/extn/output/dtd et REP_INSTALL/xapidocs/extn/output/xsd respectivement.

Remarque : Lorsque xsdgen.use.datatypeimport est défini à 'Y', le fichier datatypes.xsd mis à jour est généré dans le répertoire <REP_INSTALL>/xapidocs/extn/output/xsd sur la base du fichier datatypes.xml fusionné en incluant les extensions de type de données.

Dans l'exemple suivant, le code XML peut être placé dans le répertoire d'entrée et converti en une XSD et une DTD :

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

Le tableau ci-après contient les descriptions d'attributs spécifiques pour XML :

Zones	Description
yfc:QryTypeSupported	Cet attribut détermine si la fonctionnalité du type de requête est prise en charge pour les attributs de cet élément ou non. Si la valeur est Y, il prend effet pour tous les éléments.
yfc:ComplexQuerySupported	Cet attribut indique si un type de requête complexe est pris en charge ou non. Il ne peut être présent que dans l'élément racine.
yfc:XSDType	Nom du type à utiliser pour la définition de schéma de l'élément racine.
yfc:DTDOccurrence	Cet attribut peut contenir l'une des valeurs suivantes : REQUIRED - Cet élément doit être présent si l'élément parent est présent. ZeroOrOne - Cet élément est facultatif, mais ne peut apparaître qu'une seule fois. ZeroOrMany - Cet élément est facultatif, mais peut apparaître plusieurs fois. OneOrMany - Cet élément est obligatoire et peut apparaître plusieurs fois.
yfc:UseEntityOrdering	Cet attribut détermine si tous les enfants de premier niveau d'un élément sont classés dans l'ordre dans lequel ils se trouvent dans les codes XML de l'entité ou non. Cet attribut peut contenir l'une des valeurs suivantes : true - Tous les enfants de premier niveau d'un élément sont classés dans l'ordre dans lequel ils se trouvent dans les codes XML de l'entité. false - Les enfants de premier niveau d'un élément ne sont pas classés dans l'ordre dans lequel ils se trouvent dans les codes XML de l'entité.
xmlns	L'espace de nom à utiliser pour targetNameSpace dans la XSD de sortie. Cet attribut ne prend effet que s'il est présent dans l'élément principal.

Les attributs avec des valeurs REQUIRED sont générés comme les attributs obligatoires dans les DTD et XSD. Notez qu'un attribut obligatoire existant ne peut pas être marqué comme facultatif.

Les valeurs d'attribut peuvent également être spécifiées pour fournir des contraintes supplémentaires. Une liste d'options est séparée par une barre verticale (|). La valeur de l'attribut doit être l'une des options fournies. Ceci est uniquement pris en charge pour des types de données basés sur les chaînes. Les valeurs sont diminuées du caractère blanc si la valeur proprement dite contient entièrement des espaces, auquel cas l'option énumérée reste inchangée.

Par exemple, SomeAttr="A | B | C | |" se traduit par des options valides : "A", "B", "C" et "".

Remarque : Les DTD ne prennent pas en charge des valeurs énumérées ne contenant que des caractères blancs. En conséquence, des restrictions de ce type ne peuvent pas être représentées dans la DTD.

Les codes XML d'entrée et de sortie par défaut qui servent de base à l'écriture de codes XML personnalisés se trouvent dans le répertoire REP_INSTALL/xapidocs/xmlstruct/. Notez également que les données DTDOccurrence et REQUIRED fournies pour les tables standard sont induites à partir du fichier de base dans le répertoire xmlstruct et n'ont pas besoin d'être fournies. Si elles sont fournies, les informations existantes sont remplacées par les nouvelles informations présentes dans le code XML personnalisé. Tous les types de données et informations de relation nécessaires sont obtenues à partir des codes XML de l'entité.

Remarque : Ne placez pas vos codes XML personnalisés dans le répertoire xmlstruct.

En conséquence, lorsque l'outil exécute ces codes XML de base, les fichiers servent de valeur par défaut pour vous fichiers XML personnalisés, qui se contentent de ne contenir que les changements que vous avez effectués, par exemple sur les éléments étendus et les attributs. Ceci autorise de futures mises à niveau permettant de modifier en toute sécurité les fichiers XML dans le répertoire xmlstruct. La ré-exécution de l'outil de génération de XSD récupère automatiquement ces mises à jour.

Le fichier XML approprié du répertoire xmlstruct associé à votre code XML personnalisé est identifié par le nom du fichier. Votre code XML personnalisé peut débuter par un préfixe facultatif suivi d'un trait de soulignement et du nom du fichier de base. Par exemple, un fichier XML personnalisé nommé Custom_File_YFS_getOrderDetails_input.xml fait référence au fichier YFS_getOrderDetails_input.xml du répertoire xmlstruct.

Notez que la convention d'attribution de nom est facultative. Par exemple, vous pouvez également nommer votre code XML personnalisé sampleCustomApi.xml, sans qu'aucun fichier de base ne soit utilisé. Dans ce cas, l'outil donne en sortie un message informel indiquant qu'aucun code XML de base n'a été trouvé.

Remarque : Pour utiliser notre fichier XML de base pour une conversion, la convention d'attribution de nom de votre code XML personnalisé doit être suffixée de manière appropriée. Par exemple, Custom_File_YFS_getOrderDetails_input.xml doit utiliser le fichier de base intitulé YFS_getOrderDetails_input.xml.

La XSD générée indique l'espace de nom cible, comme illustré ci-dessous :

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

Cet espace de nom est extrait de l'attribut xmlns sur l'élément racine du code XML d'entrée et s'inscrit par défaut pour http://www.sterlingcommerce.com/documentation.

Les fichiers XSD et DTD contiennent des attributs de type de requête utilisés dans les API de liste si QryTypeSupported="Y" est défini dans l'élément racine du code XML d'entrée. De même, les types de requête complexe définis pour les API getItemList() et getOrganizationList() sont représentés dans les fichiers XSD et DTD si vous avez défini ComplexQuerySupported="Y".

Notez que dans les API les exceptions suivantes sont exposées dans les DTD, car ces contraintes ne peuvent pas être représentées dans une DTD pure, une XSD pure ou les deux :

Si un code XML contient plusieurs attributs Extn, la DTD générée seule (non la XSD générée) définit un élément Extn unique qui apparaît comme l'union de tous les éléments Extn possibles.
Attributs obligatoires selon conditions. Par exemple, vous devez indiquer un groupe d'attributs ou un autre groupe d'attributs, comme OrderHeaderKey ou EnterpriseCode/OrderNo.
Une condition obligatoire d'un noeud dépend d'une certaine valeur d'attribut. Par exemple, dans l'API createOrder() API, le noeud OrderLine est obligatoire si vous avez défini DraftOrderFlag="N".

Pour définir un type de données personnalisé pour un attribut dans la XSD générée, procédez comme suit :

Assurez-vous d'avoir étendu le fichier datatypes.xml et que le nouveau type de données personnalisé soit présent dans le répertoire INSTALL_DIR/xapidocs/api_javadocs/XSD/datatypes.xsd. Si le nouveau type de données n'est pas présent dans le fichier datatypes.xsd, exécutez la commande suivante pour régénérer le fichier datatypes.xsd basé sur les extensions datatypes.xml.
- Pour Windows - exécutez deployer.cmd -t xapideployer
- Pour Linux - exécutez ./deployer.sh -t xapideployer

Utilisez le type de données personnalisé, par exemple CustomDataType présent dans datatypes.xsd pour définir un attribut ; par exemple, CustomAttribute dans votre entrée XML présente dans le répertoire RÉP_INSTALL/xapidocs/extn/input.

Voici un exemple de fichier 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>

Exécutez l'outil xsdGenerator.xml pour générer la XSD pour l'exemple XML. La XSD générée contient l'attribut CustomAttribute personnalisé mappé vers le type de données personnalisé CustomDataType.